yutha

# Yutha

> Yutha is open-source infrastructure for groups of AI agents — identity, capability, accountability, and norms for swarms of any size, across community, enterprise, and cross-organization domains. Framework-agnostic; works in front of agents built in LangGraph, CrewAI, OpenAI Agents, Microsoft Agent Framework, or anything else you write an adapter for.

Yutha sits underneath whichever agent framework an agent is built with and gives swarms a shared substrate: Ed25519-keyed passports, typed envelopes, append-only signed receipts, attenuable capabilities, declarative constitutions in Cedar+, and an optional cryptographic verification layer via on-chain anchoring on Sui.

Two personas:
- **Operators** stand up a control plane, choose a topology, author and activate constitutions, manage operator credentials, monitor receipts, optionally anchor the receipt log for third-party verifiability.
- **Developers** wrap an existing LangGraph, CrewAI, OpenAI Agents, or Microsoft Agent Framework agent with the Yutha SDK so it can join a swarm — getting a passport, capability-gated sends, and a signed audit trail per consequential action.

The repository at https://github.com/abhinavg6/yutha contains the Rust reference implementation (control plane, registry, capability store, transport, receipt log, Cedar+ engine), Python SDK + adapters (LangGraph, CrewAI, OpenAI Agents, Microsoft Agent Framework), conformance suite, Move package for Sui anchoring, and the full RFC-governed spec set.

## Start here

- [Landing page](https://yutha.ai/): one-page concept overview, what Yutha is, what it's not, where the project is.
- [Operator quickstart](https://yutha.ai/operator/quickstart/): 30-minute initiator path — stand up a control plane, activate a constitution, send your first envelope, observe receipts.
- [Developer guide → LangGraph](https://yutha.ai/developer/langgraph/): 15-minute joiner path — wrap an existing LangGraph node as a Yutha agent.
- [Developer guide → CrewAI](https://yutha.ai/developer/crewai/): joiner path for the CrewAI framework idiom.
- [Example → OpenAI Agents research crew](https://yutha.ai/examples/research-crew/): end-to-end OpenAI Agents adapter walkthrough — citation enforcement, handoff bridging, cap-gated tools.
- [Example → MAF DevOps incident-response](https://yutha.ai/examples/devops-incident/): end-to-end Microsoft Agent Framework adapter walkthrough — SRE countersign, schema-change quarantine, ChatAgent integration.
- [Example → Procurement platform](https://yutha.ai/examples/procurement-platform/): heterogeneous-framework demo — LangGraph buyer intake + three CrewAI vendor agents on one swarm — with `OnlyIfTagged` capability caveats enforcing a multi-party confidentiality wall and a Cedar+ constitution that walks the four-stage enforcement loop on a bad-acting vendor.

## Concepts

- [Concepts overview](https://yutha.ai/concepts/): the conceptual layer of Yutha; read once and the rest of the docs make sense without re-explaining foundations.
- [Primitives](https://yutha.ai/concepts/primitives/): passports, envelopes, receipts, capabilities — the four building blocks.
- [Topology](https://yutha.ai/concepts/topology/): closed, open, and hybrid swarm shapes; when to choose which.
- [Constitution & enforcement](https://yutha.ai/concepts/constitution/): Cedar+ policy language, evaluation semantics, four-stage enforcement loop (detect, coach, quarantine, evict).
- [Verifiability](https://yutha.ai/concepts/verifiability/): optional on-chain anchoring of receipt batches via Sui; third-party verification without trusting the operator.

## Operator guide

- [Operator guide overview](https://yutha.ai/operator/): when this section applies — running, configuring, monitoring a swarm.
- [Quickstart](https://yutha.ai/operator/quickstart/): the 30-minute initiator path end-to-end, with exact CLI flags.
- [Authoring constitutions](https://yutha.ai/operator/authoring-constitutions/): plain-English DSL, scoring rules, procedures, resource budgets, memory norms.
- [Previewing rule changes — overview](https://yutha.ai/operator/previewing-changes/): the four "preview before promote" tools (shadow mode, replay, diff, simulation); decision matrix on which to reach for; combined preview-then-activate workflow.
- [Shadow mode on live traffic](https://yutha.ai/operator/shadow-mode/): activate a candidate constitution that observes the live envelope stream alongside the active rule set without blocking anything; receipt evidence carries the would-be decision; `yutha-ops constitution shadow-activate`.
- [Replay against past traffic](https://yutha.ai/operator/replay/): re-run a candidate constitution over a recorded window of receipts with deterministic wall-clock + frozen entity state; never anchors; outputs a replay session receipt with pass/deny deltas vs the original decisions.
- [Diff two rule sets](https://yutha.ai/operator/constitution-diff/): structural diff between two constitution versions (added/removed/changed policies + engine-config rules); optional behavioural diff via `--against-window` that runs both sides over the same replay window; JSON/Markdown/HTML output.
- [Simulation with synthetic traffic](https://yutha.ai/operator/simulation/): SimulationHarness drives scripted canonical agent personas (well-behaved support agent, adversarial refund attacker, broken-tool agent) against a candidate constitution before any real agent connects; YAML scenario format; `yutha-ops sim run`.
- [Operator credentials](https://yutha.ai/operator/operator-credentials/): generating, rotating, and revoking the operator key; active-stream tear-down; capability cascade.
- [Enterprise identity (end-to-end)](https://yutha.ai/operator/enterprise-identity/): integrated deployment narrative for the operator running an external Signer + Attestor pair — `--signer vault` + `--attestor spiffe` walkthrough; alternative-backend matrix (Vault/GCP-KMS/Azure-KV × SPIFFE/OIDC); first-agent SVID-attested register; receipt evidence; deny-path verification.
- [Signer backends — overview](https://yutha.ai/operator/signers/): what a Signer is, what `--signer` provides, when to use which backend (in-process default vs Vault / GCP KMS / Azure HSM), comparison table, links to per-backend runbooks.
- [Vault Signer](https://yutha.ai/operator/vault-signer/): opt-in key custody — move the bootstrap Ed25519 key out of process memory into HashiCorp Vault transit; `--signer vault` CLI wiring; Token or AppRole auth (secrets via `*_FILE` flags); least-privilege policy.
- [GCP KMS Signer](https://yutha.ai/operator/gcp-kms-signer/): opt-in key custody — hold the bootstrap Ed25519 key in Google Cloud KMS (algorithm `EC_SIGN_ED25519`); `--signer gcp-kms` CLI wiring; ADC + Workload Identity auth; `cloudkms.signerVerifier` IAM role.
- [Azure Key Vault Signer](https://yutha.ai/operator/azure-kv-signer/): opt-in key custody — hold the bootstrap Ed25519 key in Azure Managed HSM (`OKP-HSM` / `Ed25519`); `--signer azure-kv` CLI wiring; DefaultAzureCredential auth chain; **Managed HSM Crypto User** role. Requires the Managed HSM tier; standard Key Vault does not support Ed25519.
- [Attestor backends — overview](https://yutha.ai/operator/attestors/): what an Attestor is, what `--attestor` provides, when to use which backend (native default vs SPIFFE/SPIRE / OIDC), comparison table, links to per-backend runbooks.
- [SPIFFE/SPIRE Attestor](https://yutha.ai/operator/spiffe-attestor/): opt-in admission attestation — verify every `AdmissionService.Register` against a SPIRE-issued JWT-SVID; `--attestor spiffe` CLI wiring; Workload API socket or static trust-bundle file source; receipts record SPIFFE ID + selectors as evidence.
- [OIDC Attestor](https://yutha.ai/operator/oidc-attestor/): opt-in admission attestation — verify every `AdmissionService.Register` against an OpenID Connect ID token; `--attestor oidc` CLI wiring; OIDC Discovery / `jwks_uri` / static-file JWKS sources; per-IdP recipes for Auth0/Okta/Azure AD/Keycloak/Google.
- [Monitoring & receipts](https://yutha.ai/operator/monitoring/): querying the receipt log, what to alert on, OpenTelemetry export.
- [Sui anchoring](https://yutha.ai/operator/sui-anchoring/): opt-in verifiability layer — publishing the Move package, creating a SwarmAnchor, wiring the AnchorDriver into the control plane.
- [Deployment](https://yutha.ai/operator/deployment/): Postgres backend, scaling, single-tenant defaults, self-hosted vs. verifiable-backend.

## Developer guide

- [Developer guide overview](https://yutha.ai/developer/): when this section applies — building agents that join a Yutha-governed swarm.
- [Quickstart](https://yutha.ai/developer/quickstart/): 15-minute joiner path, framework-neutral.
- [Python SDK](https://yutha.ai/developer/python-sdk/): the canonical client surface — admission, envelope, receipts, capability, constitution APIs.
- [LangGraph adapter](https://yutha.ai/developer/langgraph/): full walkthrough wrapping a LangGraph node as a Yutha agent; deterministic state-graph handler, no LLM dependency at the dispatch level. Paired example: customer support with refund cap.
- [CrewAI adapter](https://yutha.ai/developer/crewai/): each `Agent` in a Crew becomes a Yutha agent with its own identity; LLM-driven dispatch via `Crew.kickoff()`. Paired example: AP/invoice processing.
- [OpenAI Agents adapter](https://yutha.ai/developer/openai-agents/): each `agents.Agent` becomes a Yutha agent; handoff bridging via `RunHooks` so every inter-agent transition produces a signed audit envelope; cap-gating via `@capability_required` on `function_tool` bodies. Paired example: research crew with citation enforcement.
- [Microsoft Agent Framework adapter](https://yutha.ai/developer/maf/): each `agent_framework.Agent` becomes a Yutha agent; cap-gating on async-native tool callables (no sync/async bridge); honest v1 scope vs `WorkflowBuilder` / `RequestInfoExecutor` / `FunctionMiddleware` follow-ons. Paired example: DevOps incident-response.
- [Writing a new adapter](https://yutha.ai/developer/writing-adapters/): how to add support for a framework Yutha doesn't yet ship for.

## Examples

- [Examples overview](https://yutha.ai/examples/): worked end-to-end use cases.
- [Customer support with refund cap](https://yutha.ai/examples/customer-support/): classifier + L1 + L2 escalation, supervisor-required for refunds above a threshold.
- [Code review crew with security boundaries](https://yutha.ai/examples/code-review/): reviewer + auto-fix agents with capability gates around security-tagged paths.
- [AP & invoice processing with payment caps](https://yutha.ai/examples/ap-invoice/): payment cap + CFO approval procedure + duplicate-detection reverse path.
- [Research crew with citation enforcement](https://yutha.ai/examples/research-crew/): OpenAI Agents adapter — Lead/Researcher/FactChecker/Writer with constitution-enforced citations and quarantine on uncited claims.
- [DevOps incident-response with SRE countersign](https://yutha.ai/examples/devops-incident/): Microsoft Agent Framework adapter — IncidentCommander/Diagnoser/SchemaSpecialist/SRE/RemediationExec with production-schema-change quarantine.
- [Procurement platform with vendor isolation](https://yutha.ai/examples/procurement-platform/): first heterogeneous-framework demo — LangGraph buyer intake plus three CrewAI vendor agents on one swarm; bounded capabilities with `OnlyIfTagged` caveats pin each vendor to its invited RFPs; a Cedar+ constitution forbids cross-vendor data leakage; a bad-acting vendor walks the four-stage enforcement loop.

## Reference

- [Specs](https://yutha.ai/reference/specs/): pointers into /spec/ on GitHub for the wire and artifact specifications.
- [RFCs](https://yutha.ai/reference/rfcs/): pointer to the RFC archive at /spec/rfcs/, with notes on the more notable ones.
- [Canonical actions](https://yutha.ai/reference/canonical-actions/): the registry of action_kind values that may appear in receipts.

## Community

- [Community overview](https://yutha.ai/community/): how to participate.
- [Contributing](https://yutha.ai/community/CONTRIBUTING/): lightweight contribution guide for the solo-maintainer phase.
- [Code of conduct](https://yutha.ai/community/CODE_OF_CONDUCT/): the Contributor Covenant.
- [Security policy](https://yutha.ai/community/SECURITY/): how to report vulnerabilities; realistic solo-maintainer response timelines.
- [RFC process](https://yutha.ai/community/RFC_PROCESS/): practical guide for filing an RFC.

## Optional

- [Full text dump for LLMs](https://yutha.ai/llms-full.txt): every page above concatenated into a single file for one-shot ingestion.
- [GitHub repository](https://github.com/abhinavg6/yutha): source, RFC archive, conformance suite.