solvapay-python 0.6.0__tar.gz → 0.7.1__tar.gz

solvapay_python-0.7.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.7.1 — 2026-05-17
+
+Payments-grade hardening: structured errors, idempotency keys, py.typed, structured logging.
+
+### Added
+- **Structured error hierarchy** (`exceptions.py`): `APIError` base with `status_code`, `request_id`, `error_code`, `error_message`. Subclasses: `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RateLimitError` (429, adds `.retry_after`), `InvalidRequestError` (4xx), `APIServerError` (5xx), `APIConnectionError`, `APITimeoutError`. `SolvaPayAPIError` aliased to `APIError` for back-compat.
+- **Idempotency keys** on all mutating ops: `create_checkout_session`, `ensure_customer`, `track_usage`, `cancel_purchase`, `reactivate_purchase`, `create_product`, `clone_product`, `create_plan` all accept `idempotency_key: str | None = None`. Header casing: `Idempotency-Key` (matches TS SDK).
+- **`solvapay.idempotency.from_payload(*parts)`** — SHA256 of stable-serialized payload parts → 32-hex-char deterministic key.
+- **PEP 561 `py.typed` marker** — downstream mypy users no longer see `Any` on `solvapay.*` imports.
+- **Structured logging** at `solvapay.http` logger: INFO on success (method, path, status, request_id, duration_ms), WARNING on 4xx/5xx (adds body_excerpt ≤200 chars). Never calls `logging.basicConfig`. Optional `logger=` injection on `SolvaPay`/`AsyncSolvaPay` constructors for `loguru`/`structlog`.
+- **Secret redaction**: `Authorization` header never appears in logs. Verified by `tests/test_redaction.py`.
+- **pyproject classifiers**: `Development Status :: 4 - Beta`, `Framework :: AsyncIO`, `Topic :: Office/Business :: Financial`, `Typing :: Typed`.
+
+### Internal
+- User-Agent bumped to `solvapay-python/0.7.1`
+- 142 tests (up from 125), `mypy --strict` clean, `ruff` clean
+
+## 0.7.0 — 2026-05-17
+
+Real-API alignment after testing against the SolvaPay sandbox revealed wire-format mismatches.
+
+### Fixed
+- **`Customer.customer_ref`** now accepts `reference` (real API) in addition to `customerRef` via `validation_alias=AliasChoices(...)`.
+- **`ensure_customer()`** reads `reference` from API response; falls back to `customerRef`. Raises if neither present.
+- **`BalanceResponse`** rewritten: `credits`, `display_currency`, `credits_per_minor_unit`, `display_exchange_rate`; `balance` and `currency` kept as computed properties.
+
+### Added
+- **`paywall_state.gate()`** — one-call enrichment helper (limits + checkout URL + plan via `get_customer`).
+- **`paywall.require` / `require_async`**: auto-mints checkout URL when `LimitResponse.checkout_url is None`.
+- **`examples/marketplace/`** — Streamlit demo with 4 paywalled AI agents (Google Gemini) against real SolvaPay sandbox.
+
+### Internal
+- User-Agent `solvapay-python/0.7.0`. 125 tests (up from 121). `mypy --strict` clean.
+
+## 0.6.0
+- Admin endpoints (products, plans, merchant config). GitHub Actions trusted-publish to PyPI.
+
+## 0.5.0
+- `paywall_state` classifier (ACTIVATION_REQUIRED / TOPUP_REQUIRED / UPGRADE_REQUIRED). LangChain `monetize_tool`.
+
+## 0.4.0
+- Full async client. 5 lifecycle operations. 13 typed webhook event classes.
+
+## 0.3.0
+- FastMCP example: AI agent with two paywalled tools.
+
+## 0.2.0
+- `@paywall.require` decorator. FastAPI webhook router.
+
+## 0.1.0
+- Sync client, HMAC-SHA256 webhook verification, Pydantic v2 models, CI on 3 Python versions.

{solvapay_python-0.6.0 → solvapay_python-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.6.0
+Version: 0.7.1
 Summary: Community Python SDK for SolvaPay (agent-native payment rails)
 Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
 Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
@@ -9,14 +9,17 @@ Author: Dhruv Sanan
 License: MIT
 License-File: LICENSE
 Keywords: agents,fintech,mcp,payments,solvapay
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.5
@@ -28,20 +31,26 @@ Description-Content-Type: text/markdown
 
 # solvapay-python
 
+[![PyPI](https://img.shields.io/pypi/v/solvapay-python)](https://pypi.org/project/solvapay-python/)
+
 Community Python SDK for [SolvaPay](https://solvapay.com) — payment rails for the agentic economy.
 
-> **Status:** v0.5, community-maintained. Pending official adoption.
+> **Status:** v0.6, community-maintained. Available on PyPI. Pending official adoption.
 > Mirrors the most-used surface of [@solvapay/core](https://github.com/solvapay/solvapay-sdk).
 
 Python is the dominant language for agent frameworks (LangChain, FastMCP, CrewAI, AutoGen). SolvaPay's official SDK is TypeScript-only. This SDK brings first-class Python support so agent developers can gate tools behind paywalls without switching ecosystems.
 
-> 🎬 **New in v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
+> **New in v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
+> **v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
 > **v0.4:** Async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events.
 
 ## Install
 
 ```bash
-pip install git+https://github.com/dhruv-sanan/solvapay-python
+pip install solvapay-python
+# with optional extras:
+pip install solvapay-python[langchain]
+pip install solvapay-python[fastapi]
 ```
 
 ## Quickstart
@@ -251,6 +260,7 @@ async def handle_webhook(request: Request) -> dict:
 - v0.3 — FastMCP paywall demo (`examples/fastmcp-paywall/`) ✅
 - v0.4 — async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events ✅
 - v0.5 — paywall state classifier, LangChain `monetize_tool` decorator ✅
+- v0.6 — admin endpoints (products, plans, merchant, platform config), PyPI publish ✅
 
 ## Contributing
 

{solvapay_python-0.6.0 → solvapay_python-0.7.1}/README.md

@@ -1,19 +1,25 @@
 # solvapay-python
 
+[![PyPI](https://img.shields.io/pypi/v/solvapay-python)](https://pypi.org/project/solvapay-python/)
+
 Community Python SDK for [SolvaPay](https://solvapay.com) — payment rails for the agentic economy.
 
-> **Status:** v0.5, community-maintained. Pending official adoption.
+> **Status:** v0.6, community-maintained. Available on PyPI. Pending official adoption.
 > Mirrors the most-used surface of [@solvapay/core](https://github.com/solvapay/solvapay-sdk).
 
 Python is the dominant language for agent frameworks (LangChain, FastMCP, CrewAI, AutoGen). SolvaPay's official SDK is TypeScript-only. This SDK brings first-class Python support so agent developers can gate tools behind paywalls without switching ecosystems.
 
-> 🎬 **New in v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
+> **New in v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
+> **v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
 > **v0.4:** Async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events.
 
 ## Install
 
 ```bash
-pip install git+https://github.com/dhruv-sanan/solvapay-python
+pip install solvapay-python
+# with optional extras:
+pip install solvapay-python[langchain]
+pip install solvapay-python[fastapi]
 ```
 
 ## Quickstart
@@ -223,6 +229,7 @@ async def handle_webhook(request: Request) -> dict:
 - v0.3 — FastMCP paywall demo (`examples/fastmcp-paywall/`) ✅
 - v0.4 — async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events ✅
 - v0.5 — paywall state classifier, LangChain `monetize_tool` decorator ✅
+- v0.6 — admin endpoints (products, plans, merchant, platform config), PyPI publish ✅
 
 ## Contributing
 

solvapay_python-0.7.1/examples/marketplace/.env.example

@@ -0,0 +1,15 @@
+# --- SolvaPay sandbox ---
+SOLVAPAY_API_BASE_URL=https://api.solvapay.com
+SOLVAPAY_SECRET_KEY=sk_sandbox_REPLACE_ME
+SOLVAPAY_PRODUCT_REF=prd_0QKI8NHF
+
+# Customer A: existing sandbox customer subscribed to the product above (OK path).
+SOLVAPAY_DEMO_CUSTOMER_REF=cus_CI5SGXJF
+
+# Customer B: pre-existing sandbox customer with no subscription.
+# SolvaPay returns withinLimits=false -> paywall_state.decide() classifies the gate.
+SOLVAPAY_DEMO_BLOCKED_CUSTOMER_REF=cus_YARKQDEN
+
+# --- Google Gemini (real LLM calls) ---
+GEMINI_API_KEY=REPLACE_ME
+GEMINI_MODEL=gemini-2.0-flash

solvapay_python-0.7.1/examples/marketplace/.streamlit/config.toml

@@ -0,0 +1,16 @@
+[theme]
+base = "dark"
+primaryColor = "#7c5cff"
+backgroundColor = "#0e1117"
+secondaryBackgroundColor = "#161a22"
+textColor = "#e6e9ef"
+font = "sans serif"
+
+[server]
+headless = true
+
+[browser]
+gatherUsageStats = false
+
+[client]
+toolbarMode = "minimal"

solvapay_python-0.7.1/examples/marketplace/PLAN.md

@@ -0,0 +1,108 @@
+# Scope A — v0.7.0 SDK fixes + Marketplace Demo
+
+## Goal
+- Real SolvaPay sandbox compatibility (SDK shape bugs fixed)
+- Demo shows OK + UPGRADE_REQUIRED with real checkout URL
+- v0.7.0 shipped + 90s LinkedIn demo recorded
+
+## Real-API findings (recorded 2026-05-16)
+
+| Endpoint | SDK expects | Real API returns |
+|---|---|---|
+| `GET /v1/sdk/customers/{ref}` | `customerRef` | `reference` |
+| `GET /v1/sdk/customers?externalRef=` | `customerRef` | `reference` |
+| `POST /v1/sdk/customers` | `customerRef` | `reference` (assumed; mirrors GET) |
+| `GET /v1/sdk/customers/{ref}/balance` | `{balance, currency, plan}` | `{customerRef, credits, displayCurrency, creditsPerMinorUnit, displayExchangeRate}` |
+| `POST /v1/sdk/limits` | `{withinLimits, remaining, plan, creditBalance, checkoutUrl, ...}` | `{withinLimits, remaining, meterName}` (no plan, no checkout_url) |
+
+## Workstreams
+
+### A. SDK patches (me) — v0.7.0
+1. **`models.py`**
+   - `Customer`: alias `customerRef` → `reference` for `customer_ref` field (or rename field to `reference`)
+   - `BalanceResponse`: drop `balance/currency/plan`; add `credits: int`, `display_currency: str` (alias `displayCurrency`), `credits_per_minor_unit: int` (alias `creditsPerMinorUnit`). Add `balance` property converting credits to display units for backwards-compat.
+   - `LimitResponse`: keep optional fields tolerant; ensure missing `plan`, `creditBalance`, `checkoutUrl` parse to `None` (already partially the case — verify).
+2. **`client.py` + `_async_client.py`**
+   - `ensure_customer`: replace `existing.get("customerRef")` / `existing["customerRef"]` / `created["customerRef"]` with `reference` (lines 127, 128, 143 sync; 111, 112, 127 async)
+3. **`paywall.py`**
+   - When `within_limits == False` and `limits.checkout_url is None`, automatically call `create_checkout_session(customer_ref=..., product_ref=...)` and surface the resulting URL in both `PaywallRequired.checkout_url` and the raised banner. Mirror in async path.
+4. **`paywall_state.py`**
+   - Stays pure. `decide()` works on whatever `LimitResponse` it gets. New helper `decide_with_checkout(client, limits, *, customer_ref, product_ref)` for callers that want the checkout URL materialized.
+5. **Tests**
+   - Update `tests/conftest.py` fixtures to use real shape
+   - Add regression test using captured real-API payloads
+   - Verify `mypy --strict` + `ruff` pass
+6. **Versioning**
+   - Bump `pyproject.toml` to `0.7.0`
+   - Update `__init__.py` __version__ if present
+   - Update User-Agent in `_http.py` to `solvapay-python/0.7.0`
+   - Append CHANGELOG entry
+
+### B. Sandbox dashboard config (user) — parallel
+1. On product `prd_0QKI8NHF`: add **Pro** pricing option (recurring, high reqs/month e.g. 10000) — NOT default
+2. Subscribe Alice (`cus_CI5SGXJF`) to Pro
+3. Leave Bob (`cus_YARKQDEN`) on Free (10 reqs/month default)
+4. Pre-record: drain Bob's free reqs via the demo itself OR via direct API
+
+### C. Marketplace demo wiring (me)
+1. Use real `client.ensure_customer` for Bob (already created → idempotent)
+2. `check_and_decide`: real `check_limits` → `decide()` → if blocked, mint real `create_checkout_session` URL
+3. Real `track_usage` per call
+4. Sidebar shows real `remaining` from `check_limits` + plan name from Customer purchases
+5. 4 agents call real Google Gemini
+6. "Show the SDK call" expander prints actual Python with real values
+7. Reset button: re-bootstrap fresh blocked customer via `ensure_customer(timestamp-ref)` — for clean retakes
+
+### D. video.md Snippet 4 (me)
+- Write 90s script for marketplace walkthrough
+- Update delivery checklist
+
+## File list
+
+**SDK:**
+- `src/solvapay/models.py`
+- `src/solvapay/client.py`
+- `src/solvapay/_async_client.py`
+- `src/solvapay/paywall.py`
+- `src/solvapay/_http.py` (UA version bump)
+- `pyproject.toml` (version 0.7.0)
+- `tests/conftest.py` + impacted test files
+- `CHANGELOG.md` (if present)
+
+**Marketplace:**
+- `examples/marketplace/app.py`
+- `examples/marketplace/sdk_gateway.py`
+- `examples/marketplace/agents.py`
+- `examples/marketplace/demo_customers.py`
+- `examples/marketplace/ui_components.py`
+- `examples/marketplace/README.md`
+- delete `examples/marketplace/_smoke.py` before commit
+
+**Docs:**
+- `/Users/dhruvsanan/Desktop/open-source/video.md` (Snippet 4)
+
+## Execution sequence
+1. ✅ Write PLAN.md + update video.md Snippet 4
+2. Patch SDK models + client + async client
+3. Patch paywall.py (auto-mint checkout URL on block)
+4. Update tests + run pytest + mypy + ruff
+5. Bump version + CHANGELOG
+6. Rewire marketplace gateway/app/sidebar against patched SDK
+7. Re-run `_smoke.py` against real sandbox — verify all paths produce expected typed states
+8. Streamlit local end-to-end run
+9. Once Alice on Pro: record 90s clip
+10. Delete `_smoke.py`, commit, push, tag v0.7.0, publish on PyPI
+
+## Open decisions
+- Customer model field name: keep `customer_ref` with new alias OR rename to `reference`. **Decision: keep `customer_ref` with alias change** — preserves public API for existing users.
+- `BalanceResponse.balance` semantics: `credits / credits_per_minor_unit` gives display-unit amount. Keep `balance: float` as computed property for backward compat. Real users see "$1000.00" not "100000 credits". 
+- Plan info source: real `/limits` doesn't return plan; pull plan from `client.get_customer(ref).purchases[0].planSnapshot` if needed for sidebar.
+
+## Risk register
+| Risk | Mitigation |
+|---|---|
+| SolvaPay API returns different shape for `POST /customers` than GET | Test create explicitly during patches; tolerate both shapes |
+| Pro plan subscribe flow not exposed in dashboard → can't subscribe Alice without API call | User flags blocker; I add `subscribe` helper or use checkout-session flow |
+| `track_usage` fails for Bob (0 credits, Free plan) → can't drain him via API | Drain via UI (record Bob using 10 calls live = the demo itself) |
+| `mypy --strict` fails after BalanceResponse rewrite | Add explicit type hints + computed property typing |
+| Existing tests pass against old mock shape but break against real shape | Update fixtures to mirror real shape (captured in this PLAN.md table) |

solvapay_python-0.7.1/examples/marketplace/README.md

@@ -0,0 +1,67 @@
+# Agent Marketplace — a real SolvaPay SDK demo
+
+Streamlit marketplace of paywalled AI agents. Every paywall decision hits the
+real **SolvaPay sandbox**. Every agent run hits a real **Gemini LLM**.
+
+## What's real
+
+- `solvapay-python` SDK — unmodified, against `https://api.solvapay.com`
+  - `check_limits` → real
+  - `track_usage` → real (sandbox metering ticks)
+  - `get_customer_balance` → real
+  - `ensure_customer` → real (bootstraps Customer B on first run)
+  - `paywall_state.decide()` → real typed state machine on real responses
+  - `@paywall.require` decorator → real, raises `PaywallRequired` from sandbox
+- Two real sandbox customers:
+  - **Alice** (`SOLVAPAY_DEMO_CUSTOMER_REF`) — pre-existing, subscribed
+  - **Bob** (`SOLVAPAY_DEMO_BLOCKED_CUSTOMER_REF`) — created by the app via
+    `ensure_customer()` on first boot; no plan assigned → SolvaPay returns
+    `withinLimits=false`
+- One real product (`SOLVAPAY_PRODUCT_REF`) — all 4 agents bill against it
+- Real LLM calls via Google Gemini
+
+## What's "fake"
+
+- The 4 per-agent display prices ($0.02 / $0.05 / $0.10 / $0.03) are cosmetic
+  for the marketplace look. Real metering is whatever your SolvaPay product
+  config dictates. The sidebar discloses this.
+
+That's it. No HTTP mocking. No fake customers.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+pip install -e ../..             # local SDK (editable)
+cp .env.example .env             # fill in:
+                                 #   SOLVAPAY_SECRET_KEY (sandbox)
+                                 #   SOLVAPAY_PRODUCT_REF (your product)
+                                 #   SOLVAPAY_DEMO_CUSTOMER_REF (subscribed customer)
+                                 #   GEMINI_API_KEY
+streamlit run app.py
+```
+
+First boot calls `client.ensure_customer(...)` to create Customer B in your
+sandbox. Subsequent boots find the same customer (idempotent).
+
+## What the demo shows
+
+1. Alice runs an agent → SDK approves → LLM responds → usage tracked.
+2. Switch to Bob → click any agent → SDK blocks → `paywall_state.decide()`
+   returns a typed `GateDecision` → UI branches on the enum.
+3. The "Show the SDK call" panel under each gated result prints the real
+   Python that produced the state — including the real `checkout_url`
+   SolvaPay returned. Click it; it opens the real sandbox checkout.
+
+Two integration styles visible side-by-side:
+
+- **Explicit** — Web Researcher / Text Analyst / Image Describer use
+  `client.check_limits(...)` + `paywall_state.decide(...)`.
+- **Decorator** — Code Reviewer's runner is wrapped with
+  `@paywall.require(product=..., customer_ref_arg="customer_ref")`.
+  Catches `PaywallRequired` and re-uses the explicit path to populate the
+  same typed banner.
+
+## Cost
+
+Each full demo cycle costs <$0.01 in Gemini tokens. SolvaPay sandbox is free.

solvapay_python-0.7.1/examples/marketplace/agents.py

@@ -0,0 +1,124 @@
+"""Marketplace agent catalog. Each agent calls a real LLM (Google Gemini).
+
+All 4 agents bill the same SolvaPay product (the one in your sandbox). They
+differ only by system prompt + display price — the marketplace framing is
+cosmetic; real metering is per-call against `SOLVAPAY_PRODUCT_REF`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Callable
+
+from google import genai
+from google.genai import types
+
+log = logging.getLogger("marketplace.llm")
+
+_client: genai.Client | None = None
+
+
+def _get_client() -> genai.Client:
+    global _client
+    if _client is None:
+        _client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+    return _client
+
+
+def _model() -> str:
+    return os.environ.get("GEMINI_MODEL", "gemini-2.0-flash")
+
+
+def _llm(system: str, user: str, max_tokens: int = 600, *, agent_name: str = "unknown") -> str:
+    """Single-turn LLM call. Returns the model's text response."""
+    model = _model()
+    log.info("LLM CALL → model=%s | agent=%s | input_chars=%d", model, agent_name, len(user))
+    response = _get_client().models.generate_content(
+        model=model,
+        contents=user,
+        config=types.GenerateContentConfig(
+            system_instruction=system,
+            max_output_tokens=max_tokens,
+        ),
+    )
+    text = (response.text or "(no response)").strip()
+    log.info("LLM DONE ✓ model=%s | agent=%s | output_chars=%d", model, agent_name, len(text))
+    return text
+
+
+# --- agent runners ---------------------------------------------------------
+
+def _run_web_researcher(query: str) -> str:
+    return _llm(
+        system=(
+            "You are a concise research assistant. Given a topic, return 3 bullet points "
+            "of factual, well-known information about it. No fluff. Use markdown."
+        ),
+        user=query.strip() or "Stockholm fintech startups in agent payments",
+        agent_name="web_researcher",
+    )
+
+
+def _run_text_analyst(text: str) -> str:
+    return _llm(
+        system=(
+            "You are a text analyst. Given a piece of text, return: (1) sentiment with a "
+            "confidence score 0-1, (2) 2-3 key themes, (3) one suggested action. "
+            "Markdown bullets only."
+        ),
+        user=text.strip() or "I love this product but the onboarding is a bit confusing.",
+        agent_name="text_analyst",
+    )
+
+
+def _run_code_reviewer(diff: str) -> str:
+    return _llm(
+        system=(
+            "You are a senior code reviewer. Given a code snippet or diff, return a "
+            "terse review: 🟢 strengths, 🟡 nits, 🔴 bugs. Max 6 bullets total."
+        ),
+        user=diff.strip() or "def add(a, b):\n    return a + b  # TODO: handle floats",
+        agent_name="code_reviewer",
+    )
+
+
+def _run_image_describer(prompt: str) -> str:
+    return _llm(
+        system=(
+            "You are an image-description assistant. The user describes an image in words. "
+            "Return a 3-bullet refinement covering subject, composition, and mood."
+        ),
+        user=prompt.strip() or "A cat sitting on a windowsill at golden hour",
+        agent_name="image_describer",
+    )
+
+
+@dataclass(frozen=True)
+class Agent:
+    slug: str
+    name: str
+    blurb: str
+    icon: str
+    price_usd: float  # display only; real billing is per the SolvaPay product config
+    run: Callable[[str], str]
+
+
+AGENTS: list[Agent] = [
+    Agent("web_researcher",  "Web Researcher",  "3-bullet brief on any topic.",                     "🔎",  0.02, _run_web_researcher),
+    Agent("text_analyst",    "Text Analyst",    "Sentiment + themes for any text.",                 "📊",  0.05, _run_text_analyst),
+    Agent("code_reviewer",   "Code Reviewer",   "Senior-style review of a snippet. (Decorator-gated.)", "🧑‍💻", 0.10, _run_code_reviewer),
+    Agent("image_describer", "Image Describer", "Refines an image description.",                    "🖼️",  0.03, _run_image_describer),
+]
+
+AGENTS_BY_SLUG: dict[str, Agent] = {a.slug: a for a in AGENTS}
+
+
+def example_input_for(slug: str) -> str:
+    return {
+        "web_researcher": "Stockholm fintech startups working on AI agent payments",
+        "text_analyst": "I love this product but the onboarding is a bit confusing.",
+        "code_reviewer": "def divide(a, b):\n    return a / b  # TODO",
+        "image_describer": "A short-haired tabby cat on a windowsill at golden hour",
+    }.get(slug, "")