Runtime calibration

Use runtime calibration from the SDKs

This page is for developers who use the Mubit SDKs, mubit-sdk for Python and @mubit-ai/sdk for TypeScript, to store lessons and report outcomes. It shows the helpers that work against the hosted service, and lists the 1.0.6 helpers that don't, so you don't meet a 403 in production.

The SDKs call the same routes as the API reference lists, on https://api.mubit.ai, with your Mubit key. They read the key from MUBIT_API_KEY. The SDK's session_id is sent as the route's run_id.

pip install mubit-sdk
npm install @mubit-ai/sdk

Helpers that work

Task	Python	TypeScript	Route
Store an item or a lesson	`client.remember`	`client.memory.remember`	`POST /v2/control/ingest`, then `GET /v2/control/ingest/jobs/{job_id}` while it waits
Store a lesson	`client.learned`	`client.learned`	The same: `remember` with `intent` set to `lesson`
Report an outcome	`client.record_outcome`	`client.memory.recordOutcome`	`POST /v2/control/outcome`
Save a checkpoint	`client.checkpoint`	`client.memory.checkpoint`	`POST /v2/control/checkpoint`
List a run's lessons	`client.lessons.list(lane="legacy", ...)`	`client.lessons.list({ lane: "legacy", ... })`	`POST /v2/control/lessons`
Read entries back	`client.memory.lookup`, `client.memory.search`	`client.memory.lookup`, `client.memory.search`	`POST /v2/core/lookup`, `POST /v2/core/search`
Check the key	`client.health`	`client.auth.health`	`GET /v2/core/health`
Delete a run	`forget` with a `session_id`	`forget` with a `runId`	`POST /v2/control/delete_run`

Two limits to know:

An outcome needs a reference_id. The SDK helpers refuse an empty one, so they report on one entry, not on a whole run. Take the id from the record_id of the finished ingest job that remember returns, or call the route directly to report on the whole run.
Pass lane="legacy" to list lessons. Without it, lessons.list asks a route the hosted service doesn't serve.

Store a lesson and report an outcome

Python

import os
from mubit import Mubit
 
client = Mubit(api_key=os.environ["MUBIT_API_KEY"])
run = "support-triage-lessons"
 
job = client.remember(
    content=(
        "A message about being charged twice belongs in the billing category, "
        "not the account category. A reviewer confirmed this on the October invoice case."
    ),
    session_id=run,
    intent="lesson",
    lesson_type="success",
    metadata={"kind": "category-rule", "contract": "v1"},
    idempotency_key="lesson-double-charge-v1",
)
 
# `remember` waits for the ingest job and returns it. Each trace lists the records it wrote.
writes = [w for trace in job.get("traces", []) for w in trace.get("writes", [])]
if writes:
    client.record_outcome(
        session_id=run,
        reference_id=writes[0]["record_id"],
        outcome="success",
        signal=1.0,
        rationale="A reviewer confirmed the billing category.",
        idempotency_key="outcome-ticket-1042",
    )
 
page = client.lessons.list(lane="legacy", run_id=run, limit=10)
print(len(page["lessons"]), "lessons")

Save a checkpoint with client.checkpoint(session_id=..., context_snapshot=..., label=...) in Python, or client.memory.checkpoint({ session_id, context_snapshot, label }) in TypeScript.

Helpers that are not offered on the hosted service

Mubit serves the routes in the API reference and no others. Each SDK 1.0.6 helper below calls a route the hosted service doesn't offer yet, and gets 403 not_in_1_0 or an error that the route doesn't exist. The cause is not your key.

Helper (Python and TypeScript names)	What to use instead
`recall`	Search or look up, then filter the entries in your app, as Recall lessons shows.
Get context (`getContext` in TypeScript, and the same helper in Python), and `memory.context` with `lane` set to `legacy`	Search, and filter in your app. `memory.context` with its default lane reads approved lessons.
`reflect`, and `lessons.reflect`	None. Write lessons yourself from runs you have checked.
`diagnose`	None.
`dereference`	Read the entry back with look up.
`memory.health`, and the other health report helper of each SDK	`health` checks that your key reaches the service.
`forget` with a `lesson_id`, and `lessons.delete`	Delete a run deletes a whole run. A single lesson can't be deleted yet.
The strategy helpers, including `lessons.strategies`, and the prompt and skill optimizers	None.
The agent registry, hand-off and feedback helpers	None.
`lessons.list` without `lane="legacy"`, and the helpers that open a run and send events: `init` and `runs.create`	List with `lane="legacy"`. The routes the other helpers use aren't served.

TypeScript names are the camelCase forms of the Python names.

Helpers that work

Store a lesson and report an outcome

Helpers that are not offered on the hosted service

Next