# mubit-sdk

Canonical Python SDK for MuBit.

## Install

```bash
pip install mubit-sdk
```

## Quickstart

```python
import os

from mubit import Client

client = Client(
    transport=os.getenv("MUBIT_TRANSPORT", "auto"),
    run_id="sdk-python-demo",
    api_key=os.environ["MUBIT_API_KEY"],
)

client.remember(
    session_id="sdk-python-demo",
    agent_id="sdk-quickstart",
    content="If the replay queue stalls, checkpoint before replaying recovery.",
    intent="lesson",
    lesson_type="success",
    lesson_scope="session",
    metadata={"source": "readme"},
)

answer = client.recall(
    session_id="sdk-python-demo",
    query="What should I do before replaying recovery?",
    entry_types=["lesson", "rule"],
)
print(answer.get("final_answer"))
```

## Surface Model

- Low-level raw APIs remain available on `client.auth.*`, `client.core.*`, and `client.control.*`.
- High-level helper APIs live on `Client`:
  - `remember`
  - `recall`
  - `get_context`
  - `archive`
  - `archive_block`
  - `dereference`
  - `memory_health`
  - `diagnose`
  - `reflect`
  - `forget`
  - `checkpoint`
  - `register_agent`
  - `list_agents`
  - `record_outcome`
  - `surface_strategies`
  - `handoff`
  - `feedback`
- Helper APIs use `session_id` as the ergonomic alias for `run_id`.

## Auto-Capture

The Python package also ships `mubit.auto` for zero-friction trace capture in MAS learning loops:

```python
from mubit.auto import instrument, observe

instrument()

@observe(name="repair-attempt")
def run_attempt():
    ...
```

## MAS / Learning Loop Example

```python
client.register_agent(
    session_id="sdk-python-demo",
    agent_id="planner",
    role="planner",
    read_scopes=["rule", "lesson", "fact"],
    write_scopes=["lesson", "trace"],
    shared_memory_lanes=["knowledge", "history"],
)

client.checkpoint(
    session_id="sdk-python-demo",
    label="pre-compaction-1",
    context_snapshot="Planner narrowed the failure to token refresh ordering.",
    metadata={"window": 1},
)

strategies = client.surface_strategies(
    session_id="sdk-python-demo",
    lesson_types=["success", "failure"],
    max_strategies=3,
)
print(len(strategies.get("strategies", [])))
```

## Exact References

```python
archived = client.archive(
    session_id="sdk-python-demo",
    artifact_kind="patch_fragment",
    content="--- a/query.py\n+++ b/query.py\n@@ ...",
    labels=["django", "retry"],
    family="patch-repair",
)

exact = client.dereference(
    session_id="sdk-python-demo",
    reference_id=archived["reference_id"],
)
print(exact.get("evidence", {}).get("content"))
```

## Endpoint Resolution

`transport` defaults to `auto` (gRPC primary, HTTP fallback).

Endpoint resolution order:
- explicit `endpoint` / `http_endpoint` / `grpc_endpoint` constructor args
- env vars `MUBIT_ENDPOINT`, `MUBIT_HTTP_ENDPOINT`, `MUBIT_GRPC_ENDPOINT`
- shared defaults `https://api.mubit.ai` and `grpc.api.mubit.ai:443`

## Package Example Lanes

Public adoption scenarios are the primary learning path:

```bash
PYTHONPATH=sdk/python/mubit-sdk/src python3 sdk/python/mubit-sdk/examples/public/run_public_examples.py --list
PYTHONPATH=sdk/python/mubit-sdk/src python3 sdk/python/mubit-sdk/examples/public/run_public_examples.py --scenario 01_remember_recall
PYTHONPATH=sdk/python/mubit-sdk/src python3 sdk/python/mubit-sdk/examples/public/run_public_examples.py --scenario 12_auto_capture_observed_loop
```

Internal raw-smoke scenarios remain available for compatibility and wire-level verification:

```bash
PYTHONPATH=sdk/python/mubit-sdk/src python3 sdk/python/mubit-sdk/examples/internal/run_internal_examples.py --list
PYTHONPATH=sdk/python/mubit-sdk/src python3 sdk/python/mubit-sdk/examples/internal/run_internal_examples.py --scenario auth_lifecycle
```
