mcp-efficiency-engine 0.1.0 → 0.1.2

package/scripts/wiki/compiler_main.py

@@ -1,9 +1,16 @@
 import json
 import os
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List
 
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from telemetry import build_telemetry_collector
+
 from orchestrator.wiki.graph_consolidator import GraphConsolidator
 from orchestrator.wiki.incremental_engine import IncrementalEngine
 from orchestrator.wiki.plugin_manager import PluginManager
@@ -106,82 +113,107 @@ def _write_routing_event(
 def main() -> int:
     start = datetime.now(timezone.utc)
     env_snapshot = _read_session_env()
-
-    manager = PluginManager()
-    include_external = str(os.getenv("AUTODOCS_INCLUDE_EXTERNAL_PROVIDERS", "")).strip().lower() in {
-        "1",
-        "true",
-        "yes",
-        "on",
-    }
-
-    # Keep CI output deterministic: external providers depend on local intake artifacts that
-    # may not exist on clean runners.
-    if include_external:
-        manager.register_provider(CodeGraphProvider(REPO_ROOT / "repo-intake" / "generated"))
-        manager.register_provider(GraphifyProvider(REPO_ROOT / "repo-intake" / "generated"))
-
-    manager.register_provider(RepoContentProvider(REPO_ROOT))
-
-    provider_result = manager.gather_all()
-    contracts = provider_result.get("contracts", [])
-    provider_errors = provider_result.get("errors", [])
-
-    consolidator = GraphConsolidator(
-        output_graph_path=UNIFIED_GRAPH_PATH,
-        markdown_output_dir=MARKDOWN_OUTPUT_DIR,
-    )
-    unified_graph = consolidator.consolidate(contracts)
-    wiki_nodes = unified_graph.get("wiki_nodes", {})
-
-    incremental_engine = IncrementalEngine(UNIFIED_GRAPH_PATH)
-    diff = incremental_engine.diff(wiki_nodes)
-    dirty_nodes = diff.get("dirty_nodes", {})
-    deleted_nodes = diff.get("deleted_nodes", [])
-    cached_nodes = diff.get("cached_graph", {}).get("nodes", {})
-
-    validator = WikiValidator(SCHEMA_PATH)
-    validation_report = validator.validate(wiki_nodes)
-    validator.write_reports(
-        json_path=VALIDATION_REPORT_JSON,
-        markdown_path=VALIDATION_REPORT_MD,
-        report=validation_report,
-    )
-
-    project_stats = consolidator.project_dirty_nodes(
-        dirty_nodes=dirty_nodes,
-        deleted_nodes=deleted_nodes,
-        all_nodes=wiki_nodes,
-        cached_nodes=cached_nodes,
-    )
-    consolidator.persist_graph(unified_graph)
-    consolidator.persist_manifests(unified_graph)
-
-    elapsed_ms = int((datetime.now(timezone.utc) - start).total_seconds() * 1000)
-    iteration_event: Dict[str, Any] = {
-        "timestamp": datetime.now(timezone.utc).isoformat(),
-        "source_type": "technical-docs",
-        "module": "autodocs",
-        "total_nodes": len(wiki_nodes),
-        "dirty_nodes": len(dirty_nodes),
-        "deleted_nodes": len(deleted_nodes),
-        "rendered_markdown": int(project_stats.get("rendered", 0)),
-        "deleted_markdown": int(project_stats.get("deleted", 0)),
-        "rendered_indexes": int(project_stats.get("indexes", 0)),
-        "rendered_manifests": int(project_stats.get("manifests", 0)),
-        "provider_errors": len(provider_errors),
-        "validation_errors": int(validation_report.get("summary", {}).get("error_count", 0)),
-        "validation_warnings": int(validation_report.get("summary", {}).get("warning_count", 0)),
-        "elapsed_ms": elapsed_ms,
-    }
-    _append_jsonl(ITERATION_LOG, iteration_event)
-    _write_routing_event(
-        env_snapshot=env_snapshot,
-        dirty_count=len(dirty_nodes),
-        total_nodes=len(wiki_nodes),
-        errors=provider_errors,
-        elapsed_ms=elapsed_ms,
-    )
+    collector = build_telemetry_collector(REPO_ROOT)
+
+    with collector.start_execution(operation="autodocs-compiler", session_id="autodocs"):
+        collector.record_event("ExecutionStarted", {"pipeline": "autodocs", "env_keys": sorted(env_snapshot.keys())})
+
+        manager = PluginManager(telemetry_collector=collector)
+        include_external = str(os.getenv("AUTODOCS_INCLUDE_EXTERNAL_PROVIDERS", "")).strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
+
+        # Keep CI output deterministic: external providers depend on local intake artifacts that
+        # may not exist on clean runners.
+        if include_external:
+            manager.register_provider(CodeGraphProvider(REPO_ROOT / "repo-intake" / "generated"))
+            manager.register_provider(GraphifyProvider(REPO_ROOT / "repo-intake" / "generated"))
+
+        manager.register_provider(RepoContentProvider(REPO_ROOT))
+
+        with collector.start_span(name="autodocs.providers", kind="INTERNAL"):
+            provider_result = manager.gather_all()
+            contracts = provider_result.get("contracts", [])
+            provider_errors = provider_result.get("errors", [])
+            collector.record_metric("provider_calls", float(len(contracts) + len(provider_errors)), unit="count")
+
+        consolidator = GraphConsolidator(
+            output_graph_path=UNIFIED_GRAPH_PATH,
+            markdown_output_dir=MARKDOWN_OUTPUT_DIR,
+            telemetry_collector=collector,
+        )
+        with collector.start_span(name="autodocs.consolidate", kind="INTERNAL"):
+            unified_graph = consolidator.consolidate(contracts)
+            wiki_nodes = unified_graph.get("wiki_nodes", {})
+
+        incremental_engine = IncrementalEngine(UNIFIED_GRAPH_PATH, telemetry_collector=collector)
+        with collector.start_span(name="autodocs.incremental", kind="INTERNAL"):
+            diff = incremental_engine.diff(wiki_nodes)
+            dirty_nodes = diff.get("dirty_nodes", {})
+            deleted_nodes = diff.get("deleted_nodes", [])
+            cached_nodes = diff.get("cached_graph", {}).get("nodes", {})
+
+        validator = WikiValidator(SCHEMA_PATH, telemetry_collector=collector)
+        with collector.start_span(name="autodocs.validate", kind="INTERNAL"):
+            validation_report = validator.validate(wiki_nodes)
+            validator.write_reports(
+                json_path=VALIDATION_REPORT_JSON,
+                markdown_path=VALIDATION_REPORT_MD,
+                report=validation_report,
+            )
+
+        with collector.start_span(name="autodocs.project", kind="INTERNAL"):
+            project_stats = consolidator.project_dirty_nodes(
+                dirty_nodes=dirty_nodes,
+                deleted_nodes=deleted_nodes,
+                all_nodes=wiki_nodes,
+                cached_nodes=cached_nodes,
+            )
+            consolidator.persist_graph(unified_graph)
+            consolidator.persist_manifests(unified_graph)
+
+        elapsed_ms = int((datetime.now(timezone.utc) - start).total_seconds() * 1000)
+        iteration_event: Dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "source_type": "technical-docs",
+            "module": "autodocs",
+            "total_nodes": len(wiki_nodes),
+            "dirty_nodes": len(dirty_nodes),
+            "deleted_nodes": len(deleted_nodes),
+            "rendered_markdown": int(project_stats.get("rendered", 0)),
+            "deleted_markdown": int(project_stats.get("deleted", 0)),
+            "rendered_indexes": int(project_stats.get("indexes", 0)),
+            "rendered_manifests": int(project_stats.get("manifests", 0)),
+            "provider_errors": len(provider_errors),
+            "validation_errors": int(validation_report.get("summary", {}).get("error_count", 0)),
+            "validation_warnings": int(validation_report.get("summary", {}).get("warning_count", 0)),
+            "elapsed_ms": elapsed_ms,
+        }
+        _append_jsonl(ITERATION_LOG, iteration_event)
+        _write_routing_event(
+            env_snapshot=env_snapshot,
+            dirty_count=len(dirty_nodes),
+            total_nodes=len(wiki_nodes),
+            errors=provider_errors,
+            elapsed_ms=elapsed_ms,
+        )
+
+        collector.record_metric("execution_time_ms", float(elapsed_ms), unit="ms")
+        collector.record_metric("warning_count", float(len(provider_errors)), unit="count")
+        collector.record_event(
+            "KnowledgeGenerated",
+            {
+                "total_nodes": len(wiki_nodes),
+                "dirty_nodes": len(dirty_nodes),
+                "deleted_nodes": len(deleted_nodes),
+                "elapsed_ms": elapsed_ms,
+            },
+        )
+
+    collector.shutdown()
 
     if int(validation_report.get("summary", {}).get("error_count", 0)) > 0:
         return 1

package/scripts/wiki/providers/repo_content_provider.py

@@ -14,6 +14,7 @@ class RepoContentProvider(BaseWikiProvider):
 
     def gather_knowledge(self) -> Dict[str, Any]:
         entities: List[Dict[str, Any]] = []
+        entities.extend(self._collect_core_docs())
         entities.extend(self._collect_agents())
         entities.extend(self._collect_skills())
         entities.extend(self._collect_policies())
@@ -25,6 +26,42 @@ class RepoContentProvider(BaseWikiProvider):
         self._enrich_relations(entities)
         return {"provider_id": self.provider_id, "entities": entities}
 
+    def _collect_core_docs(self) -> List[Dict[str, Any]]:
+        targets: List[Tuple[Path, str]] = [
+            (self.repo_root / "README.md", "Guia principal del engine y sus flujos operativos."),
+            (self.repo_root / "README_WIKI.md", "Guia de uso y alcance de la wiki AutoDocs del repositorio."),
+            (self.repo_root / "FINAL_USAGE_GUIDE.md", "Guia de uso final con pasos operativos y buenas practicas."),
+            (self.repo_root / "FILE_INDEX.md", "Indice del contenido y estructura del repositorio."),
+            (self.repo_root / "autodocs" / "README.md", "Referencia de ejecucion y artefactos de AutoDocs."),
+        ]
+
+        entities: List[Dict[str, Any]] = []
+        for path, fallback_summary in targets:
+            if not path.exists():
+                continue
+            entities.append(
+                self._entity_from_markdown(
+                    path,
+                    kind="report",
+                    section="reports",
+                    domain="documentation",
+                    fallback_summary=fallback_summary,
+                )
+            )
+
+        package_json = self.repo_root / "package.json"
+        if package_json.exists():
+            entities.append(
+                self._entity_from_json(
+                    package_json,
+                    kind="report",
+                    section="reports",
+                    domain="packaging",
+                )
+            )
+
+        return entities
+
     def _collect_agents(self) -> List[Dict[str, Any]]:
         agents_dir = self.repo_root / ".github" / "agents"
         if not agents_dir.exists():
@@ -292,6 +329,18 @@ class RepoContentProvider(BaseWikiProvider):
             for target_id in ["AGENTS.md", "orchestrator/router.md"]:
                 if target_id in entities_by_id:
                     self._add_relation(entity, target_id, "explains")
+        if source_ref == "README.md":
+            for target_id in ["AGENTS.md", "ARCHITECTURE.md", "FINAL_USAGE_GUIDE.md", "package.json"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "documents")
+        if source_ref == "FINAL_USAGE_GUIDE.md":
+            for target_id in ["README.md", "scripts/README.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "extends")
+        if source_ref == "autodocs/README.md":
+            for target_id in ["README_WIKI.md", "scripts/wiki/wiki_compiler.py"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "documents")
         if source_ref == "autodocs/analysis_mcpee/OPENWIKI_INTERNAL_BLUEPRINT.md":
             for target_id in ["autodocs/README.md", "README_WIKI.md"]:
                 if target_id in entities_by_id:
@@ -364,6 +413,8 @@ class RepoContentProvider(BaseWikiProvider):
         stem = path.name
         if path.name.lower() == "skill.md" and path.parent.name:
             stem = path.parent.name
+        elif path.stem.lower() == "readme" and path.parent != self.repo_root:
+            stem = f"{path.parent.name}-{path.name}"
         tokens = [kind, stem]
         if kind == "report" and "analysis_mcpee" in relative:
             tokens.insert(1, "autodocs")

package/scripts/wiki/validator.py

@@ -4,10 +4,11 @@ from pathlib import Path
 from typing import Any, Dict, List
 
 from scripts.wiki.normalizer import section_catalog
+from telemetry import build_telemetry_collector
 
 
 class WikiValidator:
-    def __init__(self, schema_path: Path) -> None:
+    def __init__(self, schema_path: Path, telemetry_collector: Any | None = None) -> None:
         self.schema_path = schema_path
         self.allowed_sections = {section["id"] for section in section_catalog()}
         self.allowed_kinds = {
@@ -20,27 +21,51 @@ class WikiValidator:
             "report",
             "capability",
         }
+        self._telemetry = telemetry_collector
+
+    def _collector(self) -> Any:
+        if self._telemetry is None:
+            repo_root = Path(__file__).resolve().parents[2]
+            self._telemetry = build_telemetry_collector(repo_root)
+        return self._telemetry
 
     def validate(self, wiki_nodes: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
+        collector = self._collector()
         errors: List[Dict[str, Any]] = []
         warnings: List[Dict[str, Any]] = []
         info: List[Dict[str, Any]] = []
         slug_registry: Dict[str, str] = {}
 
-        if not self.schema_path.exists():
-            warnings.append(self._issue("schema", "schema_missing", "Schema file not found", "warning"))
-
-        for node_key, node in wiki_nodes.items():
-            self._validate_required(node_key, node, errors)
-            self._validate_kind(node_key, node, errors)
-            self._validate_section(node_key, node, errors)
-            self._validate_slug(node_key, node, slug_registry, errors)
-            self._validate_sources(node_key, node, warnings)
-            self._validate_summary(node_key, node, warnings)
-            self._validate_relations(node_key, node, wiki_nodes, errors)
-
-        quality_score = self._quality_score(total=len(wiki_nodes), errors=len(errors), warnings=len(warnings))
-        info.append(self._issue("summary", "quality_score", f"quality_score={quality_score}", "info"))
+        with collector.start_execution(operation="wiki-validator", session_id="autodocs"):
+            with collector.start_span(name="wiki.validate", kind="INTERNAL", attributes={"node_count": len(wiki_nodes)}):
+                if not self.schema_path.exists():
+                    warnings.append(self._issue("schema", "schema_missing", "Schema file not found", "warning"))
+                    collector.record_event("WarningGenerated", {"warning": "schema_missing", "schema_path": str(self.schema_path)}, level="WARNING")
+
+                for node_key, node in wiki_nodes.items():
+                    self._validate_required(node_key, node, errors)
+                    self._validate_kind(node_key, node, errors)
+                    self._validate_section(node_key, node, errors)
+                    self._validate_slug(node_key, node, slug_registry, errors)
+                    self._validate_sources(node_key, node, warnings)
+                    self._validate_summary(node_key, node, warnings)
+                    self._validate_relations(node_key, node, wiki_nodes, errors)
+
+                quality_score = self._quality_score(total=len(wiki_nodes), errors=len(errors), warnings=len(warnings))
+                info.append(self._issue("summary", "quality_score", f"quality_score={quality_score}", "info"))
+
+                collector.record_metric("warning_count", float(len(warnings)), unit="count")
+                collector.record_metric("error_count", float(len(errors)), unit="count")
+                collector.record_metric("quality_score", float(quality_score), unit="score")
+                collector.record_event(
+                    "MetricCalculated",
+                    {
+                        "node_count": len(wiki_nodes),
+                        "error_count": len(errors),
+                        "warning_count": len(warnings),
+                        "quality_score": quality_score,
+                    },
+                )
 
         signature = hashlib.sha256(
             json.dumps(wiki_nodes, sort_keys=True, ensure_ascii=True, separators=(",", ":")).encode("utf-8")

package/telemetry/__init__.py

@@ -0,0 +1,4 @@
+from .bootstrap import build_telemetry_collector
+from .collector.engine import TelemetryCollector
+
+__all__ = ["TelemetryCollector", "build_telemetry_collector"]

package/telemetry/bootstrap.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from telemetry.collector.engine import TelemetryCollector
+from telemetry.config import load_config
+from telemetry.exporters.console.exporter import ConsoleExporter
+from telemetry.exporters.json.exporter import JsonExporter
+from telemetry.exporters.langsmith.exporter import LangSmithExporter
+
+
+def build_telemetry_collector(repo_root: Path) -> TelemetryCollector:
+    cfg = load_config(repo_root)
+    exporters: list[object] = []
+
+    # Console exporter is always available in runtime.
+    if "console" in cfg.exporters:
+        exporters.append(ConsoleExporter())
+    elif not cfg.exporters:
+        exporters.append(ConsoleExporter())
+
+    if "json" in cfg.exporters:
+        exporters.append(JsonExporter((repo_root / cfg.telemetry_dir).resolve()))
+
+    if "langsmith" in cfg.exporters and cfg.langsmith.enabled:
+        has_langsmith_config = bool(cfg.langsmith.api_key.strip()) and bool(cfg.langsmith.project.strip())
+        if has_langsmith_config:
+            try:
+                exporters.append(
+                    LangSmithExporter(
+                        api_key=cfg.langsmith.api_key,
+                        project=cfg.langsmith.project,
+                        endpoint=cfg.langsmith.endpoint,
+                        workspace_id=cfg.langsmith.workspace_id,
+                        high_signal_only=cfg.langsmith.high_signal_only,
+                        min_span_duration_ms=cfg.langsmith.min_span_duration_ms,
+                        emit_execution_summary=cfg.langsmith.emit_execution_summary,
+                    )
+                )
+            except Exception:
+                # LangSmith is optional and must never break startup.
+                pass
+
+    if not exporters:
+        exporters.append(ConsoleExporter())
+
+    return TelemetryCollector(exporters=exporters, enabled=cfg.enabled, batch_size=cfg.batch_size)