stigmer-sdk 0.1.0.dev0__tar.gz

stigmer_sdk-0.1.0.dev0/.gitignore

@@ -0,0 +1,178 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+bin/
+dist/
+# Turborepo's local task cache and per-package task logs (turbo.json).
+.turbo
+dist-slim/
+dist-slim-pkgs/
+# Per-arch trees the Docker image build stages (scripts/smoke-docker-image.mjs).
+dist-slim-amd64/
+dist-slim-arm64/
+# The compose-runner image's CLI tarballs (scripts/stage-compose-runner-cli.mjs).
+backend/services/runner/stage/
+# The server library tarballs a consumer installs (scripts/stage-server-library.mjs).
+backend/services/stigmer-server/stage/
+
+# Desktop embedded-runner staging: a symlink in dev (setup-runner-dev.sh),
+# the staged slim artifact in packaged builds (stage-runner-slim.sh).
+client-apps/desktop/src-tauri/resources/runner
+client-apps/desktop/src-tauri/resources/runtime
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+coverage.txt
+coverage.html
+
+# A vitest run's v8 coverage (`--coverage.enabled`), in each package
+coverage/
+
+# Stryker's copies of the files it changes in place during a mutation sweep
+# (scripts/mutation-sweep.mjs), which it removes when the run ends
+.stryker-tmp/
+
+# Go workspace sum file (auto-generated, can be ignored)
+go.work.sum
+
+# Dependency directories (Go)
+vendor/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+# The setuptools sdist artifact (a FILE named MANIFEST). With
+# core.ignorecase this pattern also swallows source directories named
+# manifest/ (e.g. sdk/*/src/manifest) — the negation re-includes those
+# while the artifact file stays ignored.
+MANIFEST
+!**/manifest/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Java / Maven
+target/
+
+# Node.js
+node_modules/
+
+# Stigmer specific
+.stigmer/
+*.skill
+*.db
+*.db-shm
+*.db-wal
+
+# Temporary files
+*.log
+*.tmp
+tmp/
+
+# Proto generated files (tracked, but ignore in development)
+# We'll commit generated code for now
+# *.pb.go
+# *_pb2.py
+# *_pb2.pyi
+
+# Build artifacts
+*.o
+*.a
+*.out
+.agent-runner-image-built
+
+# Codegen tool binaries (go build drops these in the module/repo root)
+/generator
+/proto2schema
+tools/codegen/generator/generator
+
+# Go service binaries (prevent accidental commits of built binaries in service dirs)
+backend/services/*/stigmer-server
+backend/services/*/agent-runner
+backend/services/*/cmd/*/server
+backend/services/*/server
+
+# npm auth tokens (never commit)
+.npmrc
+
+# Vale (downloaded style packages — run `vale sync` to fetch)
+vale/styles/Google/
+vale/styles/Microsoft/
+vale/styles/alex/
+
+# uv lockfile (project uses Poetry; uv.lock is auto-generated noise)
+uv.lock
+
+# Environment files (local secrets, never commit)
+.env
+.env_export
+# Vite local env overrides (e.g. desktop .env.development.local — machine-specific paths)
+.env*.local
+
+# Integration test output
+.test-output*/
+
+# TypeDoc JSON intermediates (regenerated by `make gen-react-sdk-docs` /
+# `gen-ink-sdk-docs` before every use; they embed the HEAD commit SHA in
+# every source URL, so tracking them creates churn on every SDK commit)
+sdk/*/typedoc-output.json
+
+# Dev TLS certs (generated by gen-dev-certs.sh)
+client-apps/desktop/scripts/.certs/
+
+# Cursor
+_cursor/
+_aacursor/
+*.bak
+
+# Internal planning/history migrated to the private stigmer-cloud repo (do not re-add)
+_changelog/
+_investigations/
+_projects/
+_roles/
+.cursor/plans/
+
+# Compiled codegen toolchain binaries (built ad hoc via `go build` in tools/;
+# the tools are always run via `go run ./tools/codegen/...` — never commit them)
+/tools/generator
+/tools/proto2schema
+/tools/codegen/generator/generator
+/tools/codegen/proto2schema/proto2schema

stigmer_sdk-0.1.0.dev0/Makefile

@@ -0,0 +1,46 @@
+# Stigmer Python SDK - Makefile
+
+.PHONY: help
+help: ## Display this help message
+	@echo "Stigmer Python SDK - Available targets:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: codegen-clients
+codegen-clients: ## Generate SDK client code from service schemas
+	@echo "Generating Python SDK client code..."
+	@echo "  Wiping src/stigmer/_gen/ directory..."
+	@rm -rf src/stigmer/_gen
+	@mkdir -p src/stigmer/_gen
+	@# The generator runs from TypeScript source via the repo-pinned tsx
+	@# (never bare npx — oss#531) and reads proto metadata from
+	@# @stigmer/apis, which must be built first (incremental; a no-op when
+	@# fresh). A bare CI checkout has no dist/ — skipping this fails module
+	@# resolution.
+	@cd ../.. && test -x node_modules/.bin/tsx || { echo "error: node_modules/.bin/tsx not found — run 'npm install' at the repo root"; exit 1; }
+	@cd ../.. && npm run build -w @stigmer/apis --silent
+	@cd ../.. && node_modules/.bin/tsx tools/codegen/src/generator/main.ts \
+		--schema-dir tools/codegen/schemas \
+		--output-dir sdk/python/src/stigmer/_gen \
+		--target sdk-client-python
+
+.PHONY: codegen
+codegen: codegen-clients ## Run code generation pipeline
+	@echo ""
+	@echo "Python SDK code generation complete!"
+	@echo "Generated files live in src/stigmer/_gen/"
+
+.PHONY: codegen-verify
+codegen-verify: codegen ## Generate code and verify syntax
+	@echo "Verifying generated Python files..."
+	@python3 -c "import ast, pathlib; \
+		files = list(pathlib.Path('src/stigmer/_gen').glob('*.py')); \
+		[ast.parse(f.read_text()) for f in files]; \
+		print(f'  {len(files)} files passed syntax check')"
+	@echo ""
+	@echo "Code generation verified successfully!"
+
+.PHONY: clean
+clean: ## Clean build artifacts
+	@rm -rf dist build *.egg-info src/*.egg-info
+
+.DEFAULT_GOAL := help

stigmer_sdk-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: stigmer-sdk
+Version: 0.1.0.dev0
+Summary: Stigmer Python SDK — typed API client for all Stigmer platform resources
+Project-URL: Homepage, https://stigmer.ai
+Project-URL: Repository, https://github.com/stigmer/stigmer
+Project-URL: Documentation, https://docs.stigmer.ai/sdk/python
+Author-email: Stigmer <engineering@stigmer.ai>
+License-Expression: Apache-2.0
+Keywords: ai-agents,api-client,grpc,sdk,stigmer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: protobuf>=6.32.0
+Requires-Dist: stigmer-apis==0.1.0.dev0
+Description-Content-Type: text/markdown
+
+# stigmer
+
+Python SDK for the Stigmer platform. Provides typed API clients for all Stigmer resources with authentication, error handling, and cross-resource search.
+
+## Installation
+
+```bash
+pip install stigmer-sdk
+```
+
+`stigmer-apis` (generated protobuf stubs) is installed automatically as a dependency.
+
+## Quick Start
+
+```python
+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:
+
+```python
+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              |
+| `runs`                 | Run                |
+| `api_keys`             | ApiKey             |
+| `grants`               | Grant              |
+| `identity_accounts`    | IdentityAccount    |
+| `federation_issuers`   | FederationIssuer   |
+| `organizations`        | Organization       |
+| `plugins`              | Plugin             |
+| `sessions`             | Session            |
+| `skills`               | Skill              |
+| `vaults`               | Vault              |
+| `search`               | Cross-resource search |
+| `tokens`               | User-token minting (service-account keys) |
+
+## Common Operations
+
+```python
+from ai.stigmer.agentic.agent.v1 import io_pb2 as agent_io_pb2
+from ai.stigmer.commons.apiresource import io_pb2 as apiresource_io_pb2
+from stigmer import StigmerClient, AgentInput, ResourceRef
+
+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: read, change, then name the fields you changed. Every other
+    # field keeps its stored value. The read's etag makes the save fail with
+    # "aborted" if someone changed the agent since.
+    current = client.agents.get("agent-id")
+    current.spec.description = "Updated description"
+    updated = client.agents.update(current, ["spec.description"])
+
+    # Rename: change the slug people type. The id stays, so everything that
+    # points at the agent keeps working; the old slug reads for 30 days.
+    renamed = client.agents.rename(
+        apiresource_io_pb2.RenameInput(resource_id="agent-id", slug="support-bot")
+    )
+
+    # Delete
+    deleted = client.agents.delete("agent-id")
+
+    # List: one page of the org's agents, newest first. A page carries
+    # next_page_token while more follow; page_size 0 asks for the default 50.
+    page = client.agents.list(agent_io_pb2.ListAgentsRequest(org="my-org", page_size=20))
+
+    # Every agent, page after page: list_all follows the tokens.
+    for a in client.agents.list_all(agent_io_pb2.ListAgentsRequest(org="my-org")):
+        print(a.metadata.slug)
+
+    # Only the agents carrying every label given.
+    support = client.agents.list(
+        agent_io_pb2.ListAgentsRequest(org="my-org", labels={"team": "support"})
+    )
+```
+
+## Cross-Resource Search
+
+```python
+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",
+    ))
+```
+
+## User Tokens
+
+A product that embeds Stigmer mints a short-lived token for each person
+signed in to it, from its own backend, with an ordinary client built on a
+service account's API key. The account must be an admin of the organization
+the token is for, or of its parent organization; a person's key is refused.
+Pass `access_token` to the React SDK's `StigmerProvider` through
+`getAccessToken`:
+
+```python
+from stigmer import StigmerClient
+
+with StigmerClient(os.environ["STIGMER_API_KEY"]) as client:
+    result = client.tokens.mint_user_token(
+        org="acme",
+        user_id=user.id,
+        user_email=user.email,
+        user_name=user.name,
+    )
+    print(result.access_token, result.expires_at)
+```
+
+## Billing
+
+An organization's billing account (its Stripe customer), the Stripe portal
+and card setup sessions. Token usage is read from the run client's usage
+reports (`get_run_usage_report`, `get_session_usage_report`,
+`get_agent_usage_report`, `get_org_usage_report`), counted in tokens and never
+priced. Queries require `can_view_billing` on the org and the org's own
+billing commands require `can_manage_billing`. The operator pricing methods
+(`list_model_pricing_baselines`, `upsert_model_pricing_baseline`,
+`retire_model_pricing_baseline`) require `can_manage_model_pricing` on the
+platform:
+
+```python
+from stigmer import CreatePaymentMethodSetupSessionParams, StigmerClient
+
+with StigmerClient("sk_live_abc123") as client:
+    account = client.billing.get_billing_account(org)
+
+    setup = client.billing.create_payment_method_setup_session(
+        CreatePaymentMethodSetupSessionParams(
+            org=org,
+            success_url="https://example.com/billing?setup=success",
+            cancel_url="https://example.com/billing",
+        )
+    )
+```
+
+## Error Handling
+
+All SDK operations raise `StigmerError` with structured error codes:
+
+```python
+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
+
+```python
+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)
+)
+```
+
+For a CI job or a script, use a [service account's](https://stigmer.ai/docs/guides/authentication/service-accounts) API key, not a person's: it keeps working when that person leaves and works only in its own organization.
+
+## Code Generation
+
+The resource clients in `src/stigmer/_gen/` are generated from protobuf service schemas. To regenerate after proto changes:
+
+```bash
+cd sdk/python
+make codegen
+```
+
+Handwritten code lives in `src/stigmer/` (outside `_gen/`): `_client.py`, `_transport.py`, `_interceptors.py`, `_search.py`, `_tokens.py`, and `__init__.py`.

stigmer_sdk-0.1.0.dev0/README.md

@@ -0,0 +1,208 @@
+# stigmer
+
+Python SDK for the Stigmer platform. Provides typed API clients for all Stigmer resources with authentication, error handling, and cross-resource search.
+
+## Installation
+
+```bash
+pip install stigmer-sdk
+```
+
+`stigmer-apis` (generated protobuf stubs) is installed automatically as a dependency.
+
+## Quick Start
+
+```python
+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:
+
+```python
+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              |
+| `runs`                 | Run                |
+| `api_keys`             | ApiKey             |
+| `grants`               | Grant              |
+| `identity_accounts`    | IdentityAccount    |
+| `federation_issuers`   | FederationIssuer   |
+| `organizations`        | Organization       |
+| `plugins`              | Plugin             |
+| `sessions`             | Session            |
+| `skills`               | Skill              |
+| `vaults`               | Vault              |
+| `search`               | Cross-resource search |
+| `tokens`               | User-token minting (service-account keys) |
+
+## Common Operations
+
+```python
+from ai.stigmer.agentic.agent.v1 import io_pb2 as agent_io_pb2
+from ai.stigmer.commons.apiresource import io_pb2 as apiresource_io_pb2
+from stigmer import StigmerClient, AgentInput, ResourceRef
+
+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: read, change, then name the fields you changed. Every other
+    # field keeps its stored value. The read's etag makes the save fail with
+    # "aborted" if someone changed the agent since.
+    current = client.agents.get("agent-id")
+    current.spec.description = "Updated description"
+    updated = client.agents.update(current, ["spec.description"])
+
+    # Rename: change the slug people type. The id stays, so everything that
+    # points at the agent keeps working; the old slug reads for 30 days.
+    renamed = client.agents.rename(
+        apiresource_io_pb2.RenameInput(resource_id="agent-id", slug="support-bot")
+    )
+
+    # Delete
+    deleted = client.agents.delete("agent-id")
+
+    # List: one page of the org's agents, newest first. A page carries
+    # next_page_token while more follow; page_size 0 asks for the default 50.
+    page = client.agents.list(agent_io_pb2.ListAgentsRequest(org="my-org", page_size=20))
+
+    # Every agent, page after page: list_all follows the tokens.
+    for a in client.agents.list_all(agent_io_pb2.ListAgentsRequest(org="my-org")):
+        print(a.metadata.slug)
+
+    # Only the agents carrying every label given.
+    support = client.agents.list(
+        agent_io_pb2.ListAgentsRequest(org="my-org", labels={"team": "support"})
+    )
+```
+
+## Cross-Resource Search
+
+```python
+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",
+    ))
+```
+
+## User Tokens
+
+A product that embeds Stigmer mints a short-lived token for each person
+signed in to it, from its own backend, with an ordinary client built on a
+service account's API key. The account must be an admin of the organization
+the token is for, or of its parent organization; a person's key is refused.
+Pass `access_token` to the React SDK's `StigmerProvider` through
+`getAccessToken`:
+
+```python
+from stigmer import StigmerClient
+
+with StigmerClient(os.environ["STIGMER_API_KEY"]) as client:
+    result = client.tokens.mint_user_token(
+        org="acme",
+        user_id=user.id,
+        user_email=user.email,
+        user_name=user.name,
+    )
+    print(result.access_token, result.expires_at)
+```
+
+## Billing
+
+An organization's billing account (its Stripe customer), the Stripe portal
+and card setup sessions. Token usage is read from the run client's usage
+reports (`get_run_usage_report`, `get_session_usage_report`,
+`get_agent_usage_report`, `get_org_usage_report`), counted in tokens and never
+priced. Queries require `can_view_billing` on the org and the org's own
+billing commands require `can_manage_billing`. The operator pricing methods
+(`list_model_pricing_baselines`, `upsert_model_pricing_baseline`,
+`retire_model_pricing_baseline`) require `can_manage_model_pricing` on the
+platform:
+
+```python
+from stigmer import CreatePaymentMethodSetupSessionParams, StigmerClient
+
+with StigmerClient("sk_live_abc123") as client:
+    account = client.billing.get_billing_account(org)
+
+    setup = client.billing.create_payment_method_setup_session(
+        CreatePaymentMethodSetupSessionParams(
+            org=org,
+            success_url="https://example.com/billing?setup=success",
+            cancel_url="https://example.com/billing",
+        )
+    )
+```
+
+## Error Handling
+
+All SDK operations raise `StigmerError` with structured error codes:
+
+```python
+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
+
+```python
+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)
+)
+```
+
+For a CI job or a script, use a [service account's](https://stigmer.ai/docs/guides/authentication/service-accounts) API key, not a person's: it keeps working when that person leaves and works only in its own organization.
+
+## Code Generation
+
+The resource clients in `src/stigmer/_gen/` are generated from protobuf service schemas. To regenerate after proto changes:
+
+```bash
+cd sdk/python
+make codegen
+```
+
+Handwritten code lives in `src/stigmer/` (outside `_gen/`): `_client.py`, `_transport.py`, `_interceptors.py`, `_search.py`, `_tokens.py`, and `__init__.py`.

stigmer_sdk-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stigmer-sdk"
+version = "0.1.0.dev0"
+description = "Stigmer Python SDK — typed API client for all Stigmer platform resources"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Stigmer", email = "engineering@stigmer.ai" }]
+keywords = ["stigmer", "sdk", "api-client", "grpc", "ai-agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "grpcio>=1.60.0",
+    "protobuf>=6.32.0",
+    "stigmer-apis==0.1.0.dev0",
+]
+
+[project.urls]
+Homepage = "https://stigmer.ai"
+Repository = "https://github.com/stigmer/stigmer"
+Documentation = "https://docs.stigmer.ai/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stigmer"]