prompture 1.12.3.dev1__tar.gz → 1.12.4.dev1__tar.gz

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

@@ -73,6 +73,9 @@ Configuration is in `pyproject.toml` under `[tool.ruff]`.
 - **`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/rate_limits.py`** — `LimitSnapshot` from documented rate-limit response headers (OpenAI/Groq `x-ratelimit-*`, Anthropic `anthropic-ratelimit-*`). SDK drivers hook their httpx client (`attach_rate_limit_hook`) and wrap calls in `capture_rate_limits()`; streams read `stream.response`. Surfaces as `meta["rate_limits"]` only when headers were present. `resilience/headroom.py` feeds these into routing: `HeadroomTracker` keeps the latest snapshot per target and `RoutePlan` moves targets below `RetryPolicy.min_headroom` (default 5%) to the back (`meta["route"]["deprioritized"]`).
+- **`prompture/infra/accounts.py`** — `AccountSource` registry for balances/spend from documented endpoints (OpenRouter key, DeepSeek, Moonshot, OpenAI/Anthropic admin cost reports). `get_account_snapshots()` only calls configured sources, caches ~60s, and turns failures into `error` snapshots.
+- **`prompture/companion/`** — the companion API that desktop companions (Prompture Desk) read, shared with prompture-hub: `LiveBus` (SSE event bus, asyncio + thread subscribers), `summarize_spend` / `provider_limits` / period windows, `COMPANION_API_VERSION`. `prompture companion` runs a stdlib-only local server over the usage ledger (`LedgerSource`) on 127.0.0.1 with its URL + token in `~/.prompture/companion.json`, so no hub is needed. Usage is tagged per project via `tracker.project()` / `PROMPTURE_PROJECT`.
 - **`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.3.dev1 → prompture-1.12.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.12.3.dev1
+Version: 1.12.4.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

prompture-1.12.4.dev1/prompture/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m prompture …`` runs the ``prompture`` CLI (useful when its script isn't on PATH)."""
+
+from .cli.cli import cli
+
+if __name__ == "__main__":
+    cli()

{prompture-1.12.3.dev1 → prompture-1.12.4.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.3.dev1'
-__version_tuple__ = version_tuple = (1, 12, 3, 'dev1')
+__version__ = version = '1.12.4.dev1'
+__version_tuple__ = version_tuple = (1, 12, 4, 'dev1')
 
 __commit_id__ = commit_id = None

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

@@ -1,3 +1,4 @@
+import contextlib
 import json
 import shlex
 
@@ -200,6 +201,43 @@ 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("--port", default=0, type=int, help="Port on 127.0.0.1 (default: a free one the OS picks).")
+@click.option(
+    "--db", "db_path", default=None, type=click.Path(), help="Usage ledger (default ~/.prompture/usage/usage.db)."
+)
+@click.option(
+    "--exit-with-pid",
+    default=None,
+    type=int,
+    help="Stop when this process exits (used by apps that start the companion for themselves).",
+)
+def companion(port: int, db_path: str | None, exit_with_pid: int | None) -> None:
+    """Serve this machine's Prompture usage to desktop companions (no hub needed).
+
+    Reads the usage ledger every Prompture call writes to, plus rate-limit
+    headroom and provider account balances, and serves them on localhost with
+    the same companion API as prompture-hub. The address and a bearer token are
+    written to ~/.prompture/companion.json. If a companion is already running,
+    this prints its address and exits.
+    """
+    from ..companion import CompanionServer, LedgerSource, running_instance
+
+    existing = running_instance()
+    if existing:
+        click.echo(f"Prompture companion already running at {existing['url']} (pid {existing.get('pid')}).")
+        return
+    server = CompanionServer(LedgerSource(db_path), port=port)
+    click.echo(f"Prompture companion on {server.url} - ledger {server.ledger.db_path}")
+    click.echo("Address and token in ~/.prompture/companion.json. Ctrl+C to stop.")
+    if exit_with_pid:
+        from ..companion.server import stop_when_process_exits
+
+        stop_when_process_exits(server, exit_with_pid)
+    with contextlib.suppress(KeyboardInterrupt):
+        server.run()
+
+
 @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).")

prompture-1.12.4.dev1/prompture/companion/__init__.py

@@ -0,0 +1,47 @@
+"""The companion API: what desktop companions (e.g. Prompture Desk) read.
+
+Two servers speak it:
+
+- **prompture-hub** — the gateway, which sees every call routed through it and
+  adds keys, projects, alert rules and controls.
+- **the local companion** (``prompture companion``) — no hub needed; reports
+  this machine's Prompture usage from the usage ledger, rate-limit headroom and
+  provider account balances.
+
+This package holds what both share — the live event bus, the spend / limits
+aggregations and the API version — plus the local server itself.
+"""
+
+from .live import LiveBus, get_bus, new_request_id, sse_event, visible
+from .local import LedgerSource
+from .server import CompanionServer, read_state, running_instance
+from .summary import (
+    COMPANION_API_VERSION,
+    PERIODS,
+    UsageRow,
+    account_limits,
+    provider_limits,
+    summarize_spend,
+    window_end,
+    window_start,
+)
+
+__all__ = [
+    "COMPANION_API_VERSION",
+    "PERIODS",
+    "CompanionServer",
+    "LedgerSource",
+    "LiveBus",
+    "UsageRow",
+    "account_limits",
+    "get_bus",
+    "new_request_id",
+    "provider_limits",
+    "read_state",
+    "running_instance",
+    "sse_event",
+    "summarize_spend",
+    "visible",
+    "window_end",
+    "window_start",
+]

prompture-1.12.4.dev1/prompture/companion/live.py

@@ -0,0 +1,154 @@
+"""In-process live event bus behind a companion's ``GET /v1/live``.
+
+Producers publish an event when a call starts, produces its first token,
+changes activity and finishes. Events carry metadata only: ids, model,
+project, status, tokens, cost, timings — never prompt or completion text.
+
+The bus keeps the last :data:`RING_SIZE` events, so a client that reconnects
+with ``Last-Event-ID`` gets what it missed, and the set of in-flight calls, so
+a client that connects mid-request still sees it running. Publishing is
+thread-safe. Subscribers are either asyncio queues (FastAPI servers such as
+prompture-hub) or plain thread queues (the standard-library local server).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+import queue
+import threading
+import time
+import uuid
+from collections import deque
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+RING_SIZE = 1000
+SUBSCRIBER_QUEUE = 500
+#: In-flight entries older than this are assumed abandoned (a client that
+#: dropped a stream before the upstream call finished).
+IN_FLIGHT_TTL = 30 * 60
+
+
+@dataclass(eq=False)  # compared and hashed by identity
+class Subscriber:
+    """One stream reader. ``loop`` is set for asyncio readers, ``None`` for threads."""
+
+    queue: Any
+    loop: asyncio.AbstractEventLoop | None = None
+    overflowed: bool = False
+
+
+@dataclass
+class LiveBus:
+    ring: deque = field(default_factory=lambda: deque(maxlen=RING_SIZE))
+    in_flight: dict[str, dict[str, Any]] = field(default_factory=dict)
+    _subscribers: set = field(default_factory=set)
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+    _seq: itertools.count = field(default_factory=lambda: itertools.count(1))
+
+    def publish(self, type_: str, data: dict[str, Any]) -> dict[str, Any]:
+        event = {"type": type_, "ts": data.get("ts") or datetime.now(timezone.utc).isoformat(), **data}
+        with self._lock:
+            event["id"] = next(self._seq)
+            self.ring.append(event)
+            request_id = data.get("request_id")
+            if type_ == "request.started" and request_id:
+                self.in_flight[request_id] = {**event, "_mono": time.monotonic()}
+            elif request_id in self.in_flight and type_ in ("request.first_token", "request.activity"):
+                self.in_flight[request_id].update({k: v for k, v in data.items() if k != "request_id"})
+            elif type_ == "request.finished" and request_id:
+                self.in_flight.pop(request_id, None)
+            subscribers = list(self._subscribers)
+        for sub in subscribers:
+            if sub.loop is None:
+                self._deliver(sub, event)
+                continue
+            try:
+                sub.loop.call_soon_threadsafe(self._deliver, sub, event)
+            except RuntimeError:  # loop closed; the subscriber is gone
+                self.unsubscribe(sub)
+        return event
+
+    @staticmethod
+    def _deliver(sub: Subscriber, event: dict[str, Any]) -> None:
+        try:
+            sub.queue.put_nowait(event)
+        except (asyncio.QueueFull, queue.Full):
+            sub.overflowed = True
+
+    def subscribe(self) -> Subscriber:
+        """Subscribe from a running asyncio loop."""
+        sub = Subscriber(asyncio.Queue(maxsize=SUBSCRIBER_QUEUE), asyncio.get_running_loop())
+        with self._lock:
+            self._subscribers.add(sub)
+        return sub
+
+    def subscribe_thread(self) -> Subscriber:
+        """Subscribe from a plain thread; read with ``sub.queue.get(timeout=...)``."""
+        sub = Subscriber(queue.Queue(maxsize=SUBSCRIBER_QUEUE))
+        with self._lock:
+            self._subscribers.add(sub)
+        return sub
+
+    def unsubscribe(self, sub: Subscriber) -> None:
+        with self._lock:
+            self._subscribers.discard(sub)
+
+    def replay(self, after_id: int) -> list[dict[str, Any]]:
+        """Buffered events newer than *after_id* (oldest first)."""
+        with self._lock:
+            return [e for e in self.ring if e["id"] > after_id]
+
+    def running(self) -> list[dict[str, Any]]:
+        """Calls that started and have not finished, dropping abandoned ones."""
+        cutoff = time.monotonic() - IN_FLIGHT_TTL
+        with self._lock:
+            for rid in [rid for rid, e in self.in_flight.items() if e["_mono"] < cutoff]:
+                del self.in_flight[rid]
+            return [{k: v for k, v in e.items() if k != "_mono"} for e in self.in_flight.values()]
+
+    def last_id(self) -> int:
+        with self._lock:
+            return self.ring[-1]["id"] if self.ring else 0
+
+    def reset(self) -> None:
+        with self._lock:
+            self.ring.clear()
+            self.in_flight.clear()
+            self._subscribers.clear()
+            self._seq = itertools.count(1)
+
+
+_bus = LiveBus()
+
+
+def get_bus() -> LiveBus:
+    """The process-wide bus."""
+    return _bus
+
+
+def new_request_id() -> str:
+    return f"req_{uuid.uuid4().hex[:20]}"
+
+
+def visible(event: dict[str, Any], key_ids: Iterable[int] | None) -> bool:
+    """Whether a caller limited to *key_ids* (``None`` = all) may see *event*."""
+    if key_ids is None:
+        return True
+    key_id = event.get("key_id")
+    return key_id is None or key_id in key_ids
+
+
+def sse_event(event: dict[str, Any]) -> str:
+    """Format one event as a Server-Sent Events frame."""
+    import json
+
+    lines = []
+    if "id" in event:
+        lines.append(f"id: {event['id']}")
+    lines.append(f"event: {event['type']}")
+    lines.append("data: " + json.dumps(event, separators=(",", ":"), default=str))
+    return "\n".join(lines) + "\n\n"

prompture-1.12.4.dev1/prompture/companion/local.py

@@ -0,0 +1,153 @@
+"""The local companion's data: Prompture's own usage ledger.
+
+Every Prompture driver call on this machine is recorded in
+``~/.prompture/usage/usage.db`` (see :mod:`prompture.infra.tracker`). The
+:class:`LedgerSource` reads that file — it never writes to it — to answer the
+companion views, and :meth:`LedgerSource.tail` turns newly written rows into
+``request.finished`` live events.
+
+The ledger only knows about calls once they finish, so the local companion has
+no "running now" view; prompture-hub, which sits in the request path, does.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from ..infra.tracker import PROJECT_TAG
+from .live import LiveBus
+from .summary import UsageRow, window_start
+
+DEFAULT_LEDGER = Path.home() / ".prompture" / "usage" / "usage.db"
+#: How many recent rows are scanned for each model's latest rate-limit snapshot.
+RATE_LIMIT_SCAN = 500
+
+
+def _project(tags: str | None) -> str | None:
+    for tag in json.loads(tags) if tags else []:
+        if isinstance(tag, str) and tag.startswith(PROJECT_TAG):
+            return tag[len(PROJECT_TAG) :] or None
+    return None
+
+
+def _meta(raw: str | None) -> dict[str, Any]:
+    try:
+        value = json.loads(raw) if raw else {}
+    except ValueError:
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+class LedgerSource:
+    """Read-only view of a Prompture usage ledger."""
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        self.db_path = Path(db_path) if db_path else DEFAULT_LEDGER
+
+    def _connect(self) -> sqlite3.Connection | None:
+        if not self.db_path.exists():
+            return None
+        conn = sqlite3.connect(f"file:{self.db_path.as_posix()}?mode=ro", uri=True, timeout=5)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _query(self, sql: str, params: tuple = ()) -> list[sqlite3.Row]:
+        conn = self._connect()
+        if conn is None:
+            return []
+        try:
+            return conn.execute(sql, params).fetchall()
+        except sqlite3.OperationalError:  # table not created yet
+            return []
+        finally:
+            conn.close()
+
+    @staticmethod
+    def _row(r: sqlite3.Row) -> UsageRow:
+        meta = _meta(r["metadata"])
+        route = meta.get("route") if isinstance(meta.get("route"), dict) else {}
+        return UsageRow(
+            model=r["model_name"] or "",
+            cost_usd=float(r["cost"] or 0.0),
+            tokens=int(r["total_tokens"] or 0),
+            status="ok" if r["status"] == "success" else (r["status"] or "ok"),
+            served_by=route.get("served_by"),
+            project=_project(r["tags"]),
+        )
+
+    def rows(self, period: str = "day", now: datetime | None = None) -> list[UsageRow]:
+        """Calls in the current UTC ``period`` window."""
+        start = window_start(period, now).isoformat()
+        return [
+            self._row(r)
+            for r in self._query(
+                "SELECT model_name, cost, total_tokens, status, tags, metadata FROM usage_events WHERE timestamp >= ?",
+                (start,),
+            )
+        ]
+
+    def rate_limits(self) -> dict[str, dict[str, Any]]:
+        """Latest rate-limit snapshot per model, from recent calls' metadata."""
+        out: dict[str, dict[str, Any]] = {}
+        for r in self._query(
+            "SELECT model_name, metadata FROM usage_events WHERE metadata LIKE '%rate_limits%' "
+            "ORDER BY rowid DESC LIMIT ?",
+            (RATE_LIMIT_SCAN,),
+        ):
+            model = r["model_name"]
+            data = _meta(r["metadata"]).get("rate_limits")
+            if model and model not in out and isinstance(data, dict):
+                out[model] = data
+        return out
+
+    def last_rowid(self) -> int:
+        rows = self._query("SELECT MAX(rowid) AS last FROM usage_events")
+        return int(rows[0]["last"] or 0) if rows else 0
+
+    def events_after(self, rowid: int) -> list[tuple[int, dict[str, Any]]]:
+        """``request.finished`` payloads for rows newer than *rowid*."""
+        out = []
+        for r in self._query(
+            "SELECT rowid, id, timestamp, model_name, cost, prompt_tokens, completion_tokens, total_tokens, "
+            "elapsed_ms, status, error_message, tags, metadata FROM usage_events WHERE rowid > ? ORDER BY rowid",
+            (rowid,),
+        ):
+            meta = _meta(r["metadata"])
+            route = meta.get("route") if isinstance(meta.get("route"), dict) else {}
+            attempts = sum(1 for a in route.get("attempts", []) if a.get("outcome") in ("ok", "error")) or 1
+            out.append(
+                (
+                    int(r["rowid"]),
+                    {
+                        "request_id": r["id"],
+                        "ts": r["timestamp"],
+                        "key_id": None,
+                        "model": r["model_name"],
+                        "served_by": route.get("served_by"),
+                        "project": _project(r["tags"]),
+                        "status": "ok" if r["status"] == "success" else r["status"],
+                        "error": (r["error_message"] or "")[:200] or None,
+                        "prompt_tokens": r["prompt_tokens"],
+                        "completion_tokens": r["completion_tokens"],
+                        "cost_usd": r["cost"],
+                        "latency_ms": int(r["elapsed_ms"] or 0),
+                        "attempts": attempts,
+                        "fallback": attempts > 1,
+                        "deprioritized": route.get("deprioritized") or [],
+                    },
+                )
+            )
+        return out
+
+    def tail(self, bus: LiveBus, stop: threading.Event, interval: float = 1.0) -> None:
+        """Publish a ``request.finished`` event for every row written from now on."""
+        last = self.last_rowid()
+        while not stop.wait(interval):
+            for rowid, payload in self.events_after(last):
+                bus.publish("request.finished", payload)
+                last = rowid