mcp-efficiency-engine 0.1.0 → 0.1.2

package/.githooks/post-commit

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+set -eu
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+if command -v pwsh >/dev/null 2>&1; then
+  pwsh -NoProfile -ExecutionPolicy Bypass -File "$REPO_ROOT/scripts/ops/post-commit-refresh.ps1"
+  exit 0
+fi
+
+if command -v powershell >/dev/null 2>&1; then
+  powershell -NoProfile -ExecutionPolicy Bypass -File "$REPO_ROOT/scripts/ops/post-commit-refresh.ps1"
+  exit 0
+fi
+
+# No PowerShell available; skip silently to avoid blocking commits.
+exit 0

package/.github/workflows/autodocs-sync.yml

@@ -3,22 +3,8 @@ name: AutoDocs Sync
 on:
   push:
     branches: [ main, develop ]
-    paths:
-      - 'repo-intake/generated/**'
-      - 'autodocs/**'
-      - 'scripts/wiki/**'
-      - 'orchestrator/wiki/**'
-      - '.github/skills/wiki-tools.json'
-      - '.github/agents/wiki-agent.agent.md'
   pull_request:
     branches: [ main, develop ]
-    paths:
-      - 'repo-intake/generated/**'
-      - 'autodocs/**'
-      - 'scripts/wiki/**'
-      - 'orchestrator/wiki/**'
-      - '.github/skills/wiki-tools.json'
-      - '.github/agents/wiki-agent.agent.md'
   workflow_dispatch:
 
 permissions:
@@ -68,7 +54,7 @@ jobs:
           echo "- Required artifacts: autodocs/generated + autodocs/site" >> $env:GITHUB_STEP_SUMMARY
 
   autodocs-sync:
-    if: github.event_name != 'pull_request' && github.actor != 'github-actions[bot]'
+    if: github.actor != 'github-actions[bot]'
     permissions:
       contents: write
     runs-on: windows-latest
@@ -89,6 +75,7 @@ jobs:
         shell: pwsh
 
       - name: Commit projected docs and unified graph
+        if: github.event_name != 'pull_request'
         shell: pwsh
         run: |
           git config user.name "github-actions[bot]"

package/.github/workflows/release-npm.yml

@@ -0,0 +1,111 @@
+name: Release & Publish NPM
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+    inputs:
+      npm_version:
+        description: "Version especifica a publicar (ej. 0.2.0). Si se omite, se autoajusta."
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Resolve publish version
+        id: version
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          BASE_VERSION=$(node -p "require('./package.json').version")
+          REQUESTED_VERSION="${{ github.event.inputs.npm_version || '' }}"
+
+          version_exists() {
+            npm view "$PACKAGE_NAME@$1" version >/dev/null 2>&1
+          }
+
+          if [ -n "$REQUESTED_VERSION" ]; then
+            TARGET_VERSION="$REQUESTED_VERSION"
+            MODE="explicit"
+          else
+            TARGET_VERSION="$BASE_VERSION"
+            MODE="auto"
+          fi
+
+          if [ "$MODE" = "explicit" ]; then
+            if version_exists "$TARGET_VERSION"; then
+              echo "Requested version $TARGET_VERSION is already published in npm."
+              exit 1
+            fi
+          else
+            CANDIDATE="$TARGET_VERSION"
+            while version_exists "$CANDIDATE"; do
+              CANDIDATE=$(node -e "const parts = process.argv[1].split('.').map(Number); if (parts.length !== 3 || parts.some(Number.isNaN)) { process.exit(2); } parts[2] += 1; process.stdout.write(parts.join('.'));" "$CANDIDATE") || {
+                echo "Cannot auto-bump non x.y.z version: $CANDIDATE"
+                exit 1
+              }
+            done
+            TARGET_VERSION="$CANDIDATE"
+          fi
+
+          CHANGED=false
+          if [ "$TARGET_VERSION" != "$BASE_VERSION" ]; then
+            npm version "$TARGET_VERSION" --no-git-tag-version
+            CHANGED=true
+          fi
+
+          echo "version=$TARGET_VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$TARGET_VERSION" >> "$GITHUB_OUTPUT"
+          echo "changed=$CHANGED" >> "$GITHUB_OUTPUT"
+          echo "mode=$MODE" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure NPM token is configured
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "Missing NODE_AUTH_TOKEN/NPM_TOKEN secret. Configure repository secret NPM_TOKEN."
+            exit 1
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Remove Python cache artifacts from workspace
+        run: |
+          find . -type d -name "__pycache__" -prune -exec rm -rf {} +
+          find . -type f -name "*.pyc" -delete
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Sync package.json version to repository
+        if: steps.version.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json
+          git commit -m "chore(release): sync npm version to ${{ steps.version.outputs.tag }} [skip ci]"
+          git push
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          name: ${{ steps.version.outputs.tag }}
+          generate_release_notes: true

package/FINAL_USAGE_GUIDE.md

@@ -85,6 +85,84 @@ Esto significa:
 - las fuentes se conservan cuando sean obligatorias,
 - el sistema solo aumenta detalle si el usuario o el caso lo requiere.
 
+## 7. Telemetry Engine
+
+El sistema incluye un engine de telemetría desacoplado con collector único.
+
+Flujo:
+
+```txt
+Componente -> TelemetryCollector -> Pipeline -> Exporters
+```
+
+Exporters soportados:
+
+- `console` (siempre disponible)
+- `json` (persistencia local en `.telemetry/`)
+- `langsmith` (opcional, solo con configuración válida)
+
+Si un exporter falla:
+
+- se registra warning,
+- los demás exporters continúan,
+- la ejecución principal no se detiene.
+
+### Configuración rápida
+
+Archivo `telemetry/config.json`:
+
+```json
+{
+  "telemetry": {
+    "enabled": true,
+    "batch_size": 25,
+    "telemetry_dir": ".telemetry",
+    "exporters": ["console", "json", "langsmith"]
+  },
+  "langsmith": {
+    "enabled": false,
+    "api_key": "",
+    "project": "",
+    "endpoint": ""
+  }
+}
+```
+
+### Cómo activar LangSmith
+
+1. Configurar `LANGSMITH_ENABLED=true`.
+2. Definir `LANGSMITH_API_KEY` y `LANGSMITH_PROJECT`.
+3. Mantener `langsmith` en `telemetry.exporters`.
+
+Si falta configuración, se omite automáticamente.
+
+## Flujo post-commit para proyectos consumidores
+
+El install host configura hooks git locales (`core.hooksPath=.githooks`).
+
+Hook incluido:
+
+- `post-commit` -> `scripts/ops/post-commit-refresh.ps1`
+
+Regla:
+
+- Solo actua cuando el commit toca rutas bajo `projects/`.
+
+Pipeline ejecutado en ese caso:
+
+1. AutoDocs incremental (`scripts/wiki/compiler_main.py`)
+2. Refresh de reportes de learning/value (`scripts/learning/*.py`)
+3. Publicacion de snapshots KPI a LangSmith (`scripts/ops/publish-langsmith-kpis.py`)
+
+Log de ejecucion:
+
+- `observability/logs/session/post-commit-refresh-*.json`
+
+### Cómo deshabilitar exporters
+
+- Desactivar todo: `TELEMETRY_ENABLED=false`
+- Solo algunos: `TELEMETRY_EXPORTERS=console,json`
+
 ## Diagrama Visual De Uso Diario
 
 ```mermaid

package/README.md

@@ -192,6 +192,16 @@ Comportamiento esperado:
 - si no existe `repo-registry/repos.yml`, pregunta por owner/prefix y si quieres registrar un repo inicial para intake
 - si no añades repos en ese momento, deja el registry plantilla listo para añadirlos despues y rerun de intake
 
+Nota npm (entornos con politicas de scripts):
+
+- si `npm` bloquea `install`/`postinstall` (por ejemplo con `allow-scripts`), el scaffold/bootstrapping puede no ejecutarse automaticamente
+- en ese caso, aprueba scripts (`npm approve-scripts`) o ejecuta manualmente:
+
+```powershell
+npx mcp-efficiency-engine install
+npx mcp-efficiency-engine validate -PortableMode
+```
+
 Tambien puedes relanzar la instalacion manualmente sobre el proyecto actual:
 
 ```powershell
@@ -229,6 +239,32 @@ py -3 .\scripts\intake\agent-pipeline-preflight.py
 py -3 .\scripts\intake\validate-repo-registry.py --strict
 ```
 
+### Flujo automatico al hacer commit en projects/
+
+Cuando instalas el engine en un proyecto host (`mcpee install`), se configura `core.hooksPath=.githooks` con un `post-commit` que ejecuta `scripts/ops/post-commit-refresh.ps1`.
+
+Comportamiento del hook:
+
+- si el ultimo commit no toca `projects/`, no hace nada
+- si detecta cambios en `projects/`, ejecuta:
+  - `scripts/wiki/compiler_main.py` (AutoDocs incremental)
+  - `scripts/learning/learning-loop-report.py`
+  - `scripts/learning/iteration-value-report.py`
+  - `scripts/ops/publish-langsmith-kpis.py` (best effort)
+
+Artefactos/resultados:
+
+- AutoDocs actualizado en `autodocs/generated` y `autodocs/site`
+- reportes de observabilidad actualizados en `observability/evals`
+- snapshots KPI publicados a LangSmith para dashboards
+- resumen local en `observability/logs/session/post-commit-refresh-*.json`
+
+Instalacion manual de hooks (si necesitas reprovisionar):
+
+```powershell
+.\scripts\setup\install-project-hooks.ps1
+```
+
 ## Flujo De Intake
 
 `repo-intake` soporta dos modos:
@@ -245,6 +281,201 @@ Artefactos canónicos:
 
 ## Observabilidad
 
+### Telemetry Engine (desacoplado y extensible)
+
+La observabilidad ahora se soporta mediante un engine propio en `telemetry/`.
+
+Principios:
+
+- Telemetría siempre activa a nivel de modelo de datos.
+- Exporters opcionales (`console`, `json`, `langsmith`).
+- Ningún flujo de negocio depende de LangSmith.
+- Si un exporter falla, la ejecución principal continua.
+
+Arquitectura:
+
+```mermaid
+flowchart TD
+  T[Tool/Flow] --> C[TelemetryCollector]
+  C --> P[Telemetry Pipeline]
+  P --> EX1[Console Exporter]
+  P --> EX2[JSON Exporter]
+  P --> EX3[LangSmith Exporter]
+  P --> EXN[Future Exporters]
+```
+
+Trazas jerárquicas:
+
+- Cada ejecución genera `execution_id`, `trace_id`, `span_id`, `parent_span_id`.
+- Se propaga contexto con `contextvars` (sin variables globales).
+- Spans soportan `events`, `status`, `duration_ms` y error asociado.
+
+Configuración base (`telemetry/config.json`):
+
+```json
+{
+  "telemetry": {
+    "enabled": true,
+    "batch_size": 100,
+    "telemetry_dir": ".telemetry",
+    "exporters": ["console", "json"]
+  },
+  "langsmith": {
+    "enabled": false,
+    "api_key": "",
+    "project": "",
+    "endpoint": "",
+    "high_signal_only": true,
+    "min_span_duration_ms": 100,
+    "emit_execution_summary": true
+  }
+}
+```
+
+Conexión segura a LangSmith (sin subir token al repo/npm):
+
+1. No guardes el token en `telemetry/config.json`.
+2. Define variables de entorno locales (usuario o sesión).
+3. Activa exporter por entorno con `TELEMETRY_EXPORTERS=console,json,langsmith`.
+4. Verifica que `.env` y variantes están ignorados por Git y npm.
+
+Ejemplo (PowerShell, solo sesión actual):
+
+```powershell
+$env:LANGSMITH_ENABLED='true'
+$env:LANGSMITH_API_KEY='tu_token'
+$env:LANGSMITH_PROJECT='mcpee-local'
+$env:LANGSMITH_ENDPOINT='https://api.smith.langchain.com'
+$env:LANGSMITH_HIGH_SIGNAL_ONLY='true'
+$env:LANGSMITH_MIN_SPAN_DURATION_MS='100'
+$env:LANGSMITH_EMIT_EXECUTION_SUMMARY='true'
+$env:TELEMETRY_EXPORTERS='console,json,langsmith'
+```
+
+Persistente para tu usuario Windows:
+
+```powershell
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_ENABLED','true','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_API_KEY','tu_token','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_PROJECT','mcpee-local','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_ENDPOINT','https://api.smith.langchain.com','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_HIGH_SIGNAL_ONLY','true','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_MIN_SPAN_DURATION_MS','100','User')
+[System.Environment]::SetEnvironmentVariable('LANGSMITH_EMIT_EXECUTION_SUMMARY','true','User')
+[System.Environment]::SetEnvironmentVariable('TELEMETRY_EXPORTERS','console,json,langsmith','User')
+
+Modo high-signal recomendado en LangSmith:
+
+- `LANGSMITH_HIGH_SIGNAL_ONLY=true` (default): prioriza trazas útiles y reduce ruido.
+- `LANGSMITH_MIN_SPAN_DURATION_MS=100` (default): solo mantiene spans rápidos cuando fallan; los de éxito deben superar el umbral.
+- `LANGSMITH_EMIT_EXECUTION_SUMMARY=true` (default): añade un resumen consolidado por ejecución (duración, estado, warnings/errors, tokens/coste).
+- Mantiene eventos clave (`ExecutionStarted`, `ExecutionFinished`, `RoutingResolved`, warnings/errores) y resumen `UsageSummary` con modelo/tokens/coste.
+- Omite eventos de bajo valor para la UI de LangSmith, pero conserva debug detallado en exporters locales (`console`, `json`).
+```
+
+Para volver al modo local sin LangSmith:
+
+```powershell
+$env:LANGSMITH_ENABLED='false'
+$env:TELEMETRY_EXPORTERS='console,json'
+```
+
+Troubleshooting rapido: no aparecen dashboards/runs en LangSmith
+
+Importante: en LangSmith, los runs se validan primero en `Tracing` (y opcionalmente `Monitoring`). La seccion `Custom Dashboards` no se autogenera por defecto; puede aparecer vacia aunque la telemetria este funcionando correctamente.
+
+Checklist minimo (debe cumplirse todo):
+
+- `LANGSMITH_ENABLED=true`
+- `LANGSMITH_API_KEY` definido
+- `LANGSMITH_PROJECT` definido
+- `TELEMETRY_EXPORTERS=console,json,langsmith`
+- el flujo que ejecutas realmente emite telemetria (por ejemplo `hi.ps1`, intake o routing-evals)
+
+Comprobacion en PowerShell:
+
+```powershell
+Write-Host "LANGSMITH_ENABLED=$env:LANGSMITH_ENABLED"
+Write-Host "LANGSMITH_PROJECT=$env:LANGSMITH_PROJECT"
+Write-Host "TELEMETRY_EXPORTERS=$env:TELEMETRY_EXPORTERS"
+```
+
+Si `LANGSMITH_WORKSPACE_ID` no coincide con tu workspace real, los runs pueden quedar en otro workspace y "no verse" en la UI esperada.
+
+Verificacion local (aunque LangSmith falle):
+
+- revisa que se siguen generando logs en `observability/logs/` (la app no debe romperse por un fallo del exporter)
+- si hay trazas locales pero no runs remotos, el problema es de configuracion/conectividad de LangSmith y no del flujo principal
+
+### Alinear KPIs locales con LangSmith
+
+Para enviar a LangSmith los KPIs que ya calcula el engine en local (`learning-loop-report.json` e `iteration-value-report.json`) y poder construir dashboards con esa señal:
+
+```powershell
+npm run langsmith:kpis
+```
+
+Este comando publica runs de resumen con tags `mcpee`, `kpi`, `dashboard` y nombres:
+
+- `KPI::LearningLoop`
+- `KPI::IterationValue`
+- `KPI::AlignmentSnapshot`
+
+Con eso puedes filtrar en `Tracing` por `tag:kpi` y montar dashboards manuales en `Custom Dashboards` sobre esos runs.
+
+Separacion plataforma vs proyecto consumidor:
+
+- los runs KPI incluyen metadata y tags de scope automaticamente
+- metadata: `host_project`, `host_project_slug`, `telemetry_scope` (`platform` o `consumer`)
+- tags: `scope:<valor>` y `host:<slug>`
+
+Ejemplos de filtro para un dashboard de proyecto consumidor:
+
+- `Tag contains kpi`
+- `Tag contains scope:consumer`
+- `Tag contains host:<slug-del-proyecto>`
+
+Si quieres forzar nombre de proyecto host (por ejemplo en CI):
+
+```powershell
+$env:MCPEE_HOST_PROJECT='mi-proyecto-app'
+npm run langsmith:kpis
+```
+
+Variables de entorno soportadas:
+
+- `TELEMETRY_ENABLED`
+- `TELEMETRY_EXPORTERS`
+- `TELEMETRY_BATCH_SIZE`
+- `TELEMETRY_DIR`
+- `LANGSMITH_ENABLED`
+- `LANGSMITH_API_KEY`
+- `LANGSMITH_PROJECT`
+- `LANGSMITH_ENDPOINT`
+- `LANGSMITH_WORKSPACE_ID` (opcional, recomendado para cuentas con multiples workspaces)
+
+Nota: el engine carga automáticamente `.env` en la raíz del repo. Si también existe variable en el entorno del sistema/proceso, esa tiene prioridad.
+
+Dependencia runtime: `langsmith` está incluida en `requirements.txt` para que `scripts/setup/setup-prerequisites.ps1` la instale automáticamente cuando prepares el entorno Python.
+
+Cómo crear un exporter nuevo:
+
+1. Implementar contrato `export/flush/shutdown` en `telemetry/exporters/<nuevo>/exporter.py`.
+2. Registrar el exporter en `telemetry/bootstrap.py`.
+3. Añadirlo en `telemetry/config.json` o `TELEMETRY_EXPORTERS`.
+
+Si LangSmith no está configurado correctamente, el exporter se omite y el engine sigue funcionando con `console/json`.
+
+Benchmark de overhead on/off:
+
+```powershell
+py -3 .\scripts\ops\telemetry-benchmark.py --iterations 10
+```
+
+Salida:
+
+- `observability/evals/telemetry-overhead-benchmark.json`
+
 Registros principales:
 
 - `observability/logs/routing-decisions.jsonl`

package/autodocs/README.md

@@ -14,6 +14,12 @@ AutoDocs es la wiki interna nativa de `mcp-efficiency-engine`.
 py -3 -m scripts.wiki.wiki_compiler
 ```
 
+## Sincronizacion automatica
+
+- En CI, el workflow `autodocs-sync` valida en PR y sincroniza en `main`/`develop`.
+- La ejecucion ya no depende de filtros de path: cualquier cambio potencialmente relevante recompila AutoDocs.
+- Si hay drift, CI exige regenerar y commitear `autodocs/generated` y `autodocs/site`.
+
 ## Artefactos clave
 
 - `autodocs/generated/unified-graph.json`

package/bin/install-host.js

@@ -6,6 +6,7 @@ const { spawnSync } = require("node:child_process");
 
 const packageRoot = path.resolve(__dirname, "..");
 const scaffoldEntries = [
+  ".githooks",
   ".github",
   ".vscode",
   "autodocs/README.md",
@@ -260,6 +261,15 @@ function runBootstrap(targetRoot) {
   return runPowerShell(bootstrapScript, [], targetRoot);
 }
 
+function installProjectHooks(targetRoot) {
+  const hookScript = path.join(targetRoot, "scripts", "setup", "install-project-hooks.ps1");
+  if (!fs.existsSync(hookScript)) {
+    return 0;
+  }
+
+  return runPowerShell(hookScript, [], targetRoot);
+}
+
 function runHostInstall(rawOptions) {
   const options = rawOptions;
   const targetRoot = normalizePath(options.targetDir);
@@ -284,6 +294,11 @@ function runHostInstall(rawOptions) {
       return initStatus;
     }
 
+    const hookStatus = installProjectHooks(targetRoot);
+    if (hookStatus !== 0) {
+      return hookStatus;
+    }
+
     process.stdout.write("[mcpee] Bootstrap omitido. Puedes ejecutar .\\scripts\\bootstrap-portable.cmd mas tarde.\n");
     return 0;
   }
@@ -294,11 +309,21 @@ function runHostInstall(rawOptions) {
       return initStatus;
     }
 
+    const hookStatus = installProjectHooks(targetRoot);
+    if (hookStatus !== 0) {
+      return hookStatus;
+    }
+
     process.stdout.write("[mcpee] Modo no interactivo detectado. Se inicializo el registry plantilla y se omitio bootstrap interactivo.\n");
     return 0;
   }
 
-  return runBootstrap(targetRoot);
+  const bootstrapStatus = runBootstrap(targetRoot);
+  if (bootstrapStatus !== 0) {
+    return bootstrapStatus;
+  }
+
+  return installProjectHooks(targetRoot);
 }
 
 function runHostInstallFromCli(argv = process.argv.slice(2)) {

package/observability/metrics.md

@@ -28,6 +28,39 @@ Métricas: routing accuracy, tool usage, tool misuse, tool switching, grounding
 - token_efficiency: tendencia estable o mejorando
 - caveman_effectiveness: `>= 85%`
 
+## Telemetry Engine native metrics
+
+El engine expone métricas propias y no depende de proveedores externos:
+
+- execution_time_ms
+- tool_duration_ms
+- average_duration_ms
+- parallel_tasks
+- sequential_tasks
+- retry_count
+- error_count
+- warning_count
+- llm_calls
+- provider_calls
+- mcp_calls
+- tool_invocations
+- tokens_input
+- tokens_output
+- total_tokens
+- estimated_cost
+- cache_hits
+- cache_misses
+- compression_ratio
+- parallel_efficiency
+- prompt_reduction
+- context_reduction
+- efficiency_score (0-100)
+
+Los cálculos viven en:
+
+- `telemetry/metrics/aggregator.py`
+- `telemetry/scoring/efficiency.py`
+
 ## Semaforo
 
 - `OK`: todos los umbrales en rango.

package/observability/scoring-rubric.md

@@ -1,5 +1,7 @@
 # Scoring Rubric
 
+> El score de eficiencia es nativo del Telemetry Engine y no depende de LangSmith.
+
 ## Componentes y pesos
 
 - Routing score: 40%
@@ -36,3 +38,21 @@
 - `80-89`: Aceptable
 - `70-79`: Mejorable
 - `< 70`: No apto
+
+## Efficiency Score (Telemetry Engine)
+
+Salida: `0..100`.
+
+Factores por defecto:
+
+- time
+- cost
+- tokens
+- cache
+- parallelism
+- reuse
+- calls
+- compression
+
+Implementación base en `telemetry/scoring/efficiency.py`.
+Los pesos son configurables y el algoritmo se puede ajustar sin tocar exporters.