yaab-sdk 0.1.0__tar.gz

yaab_sdk-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.so
+.coverage
+htmlcov/
+
+# Rust
+target/
+Cargo.lock
+
+# Local
+live_e2e_report.json
+*.log
+*.db
+*.sqlite
+*.sqlite3
+.DS_Store
+.env
+yaab_audit.db
+yaab_registry.db
+gap_analysis_parsed.json
+
+# Docs site build output
+site/
+
+# Local tooling, scratch, and internal working notes (never commit)
+.claude/
+CLAUDE.md
+graphify-out/
+dist-rust/
+docs/superpowers/
+docs/ADK_GAP_ANALYSIS.md
+docs/COMPARISON.md
+docs/ROADMAP.md
+docs/RESEARCH_FEATURE_DEMAND.md

yaab_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YAAB contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yaab_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,533 @@
+Metadata-Version: 2.4
+Name: yaab-sdk
+Version: 0.1.0
+Summary: Yet Another Agent Builder — a type-safe, governance-first agent SDK with a Rust performance core.
+Project-URL: Homepage, https://github.com/sthitaprajnas/yaab
+Project-URL: Repository, https://github.com/sthitaprajnas/yaab
+Author: YAAB contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,compliance,governance,litellm,llm,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: all
+Requires-Dist: beautifulsoup4>=4.12; extra == 'all'
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: litellm>=1.40; extra == 'all'
+Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Requires-Dist: pypdf>=4.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: uvicorn>=0.29; extra == 'all'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.5; extra == 'chroma'
+Provides-Extra: deepeval
+Requires-Dist: deepeval>=1.0; extra == 'deepeval'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: maturin>=1.5; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == 'http'
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=2.0; extra == 'langfuse'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'
+Provides-Extra: llm-guard
+Requires-Dist: llm-guard>=0.3; extra == 'llm-guard'
+Provides-Extra: logfire
+Requires-Dist: logfire>=0.30; extra == 'logfire'
+Provides-Extra: nemo
+Requires-Dist: nemoguardrails>=0.9; extra == 'nemo'
+Provides-Extra: opensearch
+Requires-Dist: opensearch-py>=2.4; extra == 'opensearch'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0; extra == 'oracle'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Provides-Extra: pinecone
+Requires-Dist: pinecone>=5.0; extra == 'pinecone'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: presidio
+Requires-Dist: presidio-analyzer>=2.2; extra == 'presidio'
+Requires-Dist: presidio-anonymizer>=2.2; extra == 'presidio'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.9; extra == 'qdrant'
+Provides-Extra: rag
+Requires-Dist: beautifulsoup4>=4.12; extra == 'rag'
+Requires-Dist: pypdf>=4.0; extra == 'rag'
+Provides-Extra: ragas
+Requires-Dist: datasets>=2.0; extra == 'ragas'
+Requires-Dist: ragas>=0.1; extra == 'ragas'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: rust
+Requires-Dist: yaab-core>=0.1.0; extra == 'rust'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == 'serve'
+Requires-Dist: uvicorn>=0.29; extra == 'serve'
+Provides-Extra: weaviate
+Requires-Dist: weaviate-client>=4.5; extra == 'weaviate'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# YAAB — Yet Another Agent Builder
+
+**YAAB is the agent SDK for teams that have to ship agents into production AND prove it to a regulator.**
+Type-safe, optimizable, durable, and simple — the best ideas from across the
+agent ecosystem on one runtime, on a universal LiteLLM model layer, with a
+Rust core that accelerates the compute-bound hot paths (and an opt-in native
+graph engine). Governance, an agent registry, audit lineage, and policy
+guardrails are **first-class, not bolted on**.
+
+📖 **[Documentation](https://sthitaprajnas.github.io/yaab/)** — guides, concepts, and the full API reference.
+
+```python
+from yaab import Agent
+
+agent = Agent("assistant", model="openai/gpt-4o", instructions="Be concise.")
+print(agent.run_sync("Say hello").output)
+```
+
+No API key? Everything runs offline with `TestModel`:
+
+```python
+from yaab import Agent
+from yaab.testing import TestModel
+
+agent = Agent("assistant", model=TestModel("hi!"))
+assert agent.run_sync("hello").output == "hi!"
+```
+
+---
+
+## Why YAAB
+
+No single existing framework covers the regulated-enterprise agent use case.
+Each excels at one layer and is weak elsewhere. YAAB fuses the best ideas from
+each onto **one runtime** and adds the layer none of them ship: enterprise
+governance.
+
+| Capability | ADK | DSPy | Pydantic AI | Strands | LangGraph | **YAAB** |
+|---|---|---|---|---|---|---|
+| Type-safe `Agent[Deps, Output]` | ◑ | ✕ | ✓ | ◑ | ◑ | **✓** |
+| Model-driven fast path | ◑ | ✕ | ✓ | ✓ | ✕ | **✓** |
+| Durable graph + checkpoints + HITL | ◑ | ✕ | ◑ | ✕ | ✓ | **✓** |
+| Optimizable programs (compile) | ✕ | ✓ | ✕ | ✕ | ✕ | **✓** |
+| Universal models (LiteLLM) | ◑ | ◑ | ✓ | ✓ | ◑ | **✓** |
+| MCP + A2A interop | ✓ | ✕ | ◑ | ◑ | ✕ | **✓** |
+| `fastapi_server_app` / serve as A2A server | ✕ | ✕ | ✕ | ◑ | ✕ | **✓** |
+| Pluggable auth (bearer / API key / OAuth2)| ◑ | ✕ | ✕ | ◑ | ✕ | **✓** |
+| OTel GenAI-convention tracing | ✓ | ◑ | ✓ | ✓ | ◑ | **✓** |
+| Prompt management + versioning | ✕ | ◑ | ✕ | ✕ | ✕ | **✓** |
+| Built-in RAG (provider-neutral) | ◑ cloud | ◑ cloud | ✕ | ◑ cloud | ◑ | **✓** |
+| RAG access control + citations + faithfulness | ✕ | ✕ | ✕ | ✕ | ✕ | **✓** |
+| Built-in tools + sandboxed code exec | ◑ | ✕ | ◑ | ◑ | ◑ | **✓** |
+| Eval (RAGAS / DeepEval adapters) | ◑ | ◑ | ◑ | ✕ | ◑ | **✓** |
+| AG-UI streaming + structured-output streaming | ✕ | ◑ | ◑ | ✕ | ◑ | **✓** |
+| Cloud backends (Aurora/pgvector/OpenSearch/Oracle/Chroma/Qdrant/Pinecone/Weaviate/Redis) | ◑ | ✕ | ◑ | ◑ | ◑ | **✓** |
+| **Agent registry + lifecycle FSM** | ✕ | ✕ | ✕ | ✕ | ✕ | **✓** |
+| **Guardrail / policy engine** | ◑ | ✕ | ◑ | ✕ | ◑ | **✓** |
+| **Tamper-evident audit + lineage** | ✕ | ✕ | ✕ | ✕ | ✕ | **✓** |
+| **Compliance mappers (SR 11-7 / EU AI Act / NIST / ISO 42001 / SOC 2)** | ✕ | ✕ | ✕ | ✕ | ✕ | **✓** |
+| **Rust performance core** | ✕ | ✕ | ✕ | ✕ | ✕ | **✓** |
+
+✓ first-class · ◑ partial / via add-on · ✕ not provided.
+
+---
+
+## Architecture
+
+YAAB is **progressive disclosure**: three lines to a working agent, but every
+layer is openable.
+
+**Python is the brain and the entire developer surface** — the `Agent`,
+`Runner`, model layer, tools, governance, orchestration logic, and every
+extension point are Python (~95% of the code). **Rust (`yaab-core`) is a small
+performance core** (~325 lines) holding the compute-bound primitives where
+native speed pays off: vector similarity, checkpoint serialization, channel
+reducers, BSP superstep planning + whole-superstep state folding, and
+tamper-evident audit hashing. Every Rust primitive has a **pure-Python
+fallback**, so YAAB installs and runs anywhere — Rust is an accelerator, never a
+hard dependency. This is the proven pydantic-core / Polars / Ruff pattern: a
+thin native core under a rich Python API.
+
+```
+L5  Developer API (Python)   — Agent, tools, signatures, DI, skills
+L4  Orchestration (Python)   — fast path · durable graph · optimizable programs
+L3  Governance & Registry    — registry, lifecycle, policy, audit, evals, compliance
+L2  Model Layer (LiteLLM)    — streaming, tools, structured output, fallbacks, cost
+L1  yaab-core (RUST/PyO3)    — vectors · channels · checkpoints · scheduler · hashing
+        ↑ accelerates the hot paths called by L1–L4; pure-Python fallback always present
+```
+
+What runs **where**, precisely:
+
+| Concern | Runs in |
+|---|---|
+| Agent loop, tool dispatch, model calls (I/O-bound) | **Python** (network is the bottleneck, not the loop) |
+| Governance, registry, lifecycle, compliance | **Python** |
+| Graph control flow (routing, HITL, checkp-orchestration) | **Python** |
+| Vector top-k, checkpoint (de)serialize, channel reduce, superstep fold, audit hash | **Rust** (Python fallback) |
+
+Check which core is active:
+
+```python
+import yaab
+print(yaab.BACKEND)   # "rust" or "python"
+```
+
+### Opt-in Rust graph engine
+
+The durable graph lets you choose how each superstep's state is advanced — your
+call, per compiled graph:
+
+```python
+app = graph.compile(engine="auto")     # rust if the extension is built, else python (default)
+app = graph.compile(engine="rust")     # force the native whole-superstep fold (raises if unbuilt)
+app = graph.compile(engine="python")   # force the pure-Python engine
+print(app.engine)                       # "rust" | "python"
+```
+
+Both engines produce **identical results**; `rust` folds an entire superstep's
+state in one native call instead of one cross-language hop per key. The Python
+developer API is unchanged either way.
+
+---
+
+## The three orchestration paths (one runtime)
+
+**1. Fast path — model-driven (Strands-style).** Just call the agent.
+
+```python
+from yaab import Agent, tool
+
+@tool
+def get_weather(city: str) -> str:
+    """Return the weather for a city."""
+    return f"It's sunny in {city}."
+
+agent = Agent("weather", model="openai/gpt-4o", tools=[get_weather])
+print(agent.run_sync("What's the weather in Paris?").output)
+```
+
+**2. Graph path — durable (LangGraph-style)** with checkpoints and HITL.
+
+```python
+from yaab.graph import StateGraph, Channel, START, END, MemorySaver
+
+g = StateGraph(channels={"count": Channel("add", default=0)})
+g.add_node("inc", lambda s: {"count": 1})
+g.add_edge(START, "inc")
+g.add_conditional_edges("inc", lambda s: "inc" if s["count"] < 3 else END,
+                        {"inc": "inc", END: END})
+
+app = g.compile(checkpointer=MemorySaver())
+print(app.invoke({}).state)   # {'count': 3}
+```
+
+Human-in-the-loop pauses and resumes by `thread_id`:
+
+```python
+def approve(state, ctx):
+    decision = ctx.interrupt({"need": "approval"})   # pauses on first pass
+    return {"approved": decision}
+
+# first call returns interrupted=True; resume with the human's answer:
+app.invoke({}, thread_id="t1")
+app.invoke(thread_id="t1", resume=True)
+```
+
+**3. Optimizable path — compiled (DSPy-style).** Tune at build time, freeze for prod.
+
+```python
+from yaab.optimize import Predict, BootstrapFewShot
+from yaab.governance.eval import Case
+
+qa = Predict("question -> answer", model="openai/gpt-4o")
+artifact = await BootstrapFewShot().compile(qa, trainset, metric)   # frozen, versioned
+qa.load(artifact)   # deterministic in production
+```
+
+---
+
+## Governance
+
+Governance is opt-in by **mode** (`off` / `observe` / `enforcing`) so YAAB is
+frictionless for prototyping but enforces registry, approval, and guardrails in
+production.
+
+```python
+from yaab import Agent, Runner
+from yaab.governance import (
+    GovernanceService, GovernanceMode, AgentCard, RiskTier, LifecycleState,
+    EvidenceArtifact,
+)
+
+gov = GovernanceService(mode=GovernanceMode.ENFORCING)
+
+# Register the agent and walk it through the model-risk lifecycle.
+gov.registry.register(AgentCard(agent_id="kyc-bot", name="KYC Bot", risk_tier=RiskTier.HIGH))
+gov.lifecycle.transition("kyc-bot", LifecycleState.IN_DEVELOPMENT,
+    evidence=[EvidenceArtifact(kind="development_docs"),
+              EvidenceArtifact(kind="conceptual_soundness")])
+# ... validation → approval ...
+
+agent = Agent("KYC Bot", model="openai/gpt-4o", registry_id="kyc-bot")
+runner = Runner(governance=gov)        # refuses unregistered/unapproved agents
+```
+
+You get, out of the box:
+
+- **Agent registry** — A2A-compatible cards with ownership, risk tier, decision
+  authority, data lineage, and approval status; produces the SR 11-7 / EU AI Act
+  **model inventory**.
+- **Lifecycle FSM** — `DRAFT → IN_DEVELOPMENT → IN_VALIDATION → APPROVED →
+  DEPLOYED → MONITORED → DECOMMISSIONED`, each transition evidence-gated and audited.
+- **Policy / guardrail engine** — prompt-injection, PII (redact), secret, topic,
+  and system-prompt-leak scanners; pluggable (LLM Guard / NeMo / custom).
+- **Tamper-evident audit log** — append-only, **hash-chained in Rust**; every
+  run, model call, tool call, guard decision, and lifecycle change. `audit.verify()`
+  detects any retroactive edit.
+- **Evaluation** — code-first datasets/metrics that double as optimizer metrics
+  and drift monitoring.
+- **Compliance mappers** — project the data model onto **SR 11-7, EU AI Act,
+  NIST AI RMF, ISO/IEC 42001, SOC 2** and emit audit-ready reports.
+
+```bash
+yaab compliance report sr_11_7
+```
+
+> Compliance mappers produce *evidence*, not legal sign-off. Effective challenge
+> and conformity assessment still require qualified human reviewers — YAAB
+> produces the evidence; humans attest to it.
+
+---
+
+## Serve anywhere — local to cloud
+
+Local one-liner, or mount the ASGI app in any cloud (Lambda, Cloud Run, Fargate, K8s):
+
+```python
+from yaab import Agent
+from yaab.serve import fastapi_server_app
+from yaab.auth import BearerTokenAuth
+
+agent = Agent("assistant", model="openai/gpt-4o")
+app = fastapi_server_app(agent, auth=BearerTokenAuth({"secret-token": "alice"}))
+# uvicorn module:app  →  exposes /run, /a2a/tasks, /.well-known/agent.json, /health
+```
+
+`yaab serve mymodule:agent` runs it directly. The app speaks **A2A** (agent
+card + task endpoint), so other agents can discover and delegate to it. See
+[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) and the [`Dockerfile`](Dockerfile).
+
+---
+
+## Multi-agent & managers
+
+Compose agents as Sequential / Parallel / Loop / Swarm workflows — each is itself
+an agent, so they nest and drop into tools, graphs, and servers:
+
+```python
+from yaab import SequentialAgent, ParallelAgent, Swarm
+from yaab.multiagent import SwarmState
+
+pipeline = SequentialAgent("etl", [extractor, transformer, loader])
+board    = ParallelAgent("review", [legal, finance, risk])
+support  = Swarm("support", [triage, billing, tech], entry="triage")
+await support.run("I was double charged", deps=SwarmState())
+```
+
+Scoped session / memory / artifact **managers** keep state organized per app/user:
+
+```python
+from yaab import SessionManager, MemoryManager, ArtifactManager
+
+sessions = SessionManager()
+s = await sessions.create_session(app_name="bank", user_id="alice", state={"tier": "gold"})
+
+memory = MemoryManager()
+await memory.add("Alice prefers email", app_name="bank", user_id="alice")
+await memory.add_session_to_memory(s, app_name="bank", user_id="alice")
+
+artifacts = ArtifactManager()
+await artifacts.save("report.pdf", data, session_id=s.id)   # auto-versioned
+```
+
+Interop is first-class: import an **MCP** server's tools with `MCPClient` (or
+expose yours with `MCPServer`), and discover/delegate to remote agents over
+**A2A** with `RemoteAgent` (which is also a tool). See the docs below.
+
+## Built-in RAG (provider-neutral)
+
+A whole retrieval pipeline ships in the box — not delegated to a cloud service —
+with the governance pieces other SDKs lack:
+
+```python
+from yaab import Agent, KnowledgeBase
+from yaab.rag import load_directory
+
+kb = KnowledgeBase()                       # default: in-memory + Rust top-k
+kb.add(load_directory("./docs", glob="**/*.md"))   # pdf/html/csv/json loaders too
+agent = Agent("support", model="openai/gpt-4o", tools=[kb.as_tool()])
+```
+
+Per-user/document access control, source citations, dedup/incremental indexing,
+retrieval guardrails (context-poisoning defense), and faithfulness eval are all
+first-class. Swap the store for a cloud backend with one line — see below.
+
+## Batteries included
+
+Everything below is built in, extensible by `Protocol`, and selectable by name
+through the component registry — each integration is an optional extra:
+
+- **Built-in tools** — calculator, time, HTTP fetch, web search, and sandboxed
+  Python exec (subprocess by default; `DockerSandbox` for real isolation).
+- **Cloud backends** — sessions on Postgres/**Aurora**/Redis; vector stores on
+  **pgvector/Aurora**, **OpenSearch**, **Oracle 23ai**, Chroma, Qdrant,
+  Pinecone, Weaviate; graph checkpointers on Postgres/Aurora/Redis. All ship an
+  in-memory default and honor metadata filters for per-tenant isolation.
+- **Evaluation** — deterministic + LLM-judge metrics, plus **RAGAS** and
+  **DeepEval** adapters, behind one registry.
+- **Frontends & ops** — `yaab web` dev playground, **AG-UI** streaming
+  middleware, token + structured-output streaming, batch/offline inference,
+  resilience (rate limit + circuit breaker), YAML-config agents, OTel tracing
+  with Langfuse/Logfire/OTel audit sinks.
+
+```python
+from yaab import get_component, available_components
+available_components("vectorstore")   # memory, pgvector, aurora, chroma, qdrant, opensearch, oracle, pinecone, weaviate
+store = get_component("vectorstore", "opensearch", index="kb", hosts=[...])
+```
+
+See [Storage & backends](docs/storage-backends.md) and
+[Extending YAAB](docs/extending.md).
+
+## Documentation
+
+Full guides live in [`docs/`](docs/index.md):
+
+[**Get started**](docs/get-started.md) ·
+[Concepts](docs/concepts.md) ·
+[Samples](samples/README.md) ·
+[Quickstart](docs/quickstart.md) ·
+[Agents](docs/agents.md) ·
+[Tools](docs/tools.md) ·
+[Models](docs/models.md) ·
+[State (sessions/memory/artifacts)](docs/state.md) ·
+[Storage & backends](docs/storage-backends.md) ·
+[RAG](docs/rag.md) ·
+[Multi-agent](docs/multi-agent.md) ·
+[Streaming & events](docs/streaming-events.md) ·
+[Graph](docs/graph.md) ·
+[MCP & A2A](docs/interop.md) ·
+[Governance](docs/governance.md) ·
+[Evaluation](docs/evaluation.md) ·
+[Optimization](docs/optimization.md) ·
+[Prompts & skills](docs/prompts-skills.md) ·
+[Serving & auth](docs/serving.md) ·
+[Platform extensions](docs/platform.md) ·
+[Extending](docs/extending.md) ·
+[Deployment](docs/DEPLOYMENT.md)
+
+## Install
+
+```bash
+pip install yaab-sdk                 # SDK + high-performance async-first Python core
+pip install 'yaab-sdk[litellm]'      # universal model layer
+pip install 'yaab-sdk[all]'          # everything on PyPI (litellm, otel, rag, serve, …)
+```
+
+> The PyPI distribution is **`yaab-sdk`**; the import package and CLI are **`yaab`**:
+> `pip install yaab-sdk` → `import yaab` / `from yaab import Agent` / `$ yaab web`.
+
+**Two cores, one API.** `pip install yaab-sdk` ships a high-performance,
+async-first **pure-Python core** that works on every platform with zero build
+tooling — this is what runs today (`yaab.BACKEND == "python"`).
+
+The optional **`yaab-core`** Rust accelerator transparently speeds up the hot
+paths (vector search, checkpoint serialization, channel reducers, audit hashing,
+the graph engine). It is **not yet published to PyPI**, so today you build it
+from source (needs only `maturin`); a prebuilt `abi3` wheel and `pip install
+'yaab-sdk[rust]'` are planned. YAAB auto-selects Rust when present and falls back to
+Python otherwise — your code never changes either way.
+
+```bash
+maturin develop -m yaab-core/Cargo.toml --release   # build the Rust core locally
+```
+
+Check which core is active:
+
+```python
+import yaab; print(yaab.BACKEND)   # "rust" or "python"
+```
+
+---
+
+## CLI
+
+```bash
+yaab info                         # environment + active performance backend
+yaab init my_agent                # scaffold a starter agent
+yaab registry list                # the model inventory
+yaab compliance report eu_ai_act  # audit-ready compliance report
+yaab serve my_module:agent        # serve over HTTP / A2A
+```
+
+---
+
+## Project layout
+
+```
+yaab/            Python SDK (thin API layer)
+  agent.py runner.py types.py        core abstractions + event-driven runner
+  models/                            LiteLLM provider, instrumentation, TestModel
+  tools/ sessions/ memory/ artifacts/ services
+  graph/                             durable StateGraph + checkpointers
+  optimize/                          Signature / Module / Optimizer (DSPy-style)
+  governance/                        registry, lifecycle, policy, audit, eval, compliance
+  plugins/ prompts.py skills.py auth.py serve.py cli.py
+yaab-core/       Rust crate (PyO3) — the performance core
+examples/        runnable examples
+tests/           test suite (runs offline)
+```
+
+---
+
+## Status & caveats
+
+YAAB is **alpha**. The core runtime, governance layer, graph engine, and Rust
+core are implemented and tested offline; some borrowed capabilities are
+simplified relative to their source frameworks.
+Framework APIs evolve fast — pin versions and re-verify. Verify EU AI Act
+dates/fines against EUR-Lex and SR 11-7 language against the Federal Reserve's
+official letter.
+
+## License
+
+YAAB is open source under the **MIT License** — see [`LICENSE`](LICENSE). The
+Rust core (`yaab-core`) is published under the same license. SPDX identifier:
+`MIT`. You're free to use, modify, and distribute it, including commercially,
+provided the copyright and license notice are retained.