Python API reference

Auto-generated from docstrings via mkdocstrings[python]. The top-level package re-exports stable symbols only; everything in tako._native is internal.

tako

tako — Rust-core, Python-facade framework for enterprise agentic systems.

The thin Python facade re-exports a stable, ergonomic API on top of the compiled Rust extension tako._native. End users should import from tako only — never from tako._native directly.

SingleAgent

One-provider, max-step tool-call loop.

mcp_servers accepts tako.mcp.Stdio / tako.mcp.Http instances; their tools are discovered via MCP's tools/list at construction time and merged into the orchestrator's tool registry.

To enable per-step provider routing, pass router= (one of the classes in :mod:tako.routers) along with candidates=[...]. The router picks among [provider, *candidates] at each step.

Conductor

Coordinator-LLM-driven multi-worker orchestrator.

Phase 2 implementation of arXiv:2512.04388 (Sakana AI's Conductor). The coordinator emits a structured dispatch JSON at each turn; workers keyed by role name (e.g. "code", "math") run in parallel under a configurable fanout cap.

Client

Budget

Per-request and per-day spend / token caps.

ChatRequest

Bases: BaseModel

ChatResponse

Bases: BaseModel

ContentPart

Bases: BaseModel

A typed content block: text, image, image_url, tool_call, or tool_result.

Phase 22 added the image_url variant — a URL the provider's API server fetches (Anthropic, OpenAI, Mistral). Use url=... (HTTPS only) and optionally mime=... as a hint; data_b64 stays None for URL-source images.

Message

Bases: BaseModel

Role

Bases: str, Enum

ToolSchema

Bases: BaseModel

Usage

Bases: BaseModel

tako.providers

Provider adapters: thin wrappers around the native classes.

Each adapter exposes a stable, kwargs-friendly Python constructor and forwards to the underlying Rust builder via tako._native.

OpenAI

Bases: _ProviderBase

OpenAI chat.completions provider.

Anthropic

Bases: _ProviderBase

Anthropic Messages API provider.

Fake

Bases: _ProviderBase

In-process fake provider for tests. Returns canned text and tracks call count.

AzureOpenAI

Bases: _ProviderBase

Azure OpenAI provider.

Wire format is identical to OpenAI's chat.completions; the routing layer differs: requests go to {endpoint}/openai/deployments/{deployment}/chat/completions with an api-key header. deployment is the Azure deployment name (a user-defined alias mapping to a model — distinct from the underlying model id).

Vertex

Bases: _ProviderBase

Google Vertex AI (Gemini) provider.

Auth is intentionally deferred: pass a pre-resolved OAuth2 access token (or "$ENV:VAR"). The provider does not refresh tokens — for long- lived processes, wire your own credential source (e.g. gcloud auth print-access-token, the GKE metadata server, a service account JWT exchange) and rebuild the provider before tokens expire.

Example::

provider = tako.providers.Vertex(
    project_id="my-gcp-project",
    model="gemini-2.0-pro",
    access_token=os.environ["VERTEX_ACCESS_TOKEN"],
    location="us-central1",
)

Bedrock

Bases: _ProviderBase

Amazon Bedrock provider via Converse + ConverseStream.

Credentials come from the AWS default credential chain (env, profile, IRSA, IMDS) — pass profile_name to pin a specific named profile, or endpoint_url to talk to a VPC-private endpoint or local mock.

Phase 28.C — opt in to tako-side URL-source image pre-fetch via url_prefetch=True. Bedrock's ImageSource has no URL variant, so URL-source images (ContentPart::ImageUrl) require tako to fetch the bytes itself. SSRF mitigations baked in: https://-only by default (set url_prefetch_allow_http=True to allow http://); 10s timeout (override via url_prefetch_timeout_secs); 10 MiB response cap (override via url_prefetch_max_bytes); MIME validated against image/{jpeg,png,gif,webp}.

Phase 29.C — private-IP blocklist + DNS-rebinding mitigation are on by default. The pre-fetcher rejects URLs that resolve to loopback (127/8, ::1), RFC 1918 (10/8, 172.16/12, 192.168/16), link-local (169.254/16, fe80::/10), multicast / reserved, IPv6 unique-local (fc00::/7), and IPv4-mapped variants of those. The check runs at DNS-resolve time via a custom resolver that validates EVERY returned IP, plus an inline IP-literal check for URLs whose host is already an IP. Set url_prefetch_allow_private_ips=True to opt out for deployments that already filter network egress (VPC egress rules, Pod-level egress NetworkPolicies).

Phase 30.C / 31.C / 32.C — three forms of allowlist that bypass the private-IP blocklist (but NOT the scheme / timeout / size / MIME checks):

• Exact host (Phase 30) — url_prefetch_allow_hosts list, entries like "registry.corp". Match the URL host byte-for-byte. For IP-literal URLs, match the raw IP string ("10.0.5.4").
• Wildcard host (Phase 31) — same kwarg, entries like "*.internal.corp". Match any hostname ending in .internal.corp including multi-level subdomains. Does NOT match the bare apex (internal.corp).
• CIDR subnet (Phase 32) — url_prefetch_allow_cidrs list, entries like "10.0.5.0/24" (IPv4) or "2001:db8::/32" (IPv6). Single hosts as /32 or /128 work too. Match any resolved IP that falls inside the network — useful for subnets without a shared DNS suffix or for raw IP-literal URLs. CIDR parse failures surface from the constructor as an exception.

Pass None (default) for either kwarg to use no allowlist.

Ollama

Bases: _ProviderBase

Ollama provider — local-runner LLM inference via the /api/chat HTTP endpoint.

Defaults to base_url="http://localhost:11434" (the standard Ollama daemon bind). Override base_url to point at a remote Ollama instance. timeout_secs overrides the 600-second default (local-runner inference can be slow for large models).

Phase 29.C — opt in to tako-side URL-source image pre-fetch via url_prefetch=True. Ollama's images field on each message accepts only bare base64, so URL-source images (ContentPart::ImageUrl) require tako to fetch the bytes itself. SSRF mitigations baked in: https://-only by default (set url_prefetch_allow_http=True to allow http://); private-IP blocklist on by default (set url_prefetch_allow_private_ips=True to opt out for deployments that already filter network egress); 10s timeout (override via url_prefetch_timeout_secs); 10 MiB response cap (override via url_prefetch_max_bytes); MIME validated against image/{jpeg,png,gif,webp}.

Phase 30.C / 31.C / 32.C — three forms of allowlist that bypass the private-IP blocklist:

• Exact host (Phase 30) — url_prefetch_allow_hosts list, exact-string match.
• Wildcard host (Phase 31) — same kwarg, entries like "*.internal.corp" (multi-level subdomain match).
• CIDR subnet (Phase 32) — url_prefetch_allow_cidrs list, entries like "10.0.5.0/24" (IPv4) or "2001:db8::/32" (IPv6).

Operators must enforce network egress at deployment level (Pod-level egress NetworkPolicies, etc.) for defence-in-depth.

Example::

provider = tako.providers.Ollama(
    model="llama3.2-vision:11b",
    base_url="http://ollama.internal:11434",
    url_prefetch=True,
    url_prefetch_allow_hosts=[
        "registry.internal.corp",       # exact match
        "*.images.internal.corp",       # any subdomain
    ],
    url_prefetch_allow_cidrs=[
        "10.0.5.0/24",                  # whole subnet
    ],
)

HttpGeneric

Bases: _ProviderBase

Generic HTTP / SSE provider — point at any chat-completions-compatible endpoint.

body_template is a JSON document where the literal strings "{{ request }}", "{{ model }}", "{{ messages }}" are replaced with the corresponding fields of the outgoing request at call time. response_text_pointer is a JSON Pointer (RFC 6901) into the response body that yields the assistant text.

Pass stream_config={"kind": "openai_sse", ...} or {"kind": "ndjson", ...} to enable streaming; Capabilities.supports_streaming flips automatically. Header values may carry "$VAR_NAME" literals; the provider resolves those from the environment at construction.

Example::

provider = tako.providers.HttpGeneric(
    id="custom",
    model="my-model-v1",
    url="https://api.example.com/v1/chat/completions",
    body_template={"model": "{{ model }}", "messages": "{{ messages }}"},
    response_text_pointer="/choices/0/message/content",
    headers=[("Authorization", "Bearer $MY_API_KEY")],
    stream_config={"kind": "openai_sse"},
)

PythonProvider

Bases: _ProviderBase

LlmProvider whose chat() is a Python async callable.

Useful for prototyping vendor adapters in pure Python or wiring up a provider whose Rust crate doesn't exist yet.

.. note:: SingleAgent.run_sync() is not supported with a PythonProvider (the synchronous code path doesn't run a Python event loop, which the user's async chat callable needs). Always use the async run() API.

Phase 10.D — pass stream=async_gen_fn to enable streaming. The callable is async def stream(request: dict) -> AsyncIterator[dict]; yielded dicts match :class:tako_core::ChatChunk's kind-tagged schema. When stream= is set, the provider's supports_streaming capability flips to True so orchestrators that prefer streaming (Trinity, AB-MCTS) route through the streaming path automatically.

Example::

async def my_chat(request: dict) -> str:
    return f"echo: {request['messages'][-1]['content'][0]['text']}"

async def my_stream(request: dict):
    yield {"kind": "delta", "text": "echo: "}
    yield {"kind": "delta", "text": request["messages"][-1]["content"][0]["text"]}
    yield {"kind": "end", "finish_reason": "stop",
           "usage": {"input_tokens": 0, "output_tokens": 0}}

provider = tako.providers.PythonProvider(
    "custom:echo", chat=my_chat, stream=my_stream,
)
agent = tako.SingleAgent(provider=provider)

tako.secrets

Cloud secret resolvers.

Each resolver exposes async resolve(key: str) -> str. Keys may be plain secret names (or paths, depending on the backend) and may include an optional #suffix to disambiguate sub-keys (Vault), versions (Azure KV, GCP SM, AWS SM).

The returned string is the raw secret value — handle it like a password: do not log it, prefer passing it directly to the consuming API client, and avoid keeping it resident longer than necessary.

VaultResolver

Bases: _ResolverBase

HashiCorp Vault KV-v2 resolver.

addr is the Vault server URL (e.g. https://vault.example:8200). token is sent as the X-Vault-Token header. Keys must include the KV-v2 data/ segment, e.g. "secret/data/myapp"; append #field to extract a single key from the secret object.

AzureKeyVaultResolver

Bases: _ResolverBase

Azure Key Vault REST resolver.

vault_url is the Key Vault DNS name (e.g. https://my-vault.vault.azure.net). access_token is a pre-resolved Azure AD bearer token scoped to https://vault.azure.net/.default — the resolver does not refresh it. Keys may be "<secret-name>" (latest version) or "<secret-name>#<version-id>".

GcpSecretManagerResolver

Bases: _ResolverBase

GCP Secret Manager REST resolver.

Reads via :access against the Secret Manager v1 API. Like the Vertex provider, OAuth2 token acquisition is deferred — pass a pre-resolved access token (gcloud auth print-access-token or the GKE metadata server). Keys may be "<secret-name>" (latest version) or "<secret-name>#<version-number>".

AwsSecretsManagerResolver

Bases: _ResolverBase

AWS Secrets Manager resolver.

Uses the AWS SDK with the standard credential chain (env vars, profile, IRSA, IMDS). Credential resolution happens on the first resolve() call so the constructor cannot fail in test environments without AWS creds.

tako.mcp

MCP transport wrappers.

Stdio

Bases: _TransportBase

MCP stdio transport. Spawns a subprocess and exchanges newline-delimited JSON-RPC. The initialize → initialized handshake runs at construction time and blocks until it completes.

Http

Bases: _TransportBase

MCP Streamable HTTP transport. Single-endpoint POST/GET; SSE upgrade arrives in Phase 2.

WebSocket

Bases: _TransportBase

MCP WebSocket transport. Bidirectional JSON-RPC over a single ws:// or wss:// connection. Available when the wheel was built with the ws Cargo feature (raises AttributeError otherwise).

Grpc

Bases: _TransportBase

MCP gRPC transport. JSON-RPC frames carried over a single bidi streaming RPC.

Endpoint is http://host:port (plaintext) or https://host:port for TLS. With no TLS kwargs the server cert is verified against webpki-roots. Pass ca_pem (or ca_path) to use a custom CA bundle, plus client_cert_pem / client_key_pem (or their _path siblings) together to enable mTLS. domain_name overrides the SNI / cert-hostname check.

Available when the wheel was built with the grpc Cargo feature.

tako.compat

OpenAI-compatible HTTP server.

serve_openai(orch, *, host='127.0.0.1', port=8080, tokens=None, auth=None, models=None)

Boot the OpenAI-compatible HTTP server.

Returns the bound URL (e.g. "http://127.0.0.1:8080"). The server runs in a background Tokio task; call :func:shutdown_openai to stop it. orch must be a tako.SingleAgent or tako.Conductor.

Auth: every request must carry Authorization: Bearer <token>.

Two auth modes:

1. Static map (dev / CI): tokens={"my-token": ("acme", "alice")}. Each token maps to (tenant_id, user_id). If neither tokens nor auth is set, a single "dev-token" mapping to anonymous is installed for local testing.
2. Real auth (production, Phase 14.B): pass auth= with one of tako.compat.JwtAuth.hs256(secret), tako.compat.JwtAuth.rs256_from_pem(pem), tako.compat.OidcAuth.discover(issuer, audience) (async), or tako.compat.VaultAuth(addr, vault_token). These resolvers require the wheel to be built with the matching auth-* feature (e.g. maturin build --features auth-jwt).

Phase 15.B.1 / 15.B.2 — VaultAuth gains with_approle, with_kubernetes and with_kubernetes_in_pod static constructors for AppRole / Kubernetes auth-method rotation. OidcAuth gains with_introspection / with_introspection_uri builder methods for RFC 7662 token introspection (revocation-aware checks).

Phase 16.B.3 — VaultAuth.with_namespace(ns) sets the Vault Enterprise namespace used on every KV lookup (X-Vault-Namespace header). OidcAuth.with_introspection_auth_method(m) selects between "basic" (default; HTTP Basic header) and "post" (credentials in form body) per RFC 7662 §2.1.

Phase 17.C — OidcAuth.with_introspection_auth_method now accepts "jwt" / "client_secret_jwt" for the RFC 7521 / 7523 HS256-signed client-assertion auth method. OidcAuth.with_introspection_auth_method_from_discovery() auto-selects the strongest auth method advertised by the issuer's RFC 8414 discovery doc (preference order: JWT > Basic

Post).

Phase 18.C — OidcAuth gains with_introspection_jwt_rs256_pem(pem) / with_introspection_jwt_es256_pem(pem) / with_introspection_jwt_ed25519_pem(pem) builders for the asymmetric private_key_jwt auth method (Phase 18.A; RFC 7521 / 7523 with an RSA / EC / Ed25519 key). The auto-selector prefers private_key_jwt when an asymmetric key is loaded. OidcAuth.end_session_endpoint() and OidcAuth.build_logout_uri(id_token_hint, post_logout_redirect_uri, state) expose the OIDC Session Management 1.0 logout-URL helper (Phase 18.B).

Phase 24.B — OidcAuth gains with_introspection_mtls(cert_pem, key_pem) / with_introspection_mtls_combined(combined_pem) builders for the RFC 8705 mTLS introspection auth method (tls_client_auth). The auto-selector prefers tls_client_auth over JWT methods when an mTLS identity is loaded. with_introspection_auth_method accepts new case-insensitive aliases "tls_client_auth" / "tls-client-auth" / "mtls".

Phase 25.B — OidcAuth gains with_introspection_self_signed_mtls(cert_pem, key_pem) / with_introspection_self_signed_mtls_combined(combined_pem) builders for the RFC 8705 §2.2 self-signed mTLS variant. with_introspection_auth_method accepts new aliases "self_signed_tls_client_auth" / "self-signed-mtls" (and kebab variants). The auto-selector prefers CA-backed tls_client_auth over self-signed when both are listed. After Phase 25 the OIDC introspection auth-method surface covers all six RFC 7662 §2.1 / RFC 8414 / RFC 8705 methods.

Phase 33.B — OidcAuth.reload_mtls_identity(cert_pem, key_pem) and OidcAuth.reload_mtls_identity_combined(combined_pem) atomically replace the mTLS identity used for OIDC introspection POSTs without rebuilding the resolver. Useful for cert rotation in long-running deployments (cert-manager webhook, Vault PKI rotation, filesystem watcher, periodic poll). Mutates state in place via internal mutability — the swap is atomic from the request handler's perspective; concurrent introspection POSTs either see the old Client or the new one, never a torn state. Raises ValueError when no prior with_introspection_mtls call has been made, and preserves the previously installed Client on PEM parse failure.

Phase 42 — OidcAuth.with_introspection_mtls_extra_root(cert_pem, key_pem, ca_pem) and with_introspection_self_signed_mtls_extra_root(...) are the operator-supplied-CA siblings of the Phase 24 / 25 mTLS introspection builders. The CA bundle (single root or concatenated multi-cert PEM) is added to the underlying HTTP client's trust store and is persisted across the Phase 33 / 35 / 37 / 39 rotation surfaces. For enterprise self-hosted OIDC issuers (Keycloak / Auth0 self-hosted / Authentik) presenting a server cert signed by a private internal CA. Raises ValueError on PEM parse failure (empty bundle, garbage bytes) at builder time — fail-closed.

Phase 44 — OidcAuth.discover_with_extra_root(issuer, audience, ca_pem) is a parallel async constructor that builds the resolver-wide HTTP client with an operator-supplied PEM-encoded root CA bundle added to its trust store. The same trust anchor covers BOTH the OIDC discovery doc fetch (during construction) AND every subsequent JWKS refresh, because the resolver holds a single HTTP client for non-introspection HTTP. Pair with the Phase 42 _extra_root builders when one PKI fronts the whole OIDC stack. Without it, the discovery GET against a private-CA issuer fails TLS verification before the resolver is even returned. Raises ValueError at construction time on PEM parse failure (empty bundle, garbage bytes).

Phase 21.B — tako.compat.ChainedAuth (always-on; no cargo feature gate) is a composite resolver that wraps N child resolvers and tries them in append order. The first child to return a Principal short-circuits; any error falls through to the next. Common pattern: auth=ChainedAuth().then(oidc).then(jwt) to accept either an OIDC bearer or a static-key-signed JWT. Children may themselves be ChainedAuth instances (recursive composition).

Phase 26.B — ChainedAuth.with_short_circuit_on_transport_error() opts in to fail-fast semantics for transport errors. When enabled, a transport error from any child (e.g. OIDC issuer unreachable) halts the chain immediately instead of falling through to the next child. Other error variants (auth-decision errors like "bad token") continue to fall through. Default behaviour preserves Phase 21 fall-through-on-any-Err semantics.

Phase 27.B — ChainedAuth.with_short_circuit_on_infrastructure_errors() extends fail-fast to four "definitely infrastructure / operator-set-guard" variants: Transport (network failure), RateLimited (upstream rate limit), CircuitOpen (failsafe circuit), BudgetExhausted (operator-set spend cap). Auth-decision errors and vendor errors still fall through. Last-write-wins between the two builders.

Passing both tokens and auth is an error.

shutdown_openai()

Stop the running compat server. Idempotent.

tako.tracing

Tracing setup.

Otlp

Lazy config object — most users will call :func:init_otlp directly. This class exists so user code can write tako.tracing.Otlp(endpoint=...) in a Client constructor and have tako pick up the endpoint later.

install(*, filter=None, json=False)

Apply the configuration via :func:init_otlp.

init(*, filter=None, json=False)

Initialise process-wide tracing without an OTLP exporter (stderr only). Idempotent.

init_otlp(endpoint, *, filter=None, json=False)

Initialise tracing with an OTLP gRPC exporter.

Spans land in the collector at endpoint (e.g. http://localhost:4317). A process-global guard keeps the exporter alive for the interpreter's lifetime; pending spans flush at exit. Calling twice without an intervening :func:shutdown_otlp is rejected.

shutdown_otlp()

Drop the OTLP exporter, flushing pending spans. Idempotent.