omnigent

<div align="center">

# Omnigent

**The universal scaffold for building autonomous AI agents.**

Build any AI agent — security, code analysis, DevOps, compliance, research — on a production-proven foundation. Extracted from a real-world agent with 17k+ LOC and 320 tests.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-325%20passing-brightgreen.svg)](#testing)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

[Architecture](ARCHITECTURE.md) · [Examples](examples/) · [Contributing](CONTRIBUTING.md)

</div>

---

## What is Omnigent?

Most AI agent frameworks give you wrappers around LLM APIs. Omnigent gives you **the entire brain**.

It's the domain-agnostic architecture of a production autonomous agent — the ReAct loop, multi-provider LLM routing, structured memory, hierarchical planning, reasoning graphs, error recovery, reflection, and plugin system. Everything you need to build a **real** agent, not a chatbot with tools.

**You bring the domain. Omnigent brings the intelligence.**

```
┌──────────────────────────────────────────────────────┐
│                   Agent Loop (ReAct)                 │
│         Reason → Act → Observe → Reflect             │
├──────────────┬────────────┬────────────┬─────────────┤
│   Router     │  Planner   │  Context   │   Graph     │
│  4 Providers │  Phases    │  Smart Trim│  Reasoning  │
├──────────────┴────────────┴────────────┴─────────────┤
│            Post-Processing Pipeline                  │
│    Extractors → Reflection → Error Recovery          │
├──────────────────────────────────────────────────────┤
│            Tool Registry + Plugin System             │
├──────────────────────────────────────────────────────┤
│  State │ DomainProfile │ Session │ Cost │ Knowledge  │
├──────────────────────────────────────────────────────┤
│          Config │ Logging │ MCP Integration          │
└──────────────────────────────────────────────────────┘
```

## Why Omnigent?

| Problem | Omnigent Solution |
|---------|-------------------|
| Agents that loop forever | **Circuit breaker** + **loop detection** (hash-based, blocks on first repeat) + **rate limiting** (per-iteration and total caps) |
| Context window overflow | **3-level smart trimming** preserving atomic message groups + **semantic compression** via LLM |
| "Just a tool caller" | **Reasoning Graph** chains findings into multi-step escalation paths |
| No methodology | **Hierarchical Planner** with phase-based execution, LLM refinement, skip conditions, and **macro-reflection** at phase end |
| Blind tool execution | **Extractors** auto-parse results → **structured memory** → **async reflection** |
| Failures crash the agent | **Error recovery patterns** with retry strategies and graceful degradation |
| Vendor lock-in | **4 LLM providers** with task-based routing and automatic fallback + **extensible provider ABC** |
| No human oversight | **Human-in-the-loop** approval steps for sensitive tool calls |
| Lost progress on crash | **Checkpoint/replay** mid-execution with session resume |
| Untrusted plugins | **Plugin strict checksum** mode with SHA-256 verification |
| Starting from zero | **Production-proven** — extracted from a real agent, not built in a weekend |

## Quick Start

### Install

```bash
pip install -e .
```

### Set up an API key

```bash
export DEEPSEEK_API_KEY="sk-..."  # Cheapest option (~$0.001 per analysis)
# or
export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
```

### Run the example agent

```bash
# CodeLens — code quality analyzer (included example)
python -m examples.codelens.main /path/to/any/project
```

### Build your own agent in 4 steps

**Step 1: Define your domain memory**

```python
from dataclasses import dataclass, field
from omnigent.domain_profile import DomainProfile

@dataclass
class MyProfile(DomainProfile):
    items_analyzed: list[str] = field(default_factory=list)
    risk_score: float = 0.0
```

**Step 2: Register your tools**

```python
from omnigent.tools import ToolRegistry

registry = ToolRegistry()
registry.register(
    name="my_scanner",
    schema={"description": "Scan a target", "parameters": {
        "type": "object",
        "properties": {"target": {"type": "string"}},
        "required": ["target"],
    }},
    handler=my_scanner_function,
)
```

**Step 3: Populate registries** (plan templates, chains, extractors, reflectors, error patterns)

```python
from omnigent.registry import DomainRegistry
from omnigent.chains import ChainStep

registry = DomainRegistry(
    plan_templates={
        "my_domain": [
            {"name": "Discovery", "objective": "Map the target", "steps": [
                ("Initial scan", "my_scanner"),
            ]},
        ],
    },
    chains={
        "high_risk": [
            ChainStep("Deep dive on flagged items", "deep_scanner"),
            ChainStep("Generate remediation plan", ""),
        ],
    },
    extractors={
        "my_scanner": lambda profile, result, args: setattr(
            profile, 'risk_score', 0.8
        ),
    },
)
```

**Step 4: Wire it up and run**

```python
import asyncio
from omnigent.agent import Agent
from omnigent.router import LLMRouter, Provider

async def main():
    agent = Agent(
        router=LLMRouter(primary=Provider.DEEPSEEK),
        tools=tool_registry,
        registry=registry,  # DomainRegistry with all domain-specific behavior
    )
    async for event in agent.run("Analyze this target"):
        if event.type == "text":
            print(event.content, end="")
        elif event.type == "finding":
            print(f"\n[{event.finding.severity}] {event.finding.title}")

asyncio.run(main())
```

## What Can You Build?

Omnigent is **domain-agnostic** — it provides the intelligence architecture, you provide the domain knowledge:

| Domain | What You Add | What Omnigent Provides |
|--------|-------------|------------------------|
| **Security** | Nmap, SQLMap, Burp tools + vuln knowledge | ReAct loop, attack chain reasoning, session persistence |
| **Code Quality** | AST parsers, complexity tools + refactoring patterns | Planning, structured findings, escalation chains |
| **DevOps** | K8s, Terraform, monitoring tools + runbooks | Error recovery, multi-step incident chains, cost tracking |
| **Compliance** | Document scanners, policy tools + regulation KB | Hypothesis tracking, evidence collection, reporting |
| **Research** | Search, scraping, DB tools + domain ontology | Context management, iterative refinement, reflection |

See [examples/codelens/](examples/codelens/) for a complete working implementation.

## Components

| Module | Purpose | How to Customize |
|--------|---------|-----------------|
| [agent.py](src/omnigent/agent.py) | ReAct loop, circuit breaker, loop detection, rate limiting, approval | Subclass `Agent`, override step methods and hooks |
| [registry.py](src/omnigent/registry.py) | Centralised `DomainRegistry` dataclass for all domain-specific registries | Pass `DomainRegistry(...)` to `Agent` |
| [router.py](src/omnigent/router.py) | Multi-provider LLM routing with `LLMProvider` ABC and extended thinking | Subclass `LLMProvider` for new providers |
| [reasoning_graph.py](src/omnigent/reasoning_graph.py) | Directed graph for multi-step reasoning chains | Subclass `ReasoningGraph` |
| [planner.py](src/omnigent/planner.py) | Hierarchical task planning with skip conditions and macro-reflection | Populate `plan_templates` in `DomainRegistry` |
| [context.py](src/omnigent/context.py) | Smart context trimming + LLM-based semantic compression | Works as-is |
| [domain_profile.py](src/omnigent/domain_profile.py) | Structured memory with bounded hypothesis tracking | Subclass `DomainProfile` |
| [state.py](src/omnigent/state.py) | Agent stat

[truncated…]