sp-llmgraph 0.4.0__py3-none-any.whl

llmgraph/__init__.py

@@ -0,0 +1,26 @@
+"""
+LLMGraph — Formato binario de grafos para conocimiento de LLMs
+"""
+from .schema import Graph, Node, Edge, UndirectedEdge, Property, VT
+from .encoder import encode, decode_varint, encode_varint
+from .decoder import decode
+from .compressor import compress, decompress, is_compressed
+from .retrieval import RetrievalEngine
+from .context import (
+    context_build,
+    context_health,
+    context_init,
+    context_prepare,
+    context_search,
+    context_update,
+)
+
+__version__ = "0.4.0"
+__all__ = ["Graph", "Node", "Edge", "UndirectedEdge", "Property", "VT",
+           "encode", "decode", "compress", "decompress", "is_compressed",
+           "RetrievalEngine",
+           "context_init", "context_build", "context_prepare",
+           "context_search", "context_health", "context_update",
+           "git_context", "get_git_context",
+           "registry", "register_project", "unregister_project",
+           "list_projects", "search_projects", "update_project"]

llmgraph/cli.py

@@ -0,0 +1,332 @@
+"""
+LLMGraph CLI — Herramienta de línea de comandos.
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+import os
+import time
+
+from .schema import Graph
+from .encoder import encode
+from .decoder import decode
+from .compressor import compress, decompress, is_compressed
+from .md_parser import parse_file, parse_directory
+from .context import (
+    context_build,
+    context_health,
+    context_init,
+    context_prepare,
+    context_search,
+    context_update,
+)
+
+
+def cmd_convert(args):
+    path = args.path
+    t0 = time.time()
+    if os.path.isdir(path):
+        g = parse_directory(path, recursive=not args.no_recursive)
+    else:
+        g = parse_file(path)
+
+    raw = encode(g)
+    raw_size = len(raw)
+
+    if args.compress:
+        raw = compress(raw, method=args.compress)
+        label = f" ({args.compress})"
+    else:
+        label = ""
+
+    output = args.output or (os.path.splitext(path)[0] + ".llgr")
+    with open(output, "wb") as f:
+        f.write(raw)
+
+    stats = g.stats()
+    elapsed = time.time() - t0
+    md_size = sum(os.path.getsize(os.path.join(dp, f))
+                  for dp, _, fn in os.walk(path) for f in fn
+                  if f.endswith(".md")) if os.path.isdir(path) else os.path.getsize(path)
+
+    print(f"Convertido: {path} → {output}{label}")
+    print(f"  Nodos: {stats['nodes']} ({', '.join(f'{k}:{v}' for k,v in stats['node_types'].items())})")
+    print(f"  Edges: {stats['edges']}")
+    print(f"  .md original: {md_size:,} bytes")
+    print(f"  .llgr binario: {raw_size:,} bytes")
+    if args.compress:
+        print(f"  .llgr comprimido: {len(raw):,} bytes")
+    print(f"  Compresión vs .md: {md_size/max(len(raw),1):.1f}x")
+    print(f"  Tiempo: {elapsed:.2f}s")
+
+
+def cmd_encode(args):
+    if args.input:
+        g = parse_file(args.input)
+    else:
+        g = Graph()
+    raw = encode(g)
+    if args.output:
+        with open(args.output, "wb") as f:
+            f.write(raw)
+        print(f"Guardado: {args.output} ({len(raw)} bytes)")
+    else:
+        sys.stdout.buffer.write(raw)
+
+
+def cmd_decode(args):
+    if args.input:
+        with open(args.input, "rb") as f:
+            raw = f.read()
+    else:
+        raw = sys.stdin.buffer.read()
+    if is_compressed(raw):
+        raw = decompress(raw)
+    g = decode(raw)
+    stats = g.stats()
+    print(json.dumps(stats, indent=2))
+
+
+def cmd_query(args):
+    with open(args.path, "rb") as f:
+        raw = f.read()
+    if is_compressed(raw):
+        raw = decompress(raw)
+    g = decode(raw)
+
+    if args.type:
+        nodes = g.find(type=args.type)
+        for n in nodes:
+            print(f"  [{n.id}] {n.type}: {n.get('name') or n.get('title') or '?'}")
+    elif args.edge_type:
+        edges = g.find_edges(type=args.edge_type)
+        for e in edges:
+            src_name = g.nodes[e.src].get('name') or g.nodes[e.src].get('title') or f'n{e.src}'
+            tgt_name = g.nodes[e.tgt].get('name') or g.nodes[e.tgt].get('title') or f'n{e.tgt}'
+            print(f"  {src_name} --[{e.type}]--> {tgt_name}")
+    else:
+        print(json.dumps(g.stats(), indent=2))
+
+
+def cmd_benchmark(args):
+    """Benchmark: compara .md vs .llgr vs .llgr comprimido."""
+    path = args.path
+    if os.path.isdir(path):
+        md_size = sum(os.path.getsize(os.path.join(dp, f))
+                      for dp, _, fn in os.walk(path) for f in fn
+                      if f.endswith(".md"))
+        g = parse_directory(path, recursive=not args.no_recursive)
+    else:
+        md_size = os.path.getsize(path)
+        g = parse_file(path)
+
+    raw = encode(g)
+    raw_z = compress(raw, method="zlib")
+
+    print(f"═══ Benchmark: {os.path.basename(path)} ═══")
+    print(f"  .md original:       {md_size:>10,} bytes (baseline)")
+    print(f"  .llgr binario:      {len(raw):>10,} bytes ({md_size/max(len(raw),1):.2f}x)")
+    print(f"  .llgr + zlib:       {len(raw_z):>10,} bytes ({md_size/max(len(raw_z),1):.2f}x)")
+    print(f"  JSON completo:      {len(json.dumps(g.to_dict()).encode()):>10,} bytes")
+    print(f"  Nodes: {g.stats()['nodes']}, Edges: {g.stats()['edges']}")
+
+    # Timing
+    t0 = time.time()
+    for _ in range(10):
+        encode(g)
+    t_enc = (time.time() - t0) / 10
+
+    t0 = time.time()
+    for _ in range(10):
+        decode(raw)
+    t_dec = (time.time() - t0) / 10
+
+    print(f"  Encode time:  {t_enc*1000:.1f}ms")
+    print(f"  Decode time:  {t_dec*1000:.1f}ms")
+
+
+def cmd_diff(args):
+    def _load(path):
+        with open(path, "rb") as f:
+            raw = f.read()
+        if is_compressed(raw):
+            raw = decompress(raw)
+        return decode(raw)
+
+    g1, g2 = _load(args.graph1), _load(args.graph2)
+    s1, s2 = g1.stats(), g2.stats()
+    print(f"Graph 1: {s1['nodes']} nodos, {s1['edges']} edges")
+    print(f"Graph 2: {s2['nodes']} nodos, {s2['edges']} edges")
+    all_types = set(list(s1['node_types'].keys()) + list(s2['node_types'].keys()))
+    for t in sorted(all_types):
+        c1 = s1['node_types'].get(t, 0)
+        c2 = s2['node_types'].get(t, 0)
+        if c1 != c2:
+            print(f"  {t}: {c1} → {c2} ({'+' if c2 > c1 else ''}{c2-c1})")
+
+
+def cmd_info(args):
+    """Mostrar info de un archivo .llgr."""
+    with open(args.path, "rb") as f:
+        raw = f.read()
+
+    if is_compressed(raw):
+        raw = decompress(raw)
+    g = decode(raw)
+    stats = g.stats()
+    # Detect method from original header
+    print(f"Archivo: {args.path}")
+    print(f"  Tamaño disco: {os.path.getsize(args.path):,} bytes")
+    method = "desconocido"
+    with open(args.path, "rb") as f:
+        h = f.read(7)
+    if h[4:6] == b"ZL":
+        method = "zlib"
+    elif h[4:7] == b"LZ4":
+        method = "lz4"
+    print(f"  Comprimido: {'sí (' + method + ')' if method != 'desconocido' else 'no'}")
+    print(f"  Nodos: {stats['nodes']}")
+    print(f"  Edges: {stats['edges']}")
+    print(f"  Metadata: {stats['metadata_keys']} keys")
+    print(f"  Tipos nodo: {stats['node_types']}")
+    print(f"  Tipos edge: {stats['edge_types']}")
+
+
+def cmd_context_init(args):
+    print(json.dumps(context_init(args.project), indent=2))
+
+
+def cmd_context_build(args):
+    print(json.dumps(context_build(args.project), indent=2))
+
+
+def cmd_context_prepare(args):
+    result = context_prepare(
+        args.project,
+        args.task,
+        profile_name=args.profile,
+        max_tokens=args.max_tokens,
+        save_pack=args.save,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(result["context_pack"])
+        if result.get("pack_path"):
+            print(f"\nSaved: {result['pack_path']}")
+
+
+def cmd_context_search(args):
+    print(json.dumps(context_search(args.project, args.query, profile_name=args.profile, top_k=args.top_k), indent=2))
+
+
+def cmd_context_health(args):
+    print(json.dumps(context_health(args.project), indent=2))
+
+
+def cmd_context_update(args):
+    print(json.dumps(context_update(args.project, args.type, args.note, source=args.source), indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="llmgraph",
+        description="LLMGraph — Formato binario de grafos para LLMs v0.2"
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # convert
+    p = sub.add_parser("convert", help="Convertir .md a .llgr")
+    p.add_argument("path", help="Archivo o directorio .md")
+    p.add_argument("-o", "--output")
+    p.add_argument("--no-recursive", action="store_true")
+    p.add_argument("-c", "--compress", choices=["zlib", "lz4"], help="Comprimir post-encoding")
+    p.set_defaults(func=cmd_convert)
+
+    # encode
+    p = sub.add_parser("encode", help="Codificar grafo a binario")
+    p.add_argument("-i", "--input")
+    p.add_argument("-o", "--output")
+    p.set_defaults(func=cmd_encode)
+
+    # decode
+    p = sub.add_parser("decode", help="Decodificar grafo binario")
+    p.add_argument("-i", "--input")
+    p.set_defaults(func=cmd_decode)
+
+    # query
+    p = sub.add_parser("query", help="Consultar un grafo")
+    p.add_argument("path")
+    p.add_argument("-t", "--type")
+    p.add_argument("-e", "--edge-type")
+    p.set_defaults(func=cmd_query)
+
+    # benchmark
+    p = sub.add_parser("benchmark", help="Benchmark .md vs .llgr")
+    p.add_argument("path", help="Archivo o directorio .md")
+    p.add_argument("--no-recursive", action="store_true")
+    p.set_defaults(func=cmd_benchmark)
+
+    # diff
+    p = sub.add_parser("diff", help="Comparar dos grafos")
+    p.add_argument("graph1")
+    p.add_argument("graph2")
+    p.set_defaults(func=cmd_diff)
+
+    # info
+    p = sub.add_parser("info", help="Info de un archivo .llgr")
+    p.add_argument("path")
+    p.set_defaults(func=cmd_info)
+
+    # context
+    p = sub.add_parser("context", help="Gestionar contexto operativo para agentes")
+    csub = p.add_subparsers(dest="context_command")
+
+    cp = csub.add_parser("init", help="Inicializar context/ y context-policy.toml")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.set_defaults(func=cmd_context_init)
+
+    cp = csub.add_parser("build", help="Compilar fuentes Markdown a context/project.llgr.zlib")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.set_defaults(func=cmd_context_build)
+
+    cp = csub.add_parser("prepare", help="Generar Context Pack para una tarea")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.add_argument("task", help="Tarea o pregunta")
+    cp.add_argument("--profile", default=None, help="Perfil: coding, debugging, review, planning, architecture, handoff")
+    cp.add_argument("--max-tokens", type=int, default=None)
+    cp.add_argument("--save", action="store_true", help="Guardar pack en context/packs/")
+    cp.add_argument("--json", action="store_true", help="Emitir JSON en vez de Markdown")
+    cp.set_defaults(func=cmd_context_prepare)
+
+    cp = csub.add_parser("search", help="Buscar dentro del grafo de contexto")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.add_argument("query", help="Consulta")
+    cp.add_argument("--profile", default=None)
+    cp.add_argument("--top-k", type=int, default=10)
+    cp.set_defaults(func=cmd_context_search)
+
+    cp = csub.add_parser("health", help="Auditar el grafo de contexto")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.set_defaults(func=cmd_context_health)
+
+    cp = csub.add_parser("update", help="Agregar memoria operativa al grafo")
+    cp.add_argument("project", help="Ruta del proyecto")
+    cp.add_argument("--type", default="note", help="Tipo de nodo a crear")
+    cp.add_argument("--source", default="agent-update")
+    cp.add_argument("note", help="Nota a agregar")
+    cp.set_defaults(func=cmd_context_update)
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+    if args.command == "context" and not args.context_command:
+        p.print_help()
+        sys.exit(1)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

llmgraph/compressor.py

@@ -0,0 +1,100 @@
+"""
+LLMGraph Compressor — Compresión adicional post-encoding (LZ4/zstd).
+
+El formato binario ya deduplica strings, pero una capa de compresión
+general puede ganar otro 2-4x en grafos grandes.
+"""
+from __future__ import annotations
+import struct
+from .schema import MAGIC
+
+
+# ── Compresión con zlib (stdlib, sin dependencias extra) ──
+def compress_zlib(data: bytes, level: int = 6) -> bytes:
+    """Comprime datos con zlib (deflate). Buena compresión, rápido."""
+    import zlib
+    compressed = zlib.compress(data, level)
+    # Header: MAGIC + "ZL" + compressed_len(4B) + original_len(4B)
+    return MAGIC + b"ZL" + struct.pack("<II", len(compressed), len(data)) + compressed
+
+
+def decompress_zlib(data: bytes) -> bytes:
+    """Descomprime datos comprimidos con compress_zlib."""
+    import zlib
+    if data[:4] != MAGIC or data[4:6] != b"ZL":
+        raise ValueError("No es un archivo LLMGraph comprimido con zlib")
+    comp_len, orig_len = struct.unpack_from("<II", data, 6)
+    compressed = data[14:14+comp_len]
+    return zlib.decompress(compressed)
+
+
+# ── Compresión con LZ4 (si está disponible) ──
+try:
+    import lz4.frame
+    HAS_LZ4 = True
+except ImportError:
+    HAS_LZ4 = False
+
+
+def compress_lz4(data: bytes) -> bytes:
+    if not HAS_LZ4:
+        raise ImportError("pip install lz4")
+    compressed = lz4.frame.compress(data)
+    return MAGIC + b"LZ4" + struct.pack("<II", len(compressed), len(data)) + compressed
+
+
+def decompress_lz4(data: bytes) -> bytes:
+    if not HAS_LZ4:
+        raise ImportError("pip install lz4")
+    if data[:4] != MAGIC or data[4:7] != b"LZ4":
+        raise ValueError("No es un archivo LLMGraph comprimido con LZ4")
+    comp_len, orig_len = struct.unpack_from("<II", data, 7)
+    compressed = data[15:15+comp_len]
+    return lz4.frame.decompress(compressed)
+
+
+# ── API unificada ──
+def compress(data: bytes, method: str = "zlib", level: int = 6) -> bytes:
+    """Comprime un grafo .llgr con el método especificado.
+
+    method: "zlib" (default, stdlib) o "lz4" (requiere pip install lz4)
+    """
+    if method == "lz4":
+        return compress_lz4(data)
+    return compress_zlib(data, level)
+
+
+def decompress(data: bytes) -> bytes:
+    """Auto-detecta el método y descomprime."""
+    if data[:4] != MAGIC:
+        raise ValueError("No es un archivo LLMGraph")
+    method = data[4:6] if len(data) > 5 else b""
+    if method == b"ZL":
+        return decompress_zlib(data)
+    elif data[4:7] == b"LZ4":
+        return decompress_lz4(data)
+    # No compression — return as-is
+    return data
+
+
+def is_compressed(data: bytes) -> bool:
+    return data[:4] == MAGIC and ((len(data) > 6 and data[4:6] == b"ZL") or (len(data) > 7 and data[4:7] == b"LZ4"))
+
+
+def stats(data: bytes) -> dict:
+    """Retorna estadísticas de compresión."""
+    if not is_compressed(data):
+        return {"compressed": False, "size": len(data)}
+    method = "lz4" if data[4:7] == b"LZ4" else "zlib"
+    if method == "zlib":
+        comp_len, orig_len = struct.unpack_from("<II", data, 6)
+    else:
+        comp_len, orig_len = struct.unpack_from("<II", data, 7)
+    return {
+        "compressed": True,
+        "method": method,
+        "compressed_size": len(data),
+        "original_size": orig_len,
+        "ratio": orig_len / max(len(data), 1),
+        "savings_pct": (1 - len(data) / max(orig_len, 1)) * 100,
+    }