tars-sdk 0.1.1__py3-none-any.whl

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/_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/_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"