minima-cli 0.9.0__tar.gz → 0.11.0__tar.gz

{minima_cli-0.9.0 → minima_cli-0.11.0}/.env.example

@@ -77,21 +77,6 @@ MINIMA_LATENCY_MIN_N=3
 # Affects the "estimate" cost basis only.
 MINIMA_DIFFICULTY_OUTPUT_MULTIPLIERS={"trivial": 0.5, "easy": 0.75, "medium": 1.0, "hard": 1.5, "expert": 2.0}
 
-# --- Cheap-LLM reasoner (recommend-only); set provider=anthropic|gemini + the matching key ---
-# Requires the provider extra: `uv sync --extra reasoner-anthropic` and/or `--extra reasoner-gemini`.
-MINIMA_REASONER_PROVIDER=none
-MINIMA_REASONER_MODEL=
-MINIMA_REASONER_TIMEOUT_MS=15000
-# Output cap. Gemini 3.x reasons before emitting JSON; <4096 can truncate the response.
-MINIMA_REASONER_MAX_TOKENS=4096
-MINIMA_REASONER_BLEND=0.5
-# Adaptive blend: weight the LLM's estimate by how thin the deterministic evidence is
-# (cold candidates lean on the LLM; well-evidenced ones barely move). false = fixed blend.
-MINIMA_REASONER_BLEND_ADAPTIVE=true
-MINIMA_REASONER_BLEND_MAX=0.8
-MINIMA_REASONER_CLASSIFY=true
-ANTHROPIC_API_KEY=
-GEMINI_API_KEY=
 
 # --- Selection-bias correction (inverse propensity weighting) ---
 MINIMA_IPW_ENABLED=true
@@ -114,7 +99,6 @@ MINIMA_CATALOG_REFRESH_SECONDS=21600
 MINIMA_CATALOG_STALE_AFTER_SECONDS=86400
 MINIMA_LITELLM_PRICES_URL=https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
 MINIMA_OPENROUTER_MODELS_URL=https://openrouter.ai/api/v1/models
-OPENROUTER_API_KEY=
 
 # --- Service ---
 MINIMA_HOST=0.0.0.0

{minima_cli-0.9.0 → minima_cli-0.11.0}/.github/workflows/prod.yml

@@ -88,8 +88,8 @@ jobs:
             --network=${{ env.NETWORK }} \
             --subnet=${{ env.SUBNET }} \
             --vpc-egress=private-ranges-only \
-            --set-env-vars="MUBIT_ENDPOINT=https://api.mubit.ai,MUBIT_TRANSPORT=http,MINIMA_RECALL_MODE=agent_routed,MINIMA_LOG_LEVEL=info,MINIMA_RECOMMENDATION_STORE=cloudsql,MINIMA_RECSTORE_BACKEND=redis,MINIMA_REASONER_PROVIDER=gemini,MINIMA_REASONER_MODEL=gemini-3.5-flash" \
-            --set-secrets="GEMINI_API_KEY=minima-prod-gemini-key:latest,ANTHROPIC_API_KEY=minima-prod-anthropic-key:latest,OPENROUTER_API_KEY=minima-prod-openrouter-key:latest,MINIMA_DATABASE_URL=minima-prod-db-url:latest,MINIMA_REDIS_URL=minima-prod-redis-url:latest" \
+            --set-env-vars="MUBIT_ENDPOINT=https://api.mubit.ai,MUBIT_TRANSPORT=http,MINIMA_RECALL_MODE=agent_routed,MINIMA_LOG_LEVEL=info,MINIMA_RECOMMENDATION_STORE=cloudsql,MINIMA_RECSTORE_BACKEND=redis" \
+            --set-secrets="OPENROUTER_API_KEY=minima-prod-openrouter-key:latest,MINIMA_DATABASE_URL=minima-prod-db-url:latest,MINIMA_REDIS_URL=minima-prod-redis-url:latest" \
             --quiet
 
       - name: Print service URL

{minima_cli-0.9.0 → minima_cli-0.11.0}/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to Minima are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.11.0] - 2026-07-16
+
+The learning-loop rework: honest labels in, fabricated ones out, and a posterior
+that actually accumulates. Verified end-to-end against Mubit v0.12.0 (locally
+built and the deployed instance) before release.
+
+### Changed
+- **Truth rule across the wire** — quality is nullable everywhere; feedback carries
+  `evidence_source` (`gate` | `judge` | `human` | `none`) as the provenance of the
+  quality signal (the legacy `judged`/`verified_in_production` flags still map);
+  unlabeled turns and infra failures (`error_cause="infra"`) are cost/latency
+  telemetry only — they never touch the success aggregate, reinforcement, or
+  calibration. The fabricated 0.9-quality default is gone.
+- **Ground truth and honest labels are the default** — the GT verification spine is
+  ON (`MINIMA_TUI_GROUND_TRUTH=0` opts out); green gate verdicts are the label
+  source for gated turns, a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15%)
+  labels a slice of the rest, and judge spend stays booked to the session wallet.
+- **Accumulating evidence** — the durable (cluster, model) record is a
+  read-modify-write upsert carrying outcome counters and sample rings, so organic
+  evidence no longer caps at n≈1 and one failure can't erase history. Recall embeds
+  the same gist text the write path stores, and a budgeted keyed lookup
+  (`/v2/core/lookup`, `evidence_only` recall) gives an exact-match evidence channel
+  (pairs with Mubit v0.12.0, now live).
+- **Thompson sampling is the default selection policy** — calibrated posterior
+  sampling with a capped explore share (`minima_selection_policy=argmin` or
+  `minima_argmin_orgs` opt out). The selection zoo (collapse guard, epsilon,
+  exploration bonus, shadow UCB, evidence-mass IPW) is deleted, and
+  `GET /v1/policy-value` reports doubly-robust regret-vs-oracle.
+- **Benchmark-derived catalog priors** replace hand-tuned capability numbers;
+  cross-generation seed aliasing is deleted (no more crediting 2024 outcomes to
+  2026 model ids); `minima-seed` defaults to the synthetic pack.
+- **The pre-decision LLM reasoner is deleted** — escalation is diagnostic-only
+  (`escalation_suggested:*` warnings + decision-log reasons); the harness recovery
+  ladder owns the cascade. Config shrinks 97 → 64 settings; recommendation-store
+  I/O and calibrator refits run off the event loop; a TS-mirror contract test pins
+  the wire schemas to `packages/tui/src/minima/schemas.ts`.
+- **The harness is a reference client** — phase tags, difficulty, and
+  `chosen_effort` go on the wire; cache-boundary stickiness prefers the incumbent
+  model mid-session when the tradeoff is marginal.
+
+### Added
+- **Typed SDK feedback** — `Usage(input_tokens, output_tokens, cost_usd, latency_ms)`
+  on `feedback()` in both clients, honest autocapture framing, and a loop quickstart
+  in the docs.
+- **Harness adapters** (`pip install "minima-cli[adapters]"`) — LiteLLM custom
+  routing strategy + realized-cost feedback logger, OpenHands `RouterLLM`, and a
+  `minima-route` CLI for shell-level integrations.
+
+### Fixed
+- **Reinforcement id-space discipline** — keyed-lookup hits carry numeric core-plane
+  node ids, which are never sent as reinforcement references anymore; the durable
+  record is the primary reference so one unresolvable neighbor can't drop the whole
+  reinforcement call (pairs with Mubit's cross-run `record_outcome` resolution fix).
+- Live-suite tests updated to the new contracts (diagnostic-only escalation,
+  deterministic asserts pinned to argmin) and adapter tests skip cleanly when the
+  frameworks are absent.
+
+## [0.10.0] - 2026-07-12
+
+### Fixed
+- **Ground-truth spine hardened end-to-end** (still opt-in via `MINIMA_TUI_GROUND_TRUTH=1`):
+  - Gate verdicts now carry the `rec_id` of the turn that minted them, so grounded
+    feedback can never be poisoned by a stale gate from an earlier prompt, and a
+    blocked step's red verdict is superseded by its retry (content-first flip
+    identity). Plans close when their last flip is verified, instead of haunting
+    every later turn.
+  - Step identity survives rewording (token-set matching), a step's baseline resets
+    when its `verify` command changes (no fabricated red→green), and resuming a run
+    re-adopts its active plan.
+  - Bash writes and sub-agent writes are attributed to the run; unattributed
+    ("blind") writes cap confidence at 🟡 instead of silently passing.
+  - Check runner: verify commands run in their own process group and are killed as a
+    group on timeout/abort (no orphaned children), run under a minimal env allowlist,
+    and honor `MINIMA_TUI_CHECK_TIMEOUT`.
+  - `/plan` council: injected findings are fenced as untrusted data, the whole plan
+    turn aborts cleanly on Esc (partial research kept), and each council round is
+    budget-metered ($0.25/round soft cap).
+- **Default path** (no flag required): the SQLite migration runner is race-safe across
+  concurrent sessions and self-heals a previously wedged DB; a bash tool timeout/abort
+  kills the whole process group; a throwing after-hook no longer wedges the agent loop;
+  the `task` tool is blocked in plan mode.
+- Gate-focus modal: keyboard verdict overrides (approve / reject / steer with a note)
+  reach the correct gate, and the TUI footer/overlay no longer overflow on narrow
+  terminals.
+
+### Added
+- With `MINIMA_LLM_JUDGE=1`, judge grading spend is now booked to the session wallet —
+  visible in `/cost` (as `judge overhead`), the footer, and enforced by `--budget` —
+  while staying out of feedback's `actual_cost_usd` so the cost model Minima learns
+  from stays clean.
+
 ## [0.9.0] - 2026-07-10
 
 ### Added

{minima_cli-0.9.0 → minima_cli-0.11.0}/CLAUDE.md

@@ -58,7 +58,7 @@ bun run build     # -> dist/minima native binary (bun build --compile)
 Python (`src/minima`):
 
 - `from __future__ import annotations` at the top of every module.
-- Pydantic v2 `BaseModel` for serializable schemas; `@dataclass(slots=True)` for internal types; `StrEnum` for enums; `Protocol` for seams (`Memory`, `Reasoner`, `QualityJudge`).
+- Pydantic v2 `BaseModel` for serializable schemas; `@dataclass(slots=True)` for internal types; `StrEnum` for enums; `Protocol` for seams (`Memory`, `QualityJudge`).
 - Async-first. Bridge sync SDKs (Mubit) off the event loop via `anyio`/threadpools.
 - Logging: `structlog` via `get_logger("minima.<sub>")`.
 - ruff `line-length=100`, target `py311`, lint set `E,F,I,UP,B,C4`. **Never break the hot path**: bookkeeping/feedback failures are logged-and-swallowed.
@@ -74,7 +74,7 @@ Request flow (`api/routers/recommend.py` → `recommender/engine.py`):
 1. **classify** (`recommender/classify.py`) — derives task features/type from the prompt (regex + signal tables).
 2. **recall** (`memory/adapter.py`) — the *only* Mubit touchpoint; pulls similar past `task → model → outcome` records using Mubit's server-side embeddings (no local embedding model).
 3. **aggregate + score** (`recommender/aggregate.py`, `score.py`) — ranks candidates by *real* cost. The cost basis is one of three tiers chosen for the whole candidate set: `estimate` (catalog prices, cold start) → `observed` (median realized $/call) → `rescaled` (this request's input priced + observed output behavior).
-4. **escalation** (`recommender/escalation.py`) — when memory is thin/conflicting, optionally consult a cheap-LLM reasoner (`llm/`, off by default, `MINIMA_REASONER_PROVIDER`).
+4. **escalation** (`recommender/escalation.py`) — DIAGNOSTIC only: thin/conflicting/tied evidence is surfaced as `escalation_suggested:*` warnings + decision-log reasons. The harness owns the cascade (its recovery ladder re-decides after a VERIFIED failure); the old pre-decision LLM reasoner was deleted.
 5. **feedback** (`api/routers/feedback.py`) — writes the outcome back to Mubit, reinforcing memory.
 
 Other packages: `catalog/` (model cost + capability priors), `tenancy/` (multi-tenant runtime — many orgs, per-org Mubit, one deployment; auth is pass-through: the client's Mubit key IS the credential), `seeding/` (`minima-seed` CLI for cold-start history), `schemas/` (Pydantic request/response models — the wire source of truth; every field must also land in the TS mirror `packages/tui/src/minima/schemas.ts`).
@@ -85,7 +85,7 @@ Everything external is behind a Protocol so it can be faked in tests. The server
 
 `MinimaAgent.promptRouted(task)` = **route** (`src/minima/router.ts` → `POST /v1/recommend`) → **run** (agent loop in `src/agent/`, streams the model, executes tools, before/afterToolCall hook stacks, abort via AbortSignal) → **judge** (`src/minima/judge.ts`, abstains unless `MINIMA_LLM_JUDGE=1`) → **feed back** (`POST /v1/feedback` with realized cost). Layers: `src/ai/` (multi-provider LLM API + `faux` test provider) · `src/agent/` (loop, tools, hooks) · `src/minima/` (router, runtime, meter, budget, spawn/sub-agents, ground truth) · `src/tools/` (bash/edit/read/write/grep/todowrite/websearch…) · `src/tui/` (Ink app) · `src/db/` (SQLite spine).
 
-**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): behind `MINIMA_TUI_GROUND_TRUTH=1` (**off by default — the default path must behave exactly as before**). When on: plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this gate. Anything that changes default-path behavior does NOT belong behind guidance text — gate it on `config.groundTruth`.
+**Ground-Truth verification spine** (shipped 2026-07, `docs/ground-truth-build-guide.md`): **ON by default** since Phase 0b (opt out with `MINIMA_TUI_GROUND_TRUTH=0`). Plan steps carry `verify` shell commands, the harness runs them (baseline → done-gate red→green), verdicts land in the `gates` ledger (migrations v3–v5), a confidence tier drives the UI (🟢 glide / 🟡 flag / 🔴 stop), and grounded outcomes stamp `routing_decisions` for deterministic-over-judge feedback. Green-tier gate verdicts are the harness's honest label source (`evidence_source="gate"` — the only origin that may claim verified-in-production); a sampled LLM judge (`MINIMA_JUDGE_SAMPLE`, default 15% of ungated turns, `MINIMA_LLM_JUDGE=0` disables) labels the rest; everything else is cost/latency telemetry. `/plan` (planner persona + design council + `GROUND_TRUTH.md` output) is part of this spine. Anything gated on ground truth belongs behind `config.groundTruth`, never behind prompt text.
 
 Design principles that constrain any work in this direction:
 

{minima_cli-0.9.0 → minima_cli-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.9.0
+Version: 0.11.0
 Summary: Minima CLI: cost-aware LLM model routing — recommend cheaper models, backed by Mubit memory.
 Project-URL: Homepage, https://docs.minima.sh
 Project-URL: Documentation, https://docs.minima.sh
@@ -26,10 +26,11 @@ Requires-Dist: pydantic-settings>=2.3
 Requires-Dist: pydantic>=2.7
 Requires-Dist: structlog>=24.1
 Requires-Dist: tenacity>=8.4
+Provides-Extra: adapters
+Requires-Dist: litellm>=1.60; extra == 'adapters'
+Requires-Dist: openhands-sdk>=1.30; (python_version >= '3.12') and extra == 'adapters'
 Provides-Extra: dev
-Requires-Dist: anthropic>=0.40; extra == 'dev'
 Requires-Dist: fastapi>=0.115; extra == 'dev'
-Requires-Dist: google-genai>=0.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: psycopg2-binary>=2.9; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -38,10 +39,6 @@ Requires-Dist: redis>=5.0; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Requires-Dist: uvicorn[standard]>=0.30; extra == 'dev'
-Provides-Extra: reasoner-anthropic
-Requires-Dist: anthropic>=0.40; extra == 'reasoner-anthropic'
-Provides-Extra: reasoner-gemini
-Requires-Dist: google-genai>=0.3; extra == 'reasoner-gemini'
 Provides-Extra: seed
 Requires-Dist: datasets>=2.20; extra == 'seed'
 Requires-Dist: huggingface-hub>=0.24; extra == 'seed'

{minima_cli-0.9.0 → minima_cli-0.11.0}/client_sdk/minima_client/__init__.py

@@ -3,10 +3,11 @@
 from minima.schemas.common import Constraints, OutcomeLabel, TaskInput
 from minima.schemas.workflow import WorkflowRequest, WorkflowStep
 from minima_client import autocapture
-from minima_client.client import AsyncMinimaClient, MinimaClient
+from minima_client.client import AsyncMinimaClient, MinimaClient, Usage
 from minima_client.errors import MinimaError
 
 __all__ = [
+    "Usage",
     "AsyncMinimaClient",
     "Constraints",
     "MinimaClient",

{minima_cli-0.9.0 → minima_cli-0.11.0}/client_sdk/minima_client/autocapture.py

@@ -1,4 +1,4 @@
-"""Optional zero-code intake: route ``mubit.learn`` auto-capture into Minima's lane.
+"""Optional TRACE ENRICHMENT (not the feedback loop): mubit.learn auto-capture in Minima's lane.
 
 This is a thin, opinionated wrapper over ``mubit.learn``. Calling :func:`enable` pins
 the learn run to the same memory lane Minima recalls from (``minima:<namespace>``) and a

{minima_cli-0.9.0 → minima_cli-0.11.0}/client_sdk/minima_client/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 import httpx
@@ -45,12 +46,33 @@ def _headers(api_key: str | None) -> dict[str, str]:
     return {"Authorization": f"Bearer {api_key}"} if api_key else {}
 
 
+@dataclass(slots=True)
+class Usage:
+    """Realized per-call usage — the single biggest accuracy lever of the loop.
+
+    Report what the provider ACTUALLY billed (never echo Minima's own est_cost_usd
+    back): these numbers are what let the cost basis climb estimate -> observed ->
+    rescaled for your org.
+    """
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost_usd: float = 0.0
+    latency_ms: int | None = None
+
+
 def _feedback_request(
     recommendation_id: str,
     chosen_model_id: str,
     outcome: OutcomeLabel | str,
+    usage: Usage | None = None,
     **kwargs: Any,
 ) -> FeedbackRequest:
+    if usage is not None:
+        kwargs.setdefault("input_tokens", usage.input_tokens or None)
+        kwargs.setdefault("output_tokens", usage.output_tokens or None)
+        kwargs.setdefault("actual_cost_usd", usage.cost_usd or None)
+        kwargs.setdefault("latency_ms", usage.latency_ms)
     return FeedbackRequest(
         recommendation_id=recommendation_id,
         chosen_model_id=chosen_model_id,
@@ -132,9 +154,10 @@ class MinimaClient:
         recommendation_id: str,
         chosen_model_id: str,
         outcome: OutcomeLabel | str,
+        usage: Usage | None = None,
         **kwargs: Any,
     ) -> FeedbackResponse:
-        req = _feedback_request(recommendation_id, chosen_model_id, outcome, **kwargs)
+        req = _feedback_request(recommendation_id, chosen_model_id, outcome, usage, **kwargs)
         return FeedbackResponse.model_validate(self._post("/v1/feedback", req))
 
     def models(
@@ -254,9 +277,10 @@ class AsyncMinimaClient:
         recommendation_id: str,
         chosen_model_id: str,
         outcome: OutcomeLabel | str,
+        usage: Usage | None = None,
         **kwargs: Any,
     ) -> FeedbackResponse:
-        req = _feedback_request(recommendation_id, chosen_model_id, outcome, **kwargs)
+        req = _feedback_request(recommendation_id, chosen_model_id, outcome, usage, **kwargs)
         return FeedbackResponse.model_validate(await self._post("/v1/feedback", req))
 
     async def strategies(

minima_cli-0.11.0/client_sdk/minima_client/integrations/__init__.py

@@ -0,0 +1,6 @@
+"""Adapters that plug Minima's recommend->feedback loop into existing harnesses.
+
+Each adapter is dependency-light: the target framework is imported lazily so the
+package works without it installed. Install the frameworks to use (and test) them:
+``uv sync --extra adapters`` or ``pip install litellm openhands-sdk``.
+"""

minima_cli-0.11.0/client_sdk/minima_client/integrations/claude_code.py

@@ -0,0 +1,124 @@
+"""``minima-route`` — a tiny CLI so ANY harness (Claude Code included) can consume
+Minima's loop from shell seams.
+
+Pick a model for a task (prints the bare model id, or full JSON with ``--json``)::
+
+    model=$(minima-route recommend "refactor the auth module" \
+        --candidates claude-haiku-4-5,claude-sonnet-4-6)
+    claude --model "$model" -p "refactor the auth module"
+
+Close the loop after you ran it (realized numbers, never Minima's own estimate)::
+
+    minima-route feedback "$rec_id" "$model" success \
+        --cost 0.0042 --input-tokens 1800 --output-tokens 600 --latency-ms 9000 \
+        --source human
+
+Connection comes from ``MINIMA_URL`` (default https://api.minima.sh) and
+``MINIMA_API_KEY``/``MUBIT_API_KEY``, overridable with ``--url``/``--api-key``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from minima_client.client import MinimaClient, Usage
+
+
+def _client(args: argparse.Namespace) -> MinimaClient:
+    url = args.url or os.environ.get("MINIMA_URL") or "https://api.minima.sh"
+    key = args.api_key or os.environ.get("MINIMA_API_KEY") or os.environ.get("MUBIT_API_KEY")
+    return MinimaClient(url, api_key=key)
+
+
+def _cmd_recommend(args: argparse.Namespace) -> int:
+    constraints = (
+        {"candidate_models": [c.strip() for c in args.candidates.split(",") if c.strip()]}
+        if args.candidates
+        else None
+    )
+    with _client(args) as minima:
+        rec = minima.recommend(
+            args.task,
+            cost_quality_tradeoff=args.slider,
+            constraints=constraints,
+            namespace=args.namespace,
+        )
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "recommendation_id": rec.recommendation_id,
+                    "model_id": rec.recommended_model.model_id,
+                    "est_cost_usd": rec.recommended_model.est_cost_usd,
+                    "predicted_success": rec.recommended_model.predicted_success,
+                    "warnings": rec.warnings,
+                }
+            )
+        )
+    else:
+        print(rec.recommended_model.model_id)
+    return 0
+
+
+def _cmd_feedback(args: argparse.Namespace) -> int:
+    with _client(args) as minima:
+        resp = minima.feedback(
+            args.recommendation_id,
+            args.model,
+            args.outcome,
+            usage=Usage(
+                input_tokens=args.input_tokens or 0,
+                output_tokens=args.output_tokens or 0,
+                cost_usd=args.cost or 0.0,
+                latency_ms=args.latency_ms,
+            ),
+            quality_score=args.quality,
+            evidence_source=args.source,
+        )
+    print(json.dumps({"accepted": resp.accepted, "warnings": resp.warnings}))
+    return 0 if resp.accepted else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="minima-route", description=__doc__)
+    parser.add_argument("--url", default=None)
+    parser.add_argument("--api-key", default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    rec = sub.add_parser("recommend", help="print the model Minima recommends for a task")
+    rec.add_argument("task")
+    rec.add_argument("--candidates", default=None, help="comma-separated model ids")
+    rec.add_argument("--slider", type=float, default=None, help="cost/quality 0..10")
+    rec.add_argument("--namespace", default=None)
+    rec.add_argument("--json", action="store_true", help="full JSON incl. recommendation_id")
+    rec.set_defaults(func=_cmd_recommend)
+
+    fb = sub.add_parser("feedback", help="report the realized outcome back")
+    fb.add_argument("recommendation_id")
+    fb.add_argument("model")
+    fb.add_argument("outcome", choices=["success", "partial", "failure"])
+    fb.add_argument("--cost", type=float, default=None, help="realized USD (never the estimate)")
+    fb.add_argument("--input-tokens", type=int, default=None)
+    fb.add_argument("--output-tokens", type=int, default=None)
+    fb.add_argument("--latency-ms", type=int, default=None)
+    fb.add_argument("--quality", type=float, default=None, help="0..1 if you graded it")
+    fb.add_argument(
+        "--source",
+        default="human",
+        choices=["gate", "judge", "human", "none"],
+        help="label provenance (none = cost telemetry only)",
+    )
+    fb.set_defaults(func=_cmd_feedback)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

minima_cli-0.11.0/client_sdk/minima_client/integrations/litellm_router.py

@@ -0,0 +1,203 @@
+"""LiteLLM adapter: Minima as a custom routing strategy + a feedback logger.
+
+Usage::
+
+    import litellm
+    from litellm import Router
+    from minima_client import MinimaClient
+    from minima_client.integrations.litellm_router import (
+        MinimaFeedbackLogger,
+        MinimaRoutingStrategy,
+    )
+
+    router = Router(model_list=[...])            # your deployments as usual
+    minima = MinimaClient("https://api.minima.sh", api_key="<mubit-key>")
+    strategy = MinimaRoutingStrategy(minima, router)
+    router.set_custom_routing_strategy(strategy)
+    litellm.callbacks = [MinimaFeedbackLogger(minima, strategy)]
+
+Every ``router.completion(model="my-group", ...)`` then asks Minima which deployment
+to run, and the logger reports realized cost back. Without a quality signal the
+feedback is COST TELEMETRY only (``evidence_source="none"``) — pass ``quality_fn``
+to grade responses and make the outcomes teach the success posterior too.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+from litellm.integrations.custom_logger import CustomLogger
+from litellm.router import CustomRoutingStrategyBase
+
+_CORRELATION_CAP = 512
+
+
+def _task_text(messages: list[dict[str, str]] | None, fallback: str) -> str:
+    for message in reversed(messages or []):
+        if message.get("role") == "user" and message.get("content"):
+            return str(message["content"])
+    return fallback
+
+
+def _bare_model(litellm_model: str) -> str:
+    """'anthropic/claude-haiku-4-5' -> 'claude-haiku-4-5' (Minima catalog ids are bare)."""
+    return litellm_model.rsplit("/", 1)[-1]
+
+
+def _correlation_key(model_group: str, task: str) -> str:
+    return hashlib.sha1(f"{model_group}:{task}".encode()).hexdigest()  # noqa: S324
+
+
+class MinimaRoutingStrategy(CustomRoutingStrategyBase):
+    """Pick the deployment Minima recommends; remember the rec_id for feedback."""
+
+    def __init__(
+        self,
+        minima: Any,
+        router: Any,
+        *,
+        cost_quality_tradeoff: float | None = None,
+        namespace: str | None = None,
+    ):
+        self._minima = minima
+        self._router = router
+        self._slider = cost_quality_tradeoff
+        self._namespace = namespace
+        # (model_group, task-hash) -> (rec_id, minima_model_id, ts): the logger joins
+        # its success/failure event back to the recommendation. Bounded LRU.
+        self._pending: OrderedDict[str, tuple[str, str, float]] = OrderedDict()
+
+    # -- correlation ----------------------------------------------------------
+    def _remember(self, key: str, rec_id: str, model_id: str) -> None:
+        self._pending[key] = (rec_id, model_id, time.time())
+        self._pending.move_to_end(key)
+        while len(self._pending) > _CORRELATION_CAP:
+            self._pending.popitem(last=False)
+
+    def take_recommendation(self, model_group: str, task: str) -> tuple[str, str] | None:
+        entry = self._pending.pop(_correlation_key(model_group, task), None)
+        return (entry[0], entry[1]) if entry else None
+
+    # -- deployment selection --------------------------------------------------
+    def _deployments(self, model_group: str) -> list[dict]:
+        return self._router.get_model_list(model_name=model_group) or []
+
+    def _pick(
+        self,
+        model_group: str,
+        messages: list[dict[str, str]] | None,
+    ) -> dict | None:
+        deployments = self._deployments(model_group)
+        if not deployments:
+            return None
+        by_bare = {
+            _bare_model(str(d.get("litellm_params", {}).get("model", ""))): d
+            for d in deployments
+        }
+        task = _task_text(messages, model_group)
+        try:
+            rec = self._minima.recommend(
+                task,
+                cost_quality_tradeoff=self._slider,
+                constraints={"candidate_models": sorted(by_bare)},
+                namespace=self._namespace,
+            )
+        except Exception:  # noqa: BLE001 — routing must fail open to LiteLLM's default
+            return None
+        model_id = rec.recommended_model.model_id
+        deployment = by_bare.get(model_id)
+        if deployment is None:
+            return None
+        self._remember(_correlation_key(model_group, task), rec.recommendation_id, model_id)
+        return deployment
+
+    async def async_get_available_deployment(
+        self,
+        model: str,
+        messages: list[dict[str, str]] | None = None,
+        input: list | str | None = None,  # noqa: A002 — LiteLLM's signature
+        specific_deployment: bool | None = False,
+        request_kwargs: dict | None = None,
+    ):
+        return self._pick(model, messages)
+
+    def get_available_deployment(
+        self,
+        model: str,
+        messages: list[dict[str, str]] | None = None,
+        input: list | str | None = None,  # noqa: A002 — LiteLLM's signature
+        specific_deployment: bool | None = False,
+        request_kwargs: dict | None = None,
+    ):
+        return self._pick(model, messages)
+
+
+class MinimaFeedbackLogger(CustomLogger):
+    """Report realized cost/latency (and optional quality) back to Minima."""
+
+    def __init__(
+        self,
+        minima: Any,
+        strategy: MinimaRoutingStrategy,
+        *,
+        quality_fn: Callable[[Any], float | None] | None = None,
+    ):
+        super().__init__()
+        self._minima = minima
+        self._strategy = strategy
+        self._quality_fn = quality_fn
+
+    def _join(self, kwargs: dict) -> tuple[str, str] | None:
+        group = str(kwargs.get("model", ""))
+        task = _task_text(kwargs.get("messages"), group)
+        return self._strategy.take_recommendation(group, task)
+
+    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time) -> None:
+        joined = self._join(kwargs)
+        if joined is None:
+            return
+        rec_id, model_id = joined
+        usage = getattr(response_obj, "usage", None)
+        quality = None
+        if self._quality_fn is not None:
+            try:
+                quality = self._quality_fn(response_obj)
+            except Exception:  # noqa: BLE001 — a broken grader must not break the call
+                quality = None
+        try:
+            self._minima.feedback(
+                rec_id,
+                model_id,
+                "success" if quality is None or quality >= 0.8 else "partial",
+                quality_score=quality,
+                # No grader => honest telemetry, not a fabricated success label.
+                evidence_source="judge" if quality is not None else "none",
+                input_tokens=getattr(usage, "prompt_tokens", None),
+                output_tokens=getattr(usage, "completion_tokens", None),
+                actual_cost_usd=kwargs.get("response_cost"),
+                latency_ms=int((end_time - start_time).total_seconds() * 1000)
+                if hasattr(end_time - start_time, "total_seconds")
+                else None,
+            )
+        except Exception:  # noqa: BLE001 — feedback must never break the caller's run
+            return
+
+    async def async_log_failure_event(self, kwargs, response_obj, start_time, end_time) -> None:
+        joined = self._join(kwargs)
+        if joined is None:
+            return
+        rec_id, model_id = joined
+        try:
+            self._minima.feedback(
+                rec_id,
+                model_id,
+                "failure",
+                evidence_source="none",
+                error_cause="infra",
+            )
+        except Exception:  # noqa: BLE001
+            return