reasoning-ledger 0.1.0__py3-none-any.whl

reasoning_ledger/__init__.py

@@ -0,0 +1,83 @@
+"""
+reasoning-ledger — Python SDK for the Reasoning Ledger API.
+"""
+
+from .client import LedgerClient
+from .constants import ENDPOINTS, SCHEMA_VERSION, SIZE_LIMITS
+from .errors import (
+    AuthError,
+    IdempotencyConflictError,
+    LedgerError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .http import DEFAULT_RETRY, HttpxTransport, build_url, map_http_error, should_retry, with_retry
+from .session import Session
+from .types import (
+    AgentMetadata,
+    AgentRegistration,
+    AgentWalletInput,
+    BatchAck,
+    GetTraceOpts,
+    HttpRequest,
+    HttpResponse,
+    HttpTransport,
+    LedgerClientConfig,
+    RecordAck,
+    RecordError,
+    RegisterAgentOpts,
+    ResolveAgentOpts,
+    RetryConfig,
+    SessionFetch,
+    SubmitInput,
+    TracePage,
+)
+from .utils import is_valid_record_id, new_record_id, now_epoch_ms
+from .validate import validate_batch, validate_record
+
+__all__ = [
+    "DEFAULT_RETRY",
+    "ENDPOINTS",
+    "SCHEMA_VERSION",
+    "SIZE_LIMITS",
+    "AgentMetadata",
+    "AgentRegistration",
+    "AgentWalletInput",
+    "AuthError",
+    "BatchAck",
+    "GetTraceOpts",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpTransport",
+    "HttpxTransport",
+    "IdempotencyConflictError",
+    "LedgerClient",
+    "LedgerClientConfig",
+    "LedgerError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "RecordAck",
+    "RecordError",
+    "RegisterAgentOpts",
+    "ResolveAgentOpts",
+    "RetryConfig",
+    "ServerError",
+    "Session",
+    "SessionFetch",
+    "SubmitInput",
+    "TracePage",
+    "ValidationError",
+    "build_url",
+    "is_valid_record_id",
+    "map_http_error",
+    "new_record_id",
+    "now_epoch_ms",
+    "should_retry",
+    "validate_batch",
+    "validate_record",
+    "with_retry",
+]

reasoning_ledger/client.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from .constants import ENDPOINTS, SCHEMA_VERSION
+from .http import DEFAULT_RETRY, HttpxTransport, build_url, map_http_error, with_retry
+from .types import (
+    AgentRegistration,
+    BatchAck,
+    GetTraceOpts,
+    HttpTransport,
+    LedgerClientConfig,
+    RecordAck,
+    RecordError,
+    RegisterAgentOpts,
+    ResolveAgentOpts,
+    RetryConfig,
+    SessionFetch,
+    SubmitInput,
+    TracePage,
+)
+from .utils import new_record_id, now_epoch_ms
+from .validate import validate_batch, validate_record
+
+if TYPE_CHECKING:
+    from .session import Session
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_base_url(config: LedgerClientConfig) -> str:
+    if config.endpoint is not None:
+        return config.endpoint
+    return ENDPOINTS.get(config.environment, ENDPOINTS["production"])
+
+
+def _resolve_retry(config: LedgerClientConfig) -> RetryConfig:
+    return config.retry if config.retry is not None else DEFAULT_RETRY
+
+
+def _complete_record(
+    input_record: SubmitInput,
+    agent_id: str,
+    default_model_invocation: dict[str, Any] | None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = dict(input_record)
+    record.setdefault("agent_id", agent_id)
+    record.setdefault("client_ts_utc", now_epoch_ms())
+    record.setdefault("record_id", new_record_id())
+    record.setdefault("schema_version", SCHEMA_VERSION)
+    if record.get("model_invocation") is None and default_model_invocation is not None:
+        record["model_invocation"] = default_model_invocation
+    return record
+
+
+def _call_api(
+    transport: HttpTransport,
+    retry: RetryConfig,
+    *,
+    api_key: str,
+    method: str,
+    url: str,
+    body: Any = None,
+) -> Any:
+    headers: dict[str, str] = {
+        "content-type": "application/json",
+        "x-api-key": api_key,
+    }
+
+    def _do() -> Any:
+        req_body: str | None = json.dumps(body) if body is not None else None
+        res = transport.request(
+            {
+                "body": req_body,
+                "headers": headers,
+                "method": method,
+                "url": url,
+            }
+        )
+        status = res["status"]
+        if status < 200 or status >= 300:
+            map_http_error(res)
+        return json.loads(res["body"])
+
+    return with_retry(_do, retry)
+
+
+# ---------------------------------------------------------------------------
+# LedgerClient
+# ---------------------------------------------------------------------------
+
+
+class LedgerClient:
+    def __init__(self, config: LedgerClientConfig) -> None:
+        self._config = config
+        self._transport: HttpTransport = config.http_transport or HttpxTransport()
+        self._retry = _resolve_retry(config)
+        self._base_url = _resolve_base_url(config)
+
+    # -------------------------------------------------------------------------
+    # Class methods (static factory equivalents)
+    # -------------------------------------------------------------------------
+
+    @classmethod
+    def register_agent(
+        cls,
+        opts: RegisterAgentOpts,
+        *,
+        _transport: HttpTransport | None = None,
+    ) -> AgentRegistration:
+        """Register a new agent. Idempotent on (owner, name). See §6.4."""
+        transport: HttpTransport = _transport or HttpxTransport()
+        body: dict[str, Any] = {"name": opts.name}
+        if opts.metadata is not None:
+            if opts.metadata.description is not None:
+                body["description"] = opts.metadata.description
+            if opts.metadata.website is not None:
+                body["website"] = opts.metadata.website
+            if opts.metadata.tags is not None:
+                body["tags"] = opts.metadata.tags
+        # signer is a client-side callback — never sent to the server.
+        if opts.wallet is not None:
+            body["wallet"] = {"address": opts.wallet.address}
+
+        result = _call_api(
+            transport,
+            DEFAULT_RETRY,
+            api_key=opts.api_key,
+            method="POST",
+            url=f"{ENDPOINTS['production']}/v1/agents",
+            body=body,
+        )
+        return AgentRegistration(**result)  # type: ignore[misc]
+
+    @classmethod
+    def resolve_agent_id(
+        cls,
+        opts: ResolveAgentOpts,
+        *,
+        _transport: HttpTransport | None = None,
+    ) -> str:
+        """Resolve an agent's UUID by its human-readable name. See §7.3."""
+        transport: HttpTransport = _transport or HttpxTransport()
+        url = build_url(f"{ENDPOINTS['production']}/v1/agents", {"name": opts.name})
+        result = _call_api(
+            transport,
+            DEFAULT_RETRY,
+            api_key=opts.api_key,
+            method="GET",
+            url=url,
+        )
+        return str(result["agent_id"])
+
+    # -------------------------------------------------------------------------
+    # Instance methods
+    # -------------------------------------------------------------------------
+
+    def submit(self, input_record: SubmitInput) -> RecordAck:
+        """Submit a single record with auto-fill. Validates locally first."""
+        record = _complete_record(
+            input_record,
+            self._config.agent_id,
+            self._config.default_model_invocation,
+        )
+        validate_record(record)  # raises ValidationError on failure
+
+        result = _call_api(
+            self._transport,
+            self._retry,
+            api_key=self._config.api_key,
+            method="POST",
+            url=f"{self._base_url}/v1/records",
+            body=record,
+        )
+        return RecordAck(**result)  # type: ignore[misc]
+
+    def submit_batch(self, inputs: list[SubmitInput]) -> BatchAck:
+        """Submit up to 50 records. Per-record errors don't abort the batch."""
+        completed = [
+            _complete_record(inp, self._config.agent_id, self._config.default_model_invocation)
+            for inp in inputs
+        ]
+
+        # Raises on batch-level violations (count > 50, total > 1 MB).
+        errors = validate_batch(completed)
+
+        valid_records: list[tuple[int, dict[str, Any]]] = []
+        results: list[RecordAck | RecordError | None] = [None] * len(inputs)
+
+        for i, (rec, err) in enumerate(zip(completed, errors, strict=True)):
+            if err is not None:
+                record_id = str(rec.get("record_id", "(unknown)"))
+                results[i] = RecordError(
+                    code=err.code,
+                    message=str(err),
+                    record_id=record_id,
+                )
+            else:
+                valid_records.append((i, rec))
+
+        if not valid_records:
+            # All records failed local validation; synthesize a batch_id.
+            return BatchAck(
+                batch_id=str(uuid.uuid4()),
+                results=[r for r in results if r is not None],
+            )
+
+        server_response = _call_api(
+            self._transport,
+            self._retry,
+            api_key=self._config.api_key,
+            method="POST",
+            url=f"{self._base_url}/v1/records:batch",
+            body={"records": [rec for _, rec in valid_records]},
+        )
+
+        # Merge server results back at the correct indices.
+        server_results: list[Any] = server_response.get("results", [])
+        for j, (orig_idx, _) in enumerate(valid_records):
+            if j < len(server_results):
+                results[orig_idx] = server_results[j]
+
+        return BatchAck(
+            batch_id=str(server_response["batch_id"]),
+            results=[r for r in results if r is not None],
+        )
+
+    def get_record(self, record_id: str) -> dict[str, Any]:
+        """Fetch a single stored record by record_id."""
+        return _call_api(  # type: ignore[return-value]
+            self._transport,
+            self._retry,
+            api_key=self._config.api_key,
+            method="GET",
+            url=f"{self._base_url}/v1/records/{record_id}",
+        )
+
+    def get_session(self, session_id: str) -> SessionFetch:
+        """Fetch all records in a session. agent_id is auto-filled."""
+        url = build_url(
+            f"{self._base_url}/v1/sessions/{session_id}",
+            {"agent_id": self._config.agent_id},
+        )
+        result = _call_api(
+            self._transport,
+            self._retry,
+            api_key=self._config.api_key,
+            method="GET",
+            url=url,
+        )
+        return SessionFetch(**result)  # type: ignore[misc]
+
+    def get_trace(self, opts: GetTraceOpts | None = None) -> TracePage:
+        """Fetch paginated agent trace, newest-first. agent_id is auto-filled."""
+        _opts = opts or GetTraceOpts()
+        url = build_url(
+            f"{self._base_url}/v1/traces/{self._config.agent_id}",
+            {"before": _opts.before, "limit": _opts.limit},
+        )
+        result = _call_api(
+            self._transport,
+            self._retry,
+            api_key=self._config.api_key,
+            method="GET",
+            url=url,
+        )
+        return TracePage(**result)  # type: ignore[misc]
+
+    def new_session(self, session_id: str | None = None) -> Session:
+        """Create a Session bound to session_id (or a fresh UUID)."""
+        from .session import Session  # local import avoids circular
+
+        return Session(self, session_id)
+
+    # -------------------------------------------------------------------------
+    # Internal helpers exposed for Session
+    # -------------------------------------------------------------------------
+
+    def _submit(self, input_record: SubmitInput) -> RecordAck:
+        return self.submit(input_record)
+
+    def _submit_batch(self, inputs: list[SubmitInput]) -> BatchAck:
+        return self.submit_batch(inputs)

reasoning_ledger/constants.py

@@ -0,0 +1,49 @@
+# ---------------------------------------------------------------------------
+# Schema version — stamped on every submitted record.
+# ---------------------------------------------------------------------------
+
+SCHEMA_VERSION = "1.0"
+
+# ---------------------------------------------------------------------------
+# Base URLs per environment.
+# ---------------------------------------------------------------------------
+
+ENDPOINTS: dict[str, str] = {
+    "development": "http://localhost:3000",
+    "production": "https://api.stairai.com",
+    "staging": "https://staging.api.stairai.com",
+}
+
+# ---------------------------------------------------------------------------
+# Size limits (§10.2) — enforced client-side before any network call.
+# Values are in bytes for JSON-encoded fields, or item counts for arrays.
+# ---------------------------------------------------------------------------
+
+SIZE_LIMITS: dict[str, int] = {
+    # Acting.parameters JSON-encoded size (16 KB).
+    "ACTING_PARAMETERS": 16 * 1024,
+    # Per-batch total JSON-encoded size (1 MB).
+    "BATCH_JSON": 1024 * 1024,
+    # notes field on BaseRecord (2 KB).
+    "NOTES": 2048,
+    # Other.data JSON-encoded size (16 KB).
+    "OTHER_DATA": 16 * 1024,
+    # Per-record total JSON-encoded size (64 KB).
+    "RECORD_JSON": 64 * 1024,
+    # Maximum number of tags on a record (32 items).
+    "TAGS_COUNT": 32,
+    # Each individual tag string (64 chars).
+    "TAG_LENGTH": 64,
+    # Thinking.output_payload (32 KB).
+    "THINKING_OUTPUT": 32 * 1024,
+    # Thinking.prompt (16 KB).
+    "THINKING_PROMPT": 16 * 1024,
+    # ToolCalling.input_payload JSON-encoded size (16 KB).
+    "TOOL_INPUT": 16 * 1024,
+    # ToolCalling.tool_meta JSON-encoded size (16 KB).
+    "TOOL_META": 16 * 1024,
+    # ToolCalling.output_payload JSON-encoded size (32 KB).
+    "TOOL_OUTPUT": 32 * 1024,
+    # Observing.trigger_payload_summary (4 KB).
+    "TRIGGER_PAYLOAD_SUMMARY": 4096,
+}

reasoning_ledger/errors.py

@@ -0,0 +1,73 @@
+# ---------------------------------------------------------------------------
+# LedgerError — base class for all SDK errors.
+# Partners may branch on the class hierarchy or on the stable `code` string.
+# ---------------------------------------------------------------------------
+
+
+class LedgerError(Exception):
+    code: str
+    details: dict[str, object] | None
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        details: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.details = details
+
+
+# ---------------------------------------------------------------------------
+# Subclasses (§7.10)
+# ---------------------------------------------------------------------------
+
+
+class ValidationError(LedgerError):
+    """Local schema check failed; the record never reached the network."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("validation_failed", message, details)
+
+
+class AuthError(LedgerError):
+    """API key rejected or unknown to the server."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("auth_invalid", message, details)
+
+
+class RateLimitError(LedgerError):
+    """Server returned a rate-limit signal."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("rate_limited", message, details)
+
+
+class NetworkError(LedgerError):
+    """Request never reached the server after exhausting retries."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("network_failed", message, details)
+
+
+class ServerError(LedgerError):
+    """Server returned a non-retryable 5xx."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("server_5xx", message, details)
+
+
+class IdempotencyConflictError(LedgerError):
+    """The same record_id was previously submitted with a different body."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("record_id_conflict", message, details)
+
+
+class NotFoundError(LedgerError):
+    """Lookup target does not exist or is not visible to the calling owner."""
+
+    def __init__(self, message: str, details: dict[str, object] | None = None) -> None:
+        super().__init__("not_found", message, details)

reasoning_ledger/generated/__init__.py

@@ -0,0 +1,2 @@
+# Generated package — do not edit manually.
+from .records import *

reasoning_ledger/generated/records.py

@@ -0,0 +1,208 @@
+# generated by datamodel-codegen:
+#   filename:  records.schema.json
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+
+class BehaviorType(StrEnum):
+    Observing = "Observing"
+    ToolCalling = "ToolCalling"
+    Planning = "Planning"
+    Thinking = "Thinking"
+    Acting = "Acting"
+    Reflecting = "Reflecting"
+    Other = "Other"
+
+
+class UuidV4(RootModel[UUID]):
+    root: UUID
+
+
+class ModelInvocation(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    provider: Annotated[str, Field(min_length=1)]
+    model_name: Annotated[str, Field(min_length=1)]
+    model_version: str | None = None
+    tokens_in: Annotated[int | None, Field(ge=0)] = None
+    tokens_out: Annotated[int | None, Field(ge=0)] = None
+    cost_usd: Annotated[float | None, Field(ge=0.0)] = None
+    temperature: float | None = None
+    finish_reason: str | None = None
+
+
+class Tag(RootModel[str]):
+    root: Annotated[str, Field(max_length=64)]
+
+
+class BaseRecord(BaseModel):
+    schema_version: Annotated[str, Field(examples=["1.0"], min_length=1)]
+    agent_id: UUID
+    session_id: Annotated[str, Field(min_length=1)]
+    record_id: UUID
+    behavior: BehaviorType
+    client_ts_utc: Annotated[int, Field(ge=0)]
+    notes: Annotated[str | None, Field(max_length=2048)] = None
+    tags: Annotated[list[Tag] | None, Field(max_length=32)] = None
+    model_invocation: ModelInvocation | None = None
+    upstream_record_id: Annotated[
+        list[UUID] | None,
+        Field(
+            description="DAG dependency / trace sequence. Records this one builds on. May be empty/omitted.",
+            max_length=32,
+        ),
+    ] = None
+    parent_record_id: Annotated[
+        UUID | None,
+        Field(
+            description="Sub-thread / sub-process containment. Set when this record is produced inside a sub-thread spawned by another record. Records outside the sub-thread do not list internal sub-thread records as upstream. For ordinary DAG dependencies use upstream_record_id instead."
+        ),
+    ] = None
+
+
+class ThinkingInput(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    input_record_id: UUID | None = None
+    input_payload: str
+
+
+class ReflectingInput(ThinkingInput):
+    pass
+
+
+class DependsOnItem(RootModel[int]):
+    root: Annotated[int, Field(ge=0)]
+
+
+class PlanningStep(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    index: Annotated[int, Field(ge=0)]
+    description: Annotated[str, Field(min_length=1)]
+    depends_on: list[DependsOnItem] | None = None
+
+
+class TriggerType(StrEnum):
+    signal_trigger = "signal_trigger"
+    cron_trigger = "cron_trigger"
+
+
+class ObservingRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Observing"]
+    trigger_source: Annotated[str, Field(min_length=1)]
+    trigger_type: TriggerType
+    external_trigger_id: str | None = None
+    event_ts_utc: Annotated[int | None, Field(ge=0)] = None
+    trigger_description: Annotated[str, Field(min_length=1)]
+    trigger_payload_summary: Annotated[str, Field(max_length=4096)]
+
+
+class ToolCallingRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["ToolCalling"]
+    tool_meta: dict[str, Any]
+    description: Annotated[str, Field(min_length=1)]
+    input_payload: Any
+    output_payload: Any
+    success: bool
+
+
+class PlanningRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Planning"]
+    goal: Annotated[str, Field(min_length=1)]
+    steps: list[PlanningStep]
+    contingencies: list[str] | None = None
+
+
+class ThinkingRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Thinking"]
+    prompt: Annotated[str, Field(min_length=1)]
+    inputs: list[ThinkingInput]
+    output_payload: Annotated[str, Field(min_length=1)]
+
+
+class ExecutionStatus(StrEnum):
+    confirmed = "confirmed"
+    failed = "failed"
+    simulated = "simulated"
+    pending = "pending"
+
+
+class ActingRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Acting"]
+    action_type: Annotated[str, Field(min_length=1)]
+    target_system: Annotated[str, Field(min_length=1)]
+    action_summary: Annotated[str, Field(min_length=1)]
+    parameters: dict[str, Any]
+    dry_run: bool
+    execution_id: str | None = None
+    execution_status: ExecutionStatus
+
+
+class ReflectingRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Reflecting"]
+    inputs: list[ReflectingInput]
+    output_payload: Annotated[str, Field(min_length=1)]
+
+
+class OtherRecord(BaseRecord):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    behavior: Literal["Other"]
+    label: Annotated[str, Field(min_length=1)]
+    data: dict[str, Any]
+
+
+class ReasoningLedgerRecordSchemas(
+    RootModel[
+        ObservingRecord
+        | ToolCallingRecord
+        | PlanningRecord
+        | ThinkingRecord
+        | ActingRecord
+        | ReflectingRecord
+        | OtherRecord
+    ]
+):
+    root: Annotated[
+        ObservingRecord
+        | ToolCallingRecord
+        | PlanningRecord
+        | ThinkingRecord
+        | ActingRecord
+        | ReflectingRecord
+        | OtherRecord,
+        Field(
+            description="Canonical record schemas for sections 4.1-4.8 of Reasoning_Ledger_SDK_Design_v1.",
+            discriminator="behavior",
+            title="Reasoning Ledger Record Schemas",
+        ),
+    ]