🌌 OntoAgent

The All-Knowing Code Brain & Architecture Contract Guard for AI Coding Agents

Motor de gobernanza de arquitectura y grafo de conocimiento de todo el repositorio para agentes de codificación de IA.

📖 Why OntoAgent?

Los agentes de codificación modernos suelen enfrentarse a tres problemas estructurales al trabajar con grandes bases de código:

1. El elefante y los ciegos: solo ven el archivo actual, no ven los llamadores entre módulos, los contratos de API ni las dependencias de prueba.

2. Alucinación de contexto largo: «meter todo el repositorio a la fuerza en el Prompt», con alto coste de tokens, baja relación señal-ruido, y el modelo tiende a ignorar restricciones clave.

3. Los cambios destructivos son difíciles de rastrear: al modificar una clase central, no se puede saber rápidamente qué módulos ascendentes, pruebas e interfaces explotarán a la vez.

Enfoques tradicionales:

• Naive Raw Text: se introduce todo en el contexto, con tokens enormes y sin localización estructurada.

• Vector-Chunk RAG: divide en fragmentos por similitud de texto, comprime tokens, pero pierde dependencias a nivel de AST, relaciones de herencia y semántica de contratos.

La elección de OntoAgent:

Construir un grafo de conocimiento de todo el repositorio con análisis estático de AST + base de datos de grafos embebida, para que el agente de IA vea primero la red de llamadas, contratos, pruebas y radio de explosión antes de modificar código.

Related MCP server: code-intel

🏛️ Architecture Flow

graph TD
    subgraph Base["底座层"]
        Kuzu["Kùzu Embedded Graph DB"]
        AST["AST Parsers: Python / TypeScript / Markdown / JSON"]
    end

    subgraph Core["核心引擎"]
        Blast["Blast Radius Analyzer"]
        Context["Smart Context Extractor"]
        Compliance["Architecture Compliance Guard"]
        Scanner["Codebase Scanner & Entity Ingestion"]
    end

    subgraph Ecosystem["交互生态"]
        MCP["MCP Server"]
        DSH["DSH / Cordis Plugin"]
        CLI["onto-agent CLI"]
        Dashboard["React 2D Canvas + Dagre Dashboard"]
    end

    AST --> Scanner
    Scanner --> Kuzu
    Kuzu --> Blast
    Kuzu --> Context
    Kuzu --> Compliance
    Blast --> MCP
    Context --> DSH
    Compliance --> CLI
    Scanner --> Dashboard

📊 Benchmark

Reproducción con un clic:

python benchmark/run_benchmark.py

Basado en fixtures de código deterministas, compara tres estrategias de construcción de contexto:

Conclusión:

• OntoAgent reduce el consumo de tokens en aproximadamente 89.7% en comparación con Naive Raw Text.

• OntoAgent supera a Vector-Chunk RAG en recuperación de dependencias críticas, recuperación de pruebas/contratos y localización del radio de explosión.

• El informe completo está en benchmark/reports/benchmark_report.md.

🚀 Quickstart

1. Instalación

pip install -e .[test]

2. Escanear todo el repositorio

onto-agent scan --path .

3. Iniciar el panel de trabajo visual

python dashboard/api_server.py
# 打开 http://127.0.0.1:8000

4. Configurar MCP

Copia integrations/cursor_mcp.json como .cursor/mcp.json, o combínalo en Claude Desktop:

{
  "mcpServers": {
    "onto-agent": {
      "command": "python",
      "args": ["-m", "onto_agent.mcp"]
    }
  }
}

5. Instalar el plugin nativo de DSH

dsh plugin --profile web add ./integrations/dsh/onto-agent-plugin

🧠 Agent Abilities

get_blast_radius(file_path)

Antes de modificar cualquier archivo/símbolo, devuelve:

• Llamadores directos

• Módulos afectados indirectamente

• Dependencias descendentes

• Contratos de API asociados

• Pruebas que deben ejecutarse

check_architecture_compliance(strict=True)

Comprueba:

• Imports circulares

• Llamadas que violan la capa

• Clases centrales sin cobertura de pruebas

get_smart_context(query_or_symbol)

Genera contexto de alta relación señal-ruido antes de refactorizar/generar:

• Definición, número de líneas, Docstring

• Lista de clases/funciones

• imports / callers

• Contratos de API, pruebas relacionadas, documentación relacionada

🔌 Ecosystem

🗂️ Project Layout

src/onto_agent/
├── engine/          # Scanner, ArchitectureGuard, Context, Steering, Reflection
├── storage/         # Kùzu graph storage adapter
├── mcp/             # MCP Server
├── client/          # Python SDK
└── cli.py           # Unified CLI

dashboard/           # FastAPI + React workbench
benchmark/           # Reproducible Codex-for-Open benchmark
integrations/        # Cursor / Claude / Windsurf / DSH
docs/                # Design docs & tickets
tests/               # 48+ unit / integration tests

📚 Documentation

• MCP & SDK API

• System Architecture

• Ontology Schema

• Agent Behavior Protocol

• Dashboard Spec

• Contributing Guide

📄 License

Este proyecto es de código abierto bajo Apache-2.0.