minima-cli 0.12.0__tar.gz → 0.12.2__tar.gz

{minima_cli-0.12.0 → minima_cli-0.12.2}/.github/workflows/catalog-snapshot.yml

@@ -92,9 +92,22 @@ jobs:
           git checkout -B "$BRANCH"
           git add "$SNAPSHOT_PATH"
           git commit -m "chore(catalog): refresh vendored model snapshot from live /v1/models"
-          git push -u origin "$BRANCH" --force-with-lease
+          # Plain --force: this branch is automation-owned and rebuilt from main every
+          # run, and the fresh checkout has no remote-tracking ref for it, so
+          # --force-with-lease always fails with "stale info" once the branch exists.
+          git push -u origin "$BRANCH" --force
 
-          gh pr create --base main --head "$BRANCH" \
+          # Fail LOUD when the PR can't be opened: `|| echo` masked a hard denial
+          # ("GitHub Actions is not permitted to create ... pull requests") for days —
+          # green runs, branch pushed, no PR, nobody the wiser. An existing open PR is
+          # the only benign create-failure; anything else must turn the run red.
+          if ! gh pr create --base main --head "$BRANCH" \
             --title "chore(catalog): refresh vendored model snapshot" \
-            --body "Automated refresh of \`$SNAPSHOT_PATH\` from the live catalog at \`$CATALOG_URL\` (normalized to the loader's shape). Opened by \`.github/workflows/catalog-snapshot.yml\`. Review the diff — this is the cold-start fallback the server serves when the live cost feed is unreachable." \
-            || echo "PR already open for $BRANCH; pushed update."
+            --body "Automated refresh of \`$SNAPSHOT_PATH\` from the live catalog at \`$CATALOG_URL\` (normalized to the loader's shape). Opened by \`.github/workflows/catalog-snapshot.yml\`. Review the diff — this is the cold-start fallback the server serves when the live cost feed is unreachable."; then
+            if [ -n "$(gh pr list --base main --head "$BRANCH" --json number --jq '.[0].number // empty')" ]; then
+              echo "PR already open for $BRANCH; pushed update."
+            else
+              echo "::error::pushed $BRANCH but could not open its PR — likely the repo forbids Actions-created PRs (Settings → Actions → General → 'Allow GitHub Actions to create and approve pull requests')"
+              exit 1
+            fi
+          fi

{minima_cli-0.12.0 → minima_cli-0.12.2}/.github/workflows/ci.yml

@@ -67,3 +67,30 @@ jobs:
 
       - name: Typecheck
         run: bun run check
+
+  sdk-ts:
+    name: TS SDK — bun test + tsc
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/sdk
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Install deps
+        run: bun install --frozen-lockfile
+
+      - name: Test
+        run: bun test
+
+      - name: Typecheck
+        run: bun run check
+
+      - name: Lint
+        run: bun run lint

{minima_cli-0.12.0 → minima_cli-0.12.2}/.github/workflows/release-cli.yml

@@ -1,8 +1,8 @@
 name: Release — CLI binaries + Homebrew
 
 # On a published release, cross-compile the TypeScript/Bun CLI for macOS + Linux,
-# ad-hoc codesign the macOS arches, attach the tarballs to the release, and open
-# a PR to the Homebrew tap (mubit-ai/homebrew-minima) bumping the binary formula.
+# ad-hoc codesign the macOS arches, attach the tarballs to the release, and push
+# the bumped binary formula straight to the Homebrew tap (mubit-ai/homebrew-minima).
 # PyPI publishing of the Python `minima-cli` (SDK + server tooling) stays in prod.yml.
 on:
   release:
@@ -92,7 +92,7 @@ jobs:
           path: packages/tui/dist/minima-*.tar.gz
 
   publish-and-bump:
-    name: Attach assets + open tap PR
+    name: Attach assets + push tap formula
     needs: [build-macos, build-linux]
     runs-on: ubuntu-latest
     steps:
@@ -116,7 +116,12 @@ jobs:
           VER="${RELEASE_TAG#v}"
           python3 packaging/homebrew/render_formula.py --version "$VER" --dist dist --out minima.rb
           echo "----- rendered formula -----"; cat minima.rb
-      - name: Open Homebrew tap PR
+      # Direct push, not a PR: the formula PRs sat unmerged (0.11.0 AND 0.12.0 —
+      # brew served 0.10.0 until 2026-07-20), so a published release silently never
+      # reached users. The sha256s come from the just-built release artifacts, so
+      # there is nothing for a reviewer to judge that the release itself didn't
+      # already gate.
+      - name: Push formula to the tap
         env:
           GH_TOKEN: ${{ secrets.GH_PAT }}
         run: |
@@ -126,15 +131,18 @@ jobs:
           cd tap
           git config user.name "mubit-release-bot"
           git config user.email "release-bot@mubit.ai"
-          branch="bump-minima-${VER}"
-          git checkout -b "$branch"
           if git diff --quiet Formula/minima.rb; then
             echo "formula already up to date for ${VER}; nothing to do"; exit 0
           fi
           git add Formula/minima.rb
           git commit -m "minima ${VER} (prebuilt binary)"
-          git push -u origin "$branch" --force-with-lease
-          gh pr create --repo mubit-ai/homebrew-minima --base main --head "$branch" \
-            --title "minima ${VER}" \
-            --body "Automated bump to the prebuilt TypeScript/Bun binary for \`${RELEASE_TAG}\`. Replaces the Python virtualenv formula. \`brew test-bot\` validates install + \`test do\` on macOS + Linux before merge." \
-            || echo "PR already exists for ${branch}"
+          git push origin HEAD:main
+      - name: Verify the tap serves the released version
+        run: |
+          VER="${RELEASE_TAG#v}"
+          served=$(curl -fsSL "https://raw.githubusercontent.com/mubit-ai/homebrew-minima/main/Formula/minima.rb" | sed -n 's/^ *version "\(.*\)"/\1/p' | head -1)
+          if [ "$served" != "$VER" ]; then
+            echo "::error::tap serves ${served:-nothing} but the release is ${VER}"
+            exit 1
+          fi
+          echo "tap serves ${served}"

{minima_cli-0.12.0 → minima_cli-0.12.2}/CHANGELOG.md

@@ -4,6 +4,96 @@ 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.12.2] - 2026-07-20
+
+The memory spine: the SQLite ledger starts feeding decisions. Ten PRs across the
+harness and server (#175–#184) — curated cross-session memory, a background
+curator, recall track records on server memory, and the durable-execution +
+verification upgrades.
+
+### Added
+- **Memory ledger** (harness, default ON — `MINIMA_TUI_MEMORY=0` opts out; migration
+  v12): curated per-repo memories (`note`/`workflow`/`lesson`/`guardrail`) projected
+  into each turn's system prompt (hard-capped, pinned > gate-cited > recency; every
+  distinct injection audited so "what the model saw" is replayable). Managed via
+  `/memory` (list · add · dream · pin/confirm/reject/delete = bi-temporal invalidate).
+  The model has no memory-write tool (Letta split).
+- **Memory scribe**: the sole automated memory writer — signals mined from the ledger
+  (gate flips, verified failures, user corrections, judge/gate disagreements — never
+  the transcript), recurrence-gated, one extraction call routed through Minima
+  (`tags=["memory:extract"]`, spend booked like judge spend), mem0-style
+  reconciliation (rejected rows never resurrected), provenance activation (only
+  gate-cited candidates auto-activate). Runs as crash-safe persisted jobs.
+- **Memory dream** (`/memory dream`): deterministic offline consolidation — only
+  green-gated closed plans distill into `workflow` candidates (always pending, never
+  mutates existing rows). Confirmed workflows enable **replay-with-cheap**: matching
+  prompts route with `tags=["procedure:known"]` so Thompson learns the cheaper
+  frontier for known-procedure work organically.
+- **Recall track** (server, schema v5): every trusted-label feedback casts a vote on
+  the durable records recalled into that decision; bad-track records are down-weighted
+  (floor 0.25) and eventually tombstoned (`invalidated_at`, never deleted;
+  `recall_invalidated_skipped:<n>` recommend warning). `MINIMA_RECALL_VOTE_MIN_N` /
+  `MINIMA_RECALL_INVALIDATE_RATE`.
+- **Planning critic** (advisory, at `/plan` finalize) + **zero-context diff reviewer**
+  (at plan closure; an objection can yellow the plan tier, never green it).
+  `MINIMA_TUI_PLAN_CRITIC=0` / `MINIMA_TUI_DIFF_REVIEW=0` opt out.
+- **Auto-gates**: repo manifests mined for trusted-by-construction check commands at
+  `/plan` finalize — fast command (typecheck/lint) on verify-less steps, full test
+  suite on the final step. `MINIMA_TUI_AUTO_GATES=0` opts out.
+- **Version stamps + blob tier** (migration v13): decisions/gates record
+  `harness_version` + a toolset hash (resume warns on skew, never blocks); >16KB tool
+  results spill to content-addressed blob files.
+- **Resume re-verify**: resuming re-runs the in-progress step's verify against its
+  recorded baseline (consent-gated) — divergence re-baselines from reality with a 🟡
+  banner; the resumed run's provider session id is reused for prompt-cache continuity.
+- **Ladder v2**: named rung states (`retry_step`/`revise_step`/`replan`) on recovery
+  gates + feedback notes; repeated verified failures unlock full failing-check output
+  in the retry prompt.
+- **Honest meter**: KV-cache hit rate and cost-of-pass (labeled successes only, with
+  coverage disclosure) in `/cost`.
+
+## [0.12.1] - 2026-07-20
+
+SDK integrity + a standalone TypeScript SDK. Server wire contract unchanged; all
+changes are client-side and release-pipeline hardening.
+
+### Added
+- **`@mubit-ai/minima-sdk`** (`packages/sdk`) — a standalone TypeScript SDK: pure-fetch
+  typed `/v1/*` client with zero runtime dependencies (Node 18+/Deno/Bun/edge), full
+  surface including `policyValue()`, typed feedback options, transparent feedback
+  retries, and rate-limit-aware errors. Its schema mirror is pinned against the
+  Pydantic source of truth alongside the TUI's.
+- Python SDK: `capabilities()` and `policy_value()` (the doubly-robust
+  regret-vs-oracle report) on both clients; `recommend()` gains `incumbent_model_id`,
+  `max_candidates`, and `phase=` (rides as the `phase:<v>` tag); `feedback()` gains
+  typed named params (`quality_score`, `evidence_source`, `error_cause`,
+  `chosen_effort`, `iterations`); `x-minima-client`/`User-Agent` headers; feedback
+  retries with backoff on transient faults (safe under the reconcile replay guard —
+  recommend stays fail-fast); `MinimaRateLimited(retry_after)` and
+  `MinimaUnavailable` error subtypes.
+- OpenHands adapter closes the loop: realized cost/tokens/latency auto-reported as
+  `evidence_source="none"` telemetry off the selected LLM's metrics, fire-and-forget;
+  `minima_timeout` (default 5 s) bounds the hot-path recommend.
+
+### Fixed
+- **LiteLLM logger graded outcomes**: quality now maps by the loop thresholds
+  (≥ 0.8 success / ≥ 0.4 partial / else **failure** with `error_cause="quality"`) —
+  previously a judged-bad response could never be labeled a failure.
+- LiteLLM feedback calls run off the event loop (`asyncio.to_thread`) instead of
+  blocking the caller's async app for up to the client timeout per completion.
+- LiteLLM recommendation→completion correlation is exact under concurrent identical
+  prompts (`rec_id` carried in-band via request metadata; hash join kept as fallback).
+- `Usage` distinguishes "not measured" (`None`) from a real zero — 0 tokens / $0.00
+  are reported instead of dropped.
+- `minima-route feedback --source` defaults to `none` — scripted feedback no longer
+  claims human-asserted provenance by default.
+- The dead `allow_llm_escalation` parameter is removed from both Python clients (the
+  reasoner it fed was deleted in 0.11.0).
+- Release pipeline: the Homebrew formula now pushes directly to the tap on release
+  (formula PRs previously sat unmerged — brew served 0.10.0 while 0.11.0/0.12.0
+  shipped) with a serves-the-released-version verification step; the nightly catalog
+  snapshot fails loudly when it cannot open its refresh PR instead of reporting green.
+
 ## [0.12.0] - 2026-07-20
 
 The Big Plan harness: the TUI's plan workflow grows verification teeth, and the

{minima_cli-0.12.0 → minima_cli-0.12.2}/CLAUDE.md

@@ -8,7 +8,8 @@ A Python service + client SDK, and a separate TypeScript harness:
 
 - **`src/minima/`** — Minima: a **recommend-only** LLM cost-optimization service (FastAPI, Python 3.11+). It never proxies, runs, or caches an LLM call. It answers "which model should I run for this task?" and learns from the outcome you report back. Memory is backed by [Mubit](https://docs.mubit.ai) and is the *only* external dependency of the core recommender. Hosted at `api.minima.sh`; deployed from GitHub releases (publishing a release triggers the prod deploy AND the CLI binary build).
 - **`client_sdk/minima_client/`** — bundled sync + async Python client. Ships in the same wheel as `src/minima` (`minima-cli` on PyPI).
-- **`packages/tui/`** — `minima-tui`: the **active harness** — a TypeScript/Ink agent runtime + TUI run on **Bun** (`bun:sqlite`, `>=1.2`). This is the `minima` CLI users install via Homebrew (`brew tap mubit-ai/minima`). Same `route → run → judge → feedback` loop against the `/v1/*` contract, with its own SQLite persistence spine (`src/db/minima_db.ts`, event-sourced, WAL, append-only migrations) and a `BudgetLedger`. Separate toolchain — not part of the Python wheel or `uv`. The version of record is `packages/tui/package.json` (kept in lockstep with `pyproject.toml`).
+- **`packages/tui/`** — `minima-tui`: the **active harness** — a TypeScript/Ink agent runtime + TUI run on **Bun** (`bun:sqlite`, `>=1.2`). This is the `minima` CLI users install via Homebrew (`brew tap mubit-ai/minima`). Same `route → run → judge → feedback` loop against the `/v1/*` contract, with its own SQLite persistence spine (`src/db/minima_db.ts`, event-sourced, WAL, append-only migrations) and a `BudgetLedger`. Separate toolchain — not part of the Python wheel or `uv`. The version of record is `packages/tui/package.json` (kept in lockstep with `pyproject.toml` and `packages/sdk/package.json`).
+- **`packages/sdk/`** — `@mubit-ai/minima-sdk`: the standalone **TypeScript SDK** — a pure-fetch typed `/v1/*` client (no runtime deps, no Bun APIs), mirroring `client_sdk/minima_client`. Own Bun toolchain for tests/typecheck; its `src/schemas.ts` is a second copy of the wire mirror, pinned by `tests/unit/test_ts_mirror.py`.
 
 ### The Minima loop (respect this everywhere)
 
@@ -77,7 +78,7 @@ Request flow (`api/routers/recommend.py` → `recommender/engine.py`):
 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`).
+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 BOTH TS mirrors: `packages/tui/src/minima/schemas.ts` and `packages/sdk/src/schemas.ts`).
 
 Everything external is behind a Protocol so it can be faked in tests. The server stack (fastapi/uvicorn/psycopg2/redis) lives in the `[server]` extra — the core recommender + client is dependency-light on purpose.
 
@@ -87,6 +88,10 @@ Everything external is behind a Protocol so it can be faked in tests. The server
 
 **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.
 
+**Memory ledger** (Track B of the memory spine, default ON; opt out with `MINIMA_TUI_MEMORY=0`): curated cross-session memory in SQLite (`memories`/`memory_events`/`memory_jobs`, migration v12). Active + pinned rows project into each turn's system prompt for the lead agent only (hard char cap, ranked pinned > gate-cited > recency; every distinct injected set is audited as an `inject` memory_event so "what the model saw" is replayable). Managed via `/memory` (list · add · pin/confirm/reject · delete = bi-temporal invalidate, never DELETE). Only the harness/user writes memories — the model has **no memory-write tool** (Letta split); keep it that way. The **scribe** (`src/minima/memory_scribe.ts`) is the sole automated writer: a background curator fed by SQL over the ledger (gate flips, verified failures, user corrections, judge/gate disagreements — never the transcript), recurrence-gated (a pattern must recur before it earns the one LLM extraction call, which routes through Minima with `tags=["memory:extract"]` and books its spend like judge spend), reconciled mem0-style (ADD/UPDATE/NOOP; rejected rows never resurrected), and provenance-gated (only gate-cited candidates auto-activate; the rest await `/memory confirm`). Triggers (session end, 90s quiet timer, startup leftovers) only enqueue `memory_jobs` rows; a crash-safe drain runs them.
+
+**Verification extras** (E1): the **Planning Critic** (`src/minima/plan_critic.ts`, `MINIMA_TUI_PLAN_CRITIC=0` opts out) runs one cheap completion at `/plan` finalize over the approved steps + verifies — non-discriminative checks and hidden dependencies come back as advisory flags in the finalize note, never blockers. The **zero-context diff reviewer** (`src/minima/diff_review.ts`, `MINIMA_TUI_DIFF_REVIEW=0` opts out) fires when a plan closes fully completed: fresh-eyes review of the run's whole diff, no session context; an objection writes a yellow judge milestone gate (worst-tier resolution can yellow the plan, never green it; approval/skip writes nothing). Distinct from `/verify`'s refutation pass, which is ledger-briefed and re-runs checks.
+
 Design principles that constrain any work in this direction:
 
 - **State in the DB, projections in the context** — anything that must survive scroll/compaction/restart/a lying model lives in the ledger; the model sees only a compact re-injected projection.

{minima_cli-0.12.0 → minima_cli-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.12.0
+Version: 0.12.2
 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

{minima_cli-0.12.0 → minima_cli-0.12.2}/client_sdk/minima_client/autocapture.py

@@ -7,8 +7,8 @@ OpenAI/Anthropic/LiteLLM/Google-GenAI clients so every LLM call auto-ingests its
 and gets relevant lessons injected — no code changes at the call site.
 
 What this does and does NOT do:
-- It DOES land traces + lessons in Minima's lane, so they enrich the reasoner's memory
-  block (``get_context``) and Mubit's own reflection/strategy promotion.
+- It DOES land traces + lessons in Minima's lane, so they enrich Mubit's reflection/
+  strategy promotion and anything that recalls from that lane (e.g. ``/v1/strategies``).
 - It does NOT, on its own, produce Minima *outcome records* (the ``kind="outcome"``
   rows the deterministic k-NN aggregator scores), and ``mubit.learn`` never fabricates
   a success signal. To close the loop, either call :func:`feedback` (credits the

{minima_cli-0.12.0 → minima_cli-0.12.2}/client_sdk/minima_client/client.py

@@ -3,18 +3,30 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any
+from importlib import metadata as _importlib_metadata
+from typing import Any, Literal
 
 import httpx
-
+from tenacity import (
+    AsyncRetrying,
+    Retrying,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from minima.schemas.capabilities import CapabilitiesResponse
 from minima.schemas.common import Constraints, OutcomeLabel, TaskInput
 from minima.schemas.feedback import FeedbackRequest, FeedbackResponse
 from minima.schemas.models_catalog import ModelsResponse
 from minima.schemas.recommend import RecommendRequest, RecommendResponse
-from minima.schemas.savings import CalibrationResponse, SavingsResponse
+from minima.schemas.savings import CalibrationResponse, PolicyValueResponse, SavingsResponse
 from minima.schemas.strategies import StrategiesResponse
 from minima.schemas.workflow import WorkflowRequest, WorkflowResponse
-from minima_client.errors import raise_for_status
+from minima_client.errors import MinimaUnavailable, raise_for_status
+
+EvidenceSource = Literal["gate", "judge", "human", "none"]
+ErrorCause = Literal["infra", "quality"]
 
 
 def _report_params(
@@ -42,8 +54,47 @@ def _coerce_task(task: TaskLike) -> TaskInput:
     raise TypeError(f"unsupported task type: {type(task)!r}")
 
 
+def _client_version() -> str:
+    try:
+        return _importlib_metadata.version("minima-cli")
+    except _importlib_metadata.PackageNotFoundError:
+        return "0.0.0-dev"
+
+
 def _headers(api_key: str | None) -> dict[str, str]:
-    return {"Authorization": f"Bearer {api_key}"} if api_key else {}
+    version = _client_version()
+    headers = {
+        # Server-side compat gating (mirrors the TS client): new servers can
+        # version-gate response shapes on this; old servers ignore it.
+        "x-minima-client": version,
+        "user-agent": f"minima-cli/{version} (python-httpx)",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+# Feedback retries: the server's reconcile replay guard makes /v1/feedback safe to
+# retry, and a transiently lost label is a silent learning loss. Transport faults and
+# 502/503/504 retry; 4xx (including 429) surface immediately.
+_FEEDBACK_RETRY = {
+    "retry": retry_if_exception(
+        lambda exc: isinstance(exc, httpx.TransportError | MinimaUnavailable)
+    ),
+    "stop": stop_after_attempt(3),
+    "wait": wait_exponential(multiplier=0.5, max=4),
+    "reraise": True,
+}
+
+
+def _apply_phase(task: TaskInput, phase: str | None) -> TaskInput:
+    """Reference-client convention: phase rides as a `phase:<value>` tag."""
+    if not phase:
+        return task
+    tag = f"phase:{phase}"
+    if tag in task.tags:
+        return task
+    return task.model_copy(update={"tags": [*task.tags, tag]})
 
 
 @dataclass(slots=True)
@@ -52,12 +103,13 @@ class Usage:
 
     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.
+    rescaled for your org. Fields default to None (= not measured); an explicit 0 is
+    a real measurement and is reported as such.
     """
 
-    input_tokens: int = 0
-    output_tokens: int = 0
-    cost_usd: float = 0.0
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cost_usd: float | None = None
     latency_ms: int | None = None
 
 
@@ -69,10 +121,14 @@ def _feedback_request(
     **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)
+        if usage.input_tokens is not None:
+            kwargs.setdefault("input_tokens", usage.input_tokens)
+        if usage.output_tokens is not None:
+            kwargs.setdefault("output_tokens", usage.output_tokens)
+        if usage.cost_usd is not None:
+            kwargs.setdefault("actual_cost_usd", usage.cost_usd)
+        if usage.latency_ms is not None:
+            kwargs.setdefault("latency_ms", usage.latency_ms)
     return FeedbackRequest(
         recommendation_id=recommendation_id,
         chosen_model_id=chosen_model_id,
@@ -109,19 +165,22 @@ class MinimaClient:
         constraints: Constraints | None = None,
         user_id: str | None = None,
         namespace: str | None = None,
-        allow_llm_escalation: bool = True,
         explain: bool = True,
         baseline_model_id: str | None = None,
+        incumbent_model_id: str | None = None,
+        max_candidates: int = 8,
+        phase: str | None = None,
     ) -> RecommendResponse:
         req = RecommendRequest(
-            task=_coerce_task(task),
+            task=_apply_phase(_coerce_task(task), phase),
             cost_quality_tradeoff=cost_quality_tradeoff,
             constraints=constraints or Constraints(),
             user_id=user_id,
             namespace=namespace,
-            allow_llm_escalation=allow_llm_escalation,
             explain=explain,
             baseline_model_id=baseline_model_id,
+            incumbent_model_id=incumbent_model_id,
+            max_candidates=max_candidates,
         )
         return RecommendResponse.model_validate(self._post("/v1/recommend", req))
 
@@ -155,10 +214,28 @@ class MinimaClient:
         chosen_model_id: str,
         outcome: OutcomeLabel | str,
         usage: Usage | None = None,
+        *,
+        quality_score: float | None = None,
+        evidence_source: EvidenceSource | None = None,
+        error_cause: ErrorCause | None = None,
+        chosen_effort: str | None = None,
+        iterations: int | None = None,
         **kwargs: Any,
     ) -> FeedbackResponse:
+        for key, value in (
+            ("quality_score", quality_score),
+            ("evidence_source", evidence_source),
+            ("error_cause", error_cause),
+            ("chosen_effort", chosen_effort),
+            ("iterations", iterations),
+        ):
+            if value is not None:
+                kwargs.setdefault(key, value)
         req = _feedback_request(recommendation_id, chosen_model_id, outcome, usage, **kwargs)
-        return FeedbackResponse.model_validate(self._post("/v1/feedback", req))
+        for attempt in Retrying(**_FEEDBACK_RETRY):
+            with attempt:
+                return FeedbackResponse.model_validate(self._post("/v1/feedback", req))
+        raise AssertionError("unreachable")  # reraise=True guarantees the loop exits by raise
 
     def models(
         self,
@@ -196,6 +273,21 @@ class MinimaClient:
         raise_for_status(resp)
         return StrategiesResponse.model_validate(resp.json())
 
+    def capabilities(self) -> CapabilitiesResponse:
+        resp = self._client.get("/v1/capabilities")
+        raise_for_status(resp)
+        return CapabilitiesResponse.model_validate(resp.json())
+
+    def policy_value(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+    ) -> PolicyValueResponse:
+        """Regret-vs-oracle: doubly-robust policy values over reconciled decisions."""
+        resp = self._client.get("/v1/policy-value", params=_report_params(namespace, days))
+        raise_for_status(resp)
+        return PolicyValueResponse.model_validate(resp.json())
+
     def health(self) -> dict[str, Any]:
         resp = self._client.get("/v1/health")
         raise_for_status(resp)
@@ -230,19 +322,22 @@ class AsyncMinimaClient:
         constraints: Constraints | None = None,
         user_id: str | None = None,
         namespace: str | None = None,
-        allow_llm_escalation: bool = True,
         explain: bool = True,
         baseline_model_id: str | None = None,
+        incumbent_model_id: str | None = None,
+        max_candidates: int = 8,
+        phase: str | None = None,
     ) -> RecommendResponse:
         req = RecommendRequest(
-            task=_coerce_task(task),
+            task=_apply_phase(_coerce_task(task), phase),
             cost_quality_tradeoff=cost_quality_tradeoff,
             constraints=constraints or Constraints(),
             user_id=user_id,
             namespace=namespace,
-            allow_llm_escalation=allow_llm_escalation,
             explain=explain,
             baseline_model_id=baseline_model_id,
+            incumbent_model_id=incumbent_model_id,
+            max_candidates=max_candidates,
         )
         return RecommendResponse.model_validate(await self._post("/v1/recommend", req))
 
@@ -278,10 +373,28 @@ class AsyncMinimaClient:
         chosen_model_id: str,
         outcome: OutcomeLabel | str,
         usage: Usage | None = None,
+        *,
+        quality_score: float | None = None,
+        evidence_source: EvidenceSource | None = None,
+        error_cause: ErrorCause | None = None,
+        chosen_effort: str | None = None,
+        iterations: int | None = None,
         **kwargs: Any,
     ) -> FeedbackResponse:
+        for key, value in (
+            ("quality_score", quality_score),
+            ("evidence_source", evidence_source),
+            ("error_cause", error_cause),
+            ("chosen_effort", chosen_effort),
+            ("iterations", iterations),
+        ):
+            if value is not None:
+                kwargs.setdefault(key, value)
         req = _feedback_request(recommendation_id, chosen_model_id, outcome, usage, **kwargs)
-        return FeedbackResponse.model_validate(await self._post("/v1/feedback", req))
+        async for attempt in AsyncRetrying(**_FEEDBACK_RETRY):
+            with attempt:
+                return FeedbackResponse.model_validate(await self._post("/v1/feedback", req))
+        raise AssertionError("unreachable")  # reraise=True guarantees the loop exits by raise
 
     async def strategies(
         self,
@@ -319,6 +432,21 @@ class AsyncMinimaClient:
         raise_for_status(resp)
         return ModelsResponse.model_validate(resp.json())
 
+    async def capabilities(self) -> CapabilitiesResponse:
+        resp = await self._client.get("/v1/capabilities")
+        raise_for_status(resp)
+        return CapabilitiesResponse.model_validate(resp.json())
+
+    async def policy_value(
+        self,
+        namespace: str | None = None,
+        days: float | None = None,
+    ) -> PolicyValueResponse:
+        """Regret-vs-oracle: doubly-robust policy values over reconciled decisions."""
+        resp = await self._client.get("/v1/policy-value", params=_report_params(namespace, days))
+        raise_for_status(resp)
+        return PolicyValueResponse.model_validate(resp.json())
+
     async def health(self) -> dict[str, Any]:
         resp = await self._client.get("/v1/health")
         raise_for_status(resp)

minima_cli-0.12.2/client_sdk/minima_client/errors.py

@@ -0,0 +1,49 @@
+"""Client error types."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class MinimaError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"minima error {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class MinimaRateLimited(MinimaError):
+    """429 — the server asked us to slow down; retry_after is seconds when provided."""
+
+    def __init__(self, status: int, detail: str, retry_after: float | None = None):
+        super().__init__(status, detail)
+        self.retry_after = retry_after
+
+
+class MinimaUnavailable(MinimaError):
+    """502/503/504 — transient upstream trouble; safe to retry idempotent calls."""
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float | None:
+    raw = resp.headers.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+def raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code < 400:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail") or body.get("title") or str(body)
+    except Exception:  # noqa: BLE001
+        detail = resp.text
+    if resp.status_code == 429:
+        raise MinimaRateLimited(resp.status_code, detail, _retry_after_seconds(resp))
+    if resp.status_code in (502, 503, 504):
+        raise MinimaUnavailable(resp.status_code, detail)
+    raise MinimaError(resp.status_code, detail)

{minima_cli-0.12.0 → minima_cli-0.12.2}/client_sdk/minima_client/integrations/claude_code.py

@@ -70,9 +70,9 @@ def _cmd_feedback(args: argparse.Namespace) -> int:
             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,
+                input_tokens=args.input_tokens,
+                output_tokens=args.output_tokens,
+                cost_usd=args.cost,
                 latency_ms=args.latency_ms,
             ),
             quality_score=args.quality,
@@ -107,9 +107,12 @@ def build_parser() -> argparse.ArgumentParser:
     fb.add_argument("--quality", type=float, default=None, help="0..1 if you graded it")
     fb.add_argument(
         "--source",
-        default="human",
+        default="none",
         choices=["gate", "judge", "human", "none"],
-        help="label provenance (none = cost telemetry only)",
+        help=(
+            "label provenance; default none = cost telemetry only. Pass --source human "
+            "ONLY when a human actually verified this outcome — it counts as a real label."
+        ),
     )
     fb.set_defaults(func=_cmd_feedback)
     return parser