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",
    ))

Billing

Credit balance queries, ledger history, and manual credit adjustments for an organization. Commands require the can_manage_billing permission on the org:

from stigmer import StigmerClient, AdjustCreditsParams

with StigmerClient("sk_live_abc123") as client:
    balance = client.billing.get_credit_balance(org_id)

    entry = client.billing.adjust_credits(AdjustCreditsParams(
        org_id=org_id,
        amount_micros=25_000_000,  # +$25.00
        reason="initial tenant funding",
        idempotency_key=f"fund-{org_id}",
    ))

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stigmer-3.14.0.tar.gz (43.3 kB view details)

Uploaded Sep 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

stigmer-3.14.0-py3-none-any.whl (64.6 kB view details)

Uploaded Sep 10, 2026 Python 3

File details

Details for the file stigmer-3.14.0.tar.gz.

File metadata

Download URL: stigmer-3.14.0.tar.gz
Upload date: Sep 10, 2026
Size: 43.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for stigmer-3.14.0.tar.gz
Algorithm	Hash digest
SHA256	`b381e069d13a8467f4b2b2a4ec6b88a62d98d324ba48fb9577430977f2844b7a`
MD5	`448bf05435c1c9959fb2d37b709d730c`
BLAKE2b-256	`89191a3dd0da83b96ae42397c264d95428d6b9c43f9b12b9fea74887a1d8bfc6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for stigmer-3.14.0.tar.gz:

Publisher: release.python-sdk.yaml on stigmer/stigmer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: stigmer-3.14.0.tar.gz
- Subject digest: b381e069d13a8467f4b2b2a4ec6b88a62d98d324ba48fb9577430977f2844b7a
- Sigstore transparency entry: 2780872193
- Sigstore integration time: Sep 10, 2026
Source repository:
- Permalink: stigmer/stigmer@fafe0cf83e2e29367a8faeb40c09d9c8100a47d9
- Branch / Tag: refs/tags/v3.14.0
- Owner: https://github.com/stigmer
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.python-sdk.yaml@fafe0cf83e2e29367a8faeb40c09d9c8100a47d9
- Trigger Event: push