prompture 1.12.2.dev1__tar.gz → 1.12.3.dev1__tar.gz

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/CLAUDE.md

@@ -70,6 +70,10 @@ Configuration is in `pyproject.toml` under `[tool.ruff]`.
 - **`prompture/field_definitions.py`** — Thread-safe global field registry with 50+ predefined fields, template variable substitution (`{{current_year}}`, `{{current_date}}`), and Pydantic Field generation via `field_from_registry()`.
 - **`prompture/infra/settings.py`** — Pydantic-settings `Settings` class loading provider API keys/endpoints from `.env`.
 - **`prompture/infra/discovery.py`** — `get_available_models()` plus per-modality helpers (`get_available_image_gen_models`, `get_available_video_gen_models`, `get_available_audio_models`). Auto-detects models from configured providers via static `*_PRICING` / `KNOWN_MODELS` tables, dynamic provider listing endpoints (Ollama, ElevenLabs), and models.dev capability fallback.
+- **`prompture/resilience/`** — `resilient()` / `ResilientDriver` (+ async): a composite Driver that retries, parks, rotates keys and fails over across targets. `errors.py` is the error→action decision table (`classify_error`, extensible via `register_error_rule`); `breaker.py` holds lazy-recovery circuit breakers scoped by provider/model/key; `keys.py` builds key pools from `{PROVIDER}_API_KEYS`. Every result carries `meta["route"]` (served_by, fallback, attempts).
+- **`prompture/gateway/`** — framework-agnostic wire formats. `anthropic_format.py` (Anthropic Messages: `anthropic_to_driver`, `stream_anthropic_events`, `live_events_for`) and `responses_format.py` (OpenAI Responses) sit beside the OpenAI chat format; `reasoning_cache.py` replays `reasoning_content` for stateless clients. OpenAI chat format: request→driver messages/options (`to_driver_messages`, `driver_options` incl. `response_format`→`json_mode`), `run_chat`/`arun_chat`, `chat_completion`/`chat_chunk`, `stream_chat_chunks` (with `on_complete` metering hook), `sse`. Used by `prompture serve` and prompture-hub — keep response shaping here, not in servers.
+- **Virtual models** — `combo/<name>`, `auto/<mode>`, `fusion/<name>` (`groups/fusion.py`) and aliases resolve in `resilience/virtual.py`, called at the top of `get_driver_for_model` / `get_async_driver_for_model`.
+- **`prompture/infra/otel.py`** / **`infra/compression.py`** — GenAI-convention OpenTelemetry spans via `DriverCallbacks`; conservative message compression for agent loops.
 - **`prompture/runner.py`** — Spec-driven test suite runner for cross-model comparison.
 - **`prompture/validator.py`** — JSON schema validation via jsonschema with fallback.
 

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.12.2.dev1
+Version: 1.12.3.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Author-email: Juan Denis <juan@vene.co>
 License-Expression: MIT
@@ -67,6 +67,10 @@ Requires-Dist: fastapi>=0.100; extra == "serve"
 Requires-Dist: uvicorn[standard]>=0.20; extra == "serve"
 Requires-Dist: sse-starlette>=1.6; extra == "serve"
 Requires-Dist: python-multipart>=0.0.9; extra == "serve"
+Provides-Extra: hub
+Requires-Dist: prompture-hub>=0.0.3; extra == "hub"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Provides-Extra: scaffold
 Requires-Dist: jinja2>=3.0; extra == "scaffold"
 Provides-Extra: rag-pdf
@@ -177,6 +181,8 @@ print(person.name)  # Maria
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
 **Ops**
+- Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
+- [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
 - `prompture serve` — OpenAI-compatible server (`/v1/chat/completions`, `/v1/embeddings`, `/v1/coding-agents`, …) routes any client to any provider
 - Usage tracking — tokens + cost on every call
 - Response cache — memory, SQLite, Redis backends
@@ -210,6 +216,7 @@ use.
 |---|---|---|
 | `redis` | Redis cache backend | `pip install prompture[redis]` |
 | `serve` | FastAPI server mode (`prompture serve`) | `pip install prompture[serve]` |
+| `hub` | [prompture-hub](#prompture-hub-gateway--dashboard) — gateway + dashboard with scoped keys and spend caps | `pip install prompture[hub]` |
 | `airllm` | AirLLM local inference | `pip install prompture[airllm]` |
 | `bedrock` | AWS Bedrock driver (`boto3`) | `pip install prompture[bedrock]` |
 | `sandbox` | Sandboxed Python execution tool (`tukuy`) | `pip install prompture[sandbox]` |
@@ -1106,6 +1113,126 @@ for attempt in result["attempts"]:
 
 If every model fails and no `fallback` is provided, an `ExtractionError` is raised with the full `attempts` list, `total_cost`, and `total_tokens` attached as attributes.
 
+### Resilient Routing
+
+`resilient()` wraps several models (and several API keys) into **one driver**. It retries transient failures, waits out short rate limits, parks broken or throttled targets, and fails over to the next model — while exposing the normal driver interface, so it drops into `Conversation`, `Agent`, `ask_for_json`, `extract_with_model` and `prompture serve` unchanged.
+
+```python
+from prompture import Conversation, resilient
+
+driver = resilient(
+    "openai/gpt-4o",                   # preferred
+    "claude/claude-sonnet-4-5",        # if OpenAI is down / rate limited
+    "ollama/llama3.1:8b",              # local last resort
+)
+
+conv = Conversation(driver=driver)
+print(conv.ask("Summarize this ticket: ..."))
+
+resp = driver.generate_messages([{"role": "user", "content": "hi"}], {})
+resp["meta"]["route"]
+# {"served_by": "claude/claude-sonnet-4-5", "fallback": True, "key_id": None,
+#  "attempts": [{"model": "openai/gpt-4o", "outcome": "error",
+#                "error": {"category": "rate_limit", "status_code": 429, "retry_after": 20.0, ...}},
+#               {"model": "claude/claude-sonnet-4-5", "outcome": "ok", "elapsed_ms": 812.4}]}
+```
+
+What happens on each failure is decided by a small, extensible table (`prompture.resilience.classify_error`), which understands `DriverHTTPError`, `requests`/`httpx` errors, OpenAI/Anthropic SDK errors and wrapped exceptions:
+
+| Error | Action |
+|---|---|
+| Timeout, connection reset, 500/502/504 | Retry the same model with exponential backoff |
+| 429, 503/529 overloaded | Park that model/key for `Retry-After` and move on (wait inline if it's the last option) |
+| 401/402, `insufficient_quota` | Disable that key for an hour and move on |
+| 404, context length exceeded, content filter, unsupported feature | Skip to the next model without penalizing its health |
+| Other 400/422 | Raise immediately — no model will fix a bad request |
+
+**Key rotation** — set several keys and each model expands to one target per key, rotated round-robin; a key that returns 401 or runs out of quota is parked while the others keep serving:
+
+```bash
+OPENAI_API_KEYS=sk-one,sk-two,sk-three
+```
+
+Or in code: `register_key_pool("openai", ["sk-one", "sk-two"])`.
+
+**Circuit breakers** are shared process-wide per provider, model and key, and recover lazily (no background threads): after repeated failures a target is skipped until its recovery window passes, then a single probe request decides whether it comes back. Inspect them with `prompture.resilience.get_breaker_registry().snapshot()`.
+
+Tune timings with `RetryPolicy(max_attempts=3, max_wait=10, ...)`, add provider-specific rules with `register_error_rule(ErrorRule(...))`, and use `async_resilient()` for async drivers. Streams fail over transparently until the first chunk is sent.
+
+**Combos, aliases and `auto/` models** — give a routing policy a name and use it anywhere a model string goes (`get_driver_for_model`, `Conversation(model_name=...)`, `prompture serve`, prompture-hub):
+
+```python
+from prompture import Conversation, register_combo, register_model_alias
+
+register_combo(
+    "chat",
+    ["openai/gpt-4o", "claude/claude-sonnet-4-5", "groq/llama-3.3-70b-versatile"],
+    strategy="latency",   # priority | round_robin | weighted | latency | p2c | last_good | cheapest
+    sticky=True,          # keep a conversation on one API key so prompt caches stay warm
+)
+register_model_alias("default", "combo/chat")
+
+Conversation(model_name="default").ask("hi")        # routed through the combo
+Conversation(model_name="auto/cheap").ask("hi")     # cheapest configured chat models, across providers
+```
+
+`auto/<mode>` builds a fallback chain from whichever providers you have keys for — `auto/cheap`, `auto/fast`, `auto/best`, `auto/balanced`, or a pricing tier `auto/budget` / `auto/standard` / `auto/premium`. Combos and aliases can also live in JSON, loaded with `load_combos(path)` or automatically from `PROMPTURE_COMBOS_FILE`:
+
+```json
+{
+  "combos": {"chat": {"targets": ["openai/gpt-4o", "claude/claude-sonnet-4-5"], "strategy": "latency"}},
+  "aliases": {"default": "combo/chat", "fast": "groq/llama-3.3-70b-versatile"}
+}
+```
+
+**Why did it route there?** `explain_route(resp["meta"]["route"])` turns the trace into plain text:
+
+```
+Served by claude/claude-sonnet-4-5 after 2 attempts — strategy: latency
+  1. openai/gpt-4o — rate_limit (429), retry after 20s, parked, 312 ms
+  2. claude/claude-sonnet-4-5 — ok, 812 ms
+```
+
+### Fusion (panel + judge)
+
+Ask several models in parallel and have a judge write one answer from their (anonymized, shuffled) responses. Failed or slow panelists are skipped; with one surviving answer the judge is bypassed. It's a driver too, so it works as a model name:
+
+```python
+from prompture import Conversation
+from prompture.groups import register_fusion
+
+register_fusion(
+    "council",
+    panel=["openai/gpt-4o", "claude/claude-sonnet-4-5", "google/gemini-2.5-pro"],
+    judge="claude/claude-opus-4-6",
+    timeout=60,
+)
+Conversation(model_name="fusion/council").ask("Design a rate limiter for a multi-tenant API.")
+```
+
+`resp["meta"]["fusion"]` lists each panelist's outcome, latency and cost; token and cost totals include the judge.
+
+### Prompt Compression
+
+`compress_messages()` makes conservative, meaning-preserving cuts that matter most in agent loops, where tool output dominates the bill. It trims older oversized tool results to a head+tail window, collapses whitespace in system/tool text and drops repeated system prompts. User and assistant prose, and the latest tool result, are left alone.
+
+```python
+from prompture.infra import compress_messages
+
+messages, stats = compress_messages(messages, max_tool_chars=6000)
+stats.saved_chars, stats.tool_results_trimmed
+```
+
+### Observability — OpenTelemetry
+
+`instrument_driver()` emits one span per driver call following the GenAI semantic conventions (`gen_ai.request.model`, `gen_ai.usage.input_tokens`, …) plus `prompture.cost_usd` and, for resilient drivers, who served the call and whether it fell back. Prompt/completion text is only recorded with `capture_content=True`.
+
+```python
+from prompture import instrument_driver, resilient   # pip install "prompture[otel]"
+
+driver = instrument_driver(resilient("openai/gpt-4o", "claude/claude-sonnet-4-5"))
+```
+
 ### TOON Input — Token Savings
 
 Analyze structured data with automatic TOON conversion for 45-60% fewer tokens:
@@ -1980,6 +2107,39 @@ Selected flags:
 
 Full example walkthrough: [`examples/openai_server_example.md`](examples/openai_server_example.md).
 
+## prompture-hub: Gateway + Dashboard
+
+Want a UI, or want to let other apps use your provider keys without handing them out? **[prompture-hub](https://github.com/jhd3197/prompture-hub)** is the companion app: a self-hosted gateway and web dashboard built on Prompture.
+
+```
+ your apps / Cursor / Claude Code / scripts
+        │  hub-issued keys (ph_…)
+        ▼
+ ┌─────────────────────────────┐
+ │  prompture-hub              │  dashboard · scoped keys · spend caps
+ │  (FastAPI + React, SQLite)  │  rate limits · usage + cost per call
+ └──────────────┬──────────────┘
+                │  Prompture drivers, resilience, gateway format
+                ▼
+   OpenAI · Anthropic · Google · Groq · Ollama · … (real keys stay here)
+```
+
+```bash
+pip install "prompture[hub]"
+prompture hub            # dashboard at http://localhost:1984/
+```
+
+|  | `prompture serve` | prompture-hub |
+|---|---|---|
+| Use it for | One app / local dev, one shared bearer token | Many apps or people sharing your provider keys |
+| Keys | Single optional `--api-key` | Per-app hub keys, revocable, hashed at rest |
+| Limits | Model allowlist, per-IP rate limit | Per-key model allowlist, spend caps (day/week/month), rate limits |
+| Visibility | Logs | Dashboard: usage, cost, latency, conversations |
+| Protocols | OpenAI chat completions, embeddings, media | OpenAI chat completions + Responses API, Anthropic Messages API (Claude Code), embeddings |
+| Extras | Server-side tools (`--sandbox`, `--web-search`), media endpoints | Analytics dashboard, `prompture-hub setup <tool>` for Claude Code / Codex / Cursor / Aider, key expiry + IP allowlists, OAuth login |
+
+Both build on the same wire-format code in `prompture.gateway` (OpenAI chat completions, OpenAI Responses, Anthropic Messages), so responses, streaming events and usage blocks are identical — and both accept `combo/`, `auto/`, `fusion/` and alias model names.
+
 ## Integrating & Extending
 
 - **FastAPI integration patterns** (AsyncAgent + tools, SSE streaming, structured endpoints, error handling) — see [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md#integrating-prompture-into-your-project)

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/README.md

@@ -70,6 +70,8 @@ print(person.name)  # Maria
 - `generate_qa_dataset()` — synthetic JSONL datasets ready for Unsloth, Axolotl, TRL
 
 **Ops**
+- Resilient routing — `resilient()` retries transient errors, honors `Retry-After`, rotates API keys, trips circuit breakers and fails over across models; every response records who served it — see [Resilient Routing](#resilient-routing)
+- [prompture-hub](#prompture-hub-gateway--dashboard) — optional companion app: web dashboard, scoped per-app keys, spend caps and per-call metering (`pip install prompture[hub]`)
 - `prompture serve` — OpenAI-compatible server (`/v1/chat/completions`, `/v1/embeddings`, `/v1/coding-agents`, …) routes any client to any provider
 - Usage tracking — tokens + cost on every call
 - Response cache — memory, SQLite, Redis backends
@@ -103,6 +105,7 @@ use.
 |---|---|---|
 | `redis` | Redis cache backend | `pip install prompture[redis]` |
 | `serve` | FastAPI server mode (`prompture serve`) | `pip install prompture[serve]` |
+| `hub` | [prompture-hub](#prompture-hub-gateway--dashboard) — gateway + dashboard with scoped keys and spend caps | `pip install prompture[hub]` |
 | `airllm` | AirLLM local inference | `pip install prompture[airllm]` |
 | `bedrock` | AWS Bedrock driver (`boto3`) | `pip install prompture[bedrock]` |
 | `sandbox` | Sandboxed Python execution tool (`tukuy`) | `pip install prompture[sandbox]` |
@@ -999,6 +1002,126 @@ for attempt in result["attempts"]:
 
 If every model fails and no `fallback` is provided, an `ExtractionError` is raised with the full `attempts` list, `total_cost`, and `total_tokens` attached as attributes.
 
+### Resilient Routing
+
+`resilient()` wraps several models (and several API keys) into **one driver**. It retries transient failures, waits out short rate limits, parks broken or throttled targets, and fails over to the next model — while exposing the normal driver interface, so it drops into `Conversation`, `Agent`, `ask_for_json`, `extract_with_model` and `prompture serve` unchanged.
+
+```python
+from prompture import Conversation, resilient
+
+driver = resilient(
+    "openai/gpt-4o",                   # preferred
+    "claude/claude-sonnet-4-5",        # if OpenAI is down / rate limited
+    "ollama/llama3.1:8b",              # local last resort
+)
+
+conv = Conversation(driver=driver)
+print(conv.ask("Summarize this ticket: ..."))
+
+resp = driver.generate_messages([{"role": "user", "content": "hi"}], {})
+resp["meta"]["route"]
+# {"served_by": "claude/claude-sonnet-4-5", "fallback": True, "key_id": None,
+#  "attempts": [{"model": "openai/gpt-4o", "outcome": "error",
+#                "error": {"category": "rate_limit", "status_code": 429, "retry_after": 20.0, ...}},
+#               {"model": "claude/claude-sonnet-4-5", "outcome": "ok", "elapsed_ms": 812.4}]}
+```
+
+What happens on each failure is decided by a small, extensible table (`prompture.resilience.classify_error`), which understands `DriverHTTPError`, `requests`/`httpx` errors, OpenAI/Anthropic SDK errors and wrapped exceptions:
+
+| Error | Action |
+|---|---|
+| Timeout, connection reset, 500/502/504 | Retry the same model with exponential backoff |
+| 429, 503/529 overloaded | Park that model/key for `Retry-After` and move on (wait inline if it's the last option) |
+| 401/402, `insufficient_quota` | Disable that key for an hour and move on |
+| 404, context length exceeded, content filter, unsupported feature | Skip to the next model without penalizing its health |
+| Other 400/422 | Raise immediately — no model will fix a bad request |
+
+**Key rotation** — set several keys and each model expands to one target per key, rotated round-robin; a key that returns 401 or runs out of quota is parked while the others keep serving:
+
+```bash
+OPENAI_API_KEYS=sk-one,sk-two,sk-three
+```
+
+Or in code: `register_key_pool("openai", ["sk-one", "sk-two"])`.
+
+**Circuit breakers** are shared process-wide per provider, model and key, and recover lazily (no background threads): after repeated failures a target is skipped until its recovery window passes, then a single probe request decides whether it comes back. Inspect them with `prompture.resilience.get_breaker_registry().snapshot()`.
+
+Tune timings with `RetryPolicy(max_attempts=3, max_wait=10, ...)`, add provider-specific rules with `register_error_rule(ErrorRule(...))`, and use `async_resilient()` for async drivers. Streams fail over transparently until the first chunk is sent.
+
+**Combos, aliases and `auto/` models** — give a routing policy a name and use it anywhere a model string goes (`get_driver_for_model`, `Conversation(model_name=...)`, `prompture serve`, prompture-hub):
+
+```python
+from prompture import Conversation, register_combo, register_model_alias
+
+register_combo(
+    "chat",
+    ["openai/gpt-4o", "claude/claude-sonnet-4-5", "groq/llama-3.3-70b-versatile"],
+    strategy="latency",   # priority | round_robin | weighted | latency | p2c | last_good | cheapest
+    sticky=True,          # keep a conversation on one API key so prompt caches stay warm
+)
+register_model_alias("default", "combo/chat")
+
+Conversation(model_name="default").ask("hi")        # routed through the combo
+Conversation(model_name="auto/cheap").ask("hi")     # cheapest configured chat models, across providers
+```
+
+`auto/<mode>` builds a fallback chain from whichever providers you have keys for — `auto/cheap`, `auto/fast`, `auto/best`, `auto/balanced`, or a pricing tier `auto/budget` / `auto/standard` / `auto/premium`. Combos and aliases can also live in JSON, loaded with `load_combos(path)` or automatically from `PROMPTURE_COMBOS_FILE`:
+
+```json
+{
+  "combos": {"chat": {"targets": ["openai/gpt-4o", "claude/claude-sonnet-4-5"], "strategy": "latency"}},
+  "aliases": {"default": "combo/chat", "fast": "groq/llama-3.3-70b-versatile"}
+}
+```
+
+**Why did it route there?** `explain_route(resp["meta"]["route"])` turns the trace into plain text:
+
+```
+Served by claude/claude-sonnet-4-5 after 2 attempts — strategy: latency
+  1. openai/gpt-4o — rate_limit (429), retry after 20s, parked, 312 ms
+  2. claude/claude-sonnet-4-5 — ok, 812 ms
+```
+
+### Fusion (panel + judge)
+
+Ask several models in parallel and have a judge write one answer from their (anonymized, shuffled) responses. Failed or slow panelists are skipped; with one surviving answer the judge is bypassed. It's a driver too, so it works as a model name:
+
+```python
+from prompture import Conversation
+from prompture.groups import register_fusion
+
+register_fusion(
+    "council",
+    panel=["openai/gpt-4o", "claude/claude-sonnet-4-5", "google/gemini-2.5-pro"],
+    judge="claude/claude-opus-4-6",
+    timeout=60,
+)
+Conversation(model_name="fusion/council").ask("Design a rate limiter for a multi-tenant API.")
+```
+
+`resp["meta"]["fusion"]` lists each panelist's outcome, latency and cost; token and cost totals include the judge.
+
+### Prompt Compression
+
+`compress_messages()` makes conservative, meaning-preserving cuts that matter most in agent loops, where tool output dominates the bill. It trims older oversized tool results to a head+tail window, collapses whitespace in system/tool text and drops repeated system prompts. User and assistant prose, and the latest tool result, are left alone.
+
+```python
+from prompture.infra import compress_messages
+
+messages, stats = compress_messages(messages, max_tool_chars=6000)
+stats.saved_chars, stats.tool_results_trimmed
+```
+
+### Observability — OpenTelemetry
+
+`instrument_driver()` emits one span per driver call following the GenAI semantic conventions (`gen_ai.request.model`, `gen_ai.usage.input_tokens`, …) plus `prompture.cost_usd` and, for resilient drivers, who served the call and whether it fell back. Prompt/completion text is only recorded with `capture_content=True`.
+
+```python
+from prompture import instrument_driver, resilient   # pip install "prompture[otel]"
+
+driver = instrument_driver(resilient("openai/gpt-4o", "claude/claude-sonnet-4-5"))
+```
+
 ### TOON Input — Token Savings
 
 Analyze structured data with automatic TOON conversion for 45-60% fewer tokens:
@@ -1873,6 +1996,39 @@ Selected flags:
 
 Full example walkthrough: [`examples/openai_server_example.md`](examples/openai_server_example.md).
 
+## prompture-hub: Gateway + Dashboard
+
+Want a UI, or want to let other apps use your provider keys without handing them out? **[prompture-hub](https://github.com/jhd3197/prompture-hub)** is the companion app: a self-hosted gateway and web dashboard built on Prompture.
+
+```
+ your apps / Cursor / Claude Code / scripts
+        │  hub-issued keys (ph_…)
+        ▼
+ ┌─────────────────────────────┐
+ │  prompture-hub              │  dashboard · scoped keys · spend caps
+ │  (FastAPI + React, SQLite)  │  rate limits · usage + cost per call
+ └──────────────┬──────────────┘
+                │  Prompture drivers, resilience, gateway format
+                ▼
+   OpenAI · Anthropic · Google · Groq · Ollama · … (real keys stay here)
+```
+
+```bash
+pip install "prompture[hub]"
+prompture hub            # dashboard at http://localhost:1984/
+```
+
+|  | `prompture serve` | prompture-hub |
+|---|---|---|
+| Use it for | One app / local dev, one shared bearer token | Many apps or people sharing your provider keys |
+| Keys | Single optional `--api-key` | Per-app hub keys, revocable, hashed at rest |
+| Limits | Model allowlist, per-IP rate limit | Per-key model allowlist, spend caps (day/week/month), rate limits |
+| Visibility | Logs | Dashboard: usage, cost, latency, conversations |
+| Protocols | OpenAI chat completions, embeddings, media | OpenAI chat completions + Responses API, Anthropic Messages API (Claude Code), embeddings |
+| Extras | Server-side tools (`--sandbox`, `--web-search`), media endpoints | Analytics dashboard, `prompture-hub setup <tool>` for Claude Code / Codex / Cursor / Aider, key expiry + IP allowlists, OAuth login |
+
+Both build on the same wire-format code in `prompture.gateway` (OpenAI chat completions, OpenAI Responses, Anthropic Messages), so responses, streaming events and usage blocks are identical — and both accept `combo/`, `auto/`, `fusion/` and alias model names.
+
 ## Integrating & Extending
 
 - **FastAPI integration patterns** (AsyncAgent + tools, SSE streaming, structured endpoints, error handling) — see [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md#integrating-prompture-into-your-project)

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/prompture/__init__.py

@@ -107,6 +107,20 @@ from .refusal import (
     RefusalResult,
     is_refusal,
 )
+from .resilience import (
+    AllTargetsFailedError,
+    AsyncResilientDriver,
+    ResilientDriver,
+    RetryPolicy,
+    async_resilient,
+    classify_error,
+    explain_route,
+    load_combos,
+    register_combo,
+    register_key_pool,
+    register_model_alias,
+    resilient,
+)
 from .security import (
     InjectionCategory,
     InjectionResult,

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.12.2.dev1'
-__version_tuple__ = version_tuple = (1, 12, 2, 'dev1')
+__version__ = version = '1.12.3.dev1'
+__version_tuple__ = version_tuple = (1, 12, 3, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.12.2.dev1 → prompture-1.12.3.dev1}/prompture/cli/cli.py

@@ -200,6 +200,41 @@ def test_suite(specfile: str, providers: str | None, models: str | None, fmt: st
         click.echo(json.dumps(report, indent=2, ensure_ascii=False))
 
 
+@cli.command()
+@click.option("--host", default=None, help="Bind host (default 127.0.0.1, or HUB_HOST).")
+@click.option("--port", default=None, type=int, help="Bind port (default 1984, or HUB_PORT).")
+def hub(host: str | None, port: int | None) -> None:
+    """Launch prompture-hub: gateway + dashboard with scoped keys and spend caps.
+
+    Needs the companion package: pip install "prompture[hub]".
+    Unlike `prompture serve`, the hub keeps provider keys server-side, issues
+    per-app keys with model allowlists, spend caps and rate limits, and
+    records every call in a dashboard.
+    """
+    import os
+
+    try:
+        from prompture_hub.main import cli as hub_cli
+    except ImportError:
+        raise click.ClickException(
+            "prompture-hub is not installed. Install it with:\n\n"
+            '    pip install "prompture[hub]"\n\n'
+            "or run the lightweight single-key server instead: prompture serve"
+        ) from None
+
+    if host:
+        os.environ["HUB_HOST"] = host
+    if port:
+        os.environ["HUB_PORT"] = str(port)
+    try:
+        from prompture_hub.settings import get_settings
+
+        get_settings.cache_clear()
+    except (ImportError, AttributeError):
+        pass
+    hub_cli()
+
+
 @cli.command()
 @click.option("--model", default="openai/gpt-4o-mini", help="Default model string (provider/model).")
 @click.option("--system-prompt", default=None, help="System prompt injected when the client doesn't supply one.")