Using Minima correctly

Minima is recommend-only. Everything about using it well follows from that one fact: it tells you which model to run, you run the model, and you tell it what actually happened. This page is the whole proper-use flow in one place.

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           │
        └───────────────────────────────────────────────────────-─┘

recommend → run the model yourself → judge quality → feedback. Minima never proxies, executes, or caches an LLM call — so it adds zero latency to your real request, and everything it learns comes from the feedback you send.

The golden rules

1. Run the model yourself

The response gives you recommended_model.model_id and a recommendation_id. Run that model in your own stack with your own provider credentials. If recommend fails, fail open to your default model — your LLM call must never block on Minima.

2. Report realized usage and cost — never echo est_cost_usd

Feedback must carry what actually happened: realized input_tokens, output_tokens, actual_cost_usd, and latency_ms, measured from the provider's own response.

3. Report outcomes honestly

outcome is "success" | "partial" | "failure". When you have a quality score in [0, 1], the ecosystem-wide mapping is:

Declare where the label came from with evidence_source: "gate" (a deterministic check passed — the only origin that may claim verified-in-production), "judge" (an LLM judge), "human" (you asserted it), or "none" (no label — the outcome rides as cost/latency telemetry only and never teaches the success posterior). Never fabricate a score you don't have; an honest "none" is more useful than an invented 0.9.

4. Keep recommendation_id as the join key

The recommendation_id from each recommendation is the single key that joins your run to Minima's decision log and memory. Carry it through your pipeline and quote it back on feedback — feedback with a lost or invented id can't credit the memories that drove the pick.

5. Send feedback even for failures

A failure is a learning signal, not an embarrassment to hide — it's how Minima learns a model can't handle a task type and stops recommending it. For provider/infra faults (429s, 5xx, timeouts) pass error_cause: "infra" so a rate limit is never learned as model quality.

What degrades if you skip feedback

• The cost basis stays at estimate — ranking runs on list prices and assumed token counts instead of your realized costs.
• Recommendations stay prior-driven (decision_basis: "prior") instead of grounded in your own history.
• The measurement layer goes dark: /v1/savings reports low feedback_coverage (its realized figures can't bear weight), and /v1/calibration has no outcomes to check predictions against.
• No reinforcement, no lesson promotion — the system never converges on your workload.

Where to go from here