tars-sdk 0.1.1__tar.gz

tars_sdk-0.1.1/.gitignore

@@ -0,0 +1,56 @@
+# Node
+node_modules/
+*.tsbuildinfo
+*.log
+
+# Environment / secrets — commit only the .example files
+.env
+.env.*
+!.env.example
+
+# Terraform — providers, state, and real tfvars (contain subscription IDs)
+**/.terraform/
+*.tfstate
+*.tfstate.*
+terraform.tfvars
+!terraform.tfvars.example
+
+# Restate local data (journals, ledger)
+restate-data/
+
+# OS
+.DS_Store
+
+# Terraform saved plans
+tfplan
+
+# built SDK artifacts
+sdk/dist/
+
+# Next.js
+.next/
+backend/dist/
+frontend/.next/
+frontend/next-env.d.ts
+website/next-env.d.ts
+website/package-lock.json
+
+# Claude Code — machine-local permission state and per-task worktrees
+# (EnterWorktree). settings.json IS tracked; settings.local.json is not.
+.claude/settings.local.json
+.claude/worktrees/
+
+# Verification screenshots never belong at the repo root
+/*.png
+/*.jpg
+
+# .NET build output (sdk-dotnet, examples/chat-dotnet)
+bin/
+obj/
+
+# Python (sdk-python, examples/chat-python)
+.venv/
+__pycache__/
+*.egg-info/
+sdk-python/dist/
+.pytest_cache/

tars_sdk-0.1.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# tars-sdk
+
+Tenant-facing record of the Python SDK, newest first. Each entry names the
+minimum TARS backend it needs. The version lives in `pyproject.toml`; bump
+it in the same PR as the entry, and label that PR `release-approved` once
+prd runs that backend — merging it publishes.
+
+## 0.1.1
+
+First published release. Needs TARS backend ≥ `prd-20261108-2059-sha-918f00a7`.
+
+- `TarsClient(api_key, base_url=, provider_keys=, act_as_tenant=, http_client=)`:
+  BYOK provider keys as one `x-tars-key-<provider>` header per key, never
+  stored; `act_as_tenant` for admin keys (read-only); an injectable
+  `httpx.AsyncClient`. Async context manager; `aclose()`.
+- `agents`: create, list, get, update, archive, unarchive, versions. On
+  `update`, omitted keywords are unchanged and `None` clears a clearable
+  field (description, tools, metadata, mcp_servers, skills, environment,
+  reasoning).
+- `sessions`: create (with client-executed tools), open, list, get, events,
+  rename, set_mcp_servers, set_custom_tools, interrupt, compact, usage,
+  destroy.
+- `TarsSession`: `send` (streams the turn and runs your tool handlers, sync
+  or async), `send_raw`, `stream` (replay + live tail), `resume` (current
+  turn only), `mount_file`, `attach_file`, `interrupt`, `compact`, `destroy`.
+- `files`: upload, upload_text, list, get, download (stream), download_bytes.
+- `skills`: create, list, get, versions, push_version, download_version.
+- `mcp_credentials`: set (`BearerCredential` / `OAuthCredential`), list,
+  delete; `mcp.list_tools`.
+- `usage`: get (from/to/session/end-user filters), daily, sessions. Dates
+  are `datetime` (naive = UTC) or ISO strings, sent as UTC ISO 8601.
+- `api_keys`: create (key returned once), list, revoke.
+- `completions.create`; `admin` (admin keys): tenants, their keys, stats.
+- `me`, `providers`, `provider_status`, `models`.
+- Typed events: one dataclass per journal event type, `UnknownEvent` for
+  types newer than the SDK, `raw` on every event. `SESSION_EVENT_TYPES` and
+  `AGENT_ERROR_CODES` are pinned to the backend taxonomy by a test.
+- `TarsApiError` with `status`, the stable `code` from the error envelope,
+  and the raw `body`.
+
+## 0.1.0
+
+Never published: PyPI refused the `tars_sdk-0.1.0` filenames because an
+unrelated, since-deleted upload had used them once, and PyPI never lets a
+filename be reused. 0.1.1 is the same code.

tars_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: tars-sdk
+Version: 0.1.1
+Summary: Client SDK for TARS — the self-hosted managed-agents platform (agents, durable sessions, streaming turns, client-executed tools, files).
+Project-URL: Homepage, https://github.com/LegendariTech/tars
+Project-URL: Repository, https://github.com/LegendariTech/tars
+Project-URL: Changelog, https://github.com/LegendariTech/tars/blob/dev/sdk-python/CHANGELOG.md
+Author: Legendari
+License-Expression: MIT
+Keywords: agents,ai,anthropic,mcp,sdk,tars
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tars-sdk
+
+Python client for [TARS](https://github.com/LegendariTech/tars) — a
+self-hosted managed-agents platform: server-side agent loops in sandboxes,
+an append-only session event log with SSE streaming + replay, client-executed
+tools, files, and usage metering.
+
+```bash
+pip install tars-sdk
+```
+
+Python 3.10+, async (`asyncio`), one dependency (`httpx`).
+
+## Quickstart
+
+```python
+import asyncio, os
+from tars_sdk import TarsClient, TextDeltaEvent
+
+async def main():
+    async with TarsClient(
+        api_key=os.environ["TARS_API_KEY"],          # tars_sk_…
+        base_url="https://your-tars-host",
+        provider_keys={"openrouter": os.environ["OPENROUTER_API_KEY"]},
+    ) as tars:
+        agent = await tars.agents.create(
+            name="assistant",
+            system="You are a helpful assistant.",
+            model="openrouter/anthropic/claude-sonnet-5",
+        )
+        session = await tars.sessions.create(agent_id=agent.id)
+        async for ev in session.send("Summarize the attached file."):
+            if isinstance(ev, TextDeltaEvent):
+                print(ev.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+## Streaming surfaces
+
+- `session.send(text)` — yields the turn's events; client-executed tools
+  you registered (`tools=` on `sessions.create` / `session.on_tool_call`)
+  are run and their results returned to the turn automatically. Handlers
+  may be sync or async.
+- `session.send_raw(text)` — same events, **no auto-dispatch**: hosts
+  that own their tool dispatcher consume this.
+- `session.stream(after)` — replay the journal after a seq, then
+  live-tail; survives restarts.
+- `session.resume(after)` — reconnect to the current turn only.
+
+Every event is a `SessionEvent` dataclass (`TextDeltaEvent`,
+`ToolCallEvent`, `TurnEndEvent`, …); a type newer than this SDK arrives as
+`UnknownEvent` with the payload in `raw`. Non-2xx answers raise
+`TarsApiError` with `status` and the stable `code`.
+
+## Everything else
+
+`tars.skills`, `tars.mcp_credentials`, `tars.mcp.list_tools`, `tars.usage`,
+`tars.api_keys`, `tars.completions` and `tars.admin` (admin keys) cover the
+rest of the API, one typed method per `/v1/*` route. On
+`agents.update`, a keyword you do not pass is unchanged; passing `None` for
+a clearable field (description, tools, metadata, mcp_servers, skills,
+environment, reasoning) clears it.
+
+Full docs: the TARS docs site, *SDK for Python* page.

tars_sdk-0.1.1/README.md

@@ -0,0 +1,65 @@
+# tars-sdk
+
+Python client for [TARS](https://github.com/LegendariTech/tars) — a
+self-hosted managed-agents platform: server-side agent loops in sandboxes,
+an append-only session event log with SSE streaming + replay, client-executed
+tools, files, and usage metering.
+
+```bash
+pip install tars-sdk
+```
+
+Python 3.10+, async (`asyncio`), one dependency (`httpx`).
+
+## Quickstart
+
+```python
+import asyncio, os
+from tars_sdk import TarsClient, TextDeltaEvent
+
+async def main():
+    async with TarsClient(
+        api_key=os.environ["TARS_API_KEY"],          # tars_sk_…
+        base_url="https://your-tars-host",
+        provider_keys={"openrouter": os.environ["OPENROUTER_API_KEY"]},
+    ) as tars:
+        agent = await tars.agents.create(
+            name="assistant",
+            system="You are a helpful assistant.",
+            model="openrouter/anthropic/claude-sonnet-5",
+        )
+        session = await tars.sessions.create(agent_id=agent.id)
+        async for ev in session.send("Summarize the attached file."):
+            if isinstance(ev, TextDeltaEvent):
+                print(ev.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+## Streaming surfaces
+
+- `session.send(text)` — yields the turn's events; client-executed tools
+  you registered (`tools=` on `sessions.create` / `session.on_tool_call`)
+  are run and their results returned to the turn automatically. Handlers
+  may be sync or async.
+- `session.send_raw(text)` — same events, **no auto-dispatch**: hosts
+  that own their tool dispatcher consume this.
+- `session.stream(after)` — replay the journal after a seq, then
+  live-tail; survives restarts.
+- `session.resume(after)` — reconnect to the current turn only.
+
+Every event is a `SessionEvent` dataclass (`TextDeltaEvent`,
+`ToolCallEvent`, `TurnEndEvent`, …); a type newer than this SDK arrives as
+`UnknownEvent` with the payload in `raw`. Non-2xx answers raise
+`TarsApiError` with `status` and the stable `code`.
+
+## Everything else
+
+`tars.skills`, `tars.mcp_credentials`, `tars.mcp.list_tools`, `tars.usage`,
+`tars.api_keys`, `tars.completions` and `tars.admin` (admin keys) cover the
+rest of the API, one typed method per `/v1/*` route. On
+`agents.update`, a keyword you do not pass is unchanged; passing `None` for
+a clearable field (description, tools, metadata, mcp_servers, skills,
+environment, reasoning) clears it.
+
+Full docs: the TARS docs site, *SDK for Python* page.

tars_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tars-sdk"
+# Bumped by hand in the PR that adds the CHANGELOG entry; Verify refuses the
+# bump without the `release-approved` label; merging publishes to PyPI.
+version = "0.1.1"
+description = "Client SDK for TARS — the self-hosted managed-agents platform (agents, durable sessions, streaming turns, client-executed tools, files)."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Legendari" }]
+keywords = ["agents", "ai", "mcp", "anthropic", "sdk", "tars"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+# httpx is the one dependency: async HTTP with streaming responses, the
+# transport seam tests use (MockTransport), and HTTP/2-ready.
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://github.com/LegendariTech/tars"
+Repository = "https://github.com/LegendariTech/tars"
+Changelog = "https://github.com/LegendariTech/tars/blob/dev/sdk-python/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tars_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tars_sdk", "README.md", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

tars_sdk-0.1.1/src/tars_sdk/__init__.py

@@ -0,0 +1,219 @@
+"""tars-sdk — the Python client for TARS.
+
+    from tars_sdk import TarsClient, TextDeltaEvent
+
+    async with TarsClient(api_key="tars_sk_…", base_url="https://your-tars-host") as tars:
+        agent = await tars.agents.create(name="assistant", system="You are helpful.")
+        session = await tars.sessions.create(agent_id=agent.id)
+        async for ev in session.send("Hello!"):
+            if isinstance(ev, TextDeltaEvent):
+                print(ev.text, end="")
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from ._wire import UNSET
+from .client import (
+    DEFAULT_BASE_URL,
+    KEYED_PROVIDERS,
+    AdminClient,
+    AgentsClient,
+    ApiKeysClient,
+    CompletionsClient,
+    FilesClient,
+    McpClient,
+    McpCredentialsClient,
+    SessionsClient,
+    SkillsClient,
+    TarsClient,
+    UsageClient,
+)
+from .errors import TarsApiError
+from .events import (
+    AGENT_ERROR_CODES,
+    SESSION_EVENT_TYPES,
+    CompactionEvent,
+    ConnectRequiredEvent,
+    ErrorEvent,
+    McpConnectEvent,
+    MessageAttachment,
+    OutputFileEvent,
+    SessionEvent,
+    StatusEvent,
+    TextDeltaEvent,
+    TextEndEvent,
+    TextStartEvent,
+    ToolCallEvent,
+    ToolResultEvent,
+    TurnEndEvent,
+    TurnStartEvent,
+    TurnUsage,
+    UnknownEvent,
+    UserMessageEvent,
+    parse_event,
+)
+from .models import (
+    Agent,
+    AgentEnvironment,
+    AgentPackages,
+    AgentStatusResult,
+    AgentVersion,
+    ApiKeyInfo,
+    AttachResult,
+    BearerCredential,
+    BuiltinToolInfo,
+    ClientIdentity,
+    ClientTool,
+    ClientToolDeclaration,
+    CompactResult,
+    CompletionResult,
+    CompletionUsage,
+    CreatedApiKey,
+    CreatedTenant,
+    DailyUsageRow,
+    FileMeta,
+    InterruptResult,
+    McpCredential,
+    McpCredentialStatus,
+    McpServer,
+    McpServerTools,
+    McpToolAnnotations,
+    McpToolInfo,
+    ModelInfo,
+    ModelPricing,
+    MountResult,
+    OAuthCredential,
+    OkResult,
+    PlatformStats,
+    PlatformUsageTotals,
+    ProviderStatus,
+    ProviderStatusReport,
+    ReasoningConfig,
+    SessionClientTool,
+    SessionEventsPage,
+    SessionInfo,
+    SessionListItem,
+    SessionsPage,
+    SessionToolSurface,
+    SessionUsage,
+    SessionUsageFigures,
+    SessionUsageRow,
+    Skill,
+    SkillPin,
+    SkillVersion,
+    SkillVersionPushed,
+    Tenant,
+    TenantCounts,
+    TenantDetail,
+    TenantFirstKey,
+    TenantStats,
+    ToolHandler,
+    UsageBreakdownRow,
+    UsageSummary,
+    UsageTotals,
+)
+from .session import TarsSession
+
+try:
+    __version__ = _version("tars-sdk")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AGENT_ERROR_CODES",
+    "DEFAULT_BASE_URL",
+    "KEYED_PROVIDERS",
+    "SESSION_EVENT_TYPES",
+    "UNSET",
+    "AdminClient",
+    "Agent",
+    "AgentEnvironment",
+    "AgentPackages",
+    "AgentStatusResult",
+    "AgentVersion",
+    "AgentsClient",
+    "ApiKeyInfo",
+    "ApiKeysClient",
+    "AttachResult",
+    "BearerCredential",
+    "BuiltinToolInfo",
+    "ClientIdentity",
+    "ClientTool",
+    "ClientToolDeclaration",
+    "CompactResult",
+    "CompactionEvent",
+    "CompletionResult",
+    "CompletionUsage",
+    "CompletionsClient",
+    "ConnectRequiredEvent",
+    "CreatedApiKey",
+    "CreatedTenant",
+    "DailyUsageRow",
+    "ErrorEvent",
+    "FileMeta",
+    "FilesClient",
+    "InterruptResult",
+    "McpClient",
+    "McpConnectEvent",
+    "McpCredential",
+    "McpCredentialStatus",
+    "McpCredentialsClient",
+    "McpServer",
+    "McpServerTools",
+    "McpToolAnnotations",
+    "McpToolInfo",
+    "MessageAttachment",
+    "ModelInfo",
+    "ModelPricing",
+    "MountResult",
+    "OAuthCredential",
+    "OkResult",
+    "OutputFileEvent",
+    "PlatformStats",
+    "PlatformUsageTotals",
+    "ProviderStatus",
+    "ProviderStatusReport",
+    "ReasoningConfig",
+    "SessionClientTool",
+    "SessionEvent",
+    "SessionEventsPage",
+    "SessionInfo",
+    "SessionListItem",
+    "SessionToolSurface",
+    "SessionUsage",
+    "SessionUsageFigures",
+    "SessionUsageRow",
+    "SessionsClient",
+    "SessionsPage",
+    "Skill",
+    "SkillPin",
+    "SkillVersion",
+    "SkillVersionPushed",
+    "SkillsClient",
+    "StatusEvent",
+    "TarsApiError",
+    "TarsClient",
+    "TarsSession",
+    "Tenant",
+    "TenantCounts",
+    "TenantDetail",
+    "TenantFirstKey",
+    "TenantStats",
+    "TextDeltaEvent",
+    "TextEndEvent",
+    "TextStartEvent",
+    "ToolCallEvent",
+    "ToolHandler",
+    "ToolResultEvent",
+    "TurnEndEvent",
+    "TurnStartEvent",
+    "TurnUsage",
+    "UnknownEvent",
+    "UsageBreakdownRow",
+    "UsageClient",
+    "UsageSummary",
+    "UsageTotals",
+    "UserMessageEvent",
+    "__version__",
+    "parse_event",
+]

tars_sdk-0.1.1/src/tars_sdk/_sse.py

@@ -0,0 +1,33 @@
+"""Minimal SSE reader for the session streams.
+
+TARS writes ``id: <seq>\\ndata: <json>\\n\\n`` per event (``backend/src/http/sse.ts``);
+the seq is also inside the JSON, so ``id:`` is ignored. ``data:`` lines of one
+frame are joined, a blank line ends the frame, EOF flushes a frame the server
+closed without a blank line.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+import httpx
+
+from .events import SessionEvent, parse_event
+
+
+async def read_events(response: httpx.Response) -> AsyncIterator[SessionEvent]:
+    data: list[str] = []
+    async for line in response.aiter_lines():
+        if line == "":
+            if data:
+                yield parse_event(json.loads("".join(data)))
+                data = []
+            continue
+        if line.startswith("data: "):
+            data.append(line[6:])
+        elif line.startswith("data:"):
+            data.append(line[5:])
+        # id:, event:, retry:, comments — not used by this stream.
+    if data:
+        yield parse_event(json.loads("".join(data)))

tars_sdk-0.1.1/src/tars_sdk/_wire.py

@@ -0,0 +1,49 @@
+"""Request-body helpers.
+
+``UNSET`` lets a method tell "the caller did not pass this" from "the caller
+passed ``None``": for a PATCH that is "leave it" versus "clear it". ``body()``
+drops the SDK's own unset/None fields; the caller's data inside them (tool
+outputs, input schemas, metadata) is passed through verbatim.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+
+class _Unset:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET: Final = _Unset()
+"""Default for optional update fields: not sent. Pass ``None`` to clear a field."""
+
+
+def body(**fields: Any) -> dict[str, Any]:
+    """The SDK's own top-level fields, minus the ones left ``None``/``UNSET``."""
+    return {k: v for k, v in fields.items() if v is not None and v is not UNSET}
+
+
+def patch(**fields: Any) -> dict[str, Any]:
+    """Like :func:`body`, but a ``None`` is kept (sent as JSON ``null``); only ``UNSET`` is dropped."""
+    return {k: v for k, v in fields.items() if v is not UNSET}
+
+
+def iso(at: Any) -> str:
+    """UTC ISO 8601 with milliseconds and ``Z``, the shape the API expects."""
+    from datetime import datetime, timezone
+
+    if isinstance(at, str):
+        return at
+    if not isinstance(at, datetime):
+        raise TypeError(f"expected a datetime or ISO string, got {type(at).__name__}")
+    if at.tzinfo is None:
+        at = at.replace(tzinfo=timezone.utc)
+    at = at.astimezone(timezone.utc)
+    return at.strftime("%Y-%m-%dT%H:%M:%S.") + f"{at.microsecond // 1000:03d}Z"