SDK Reference

Complete Python API reference. Node.js SDK is planned — not yet shipped.

spineforge.init()

The single entry point. Returns a Spine handle.

def init(
    agent_name: str,
    allowed_scopes: list[str] | None = None,
    **kwargs
) -> Spine

Spine class

The agent handle returned by init().

class Spine:
    agent_name: str     # The name passed to init()
    spine_id:   str     # Server-assigned UUID (or local UUID in offline mode)
    created_at: str     # ISO 8601 timestamp of registration

    def run(self, input: str = "") -> Run:
        """Create a Run context manager."""

    def lease_credential(self, secret_name: str) -> str:
        """Lease a provider secret. Requires registry_url and credential:lease scope."""

    def request_token(
        self,
        scopes: list[str],
        aud: str | None = None
    ) -> str:
        """Request a scoped JWT. Returns the raw JWT string."""

Spine.run()

Context manager for a single top-level agent invocation.

with spine.run(input="user query text") as run:
    result = do_agent_work(...)
    run.set_output(result)

# run.run_id  — UUID for this run
# run.set_output(value: Any) — record final output

• __enter__: emits run / running event, sets run_id in ContextVar for all spans
• __exit__: force-flushes TracerProvider, emits run / success or run / error, flushes sinks
• Never suppresses exceptions — return False from __exit__

Spine.lease_credential()

value = spine.lease_credential(secret_name: str) -> str

• Internally calls request_token(scopes=["credential:lease"]) then POST /credentials/lease
• Returns the raw secret value as a string
• Raises RuntimeError if no registry URL is configured
• Raises RegistryError on network / auth failures

Spine.request_token()

token = spine.request_token(
    scopes: list[str],
    aud: str | None = None   # defaults to "registry"
) -> str

• Signs a JWT assertion with the agent's private key
• Submits to POST /auth/token
• Returns the raw JWT string
• Raises RuntimeError if no registry URL is configured
• Raises RegistryError if scopes are not granted

@track_tool decorator

from spineforge import track_tool

@track_tool
def my_tool_function(arg1: str, arg2: int) -> str:
    ...

• Emits a tool_call action spanning the function's execution
• Captures: function name, duration, success/error status, error message if exception
• Does not capture function arguments or return value (privacy)
• Required for raw SDK agents. Not needed for LangChain / LangGraph / CrewAI / AutoGen — those are auto-instrumented

SpineforgeConfig

All configuration in one place. Read from env, overridden by kwargs.

@dataclass(frozen=True)
class SpineforgeConfig:
    data_dir:      Path   # .spineforge/ parent directory
    log_file:      str    # JSONL filename
    verbose:       bool   # ConsoleSink on/off
    trace_content: bool   # Capture prompt/completion text
    registry_url:  str    # Backend URL — empty = offline

    # Derived paths
    @property
    def spineforge_dir(self) -> Path: ...  # <data_dir>/.spineforge/
    @property
    def registry_path(self) -> Path: ...  # .../registry.json
    @property
    def key_path(self) -> Path: ...       # .../agent_key.pem
    @property
    def log_path(self) -> Path: ...       # .../logs/<log_file>

RunEvent and ActionEvent

@dataclass
class RunEvent:
    event:      Literal["run"]
    run_id:     str
    spine_id:   str
    agent_name: str
    started_at: str         # ISO 8601
    status:     Literal["running", "success", "error"]
    ended_at:   str | None
    input:      str | None
    output:     str | None
    error:      str | None

@dataclass
class ActionEvent:
    event:      Literal["action"]
    action_id:  str
    run_id:     str
    spine_id:   str
    type:       Literal["llm_call", "tool_call"]
    name:       str         # model name or tool function name
    duration_ms: int
    status:     Literal["success", "error"]
    tokens:     dict | None  # {"prompt": N, "completion": N, "total": N}
    cost_usd:   float | None
    rate_card_id: str | None
    error:      str | None

Node.js SDK

Next steps

• Quickstart — minimal working example
• Framework Setup — per-framework wiring
• Sinks — configure telemetry output