cartha-sdk 0.1.0__tar.gz

cartha_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maulik Jadav / Cartha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cartha_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: cartha-sdk
+Version: 0.1.0
+Summary: Cartha SDK — memory, traces, costs, and policies for AI agents
+Author-email: Maulik Jadav <maulikjadav239@gmail.com>
+Maintainer-email: Maulik Jadav <maulikjadav239@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://cartha.in
+Project-URL: Documentation, https://cartha.in
+Project-URL: Repository, https://github.com/maulik-jadav/nexus
+Project-URL: Issues, https://github.com/maulik-jadav/nexus/issues
+Project-URL: Source, https://github.com/maulik-jadav/nexus/tree/main/nexus/packages/sdk-python
+Keywords: cartha,agents,llm,observability,tracing,memory,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# Cartha SDK (Python)
+
+Instrument AI agents with memory, traces, costs, and policies on [Cartha](https://cartha.in).
+
+## Install
+
+```bash
+pip install cartha-sdk
+```
+
+Requires Python 3.10+.
+
+From source (development):
+
+```bash
+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
+
+```bash
+export CARTHA_API_KEY="cartha_..."          # from the dashboard → Keys
+export CARTHA_API_BASE="https://cartha.in"  # your Cartha deployment
+```
+
+```python
+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
+
+```python
+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.
+
+```python
+@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:
+
+```python
+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):
+
+```python
+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):
+
+```bash
+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.

cartha_sdk-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Cartha SDK (Python)
+
+Instrument AI agents with memory, traces, costs, and policies on [Cartha](https://cartha.in).
+
+## Install
+
+```bash
+pip install cartha-sdk
+```
+
+Requires Python 3.10+.
+
+From source (development):
+
+```bash
+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
+
+```bash
+export CARTHA_API_KEY="cartha_..."          # from the dashboard → Keys
+export CARTHA_API_BASE="https://cartha.in"  # your Cartha deployment
+```
+
+```python
+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
+
+```python
+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.
+
+```python
+@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:
+
+```python
+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):
+
+```python
+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):
+
+```bash
+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.

cartha_sdk-0.1.0/cartha/__init__.py

@@ -0,0 +1,142 @@
+"""
+Cartha SDK — instrument AI agents with memory, traces, costs, and policies.
+
+Quickstart (mirrors the dashboard Settings page):
+
+    export CARTHA_API_KEY="cartha_..."
+    export CARTHA_API_BASE="https://cartha.in"
+
+    import cartha
+    cartha.init()
+
+    @cartha.trace()
+    def run_agent(prompt: str):
+        return "..."
+
+`cartha.trace()` works on both sync and async functions. Async functions keep
+their full signature and are awaited as usual; sync functions are executed
+through the same instrumentation pipeline via a private event loop.
+
+Advanced users can access the underlying instrumentation API directly:
+
+    from cartha import ops
+    await ops.remember(...)
+    await ops.recall(...)
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any, Callable, Literal
+
+from nexus import ops
+from nexus.ops import (  # noqa: F401 — re-exported public API
+    PolicyViolation,
+    cost,
+    cost_sync,
+    delegate,
+    delegate_sync,
+    propagation_context,
+    recall,
+    recall_sync,
+    remember,
+    remember_sync,
+    task_context,
+    tool_call,
+    tool_call_sync,
+)
+
+__all__ = [
+    "init",
+    "trace",
+    "ops",
+    "PolicyViolation",
+    "recall", "remember", "tool_call", "cost", "delegate", "propagation_context",
+    "task_context",
+    "recall_sync", "remember_sync", "tool_call_sync", "cost_sync", "delegate_sync",
+]
+
+__version__ = "0.1.0"
+
+
+def init(
+    api_key: str | None = None,
+    api_base: str | None = None,
+    org_id: str | None = None,
+) -> None:
+    """
+    Configure the SDK. Values are resolved in priority order:
+    explicit argument > CARTHA_* env var > existing NEXUS_* env var.
+
+    Safe to call multiple times; later calls override earlier ones.
+    """
+    key = api_key or os.getenv("CARTHA_API_KEY")
+    if key:
+        os.environ["NEXUS_API_KEY"] = key
+
+    base = api_base or os.getenv("CARTHA_API_BASE")
+    if base:
+        os.environ["NEXUS_ENDPOINT"] = base.rstrip("/")
+
+    org = org_id or os.getenv("CARTHA_ORG_ID")
+    if org:
+        os.environ["NEXUS_ORG_ID"] = org
+
+
+def trace(
+    id: str | None = None,
+    *,
+    team: str | None = None,
+    org: str | None = None,
+    protocols: list[Literal["mcp", "a2a"]] | None = None,
+    description: str = "",
+    task_id: str | None = None,
+    nest: bool = True,
+) -> Callable:
+    """
+    Instrument an agent function: registration, heartbeats, trace
+    start/steps/finish, and failure capture — all automatic.
+
+    nest=True (default): if called inside another traced agent, this run
+    becomes a child trace (parent_trace_id) — required for multi-agent loops.
+
+    task_id: group retries of the same logical outcome for cost-per-task.
+    Pass cartha_task_id= at call time to override per-invocation.
+    """
+    team_id = team or os.getenv("CARTHA_TEAM_ID", "default_team")
+
+    def decorator(fn: Callable) -> Callable:
+        agent_key = id or fn.__name__
+        ops_decorator = ops.agent(
+            id=agent_key,
+            team=team_id,
+            org=org,
+            protocols=protocols,
+            description=description,
+            task_id=task_id,
+            nest=nest,
+        )
+
+        if asyncio.iscoroutinefunction(fn):
+            return ops_decorator(fn)
+
+        # Sync function: route it through the async instrumentation pipeline.
+        # The body runs in a worker thread so that sync helpers like
+        # remember_sync()/recall_sync() (which call asyncio.run internally)
+        # aren't executed inside this already-running event loop. to_thread
+        # copies contextvars, so the trace context follows into the thread.
+        async def _async_shim(*args: Any, **kwargs: Any) -> Any:
+            return await asyncio.to_thread(fn, *args, **kwargs)
+
+        _async_shim.__name__ = fn.__name__
+        _async_shim.__doc__ = fn.__doc__
+        instrumented = ops_decorator(_async_shim)
+
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return asyncio.run(instrumented(*args, **kwargs))
+
+        sync_wrapper.__name__ = fn.__name__
+        sync_wrapper.__doc__ = fn.__doc__
+        return sync_wrapper
+
+    return decorator

cartha_sdk-0.1.0/cartha_sdk.egg-info/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: cartha-sdk
+Version: 0.1.0
+Summary: Cartha SDK — memory, traces, costs, and policies for AI agents
+Author-email: Maulik Jadav <maulikjadav239@gmail.com>
+Maintainer-email: Maulik Jadav <maulikjadav239@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://cartha.in
+Project-URL: Documentation, https://cartha.in
+Project-URL: Repository, https://github.com/maulik-jadav/nexus
+Project-URL: Issues, https://github.com/maulik-jadav/nexus/issues
+Project-URL: Source, https://github.com/maulik-jadav/nexus/tree/main/nexus/packages/sdk-python
+Keywords: cartha,agents,llm,observability,tracing,memory,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# Cartha SDK (Python)
+
+Instrument AI agents with memory, traces, costs, and policies on [Cartha](https://cartha.in).
+
+## Install
+
+```bash
+pip install cartha-sdk
+```
+
+Requires Python 3.10+.
+
+From source (development):
+
+```bash
+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
+
+```bash
+export CARTHA_API_KEY="cartha_..."          # from the dashboard → Keys
+export CARTHA_API_BASE="https://cartha.in"  # your Cartha deployment
+```
+
+```python
+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
+
+```python
+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.
+
+```python
+@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:
+
+```python
+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):
+
+```python
+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):
+
+```bash
+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.

cartha_sdk-0.1.0/cartha_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+./cartha/__init__.py
+./nexus/__init__.py
+./nexus/ops.py
+cartha/__init__.py
+cartha_sdk.egg-info/PKG-INFO
+cartha_sdk.egg-info/SOURCES.txt
+cartha_sdk.egg-info/dependency_links.txt
+cartha_sdk.egg-info/requires.txt
+cartha_sdk.egg-info/top_level.txt
+nexus/__init__.py
+nexus/ops.py

cartha_sdk-0.1.0/cartha_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cartha_sdk-0.1.0/cartha_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27

cartha_sdk-0.1.0/cartha_sdk.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+cartha
+nexus

cartha_sdk-0.1.0/nexus/__init__.py

@@ -0,0 +1,8 @@
+"""Legacy import path kept for backward compatibility.
+
+Prefer ``import cartha`` / ``from cartha import ops`` in new code.
+"""
+
+from . import ops
+
+__all__ = ["ops"]