# Minima

> A recommendation engine for LLM model routing. Cuts token spend without losing quality — plus the minima harness, a cost-aware terminal coding agent.

import { PageHeader, Warning } from '@components'

<PageHeader />

## Python Client SDK

The `minima_client` package is the official thin, typed Python client for the hosted Minima API, plus an optional zero-code intake helper.

### Install

```bash
pip install minima-cli
```

The SDK is published on PyPI as part of [**`minima-cli`**](https://pypi.org/project/minima-cli/) — the Python package that ships the `minima_client` SDK and the Minima server tooling. It does **not** include the `minima` terminal agent: the CLI is a native binary installed with [Homebrew](/harness/installation) (`brew install mubit-ai/minima/minima`). Import the SDK as `minima_client`:

```python
from minima_client import MinimaClient, AsyncMinimaClient, MinimaError, autocapture
```

### Clients

Both `MinimaClient` (sync) and `AsyncMinimaClient` (async) share the same surface.

```python
from minima_client import MinimaClient

with MinimaClient("https://api.minima.sh", api_key="mbt_…", timeout=10.0) as minima:
    rec = minima.recommend("Summarize this incident report into 3 bullets.",
                           cost_quality_tradeoff=3)
    print(rec.recommended_model.model_id)
```

* `base_url` — the Minima API base URL (`https://api.minima.sh`).
* `api_key` — your **Mubit** API key (`mbt_…`), sent as `Authorization: Bearer <key>` and passed through to Mubit. Required.
* `timeout` — HTTP timeout in seconds.

The async client mirrors every method with `await`; use it inside FastAPI/async apps:

```python
async with AsyncMinimaClient("https://api.minima.sh", api_key="mbt_…") as minima:
    rec = await minima.recommend(task)
```

### `recommend(task, *, ...)`

Returns a `RecommendResponse`.

```python
rec = minima.recommend(
    task,                              # str | TaskInput | dict
    cost_quality_tradeoff=5.0,         # 0..10
    constraints=None,                  # Constraints | None
    user_id=None,
    namespace=None,
    allow_llm_escalation=True,
    explain=True,
    baseline_model_id=None,            # the model you'd use without Minima -> savings()
)
```

`task` is flexible:

```python
minima.recommend("plain prompt text")                       # str
minima.recommend({"task": "…", "task_type": "code"})        # dict

from minima_client import TaskInput, Constraints
minima.recommend(
    TaskInput(task="…", difficulty="hard"),
    constraints=Constraints(min_quality=0.85, max_cost_per_call=0.02),
)
```

### `recommend_workflow(req)`

Takes a `WorkflowRequest`, returns a `WorkflowResponse`.

```python
from minima_client import WorkflowRequest, WorkflowStep, TaskInput

req = WorkflowRequest(
    steps=[
        WorkflowStep(step_id="extract",
                     task=TaskInput(task="Extract entities from …",
                                    task_type="extraction")),
        WorkflowStep(step_id="reason",
                     task=TaskInput(task="Decide next action given …",
                                    task_type="reasoning", difficulty="hard")),
    ],
    cost_quality_tradeoff=4,
)
wf = minima.recommend_workflow(req)
print(wf.total_est_cost_usd, "vs", wf.total_est_cost_if_all_premium)
```

### `feedback(recommendation_id, chosen_model_id, outcome, **kwargs)`

Returns a `FeedbackResponse`. `outcome` is `"success"` | `"partial"` | `"failure"`. Pass realized numbers to power the observed/rescaled cost tiers:

```python
minima.feedback(
    rec.recommendation_id,
    rec.recommended_model.model_id,
    "success",
    quality_score=0.95,
    input_tokens=180,
    output_tokens=640,
    actual_cost_usd=0.0034,
    latency_ms=2100,
    verified_in_production=True,
    idempotency_key="…",  # optional
)
```

### `models(...)`, `strategies(...)`, `health()`

```python
catalog = minima.models(provider="anthropic", max_cost=10.0)      # ModelsResponse
strat   = minima.strategies(namespace="team-payments", max_strategies=5)
status  = minima.health()                                          # dict
```

### `savings(...)` and `calibration(...)`

The measurement layer: what Minima saved you, and whether `predicted_success` is calibrated against your reported outcomes. Both report on your account's decision ledger (see the [API reference](/api-reference/endpoints#get-v1savings) for every field).

```python
report = minima.savings(namespace="team-payments", days=30, group_by="task_type")
print(report.summary.estimated.savings_vs_premium_usd,   # generous baseline
      report.summary.estimated.savings_vs_declared_usd,  # your declared default
      report.health["feedback_coverage"])                # how much to trust "realized"

cal = minima.calibration(days=30)
for r in cal.reports:
    print(r.slice_key, r.n, r.ece, r.ece_shrunk)
for flag in cal.drift_flags:
    print(flag.cluster, flag.model_id, flag.direction)   # sustained prediction drift
```

Pass `baseline_model_id` on `recommend()` and realized `actual_cost_usd` on `feedback()` to turn the savings report from an estimate into a measurement.

### Errors

Non-2xx responses raise `MinimaError` (which carries the problem+json detail):

```python
from minima_client import MinimaError

try:
    rec = minima.recommend(task)
except MinimaError as exc:
    # fall back to a default model
    ...
```

***

### Zero-code intake: `autocapture`

`minima_client.autocapture` is a thin wrapper over `mubit.learn`. Calling `enable()` pins a learn session to the same memory lane Minima recalls from (`minima:<namespace>`) and monkeypatches your OpenAI/Anthropic/LiteLLM/Google-GenAI clients, so every LLM call auto-ingests its trace — no code changes at the call site. Requires `mubit-sdk`.

```python
from minima_client import autocapture

autocapture.enable(
    api_key="<mubit-key>",
    endpoint="https://api.mubit.ai",
    namespace="team-payments",
    user_id="svc-router",
)

# ... your normal OpenAI/Anthropic/LiteLLM calls happen here, auto-captured ...

# mubit.learn does NOT fabricate a success signal — close the loop explicitly:
autocapture.feedback(good=True)   # or score in [-1, 1]
autocapture.disable()             # restore original client behavior
```

<Warning>
  **What autocapture does and doesn't do.** Autocapture lands traces + lessons in Minima's lane (enriching the reasoner's memory block and Mubit's reflection), but it does **not** by itself produce the `kind="outcome"` records the deterministic k-NN aggregator scores. To fully close the loop, either call `autocapture.feedback(...)` or send a quality score to `POST /v1/feedback`.
</Warning>

Other helpers:

```python
autocapture.wrap(client)                           # enrich one client instead of global patching
autocapture.capture(messages, response)            # manual ingest for raw HTTP / unsupported libs
```

See the [zero-code intake example](/sdk/examples#5-zero-code-intake).


import { PageHeader, Tip } from '@components'

<PageHeader />

## Concepts

### The problem Minima solves

LLM workflows overspend by sending every call to a top-tier model when a cheaper model would do a portion of the work just as well. Token cost is the lever; **model choice is the cheapest knob to turn**. Minima turns that knob, per task, based on what models have actually done on similar tasks before.

### Recommend-only, zero added latency

Minima **only recommends**. It does not proxy your call, execute a model, rewrite prompts, cache, or compress. You ask "which model should run this?", it answers, and you run the model yourself in your own stack. Because Minima sits *beside* your call rather than in front of it, it adds **zero latency to the actual LLM request**. The only Minima round-trip is the recommendation lookup (typically \~100–300ms).

### The loop

```
        ┌─────────────────────────────────────────────────────────┐
        │                                                           │
        ▼                                                           │
  POST /v1/recommend  ──▶  you run the model  ──▶  POST /v1/feedback
   (recall + rank)          (your stack)            (write outcome,
                                                     reinforce memory)
        ▲                                                           │
        │              memory gets sharper for next time           │
        └───────────────────────────────────────────────────────-─┘
```

1. **Recommend.** Minima recalls similar past `task → model → outcome` records from Mubit, aggregates each candidate model's empirical success rate, combines it with cost and capability priors, and returns the cheapest model expected to clear a quality bar.
2. **Run it yourself.** Minima hands back a `recommendation_id`; you run the recommended model.
3. **Feed back.** You report the outcome and a quality score. Minima writes the outcome to Mubit, reinforces the exact memories that drove the decision, and (on strong verified-in-production results) promotes a durable lesson.

### Why memory

The recommendation engine is **non-parametric k-NN over history**: recall similar past records, aggregate per-model success, pick the cheapest model clearing a threshold. Minima is backed by [Mubit](https://mubit.ai), which provides that substrate — semantic recall over server-side embeddings, per-entry reinforcement with a Bayesian reliability estimate, lesson promotion, and strategy surfacing for explainability. You don't operate any of it; it's part of the hosted service.

### The recommendation algorithm

For each request Minima:

1. **Classifies** the task. It uses your `task_type` / `difficulty` hints if given; otherwise a fast heuristic infers them. If the heuristic is uncertain and escalation is allowed, the cheap-LLM reasoner can refine the classification. From this it derives a *task cluster* (e.g. `code:hard`).

2. **Selects candidates.** It starts from the full model catalog, applies your constraint filters (`candidate_models`, `allowed_providers`, `excluded_models`, `require_prompt_caching`, `require_context_window`), pre-ranks by capability prior, and caps to `max_candidates`.

3. **Recalls** similar past outcome records scoped to your account (and `namespace`, if set), with a hard timeout. On timeout or no history, it falls back to the prior-only path.

4. **Aggregates per model.** Each recalled neighbor is weighted by `similarity × reliability × staleness_decay`, then combined into a Beta-smoothed empirical success rate per candidate (so models with no neighbors fall back to their capability prior, not to 0.5). An inverse-propensity weighting step corrects for the selection bias that you've historically sent certain task types to certain models.

5. **Scores** each candidate by combining predicted success with estimated cost (see **Cost-basis tiers** below). The slider sets a quality threshold `τ`.

6. **Optimizes.** Among models predicted to clear `τ`, it recommends the **cheapest** (tie-break: higher success, then higher confidence). If none clear `τ`, it recommends the highest-predicted-success model and warns `no_model_meets_threshold`. A `fallback_model` is chosen as a more reliable retry target.

7. **Escalates** to a cheap-LLM reasoner when evidence is thin or conflicting — see below.

### The cost/quality slider

`cost_quality_tradeoff` (0–10, default 5) maps to a quality threshold:

```
τ = τ_min + (cost_quality_tradeoff / 10) × (τ_max − τ_min)
```

with `τ_min = 0.55` and `τ_max = 0.92` by default. **0 means "cheapest model that's acceptable"; 10 means "highest quality regardless of cost".** A request's `min_quality` constraint raises the floor. The slider also shifts the ranking weight between predicted success and normalized cost.

### Cost-basis tiers (estimate → observed → rescaled)

The single most important accuracy mechanism. A flat token estimate assumes a fixed output length, so it **ignores reasoning/thinking tokens** — which mis-ranks a model with cheap list prices but heavy internal reasoning. Minima ranks candidates by what they *really* cost.

One basis is chosen for the **whole candidate set** so all costs are compared like-for-like (`choose_cost_basis`), preferring the most grounded tier every candidate supports:

| Tier         | Used when                                                        | How cost is computed                                                                                                          | Breakdown key                   |
| ------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| **rescaled** | every candidate has enough observations carrying `output_tokens` | `this_request_input_tokens × input_price + observed_median_output_tokens × output_price` — size-exact **and** reasoning-aware | `rescaled`, `obs_output_tokens` |
| **observed** | every candidate has enough realized `cost_usd` observations      | robust similarity-weighted **median** of realized `cost_usd` per call                                                         | `observed_avg`                  |
| **estimate** | cold start                                                       | `input_tokens × input_price + output_tokens × output_price`, using the request's expected tokens or per-task-type defaults    | `input`, `output`               |

A small minimum number of observations per candidate (default 3) gates the observed and rescaled tiers. The chosen basis is reflected in each `RankedModel.est_cost_breakdown`, and the rationale tags the number `obs` (grounded) or `est` (cold). The realized `cost_usd` / `input_tokens` / `output_tokens` come from your `POST /v1/feedback` calls — so the more you feed back, the more the ranking climbs from estimate → observed → rescaled.

<Tip>
  The **median** (not mean) makes the observed/rescaled tiers robust to outlier calls. The weight is similarity-only (not staleness-decayed) because cost is an objective fact about a model, not a quality signal that should fade.
</Tip>

### Escalation to a cheap-LLM reasoner

When deterministic evidence is thin or conflicting, Minima can consult a cheap LLM (an inexpensive reasoning model such as Anthropic Haiku or Gemini Flash). It fires only when `allow_llm_escalation` is true **and** any of:

* **thin evidence** — too little recalled history overall, or too few candidate models with any neighbor;
* **low confidence** — the recommended model's neighborhood confidence is too low;
* **conflict/tie** — the top two candidates' scores are within a small margin.

On trigger, Minima builds a memory context block, asks the reasoner to rank the candidates with structured output, and **blends** the reasoner's predicted success with the deterministic one. On any reasoner error or parse failure it falls back to the deterministic result and warns `reasoner_failed`. The reasoner is the explicit slow tier and never touches your real LLM call.

`decision_basis` on the response tells you which path won: `memory`, `prior`, or `llm`.

### How it gets better over time

| Phase                  | What's happening                                                                                                                            | Typical `decision_basis`    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Cold start (day 0)** | no history; leans on capability priors and flat estimates; reasoner fires often                                                             | `prior` (with `cold_start`) |
| **Warming up**         | `/feedback` outcomes cross `MIN_N`; cost basis climbs estimate → observed → rescaled; reasoner fires less                                   | mix of `memory` and `prior` |
| **Mature**             | dense history; most picks are empirical; reflection has promoted durable lessons; selection bias in your routing history has been corrected | mostly `memory`             |

New accounts start with a baseline of benchmark-derived history so picks are useful from day one; it's progressively dominated by your own `/v1/feedback` outcomes as they accumulate — seeded evidence is explicitly down-weighted and crowded out as live outcomes arrive, and every outcome's influence decays with age (a result from last month counts less than one from yesterday), so the recommender tracks how models behave **now**.

### Measuring it

Every recommendation is logged with its counterfactual cost baselines and reconciled with the outcome you report — so the two questions that matter are answerable from your own traffic, not from a benchmark:

* **Did it save money?** [`GET /v1/savings`](/api-reference/endpoints#get-v1savings) reports estimated and realized savings against two explicitly-labeled baselines: the most expensive scored candidate (generous) and your own declared default (`baseline_model_id` — honest). It also reports `feedback_coverage`, the share of recommendations that ever received feedback — the number that tells you how much weight the realized figures can bear.
* **Are the predictions honest?** [`GET /v1/calibration`](/api-reference/endpoints#get-v1calibration) compares `predicted_success` at decision time against realized outcomes (expected calibration error per task type) and flags sustained drift per `(cluster, model)` — the early-warning signal for a provider silently changing a model.

Accounts can additionally opt into a small amount of bounded **exploration** (`selection_policy: epsilon_softmax`): a few percent of picks sample from the *eligible* set (never below your quality bar) instead of always taking the cheapest eligible model, which keeps evidence flowing for under-tried cheap models and makes the logged history statistically sound for off-policy analysis. Default is off — deterministic picks everywhere.

### The learning loop in detail

When `POST /v1/feedback` is called:

1. Resolve the `recommendation_id` → the recalled neighbors, cluster, and scope. (Account-scoped: an id from another account resolves to nothing, so accounts can't credit or poison each other.)
2. Upsert one durable **outcome record** per `(task cluster, model)`, carrying `cost_usd`, `input_tokens`, `output_tokens`, and `quality_score`.
3. Credit the exact recalled neighbors that drove the pick, bumping their reinforcement counters and reliability.
4. On a verified-in-production strong success, promote a durable **lesson** that feeds rule promotion.
5. Periodically reflect (after a number of feedbacks, or on any verified-prod failure) to promote run → session → account-level lessons.

### Degradation behavior

Minima is designed to keep serving when Mubit is slow or down:

| Condition                   | Behavior                                                               |
| --------------------------- | ---------------------------------------------------------------------- |
| Recall timeout              | Prior-only recommendation + `recall_timeout` warning.                  |
| Mubit unavailable           | Prior-only + `memory_unavailable`.                                     |
| Stale prices                | Last-good price snapshot used; `catalog_stale: true` + `prices_stale`. |
| Reasoner error              | Deterministic result + `reasoner_failed`.                              |
| Reasoner not configured     | Escalation surfaced as warning; deterministic result used.             |
| No models match constraints | `422 NoCandidatesError`.                                               |


import { PageHeader, Tip } from '@components'

<PageHeader />

## Examples

Copy-paste recipes against the hosted API, from a single `curl` to a production routing wrapper. Every snippet is self-contained.

<Tip>
  **Setup.** Set your key once: `export MUBIT_API_KEY=mbt_…`. The Python examples use the [`minima_client`](/sdk/client-sdk) package and read the same key. All requests go to `https://api.minima.sh`.
</Tip>

### 1. Quickstart with curl

Exercise the core endpoints with nothing but `curl` and `jq` — the fastest way to confirm your key works.

```bash
# Service health and the capabilities handshake (the two keyless endpoints)
curl -s https://api.minima.sh/v1/health | jq
curl -s https://api.minima.sh/v1/capabilities | jq

# A recommendation
REC=$(curl -s https://api.minima.sh/v1/recommend \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"task":{"task":"Classify this support ticket by urgency.","task_type":"classification"},
       "cost_quality_tradeoff":2}')
echo "$REC" | jq '.recommended_model.model_id, .decision_basis, .recommendation_id'

# Close the loop
curl -s https://api.minima.sh/v1/feedback \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' \
  -d "{\"recommendation_id\":$(echo "$REC" | jq .recommendation_id),
       \"chosen_model_id\":\"claude-haiku-4-5\",\"outcome\":\"success\",\"quality_score\":0.92}" | jq
```

### 2. The core loop

The whole value loop with the Python SDK: recommend → (you run the model) → feedback. Report realized tokens and cost so the cost ranking sharpens.

```python
from minima_client import MinimaClient

with MinimaClient("https://api.minima.sh", api_key="mbt_…") as minima:
    rec = minima.recommend(
        "Summarize this incident report into 3 bullet points.",
        cost_quality_tradeoff=3,
        baseline_model_id="claude-opus-4-8",  # what you'd use without Minima -> honest savings
    )
    print(rec.recommended_model.model_id, rec.decision_basis)

    # ... run rec.recommended_model.model_id in your own stack ...

    minima.feedback(
        rec.recommendation_id,
        rec.recommended_model.model_id,
        "success",
        quality_score=0.95,
        input_tokens=1180,
        output_tokens=320,
        actual_cost_usd=0.0028,
        verified_in_production=True,
    )
```

### 3. Constraints and the slider

Hard `Constraints` (provider whitelist, quality floor, cost ceiling, deny-list) plus sweeping `cost_quality_tradeoff` from 0→10 to watch Minima walk the cost-vs-quality frontier for the same task.

```python
from minima_client import MinimaClient, TaskInput, Constraints

task = TaskInput(task="Refactor this 200-line module for readability.", task_type="code")

with MinimaClient("https://api.minima.sh", api_key="mbt_…") as minima:
    rec = minima.recommend(
        task,
        constraints=Constraints(
            allowed_providers=["anthropic", "google"],
            min_quality=0.8,
            max_cost_per_call=0.02,
        ),
    )
    print("constrained pick:", rec.recommended_model.model_id)

    for cq in (0, 5, 10):
        r = minima.recommend(task, cost_quality_tradeoff=cq)
        print(f"slider {cq:>2}: {r.recommended_model.model_id}  "
              f"~${r.recommended_model.est_cost_usd:.4f}")
```

### 4. Multi-step workflow

`POST /v1/recommend/workflow` routes each step of a pipeline independently — a cheap model for classify/extract, a stronger one for the hard reasoning step — and reports total cost versus the all-premium baseline. Each step gets its own `recommendation_id` for per-step feedback.

```python
from minima_client import MinimaClient, WorkflowRequest, WorkflowStep, TaskInput

req = WorkflowRequest(
    steps=[
        WorkflowStep(step_id="extract",
                     task=TaskInput(task="Extract entities from the email.",
                                    task_type="extraction")),
        WorkflowStep(step_id="reason",
                     task=TaskInput(task="Decide the next action given the entities.",
                                    task_type="reasoning", difficulty="hard")),
    ],
    cost_quality_tradeoff=4,
)

with MinimaClient("https://api.minima.sh", api_key="mbt_…") as minima:
    wf = minima.recommend_workflow(req)
    for step in wf.steps:
        print(step.step_id, "→", step.recommendation.recommended_model.model_id)
    print(f"total ${wf.total_est_cost_usd:.4f} vs all-premium ${wf.total_est_cost_if_all_premium:.4f}")
```

### 5. Zero-code intake

`minima_client.autocapture` auto-captures your existing LLM calls into Minima's memory with no call-site changes — useful for backfilling history from traffic you already run. It needs a Mubit key for the underlying memory.

```python
from minima_client import autocapture

autocapture.enable(api_key="<mubit-key>", endpoint="https://api.mubit.ai",
                   namespace="team-payments", user_id="svc-router")

# ... your normal OpenAI / Anthropic / LiteLLM / Gemini calls run here, auto-captured ...

autocapture.feedback(good=True)   # learn does NOT fabricate a success signal — close it explicitly
autocapture.disable()
```

### 6. Production routing wrapper

The shape you'd ship: recommend a model, run it via the official **Anthropic SDK** (streaming, real token usage), then feed the realized cost/quality back.

```python
import anthropic
from minima_client import AsyncMinimaClient

async def routed_call(minima: AsyncMinimaClient, client: anthropic.AsyncAnthropic,
                      prompt: str, *, cost_quality_tradeoff: float = 4) -> str:
    rec = await minima.recommend(prompt, cost_quality_tradeoff=cost_quality_tradeoff)
    model = rec.recommended_model.model_id

    async with client.messages.stream(
        model=model, max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    ) as stream:
        msg = await stream.get_final_message()

    text = "".join(b.text for b in msg.content if b.type == "text")
    cost = rec.recommended_model.est_cost_usd  # or compute from msg.usage + your price table
    await minima.feedback(
        rec.recommendation_id, model, "success",
        quality_score=0.95,
        input_tokens=msg.usage.input_tokens,
        output_tokens=msg.usage.output_tokens,
        actual_cost_usd=cost,
        verified_in_production=True,
    )
    return text
```

### 7. Measure your savings

The measurement loop: declare your default model on `recommend`, report realized cost on `feedback`, then read the ledger. Both baselines are reported side by side — `vs_premium` (generous) and `vs_declared` (your own default; the honest one).

```python
from minima_client import MinimaClient

with MinimaClient("https://api.minima.sh", api_key="mbt_…") as minima:
    rec = minima.recommend(
        "Classify this ticket by urgency.",
        baseline_model_id="claude-opus-4-8",   # the model you'd have used
    )
    # ... run rec.recommended_model.model_id in your stack ...
    minima.feedback(
        rec.recommendation_id, rec.recommended_model.model_id, "success",
        quality_score=0.95, actual_cost_usd=0.0009,    # realized, not estimated
        input_tokens=420, output_tokens=80,
    )

    report = minima.savings(days=30, group_by="task_type")
    est = report.summary.estimated
    print(f"saved ${est.savings_vs_declared_usd:.4f} vs your default "
          f"over {est.n_declared} calls "
          f"(coverage {report.health['feedback_coverage']:.0%})")

    cal = minima.calibration(days=30)
    print("global ECE:", cal.reports[0].ece)   # 0 = predictions match reality
```

***

### Where to go next

* The schemas behind every field: [API Reference](/api-reference/endpoints).
* Why the cost numbers move the way they do: [Concepts → Cost-basis tiers](/sdk/concepts#cost-basis-tiers-estimate--observed--rescaled).
* The full client surface: [Python Client SDK](/sdk/client-sdk).


import { PageHeader, Steps, Step, Note, Tip } from '@components'

<PageHeader />

## Getting Started

Minima is a hosted API. There is nothing to install or run — you call the service with an API key, get a model recommendation, run that model in **your own** stack, and report the outcome so the next pick gets sharper. This walks you from a key to a closed feedback loop.

### Prerequisites

* **A Mubit API key** (`mbt_…`) — your Mubit data-plane key. Minima passes it through on each request to read and write your `task → model → outcome` history in Mubit; there is no separate Minima key. [Request access](https://minima.sh) if you don't have one yet.
* Nothing else. Minima computes its own embeddings server-side — there's no model, database, or runtime for you to operate.

<Note>
  **Base URL.** All requests go to `https://api.minima.sh`. The examples below read your Mubit key from a `MUBIT_API_KEY` environment variable — `export MUBIT_API_KEY=mbt_…` before running them.
</Note>

<Steps>
  <Step title="Make your first recommendation">
    ```bash
    curl -s https://api.minima.sh/v1/recommend \
      -H "authorization: Bearer $MUBIT_API_KEY" \
      -H 'content-type: application/json' \
      -d '{
            "task": {"task": "Summarize this 2-page incident report into 3 bullet points.",
                     "task_type": "summarization"},
            "cost_quality_tradeoff": 3
          }' | jq
    ```

    You get back a `recommendation_id`, a `recommended_model`, a ranked candidate list, a `fallback_model`, and a `decision_basis` (`memory` | `prior` | `llm`).
  </Step>

  <Step title="Run the model yourself">
    Minima hands back the pick — it never proxies, executes, or rewrites. Run the recommended model in your own stack with your own provider credentials. Keep the `recommendation_id`; you'll quote it back in the next step.
  </Step>

  <Step title="Close the loop">
    Tell Minima how it went. This is what makes the next recommendation sharper — and it populates the realized cost/token history that powers accurate cost ranking.

    ```bash
    curl -s https://api.minima.sh/v1/feedback \
      -H "authorization: Bearer $MUBIT_API_KEY" \
      -H 'content-type: application/json' \
      -d '{
            "recommendation_id": "<from step 1>",
            "chosen_model_id": "claude-haiku-4-5",
            "outcome": "success",
            "quality_score": 0.95,
            "input_tokens": 1180,
            "output_tokens": 320,
            "actual_cost_usd": 0.0028,
            "verified_in_production": true
          }' | jq
    ```
  </Step>
</Steps>

<Tip>
  **Cold start.** On day one your account has little history, so early picks lean on capability priors (`decision_basis: "prior"`, a `cold_start` warning) and the cheap-LLM reasoner fires more often. As your `/v1/feedback` outcomes accumulate, recommendations shift to `decision_basis: "memory"` and the cost ranking sharpens automatically — see [How it gets better over time](/sdk/concepts#how-it-gets-better-over-time).
</Tip>

### Next steps

* Use the typed [Python Client SDK](/sdk/client-sdk) instead of raw `curl`.
* Read [Concepts](/sdk/concepts) to understand the slider, the cost-basis tiers, and the escalation path.
* Browse the [Examples](/sdk/examples) for constraints, workflows, and a production routing wrapper.
* Prefer the terminal? The [Minima CLI](/harness/overview) wraps this whole loop in a coding agent.


import { PageHeader, Note, Tip } from '@components'

<PageHeader />

## CLI usage

Besides the interactive TUI, `minima` runs in two non-interactive modes and exposes two subcommands.

### Usage

```
minima [prompt] [--print|--mode json] [options]
minima auth              sign in to Mubit + provision this repo's project
minima config [set|get]  manage stored credentials
```

### Run modes

| Mode                      | Invocation               | Behavior                                                   |
| ------------------------- | ------------------------ | ---------------------------------------------------------- |
| **Interactive** (default) | `minima`                 | Full Ink TUI. See [Interactive TUI](/harness/interactive). |
| **One-shot print**        | `minima -p "…"`          | Runs the prompt, prints the final reply, exits.            |
| **Event stream**          | `minima --mode json "…"` | Streams agent events as JSON lines for scripting.          |

```bash
# one-shot
minima -p "explain this repo"

# machine-readable event stream
minima --mode json "refactor the config loader" | jq .
```

<Note>
  `--print` / `--mode json` require a prompt argument. Without one, the harness exits with an error.
</Note>

### Options

| Flag                     | Argument                                                     | Meaning                                                                            |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `-p`, `--print`          | —                                                            | One-shot: print the reply and exit.                                                |
| `--mode`                 | `interactive` \| `print` \| `json`                           | Select the run mode explicitly.                                                    |
| `--model`                | `ID`                                                         | Pin a model, bypassing routing.                                                    |
| `--provider`             | `NAME`                                                       | Provider for a pinned `--model` (registers unknown models on the fly).             |
| `--thinking`             | `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` | Extended-thinking level for models that support it.                                |
| `--offline`              | —                                                            | Bypass Minima routing entirely.                                                    |
| `-t`, `--tools`          | `LIST`                                                       | Comma-separated tool allowlist (only these run).                                   |
| `-xt`, `--exclude-tools` | `LIST`                                                       | Comma-separated tool denylist.                                                     |
| `-nt`, `--no-tools`      | —                                                            | Disable all tools.                                                                 |
| `-b`, `--budget`         | `USD`                                                        | Session budget with graduated warnings at 50/75/90/100%.                           |
| `--budget-enforce`       | —                                                            | Refuse new runs once the budget is exhausted (default: warn only).                 |
| `--slider`               | `0–10`                                                       | Cost/quality tradeoff — 0 = cheapest acceptable, 10 = highest quality (default 5). |
| `-h`, `--help`           | —                                                            | Print usage and exit.                                                              |

```bash
# pin a specific model and raise thinking effort
minima --model claude-opus-4-8 --provider anthropic --thinking high -p "review this diff"

# read-only, no shell: allow only read/ls/grep
minima -t read,ls,grep -p "where is auth handled?"

# run without the recommender at all
minima --offline --model gpt-4o-mini --provider openai -p "quick summary"
```

<Tip>
  `--model` (optionally with `--provider`) pins one model and skips routing; `--offline` skips the recommender while still using the seeded catalog. See [Model routing](/harness/routing) for how these interact. Tool filtering with `-t`/`-xt`/`-nt` composes with the interactive [permission system](/harness/tools).
</Tip>

### `minima auth`

Browser login → provisions a Mubit project for the current repo → stores `MUBIT_API_KEY` (and `MINIMA_URL`) → records the repo mapping in `~/.minima-harness/projects.json`.

```bash
minima auth                 # default region
minima auth --region eu     # or --region us
```

The console URL defaults to `https://console.mubit.ai` (override with `MUBIT_CONSOLE_URL`).

### `minima config`

Manage the per-user credential store without opening the TUI — works before any keys exist.

```bash
minima config                    # list every key (secrets masked)
minima config set MUBIT_API_KEY mbt_…
minima config get MINIMA_URL
```

See [Configuration](/harness/configuration) for every key, storage backend, and precedence rules.


import { PageHeader, Note, Tip, Warning } from '@components'

<PageHeader />

## Configuration

The harness is configured through environment variables — supplied via a per-user credential store, project `.env` files, or your shell. `minima config` manages the per-user store.

### Managing credentials

```bash
minima config                       # list every configurable key (secrets masked)
minima config set <KEY> <value>     # store a credential
minima config get <KEY>             # print a stored value
```

You don't have to drop to the CLI — the same is available **inside the interactive TUI** via the [`/config`](/harness/interactive) slash command:

```
/config                     # open the config editor / list keys
/config set <KEY> <value>   # store a credential
/config get <KEY>           # print a stored value
```

Secrets are stored **keychain-first**: the OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) via `keytar` when available, otherwise a `~/.minima-harness/config.env` file written mode `0600`. Non-secret values (URLs) always live in the file. `minima config set` reports which backend it used.

<Warning>
  The `keytar` native module does not bundle into the compiled binary, so the Homebrew-installed `minima` binary transparently falls back to the `0600` file store. That file is plaintext — keep it owner-only (it already is) and prefer project `.env` files or your shell for CI.
</Warning>

### Precedence

When the harness starts it loads configuration in this order — **earlier wins**, and stored values never overwrite something already set:

1. **Real shell environment** — anything already exported in your shell.
2. **Project `.env` files** in the current directory — `.env.harness`, then `.env`. Only fills keys not already set.
3. **Per-user store** — OS keychain + `~/.minima-harness/config.env`, materialized into the environment with set-default semantics (lowest precedence).

<Note>
  Put shared, non-secret settings (like `MINIMA_URL` for a local recommender) in a project `.env.harness`, and keep secrets in the keychain via `minima config set`.
</Note>

### Environment variables

#### Mubit / Minima routing

| Variable            | Required | Default                       | Purpose                                                                        |
| ------------------- | -------- | ----------------------------- | ------------------------------------------------------------------------------ |
| `MUBIT_API_KEY`     | **Yes**  | —                             | Memory backend + routing auth. Passed through to Mubit for recall/learning.    |
| `MINIMA_URL`        | No       | `https://api.minima.sh`       | The Minima recommender endpoint. Set to `http://localhost:8080` for local dev. |
| `MINIMA_API_KEY`    | No       | falls back to `MUBIT_API_KEY` | Separate Minima auth, if your deployment uses one.                             |
| `MUBIT_ENDPOINT`    | No       | —                             | Override the Mubit memory backend URL.                                         |
| `MUBIT_CONSOLE_URL` | No       | `https://console.mubit.ai`    | Console URL used by `minima auth`.                                             |
| `MINIMA_NAMESPACE`  | No       | per-repo project              | Memory isolation lane. Overrides the repo's provisioned project.               |
| `MINIMA_TIMEOUT`    | No       | `30`                          | Recommender request timeout, in seconds.                                       |

<Note>
  **Per-repo memory isolation.** If `MINIMA_NAMESPACE` is set it wins; otherwise the harness uses the namespace of the Mubit project that `minima auth` provisioned for this repo (stored in `~/.minima-harness/projects.json`). This keeps each project's `task → model → outcome` history separate.
</Note>

#### LLM provider keys

Set a key for any provider you want the harness to be able to run. The first environment variable listed for a provider wins.

| Provider           | Environment variable(s)                                    | Notes                                                             |
| ------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------- |
| Anthropic (Claude) | `ANTHROPIC_API_KEY`, `ANTHROPIC_OAUTH_TOKEN`               | Claude — Opus / Sonnet / Haiku                                    |
| OpenAI             | `OPENAI_API_KEY`                                           | GPT-5.x / GPT-4o                                                  |
| Google Gemini      | `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_GENAI_API_KEY` | Gemini 2.5 / 3.5                                                  |
| xAI (Grok)         | `XAI_API_KEY`                                              | Grok 4.x · base URL `https://api.x.ai/v1`                         |
| DeepSeek           | `DEEPSEEK_API_KEY`                                         | Open-weight, cheap · `https://api.deepseek.com`                   |
| OpenRouter         | `OPENROUTER_API_KEY`                                       | Aggregator — any model, one key · `https://openrouter.ai/api/v1`  |
| Groq               | `GROQ_API_KEY`                                             | Fast inference for open models · `https://api.groq.com/openai/v1` |

### Default model catalog

Out of the box the harness seeds this catalog; `/model` lets you pin one or add your own.

| Model               | Provider  | Context |
| ------------------- | --------- | ------- |
| `gpt-4o-mini`       | openai    | 128K    |
| `gpt-4o`            | openai    | 128K    |
| `deepseek-chat`     | deepseek  | 64K     |
| `claude-haiku-4-5`  | anthropic | 200K    |
| `claude-sonnet-4-6` | anthropic | 200K    |
| `claude-opus-4-8`   | anthropic | 200K    |
| `gemini-2.5-flash`  | google    | 1M      |
| `gemini-2.5-pro`    | google    | 2M      |

When routing (not pinned), Minima chooses from the candidate set `gemini-2.5-flash`, `claude-haiku-4-5`, `claude-sonnet-4-6`, `gemini-2.5-pro`, `claude-opus-4-8` by default.

<Tip>
  To run a model that isn't seeded, pass `--model <id> --provider <name>` — the harness registers it on the fly against the provider's OpenAI-compatible endpoint. See [CLI usage](/harness/cli).
</Tip>

### Config files at a glance

| Path                                 | What it holds                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| `~/.minima-harness/config.env`       | Per-user credentials (file backend, mode `0600`).                               |
| `~/.minima-harness/projects.json`    | Repo → Mubit instance / project / namespace mapping (written by `minima auth`). |
| `~/.minima-harness/sessions/*.jsonl` | Append-only session history. See [Sessions](/harness/sessions).                 |
| `./.env.harness`, `./.env`           | Project-scoped environment overrides.                                           |


import { PageHeader, Steps, Step, Note, Tip, Accordion } from '@components'

<PageHeader />

## Installation

The `minima` harness is distributed as a self-contained native binary through the [`mubit-ai/homebrew-minima`](https://github.com/mubit-ai/homebrew-minima) Homebrew tap. Install it, authenticate, and start.

### Prerequisites

* **[Homebrew](https://brew.sh)** (macOS or Linux).
* **A Mubit API key** (`MUBIT_API_KEY`) — routing + memory-backend auth. Get one from the [Mubit console](https://console.mubit.ai), or run `minima auth` (see below) to have it created and stored for you.
* **At least one LLM provider key** — the harness runs the model itself, so you need a key for whichever provider(s) you want to call: OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Groq, or OpenRouter. Local runtimes (Ollama, vLLM, LM Studio) need no key.

### Install with Homebrew

```bash
brew install mubit-ai/minima/minima
```

That taps [`mubit-ai/homebrew-minima`](https://github.com/mubit-ai/homebrew-minima) and installs the `minima` formula in one step. Prefer to tap explicitly? It's equivalent to:

```bash
brew tap mubit-ai/minima
brew install minima
```

Verify it's on your `PATH`, and upgrade later with Homebrew:

```bash
minima --help
brew upgrade minima      # pull the latest release
```

<Note>
  The Homebrew formula ships the compiled binary, which bundles no OS keychain module — so credentials fall back to a `~/.minima-harness/config.env` file (mode `0600`). See [Configuration](/harness/configuration#managing-credentials).
</Note>

<Accordion title="Build from source (for development)">
  Contributing to the harness? Build the binary yourself from the `packages/tui` workspace with [Bun](https://bun.sh) ≥ 1.2:

  ```bash
  cd packages/tui
  bun install
  bun test          # hermetic test suite (no network, no keys)
  bun run check     # tsc --noEmit
  bun run lint      # biome
  bun run build     # -> dist/minima (a self-contained native binary)
  ./dist/minima --help
  ```

  Put `dist/minima` on your `PATH` (or symlink it) to invoke it as `minima` from any repo.
</Accordion>

### First-time setup

Pick one of the two paths below.

#### Recommended — browser login

`minima auth` opens your browser, signs you in to Mubit, provisions a Mubit **project scoped to the current repo**, stores your `MUBIT_API_KEY`, and records the project mapping for per-repo memory isolation. Already running the TUI? The [`/auth`](/harness/interactive) slash command runs the same flow.

```bash
cd your-repo
minima auth
# Opens the browser to authorize; on success stores MUBIT_API_KEY (+ MINIMA_URL)
# and writes the repo → project mapping to ~/.minima-harness/projects.json
```

<Note>
  `minima auth` accepts `--region eu|us` to choose a Mubit region. The console URL defaults to `https://console.mubit.ai` and can be overridden with `MUBIT_CONSOLE_URL`.
</Note>

#### Manual — set credentials directly

If you already have keys, store them with `minima config`:

```bash
minima config set MUBIT_API_KEY   mbt_…
minima config set OPENAI_API_KEY  sk-…
# or ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / …
```

Secrets go to your OS keychain when available, otherwise to `~/.minima-harness/config.env` (mode `0600`). See [Configuration](/harness/configuration) for the full precedence rules and every key.

### Start

```bash
minima            # interactive TUI (default)
minima -p "explain this repo"          # one-shot answer, then exit
minima --mode json "refactor foo" | jq # machine-readable event stream
```

<Tip>
  `MUBIT_API_KEY` (routing) plus **one** provider key is enough to start. From there, `--offline` bypasses the recommender and `--model` / `--provider` pin a specific model. See [CLI usage](/harness/cli).
</Tip>


import { PageHeader, Note, Tip } from '@components'

<PageHeader />

## Interactive TUI

Running `minima` with no prompt opens the interactive terminal UI: a scrolling conversation view, an input prompt, and a status bar. Type a message and press <kbd>Enter</kbd> to send it; the harness routes it, runs the chosen model, streams the reply, and executes any tool calls (asking permission where required).

### The status bar

The bar along the bottom shows, at a glance:

* **Model** — the pinned model, or `auto` when Minima is routing.
* **Cost** — running total from the cost meter for this session.
* **Context** — percentage of the model's context window used, plus token counts.
* **State** — whether a turn is in flight.

### Keyboard shortcuts

| Key                                     | Action                                                             |
| --------------------------------------- | ------------------------------------------------------------------ |
| <kbd>Enter</kbd>                        | Send the current prompt                                            |
| <kbd>Ctrl</kbd>+<kbd>L</kbd>            | Open the model picker                                              |
| <kbd>Ctrl</kbd>+<kbd>P</kbd>            | Open the command palette (slash commands)                          |
| <kbd>Ctrl</kbd>+<kbd>R</kbd>            | Toggle route mode (auto ↔ confirm)                                 |
| <kbd>Esc</kbd>                          | Abort the in-flight run                                            |
| <kbd>Ctrl</kbd>+<kbd>C</kbd>            | Abort a running turn; press again at the prompt to quit            |
| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | Scroll the conversation                                            |
| <kbd>Shift</kbd>+<kbd>Space</kbd>       | Scroll down                                                        |
| <kbd>Ctrl</kbd>+<kbd>G</kbd>            | Jump to the top of the chat                                        |
| <kbd>Ctrl</kbd>+<kbd>E</kbd>            | Jump to the bottom of the chat                                     |
| <kbd>Tab</kbd>                          | Auto-complete a slash command                                      |
| <kbd>↑</kbd> / <kbd>↓</kbd>             | Cycle input history (at the prompt) · navigate items (in a picker) |

<Note>
  In the model picker, command palette, and session picker, use <kbd>↑</kbd>/<kbd>↓</kbd> to move, <kbd>Enter</kbd> to choose, and <kbd>Esc</kbd> to dismiss.
</Note>

### Slash commands

Type `/` (or open the palette with <kbd>Ctrl</kbd>+<kbd>P</kbd>) and pick a command:

| Command               | What it does                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `/model`              | Select or pin a model (or `auto` to unpin and let Minima route)                                                           |
| `/clear`              | Clear chat messages                                                                                                       |
| `/auth`               | Sign in to Mubit & provision this repo's project                                                                          |
| `/config`             | Show/set API keys (`MUBIT`, `GEMINI`, `ANTHROPIC`, …)                                                                     |
| `/help`               | Show the available commands                                                                                               |
| `/cost`               | Show cost-meter totals                                                                                                    |
| `/budget`             | Show or set the session budget (`/budget set <usd>` · `/budget mode shadow\|warn\|enforce`)                               |
| `/reconnect`          | Reconnect the routing client                                                                                              |
| `/new`                | Start a fresh session                                                                                                     |
| `/name <label>`       | Set the session display name                                                                                              |
| `/session`            | Show session info                                                                                                         |
| `/tree`               | Toggle the live [sub-agent tree panel](/harness/tools#sub-agents-the-task-tool) — one row per child with status and spend |
| `/fork <entry-id>`    | Fork a new session from an entry id                                                                                       |
| `/clone`              | Clone the current session                                                                                                 |
| `/resume [id]`        | Resume a previous session (optionally by id)                                                                              |
| `/judge [on\|off]`    | Toggle LLM quality judging                                                                                                |
| `/thoughts [on\|off]` | Toggle streaming the model's thinking                                                                                     |
| `/mouse [on\|off]`    | Toggle mouse capture (scroll vs. select/copy)                                                                             |
| `/perms`              | Show current tool permission grants                                                                                       |
| `/undo`               | Undo the last AI change (`git checkout`)                                                                                  |
| `/compact`            | Summarize old turns to free context                                                                                       |
| `/plan`               | Toggle plan mode (read-only)                                                                                              |
| `/quit`, `/exit`      | Exit the application                                                                                                      |

<Tip>
  `/model auto` hands routing back to Minima after you've pinned a model. `/plan` is handy when you want the agent to think and read without touching files — it blocks `write`, `edit`, and `bash`. See [Tools & permissions](/harness/tools).
</Tip>

### Related

* [Model routing](/harness/routing) — auto routing, pinning, and the feedback loop.
* [Sessions](/harness/sessions) — `/new`, `/resume`, `/fork`, `/clone`, `/compact`.
* [Tools & permissions](/harness/tools) — what the agent can do and how grants work.


import { PageHeader, CardGroup, Card, Note } from '@components'

<PageHeader />

## Minima CLI

`minima` is a terminal coding agent. It reads and edits your code, runs commands, and answers questions about a repo — like any agentic CLI — but every prompt is first sent to the [Minima recommender](/sdk/getting-started) to pick the cheapest model that will actually do the job. It then **runs that model itself** (calling the provider API directly), grades the outcome, and reports feedback so the next pick is sharper.

```
recommend  ──▶  run the model yourself  ──▶  judge quality  ──▶  feedback
```

<Note>
  The harness talks to the Minima recommender service over the same `/v1/*` HTTP contract as the [SDK](/sdk/getting-started). It **never proxies LLM calls** — it calls OpenAI / Anthropic / Google / etc. directly with your provider keys, so your prompts and code never pass through Minima.
</Note>

### What you get

<CardGroup cols={2}>
  <Card title="Cost-aware routing" icon="circle-nodes" href="/harness/routing">
    Every turn is routed to the cheapest model expected to clear the task, across OpenAI, Anthropic, Google, DeepSeek, xAI, Groq, and OpenRouter. Pin a model with `/model` or `--model` any time.
  </Card>

  <Card title="Built-in tools" icon="folder-tree" href="/harness/tools">
    `read`, `write`, `edit`, `bash`, `ls`, `glob`, `grep`, `web_fetch`, and `todowrite` — gated by a permission system — plus `task`, which delegates subtasks to parallel, cost-routed sub-agents (watch them live with `/tree`).
  </Card>

  <Card title="Per-repo memory" icon="brain" href="/harness/configuration">
    `minima auth` provisions a Mubit project scoped to the current repo, so each project's `task → model → outcome` history stays isolated.
  </Card>

  <Card title="Sessions you can branch" icon="folder-tree" href="/harness/sessions">
    An append-only session tree — fork, clone, and resume past conversations, and compact old turns to free context.
  </Card>
</CardGroup>

### How it fits together

* **Interactive TUI** — the default. A conversation view, status bar (model, cost, context), model picker, and slash commands. See [Interactive TUI](/harness/interactive).
* **Non-interactive** — `minima -p "…"` prints one answer; `minima --mode json "…"` streams machine-readable events for scripting. See [CLI usage](/harness/cli).
* **The recommender** — the Python FastAPI service that ranks models. The harness needs only a `MUBIT_API_KEY` (routing + memory auth) plus one provider key to call models. See [Configuration](/harness/configuration).

### Next steps

* [Install the harness](/harness/installation) and run `minima auth`.
* [Configure credentials](/harness/configuration) and pick your providers.
* Learn the [interactive TUI](/harness/interactive) — keybindings and slash commands.


import { PageHeader, Note, Tip } from '@components'

<PageHeader />

## Model routing

Every turn follows the Minima loop:

```
recommend  ──▶  run the model yourself  ──▶  judge quality  ──▶  feedback
```

1. **Recommend.** The harness sends the turn to the Minima recommender, which ranks the candidate models and returns the cheapest one expected to clear the task.
2. **Run.** The harness runs that model directly against the provider API — Minima never sees your prompt or code.
3. **Judge.** The outcome is optionally graded (see [Quality judging](#quality-judging)).
4. **Feedback.** The result and realized cost/tokens are reported back so the next recommendation is sharper.

This is the same engine described in the [SDK Concepts](/sdk/concepts) — the harness is a client of it.

### Auto vs. pinned

* **Auto (default).** The status bar shows `auto`; Minima picks a model per turn from the candidate set (`gemini-2.5-flash`, `claude-haiku-4-5`, `claude-sonnet-4-6`, `gemini-2.5-pro`, `claude-opus-4-8` by default).
* **Pinned.** Choose a model with `/model` in the TUI, or `--model <id>` (optionally `--provider <name>`) on the CLI. Routing is bypassed — the harness always runs that model. `/model auto` returns to routing.

<Note>
  The cost/quality tradeoff defaults to the middle of the slider (`5` of `0–10`). Lower it to favor cheaper models, raise it to demand higher predicted quality. See [the slider](/sdk/concepts#the-costquality-slider).
</Note>

### Offline mode

`--offline` bypasses the Minima recommender entirely — no recommend/feedback round-trips. Pair it with `--model`/`--provider` to run a specific model with no routing at all:

```bash
minima --offline --model gpt-4o-mini --provider openai -p "quick summary"
```

Use `/reconnect` in the TUI to re-establish the routing client if the recommender was briefly unreachable.

### Quality judging

After a turn, the harness can grade the outcome and send that quality score with feedback. In the CLI the judge **abstains by default** (it reports no score unless you enable it). Toggle an LLM judge on or off with `/judge [on|off]` in the TUI.

<Tip>
  Reporting quality and realized cost is what turns Minima's savings report from an estimate into a measurement, and sharpens future picks. Judging is how the harness supplies the quality half automatically.
</Tip>

### Memory isolation

Routing recall and learning are scoped to a **namespace** — by default the Mubit project `minima auth` provisioned for the current repo, or `MINIMA_NAMESPACE` if set. Different repos therefore learn independently. See [Configuration → per-repo memory isolation](/harness/configuration).


import { PageHeader, Note, Tip } from '@components'

<PageHeader />

## Sessions

Every conversation is persisted as an **append-only session** — a JSONL log of turns stored under `~/.minima-harness/sessions/<session-id>.jsonl`. Because entries are only ever appended, you can branch from any point in the history rather than losing it.

### Session commands

| Command            | What it does                                                          |
| ------------------ | --------------------------------------------------------------------- |
| `/new`             | Start a fresh session                                                 |
| `/name <label>`    | Set the current session's display name                                |
| `/session`         | Show info about the current session                                   |
| `/resume [id]`     | Resume a previous session — opens a picker, or jumps straight to `id` |
| `/fork <entry-id>` | Start a new session branched from a specific entry                    |
| `/clone`           | Clone the current session into a new one                              |
| `/compact`         | Summarize older turns to free up context                              |

### Branching

Because the log is append-only, `/fork <entry-id>` lets you rewind to an earlier point and take the conversation in a different direction without discarding what came after — the original branch is still there. `/clone` duplicates the whole current session so you can experiment safely.

<Tip>
  Entry ids are recorded in the session's JSONL log under `~/.minima-harness/sessions/` — grab one there, then `/fork <entry-id>` to explore an alternative from that point. (`/tree` shows the live [sub-agent panel](/harness/tools#sub-agents-the-task-tool), not the session tree.)
</Tip>

### Managing context

Long sessions eventually fill the model's context window (watch the context percentage in the [status bar](/harness/interactive#the-status-bar)). `/compact` summarizes older turns into a compact form so the conversation can continue without hitting the limit — recent turns are preserved verbatim.

<Note>
  Resuming a session restores its message history so routing and the agent pick up where you left off. Sessions are local to your machine, under `~/.minima-harness/sessions/`.
</Note>


import { PageHeader, Note, Warning, Tip } from '@components'

<PageHeader />

## Tools & permissions

The agent gets things done by calling **tools**. Each tool call passes through a permission gate before it runs, so nothing touches your files or shell without approval (or a standing grant).

### Built-in tools

| Tool        | What it does                                                                              | Class         |
| ----------- | ----------------------------------------------------------------------------------------- | ------------- |
| `read`      | Read a file's contents                                                                    | read          |
| `ls`        | List a directory                                                                          | read          |
| `glob`      | Match files by glob pattern                                                               | read          |
| `grep`      | Search file contents by regex                                                             | read          |
| `web_fetch` | Fetch and parse an HTTP URL                                                               | read          |
| `write`     | Create a new file                                                                         | write         |
| `edit`      | Modify an existing file                                                                   | write         |
| `bash`      | Run a shell command (with timeout + abort)                                                | dangerous     |
| `todowrite` | Maintain a plan/todo file                                                                 | write         |
| `task`      | Delegate subtasks to cost-routed sub-agents (see [Sub-agents](#sub-agents-the-task-tool)) | orchestration |

### The permission model

Approval depends on the tool's class:

* **`read` / `ls`** prompt the **first time** a new directory is accessed — the working directory is not pre-approved. Granting "always" approves that directory tree, so future reads there are silent.
* **Write tools** (`write`, `edit`, `todowrite`) always prompt. You can grant "always" for the tool.
* **Dangerous tools** (`bash`) always prompt. You can grant "always" for the tool.
* **Everything else** (`glob`, `grep`, `web_fetch`, `task`) prompts per call, with the same per-tool "always" grant.

When a tool needs approval, the TUI shows an inline prompt: approve once (<kbd>y</kbd>), approve always (<kbd>a</kbd>), or deny (<kbd>n</kbd> / <kbd>Esc</kbd>).

<Note>
  Use `/perms` to see the grants active in the current session.
</Note>

### Sub-agents (the `task` tool)

The lead agent carries one orchestration tool: `task`. The model calls it with a JSON array of **delegations** — subtasks with a required contract (`objective`, `output_format`, `boundaries`) plus optional `depends_on`, `effort` (`light` | `standard` | `deep`), `difficulty`, `tool_allowlist`, `budget_usd`, and `isolation`. The harness validates the graph (unique step ids, no dangling `depends_on`, no cycles) and executes it as a DAG: independent steps run **concurrently** (up to 4 at a time), dependents wait for their prerequisites, and a failed dependency blocks its dependents.

Each child is its own cost-routed agent: it gets a per-step model recommendation (the delegation's `difficulty` reaches the recommender), its own cost meter and budget slice, a tool set scoped by the delegation's allowlist and confined to its working directory, and effort-scaled turn and wall-clock caps. Children cannot delegate further — the `task` tool is excluded from their toolset. Sub-agent spend and decisions are recorded under their own agent id, so they demux cleanly from the lead's.

#### Git worktree isolation

A delegation with `isolation: "workdir"` runs in a **temporary git worktree** created from `HEAD`, so parallel children editing the same files can't clobber each other's writes. The worktree is removed automatically when the child finishes. If the working tree is dirty when the child spawns, its result carries a note that uncommitted changes weren't visible to it; if the worktree can't be created (e.g. not a git repo), the child falls back to the parent's directory.

#### Watching it live

`/tree` in the TUI toggles a live sub-agent panel — one row per child showing its step id, status (running / done / aborted / failure), and accumulated spend. See [Interactive TUI](/harness/interactive).

### Plan mode

`/plan` toggles **read-only** mode: `write`, `edit`, and `bash` are blocked entirely, so the agent can read, search, and reason about the repo without changing anything. Toggle it off to let it act.

<Tip>
  `/undo` reverts the last AI change with `git checkout`, so an unwanted edit is one command away.
</Tip>

### Restricting tools from the CLI

In non-interactive runs (and to constrain the interactive agent), narrow the toolset with flags:

```bash
minima -t read,ls,grep     -p "trace how requests are authenticated"   # allowlist
minima -xt bash,write      -p "summarize the module"                    # denylist
minima -nt                 -p "just answer, no tools"                   # no tools at all
```

<Warning>
  `bash` runs arbitrary commands in your shell. Grant "always" only in repos you trust, and prefer an allowlist (`-t`) or [plan mode](/harness/tools) when you only need the agent to look, not act.
</Warning>

See the flags reference in [CLI usage](/harness/cli).


import { PageHeader, Note, Tip } from '@components'

<PageHeader />

## Troubleshooting

### The recommender is unreachable

If routing calls fail or hang:

* Run `/reconnect` to re-establish the routing client.
* Check `MINIMA_URL` (`minima config get MINIMA_URL`) — it should be `https://api.minima.sh` unless you're pointing at a local recommender.
* As a fallback, run pinned + offline: `minima --offline --model <id> --provider <name>`.

### Authentication failures

* Re-run `minima auth` to refresh your `MUBIT_API_KEY` and repo project mapping.
* Verify the key is stored: `minima config get MUBIT_API_KEY` (it will show the stored value).
* If your org is in a specific region, pass `minima auth --region eu` or `--region us`.
* Override the console with `MUBIT_CONSOLE_URL` if you use a non-default Mubit console.

### "No provider key" / a model won't run

The harness runs models itself, so the relevant provider key must be set. Confirm with `minima config`, then set the missing one:

```bash
minima config set ANTHROPIC_API_KEY sk-ant-…   # or OPENAI_API_KEY / GEMINI_API_KEY / …
```

<Note>
  See the full provider → environment-variable table in [Configuration](/harness/configuration#llm-provider-keys). Remember the precedence order: shell env > project `.env` > stored config.
</Note>

### A tool won't run

* Writes and `bash` prompt for approval every time unless you grant "always". Check active grants with `/perms`.
* If you're in **plan mode**, `write`/`edit`/`bash` are blocked — toggle it off with `/plan`.
* If you launched with `-t`/`-xt`/`-nt`, the toolset is restricted by those flags. See [Tools & permissions](/harness/tools).
* Undo an unwanted change with `/undo` (`git checkout` of the last AI edit).

### Running out of context

When the context percentage in the [status bar](/harness/interactive#the-status-bar) climbs, run `/compact` to summarize older turns, or `/new` to start fresh. See [Sessions](/harness/sessions).

### Credentials aren't persisting

On the compiled binary, `keytar` isn't available, so credentials fall back to `~/.minima-harness/config.env` (mode `0600`). That's expected — `minima config set` reports `file` as the backend in that case. See the note in [Configuration](/harness/configuration#managing-credentials).

<Tip>
  Mouse selection not working for copy/paste? Toggle `/mouse off` to release mouse capture back to your terminal (then `/mouse on` to re-enable in-app scrolling).
</Tip>


import { PageHeader, Note, Badge } from '@components'

<PageHeader />

## API Reference

Base URL: `https://api.minima.sh`. Base path: `/v1`. All request and response bodies are JSON. Interactive OpenAPI docs are served at [`https://api.minima.sh/docs`](https://api.minima.sh/docs).

### Authentication

Minima uses **pass-through auth**: present your own **Mubit API key** as a bearer token. There is no separate Minima key — Minima forwards the key to Mubit to read and write your `task → model → outcome` history on your behalf.

```
Authorization: Bearer mbt_<instance>_<keyid>_<secret>
```

A missing or invalid key returns `401`. Your Mubit key determines which Mubit instance Minima reads and writes — it's your data boundary. Only two endpoints work without a key: `GET /v1/health` (service liveness) and `GET /v1/capabilities` (structural metadata).

`user_id` and `namespace` are scoping fields **within your Mubit instance**, not auth boundaries — use them to partition recall and learning across teams, projects, or environments.

### Errors

Errors are returned as `application/problem+json` (RFC 7807-style):

```json
{ "type": "about:blank", "title": "No candidate models", "status": 422,
  "detail": "no models match the supplied constraints" }
```

| Status | Title               | When                                        |
| ------ | ------------------- | ------------------------------------------- |
| `400`  | Invalid request     | Request body fails validation.              |
| `401`  | Unauthorized        | Missing or invalid Mubit key.               |
| `422`  | No candidate models | Constraints eliminated every catalog model. |

<Note>
  `POST /v1/feedback` does **not** error on an unknown `recommendation_id`. It returns `200` with `accepted: false` and an `unknown_recommendation` warning, so retried or cross-instance feedback fails safely.
</Note>

***

### `POST /v1/recommend`

<Badge text="core" variant="success" />

Recommend a model for a single task.

#### Request — `RecommendRequest`

| Field                   | Type           | Default  | Notes                                                                                                                          |
| ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `task`                  | `TaskInput`    | required | The task to route (see below).                                                                                                 |
| `cost_quality_tradeoff` | float `0–10`   | `5.0`    | 0 = cheapest acceptable, 10 = highest quality. Sets the quality threshold `τ`.                                                 |
| `constraints`           | `Constraints`  | `{}`     | Hard limits on the candidate set (see below).                                                                                  |
| `user_id`               | string \| null | `null`   | Within-account actor label. Scopes recall.                                                                                     |
| `namespace`             | string \| null | `null`   | Within-account sub-scope (team / project / environment). Isolates recall and learning.                                         |
| `max_candidates`        | int `1–64`     | `8`      | Cap on candidates considered.                                                                                                  |
| `allow_llm_escalation`  | bool           | `true`   | Allow the cheap-LLM reasoner when evidence is thin.                                                                            |
| `explain`               | bool           | `true`   | Include `evidence[]` refs on each ranked model.                                                                                |
| `baseline_model_id`     | string \| null | `null`   | The model you would have used without Minima. Powers the honest `vs_declared` baseline in [`GET /v1/savings`](#get-v1savings). |

##### `TaskInput`

| Field                    | Type            | Default  | Notes                                                                                                                                                                                   |
| ------------------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task`                   | string          | required | Raw task/prompt text; embedded by Mubit for recall.                                                                                                                                     |
| `task_type`              | enum \| null    | `null`   | `code` \| `summarization` \| `extraction` \| `qa` \| `reasoning` \| `classification` \| `translation` \| `creative` \| `rag` \| `tool_use` \| `other`. Heuristic-classified if omitted. |
| `difficulty`             | enum \| null    | `null`   | `trivial` \| `easy` \| `medium` \| `hard` \| `expert`.                                                                                                                                  |
| `expected_input_tokens`  | int ≥ 0 \| null | `null`   | Feeds the cost estimate; a per-task-type default is used if omitted.                                                                                                                    |
| `expected_output_tokens` | int ≥ 0 \| null | `null`   | Feeds the cost estimate.                                                                                                                                                                |
| `tags`                   | string\[]       | `[]`     | Propagated to Mubit `env_tags` (e.g. `lang:python`) for version-aware recall.                                                                                                           |

##### `Constraints` (all optional)

| Field                    | Type                | Notes                                                                                                                                        |
| ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed_providers`      | string\[] \| null   | Whitelist by provider.                                                                                                                       |
| `candidate_models`       | string\[] \| null   | Restrict to these model ids.                                                                                                                 |
| `excluded_models`        | string\[] \| null   | Blacklist by model id.                                                                                                                       |
| `max_cost_per_call`      | float ≥ 0 \| null   | USD hard filter on estimated cost.                                                                                                           |
| `min_quality`            | float `0–1` \| null | Predicted-success floor; raises `τ`.                                                                                                         |
| `require_prompt_caching` | bool                | Keep only models that support prompt caching.                                                                                                |
| `max_latency_ms`         | int > 0 \| null     | Drop candidates whose **observed** latency (p75 from similar past outcomes) exceeds this. A model with no latency history is never excluded. |
| `require_context_window` | int > 0 \| null     | Keep only models with at least this context window.                                                                                          |

#### Response — `RecommendResponse`

| Field                   | Type                  | Notes                                                                                                                                          |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `recommendation_id`     | string                | Quote this back to `POST /v1/feedback`.                                                                                                        |
| `recommended_model`     | `RankedModel`         | The chosen model.                                                                                                                              |
| `ranked`                | `RankedModel[]`       | Every candidate, sorted by final score.                                                                                                        |
| `fallback_model`        | `RankedModel` \| null | A more reliable retry target.                                                                                                                  |
| `confidence`            | float `0–1`           | Overall confidence in the pick.                                                                                                                |
| `decision_basis`        | enum                  | `memory` \| `prior` \| `llm` — which path produced the pick.                                                                                   |
| `threshold_used`        | float                 | The quality threshold `τ` applied.                                                                                                             |
| `classified_task_type`  | enum                  | Final task type used.                                                                                                                          |
| `classified_difficulty` | enum                  | Final difficulty used.                                                                                                                         |
| `catalog_version`       | string                | Catalog version that priced the candidates.                                                                                                    |
| `catalog_stale`         | bool                  | Prices older than the staleness window.                                                                                                        |
| `latency_ms`            | int                   | Minima-side recommendation latency.                                                                                                            |
| `warnings`              | string\[]             | See **Warnings** below.                                                                                                                        |
| `selection_policy`      | enum                  | `argmin` (deterministic cheapest-eligible, the default) \| `epsilon_softmax` (account opted into bounded exploration within the eligible set). |

##### `RankedModel`

| Field                     | Type            | Notes                                                                                                                                                                                   |
| ------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model_id`                | string          |                                                                                                                                                                                         |
| `provider`                | string          |                                                                                                                                                                                         |
| `predicted_success`       | float `0–1`     | Probability the model clears the task.                                                                                                                                                  |
| `est_cost_usd`            | float ≥ 0       | Estimated cost for this request, per the chosen cost basis.                                                                                                                             |
| `est_cost_breakdown`      | object          | Keys depend on the basis: `{rescaled, obs_output_tokens}`, `{observed_avg}`, or `{input, output}`. See [Cost-basis tiers](/sdk/concepts#cost-basis-tiers-estimate--observed--rescaled). |
| `score`                   | float           | Final objective score; the sorting key.                                                                                                                                                 |
| `rationale`               | string          | Human-readable reason (tags cost as `obs` or `est`).                                                                                                                                    |
| `decision_basis`          | enum            | Per-model basis: `memory` \| `prior` \| `llm`.                                                                                                                                          |
| `evidence`                | `EvidenceRef[]` | Recalled neighbors that informed this candidate (empty if `explain=false`).                                                                                                             |
| `supports_prompt_caching` | bool            |                                                                                                                                                                                         |
| `context_window`          | int             |                                                                                                                                                                                         |
| `est_latency_ms`          | float \| null   | Observed latency percentile from similar past outcomes; `null` without latency history.                                                                                                 |
| `latency_basis`           | string          | e.g. `observed_p75`; empty without latency history.                                                                                                                                     |

##### `EvidenceRef`

| Field                  | Type           | Notes                                                    |
| ---------------------- | -------------- | -------------------------------------------------------- |
| `entry_id`             | string         | Mubit `QueryEvidence.id` (used for outcome attribution). |
| `reference_id`         | string \| null | Stable reference id.                                     |
| `model_id`             | string         | The model this past outcome was about.                   |
| `score`                | float          | Retrieval similarity.                                    |
| `knowledge_confidence` | float `0–1`    | Mubit's reliability estimate for the entry.              |
| `observed_success`     | float `0–1`    | The recorded quality of that past outcome.               |
| `is_stale`             | bool           | Whether the entry is marked stale.                       |

#### Warnings

| Warning                          | Meaning                                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------------------- |
| `cold_start`                     | No recalled outcomes; prior-only.                                                                 |
| `recall_timeout`                 | Mubit recall exceeded the timeout; prior-only.                                                    |
| `memory_unavailable`             | Recall errored; prior-only.                                                                       |
| `prices_stale`                   | Catalog prices older than the staleness window.                                                   |
| `no_model_meets_threshold`       | No candidate cleared `τ`; recommended the highest-success one.                                    |
| `no_model_within_cost_budget`    | `max_cost_per_call` eliminated all; constraint relaxed for ranking.                               |
| `no_model_within_latency_budget` | `max_latency_ms` eliminated every candidate with latency history; constraint relaxed for ranking. |
| `escalation_suggested:<reason>`  | Escalation criteria met (`thin_evidence`, `low_confidence`, `tie`, `conflict`, `wide_interval`).  |
| `exploration_pick`               | The opt-in exploration policy sampled a different eligible model than the deterministic pick.     |
| `reasoner_consulted`             | The cheap-LLM reasoner was consulted and changed scores.                                          |
| `reasoner_failed`                | The reasoner errored or returned unusable output; deterministic result used.                      |
| `reasoner_disabled`              | Escalation suggested but no reasoner is configured.                                               |
| `llm_classified`                 | The reasoner refined an ambiguous task classification.                                            |

#### Example

```bash
curl -s https://api.minima.sh/v1/recommend \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' -d '{
  "task": {"task": "Write a Python function that merges k sorted linked lists.",
           "task_type": "code", "difficulty": "hard",
           "expected_input_tokens": 180, "expected_output_tokens": 600,
           "tags": ["lang:python"]},
  "cost_quality_tradeoff": 3,
  "constraints": {"min_quality": 0.8, "excluded_models": ["some-deprecated-model"]},
  "namespace": "team-payments"
}' | jq
```

***

### `POST /v1/recommend/workflow`

<Badge text="workflow" variant="note" />

Recommend a model for each step of a multi-step workflow. Each step runs the same engine independently and gets its own `recommendation_id` for per-step feedback.

#### Request — `WorkflowRequest`

| Field                   | Type             | Default  | Notes                                       |
| ----------------------- | ---------------- | -------- | ------------------------------------------- |
| `steps`                 | `WorkflowStep[]` | required | The steps to route.                         |
| `cost_quality_tradeoff` | float `0–10`     | `5.0`    | Applied to every step.                      |
| `constraints`           | `Constraints`    | `{}`     | Global constraints; each step may override. |
| `user_id`               | string \| null   | `null`   |                                             |
| `namespace`             | string \| null   | `null`   |                                             |
| `allow_llm_escalation`  | bool             | `true`   |                                             |

##### `WorkflowStep`

| Field         | Type                  | Notes                                                                  |
| ------------- | --------------------- | ---------------------------------------------------------------------- |
| `step_id`     | string                | Caller-defined id (echoed in the response).                            |
| `task`        | `TaskInput`           | The step's task.                                                       |
| `constraints` | `Constraints` \| null | Per-step override, **merged over** the global constraints.             |
| `depends_on`  | string\[]             | Declared dependencies (informational; steps are scored independently). |

#### Response — `WorkflowResponse`

| Field                           | Type                   | Notes                                                                      |
| ------------------------------- | ---------------------- | -------------------------------------------------------------------------- |
| `workflow_recommendation_id`    | string                 | Id for the whole workflow.                                                 |
| `steps`                         | `StepRecommendation[]` | `{step_id, recommendation: RecommendResponse}` per step.                   |
| `total_est_cost_usd`            | float                  | Sum of recommended-model costs across steps.                               |
| `total_est_cost_if_all_premium` | float                  | Sum if each step used its most expensive candidate — the savings baseline. |
| `confidence`                    | float `0–1`            | Mean step confidence.                                                      |

See the [multi-step workflow example](/sdk/examples#4-multi-step-workflow).

***

### `POST /v1/feedback`

<Badge text="core" variant="success" />

Report an outcome and close the learning loop. This reinforces the memories that drove the recommendation **and** records realized cost/token history that powers the observed and rescaled cost-basis tiers.

#### Request — `FeedbackRequest`

| Field                    | Type                | Default  | Notes                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `recommendation_id`      | string              | required | From a prior `/recommend` (or a workflow step).                                                                                                                                                                                                                                                                                                              |
| `chosen_model_id`        | string              | required | The model you **actually ran** (may differ from the recommendation).                                                                                                                                                                                                                                                                                         |
| `outcome`                | enum                | required | `success` \| `partial` \| `failure`.                                                                                                                                                                                                                                                                                                                         |
| `quality_score`          | float `0–1` \| null | `null`   | Caller-supplied; no LLM judge. Defaults applied per outcome if omitted (0.9 / 0.5 / 0.1). A score that flatly contradicts the outcome label (e.g. `failure` at `0.95`) is clamped into a consistent band with a `quality_outcome_mismatch` warning.                                                                                                          |
| `input_tokens`           | int ≥ 0 \| null     | `null`   | Realized input tokens — **populate this** to enable the rescaled cost tier.                                                                                                                                                                                                                                                                                  |
| `output_tokens`          | int ≥ 0 \| null     | `null`   | Realized output tokens (captures reasoning/thinking) — **populate this** for the rescaled tier.                                                                                                                                                                                                                                                              |
| `actual_cost_usd`        | float ≥ 0 \| null   | `null`   | Realized $/call — enables the observed cost tier.                                                                                                                                                                                                                                                                                                            |
| `latency_ms`             | int ≥ 0 \| null     | `null`   |                                                                                                                                                                                                                                                                                                                                                              |
| `iterations`             | int ≥ 0 \| null     | `null`   | Agent-loop turns to resolution — a token-yield signal recorded on the outcome.                                                                                                                                                                                                                                                                               |
| `verified_in_production` | bool                | `false`  | Marks a real production outcome; gates lesson promotion.                                                                                                                                                                                                                                                                                                     |
| `judged`                 | bool \| null        | `null`   | Whether a quality judge actually ran on this outcome. `false` = quality was **not measured** (cadence-skip or judge abstain) — the decision log reconciles quality as `NULL` instead of a label-based default, so calibration and savings metrics never trust a fabricated score. Omitted (`null`) preserves the old-client behavior (per-outcome defaults). |
| `notes`                  | string \| null      | `null`   |                                                                                                                                                                                                                                                                                                                                                              |
| `idempotency_key`        | string \| null      | `null`   | Dedupe key; derived from `recommendation_id + model` if omitted.                                                                                                                                                                                                                                                                                             |

#### Response — `FeedbackResponse`

| Field                  | Type           | Notes                                                                                                                                                           |
| ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted`             | bool           | `false` with a warning on failure.                                                                                                                              |
| `record_id`            | string \| null | The Mubit id of the upserted outcome record.                                                                                                                    |
| `reinforced_entry_ids` | string\[]      | The neighbor entry ids credited.                                                                                                                                |
| `updated_confidence`   | float \| null  | Mubit's updated `knowledge_confidence` for the primary entry.                                                                                                   |
| `reflection_triggered` | bool           | Whether reflection fired this call.                                                                                                                             |
| `lesson_promoted`      | bool           | Whether a durable lesson was promoted.                                                                                                                          |
| `warnings`             | string\[]      | `unknown_recommendation`, `memory_write_failed`, `reinforcement_failed`, `lesson_promotion_failed`, `quality_outcome_mismatch`, `late_feedback_no_attribution`. |

<Note>
  **How late can feedback arrive?** A `recommendation_id` accepts fully-attributed feedback for **7 days**. After that the outcome is still accepted and still teaches the recommender (the durable outcome record is written), but the specific recalled neighbors can no longer be credited — the response carries a `late_feedback_no_attribution` warning.
</Note>

#### Example

```bash
curl -s https://api.minima.sh/v1/feedback \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' -d '{
  "recommendation_id": "…",
  "chosen_model_id": "claude-haiku-4-5",
  "outcome": "success",
  "quality_score": 0.95,
  "input_tokens": 180, "output_tokens": 640, "actual_cost_usd": 0.0034,
  "verified_in_production": true
}' | jq
```

***

### `GET /v1/models`

The current model catalog (cost + capability priors).

#### Query parameters

| Param           | Type   | Default | Notes                                                        |
| --------------- | ------ | ------- | ------------------------------------------------------------ |
| `provider`      | string | —       | Filter by provider (case-insensitive).                       |
| `task_type`     | enum   | —       | Keep only models with a capability prior for this task type. |
| `max_cost`      | float  | —       | Keep only models whose max(input, output) $/Mtok ≤ this.     |
| `include_stale` | bool   | `true`  | Prefer fresh-priced models when false.                       |

#### Response

`{ models: ModelCard[], catalog_version, refreshed_at, stale }`, sorted by input price.

**`ModelCard`** fields include: `model_id`, `provider`, `display_name`, `input_cost_per_mtok`, `output_cost_per_mtok`, `cache_read_cost_per_mtok`, `supports_prompt_caching`, `context_window`, `max_output_tokens`, `capability_priors`, `capability_by_task_type`, `cost_source`, `cost_fetched_at`, `cost_stale`, `capability_source`.

***

### `GET /v1/strategies`

Surfaces the rules Mubit has promoted for a namespace — the "why" behind routing patterns.

#### Query parameters

| Param            | Type       | Default | Notes                                            |
| ---------------- | ---------- | ------- | ------------------------------------------------ |
| `namespace`      | string     | —       | Within-account sub-scope to read strategies for. |
| `lesson_types`   | string\[]  | —       | Filter by lesson type.                           |
| `max_strategies` | int `1–50` | `5`     |                                                  |

#### Response

`{ namespace, lane, strategies: Strategy[], count }`, where each `Strategy` has `strategy_id`, `description`, `supporting_lesson_count`, `avg_confidence`, `avg_reinforcement`, `dominant_lesson_type`, `dominant_scope`, `lesson_ids[]`.

***

### `GET /v1/savings`

<Badge text="measurement" variant="tip" />

What Minima actually saved you. Every recommendation is logged with its counterfactual cost baselines and reconciled with the realized cost you report to `/v1/feedback` — this endpoint aggregates that ledger for your account.

Two baselines are always reported side by side, explicitly labeled: **`vs premium`** (the most expensive candidate that was scored for each request — generous; overstates savings if you'd never have used the premium model) and **`vs declared`** (your own stated default via `baseline_model_id` — honest, but only present on requests where you declared one). Estimated and realized figures are never mixed into one number.

#### Query parameters

| Param       | Type           | Default | Notes                                                    |
| ----------- | -------------- | ------- | -------------------------------------------------------- |
| `namespace` | string         | —       | Restrict to one namespace.                               |
| `days`      | float `>0–365` | `30`    | Lookback window (must be greater than 0).                |
| `group_by`  | enum           | —       | `cluster` \| `task_type` \| `lane` — optional breakdown. |

#### Response

| Field               | Type   | Notes                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary.estimated` | object | `n`, `cost_recommended_usd`, `cost_premium_usd`, `savings_vs_premium_usd`, plus `n_declared` / `cost_declared_usd` / `savings_vs_declared_usd` over the declared-baseline subset.                                                                                                                                                                                      |
| `summary.realized`  | object | A **different** field set over the **reconciled** subset (feedback received with `actual_cost_usd`): `n_reconciled`, `realized_cost_usd`, `est_cost_recommended_usd`, `est_cost_premium_usd`, `savings_vs_premium_est_usd`, plus `n_declared` / `est_cost_declared_usd` / `savings_vs_declared_est_usd` — your realized cost measured against the estimated baselines. |
| `health`            | object | `recommendations`, `feedback_coverage` (share of recommendations that ever got feedback — the number that decides how much to trust `realized`), `late_feedback_share`, `escalation_rate`, `exploration_share`, `epsilon_policy_share`.                                                                                                                                |
| `groups`            | array  | Per-`group_by` key: the same `summary` + `health`.                                                                                                                                                                                                                                                                                                                     |

```bash
curl -s "https://api.minima.sh/v1/savings?days=30&group_by=task_type" \
  -H "authorization: Bearer $MUBIT_API_KEY" | jq '.summary, .health'
```

<Note>
  Send `baseline_model_id` on your `/v1/recommend` calls and realized `actual_cost_usd` on your `/v1/feedback` calls — they turn the savings report from an estimate into a measurement.
</Note>

***

### `GET /v1/calibration`

<Badge text="measurement" variant="tip" />

Is `predicted_success` telling the truth for your traffic? Compares each recommendation's predicted success against the realized outcome you reported, per task type.

#### Query parameters

| Param       | Type           | Default | Notes                                     |
| ----------- | -------------- | ------- | ----------------------------------------- |
| `namespace` | string         | —       | Restrict to one namespace.                |
| `days`      | float `>0–365` | `30`    | Lookback window (must be greater than 0). |

#### Response

| Field         | Type   | Notes                                                                                                                                                                                                                                                                                                                                               |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reports`     | array  | Per slice (first entry is `global`, then each task type): `n`, `ece` (expected calibration error — 0 is perfect), `ece_shrunk` (sparse slices pulled toward the global estimate so 3 feedbacks don't read as a verdict), `ece_quality` (quality-score-weighted variant), and reliability `bins` (`lo`, `hi`, `n`, `avg_predicted`, `avg_realized`). |
| `drift_flags` | array  | Sustained prediction drift per `(cluster, model)` — `direction` is `over_predicting` (the model got worse than the evidence says; the expensive failure mode) or `under_predicting`.                                                                                                                                                                |
| `health`      | object | Same routing-health rates as `/v1/savings`.                                                                                                                                                                                                                                                                                                         |

```bash
curl -s "https://api.minima.sh/v1/calibration?days=30" \
  -H "authorization: Bearer $MUBIT_API_KEY" | jq '.reports[] | {slice_key, n, ece, ece_shrunk}'
```

***

### `GET /v1/capabilities`

Server feature handshake: which optional endpoints and constraint fields the running server honors. Read it once at startup and cache it per session — gate optional features (like workflow routing) on what the server actually supports instead of guessing. No auth required — this is structural metadata, not account-scoped data.

#### Response — `CapabilitiesResponse`

| Field                 | Type      | Notes                                                                      |
| --------------------- | --------- | -------------------------------------------------------------------------- |
| `plan`                | bool      | `POST /v1/plan` (goal → Delegation DAG) is available. Currently `false`.   |
| `workflow`            | bool      | `POST /v1/recommend/workflow` is available.                                |
| `api_version`         | string    | Running server version.                                                    |
| `honored_constraints` | string\[] | Constraint fields the engine **actively filters on** (not merely accepts). |

```bash
curl -s https://api.minima.sh/v1/capabilities | jq
```

```json
{
  "plan": false,
  "workflow": true,
  "api_version": "0.7.0",
  "honored_constraints": ["candidate_models", "excluded_models", "max_cost_per_call",
    "min_quality", "require_prompt_caching", "max_latency_ms",
    "require_context_window", "allowed_providers"]
}
```

***

### `GET /v1/health`

Always returns `200`; reports degraded state in the body. Doesn't require a key (an unauthenticated probe gets service liveness; a key-bearing probe additionally confirms your account's memory reachability).

```json
{
  "status": "ok",
  "mubit": {"reachable": true, "latency_ms": 12, "endpoint": "https://api.mubit.ai", "org_id": "…"},
  "auth": "passthrough",
  "catalog": {"version": "…", "cost_source": "litellm", "stale": false, "models": 42},
  "reasoner": {"provider": "gemini", "configured": true},
  "version": "0.7.0"
}
```

An unauthenticated probe (no key) returns `"mubit": {"reachable": null, "scope": "unauthenticated"}` and `status: "ok"` — liveness only. `status` is `degraded` only when a **key-bearing** probe finds your memory backend unreachable (`mubit.reachable == false`); in that state `/recommend` still serves prior-only recommendations.