stigmer 0.4.0

Stigmer Python SDK — typed API client for all Stigmer platform resources

stigmer

Python SDK for the Stigmer platform. Provides typed API clients for all Stigmer resources with authentication, error handling, and cross-resource search.

Installation

pip install stigmer

stigmer-protos (generated protobuf stubs) is installed automatically as a dependency.

Quick Start

from stigmer import StigmerClient, AgentInput

with StigmerClient("sk_live_abc123") as client:
    agent = client.agents.create(AgentInput(name="my-agent", org="my-org"))
    print(agent.metadata.name)

Or without a context manager:

client = StigmerClient("sk_live_abc123")
agent = client.agents.get("agent-id")
client.close()

Resource Clients

Every resource type has a typed client accessible as a property on StigmerClient:

Property	Resource
agents	Agent
agent_executions	AgentExecution
agent_instances	AgentInstance
api_keys	ApiKey
environments	Environment
execution_contexts	ExecutionContext
iam_policies	IamPolicy
identity_accounts	IdentityAccount
identity_providers	IdentityProvider
mcp_servers	McpServer
organizations	Organization
projects	Project
sessions	Session
skills	Skill
workflows	Workflow
workflow_executions	WorkflowExecution
workflow_instances	WorkflowInstance
search	Cross-resource search

Common Operations

from stigmer import StigmerClient, AgentInput, ListParams, ResourceRef, Page

with StigmerClient("sk_live_abc123") as client:
    # Create
    agent = client.agents.create(AgentInput(
        name="my-agent",
        org="my-org",
        description="Handles customer inquiries",
        instructions="Be helpful and concise.",
    ))

    # Get by ID
    agent = client.agents.get("agent-id")

    # Get by reference (org + slug)
    agent = client.agents.get_by_reference(ResourceRef(org="my-org", slug="my-agent"))

    # Update
    updated = client.agents.update(AgentInput(
        name="my-agent",
        org="my-org",
        description="Updated description",
    ))

    # Delete
    deleted = client.agents.delete("agent-id")

    # List (search-backed)
    results = client.agents.list(ListParams(
        org="my-org",
        query="customer",
        page=Page(num=1, size=20),
    ))

Cross-Resource Search

from stigmer import StigmerClient, ApiResourceKind, SearchParams

with StigmerClient("sk_live_abc123") as client:
    results = client.search.query(SearchParams(
        kinds=[ApiResourceKind.agent, ApiResourceKind.skill],
        org="my-org",
        query="customer support",
    ))

Error Handling

All SDK operations raise StigmerError with structured error codes:

from stigmer import StigmerClient, StigmerError, is_not_found, is_retryable

with StigmerClient("sk_live_abc123") as client:
    try:
        agent = client.agents.get("nonexistent")
    except StigmerError as err:
        if is_not_found(err):
            print("Agent not found")
        elif is_retryable(err):
            print("Transient error, retry later")
        else:
            print(f"Error [{err.code.value}]: {err}")

Error codes: not-found, permission-denied, unauthenticated, invalid-argument, already-exists, resource-exhausted, failed-precondition, internal, unavailable, cancelled, unknown.

Configuration

StigmerClient(
    api_key: str,               # Stigmer API key (required)
    *,
    base_url: str = "api.stigmer.ai:443",  # gRPC target address
    insecure: bool = False,     # Skip TLS (local development only)
)

Code Generation

The resource clients in src/stigmer/_gen/ are generated from protobuf service schemas. To regenerate after proto changes:

cd sdk/python
make codegen

Handwritten code lives in src/stigmer/ (outside _gen/): _client.py, _transport.py, _interceptors.py, _search.py, and __init__.py.