agent-os-kernel 1.1.0__tar.gz → 1.2.0__tar.gz

{agent_os_kernel-1.1.0 → agent_os_kernel-1.2.0}/.gitignore

@@ -152,3 +152,5 @@ benchmark_results/
 # Experiment outputs
 experiments/outputs/
 experiments/logs/
+
+node_modules/

agent_os_kernel-1.2.0/PKG-INFO

@@ -0,0 +1,647 @@
+Metadata-Version: 2.4
+Name: agent-os-kernel
+Version: 1.2.0
+Summary: A kernel architecture for governing autonomous AI agents with Nexus Trust Exchange
+Project-URL: Homepage, https://github.com/imran-siddique/agent-os
+Project-URL: Documentation, https://github.com/imran-siddique/agent-os/tree/master/docs
+Project-URL: Repository, https://github.com/imran-siddique/agent-os
+Project-URL: Bug Tracker, https://github.com/imran-siddique/agent-os/issues
+Author-email: Imran Siddique <imran.siddique@microsoft.com>
+Maintainer-email: Imran Siddique <imran.siddique@microsoft.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,control-plane,governance,kernel,llm,multi-agent,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: amb
+Requires-Dist: aiofiles>=23.0.0; extra == 'amb'
+Requires-Dist: anyio>=3.0.0; extra == 'amb'
+Provides-Extra: cmvk
+Requires-Dist: numpy>=1.20.0; extra == 'cmvk'
+Provides-Extra: dev
+Requires-Dist: anyio>=3.0.0; extra == 'dev'
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: numpy>=1.20.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: rich>=13.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: typer>=0.9.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.20.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: agent-os[amb,cmvk,iatp,mcp,nexus,observability]; extra == 'full'
+Provides-Extra: iatp
+Requires-Dist: cryptography>=42.0.0; extra == 'iatp'
+Requires-Dist: fastapi>=0.100.0; extra == 'iatp'
+Requires-Dist: httpx>=0.24.0; extra == 'iatp'
+Requires-Dist: pynacl>=1.5.0; extra == 'iatp'
+Requires-Dist: uvicorn>=0.20.0; extra == 'iatp'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: nexus
+Requires-Dist: agent-os[iatp]; extra == 'nexus'
+Requires-Dist: pyyaml>=6.0.0; extra == 'nexus'
+Requires-Dist: structlog>=24.1.0; extra == 'nexus'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'observability'
+Requires-Dist: prometheus-client>=0.17.0; extra == 'observability'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Agent OS
+
+**A kernel architecture for governing autonomous AI agents**
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![CI](https://github.com/imran-siddique/agent-os/actions/workflows/ci.yml/badge.svg)](https://github.com/imran-siddique/agent-os/actions/workflows/ci.yml)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code-Extension-007ACC?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=agent-os.agent-os-vscode)
+[![Documentation](https://img.shields.io/badge/docs-imran--siddique.github.io-blue)](https://imran-siddique.github.io/agent-os-docs/)
+
+[Quick Start](#quick-example) • [Documentation](https://imran-siddique.github.io/agent-os-docs/) • [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=agent-os.agent-os-vscode) • [Examples](examples/)
+
+<br/>
+
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/imran-siddique/agent-os)
+
+*Try Agent OS instantly in your browser - no installation required*
+
+</div>
+
+---
+
+<p align="center">
+  <img src="assets/demo-terminal.svg" alt="Agent OS Terminal Demo" width="700"/>
+</p>
+
+---
+
+## 🎯 What You'll Build in 5 Minutes
+
+```python
+from agent_os import KernelSpace, Policy
+
+# 1. Define safety policies (not prompts - actual enforcement)
+kernel = KernelSpace(policies=[
+    Policy.no_destructive_sql(),      # Block DROP, DELETE without WHERE
+    Policy.file_access("/workspace"), # Restrict file access
+    Policy.rate_limit(100, "1m"),     # Max 100 calls/minute
+])
+
+# 2. Your agent code runs in user space
+@kernel.register
+async def data_analyst(query: str):
+    result = await llm.generate(f"Analyze: {query}")
+    return result
+
+# 3. Kernel intercepts and validates EVERY action
+result = await kernel.execute(data_analyst, "revenue by region")
+# ✅ Safe queries execute
+# ❌ "DROP TABLE users" → BLOCKED (not by prompt, by kernel)
+```
+
+**Result:** Defined policies are deterministically enforced by the kernel—not by hoping the LLM follows instructions.
+
+---
+
+## What is Agent OS?
+
+Agent OS applies operating system concepts to AI agent governance. Instead of relying on prompts to enforce safety ("please don't do dangerous things"), it provides application-level middleware that intercepts and validates agent actions before execution.
+
+> **Note:** This is application-level enforcement (Python middleware), not OS kernel-level isolation. Agents run in the same process. For true isolation, run agents in containers.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              USER SPACE (Agent Code)                    │
+│   Your agent code runs here. The kernel intercepts      │
+│   actions before they execute.                          │
+├─────────────────────────────────────────────────────────┤
+│              KERNEL SPACE                               │
+│   Policy Engine │ Flight Recorder │ Signal Dispatch     │
+│   Actions are checked against policies before execution │
+└─────────────────────────────────────────────────────────┘
+```
+
+## The Idea
+
+**Prompt-based safety** asks the LLM to follow rules. The LLM decides whether to comply.
+
+**Kernel-based safety** intercepts actions before execution. The policy engine decides, not the LLM.
+
+This is the same principle operating systems use: applications request resources, the kernel grants or denies access based on permissions.
+
+---
+
+## Architecture
+
+```
+agent-os/
+├── src/agent_os/             # Core Python package
+│   ├── __init__.py           # Public API
+│   ├── cli.py                # Command-line interface
+│   └── integrations/         # Framework adapters
+├── modules/                  # Kernel Modules (4-layer architecture)
+│   ├── primitives/           # Layer 1: Base types and failures
+│   ├── cmvk/                 # Layer 1: Cross-model verification
+│   ├── emk/                  # Layer 1: Episodic memory kernel
+│   ├── caas/                 # Layer 1: Context-as-a-Service
+│   ├── amb/                  # Layer 2: Agent message bus
+│   ├── iatp/                 # Layer 2: Inter-agent trust protocol
+│   ├── atr/                  # Layer 2: Agent tool registry
+│   ├── observability/        # Layer 2: Prometheus + OpenTelemetry
+│   ├── control-plane/        # Layer 3: THE KERNEL (policies, signals)
+│   ├── scak/                 # Layer 4: Self-correcting agent kernel
+│   ├── mute-agent/           # Layer 4: Face/Hands architecture
+│   └── mcp-kernel-server/    # Integration: MCP protocol support
+├── extensions/               # IDE & AI Assistant Extensions
+│   ├── vscode/               # VS Code extension
+│   ├── mcp-server/           # Claude Desktop MCP Server
+│   ├── copilot/              # GitHub Copilot integration
+│   ├── jetbrains/            # IntelliJ/PyCharm plugin
+│   ├── cursor/               # Cursor IDE extension
+│   ├── chrome/               # Chrome extension
+│   └── github-cli/           # gh CLI extension
+├── examples/                 # Working examples
+│   ├── quickstart/           # Start here: my_first_agent.py
+│   ├── demo-app/             # Full demo application
+│   ├── hello-world/          # Minimal example
+│   └── [domain examples]/    # Real-world use cases
+├── docs/                     # Documentation
+├── tests/                    # Test suite (organized by layer)
+├── notebooks/                # Jupyter tutorials
+└── templates/                # Policy templates
+```
+
+---
+
+## Core Modules
+
+| Module | Layer | Description |
+|--------|-------|-------------|
+| [`primitives`](modules/primitives/) | 1 | Base types and failure modes |
+| [`cmvk`](modules/cmvk/) | 2 | Cross-model verification (consensus across LLMs) |
+| [`amb`](modules/amb/) | 2 | Agent message bus (decoupled communication) |
+| [`iatp`](modules/iatp/) | 2 | Inter-agent trust protocol (sidecar-based) |
+| [`emk`](modules/emk/) | 2 | Episodic memory kernel (append-only ledger) |
+| [`control-plane`](modules/control-plane/) | 3 | **THE KERNEL** - Policy engine, signals, VFS |
+| [`observability`](modules/observability/) | 3 | Prometheus metrics + OpenTelemetry tracing |
+| [`scak`](modules/scak/) | 4 | Self-correcting agent kernel |
+| [`mute-agent`](modules/mute-agent/) | 4 | Decoupled reasoning/execution architecture |
+| [`atr`](modules/atr/) | 4 | Agent tool registry (runtime discovery) |
+| [`caas`](modules/caas/) | 4 | Context-as-a-Service (RAG routing) |
+| [`mcp-kernel-server`](modules/mcp-kernel-server/) | Int | MCP server for Claude Desktop |
+
+---
+
+## IDE & CLI Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| [`vscode`](extensions/vscode/) | VS Code extension with real-time policy checks |
+| [`jetbrains`](extensions/jetbrains/) | IntelliJ, PyCharm, WebStorm plugin |
+| [`cursor`](extensions/cursor/) | Cursor IDE extension (Composer integration) |
+| [`copilot`](extensions/copilot/) | GitHub Copilot safety layer |
+| [`mcp-server`](extensions/mcp-server/) | **NEW** MCP Server for Claude Desktop |
+| [`github-cli`](extensions/github-cli/) | `gh agent-os` CLI extension |
+| [`chrome`](extensions/chrome/) | Chrome extension for web agents |
+
+---
+
+## Install
+
+```bash
+pip install agent-os
+```
+
+Or with optional components:
+
+```bash
+pip install agent-os[cmvk]           # + cross-model verification
+pip install agent-os[iatp]           # + inter-agent trust
+pip install agent-os[observability]  # + Prometheus/OpenTelemetry
+pip install agent-os[full]           # Everything
+```
+
+### One-Command Quickstart
+
+**macOS/Linux:**
+```bash
+curl -sSL https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+iwr -useb https://raw.githubusercontent.com/imran-siddique/agent-os/main/scripts/quickstart.ps1 | iex
+```
+
+---
+
+## Quick Example
+
+```python
+from agent_os import KernelSpace
+
+# Create kernel with policy
+kernel = KernelSpace(policy="strict")
+
+@kernel.register
+async def my_agent(task: str):
+    # Your LLM code here
+    return llm.generate(task)
+
+# Actions are checked against policies
+result = await kernel.execute(my_agent, "analyze this data")
+```
+
+---
+
+## POSIX-Inspired Primitives
+
+Agent OS borrows concepts from POSIX operating systems:
+
+| Concept | POSIX | Agent OS |
+|---------|-------|----------|
+| Process control | `SIGKILL`, `SIGSTOP` | `AgentSignal.SIGKILL`, `AgentSignal.SIGSTOP` |
+| Filesystem | `/proc`, `/tmp` | VFS with `/mem/working`, `/mem/episodic` |
+| IPC | Pipes (`\|`) | Typed IPC pipes between agents |
+| Syscalls | `open()`, `read()` | `kernel.execute()` |
+
+### Signals
+
+```python
+from agent_os import SignalDispatcher, AgentSignal
+
+dispatcher.signal(agent_id, AgentSignal.SIGSTOP)  # Pause
+dispatcher.signal(agent_id, AgentSignal.SIGCONT)  # Resume
+dispatcher.signal(agent_id, AgentSignal.SIGKILL)  # Terminate
+```
+
+### VFS (Virtual File System)
+
+```python
+from agent_os import AgentVFS
+
+vfs = AgentVFS(agent_id="agent-001")
+vfs.write("/mem/working/task.txt", "Current task")
+vfs.read("/policy/rules.yaml")  # Read-only from user space
+```
+
+---
+
+## Framework Integrations
+
+Wrap existing frameworks with Agent OS governance:
+
+```python
+# LangChain
+from agent_os.integrations import LangChainKernel
+governed = LangChainKernel().wrap(my_chain)
+
+# OpenAI Assistants
+from agent_os.integrations import OpenAIKernel
+governed = OpenAIKernel().wrap_assistant(assistant, client)
+
+# Semantic Kernel
+from agent_os.integrations import SemanticKernelWrapper
+governed = SemanticKernelWrapper().wrap(sk_kernel)
+
+# CrewAI
+from agent_os.integrations import CrewAIKernel
+governed = CrewAIKernel().wrap(my_crew)
+```
+
+See [integrations documentation](docs/integrations.md) for full details.
+
+---
+
+## How It Differs from Other Tools
+
+**Agent Frameworks** (LangChain, CrewAI): Build agents. Agent OS governs them. Use together.
+
+**Safety Tools** (NeMo Guardrails, LlamaGuard): Input/output filtering. Agent OS intercepts actions mid-execution.
+
+| Tool | Focus | When it acts |
+|------|-------|--------------|
+| LangChain/CrewAI | Building agents | N/A (framework) |
+| NeMo Guardrails | Input/output filtering | Before/after LLM call |
+| LlamaGuard | Content classification | Before/after LLM call |
+| **Agent OS** | Action interception | During execution |
+
+You can use them together:
+
+```python
+from langchain.agents import AgentExecutor
+from agent_os import KernelSpace
+
+kernel = KernelSpace(policy="strict")
+
+@kernel.govern
+async def my_langchain_agent(task: str):
+    return agent_executor.invoke({"input": task})
+```
+
+---
+
+## Examples
+
+The `examples/` directory contains working demos:
+
+### Getting Started
+
+| Demo | Description | Command |
+|------|-------------|---------|
+| [hello-world](examples/hello-world/) | Simplest example (15 lines) | `cd examples/hello-world && python agent.py` |
+| [chat-agent](examples/chat-agent/) | Interactive chatbot with memory | `cd examples/chat-agent && python chat.py` |
+| [tool-using-agent](examples/tool-using-agent/) | Agent with safe tools | `cd examples/tool-using-agent && python agent.py` |
+
+### Production Demos (with Observability)
+
+| Demo | Description | Command |
+|------|-------------|---------|
+| [carbon-auditor](examples/carbon-auditor/) | Multi-model verification | `cd examples/carbon-auditor && docker-compose up` |
+| [grid-balancing](examples/grid-balancing/) | Multi-agent coordination (100 agents) | `cd examples/grid-balancing && docker-compose up` |
+| [defi-sentinel](examples/defi-sentinel/) | Real-time attack detection | `cd examples/defi-sentinel && docker-compose up` |
+| [pharma-compliance](examples/pharma-compliance/) | Document analysis | `cd examples/pharma-compliance && docker-compose up` |
+
+Each production demo includes:
+- **Grafana dashboard** on port 300X
+- **Prometheus metrics** on port 909X  
+- **Jaeger tracing** on port 1668X
+
+```bash
+# Run carbon auditor with full observability
+cd examples/carbon-auditor
+cp .env.example .env  # Optional: add API keys
+docker-compose up
+
+# Open dashboards
+open http://localhost:3000  # Grafana (admin/admin)
+open http://localhost:16686 # Jaeger traces
+```
+
+---
+
+## Safe Tool Plugins
+
+Agent OS includes pre-built safe tools for agents:
+
+```python
+from atr.tools.safe import create_safe_toolkit
+
+toolkit = create_safe_toolkit("standard")
+
+# Available tools
+http = toolkit["http"]        # Rate-limited HTTP with domain whitelisting
+files = toolkit["files"]      # Sandboxed file reader
+calc = toolkit["calculator"]  # Safe math (no eval)
+json = toolkit["json"]        # Safe JSON/YAML parsing
+dt = toolkit["datetime"]      # Timezone-aware datetime
+text = toolkit["text"]        # Text processing
+
+# Use a tool
+result = await http.get("https://api.github.com/users/octocat")
+```
+
+See [Creating Custom Tools](docs/tutorials/custom-tools.md) for more.
+
+---
+
+## Message Bus Adapters
+
+Connect agents using various message brokers:
+
+```python
+from amb_core.adapters import RedisBroker, KafkaBroker, NATSBroker
+
+# Redis (low latency)
+broker = RedisBroker(url="redis://localhost:6379")
+
+# Kafka (high throughput)
+broker = KafkaBroker(bootstrap_servers="localhost:9092")
+
+# NATS (cloud-native)
+broker = NATSBroker(servers=["nats://localhost:4222"])
+
+# Also: AzureServiceBusBroker, AWSSQSBroker
+```
+
+See [Message Bus Adapters Guide](docs/tutorials/message-bus-adapters.md) for details.
+
+---
+
+## CLI Tool
+
+Agent OS includes a CLI for terminal workflows:
+
+```bash
+# Check files for safety violations
+agentos check src/app.py
+
+# Check staged git files (pre-commit)
+agentos check --staged
+
+# Multi-model code review
+agentos review src/app.py --cmvk
+
+# Install git pre-commit hook
+agentos install-hooks
+
+# Initialize Agent OS in project
+agentos init
+```
+
+---
+
+## MCP Integration (Claude Desktop)
+
+Agent OS provides an MCP server for Claude Desktop integration:
+
+```bash
+# Install
+pip install agent-os[mcp]
+
+# Run MCP server
+mcp-kernel-server --stdio
+
+# Or add to claude_desktop_config.json:
+{
+  "mcpServers": {
+    "agent-os": {
+      "command": "mcp-kernel-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Exposes tools: `cmvk_verify`, `kernel_execute`, `iatp_sign`, `iatp_verify`
+
+See [MCP server documentation](modules/mcp-kernel-server/README.md).
+
+---
+
+## Documentation
+
+### Tutorials
+- [5-Minute Quickstart](docs/tutorials/5-minute-quickstart.md) - Get running fast
+- [30-Minute Deep Dive](docs/tutorials/30-minute-deep-dive.md) - Comprehensive walkthrough
+- [Building Your First Governed Agent](docs/tutorials/first-governed-agent.md) - Complete tutorial
+- [Using Message Bus Adapters](docs/tutorials/message-bus-adapters.md) - Connect agents
+- [Creating Custom Tools](docs/tutorials/custom-tools.md) - Build safe tools
+- [Cheatsheet](docs/cheatsheet.md) - Quick reference
+
+### Interactive Notebooks
+Learn by doing with Jupyter notebooks:
+
+| Notebook | Description | Time |
+|----------|-------------|------|
+| [Hello Agent OS](notebooks/01-hello-agent-os.ipynb) | Your first governed agent | 5 min |
+| [Episodic Memory](notebooks/02-episodic-memory-demo.ipynb) | Agent memory that persists | 15 min |
+| [Time-Travel Debugging](notebooks/03-time-travel-debugging.ipynb) | Replay and debug decisions | 20 min |
+| [Cross-Model Verification](notebooks/04-cross-model-verification.ipynb) | Detect hallucinations | 15 min |
+| [Multi-Agent Coordination](notebooks/05-multi-agent-coordination.ipynb) | Trust between agents | 20 min |
+| [Policy Engine](notebooks/06-policy-engine.ipynb) | Deep dive into policies | 15 min |
+
+### Reference
+- [Quickstart Guide](docs/quickstart.md) - 60 seconds to first agent
+- [Framework Integrations](docs/integrations.md) - LangChain, OpenAI, etc.
+- [Kernel Internals](docs/kernel-internals.md) - How the kernel works
+- [Architecture Overview](docs/architecture.md) - System design
+- [CMVK Algorithm](docs/cmvk-algorithm.md) - Cross-model verification
+- [RFC-003: Agent Signals](docs/rfcs/RFC-003-Agent-Signals.md) - POSIX-style signals
+- [RFC-004: Agent Primitives](docs/rfcs/RFC-004-Agent-Primitives.md) - Core primitives
+
+---
+
+## Status
+
+This is a research project exploring kernel concepts for AI agent governance. The code is functional but evolving.
+
+### Core (Production-Ready)
+The minimal trust boundary that's small enough to audit:
+- **Policy Engine**: Deterministic rule enforcement for defined patterns
+- **Flight Recorder**: SQLite-based audit logging (see known limitations below)
+- **SDK Adapters**: Intercept tool calls at SDK boundary (OpenAI, LangChain, CrewAI)
+
+### Extensions (Experimental)
+Additional capabilities built on the core:
+- Cross-model verification (CMVK), Inter-agent trust (IATP)
+- Supervisor agents, Constraint graphs, Shadow mode
+- IDE extensions (VS Code, JetBrains, Copilot)
+- Observability (Prometheus, OpenTelemetry)
+- Message bus adapters (Redis, Kafka, NATS)
+
+### Known Architectural Limitations
+Be aware of these design constraints:
+
+| Limitation | Impact | Mitigation |
+|------------|--------|------------|
+| **Application-level only** | Direct stdlib calls (subprocess, open) bypass kernel | Pair with container isolation for production |
+| **Blocklist-based policies** | Novel attack patterns not in rules will pass | Add AST-level parsing (#32), use defense in depth |
+| **Shadow Mode single-step** | Multi-step agent simulations diverge from reality | Use for single-turn validation only |
+| **No tamper-proof audit** | Flight Recorder SQLite can be modified by compromised agent | Write to external sink for critical audits |
+| **Provider-coupled adapters** | Each SDK needs separate adapter | Abstract interface planned (#47) |
+
+See [GitHub Issues](https://github.com/imran-siddique/agent-os/issues) for the full roadmap.
+- Some integrations are basic wrappers
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**ModuleNotFoundError: No module named 'agent_os'**
+```bash
+# Install from source
+git clone https://github.com/imran-siddique/agent-os.git
+cd agent-os
+pip install -e .
+```
+
+**Permission errors on Windows**
+```bash
+# Run PowerShell as Administrator, or use --user flag
+pip install --user -e .
+```
+
+**Docker not working**
+```bash
+# Build with Dockerfile (no Docker Compose needed for simple tests)
+docker build -t agent-os .
+docker run -it agent-os python examples/hello-world/agent.py
+```
+
+**Tests failing with API errors**
+```bash
+# Most tests work without API keys - mock mode is default
+pytest tests/ -v
+
+# For real LLM tests, set environment variables
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## FAQ
+
+**Q: How is this different from LangChain/CrewAI?**
+A: LangChain and CrewAI are *frameworks* for building agents. Agent OS is *infrastructure* for governing them. Use them together—wrap your LangChain agent with Agent OS for safety guarantees.
+
+**Q: What does "deterministic enforcement" mean?**
+A: When a policy matches an action, that action is blocked—not by asking the LLM nicely. The middleware intercepts and stops it. However, this only works for patterns the policy engine knows about. Novel attacks that don't match defined rules will pass through.
+
+**Q: Do I need to rewrite my agents?**
+A: No. Agent OS provides integration wrappers for LangChain, CrewAI, AutoGen, OpenAI Assistants, and Semantic Kernel. Wrap your existing code and add governance.
+
+**Q: Does it work with local models (Ollama, llama.cpp)?**
+A: Yes. Agent OS is model-agnostic—it governs what agents *do*, not what LLM they use.
+
+**Q: How do I contribute?**
+A: See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Good first issues are labeled in GitHub.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/imran-siddique/agent-os.git
+cd agent-os
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+
+---
+
+<div align="center">
+
+**Exploring kernel concepts for AI agent safety.**
+
+[GitHub](https://github.com/imran-siddique/agent-os) · [Docs](docs/)
+
+</div>