appstore-ppp-pricing-agent-skill: Instructions file for Claude Code

CLAUDE.md — Project Context for AI Agents

What This Project Does

CLI tool that automates regional pricing for App Store in-app purchases and subscriptions. Distributed on PyPI as appstore-ppp-prices; the module is appstore_ppp_prices and it installs two equivalent commands, appstore-ppp-prices and the shorter ppp-pricing. Calculates optimal prices for 175+ countries based on GDP per capita and optionally uses GPT to adjust coefficients per app type.

Tech Stack

• Python 3.10+
• httpx — HTTP client for App Store Connect API
• PyJWT — JWT token generation for API auth
• openai — GPT integration for pricing analysis
• python-dotenv — .env config loading

Architecture

appstore_ppp_prices/          — the installable package (importable as appstore_ppp_prices)
  cli.py          — Entry point, argument parsing, orchestration
  appstore.py     — App Store Connect API client (JWT auth, products, prices)
  pipeline.py     — Core workflow: find product → AI analysis → calculate → resolve → apply
  pricing.py      — Pure pricing logic: coefficients × US price → target prices
  countries.py    — Country data loader from CSV (GDP, categories, coefficients)
  ai_analyzer.py  — Prompt template, response parsing, caching, cache clearing
  llm.py          — OpenAI-compatible chat-completions client: retries, timeouts, provider override
  display.py      — Terminal output formatting, dry-run tables
  paths.py        — Config and cache directory resolution
  countries.csv   — 175+ countries with GDP per capita and default coefficients (shipped as package data)

.env              — Secrets (not committed)
.env.example      — Template for .env

Never anchor runtime paths to Path(__file__).parent.parent — in an installed wheel that resolves to site-packages, not the repository. Data files go through importlib.resources; writable state goes through paths.py.

Key Patterns

• Business logic is pure: pricing.py has no I/O, no side effects
• API client is stateful: AppStoreConnectClient manages JWT token lifecycle with thread-safe locking
• Context manager: AppStoreConnectClient supports with client: pattern
• Concurrent API calls: ThreadPoolExecutor for price-point batches and subscription price setting. Territory price grids are batched 8 territories per request (the endpoint serves 8000 rows a page), so 175 territories cost ~22 calls, not 175
• No vendor SDK: the LLM call is a plain httpx POST in llm.py, so any OpenAI-compatible endpoint works (OpenRouter, Groq, Ollama, vLLM) and nothing in the dependency tree needs compiling. Retries live there — 429/5xx/timeouts, three attempts, 1s then 2s backoff; 4xx fails immediately
• AI caching: Results cached in ~/.cache/ppp-pricing/ ($XDG_CACHE_HOME honoured) by SHA-256 hash of app name; --clear-cache removes all cached results
• Config discovery: --config → $PPP_PRICING_CONFIG → nearest ancestor of cwd holding a .env → ~/.config/ppp-pricing/. The first two are authoritative: a wrong explicit path fails loudly instead of silently falling back. load_dotenv is only ever called with an explicit path — never with None, which would make python-dotenv search upwards and override the chosen directory
• IAP vs Subscription: Different API endpoints and flows — IAPs use single atomic request, subscriptions need per-territory POST + pending price cleanup