Metadata-Version: 2.4
Name: argon-architecture-scanner
Version: 0.9.2
Summary: Pre-1.0 token-budgeted architecture context engine for AI coding assistants.
Author: Dante7u7r
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: pathspec>=1.1.1
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-language-pack>=0.10.0
Requires-Dist: mcp>=1.27.1
Provides-Extra: dev
Requires-Dist: pytest>=9.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: playwright>=1.59.0; extra == "dev"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3.0.0; extra == "semantic"

# 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)

```bash
# 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.

```bash
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:

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

```bash
python argon_bench.py /ruta/proyecto benchmark.json --min-score 0.8
```
## Uso rápido

```bash
# 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`.

```bash
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:

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

## Licencia

MIT
