Metadata-Version: 2.4
Name: agent-os-kernel
Version: 1.1.0
Summary: A Safety-First Kernel for Autonomous AI Agents - POSIX-inspired primitives with 0% policy violation guarantee
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
Project-URL: Changelog, https://github.com/imran-siddique/agent-os/blob/master/CHANGELOG.md
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,autonomous,control-plane,governance,kernel,llm,multi-agent,posix,safety,signals,vfs
Classifier: Development Status :: 4 - Beta
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 :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Operating System Kernels
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: agent-os[dev,docs,full]; extra == 'all'
Provides-Extra: amb
Requires-Dist: aiofiles>=23.0.0; extra == 'amb'
Requires-Dist: anyio>=3.0.0; extra == 'amb'
Provides-Extra: atr
Requires-Dist: docker>=6.0.0; extra == 'atr'
Provides-Extra: caas
Requires-Dist: fastapi>=0.100.0; extra == 'caas'
Requires-Dist: numpy>=1.20.0; extra == 'caas'
Requires-Dist: pypdf2>=3.0.0; extra == 'caas'
Requires-Dist: scikit-learn>=1.0.0; extra == 'caas'
Requires-Dist: uvicorn>=0.20.0; extra == 'caas'
Provides-Extra: cmvk
Requires-Dist: numpy>=1.20.0; extra == 'cmvk'
Provides-Extra: control-plane
Provides-Extra: core
Requires-Dist: agent-os[cmvk,control-plane,primitives]; extra == 'core'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.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: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: emk
Requires-Dist: chromadb>=0.4.0; extra == 'emk'
Requires-Dist: numpy>=1.20.0; extra == 'emk'
Provides-Extra: full
Requires-Dist: agent-os[amb,atr,caas,cmvk,control-plane,emk,iatp,mute-agent,primitives,scak]; extra == 'full'
Provides-Extra: iatp
Requires-Dist: fastapi>=0.100.0; extra == 'iatp'
Requires-Dist: httpx>=0.24.0; extra == 'iatp'
Requires-Dist: uvicorn>=0.20.0; extra == 'iatp'
Provides-Extra: infrastructure
Requires-Dist: agent-os[amb,atr,iatp]; extra == 'infrastructure'
Provides-Extra: intelligence
Requires-Dist: agent-os[mute-agent,scak]; extra == 'intelligence'
Provides-Extra: mute-agent
Provides-Extra: primitives
Provides-Extra: scak
Requires-Dist: pyyaml>=6.0; extra == 'scak'
Description-Content-Type: text/markdown

# Agent OS

### The Linux Kernel for AI Agents

**0% Safety Violations • Deterministic Enforcement • POSIX-Inspired**

[![PyPI](https://img.shields.io/pypi/v/agent-os?label=PyPI)](https://pypi.org/project/agent-os/)
[![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)

[Quick Start](#-quick-start) • [Why Agent OS?](#-why-agent-os) • [Demos](#-live-demos) • [Integrations](#-integrations) • [Contributing](#-contributing)

---

## 🎯 What is Agent OS?

**Agent OS treats LLMs like raw compute and provides OS-level governance.** 

Current AI agent frameworks let the LLM "decide" everything - including whether to follow safety rules. Agent OS inverts this: the **kernel decides**, the LLM just computes.

```
┌─────────────────────────────────────────────────────────┐
│              USER SPACE (Untrusted LLM)                 │
│   Your agent code runs here. It can crash, hallucinate, │
│   or misbehave - the kernel survives.                   │
├─────────────────────────────────────────────────────────┤
│              KERNEL SPACE (Trusted)                     │
│   Policy Engine │ Flight Recorder │ Signal Dispatch     │
│   If agent violates policy → SIGKILL (non-catchable)   │
└─────────────────────────────────────────────────────────┘
```

## ❓ Why Agent OS?

### The Problem with Current Approaches

| Approach | How it works | Why it fails |
|----------|--------------|--------------|
| **Prompt-based safety** | "Please don't do bad things" | LLM can ignore prompts |
| **Constitutional AI** | Train model to be safe | Training doesn't guarantee |
| **Guardrails** | Check output after generation | Too late - damage done |
| **Agent OS** | **Kernel-level enforcement** | **Can't bypass the kernel** |

### Real Benchmark Results

| Metric | Prompt-based | Agent OS |
|--------|-------------|----------|
| Safety Violations | 26.67% | **0.00%** |
| Response Tokens | 26.1 avg | **0.5 avg** |
| Deterministic | No | **Yes** |

## 🚀 Quick Start

### Option 1: pip install (30 seconds)

```bash
pip install agent-os

# Verify installation
python -c "from agent_os import KernelSpace; print('Agent OS ready!')"
```

### Option 2: GitHub CLI Extension (Recommended for daily use)

```bash
# Install the gh extension
gh extension install imran-siddique/gh-agent-os

# Now use Agent OS directly from your terminal
gh agent-os run "analyze this codebase for security issues"
gh agent-os audit --policy pci-dss
gh agent-os status
```

### Option 3: Docker (Production)

```bash
docker pull ghcr.io/imran-siddique/agent-os:latest
docker run -it agent-os agentctl --help
```

## 💡 Core Concepts (5 minutes)

### 1. Signals - Control Your Agents Like Processes

```python
from agent_os import AgentSignal, SignalDispatcher

# Pause agent to inspect state (like Ctrl+Z)
dispatcher.signal(agent_id, AgentSignal.SIGSTOP)

# Resume execution
dispatcher.signal(agent_id, AgentSignal.SIGCONT)

# Policy violation? Kernel kills it (non-catchable)
dispatcher.signal(agent_id, AgentSignal.SIGKILL)
```

### 2. Virtual File System - Memory That Makes Sense

```python
from agent_os import AgentVFS

vfs = AgentVFS(agent_id="agent-001")

# Standard mount points (like /home, /tmp, /etc)
vfs.write("/mem/working/task.txt", "Current task...")  # Ephemeral
vfs.write("/mem/episodic/session.log", "What happened")  # Experience
vfs.read("/policy/allowed_actions.yaml")  # Read-only rules
```

### 3. IPC Pipes - Agents Talk Through Policies

```python
from agent_os.iatp import Pipeline, PolicyCheckPipe

# Unix-style piping: agent1 | policy | agent2
pipeline = Pipeline([
    research_agent,
    PolicyCheckPipe(allowed=["ResearchResult"]),  # Type check!
    summary_agent
])

# If research_agent outputs wrong type → pipeline fails safely
result = await pipeline.execute("Find recent AI papers")
```

## 🎬 Live Demos

Four production-ready demos showing Agent OS in action:

| Demo | Industry | What it shows | Run it |
|------|----------|---------------|--------|
| **[Carbon Auditor](examples/carbon-auditor/)** | Climate | CMVK drift detection catches $5M fraud | `python examples/carbon-auditor/demo.py` |
| **[Grid Balancing](examples/grid-balancing/)** | Energy | 100 agents negotiate in 100ms | `python examples/grid-balancing/demo.py` |
| **[DeFi Sentinel](examples/defi-sentinel/)** | Crypto | Stop hacks in 142ms | `python examples/defi-sentinel/demo.py` |
| **[Pharma Compliance](examples/pharma-compliance/)** | Healthcare | Find contradictions in 100K pages | `python examples/pharma-compliance/demo.py` |

```bash
# Run all demos
cd examples && docker-compose up
```

## 🔌 Integrations

### Works With Your Existing Stack

Agent OS doesn't replace your tools - it governs them:

```python
# With LangChain
from agent_os.integrations import langchain_kernel
chain = langchain_kernel.wrap(your_langchain_agent)

# With CrewAI
from agent_os.integrations import crewai_kernel
crew = crewai_kernel.wrap(your_crew)

# With AutoGen
from agent_os.integrations import autogen_kernel
autogen_kernel.govern(your_autogen_agents)
```

### GitHub Integration

```yaml
# .github/workflows/agent-os.yml
name: Agent OS Safety Check
on: [push, pull_request]

jobs:
  safety-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: imran-siddique/agent-os-action@v1
        with:
          policy: .agent-os/policy.yaml
          fail-on-violation: true
```

### VS Code Extension

```bash
# Install from marketplace
code --install-extension imran-siddique.agent-os

# Or use Command Palette: "Agent OS: Audit Current File"
```

### CLI for Daily Workflows

```bash
# Audit any agent codebase
agentctl audit ./my-agent-project

# Run with safety constraints
agentctl run --policy strict "agent.py"

# Monitor running agents
agentctl status --watch

# Replay agent execution from flight recorder
agentctl replay --from checkpoint-001
```

## 📦 Package Architecture

```
agent-os/
├── L1: Primitives (Foundation)
│   ├── primitives     # Failure types, base models
│   ├── cmvk           # Cross-model verification
│   ├── caas           # Context-as-a-Service
│   └── emk            # Episodic Memory Kernel
│
├── L2: Infrastructure (Communication)
│   ├── iatp           # Inter-Agent Trust Protocol
│   ├── amb            # Agent Message Bus
│   └── atr            # Agent Tool Registry
│
├── L3: Framework (Governance)
│   └── control-plane  # Kernel, signals, VFS
│
└── L4: Intelligence (Self-Correction)
    ├── scak           # Self-Correcting Agent Kernel
    └── mute-agent     # Reasoning/Execution split
```

Install what you need:

```bash
pip install agent-os              # Core only
pip install agent-os[control-plane]  # + Governance
pip install agent-os[full]        # Everything
```

## 🆚 How We Compare

| Feature | LangChain | AutoGen | CrewAI | AIOS | **Agent OS** |
|---------|-----------|---------|--------|------|--------------|
| Multi-agent | ✅ | ✅ | ✅ | ✅ | ✅ |
| Safety guarantees | ❌ | ❌ | ❌ | ❌ | **✅ Kernel-level** |
| Deterministic | ❌ | ❌ | ❌ | ❌ | **✅** |
| Process isolation | ❌ | ❌ | ❌ | ❌ | **✅ Kernel/User** |
| Policy enforcement | ❌ | ❌ | ❌ | ❌ | **✅ SIGKILL** |
| Audit trail | Partial | Partial | Partial | ❌ | **✅ Flight Recorder** |
| Memory model | Ad-hoc | Ad-hoc | Ad-hoc | Short/Long | **✅ VFS** |

**TL;DR**: Other frameworks help you *build* agents. Agent OS helps you *trust* them.

## 🤝 Contributing

We welcome contributions! Agent OS is designed to be extended.

### Good First Issues

- 🏷️ [`good-first-issue`](https://github.com/imran-siddique/agent-os/labels/good-first-issue) - Perfect for newcomers
- 📚 [`documentation`](https://github.com/imran-siddique/agent-os/labels/documentation) - Help improve docs
- 🧪 [`needs-tests`](https://github.com/imran-siddique/agent-os/labels/needs-tests) - Add test coverage

### Development Setup

```bash
# Clone and setup
git clone https://github.com/imran-siddique/agent-os.git
cd agent-os
pip install -e ".[dev]"

# Run tests
pytest

# Run a specific demo
python examples/carbon-auditor/demo.py
```

### Integration Bounties

Want to add an integration? We're looking for:

| Integration | Bounty | Status |
|-------------|--------|--------|
| LangChain adapter | 🎁 | Open |
| CrewAI adapter | 🎁 | Open |
| AutoGen adapter | 🎁 | Open |
| OpenAI Swarm adapter | 🎁 | Open |
| Anthropic Claude adapter | 🎁 | Open |

See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

## 📖 Documentation

- **[Architecture Guide](docs/architecture.md)** - Deep dive into kernel design
- **[API Reference](docs/api/)** - Full API documentation
- **[Examples](examples/)** - Working demos
- **[AIOS Comparison](docs/AIOS_COMPARISON.md)** - Detailed competitor analysis

## 🔬 Research

Agent OS is designed for both production and academic use:

- **Target**: ASPLOS 2026 Workshop on Agentic Systems
- **Paper**: "Agent OS: A Safety-First Kernel for Autonomous AI Agents"
- **Novel Contribution**: First OS-level governance for LLM agents

## 📜 License

MIT License - Use it, modify it, ship it. See [LICENSE](LICENSE).

---

**Built for engineers who don't trust their agents (yet).**

[⭐ Star us on GitHub](https://github.com/imran-siddique/agent-os) • [📦 PyPI](https://pypi.org/project/agent-os/) • [💬 Discussions](https://github.com/imran-siddique/agent-os/discussions)

