Cartha SDK (Python)

Instrument AI agents with memory, traces, costs, and policies on Cartha.

Install

pip install cartha-sdk

Requires Python 3.10+.

From source (development):

pip install "git+https://github.com/maulik-jadav/nexus.git#subdirectory=nexus/packages/sdk-python"
# or from a local clone:
pip install -e nexus/packages/sdk-python

Quickstart

export CARTHA_API_KEY="cartha_..."          # from the dashboard → Keys
export CARTHA_API_BASE="https://cartha.in"  # your Cartha deployment

import cartha

cartha.init()  # picks up CARTHA_* env vars

@cartha.trace()
def run_agent(prompt: str):
    return "..."

@cartha.trace() works on sync and async functions. Every call registers the agent, sends heartbeats, and records a full trace (start → steps → finish), including failures.

Memory

import cartha

# async agents
await cartha.remember(user_id="u1", content="Prefers dark mode", scope="user")
hits = await cartha.recall(user_id="u1", context="UI preferences", scope=["user", "team"])

# sync code
cartha.remember_sync(user_id="u1", content="Prefers dark mode", scope="user")

Scopes: agent (private) · user (all agents serving that user) · team (same team_id) · org (everyone in your org).

Nested agents (multi-agent loops)

By default, @cartha.trace() auto-nests: if a traced agent calls another traced agent, the child run links via parent_trace_id. No env plumbing required for in-process sub-agents.

@cartha.trace(id="parent")
async def orchestrator(user_id: str):
    await cartha.ops.delegate(to_agent_id="worker", task_description="handle")
    return await worker(user_id)

@cartha.trace(id="worker")  # nests under orchestrator automatically
async def worker(user_id: str):
    ...

Cost per completed task

Share a task_id across retries so the dashboard rolls failed redoes into one outcome:

tid = cartha.task_context()
for attempt in range(3):
    try:
        await run_agent(..., cartha_task_id=tid)
        break
    except Exception:
        continue

Memory denial mode

Org setting (PATCH /org → memory_denial_mode):

• denied_hint (default): recall returns explicit denials without content so agents don't invent over a hole.
• silent: empty hits only (no existence leak).

Advanced

The full instrumentation API lives in cartha.ops (tool calls, cost events, A2A delegation, policy checks, run nesting):

from cartha import ops

Legacy alias: older code may from nexus import ops. That still works for compatibility, but new code should use cartha.

Trace diff: GET /api/v1/traces/diff?left=…&right=… finds the first diverging step between two runs (also on the dashboard).

Publishing (maintainers)

Releases are published from GitHub Actions when you push a tag matching sdk-python-v* (for example sdk-python-v0.1.0).

Manual upload (emergency / first release):

cd nexus/packages/sdk-python
python -m pip install --upgrade build twine
python -m build
# TestPyPI first (recommended):
python -m twine upload --repository testpypi dist/*
# Production PyPI:
python -m twine upload dist/*

Use a PyPI API token (pypi-...), not your account password.