argon-architecture-scanner 0.9.2

Pre-1.0 token-budgeted architecture context engine for AI coding assistants.

ARGON — Token-Budgeted Architecture Context

ARGON is a pre-1.0 static context engine for AI coding assistants. It scans repositories, ranks symbols, follows imports/calls, and emits task-focused context that fits a strict token budget.

ARGON's goal is narrow by design: help an AI assistant see the smallest useful slice of a codebase for a specific task. It is not an editor, agent, formatter, or code modifier.

ARGON escanea proyectos de software y genera un grafo de arquitectura con:

• Símbolos (clases, funciones, interfaces) vía Tree-sitter o regex
• Conexiones entre archivos (imports/dependencias)
• Call graph intra-archivo (función A llama a función B en el mismo archivo)
• Búsqueda semántica opcional/experimental con TF-IDF, sentence-transformers u Ollama
• Visualización interactiva con D3.js (SVG voxels) o PixiJS/WebGL (GPU)
• MCP Server para integración con asistentes IA
• Watch mode para actualización automática en cambios
• Modo Precision: selección de contexto por tarea con presupuesto real de tokens.

Estado

ARGON está en fase pre-1.0. El scanner, el modo Precision, el MCP server y la vista HTML son usables, pero el ranking y los formatos pueden cambiar mientras maduran los benchmarks.

Claims medibles que ARGON busca optimizar:

• recall@budget: símbolos críticos incluidos dentro del presupuesto.
• precision@top: cuánta señal hay en los primeros símbolos elegidos.
• precision@critical: cuánta señal hay en la capa crítica antes de leer soporte.
• budget_ok: el contexto final no excede el límite de tokens.
• context_audit: recall real dentro del paquete emitido, recall alcanzable vía expansion_plan, utilización de presupuesto, símbolos con código completo y guardrails de empaquetado.
• tokens wasted: ruido incluido por encima del contexto necesario.

Uso (Plug & Play)

# Escaneo de precisión
python argon.py . --precision

# Modo centinela (Watch)
python argon_watch.py .

Benchmark De Calidad

ARGON incluye benchmarks enfocados en la métrica central del producto: recuperar el contexto correcto con pocos tokens.

python argon_quality_bench.py --output-dir C:\tmp\argon-bench --min-score 0.7

También puedes evaluar un proyecto con un spec propio:

{
  "cases": [
    {
      "task": "fix checkout total bug in tests",
      "budget": 4000,
      "top_n": 10,
      "must_include": ["checkoutTotal", "sumPrice", "testCheckoutTotal"],
      "must_not_include": ["GeneratedTypes", "Theme"]
    }
  ]
}

python argon_bench.py /ruta/proyecto benchmark.json --min-score 0.8

Uso rápido

# Escanear proyecto
python argon.py /ruta/proyecto --context

# Generar visualización interactiva
python argon_view.py --json argon_graph.json

# Servidor MCP (para Claude, Cursor, etc.)
python argon_mcp.py

# Watch mode (actualización automática)
python argon_watch.py /ruta/proyecto

Herramientas

Comando	Descripción
argon.py	Escáner universal con parser dual (Tree-sitter + regex)
argon_view.py	Genera visualización HTML interactiva
argon_mcp.py	Servidor MCP con herramientas para IA
argon_watch.py	Sentinel que actualiza el grafo en cambios
argon_semantic.py	Motor de búsqueda semántica por embeddings
argon_quality_bench.py	Benchmarks formales recall@budget y precision@top multi-lenguaje
argon_template.html	Template del visualizador D3.js/PixiJS

Visualización

• < 500 nodos: SVG voxels (cubos 3D isométricos)
• ≥ 500 nodos: PixiJS/WebGL (renderizado GPU, 10K+ nodos suaves)
• 6 temas visuales: Architect, Cyber, Fallout, Vaporwave, Matrix, Industrial
• Búsqueda por nombre de archivo, símbolo o concepto

MCP Tools

Tool	Descripción
argon_overview	Resumen del proyecto estadísticas y hubs
argon_query	Buscar símbolos específicos
argon_deps	Dependencias de un archivo
argon_search	Búsqueda por concepto/funcionalidad
argon_focused_context	Contexto optimizado para tareas específicas
argon_context_layer	Devuelve solo una capa: critical, workflow, support o all
argon_expand_symbol	Expande un símbolo concreto con código y relaciones directas
argon_semantic_search	Búsqueda semántica por intención (embeddings)
argon_ast_query	Buscar por patrón en firmas/nombres (regex)
argon_rescan	Regenerar grafo tras cambios

Capas De Contexto

El modo Precision ordena símbolos por capas para que una IA lea lo importante primero:

• critical: símbolos directamente necesarios para la tarea.
• workflow: callers/callees y flujo cercano.
• support: modelos, tipos, tests no pedidos y soporte de menor prioridad.

El empaquetador usa código completo para critical/workflow cuando cabe en el presupuesto y deja support compacto por defecto. Así conserva rutas, firmas, razones y relaciones sin gastar tokens en cuerpos de soporte que la IA puede pedir después.

Cada contexto Precision incluye un expansion_plan: una cola pequeña de símbolos compactos u omitidos que conviene pedir después con argon_expand_symbol. Esto permite empezar con el paquete crítico y expandir solo lo que falta, en lugar de pagar tokens por todo el soporte desde el primer mensaje.

También puedes usar perfiles de presupuesto:

• micro: 1500 tokens, contexto inicial mínimo y hasta 3 expansiones sugeridas.
• standard: 4096 tokens, equilibrio por defecto para tareas normales.
• deep: 8192 tokens, más código completo y hasta 12 expansiones.
• custom: usa el valor de --budget.

python argon.py . --precision --task "fix login bug" --budget-profile micro --format json

En MCP puedes pedir solo la capa crítica y expandir después:

argon_context_layer("fix checkout total bug", tier="critical", max_tokens=1500)
argon_expand_symbol("checkoutTotal", max_tokens=1200)

Licencia

MIT