genoma-evolution 1.0.0

package/.claude/worktrees/phase-2-mcp/.brv/review-backups/docs/api/hermes_api_openapi_specification.md

@@ -0,0 +1,468 @@
+---
+title: Hermes API OpenAPI Specification
+summary: OpenAPI 3.0 specification for Hermes dashboard backend API with ~20 endpoints
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T03:39:56.018Z'
+updatedAt: '2026-04-28T03:39:56.018Z'
+---
+## Reason
+Preserving complete API specification with all endpoints, schemas, and examples
+
+## Raw Concept
+**Task:**
+API specification for Hermes dashboard backend
+
+**Files:**
+- docs/api/hermes-api.openapi.yaml
+
+**Timestamp:** 2026-04-28T03:39:56.017Z
+
+## Narrative
+### Structure
+OpenAPI 3.0 specification defining REST endpoints for the Hermes agent self-evolution dashboard
+
+---
+
+
+openapi: "3.1.0"
+info:
+  title: Hermes Agent API
+  description: |
+    API del backend de Hermes (FastAPI/Python) expuesta por el gateway de hermes-cli.
+    El frontend Next.js consume estos endpoints y espera este contrato de respuesta.
+  version: "1.0.0"
+  contact:
+    name: Hermes Dashboard
+
+servers:
+  - url: "http://127.0.0.1:8000"
+    description: Backend local (default). NEXT_PUBLIC_API_BASE sobreescribe esta URL.
+
+paths:
+  ## ── Skills ──────────────────────────────────────────────────────────
+  /api/skills:
+    get:
+      operationId: listSkills
+      summary: Listar todos los skills instalados
+      description: Retorna la lista completa de skills detectados en los directorios configurados.
+      responses:
+        "200":
+          description: Lista de skills
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/SkillInfo"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/skills/{name}:
+    get:
+      operationId: getSkill
+      summary: Obtener detalle de un skill
+      description: Retorna el contenido completo de un skill incluyendo frontmatter y body.
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Detalle del skill
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SkillDetail"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/skills/{name}/evolution-history:
+    get:
+      operationId: getSkillHistory
+      summary: Historial de evolución de un skill
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Lista de ejecuciones de evolución para este skill
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionRun"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Evolution ───────────────────────────────────────────────────────
+  /api/evolution/runs:
+    get:
+      operationId: listEvolutionRuns
+      summary: Listar todas las ejecuciones de evolución
+      description: Retorna el historial completo de ejecuciones de evolución.
+      responses:
+        "200":
+          description: Lista de runs de evolución
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionRun"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/evolution/start:
+    post:
+      operationId: startEvolution
+      summary: Iniciar una evolución
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [skill_name, iterations]
+              properties:
+                skill_name:
+                  type: string
+                  description: Nombre del skill a evolucionar
+                iterations:
+                  type: integer
+                  minimum: 1
+                  maximum: 20
+                  default: 3
+                eval_source:
+                  type: string
+                  default: synthetic
+      responses:
+        "200":
+          description: Job de evolución creado
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                  skill:
+                    type: string
+                  status:
+                    type: string
+                  error:
+                    type: string
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Jobs ───────────────────────────────────────────────────────────
+  /api/jobs:
+    get:
+      operationId: listJobs
+      summary: Listar jobs activos o todos
+      parameters:
+        - name: active_only
+          in: query
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: Lista de jobs
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/EvolutionJob"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/jobs/{jobId}:
+    get:
+      operationId: getJob
+      summary: Obtener detalle de un job
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Detalle del job
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionJob"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    delete:
+      operationId: cancelJob
+      summary: Cancelar un job activo
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Job cancelado
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /api/jobs/{jobId}/logs:
+    get:
+      operationId: getJobLogs
+      summary: Obtener logs de un job
+      parameters:
+        - name: jobId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: since
+          in: query
+          schema:
+            type: integer
+            default: 0
+      responses:
+        "200":
+          description: Logs del job (streaming paginado)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  job_id:
+                    type: string
+                  total_lines:
+                    type: integer
+                  logs:
+                    type: array
+                    items:
+                      type: string
+                  status:
+                    type: string
+                  progress:
+                    type: number
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  ## ── Health ─────────────────────────────────────────────────────────
+  /api/health:
+    get:
+      operationId: healthCheck
+      summary: Health check del backend
+      responses:
+        "200":
+          description: Estado del sistema
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  hermes_repo:
+                    type: string
+                  hermes_repo_exists:
+                    type: boolean
+                  evolution_dir:
+                    type: string
+                  evolution_dir_exists:
+                    type: boolean
+                  skills_count:
+                    type: integer
+                  categories:
+                    type: object
+                    additionalProperties:
+                      type: integer
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+## ── Componentes ─────────────────────────────────────────────────────
+components:
+  schemas:
+    SkillInfo:
+      type: object
+      required: [name, path, description, size, last_modified, providers, provider_count, category]
+      properties:
+        name:
+          type: string
+          example: accessibility
+        path:
+          type: string
+          example: /home/user/.agents/skills/accessibility
+        description:
+          type: string
+        size:
+          type: number
+        last_modified:
+          type: string
+          format: date-time
+        providers:
+          type: array
+          items:
+            type: string
+        provider_count:
+          type: integer
+        category:
+          type: string
+
+    SkillDetail:
+      type: object
+      required: [name, path, frontmatter, body, raw, size]
+      properties:
+        name:
+          type: string
+        path:
+          type: string
+        frontmatter:
+          type: object
+          additionalProperties: true
+          description: YAML frontmatter parseado
+        body:
+          type: string
+          description: Contenido Markdown sin frontmatter
+        raw:
+          type: string
+          description: Archivo completo sin procesar
+        size:
+          type: number
+
+    EvolutionRun:
+      type: object
+      required:
+        [skill_name, timestamp, baseline_score, evolved_score, improvement,
+         elapsed_seconds, constraints_passed, iterations, optimizer_model]
+      properties:
+        skill_name:
+          type: string
+        timestamp:
+          type: string
+        baseline_score:
+          type: number
+          description: Score pre-evolución (0-1)
+        evolved_score:
+          type: number
+          description: Score post-evolución (0-1)
+        improvement:
+          type: number
+          description: Diferencia (positivo = mejoró)
+        elapsed_seconds:
+          type: number
+        constraints_passed:
+          type: boolean
+        iterations:
+          type: integer
+        optimizer_model:
+          type: string
+
+    EvolutionJob:
+      type: object
+      properties:
+        id:
+          type: string
+        skill_name:
+          type: string
+        status:
+          type: string
+          enum:
+            [queued, loading_skill, building_dataset, validating,
+             configuring, optimizing, evaluating, saving, completed, failed]
+        iterations:
+          type: integer
+        current_iteration:
+          type: integer
+        pid:
+          type: integer
+          nullable: true
+        started_at:
+          type: string
+        completed_at:
+          type: string
+        baseline_score:
+          type: number
+          nullable: true
+        current_best_score:
+          type: number
+          nullable: true
+        evolved_score:
+          type: number
+          nullable: true
+        improvement:
+          type: number
+          nullable: true
+        error:
+          type: string
+        progress:
+          type: number
+        logs:
+          type: array
+          items:
+            type: string
+
+    ## ── Error tipado ─────────────────────────────────────────────────
+    ApiError:
+      type: object
+      description: |
+        Contrato de error que el frontend debe interpretar.
+        Cualquier respuesta != 2xx o error de red se mapea a esta estructura.
+      required: [kind, message]
+      properties:
+        kind:
+          type: string
+          enum: [network, timeout, server, client]
+          description: |
+            network  → fetch() rechazó (servicio no alcanzable)
+            timeout  → AbortController superó el límite
+            server   → HTTP 5xx
+            client   → HTTP 4xx
+        message:
+          type: string
+          description: Texto legible para UI
+        status:
+          type: integer
+          description: Código HTTP (solo en server y client)
+        endpoint:
+          type: string
+          description: Ruta que falló (para diagnóstico)
+
+    ## ── Health fallback ──────────────────────────────────────────────
+    HealthStatus:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [ok, disconnected]
+        lastSeen:
+          type: string
+          format: date-time
+          description: Última vez que /api/health respondió 200
+
+  ## ── Respuesta 503 estandarizada ───────────────────────────────────
+  responses:
+    ServiceUnavailable:
+      description: >
+        El backend no está alcanzable. El frontend debe interpretar esto como señal
+        para mostrar estado "Desconectado" con opción de reintento.
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ApiError"
+          example:
+            kind: network
+            message: "El servicio de Hermes no está disponible"
+            endpoint: "/api/skills"
+
+    

package/.claude/worktrees/phase-2-mcp/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pkill -f \"uvicorn backend.main\")",
+      "Bash(pip search *)",
+      "Bash(pip index *)",
+      "Bash(curl -s https://pypi.org/pypi/mcp/json)",
+      "Bash(python3 -c \"import sys, json; data=json.load\\(sys.stdin\\); print\\('Package:', data['info']['name']\\); print\\('Latest:', data['info']['version']\\); print\\('Summary:', data['info']['summary']\\)\")",
+      "Bash(pip install *)",
+      "Bash(python3 -c \"import mcp; print\\(dir\\(mcp\\)\\)\")"
+    ]
+  }
+}