Metadata-Version: 2.4
Name: modus-ai
Version: 0.2.1
Summary: Modular AI agent framework
Author: Modus Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ModusAgent/modus
Project-URL: Repository, https://github.com/ModusAgent/modus
Project-URL: Documentation, https://github.com/ModusAgent/modus#readme
Keywords: ai,agents,llm,framework,memory,mcp,orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.120.2
Requires-Dist: openai>=2.50.0
Requires-Dist: lancedb>=0.12.0
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: mcp>=2.0.0
Requires-Dist: fastapi>=0.141.1
Requires-Dist: uvicorn>=0.52.0
Requires-Dist: apscheduler>=3.11.3
Requires-Dist: pillow>=12.3.0
Requires-Dist: google-genai>=2.16.0
Requires-Dist: pyyaml>=6.0.3
Dynamic: license-file

<p align="center">
  <img src="modus/assets/logo-dark-readme.png" alt="Modus" width="200">
  <br><br>
  <b>Modus — Modular AI agents. Composable by design.</b><br><br>
    <img src="https://img.shields.io/badge/status-alpha-8B5CF6?style=for-the-badge" alt="Status">
    <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
    <img src="https://img.shields.io/badge/tests-543%20passing-22C55E?style=for-the-badge" alt="Tests">
    <img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="MIT">
  <br><br>
  <b>Modus</b> is an open-source modular AI agent framework that provides reusable components<br>
  for building, orchestrating, and deploying autonomous AI systems.<br><br>
  Memory systems. Planning loops. Safety guards. Tool execution. MCP integration.<br>
  All packaged as swappable modules with clear protocol boundaries.<br><br>
  <a href="docs/index.md"><img src="https://img.shields.io/badge/Docs-8B5CF6?style=for-the-badge" alt="Docs"></a>
  <a href="docs/modules/memory.md"><img src="https://img.shields.io/badge/Memory-22C55E?style=for-the-badge" alt="Memory"></a>
  <a href="docs/guide/actions.md"><img src="https://img.shields.io/badge/Actions-3B82F6?style=for-the-badge" alt="Actions"></a>
  <a href="docs/roadmap.md"><img src="https://img.shields.io/badge/Roadmap-F59E0B?style=for-the-badge" alt="Roadmap"></a>
</p>

## Why Modus?

Building AI agents today means reinventing the same infrastructure every time: memory systems, planning loops, safety guards, tool execution, perception pipelines. Every framework forces you into a monolithic agent runtime where swapping one piece means rewriting half the system.

Modus takes the opposite approach.

Each capability is a self-contained module with a well-defined protocol interface. Swap memory backends without touching the planner. Change planning strategies without rewriting the action layer. Add safety policies without forking the codebase.

No vendor lock-in. No monolithic runtimes. Just composable building blocks.

## Quick start

```bash
pip install modus-ai
```

```python
from modus import Agent
from modus.memory import Memory
from modus.memory.embeddings import GeminiEmbedding, OpenAIEmbedding

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    provider="openai",
    memory=Memory("./data", embedding=OpenAIEmbedding()),
)

# Memory context auto-injected, Chat auto-managed
response = agent.run("What do I know about Project Phoenix?")

# Gemini embeddings (uses the GEMINI_API_KEY env var)
gemini_memory = Memory("./data", embedding=GeminiEmbedding(model="gemini-embedding-001"))
```

## What's built

| Module | Features | Status |
|---|---|---|
| **Agent** | ReAct loop, Chat history, Memory injection, Tool calling, Event hooks, session persistence, trace IDs, dry-run | ✅ |
| **Memory** | OKF `.md` files, PyYAML frontmatter, FTS5 keyword search, LanceDB vector search, Hybrid scoring, LLM analysis, entity extraction, TTL + importance eviction, dedup gate, Dreaming, consolidation, tenant isolation, concurrent + cross-process safe writes | ✅ |
| **Actions** | Local tool registry, `@tool` decorator, MCP stdio/HTTP transport with handshake + auth headers, argument validation, result compaction, caching, transient-only retry, timeout, parallel execution, middleware, authorization | ✅ |
| **Safety** | 3-tier interceptor (deterministic rules, HITL, LLM review), per-iteration and global call limits | ✅ |
| **Planner** | SHORT_CIRCUIT, REACT, TREE_OF_THOUGHT with parallel branch execution | ✅ |
| **Vision** | OpenAI, Anthropic, Gemini, Ollama, Tesseract providers; SSRF guard, thumbnailing, caching, multi-modal memory | ✅ |
| **Skills** | Package registry (tools + prompts + concepts), path-traversal protection | ✅ |
| **Providers** | OpenAI (incl. Groq/OpenRouter/Together/Ollama), Anthropic, Gemini with tool calling; retry/backoff with jitter + Retry-After | ✅ |
| **Orchestration** | Workflow graph engine, dependency resolution, conditional routing, loops, HITL, state persistence, validation, hooks, async, sub-workflows, Mermaid export, context isolation, Team | ✅ |
| **Deploy** | FastAPI webhook server (Bearer auth, CORS, rate limit, body caps), APScheduler (cron + interval) | ✅ |
| **Observability** | Trace IDs, JSON structured logs, optional OpenTelemetry spans | ✅ |

## Key architecture

- **Monorepo, single package:** `pip install modus-ai`
- **Memory:** OKF `.md` files + YAML frontmatter → FTS5 + LanceDB hybrid search
- **Actions:** Plugin local tools or connect MCP servers (`stdio` or `HTTP`)
- **ReAct loop:** Agent detects LLM tool calls, executes in parallel, feeds results back
- **Chat:** Token-budget conversation history, auto-summarized overflow
- **All modules are standalone:** `from modus.memory import Memory` — works without Agent

## Example: Tools

```python
from modus import Agent
from modus.actions import tool

@tool(name="get_weather", description="Get weather for a city", parameters={
    "type": "object",
    "properties": {"city": {"type": "string"}},
    "required": ["city"],
})
def get_weather(city: str) -> str:
    return f"Sunny, 25°C in {city}"

agent = Agent(name="WeatherBot", instructions="Use tools to answer questions.")
agent.actions.register(get_weather)

response = agent.run("What is the weather in Tokyo?")
```

## Example: MCP server

```python
agent.actions.connect(
    "filesystem",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "."],
)
# Tools auto-discovered and available in the ReAct loop
```

## Example: Workflow with multiple agents

```python
from modus.orchestration import Workflow, Step

workflow = Workflow(steps={
    "classify": Step(agent=classifier, next={"billing": "resolve", "tech": "escalate"}),
    "resolve": Step(agent=resolver, retry=2, timeout=30),
    "respond": Step(agent=responder, depends_on=["resolve", "escalate"]),
})

result = workflow.run("I was charged twice")
```

## Documentation

| Section | Description |
|---|---|
| [Architecture](docs/architecture.md) | Block architecture and lifecycle |
| [Memory Guide](docs/modules/memory.md) | OKF concepts, storage, retrieval, API reference |
| [Actions Guide](docs/guide/actions.md) | MCP servers, tool execution, ReAct loop |
| [Logging & Observability](docs/guide/logging.md) | Trace IDs, structured logs, per-module tuning |
| [Security Model](docs/guide/security.md) | Trust boundaries, subprocess isolation |
| [Protocol Reference](docs/reference/protocols.md) | Module interface contracts |
| [Contributing](docs/contributing.md) | Development guide and RFC process |
| [Roadmap](docs/roadmap.md) | Upcoming milestones |

## Current status

**Alpha.** Agent, memory, actions, safety, planner, vision, skills, providers,
orchestration, deploy, and observability are implemented and tested
(543 tests, ~82% coverage, mypy-clean, ruff-clean).

## License

MIT
