Metadata-Version: 2.4
Name: sp-llmgraph
Version: 0.4.0
Summary: Gestor de contexto para agentes IA basado en grafos comprimidos generados desde Markdown
Project-URL: Repository, https://github.com/PRojas01/SP-LLMGraph
Project-URL: Issues, https://github.com/PRojas01/SP-LLMGraph/issues
Project-URL: Changelog, https://github.com/PRojas01/SP-LLMGraph/blob/main/CHANGELOG.md
Author-email: Pedro Rojas <pedro@solucionespro.com>
License-Expression: MIT
License-File: LICENSE
Keywords: binary,context,graph,knowledge,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: mcp>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# LLMGraph

Gestor de contexto para modelos y agentes IA basado en grafos comprimidos.

Principio del sistema:

```text
Markdown humano editable -> grafo comprimido -> Context Pack minimo, vigente y trazable
```

LLMGraph no reemplaza la documentacion humana. Compila `.md` a un indice
`.llgr.zlib` para que los agentes consulten solo el contexto relevante de una
tarea, con fuentes y metricas.

## Instalación

```bash
pip install -e ".[mcp]"
```

## Instalación por editor

### VS Code / Cursor / Windsurf

LLMGraph incluye una extension VSIX en `extension/` que agrega una pestaña en
la Activity Bar del editor. El panel invoca el CLI local y puede asegurar la
configuracion MCP del workspace.

```bash
cd extension
npm install
npm run validate
npm run package
code --install-extension llmgraph-editor-0.4.0.vsix
```

Cursor y Windsurf pueden instalar el mismo `.vsix` desde su interfaz de
extensiones o desde un CLI compatible.

### Claude Code

El plugin vive en `.claude-plugin/plugin.json` y registra el MCP `llmgraph`.
Tambien se incluye el skill `.claude/skills/llmgraph-context/SKILL.md`.

### Codex

```bash
codex mcp add llmgraph -- llmgraph-mcp
```

La configuracion equivalente esta en `.codex/config.toml`.

### opencode

Copiar `opencode.json` al workspace o usarlo desde esta raiz. Declara el MCP
local `llmgraph`.

### ChatGPT Desktop

Usar el connector MCP local con comando `llmgraph-mcp` y working directory del
proyecto. ChatGPT web no aplica porque LLMGraph no expone una API HTTP.

## Uso rápido

### Python
```python
from llmgraph import Graph, encode, decode
from llmgraph.md_parser import parse_file

# Crear grafo
g = Graph()
g.metadata["project"] = "mi-proyecto"
g.add_node("file", name="auth.py", lang="python")
g.add_node("file", name="db.py", lang="python")
g.add_edge(0, 1, "imports")

# Codificar a binario
raw = encode(g)  # → bytes, ~10x más pequeño que .md equivalente

# Decodificar
g2 = decode(raw)
```

### CLI
```bash
# Convertir .md a .llgr
llmgraph convert README.md -o project.llgr

# Consultar
llmgraph query project.llgr -t section

# Comparar
llmgraph diff graph1.llgr graph2.llgr
```

### Context Manager

```bash
# Crear context/context-policy.toml
llmgraph context init .

# Compilar README.md/docs/operations a context/project.llgr.zlib
llmgraph context build .

# Preparar contexto optimizado para una tarea
llmgraph context prepare . "refactorizar autenticacion" --profile coding --max-tokens 3000

# Buscar dentro del grafo de contexto
llmgraph context search . "middleware de autenticacion"

# Auditar fuentes, nodos grandes y referencias rotas
llmgraph context health .
```

El `Context Pack` reporta:

- tokens fuente vs tokens usados;
- porcentaje de tokens ahorrados;
- nodos incluidos;
- fuentes usadas;
- porcentaje de trazabilidad;
- nodos obsoletos excluidos.

Plan de continuación:

- [docs/plan-contexto.md](docs/plan-contexto.md)

### MCP Server (para editores agenticos)
```bash
# Agregar a opencode.json:
{
  "mcp": {
    "llmgraph": {
      "type": "local",
      "command": ["python", "-m", "llmgraph.mcp_server"],
      "enabled": true
    }
  }
}
```

## Formato binario

Un archivo `.llgr` contiene:
- **Header** (16 bytes): magic "LLGR" + versión + conteos
- **String dictionary**: strings deduplicadas (como side channel en MP3)
- **Nodes**: tipo + propiedades por nodo
- **Edges**: src + tgt + tipo + propiedades por edge
- **Metadata**: key-value pairs a nivel de grafo

## Compresión vs .md

| Formato | Tamaño (50 nodos) | Ratio |
|---------|-------------------|-------|
| .md     | 1x (baseline)     | 1.0x  |
| .llgr   | ~0.3-0.5x         | 2-3x  |
| JSON    | ~2x               | 0.5x  |

La compresión mejora con grafos más grandes gracias a la deduplicación de strings.

## Licencia

MIT
