Multi-Agent Research System 🚀

An enterprise-grade, secure, multi-agent intelligence research system built with CrewAI, FastAPI, and PostgreSQL. It features an autonomous multi-agent consensus loop, an OWASP Agentic Security Initiative (ASI) mapped Native Governance Engine with a Three-Layered Defense-in-Depth Pipeline, and an economic Cost Optimization Router (Middleware Suite).

🛡️ Governance & Security Architecture

The system features an active security middleware interceptor (governance_engine.py) enforcing OWASP Agentic Security Initiative (ASI) standards:

flowchart TD
    Payload[Incoming Prompt / Web Payload] --> Router{inspect_input Router}
    
    subgraph Defense_in_Depth ["Three-Layered Defense-in-Depth Pipeline (ASI-03)"]
        Router --> L1["Layer 1: Deterministic Regex Blocklist (< 5ms)"]
        L1 -- Violation --> Halt1[HALT Execution & Issue Receipt]
        L1 -- Safe --> L2["Layer 2: In-Memory Semantic Cosine Similarity"]
        L2 -- "Sim >= 0.85" --> Halt2[HALT Execution & Issue Receipt]
        L2 -- Safe / Fail-Open --> L3["Layer 3: Local LLM Judge (Gemma 2B via Ollama)"]
        L3 -- "MALICIOUS" --> Halt3[HALT Execution & Issue Receipt]
        L3 -- "SAFE / Circuit Breaker Fail-Open" --> Approved[Approved for Multi-Agent Loop]
    end

    subgraph Security_Guards ["OWASP ASI Security Guards"]
        Approved --> ASI01["ASI-01: Tool Allowlist Enforcement"]
        Approved --> ASI02["ASI-02: Shell & Command Injection Block"]
        Approved --> ASI04["ASI-04/05: PII & Secrets Redaction"]
        Approved --> ASI05_XML["ASI-05: <untrusted_context> XML Isolation"]
        Approved --> ASI07["ASI-07: Safe Non-Leaking Error Handlers"]
    end

Defense-in-Depth Layers (ASI-03 Prompt Injection Mitigation)

1. Layer 1: Deterministic Regex Blocklist ($< 5\text{ms}$ Execution)
   • Categorized pattern matching: Roleplay & Personas ("DAN", "Developer Mode", "Simulation"), Instruction Overrides & Token Smuggling (i g n o r e), Encoding Heuristics (Base64/Hex), and Context Hijacking (--- END SYSTEM INSTRUCTIONS ---, </system>).
2. Layer 2: In-Memory Semantic Cosine Similarity ($\approx 20\text{-}30\text{ms}$ Execution)
   • Utilizes sentence-transformers (all-MiniLM-L6-v2) and raw numpy dot products against pre-computed seed jailbreak vectors ($\ge 0.85$ threshold). Includes a fail-open circuit breaker if packages are missing.
3. Layer 3: Quantized Local LLM Judge
   • Routes obfuscated payloads to a local gemma2:2b model via Ollama REST API with temperature=0.0. Enforces a 2.0-second HTTP timeout circuit breaker that fails open if the local daemon is offline.

💰 Cost Optimization Router (Middleware Suite)

Decoupled from security, the system includes a CostOptimizationRouter (cost_router.py) that evaluates prompt payloads and task requirements to maximize economic efficiency:

• Token Estimator: Uses a fast heuristic ($\text{Words} \times 1.3$) for zero-latency token count estimation.
• Local Inference Tier (LOCAL_INFERENCE): Routes standard prompts $< 8,000$ tokens to local models (ollama/mistral) for 100% cost savings.
• Frontier API Tier (FRONTIER_API): Routes payloads $\ge 8,000$ tokens or high-reasoning consensus tasks (e.g. Fact-Checker) to frontier models (gpt-4o).
• Typed Decision Receipts: Emits RoutingDecisionReceipt objects logging target model, token estimate, rationale, and cost savings metrics.

🤖 Multi-Agent Consensus Loop

1. Researcher Agent (SearxNG Integration): Operates under strict query bounds and length constraints ($< 200$ chars) to retrieve raw factual research context.
2. Writer Agent (Air-Gapped): Operating with zero external tool permissions, synthesizes raw research context inside <untrusted_context> XML tags into structured intelligence reports.
3. Fact-Checker Agent (LLM-as-a-Judge): Evaluates draft reports line-by-line against raw context to issue deterministic verdicts (APPROVED or REJECTED with specific critiques). Rejections trigger controlled feedback loops up to MAX_LOOPS.

📁 Repository Structure

Multi-Agent Research System/
├── src/
│   ├── routing/
│   │   └── cost_router.py         # Decoupled Cost Optimization Router (Local vs Frontier)
│   ├── security/
│   │   ├── governance_engine.py   # Native OWASP ASI Governance Engine & 3-Layer Pipeline
│   │   └── sanitizer.py           # Text/HTML & PII scrubbing utilities
│   ├── agents/
│   │   └── research_agents.py     # CrewAI agent definitions (Researcher, Writer, Fact-Checker)
│   ├── tools/
│   │   └── searxng_tool.py        # Secure SearxNG search integration tool
│   ├── app.py                     # FastAPI web application & web UI dashboard
│   ├── orchestrator.py            # Research session orchestration & consensus loop
│   ├── database.py                # Async PostgreSQL ORM (with SQLite fallback)
│   ├── models.py                  # Pydantic data schemas & audit/routing decision receipts
│   └── templates/                 # Web UI HTML templates
├── tests/
│   ├── unit/                      # Governance engine, cost router & unit test suite
│   ├── integration/               # System integration tests
│   └── evals/                     # DeepEval LLM evaluation benchmarks
├── docker-compose.yml             # Docker services (PostgreSQL + SearxNG)
├── searxng_settings.yml           # SearxNG search engine configuration
├── init.sql                       # Database initialization schema
├── requirements.txt               # Python package dependencies
└── README.md                      # Documentation

⚙️ Getting Started

1. Prerequisites

• Python 3.11+
• Docker & Docker Compose
• Ollama (Optional, for Layer 3 LLM Judge with gemma2:2b and Local Inference with mistral)

2. Installation

Clone the repository and install dependencies:

git clone https://github.com/lawrenceemenike/Multi-Agent-Research-System.git
cd Multi-Agent-Research-System

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Environment Setup

Copy the .env.example file to .env:

cp .env.example .env

Configure your environment variables in .env:

DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/research_audit
SEARXNG_BASE_URL=http://localhost:8080/search
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL_NAME=gpt-4o
MAX_LOOPS=3

🐳 Running Services with Docker

Start PostgreSQL and SearxNG services:

docker-compose up -d

Check service status:

• PostgreSQL: localhost:5432 (Database: research_audit)
• SearxNG: http://localhost:8080

🚀 Running the Web Application

Start the FastAPI application:

python -m uvicorn src.app:app --reload --port 8000

Access the UI dashboard at http://localhost:8000.

🧪 Running Unit & Security Tests

Run the unit test suite (including governance engine sub-5ms performance tests, defense-in-depth pipeline checks, and cost optimization router tests):

py -m pytest tests/unit/test_cost_router.py tests/unit/test_governance_engine.py

📜 License

This project is licensed under the MIT License.