klapcontext 0.1.3__tar.gz → 0.2.0__tar.gz

{klapcontext-0.1.3/src/klapcontext.egg-info → klapcontext-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: klapcontext
-Version: 0.1.3
+Version: 0.2.0
 Summary: Make your repository understandable to humans and AI.
 Author: Willy Cordon
 License-Expression: Apache-2.0
@@ -21,6 +21,11 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: graphifyy>=0.9.66
+Requires-Dist: tree-sitter<0.26,>=0.24
+Requires-Dist: tree-sitter-php<0.25,>=0.24
+Requires-Dist: tree-sitter-javascript<0.26,>=0.23
+Requires-Dist: tree-sitter-typescript<0.26,>=0.23
+Requires-Dist: mcp<2,>=1.0
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
@@ -36,6 +41,14 @@ entrada, flujos, automatizaciones, integraciones y sus incertidumbres.
 Graphify funciona como proveedor de análisis técnico; KlapContext es la capa
 que transforma esa evidencia en comprensión para personas y agentes de IA.
 
+## Agent Intelligence
+
+KlapContext planifica el **mínimo contexto relevante** antes de que un agente
+empiece a cambiar código. Según la intención —entender, modificar, depurar,
+probar, refactorizar o medir impacto— selecciona capacidades y proveedores
+necesarios, sin acoplarse a una herramienta externa ni cargar archivos enteros
+por defecto. La compilación de Task Context llegará en los siguientes sprints.
+
 KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
 portal estático para personas y un briefing compacto para agentes de IA. Usa
 [Graphify](https://github.com/Graphify-Labs/graphify) como motor local de

{klapcontext-0.1.3 → klapcontext-0.2.0}/README.md

@@ -7,6 +7,14 @@ entrada, flujos, automatizaciones, integraciones y sus incertidumbres.
 Graphify funciona como proveedor de análisis técnico; KlapContext es la capa
 que transforma esa evidencia en comprensión para personas y agentes de IA.
 
+## Agent Intelligence
+
+KlapContext planifica el **mínimo contexto relevante** antes de que un agente
+empiece a cambiar código. Según la intención —entender, modificar, depurar,
+probar, refactorizar o medir impacto— selecciona capacidades y proveedores
+necesarios, sin acoplarse a una herramienta externa ni cargar archivos enteros
+por defecto. La compilación de Task Context llegará en los siguientes sprints.
+
 KlapContext convierte un repositorio en contexto de ingeniería reutilizable: un
 portal estático para personas y un briefing compacto para agentes de IA. Usa
 [Graphify](https://github.com/Graphify-Labs/graphify) como motor local de

{klapcontext-0.1.3 → klapcontext-0.2.0}/pyproject.toml

@@ -13,7 +13,7 @@ license-files = ["LICENSE"]
 authors = [{name = "Willy Cordon"}]
 keywords = ["codebase", "developer-tools", "engineering-context", "graphify", "ai-agents"]
 classifiers = ["Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Topic :: Software Development :: Documentation"]
-dependencies = ["graphifyy>=0.9.66"]
+dependencies = ["graphifyy>=0.9.66", "tree-sitter>=0.24,<0.26", "tree-sitter-php>=0.24,<0.25", "tree-sitter-javascript>=0.23,<0.26", "tree-sitter-typescript>=0.23,<0.26", "mcp>=1.0,<2"]
 
 [project.optional-dependencies]
 dev = ["build>=1.2", "pytest>=8", "twine>=6"]

{klapcontext-0.1.3 → klapcontext-0.2.0}/src/klapcontext/__init__.py

@@ -1,3 +1,3 @@
 """KlapContext local engineering-context generator."""
 
-__version__ = "0.1.3"
+__version__ = "0.2.0"

klapcontext-0.2.0/src/klapcontext/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Planning layer for compact, task-specific agent context."""
+
+from .planner import ContextPlanner
+
+__all__ = ["ContextPlanner"]

klapcontext-0.2.0/src/klapcontext/agent/capabilities.py

@@ -0,0 +1,66 @@
+"""Capabilities are stable; tools that implement them are replaceable."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Capability(str, Enum):
+    FRAMEWORK_ANALYSIS = "framework_analysis"
+    ENTRY_POINT_DISCOVERY = "entry_point_discovery"
+    FLOW_RECONSTRUCTION = "flow_reconstruction"
+    DEPENDENCY_GRAPH = "dependency_graph"
+    PATH_SEARCH = "path_search"
+    TEST_DISCOVERY = "test_discovery"
+    INTEGRATION_DISCOVERY = "integration_discovery"
+    AUTOMATION_DISCOVERY = "automation_discovery"
+    CONFIG_DISCOVERY = "config_discovery"
+    SYMBOL_LOOKUP = "symbol_lookup"
+    CALL_GRAPH = "call_graph"
+    CALLERS = "callers"
+    CALLEES = "callees"
+    IMPACT_ANALYSIS = "impact_analysis"
+    MINIMAL_EDIT_CONTEXT = "minimal_edit_context"
+    GIT_HISTORY = "git_history"
+
+
+@dataclass(frozen=True)
+class ProviderInfo:
+    name: str
+    capabilities: frozenset[Capability]
+    available: bool
+    optional: bool = False
+
+
+@dataclass(frozen=True)
+class CapabilityResolution:
+    capability: Capability
+    provider: str | None
+    status: str
+    fallbacks: tuple[str, ...] = ()
+
+
+class CapabilityRouter:
+    """Select an available provider without leaking provider names to callers."""
+    def __init__(self, providers: list[ProviderInfo]):
+        self.providers = providers
+
+    def resolve(self, capability: Capability) -> CapabilityResolution:
+        candidates = [provider for provider in self.providers if capability in provider.capabilities]
+        ready = next((provider for provider in candidates if provider.available), None)
+        if ready:
+            return CapabilityResolution(capability, ready.name, "READY", tuple(provider.name for provider in candidates if provider.name != ready.name))
+        return CapabilityResolution(capability, None, "UNAVAILABLE", tuple(provider.name for provider in candidates))
+
+
+def default_providers(graphify_ready: bool | None = None) -> list[ProviderInfo]:
+    from ..providers.code_intelligence import available as php_code_intelligence_available
+    if graphify_ready is None:
+        from ..graphify import command_prefix
+        graphify_ready = command_prefix() is not None
+    return [
+        ProviderInfo("klap-native", frozenset({Capability.FRAMEWORK_ANALYSIS, Capability.ENTRY_POINT_DISCOVERY, Capability.FLOW_RECONSTRUCTION, Capability.TEST_DISCOVERY, Capability.INTEGRATION_DISCOVERY, Capability.AUTOMATION_DISCOVERY, Capability.CONFIG_DISCOVERY}), True),
+        ProviderInfo("graphify", frozenset({Capability.DEPENDENCY_GRAPH, Capability.PATH_SEARCH, Capability.FLOW_RECONSTRUCTION}), graphify_ready),
+        ProviderInfo("php-tree-sitter", frozenset({Capability.SYMBOL_LOOKUP, Capability.CALL_GRAPH, Capability.CALLERS, Capability.CALLEES, Capability.IMPACT_ANALYSIS, Capability.MINIMAL_EDIT_CONTEXT}), php_code_intelligence_available()),
+        ProviderInfo("tree-sitter-mcp", frozenset({Capability.SYMBOL_LOOKUP, Capability.CALL_GRAPH, Capability.CALLERS, Capability.CALLEES, Capability.IMPACT_ANALYSIS, Capability.MINIMAL_EDIT_CONTEXT}), False, True),
+    ]

klapcontext-0.2.0/src/klapcontext/agent/compiler.py

@@ -0,0 +1,64 @@
+"""Compile a small, explainable agent context from the system model."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .planner import ContextPlanner
+from ..context_builder import build
+from .verification import reconcile, sanitize
+
+DETAIL_LIMITS = {"minimal": 3, "standard": 6, "deep": 12}
+
+
+def _terms(query: str, area: str) -> set[str]:
+    return {item for item in re.findall(r"[a-zA-Z_]{4,}", f"{query} {area}".casefold()) if item not in {"quiero", "modificar", "cambiar", "sobre", "para"}}
+
+
+def _rank(items: list[dict], terms: set[str], limit: int) -> list[dict]:
+    ranked = []
+    for original in items:
+        text = json.dumps(original, ensure_ascii=False).casefold(); matches = sum(term in text for term in terms)
+        if matches or not terms:
+            item = dict(original); item["relevance"] = "directa" if matches else "contextual"; item["reason"] = "Coincide con la tarea" if matches else "Contexto estructural cercano"; ranked.append((matches, item))
+    return [item for _, item in sorted(ranked, key=lambda pair: pair[0], reverse=True)[:limit]]
+
+
+def compile_context(root: Path, query: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    plan = ContextPlanner().plan(query, detail=detail, max_tokens=max_tokens)
+    context = build(root, {"nodes": []}); model = context["system_model"]; limit = min(DETAIL_LIMITS[detail], max(1, max_tokens // 350)); terms = _terms(query, plan.area)
+    entries = _rank(model["entry_points"], terms, limit); flows = _rank(model["main_flows"], terms, limit); files = _rank(model["important_files"], terms, limit)
+    read_first = ([{"path": item.get("file"), "reason": "Punto de entrada relacionado", "relevance": item["relevance"]} for item in entries if item.get("file")] + files)[:limit]
+    result = {"intent": plan.intent, "confidence": plan.confidence, "query": query, "area": plan.area, "detail": detail, "max_tokens": max_tokens, "entry_points": entries, "flows": flows, "symbols": _rank(model["semantic_model"]["components"], terms, limit), "files": files, "dependencies": _rank(model["dependencies"], terms, limit), "tests": _rank(context["tests"], terms, limit), "read_first": read_first, "evidence": [evidence for group in entries + flows for evidence in group.get("evidence", [])][:limit], "uncertainties": model["unknowns"], "strategy": plan.strategy}
+    result["verification"] = reconcile(result["evidence"])
+    result = sanitize(result)
+    result["estimated_tokens"] = min(max_tokens, len(json.dumps(result, ensure_ascii=False)) // 4)
+    result["execution"] = {"capabilities": plan.capabilities, "providers": plan.providers, "files_selected": len(result["read_first"]), "sections_selected": len(plan.sections), "adaptive": True}
+    return result
+
+
+def system_context(root: Path, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    return compile_context(root, "understand system", detail=detail, max_tokens=max_tokens)
+
+
+def area_context(root: Path, area: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    return compile_context(root, f"understand {area}", detail=detail, max_tokens=max_tokens)
+
+
+def change_context(root: Path, task: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    result = compile_context(root, task, detail=detail, max_tokens=max_tokens)
+    result["context_type"] = "CHANGE"; result["risks"] = result["uncertainties"]
+    return result
+
+
+def debug_context(root: Path, task: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    result = compile_context(root, task, detail=detail, max_tokens=max_tokens)
+    result["context_type"] = "DEBUG"; result["investigation_points"] = result["entry_points"] + result["flows"]
+    return result
+
+
+def compile_test_context(root: Path, task: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    result = compile_context(root, f"test {task}", detail=detail, max_tokens=max_tokens)
+    result["context_type"] = "TEST"
+    return result

klapcontext-0.2.0/src/klapcontext/agent/impact.py

@@ -0,0 +1,18 @@
+"""Explain structural impact; it never predicts that a change will break code."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..context_builder import build
+from ..providers.code_intelligence import PhpCodeIntelligenceProvider
+
+
+def analyze_impact(root: Path, symbol: str) -> dict:
+    structural = PhpCodeIntelligenceProvider(root).impact(symbol)
+    model = build(root, {"nodes": []})["system_model"]
+    callers = structural["direct_callers"] + [{"source_symbol": item, "confidence": "INFERRED"} for item in structural["indirect_callers"]]
+    names = {symbol, *(item["source_symbol"] for item in callers)}
+    flows = [item for item in model["main_flows"] if any(any(name.endswith(step["name"]) or step["name"].endswith(name) for name in names) for step in item["steps"])]
+    entries = [item for item in model["entry_points"] if any(item.get("handler", "").endswith(name) or name.endswith(item.get("handler", "")) for name in names)]
+    tests = sorted(set(structural["related_tests"] + [item["path"] for item in model["important_files"] if "test" in item["path"].casefold()]))
+    return {"symbol": symbol, "statement": "Elementos potencialmente afectados según relaciones estructurales; no predice fallas.", "direct_callers": structural["direct_callers"], "indirect_callers": structural["indirect_callers"], "entry_points": entries, "flows": flows, "tests": tests, "configuration": [item for item in model["important_files"] if item["path"].startswith("config/")], "integrations": model["external_systems"], "uncertainties": model["unknowns"]}

klapcontext-0.2.0/src/klapcontext/agent/intents.py

@@ -0,0 +1,39 @@
+"""Deterministic Spanish/English intent and area detection for planning."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class IntentMatch:
+    intent: str
+    confidence: float
+    area: str
+
+
+RULES = (
+    ("DEBUG", ("error", "falla", "fallo", "bug", "exception", "500", "debug")),
+    ("IMPACT", ("impacto", "qué rompe", "que rompe", "qué usa", "que usa", "afecta", "impact")),
+    ("REFACTOR", ("refactor", "limpiar", "separar", "reestructurar")),
+    ("TEST", ("test", "prueba", "coverage", "cobertura")),
+    ("CHANGE", ("modificar", "cambiar", "agregar", "implementar", "añadir", "fix", "update", "edit")),
+    ("UNDERSTAND", ("qué hace", "que hace", "entender", "explicar", "comprender", "how does", "what does")),
+)
+AREAS = (
+    ("authentication", ("auth", "autentic", "login", "logout", "jwt", "oauth", "sanctum", "passport", "password")),
+    ("orders", ("order", "pedido", "orden")),
+    ("files", ("archivo", "file", "upload", "sftp", "ftp", "storage")),
+    ("payments", ("payment", "pago", "checkout", "stripe")),
+    ("notifications", ("notification", "notific", "mail", "email", "sms")),
+)
+
+
+def detect(query: str) -> IntentMatch:
+    text = query.casefold()
+    intent, confidence = "UNDERSTAND", .45
+    for candidate, words in RULES:
+        if any(word in text for word in words):
+            intent, confidence = candidate, .9
+            break
+    area = next((name for name, words in AREAS if any(word in text for word in words)), "unknown")
+    return IntentMatch(intent, confidence, area)

klapcontext-0.2.0/src/klapcontext/agent/models.py

@@ -0,0 +1,21 @@
+"""Small serializable model for the future context compiler."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class AgentContextPlan:
+    query: str
+    intent: str
+    confidence: float
+    area: str
+    detail: str
+    max_tokens: int
+    capabilities: list[str]
+    providers: list[dict]
+    sections: list[str]
+    strategy: str
+
+    def as_dict(self) -> dict:
+        return asdict(self)

klapcontext-0.2.0/src/klapcontext/agent/planner.py

@@ -0,0 +1,32 @@
+"""Choose the smallest evidence plan that can answer an agent's task."""
+from __future__ import annotations
+
+from .capabilities import Capability, CapabilityRouter, default_providers
+from .intents import detect
+from .models import AgentContextPlan
+
+
+PLANS = {
+    "UNDERSTAND": ([Capability.FRAMEWORK_ANALYSIS, Capability.ENTRY_POINT_DISCOVERY, Capability.FLOW_RECONSTRUCTION, Capability.INTEGRATION_DISCOVERY, Capability.AUTOMATION_DISCOVERY], ["purpose", "entry_points", "flows", "integrations", "automations", "uncertainties"]),
+    "CHANGE": ([Capability.ENTRY_POINT_DISCOVERY, Capability.FLOW_RECONSTRUCTION, Capability.SYMBOL_LOOKUP, Capability.CALLERS, Capability.IMPACT_ANALYSIS, Capability.CONFIG_DISCOVERY, Capability.TEST_DISCOVERY], ["entry_points", "flows", "files", "symbols", "configuration", "tests", "impact", "evidence", "uncertainties"]),
+    "DEBUG": ([Capability.ENTRY_POINT_DISCOVERY, Capability.FLOW_RECONSTRUCTION, Capability.INTEGRATION_DISCOVERY, Capability.CONFIG_DISCOVERY, Capability.TEST_DISCOVERY], ["entry_points", "flows", "configuration", "tests", "investigation_points", "evidence", "uncertainties"]),
+    "TEST": ([Capability.TEST_DISCOVERY, Capability.ENTRY_POINT_DISCOVERY, Capability.FLOW_RECONSTRUCTION], ["tests", "related_code", "entry_points", "flows", "uncertainties"]),
+    "REFACTOR": ([Capability.SYMBOL_LOOKUP, Capability.CALLERS, Capability.CALLEES, Capability.IMPACT_ANALYSIS, Capability.TEST_DISCOVERY], ["symbols", "callers", "callees", "impact", "tests", "evidence"]),
+    "IMPACT": ([Capability.SYMBOL_LOOKUP, Capability.CALLERS, Capability.IMPACT_ANALYSIS, Capability.TEST_DISCOVERY], ["symbols", "callers", "impact", "tests", "uncertainties"]),
+}
+
+
+class ContextPlanner:
+    def __init__(self, router: CapabilityRouter | None = None):
+        self.router = router or CapabilityRouter(default_providers())
+
+    def plan(self, query: str, *, detail: str = "standard", max_tokens: int = 5000) -> AgentContextPlan:
+        if detail not in {"minimal", "standard", "deep"}:
+            raise ValueError("detail must be minimal, standard or deep")
+        if max_tokens < 200:
+            raise ValueError("max_tokens must be at least 200")
+        match = detect(query)
+        capabilities, sections = PLANS[match.intent]
+        if detail == "minimal": sections = sections[:max(3, len(sections) // 2)]
+        resolutions = [self.router.resolve(capability) for capability in capabilities]
+        return AgentContextPlan(query, match.intent, match.confidence, match.area, detail, max_tokens, [capability.value for capability in capabilities], [{"capability": resolution.capability.value, "provider": resolution.provider, "status": resolution.status, "fallbacks": list(resolution.fallbacks)} for resolution in resolutions], sections, "Prioriza evidencia directa, luego relaciones de flujo y finalmente contexto periférico hasta agotar el presupuesto.")

klapcontext-0.2.0/src/klapcontext/agent/verification.py

@@ -0,0 +1,19 @@
+"""Normalize evidence and prevent secrets from entering agent output."""
+from __future__ import annotations
+
+import re
+
+SECRET = re.compile(r"(?i)(password|secret|token|api[_-]?key|private[_-]?key)\s*[:=]\s*[^\s,]+")
+
+def sanitize(value):
+    if isinstance(value, str): return SECRET.sub(lambda match: match.group(1) + "=[REDACTED]", value)
+    if isinstance(value, list): return [sanitize(item) for item in value]
+    if isinstance(value, dict): return {key: sanitize(item) for key, item in value.items() if key.casefold() not in {"password", "secret", "token", "api_key", "private_key"}}
+    return value
+
+def reconcile(evidence: list[dict]) -> dict:
+    unique, seen = [], set()
+    for item in evidence:
+        clean = sanitize(item); key = (clean.get("path"), clean.get("line"), clean.get("symbol"), clean.get("reason"))
+        if key not in seen: seen.add(key); unique.append(clean)
+    return {"evidence": unique, "conflicts": [], "status": "CONFIRMED" if unique else "UNKNOWN"}

klapcontext-0.2.0/src/klapcontext/agent/workflows.py

@@ -0,0 +1,31 @@
+"""Agent workflows combine compact context with Git and impact evidence."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .compiler import change_context
+from .impact import analyze_impact
+from ..git import intelligence
+from ..git import dirty_files, run_git
+
+
+def prepare_change(root: Path, task: str, *, detail: str = "standard", max_tokens: int = 5000) -> dict:
+    result = change_context(root, task, detail=detail, max_tokens=max_tokens)
+    paths = [item.get("path") for item in result["read_first"] if item.get("path")]
+    result["git"] = intelligence(root, paths)
+    result["workflow"] = "PREPARE_CHANGE"
+    return result
+
+
+def change_impact(root: Path, symbol: str) -> dict:
+    result = analyze_impact(root, symbol); result["git"] = intelligence(root); result["workflow"] = "CHANGE_IMPACT"
+    return result
+
+
+def verify_change(root: Path) -> dict:
+    changed = dirty_files(root)
+    diff = run_git(root, "diff", "--name-only") or ""
+    changed = sorted(set(changed + [line for line in diff.splitlines() if line]))
+    context = prepare_change(root, "verificar cambio", detail="minimal", max_tokens=1200)
+    tests = [item for item in context["tests"] if item.get("path")]
+    return {"workflow": "VERIFY_CHANGE", "changed_files": changed, "related_tests": tests, "potential_risks": context["uncertainties"], "statement": "Hallazgos verificables del diff actual; no aprueba ni rechaza el cambio automáticamente."}

{klapcontext-0.1.3 → klapcontext-0.2.0}/src/klapcontext/cli.py

@@ -57,6 +57,13 @@ def cmd_agent(args):
     print("Graphify MCP (stdio):\npython -m graphify.serve " + str(graph) + "\n\nGeneric configuration:\n{\n  \"mcpServers\": {\n    \"graphify\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"graphify.serve\", \"" + str(graph).replace('\\','\\\\') + "\"]\n    }\n  }\n}")
     return 0
 
+def cmd_context(args):
+    from .agent.compiler import compile_context
+    result=compile_context(root_path(args.path), args.query, detail=args.detail, max_tokens=args.max_tokens)
+    if args.json: print(json.dumps(result, ensure_ascii=False, indent=2))
+    else: print(f"Intent: {result['intent']}\nÁrea: {result['area']}\nRead first:\n" + "\n".join(f"- {item.get('path', item.get('name'))}: {item['reason']}" for item in result['read_first']))
+    return 0
+
 def main(argv=None):
     # PowerShell's legacy cp1252 console otherwise raises on the intended status symbols.
     if hasattr(sys.stdout, "reconfigure"):
@@ -68,6 +75,7 @@ def main(argv=None):
     subs=parser.add_subparsers(dest="command", required=True)
     for name, func, help_text in (("init",cmd_init,"Generate engineering context"),("update",cmd_update,"Refresh engineering context"),("status",cmd_status,"Show context freshness"),("open",cmd_open,"Open the human portal"),("agent",cmd_agent,"Show Graphify MCP setup")):
         p=subs.add_parser(name, help=help_text); p.add_argument("path", nargs="?", help="Repository root (defaults to current directory)"); p.set_defaults(func=func)
+    p=subs.add_parser("context", help="Compile compact context for an agent task"); p.add_argument("query"); p.add_argument("path", nargs="?", default="."); p.add_argument("--detail", choices=("minimal", "standard", "deep"), default="standard"); p.add_argument("--max-tokens", type=int, default=5000); p.add_argument("--json", action="store_true"); p.set_defaults(func=cmd_context)
     args=parser.parse_args(argv); return args.func(args)
 
 if __name__ == "__main__": raise SystemExit(main())

klapcontext-0.2.0/src/klapcontext/context_builder.py

@@ -0,0 +1,121 @@
+"""Build a product-level model from framework-neutral semantic evidence."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .detector import detect_components, detect_project
+from .frameworks.generic_php import GenericPhpAdapter
+from .frameworks.laravel import LaravelAdapter
+from .frameworks.fastapi import FastAPIAdapter
+from .frameworks.node import NodeAdapter
+from .git import commit
+from .semantic import SemanticModel
+from .system import deployment, documents, external_systems, purpose
+
+
+def _nodes(graph: dict) -> list[dict]:
+    return graph.get("nodes", []) if isinstance(graph.get("nodes"), list) else graph.get("graph", {}).get("nodes", [])
+
+
+def _modules(nodes: list[dict]) -> list[dict]:
+    return [{"name": item.get("label") or item.get("name") or item.get("id"), "path": item.get("file") or item.get("path"), "kind": item.get("type", "module"), "description": None, "status": "CONFIRMED", "evidence": []} for item in nodes if (item.get("label") or item.get("name") or item.get("id")) and (item.get("file") or item.get("path"))][:100]
+
+
+def _runtime(points: list[dict], background: list[dict], frameworks: list[str]) -> dict:
+    types = {item["type"].casefold() for item in points}
+    modes, descriptions = [], []
+    if "http" in types: modes.append("http"); descriptions.append("Las solicitudes HTTP ingresan por las rutas detectadas.")
+    if "cli" in types: modes.append("cli"); descriptions.append("La aplicación expone comandos ejecutables.")
+    if background: modes.append("scheduler"); descriptions.append("La aplicación declara procesamiento en segundo plano.")
+    return {"modes": modes, "layers": frameworks, "description": " ".join(descriptions) or None, "status": "CONFIRMED" if descriptions else "UNKNOWN"}
+
+
+def _io(points: list[dict], systems: list[dict], stores: list[dict]) -> tuple[list[dict], list[dict]]:
+    inputs, outputs, types = [], [], {item["type"].casefold() for item in points}
+    if "http" in types:
+        inputs.append({"type": "http_request", "description": "Solicitudes HTTP", "status": "CONFIRMED"}); outputs.append({"type": "http_response", "description": "Respuestas HTTP", "status": "INFERRED"})
+    if "cli" in types: inputs.append({"type": "cli", "description": "Invocación por línea de comandos", "status": "CONFIRMED"})
+    if stores:
+        inputs.append({"type": "datastore", "description": "Base de datos", "status": "INFERRED"}); outputs.append({"type": "datastore", "description": "Escrituras de base de datos", "status": "INFERRED"})
+    return inputs, outputs
+
+
+def _flows(model: dict) -> list[dict]:
+    """Reconstruct compact flows from generic entry points and transitions only."""
+    components = {item.get("symbol") or item["name"]: item for item in model["components"]}
+    outgoing: dict[str, list[dict]] = {}
+    for edge in model["transitions"]: outgoing.setdefault(edge["source"], []).append(edge)
+    flows = []
+    for entry in model["entry_points"][:10]:
+        steps = [{"name": entry["name"], "kind": entry["type"].casefold(), "path": entry.get("file"), "status": entry["status"]}]
+        current = entry["name"]
+        if entry.get("handler"):
+            steps.append({"name": entry["handler"], "kind": "handler", "path": entry.get("file"), "status": entry["status"]}); current = entry["handler"]
+        seen = {entry["name"], current}
+        for _ in range(4):
+            candidates = outgoing.get(current, []) or [item for source, values in outgoing.items() if source.endswith(current) for item in values]
+            edge = next((item for item in candidates if item["target"] not in seen), None)
+            if not edge: break
+            target = edge["target"]; component = components.get(target, {})
+            steps.append({"name": target, "kind": edge["type"].casefold(), "path": component.get("file") or edge.get("file"), "status": edge["status"]})
+            seen.add(target); current = target
+        if len(steps) > 1:
+            status = "CONFIRMED" if all(item["status"] == "CONFIRMED" for item in steps) else "INFERRED"
+            flows.append({"name": entry["name"], "trigger": entry["type"].casefold(), "entry_point": entry["name"], "steps": steps, "status": status, "confidence": 1.0 if status == "CONFIRMED" else .7, "evidence": entry["evidence"], "inputs": [], "outputs": [], "external_systems": [], "datastores": [], "tests": []})
+    return flows
+
+
+def _interactions(flows: list[dict], systems: list[dict], stores: list[dict]) -> dict:
+    nodes, edges = [], []
+    def add(name: str, kind: str):
+        if not any(item["name"] == name for item in nodes): nodes.append({"name": name, "type": kind})
+    for flow in flows:
+        previous = None
+        for step in flow["steps"]:
+            add(step["name"], step["kind"])
+            if previous: edges.append({"source": previous, "target": step["name"], "label": "calls"})
+            previous = step["name"]
+    for store in stores: add(store["name"], "datastore")
+    for system in systems: add(system["name"], "external_system")
+    return {"nodes": nodes[:30], "edges": edges[:45], "status": "INFERRED" if edges else "UNKNOWN"}
+
+
+def _empty_raw() -> dict:
+    return {"routes": [], "commands": [], "scheduled_processes": [], "queue_jobs": [], "events": [], "listeners": [], "components": [], "dependencies": [], "runtime_surfaces": [], "important_files": [], "framework": None}
+
+
+def _semantic(root: Path, stack: dict) -> tuple[SemanticModel, dict]:
+    if "Laravel" in stack["frameworks"]:
+        model = LaravelAdapter().analyze(root)
+        return model, model.metadata["raw"]
+    if "FastAPI" in stack["frameworks"]:
+        return FastAPIAdapter().analyze(root), _empty_raw()
+    for framework in ("Express", "NestJS"):
+        if framework in stack["frameworks"]: return NodeAdapter(framework).analyze(root), _empty_raw()
+    if "PHP" in stack["languages"]: return GenericPhpAdapter().analyze(root), _empty_raw()
+    return SemanticModel(stack["languages"][0] if stack["languages"] else None), _empty_raw()
+
+
+def _analysis_evidence(raw: dict) -> list[dict]:
+    seen, result = set(), []
+    for group in ("routes", "commands", "scheduled_processes", "queue_jobs", "events", "listeners", "components", "dependencies"):
+        for item in raw.get(group, []):
+            for evidence in item.get("evidence", []):
+                key = (evidence.get("path"), evidence.get("line"), evidence.get("reason"), evidence.get("symbol"))
+                if key not in seen: seen.add(key); result.append(evidence)
+    return result
+
+
+def build(root: Path, graph: dict) -> dict:
+    stack, detector_evidence = detect_project(root)
+    docs = documents(root); value = purpose(root, docs); systems, stores = external_systems(root); deploy, observability, _ = deployment(root)
+    semantic, raw = _semantic(root, stack); model = semantic.as_dict(); model["project_components"] = detect_components(root); points, background = model["entry_points"], model["background_tasks"]
+    runtime = _runtime(points, background, stack["frameworks"]); inputs, outputs = _io(points, systems, stores); flows = _flows(model)
+    important = raw["important_files"] or ([{"path": "README.md", "role": "Documentación", "reason": "README detectado"}] if (root / "README.md").exists() else [])
+    tests = [{"path": item, "reason": "Tests detectados"} for item in ("tests", "test", "phpunit.xml", "pytest.ini") if (root / item).exists()]
+    story = " ".join(item for item in (value["text"], runtime["description"], "La aplicación está contenerizada con Docker." if "Docker" in deploy["tools"] else None) if item)
+    system = {"purpose": value, "project_story": {"text": story or None, "status": "CONFIRMED" if story else "UNKNOWN"}, "runtime": runtime, "framework": raw["framework"], "runtime_surfaces": raw["runtime_surfaces"], "routes": raw["routes"], "commands": raw["commands"], "scheduled_processes": raw["scheduled_processes"], "queue_jobs": raw["queue_jobs"], "events": raw["events"], "listeners": raw["listeners"], "components": raw["components"], "dependencies": raw["dependencies"], "semantic_model": model, "entry_points": points, "main_flows": flows, "system_interactions": _interactions(flows, systems, stores), "capabilities": _modules(_nodes(graph)), "inputs": inputs, "outputs": outputs, "external_systems": systems, "background_processes": background, "datastores": stores, "deployment": deploy, "observability": observability, "important_files": important, "start_here": [], "unknowns": [item for item, found in (("Propósito de negocio del proyecto", value["text"]), ("Plataforma de despliegue en producción", deploy["tools"])) if not found]}
+    technical = {"languages": stack["languages"], "frameworks": stack["frameworks"], "framework": raw["framework"], "dependencies": raw["dependencies"], "graph": {"nodes": len(_nodes(graph)), "edges": len(graph.get("edges", graph.get("graph", {}).get("edges", [])))}, "documents": [{"path": item["path"]} for item in docs], "tests": tests, "infrastructure": stack["infrastructure"]}
+    project = {"name": root.name, "type": stack["frameworks"][0] if stack["frameworks"] else None, "root": str(root.resolve()), "generated_at": datetime.now(timezone.utc).isoformat(), "git_commit": commit(root)}
+    return {"schema_version": "0.5", "project": project, "technical_model": technical, "system_model": system, "semantic_model": model, "human_context": {"purpose": None, "users": None, "important_processes": [], "notes": []}, "stack": stack, "architecture": {"style": "MVC" if "Laravel" in stack["frameworks"] else None, "status": "INFERRED" if "Laravel" in stack["frameworks"] else "UNKNOWN", "confidence": None, "evidence": []}, "entry_points": points, "modules": system["capabilities"], "flows": flows, "api": raw["routes"], "jobs": background, "datastores": stores, "external_systems": systems, "deployment": deploy, "observability": observability, "tests": tests, "evidence": [item.as_dict() for item in detector_evidence] + value["evidence"] + _analysis_evidence(raw)}

{klapcontext-0.1.3 → klapcontext-0.2.0}/src/klapcontext/detector.py

@@ -18,17 +18,37 @@ def detect_project(root: Path) -> tuple[dict, list[Evidence]]:
         try: deps = {**json.loads(composer.read_text(encoding="utf-8")).get("require", {}), **json.loads(composer.read_text(encoding="utf-8")).get("require-dev", {})}
         except json.JSONDecodeError: deps = {}
         if "laravel/framework" in deps: add("frameworks", "Laravel", "composer.json", "laravel/framework dependency detected")
+    elif any(root.rglob("*.php")):
+        # A standalone PHP repository has no Composer manifest to identify it,
+        # but language analysis can still provide a useful generic model.
+        first_php = next(root.rglob("*.php"))
+        add("languages", "PHP", str(first_php.relative_to(root)).replace("\\", "/"), "PHP source file detected")
     package = root / "package.json"
     if package.exists():
         add("languages", "JavaScript", "package.json", "npm manifest detected")
         try: deps = {**json.loads(package.read_text(encoding="utf-8")).get("dependencies", {}), **json.loads(package.read_text(encoding="utf-8")).get("devDependencies", {})}
         except json.JSONDecodeError: deps = {}
-        for name, label in (("next", "Next.js"), ("vue", "Vue"), ("react", "React"), ("express", "Express")):
+        for name, label in (("next", "Next.js"), ("vue", "Vue"), ("react", "React"), ("express", "Express"), ("@nestjs/core", "NestJS")):
             if name in deps: add("frameworks", label, "package.json", f"{name} dependency detected")
-    if (root / "pyproject.toml").exists() or (root / "requirements.txt").exists(): add("languages", "Python", "pyproject.toml" if (root / "pyproject.toml").exists() else "requirements.txt", "Python manifest detected")
+    if (root / "pyproject.toml").exists() or (root / "requirements.txt").exists():
+        python_manifest = root / "pyproject.toml" if (root / "pyproject.toml").exists() else root / "requirements.txt"
+        add("languages", "Python", python_manifest.name, "Python manifest detected")
+        if "fastapi" in python_manifest.read_text(encoding="utf-8", errors="ignore").casefold(): add("frameworks", "FastAPI", python_manifest.name, "FastAPI dependency detected")
     if (root / "manage.py").exists(): add("frameworks", "Django", "manage.py", "Django entry point detected")
     if list(root.glob("*.csproj")): add("languages", "C#", next(root.glob("*.csproj")).name, ".NET project detected")
     if (root / "Dockerfile").exists(): add("infrastructure", "Docker", "Dockerfile", "Dockerfile detected")
     if list(root.glob("docker-compose*")) or list(root.glob("compose*")): add("infrastructure", "Docker Compose", "docker-compose", "Compose configuration detected")
     if (root / ".github" / "workflows").exists(): add("infrastructure", "GitHub Actions", ".github/workflows", "GitHub Actions workflows detected")
     return stack, evidence
+
+
+def detect_components(root: Path) -> list[dict]:
+    """Find independent project boundaries without assuming a monorepo layout."""
+    result = []
+    for manifest in [*root.rglob("composer.json"), *root.rglob("package.json"), *root.rglob("pyproject.toml"), *root.rglob("requirements.txt")]:
+        if any(part in {".git", ".klap", "node_modules", "vendor", ".venv", "venv"} for part in manifest.relative_to(root).parts): continue
+        directory = manifest.parent
+        if directory == root: continue
+        stack, _ = detect_project(directory)
+        result.append({"name": directory.name, "path": directory.relative_to(root).as_posix(), "languages": stack["languages"], "frameworks": stack["frameworks"], "manifest": manifest.name, "status": "CONFIRMED"})
+    return result

klapcontext-0.2.0/src/klapcontext/frameworks/base.py

@@ -0,0 +1,17 @@
+"""Contracts for framework-specific enrichment of the generic semantic model."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..semantic import SemanticModel
+
+
+class FrameworkAdapter(Protocol):
+    """Detect one framework and emit framework-neutral semantic facts."""
+
+    name: str
+
+    def detect(self, root: Path) -> bool: ...
+
+    def analyze(self, root: Path) -> SemanticModel: ...

klapcontext-0.2.0/src/klapcontext/frameworks/fastapi.py

@@ -0,0 +1,37 @@
+"""FastAPI conventions translated into the framework-neutral semantic model."""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from ..evidence import Evidence
+from ..providers.python_intelligence import analyze as analyze_python
+from ..semantic import EntryPoint, ExecutionTransition, SemanticModel
+
+
+class FastAPIAdapter:
+    name = "FastAPI"
+
+    def detect(self, root: Path) -> bool:
+        return any("fastapi" in path.read_text(encoding="utf-8", errors="ignore").casefold() for path in (root / "pyproject.toml", root / "requirements.txt") if path.exists())
+
+    def analyze(self, root: Path) -> SemanticModel:
+        components, transitions = analyze_python(root); entries = []
+        for path in root.rglob("*.py"):
+            if any(part in {".venv", "venv", ".git", ".klap"} for part in path.relative_to(root).parts): continue
+            relative = path.relative_to(root).as_posix()
+            try: tree = ast.parse(path.read_text(encoding="utf-8"))
+            except (OSError, SyntaxError): continue
+            for node in tree.body:
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): continue
+                for decorator in node.decorator_list:
+                    if not isinstance(decorator, ast.Call) or not isinstance(decorator.func, ast.Attribute): continue
+                    if decorator.func.attr.lower() not in {"get", "post", "put", "patch", "delete", "options"}: continue
+                    route = decorator.args[0].value if decorator.args and isinstance(decorator.args[0], ast.Constant) else None
+                    if not isinstance(route, str): continue
+                    method = decorator.func.attr.upper(); name = f"{method} {route}"
+                    evidence = [Evidence("code", relative, "Decorador de ruta FastAPI", "CONFIRMED", 1.0, line=node.lineno, symbol=node.name).as_dict()]
+                    handler = f"{relative.removesuffix('.py').replace('/', '.')}.{node.name}"
+                    entries.append(EntryPoint("HTTP", name, handler, "HTTP", method, route, relative, node.lineno, "FastAPI", "CONFIRMED", evidence))
+                    transitions.append(ExecutionTransition(name, handler, "HTTP_ENTRY", relative, node.lineno, "CONFIRMED", "fastapi", evidence))
+        return SemanticModel("Python", "FastAPI", "FRAMEWORK", components, entries, transitions)