mellontoken 0.1.0__tar.gz

mellontoken-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+
+# Env / secrets — NEVER commit
+.env
+.env.*
+!.env.example
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Node / frontend
+node_modules/
+dist/
+# TanStack Router generated tree (rebuilt by the vite plugin)
+frontend/src/routeTree.gen.ts
+# OpenAPI-generated client (regenerated on predev/prebuild)
+frontend/src/client/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Harvested org prompts — internal, never committed
+ORG_PROMPTS.md
+
+# Customer workload measurements — a client's call volumes and token counts, which
+# are their commercial data rather than ours. `scripts/cost_summary` reads these;
+# the format is documented in its docstring so a file can be rebuilt from a run.
+backend/workloads/

mellontoken-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: mellontoken
+Version: 0.1.0
+Summary: Client for the mellontoken gateway: ask(prompt), and it tells you what it cost.
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Provides-Extra: schema
+Requires-Dist: pydantic>=2.0; extra == 'schema'
+Description-Content-Type: text/markdown
+
+# mellontoken
+
+Client for the mellontoken gateway.
+
+```python
+import mellontoken
+
+answer = await mellontoken.ask("Summarise this tender in one line.")
+parsed = await mellontoken.ask(document_text, schema=DocExtraction)
+full   = await mellontoken.ask_full(document_text, schema=DocExtraction)
+full.cost_usd     # "0.00059550"
+full.model        # the model that actually served it
+```
+
+## Letting the gateway pick the model
+
+```python
+answer = await mellontoken.ask(prompt, model="auto")
+answer = await mellontoken.ask(prompt, model="auto", tier="high")   # bound the spend
+
+full = await mellontoken.ask_full(prompt, model="auto")
+full.route.model_slug    # what it picked
+full.route.task          # the grid row it read
+full.route.explanation   # why, in a paragraph you can argue with
+```
+
+One command. `model="auto"` makes the gateway classify the prompt on three axes
+(task, effort, capability), read the resulting grid cell, and serve the answer from
+whatever that cell names — and `ask_full` reports the decision on `Answer.route`, so
+routing is legible after the fact without a second call to ask about it.
+
+Those three classifier calls are billed, per call. They cost roughly $0.005 against
+a completion's dollars and land on the ledger as `kind=classifier` rows, so the
+spend is visible rather than hidden. **A service sending the same shape of prompt a
+thousand times should read `full.route.model_slug` once and then name that slug**:
+the decision is a property of the workload, not of each call.
+
+`tier=` bounds what the router may spend and outranks the effort classifier, because
+a tier is a statement about your budget rather than a property of the text. Set it
+per call, or once via `MELLONTOKEN_TIER`. It is only read on the `auto` path — with a
+named model it is logged as ignored rather than silently dropped.
+
+**A router that resolves nothing is not an error.** `route.model_slug` is None when
+the capability gate rejected every candidate in the cell; `ask` logs the explanation
+and falls back to `MELLONTOKEN_MODEL`, which is what the gateway's own advice is —
+keep your own model. The one case that raises is `MELLONTOKEN_MODEL=auto` as well,
+where there is no own model to keep.
+
+## Configuration
+
+From the environment:
+
+| variable | default |
+|---|---|
+| `MELLONTOKEN_BASE_URL` | `http://localhost:8000/api/v1` |
+| `MELLONTOKEN_API_KEY` | — required |
+| `MELLONTOKEN_MODEL` | `gemini-3.7-flash` (or `auto`) |
+| `MELLONTOKEN_TIER` | — (the effort classifier judges it) |
+| `MELLONTOKEN_MAX_TOKENS` | `32000` |
+| `MELLONTOKEN_TIMEOUT` | `600` |
+
+or in code:
+
+```python
+mellontoken.configure(base_url="http://gateway:8000/api/v1", api_key=key, model="gpt-5.6-luna")
+```
+
+From inside a container the host's gateway is `host.docker.internal`, not `localhost`.
+
+## What `ask` does that a bare HTTP call does not
+
+- **Sends the schema twice**, as `response_format` *and* as prompt text. The request
+  field is only honoured where the provider can enforce it; Gemini accepts a schema
+  it will then ignore, and the field names in the prompt are what stop it inventing
+  `col_idx` for `col`.
+- **Reads JSON out of a fenced reply**, and wraps a bare list under the schema's
+  single array field when that is unambiguous.
+- **Retries the shape, not the wire.** A 401/402/403/404 is final — a key, a budget,
+  a permission, a missing model — and raises immediately. A reply that did not parse
+  is retried three times.
+- **Logs the cost of every call**, which is the reason to route through the gateway
+  at all: `mellon.cost_usd` is the only per-call price any provider path reports.
+- **Resolves `model="auto"` before sending anything.** `auto` is a request for a
+  decision, not a catalogue slug, and the completion endpoint would 404 it. Resolved
+  once per `ask`, outside the retry loop: a reply that did not parse is a reason to
+  ask the same model again, not to pay three classifiers for the same decision again.
+
+## Install
+
+Built from this directory, which lives in the gateway's own repo so the client and
+the endpoint version together:
+
+    uv build            # -> dist/mellontoken-0.1.0-py3-none-any.whl

mellontoken-0.1.0/README.md

@@ -0,0 +1,93 @@
+# mellontoken
+
+Client for the mellontoken gateway.
+
+```python
+import mellontoken
+
+answer = await mellontoken.ask("Summarise this tender in one line.")
+parsed = await mellontoken.ask(document_text, schema=DocExtraction)
+full   = await mellontoken.ask_full(document_text, schema=DocExtraction)
+full.cost_usd     # "0.00059550"
+full.model        # the model that actually served it
+```
+
+## Letting the gateway pick the model
+
+```python
+answer = await mellontoken.ask(prompt, model="auto")
+answer = await mellontoken.ask(prompt, model="auto", tier="high")   # bound the spend
+
+full = await mellontoken.ask_full(prompt, model="auto")
+full.route.model_slug    # what it picked
+full.route.task          # the grid row it read
+full.route.explanation   # why, in a paragraph you can argue with
+```
+
+One command. `model="auto"` makes the gateway classify the prompt on three axes
+(task, effort, capability), read the resulting grid cell, and serve the answer from
+whatever that cell names — and `ask_full` reports the decision on `Answer.route`, so
+routing is legible after the fact without a second call to ask about it.
+
+Those three classifier calls are billed, per call. They cost roughly $0.005 against
+a completion's dollars and land on the ledger as `kind=classifier` rows, so the
+spend is visible rather than hidden. **A service sending the same shape of prompt a
+thousand times should read `full.route.model_slug` once and then name that slug**:
+the decision is a property of the workload, not of each call.
+
+`tier=` bounds what the router may spend and outranks the effort classifier, because
+a tier is a statement about your budget rather than a property of the text. Set it
+per call, or once via `MELLONTOKEN_TIER`. It is only read on the `auto` path — with a
+named model it is logged as ignored rather than silently dropped.
+
+**A router that resolves nothing is not an error.** `route.model_slug` is None when
+the capability gate rejected every candidate in the cell; `ask` logs the explanation
+and falls back to `MELLONTOKEN_MODEL`, which is what the gateway's own advice is —
+keep your own model. The one case that raises is `MELLONTOKEN_MODEL=auto` as well,
+where there is no own model to keep.
+
+## Configuration
+
+From the environment:
+
+| variable | default |
+|---|---|
+| `MELLONTOKEN_BASE_URL` | `http://localhost:8000/api/v1` |
+| `MELLONTOKEN_API_KEY` | — required |
+| `MELLONTOKEN_MODEL` | `gemini-3.7-flash` (or `auto`) |
+| `MELLONTOKEN_TIER` | — (the effort classifier judges it) |
+| `MELLONTOKEN_MAX_TOKENS` | `32000` |
+| `MELLONTOKEN_TIMEOUT` | `600` |
+
+or in code:
+
+```python
+mellontoken.configure(base_url="http://gateway:8000/api/v1", api_key=key, model="gpt-5.6-luna")
+```
+
+From inside a container the host's gateway is `host.docker.internal`, not `localhost`.
+
+## What `ask` does that a bare HTTP call does not
+
+- **Sends the schema twice**, as `response_format` *and* as prompt text. The request
+  field is only honoured where the provider can enforce it; Gemini accepts a schema
+  it will then ignore, and the field names in the prompt are what stop it inventing
+  `col_idx` for `col`.
+- **Reads JSON out of a fenced reply**, and wraps a bare list under the schema's
+  single array field when that is unambiguous.
+- **Retries the shape, not the wire.** A 401/402/403/404 is final — a key, a budget,
+  a permission, a missing model — and raises immediately. A reply that did not parse
+  is retried three times.
+- **Logs the cost of every call**, which is the reason to route through the gateway
+  at all: `mellon.cost_usd` is the only per-call price any provider path reports.
+- **Resolves `model="auto"` before sending anything.** `auto` is a request for a
+  decision, not a catalogue slug, and the completion endpoint would 404 it. Resolved
+  once per `ask`, outside the retry loop: a reply that did not parse is a reason to
+  ask the same model again, not to pay three classifiers for the same decision again.
+
+## Install
+
+Built from this directory, which lives in the gateway's own repo so the client and
+the endpoint version together:
+
+    uv build            # -> dist/mellontoken-0.1.0-py3-none-any.whl

mellontoken-0.1.0/mellontoken/__init__.py

@@ -0,0 +1,531 @@
+"""The mellontoken client. One function: `ask(prompt)`.
+
+    import mellontoken
+
+    answer = await mellontoken.ask("Summarise this tender in one line.")
+    parsed = await mellontoken.ask(text, schema=DocExtraction)
+    routed = await mellontoken.ask(text, model="auto", tier="high")   # it picks
+    cheap  = await mellontoken.ask(text, model="auto", mode="cost")   # …the cheapest
+    full   = await mellontoken.ask_full(text, schema=DocExtraction)   # + cost
+
+Everything else — the endpoint, the key, the model, the retry, the JSON repair, the
+cost line in the log — has a defensible default and lives here rather than at every
+call site.
+
+Configured from the environment (`MELLONTOKEN_BASE_URL`, `MELLONTOKEN_API_KEY`,
+`MELLONTOKEN_MODEL`, `MELLONTOKEN_TIER`, `MELLONTOKEN_MODE`) or in code with
+`configure()`. Nothing here knows about any
+particular service: this package is what several of them share, and it is versioned
+in the gateway's own repo so the client and the endpoint move together.
+
+## Why a facade at all
+
+The gateway is OpenAI-shaped, so `openai.AsyncOpenAI(base_url=...)` already works
+and needs no wrapper. What it does not do is any of the four things every caller
+ends up needing anyway: send the schema so the reply has the right field names, read
+the JSON back out of a markdown fence, retry the shape rather than the network, and
+record what the call cost. Four services doing that four times is where the bugs
+were — and each of those four was a real bug found in one afternoon.
+
+## What `ask` decides for you
+
+**A schema is sent as both a request field and prompt text.** `response_format` is
+the request field, and the gateway now forwards it — but only where the provider can
+enforce it. Gemini's is an OpenAPI subset that silently accepts a schema it will not
+honour, so the field names also go in the prompt. Belt and braces, cheaply: the
+schema is a few hundred tokens and a failed extraction is a whole call.
+
+**Retries are for the shape, not the wire.** httpx already retries nothing and the
+gateway's own errors are final (a 402 is a budget, a 401 is a key — neither improves
+on a second attempt). What is worth retrying is a reply that did not parse, which is
+a different failure with a different fix.
+
+**`model="auto"` is one command, not two.** The gateway resolves the model behind
+`/api/auto/preview` and the completion goes to whatever it picked, in a single `ask`.
+There is no public `route()`: `ask_full` already hands back the decision on
+`Answer.route`, and a second entry point for the same question would be a second
+place for `tier` handling to drift out of step. A caller that wants a decision
+*without* a completion — building a workload file for `scripts/cost_summary`, say —
+wants the HTTP endpoint, not a wrapper round it.
+
+**`tier` and `mode` are two different questions.** `tier` is how much you will
+spend; `mode` is what to optimise for once that is fixed. `mode="cost"` does not
+make a call cheaper than its tier allows — it picks the cheapest model *that tier
+admits*, so `tier="max", mode="cost"` is still a frontier model. Both are ignored
+with a named `model=`, loudly, because a caller passing either alongside a slug has
+misunderstood one of them.
+
+**Cost is logged, never returned by `ask`.** `ask` gives you the answer because that
+is what the name promises. `ask_full` gives you `Answer`, which carries the cost, the
+model that actually served it and the token counts, for when you are the one paying
+attention to that.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+from typing import TYPE_CHECKING, Any, overload
+
+import httpx
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+log = logging.getLogger("mellontoken")
+
+#: The version prefix is part of the URL. From inside a container the host's gateway
+#: is `host.docker.internal`, not `localhost`.
+BASE_URL = os.environ.get("MELLONTOKEN_BASE_URL", "http://localhost:8000/api/v1")
+API_KEY = os.environ.get("MELLONTOKEN_API_KEY") or None
+#: A catalogue slug, or `"auto"` to let the gateway's router pick one per prompt.
+#: `auto` costs three extra classifier calls a call and adds their latency, so it is
+#: opt-in rather than the default — see `route`.
+MODEL = os.environ.get("MELLONTOKEN_MODEL", "gemini-3.7-flash")
+#: The default cost band `auto` resolves within, when a call does not name one.
+#: None lets the effort classifier judge it from the text; naming one here outranks
+#: that, because a tier is a statement about what you will spend rather than a
+#: property of the prompt.
+TIER = os.environ.get("MELLONTOKEN_TIER") or None
+#: What `auto` optimises for inside the tier it lands on: `performance` (the
+#: default — the best model on the evidence), `cost` (the cheapest) or `latency`
+#: (the fastest). It reorders *within* the band and never widens it, so `cost` is
+#: the cheapest model that tier admits rather than the cheapest model there is —
+#: a `max` prompt asked for the cheapest still comes back with a frontier model.
+MODE = os.environ.get("MELLONTOKEN_MODE") or "performance"
+#: Caps reasoning *and* output together, and reasoning is spent first — a small
+#: budget on a thinking model returns `finish_reason=length` and an empty answer.
+MAX_TOKENS = int(os.environ.get("MELLONTOKEN_MAX_TOKENS", "32000"))
+#: Wall-clock cap per attempt.
+TIMEOUT = float(os.environ.get("MELLONTOKEN_TIMEOUT", "600"))
+
+_ATTEMPTS = 3
+_HTTP_OK = 200
+#: Ask the gateway to pick the model. Not a catalogue slug — `ask` resolves it to
+#: one before sending anything, so the completion request never carries this.
+AUTO = "auto"
+#: A key, a budget or a permission. None of them improves on a retry.
+_FINAL = frozenset({401, 402, 403, 404})
+
+
+def configure(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    model: str | None = None,
+    tier: str | None = None,
+    mode: str | None = None,
+    max_tokens: int | None = None,
+    timeout: float | None = None,
+) -> None:
+    """Set any of the defaults in code, for a service that does not use env vars.
+
+    Module-level rather than a client object because there is one gateway per
+    deployment and passing the same four values through every call site is the
+    ceremony this package exists to remove. Pass `model=` to a single `ask` when one
+    call wants something different.
+    """
+    global BASE_URL, API_KEY, MODEL, TIER, MODE, MAX_TOKENS, TIMEOUT  # noqa: PLW0603
+    if base_url is not None:
+        BASE_URL = base_url
+    if api_key is not None:
+        API_KEY = api_key
+    if model is not None:
+        MODEL = model
+    if tier is not None:
+        TIER = tier
+    if mode is not None:
+        MODE = mode
+    if max_tokens is not None:
+        MAX_TOKENS = max_tokens
+    if timeout is not None:
+        TIMEOUT = timeout
+
+
+class MellontokenError(RuntimeError):
+    """The gateway refused, or three replies in a row did not parse."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Route:
+    """What the router decided, and enough of the reasoning to argue with it.
+
+    `model_slug` is None when nothing survived — no grid cell to read, or the
+    capability gate rejected every candidate in it. That is an answer rather than a
+    failure, and `explanation` says which; `ask` falls back to the configured model.
+    """
+
+    #: None when nothing survived the gate. `explanation` says why.
+    model_slug: str | None
+    #: The grid row it read. `other` when no tag fit — see `task_from_fallback`.
+    task: str | None
+    #: True when `task` is the `other` fallback row rather than a reading of the
+    #: text. `other` chosen and `other` fallen back to are different claims.
+    task_from_fallback: bool
+    #: The cost band, from `tier=` if you gave one and the classifier otherwise.
+    tier: str | None
+    #: True when the tier came from you, so the effort classifier was advisory.
+    tier_from_caller: bool
+    #: Capabilities the prompt needs, e.g. `["tools", "json_mode"]`.
+    required: tuple[str, ...]
+    #: `assigned` (an operator filled that cell) | `derived` (ranked from
+    #: evidence) | `none`.
+    source: str
+    #: What the cell offered in order, before the gate.
+    shortlist: tuple[str, ...]
+    #: One paragraph you can check the decision against. Worth logging on a
+    #: surprising pick.
+    explanation: str
+    #: The classifier calls, which are billed separately from the completion.
+    input_tokens: int
+    output_tokens: int
+    latency_ms: int
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Answer:
+    """What came back, and what it cost."""
+
+    text: str
+    model: str
+    cost_usd: str
+    input_tokens: int
+    output_tokens: int
+    #: Part of `output_tokens`, billed at the output rate. Often most of it.
+    reasoning_tokens: int | None
+    finish_reason: str
+    #: Set when a `schema=` was given: the validated object.
+    parsed: Any = None
+    #: Set when the model was resolved rather than named — `model="auto"`. Carries
+    #: the classifier spend, which `cost_usd` does not: that is the completion's
+    #: price and the routing was billed separately.
+    route: Route | None = None
+
+
+def _client(base_url: str | None = None) -> httpx.AsyncClient:
+    if not API_KEY:
+        raise MellontokenError("MELLONTOKEN_API_KEY is not set")
+    return httpx.AsyncClient(
+        base_url=base_url or BASE_URL,
+        headers={"Authorization": f"Bearer {API_KEY}"},
+        timeout=TIMEOUT,
+    )
+
+
+def _api_root() -> str:
+    """`.../api/v1` -> `.../api`, for the control-plane endpoints.
+
+    The router is not part of the OpenAI-shaped surface and is deliberately not
+    versioned with it: `/v1` is a promise about a wire format somebody else defined,
+    and `/api/auto/preview` is ours. Derived rather than configured, so one env var
+    still points the client at one deployment.
+    """
+    root = BASE_URL.rstrip("/")
+    return root.removesuffix("/v1")
+
+
+def _schema_of(schema: type[BaseModel]) -> dict[str, Any]:
+    """Return a JSON schema with the two keys strict mode needs; Pydantic omits both."""
+    body = schema.model_json_schema()
+    _harden(body)
+    return {"type": "json_schema", "json_schema": {"name": schema.__name__, "schema": body, "strict": True}}
+
+
+def _harden(node: object) -> None:
+    """Close every object and require every property, in place."""
+    if isinstance(node, dict):
+        if node.get("type") == "object" and isinstance(node.get("properties"), dict):
+            node["additionalProperties"] = False
+            node["required"] = list(node["properties"])
+        for value in node.values():
+            _harden(value)
+    elif isinstance(node, list):
+        for item in node:
+            _harden(item)
+
+
+def _schema_prompt(schema: type[BaseModel]) -> str:
+    """Render the field names as prompt text, for providers that cannot enforce a schema."""
+    body = schema.model_json_schema()
+    _strip_prose(body)
+    return (
+        "\n\nReturn ONLY a JSON object matching this schema exactly — every field "
+        "name spelled as written here, no extra fields, no markdown fence:\n"
+        + json.dumps(body, ensure_ascii=False, separators=(",", ":"))
+    )
+
+
+def _strip_prose(node: object) -> None:
+    """Drop `title`/`description`, which are most of a Pydantic schema's tokens."""
+    if isinstance(node, dict):
+        node.pop("title", None)
+        node.pop("description", None)
+        for value in node.values():
+            _strip_prose(value)
+    elif isinstance(node, list):
+        for item in node:
+            _strip_prose(item)
+
+
+def _slug(picked: Route | None, model: str | None) -> str:
+    """Return the catalogue slug to send. Never the literal `"auto"`.
+
+    Order: what the router resolved, then the call's own `model=`, then the module
+    default — skipping `"auto"` wherever it appears, since it is a request for a
+    decision rather than a model and the gateway would 404 it as an unknown slug.
+    """
+    if picked is not None and picked.model_slug:
+        return picked.model_slug
+    for candidate in (model, MODEL):
+        if candidate and candidate != AUTO:
+            return candidate
+    raise MellontokenError("no model to send: both `model=` and MELLONTOKEN_MODEL are 'auto'")
+
+
+def _loads(content: str, schema: type[BaseModel]) -> object:
+    """Read JSON out of a reply, repairing the two shapes models actually return.
+
+    A ```json fence, and a bare list where the schema wants an object holding one
+    list — wrapped under that field's name, but only when the schema has exactly one
+    array field, so the guess cannot be ambiguous.
+    """
+    text = content.strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[-1] if "\n" in text else text
+        text = text.rsplit("```", 1)[0].strip()
+
+    data = json.loads(text)
+    if isinstance(data, list):
+        props = schema.model_json_schema().get("properties", {})
+        arrays = [name for name, spec in props.items() if spec.get("type") == "array"]
+        if len(arrays) == 1:
+            return {arrays[0]: data}
+    return data
+
+
+async def _preview(
+    prompt: str,
+    *,
+    tier: str | None = None,
+    mode: str | None = None,
+    label: str = "route",
+) -> Route:
+    """Ask the gateway which model this prompt should go to. `POST /api/auto/preview`.
+
+    Internal: `ask(model="auto")` is the way to reach this, and `Answer.route` is
+    where the decision comes back. There is no public `route()` — it would be a
+    second entry point for something `ask` already returns, and a caller who wants
+    the decision without a completion wants the HTTP endpoint rather than a wrapper
+    round it.
+
+    Three classifier calls — task, effort, capability — run concurrently on the
+    gateway and reduce to one grid cell. They are billed and appear on the ledger as
+    `kind=classifier` rows, so this is not free advice: roughly $0.005 a resolution
+    against a completion's dollars.
+
+    `tier` outranks the effort classifier — it is a statement about what you will
+    spend rather than a property of the text. `mode` then decides what to optimise
+    for inside whatever tier that lands on; it is omitted from the payload at its
+    default, so an older gateway that has never heard of it still answers.
+    """
+    payload: dict[str, Any] = {"prompt": prompt}
+    if tier or TIER:
+        payload["tier"] = tier or TIER
+    chosen = mode or MODE
+    if chosen and chosen != "performance":
+        payload["mode"] = chosen
+
+    async with _client(_api_root()) as http:
+        response = await http.post("/auto/preview", json=payload)
+    if response.status_code != _HTTP_OK:
+        raise MellontokenError(
+            f"{label}: gateway refused ({response.status_code}): {response.text[:300]}",
+        )
+
+    body = response.json()
+    picked = Route(
+        model_slug=body.get("model_slug"),
+        task=body.get("task"),
+        task_from_fallback=bool(body.get("task_from_fallback")),
+        tier=body.get("tier"),
+        tier_from_caller=bool(body.get("tier_from_caller")),
+        required=tuple(body.get("required") or ()),
+        source=body.get("source", "none"),
+        shortlist=tuple(body.get("shortlist") or ()),
+        explanation=body.get("explanation", ""),
+        input_tokens=int(body.get("input_tokens", 0)),
+        output_tokens=int(body.get("output_tokens", 0)),
+        latency_ms=int(body.get("latency_ms", 0)),
+    )
+    log.info(
+        "%s model=%s task=%s%s tier=%s%s source=%s in=%d out=%d %dms",
+        label, picked.model_slug, picked.task,
+        " (no tag fit)" if picked.task_from_fallback else "",
+        picked.tier, " (yours)" if picked.tier_from_caller else "",
+        picked.source, picked.input_tokens, picked.output_tokens, picked.latency_ms,
+    )
+    return picked
+
+
+async def _resolve(
+    prompt: str,
+    *,
+    model: str | None,
+    tier: str | None,
+    mode: str | None,
+    label: str,
+) -> Route | None:
+    """Route the prompt when `model` is `auto`, else None. Raises only when stuck.
+
+    Called once per `ask`, outside its retry loop: a reply that did not parse is a
+    reason to ask the same model again, not to re-run three classifiers on an
+    unchanged prompt and be billed for the same decision three times.
+
+    A router that resolves nothing is a real answer, not a failure, and the fallback
+    is what the gateway's own preview tells a caller to do — keep your own model.
+    Raising instead would make `auto` less reliable than naming a slug, which is the
+    opposite of the point. The one case with no way forward is `auto` as the module
+    default too, where there is no own model to keep.
+    """
+    if (model or MODEL) != AUTO:
+        # `tier` only means something to the router. Named model + tier is a caller
+        # who thinks they are bounding a cost and is not, so it is said out loud
+        # rather than dropped — the two arguments arriving together is the whole
+        # signal that one of them was misunderstood.
+        for name, value in (("tier", tier), ("mode", mode)):
+            if value:
+                log.warning(
+                    "%s: %s=%r ignored — it steers the router, and model=%r names a "
+                    "model outright. Pass model='auto' to use it.",
+                    label, name, value, model or MODEL,
+                )
+        return None
+
+    picked = await _preview(prompt, tier=tier, mode=mode, label=f"{label}:route")
+    if picked.model_slug is not None:
+        return picked
+
+    if MODEL == AUTO and (model is None or model == AUTO):
+        raise MellontokenError(
+            f"{label}: the router resolved no model, and there is no non-auto default "
+            f"to fall back to. {picked.explanation}",
+        )
+    log.warning("%s: router resolved nothing, falling back — %s", label, picked.explanation)
+    return picked
+
+
+async def ask_full(
+    prompt: str,
+    *,
+    system: str | None = None,
+    schema: type[BaseModel] | None = None,
+    model: str | None = None,
+    tier: str | None = None,
+    mode: str | None = None,
+    max_tokens: int | None = None,
+    label: str = "ask",
+) -> Answer:
+    """Ask, and get the answer with its cost and token counts.
+
+    `label` names the call in the log line — worth setting when a service makes
+    several kinds of call, because the log is the only per-call cost record there is.
+
+    `model="auto"` resolves the model through `route` first and reports the decision
+    on `Answer.route`. `tier` and `mode` are only read on that path: `tier` bounds
+    what the router may spend, `mode` says what to optimise for inside that bound —
+    `performance` (default), `cost` or `latency`.
+    """
+    picked = await _resolve(prompt, model=model, tier=tier, mode=mode, label=label)
+
+    messages = []
+    if system:
+        messages.append({"role": "system", "content": system})
+    messages.append({"role": "user", "content": prompt + (_schema_prompt(schema) if schema else "")})
+
+    payload: dict[str, Any] = {
+        # `picked.model_slug` when the router resolved one; never the literal
+        # `"auto"`, which the gateway would 404 as an unknown slug.
+        "model": _slug(picked, model),
+        "messages": messages,
+        "max_tokens": max_tokens or MAX_TOKENS,
+    }
+    if schema is not None:
+        payload["response_format"] = _schema_of(schema)
+
+    last: str | None = None
+    async with _client() as http:
+        for attempt in range(_ATTEMPTS):
+            response = await http.post("/chat/completions", json=payload)
+            if response.status_code in _FINAL:
+                raise MellontokenError(f"gateway refused ({response.status_code}): {response.text[:300]}")
+            if response.status_code != _HTTP_OK:
+                last = f"HTTP {response.status_code}: {response.text[:200]}"
+                log.warning("%s attempt %d %s", label, attempt + 1, last)
+                continue
+
+            body = response.json()
+            choice = body["choices"][0]
+            mellon = body.get("mellon") or {}
+            usage = body.get("usage") or {}
+            answer = Answer(
+                text=choice["message"].get("content") or "",
+                model=mellon.get("served_model", payload["model"]),
+                cost_usd=str(mellon.get("cost_usd", "?")),
+                input_tokens=int(usage.get("prompt_tokens", 0)),
+                output_tokens=int(usage.get("completion_tokens", 0)),
+                reasoning_tokens=mellon.get("reasoning_tokens"),
+                finish_reason=choice.get("finish_reason", ""),
+                route=picked,
+            )
+            log.info(
+                "%s model=%s in=%d out=%d reasoning=%s cost=$%s finish=%s",
+                label, answer.model, answer.input_tokens, answer.output_tokens,
+                answer.reasoning_tokens, answer.cost_usd, answer.finish_reason,
+            )
+            if mellon.get("refused"):
+                raise MellontokenError(f"{label}: the model refused")
+            if schema is None:
+                return answer
+
+            try:
+                return dataclasses.replace(
+                    answer, parsed=schema.model_validate(_loads(answer.text, schema))
+                )
+            except Exception as exc:  # noqa: BLE001 - json or validation, both retryable
+                # The message, not just the class: "ValidationError" three times over
+                # says nothing about which field was wrong.
+                last = f"{type(exc).__name__} (finish={answer.finish_reason}): {str(exc)[:200]}"
+                log.warning("%s attempt %d %s", label, attempt + 1, last)
+
+    raise MellontokenError(f"{label}: failed after {_ATTEMPTS} attempts: {last}")
+
+
+@overload
+async def ask(prompt: str, *, schema: type[BaseModel], **kw: Any) -> BaseModel: ...
+@overload
+async def ask(prompt: str, **kw: Any) -> str: ...
+
+
+async def ask(prompt: str, **kw: Any) -> Any:
+    """Ask, and get the answer. The whole point of this module.
+
+    Returns the reply text, or — with `schema=` — a validated instance of it. Pass
+    `model="auto"` to have the gateway pick the model; `ask_full` is the way to see
+    which one it picked.
+    """
+    answer = await ask_full(prompt, **kw)
+    return answer.parsed if kw.get("schema") is not None else answer.text
+
+
+__all__ = [
+    "AUTO",
+    "Answer",
+    "MellontokenError",
+    #: Exported as a type, not an entry point: it is what `Answer.route` holds.
+    "Route",
+    "ask",
+    "ask_full",
+    "configure",
+]

mellontoken-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "mellontoken"
+version = "0.1.0"
+description = "Client for the mellontoken gateway: ask(prompt), and it tells you what it cost."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+# Only needed for `schema=`; a caller asking for plain text does not need pydantic.
+schema = ["pydantic>=2.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mellontoken"]