stigmer-sdk 0.1.0__tar.gz

stigmer_sdk-0.1.0/.gitignore

@@ -0,0 +1,181 @@
+# 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
+# ...except the benchmark fixture's sync log, data the instrument reads
+# (test/conformance/fixtures/working-agent/README.md).
+!test/conformance/fixtures/working-agent/evals/_fixture/workspace/logs/*.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
+
+# 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
+
+# The docs snippet gate's Python venv and Java classpath (make docs-snippets-toolchains)
+/.docs-snippets-toolchains/

stigmer_sdk-0.1.0/Makefile

@@ -0,0 +1,62 @@
+# 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!"
+
+# The tests run in a virtual environment (the system Python on Homebrew and
+# Ubuntu 24.04 refuses a global pip install, PEP 668) against the in-tree
+# proto stubs, never PyPI's stigmer-apis, which lags the tree. VENV may sit
+# outside the package, where a build here can never pack it.
+VENV ?= .venv
+PYTHON ?= python3
+
+.PHONY: test
+test: ## Run the SDK's tests against the in-tree proto stubs
+	@test -x $(VENV)/bin/python || $(PYTHON) -m venv $(VENV)
+	@# A .venv made by uv has no pip.
+	@$(VENV)/bin/python -m pip --version >/dev/null 2>&1 || $(VENV)/bin/python -m ensurepip --default-pip >/dev/null
+	@$(VENV)/bin/python -m pip install --quiet --disable-pip-version-check ../../apis/stubs/python/stigmer
+	@$(VENV)/bin/python -m pip install --quiet --disable-pip-version-check -e '.[test]'
+	@$(VENV)/bin/python -m pytest tests
+
+.PHONY: clean
+clean: ## Clean build artifacts and the test environment
+	@rm -rf dist build *.egg-info src/*.egg-info .venv .pytest_cache
+
+.DEFAULT_GOAL := help

stigmer_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+Metadata-Version: 2.5
+Name: stigmer-sdk
+Version: 0.1.0
+Summary: Python client for Stigmer, the open-source backend for the agents in your product
+Project-URL: Homepage, https://stigmer.ai
+Project-URL: Repository, https://github.com/stigmer/stigmer
+Project-URL: Documentation, https://stigmer.ai/docs/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
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# stigmer
+
+Python client for [Stigmer](https://stigmer.ai), the open-source backend for the agents in your product. Provides typed API clients for every Stigmer resource 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
+
+Before you start, run Stigmer on your machine with `stigmer up` and give it a model key ([Start Stigmer and add your model key](https://stigmer.ai/docs/getting-started/quickstart#start-stigmer-and-add-your-model-key)). Without a key the server refuses the message, and the program prints why.
+
+This program connects to that Stigmer, sets up a small agent, asks it one thing and prints its answer:
+
+```python
+"""The Stigmer quick start: connect to the Stigmer running on this machine,
+set up a small agent, ask it one thing and print its answer.
+
+Start Stigmer first with `stigmer up` (given a model key), then:
+python quickstart.py
+"""
+
+import sys
+
+from stigmer import AgentInput, ResourceRef, SessionSpecInput, StigmerClient, StigmerError
+
+try:
+    # `stigmer up` serves on localhost:7234 and needs no key on your machine.
+    with StigmerClient(base_url="localhost:7234", insecure=True) as client:
+        # apply creates the agent, or updates it when you run this again.
+        agent = client.agents.apply(
+            AgentInput(
+                name="greeter",
+                org="stigmer",
+                instructions="You greet people in one short, friendly sentence.",
+            )
+        )
+
+        turn = client.send_and_wait(
+            org="stigmer",
+            session_spec=SessionSpecInput(agent_ref=ResourceRef(org="stigmer", slug=agent.metadata.slug)),
+            message="Say hello to a developer trying Stigmer for the first time.",
+        )
+except StigmerError as err:
+    sys.exit(f"stigmer: {err}")
+
+if turn.phase != "completed":
+    sys.exit(f"the turn did not complete ({turn.phase}): {turn.error}")
+print(turn.answer)
+```
+
+It is `examples/quickstart.py`. Run `python quickstart.py`; it prints the agent's answer, for example "Hello, and welcome to Stigmer!".
+
+`send_and_wait` sends the message and waits for the agent's answer, reconnecting if the stream drops. A turn that waits for a person's approval returns with `phase` `"waiting"` and its `asks`; answer them with `client.sessions.confirm_tool_use` and call `client.wait_for_turn` with the outcome's `last_seq`.
+
+### On Stigmer Cloud
+
+Make two changes: connect with an API key, `StigmerClient(os.environ["STIGMER_API_KEY"])` (keys read `stk_…`), and use your own organization, `os.environ["STIGMER_ORG"]`, where the program says `"stigmer"`.
+
+## 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
+import os
+
+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(os.environ["STIGMER_API_KEY"]) as client:
+    # Create
+    agent = client.agents.create(AgentInput(
+        name="my-agent",
+        org="my-org",
+        description="Turns a customer's ledger into a variance report",
+        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="variance-reporter")
+    )
+
+    # 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.
+    finance = client.agents.list(
+        agent_io_pb2.ListAgentsRequest(org="my-org", labels={"team": "finance"})
+    )
+```
+
+## Cross-Resource Search
+
+```python
+import os
+
+from stigmer import StigmerClient, ApiResourceKind, SearchParams
+
+with StigmerClient(os.environ["STIGMER_API_KEY"]) as client:
+    results = client.search.query(SearchParams(
+        kinds=[ApiResourceKind.agent, ApiResourceKind.skill],
+        org="my-org",
+        query="variance report",
+    ))
+```
+
+## 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
+import os
+
+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
+import os
+
+from stigmer import CreatePaymentMethodSetupSessionParams, StigmerClient
+
+with StigmerClient(os.environ["STIGMER_API_KEY"]) 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
+import os
+
+from stigmer import StigmerClient, StigmerError, is_not_found, is_retryable
+
+with StigmerClient(os.environ["STIGMER_API_KEY"]) 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 | None = None, # Stigmer API key, "stk_…" (required unless insecure)
+    *,
+    base_url: str = "api.stigmer.ai:443",  # gRPC target address
+    insecure: bool = False,     # Skip TLS (local development only)
+)
+```
+
+On your machine, `stigmer up` serves on `localhost:7234` and needs no key; leave the key out on that plain-text connection, and the client sends no `authorization` header:
+
+```python
+client = StigmerClient(base_url="localhost:7234", insecure=True)
+```
+
+A client with no key on a TLS connection is refused at construction, as is an empty key.
+
+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`, `_turns.py`, and `__init__.py`.
+
+## Tests
+
+```bash
+cd sdk/python
+make test
+```
+
+It makes a virtual environment in `.venv`, installs the SDK and the proto stubs from this repository into it (not PyPI's `stigmer-apis`, which can lag the tree), and runs `pytest`. `make clean` removes the environment.