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 |
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. Queries require can_view_billing on the org and the org's own
billing commands require can_manage_billing. Adding or removing credits
without a purchase (adjust_credits, grant_credits) requires
can_manage_credits on the platform, held by platform operators and by the
funding identities Stigmer makes credit issuers:
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="support credit for an outage",
idempotency_key=f"support-{org_id}-2026-09",
))
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.
1 maintainer
Release files for stigmer 3.30.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stigmer-3.30.0.tar.gz | 45.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stigmer-3.30.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 114.9 kB
Release files / stigmer-3.30.0.tar.gz
| Download URL | stigmer-3.30.0.tar.gz |
|---|---|
| Size | 45.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f4eb392aa97b4ac26cd7079d35123d96ec78b026b9915c052528da0d8e6f9049
|
|
BLAKE2b-256 checksum How to use checksums |
bafaa429f033aad5bf94fd7a0a3c19cdf16dd6af563b5e154d859a55fbf27105
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / stigmer-3.30.0-py3-none-any.whl
| Download URL | stigmer-3.30.0-py3-none-any.whl |
|---|---|
| Size | 69.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e7971f80596d45ecb4b1cde5af88dfd17bb5a36babefcab5f8e152b74e803b3
|
|
BLAKE2b-256 checksum How to use checksums |
17f564c1fab57d6ae43fb6efc52855c70ce8158c0c7d9d5cfb91d3bb524a3fed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency log
