genoma-evolution 1.0.0

package/.brv/context-tree/frontend/src/lib/api_client_library.md

@@ -0,0 +1,403 @@
+---
+title: API Client Library
+summary: TypeScript API client with typed functions for jobs, skills, evolution, and WebSocket connection management
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T03:46:41.151Z'
+updatedAt: '2026-04-28T03:46:41.151Z'
+---
+## Reason
+Preserving complete frontend API client with typed endpoints
+
+## Raw Concept
+**Task:**
+Document frontend API client library
+
+**Files:**
+- src/lib/api.ts
+
+**Timestamp:** 2026-04-28
+
+## Narrative
+### Structure
+React Query-based API client with typed endpoints, WebSocket hooks, and API configuration
+
+---
+
+
+// ── Infrastructure: Resilient API client ──────────────────────────────
+//
+// Contract  → docs/api/hermes-api.openapi.yaml
+// Design    → AbortController timeouts, typed errors, network detection
+// Auth      → Hermes session-token (X-Hermes-Session-Token), auto-refresh on 401
+// Fallback  → 127.0.0.1 (evita resolución DNS rota en tiling WMs/Linux)
+// Env       → NEXT_PUBLIC_API_BASE (sin trailing slash)
+
+// ── Env resolution ───────────────────────────────────────────────────
+function resolveBase(): string {
+  if (typeof window !== "undefined") {
+    // Client-side: NEXT_PUBLIC_ variables están expuestas
+    const env = process.env as Record<string, string | undefined>;
+    // Soporta ambas variables: NEXT_PUBLIC_API_BASE (nuevo estándar) y NEXT_PUBLIC_API_URL (legacy)
+    const fromEnv = env.NEXT_PUBLIC_API_BASE ?? env.NEXT_PUBLIC_API_URL;
+    if (fromEnv) return fromEnv.replace(/\/+$/, "");
+  }
+  // Fallback: 127.0.0.1 en vez de localhost para evitar problemas DNS. Puerto 9119 = default de Hermes web.
+  return "http://127.0.0.1:9119";
+}
+
+const API_BASE = resolveBase();
+
+// ── Session token (Hermes auth) ──────────────────────────────────────
+let _sessionToken: string | null = null;
+let _tokenPromise: Promise<string | null> | null = null;
+
+async function fetchSessionToken(): Promise<string | null> {
+  try {
+    const html = await fetch(`${API_BASE}/`, {
+      signal: AbortSignal.timeout(5_000),
+    }).then((r) => r.text());
+    const match = html.match(/__HERMES_SESSION_TOKEN__\s*=\s*"([^"]+)"/);
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function getSessionToken(): Promise<string | null> {
+  if (_sessionToken) return _sessionToken;
+  if (!_tokenPromise) {
+    _tokenPromise = fetchSessionToken().then((token) => {
+      _sessionToken = token;
+      _tokenPromise = null;
+      return token;
+    });
+  }
+  return _tokenPromise;
+}
+
+function invalidateToken(): void {
+  _sessionToken = null;
+  _tokenPromise = null;
+}
+
+// ── Defaults ─────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+// ── Typed errors (contract: ApiError schema) ─────────────────────────
+export type ErrorKind = "network" | "timeout" | "server" | "client";
+
+export class ApiError extends Error {
+  readonly kind: ErrorKind;
+  readonly status?: number;
+  readonly endpoint: string;
+
+  constructor(kind: ErrorKind, message: string, endpoint: string, status?: number) {
+    super(message);
+    this.name = "ApiError";
+    this.kind = kind;
+    this.status = status;
+    this.endpoint = endpoint;
+  }
+}
+
+/** Type guard para distinguir errores de API de excepciones genéricas */
+export function isApiError(err: unknown): err is ApiError {
+  return err instanceof ApiError;
+}
+
+// ── Core fetch wrapper ───────────────────────────────────────────────
+interface ApiOptions extends Omit<RequestInit, "signal"> {
+  /** Timeout en ms. Default 15s. 0 = sin timeout. */
+  timeout?: number;
+}
+
+async function executeRequest<T>(
+  path: string,
+  init: RequestInit & { timeout?: number },
+): Promise<T> {
+  const url = `${API_BASE}${path}`;
+  const controller = new AbortController();
+  const timer =
+    init.timeout && init.timeout > 0
+      ? setTimeout(() => controller.abort(), init.timeout)
+      : null;
+  const signal = controller.signal;
+
+  try {
+    const res = await fetch(url, { ...init, signal });
+
+    if (timer) clearTimeout(timer);
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => res.statusText);
+      const kind: ErrorKind = res.status >= 500 ? "server" : "client";
+      throw new ApiError(kind, `HTTP ${res.status}: ${body.slice(0, 200)}`, path, res.status);
+    }
+
+    return res.json() as T;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export async function api<T>(path: string, options?: ApiOptions): Promise<T> {
+  const { timeout = DEFAULT_TIMEOUT_MS, ...init } = options ?? {};
+  const token = await getSessionToken();
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(token ? { "X-Hermes-Session-Token": token } : {}),
+    ...((init.headers as Record<string, string>) ?? {}),
+  };
+
+  try {
+    return await executeRequest<T>(path, { ...init, headers, timeout });
+  } catch (err: unknown) {
+    // Auto-refresh token on 401 and retry once
+    if (err instanceof ApiError && err.status === 401) {
+      invalidateToken();
+      const freshToken = await getSessionToken();
+      if (freshToken) {
+        headers["X-Hermes-Session-Token"] = freshToken;
+        return executeRequest<T>(path, { ...init, headers, timeout });
+      }
+    }
+
+    // Re-lanzar errores ya tipados
+    if (err instanceof ApiError) throw err;
+
+    // AbortController / timeout
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new ApiError("timeout", `Request to ${path} timed out after ${timeout}ms`, path);
+    }
+
+    // TypeError (network unreachable, CORS, DNS)
+    if (err instanceof TypeError) {
+      throw new ApiError("network", `Cannot reach ${API_BASE} — ${err.message}`, path);
+    }
+
+    // Fallback
+    throw new ApiError("network", err instanceof Error ? err.message : "Unknown fetch error", path);
+  }
+}
+
+// ── WebSocket helper ─────────────────────────────────────────────────
+let _wsToken: string | null = null;
+
+export async function wsConnect(onMessage: (data: unknown) => void): Promise<WebSocket> {
+  // Lazy-load token
+  if (!_wsToken) {
+    _wsToken = await getSessionToken();
+  }
+  const tokenQs = _wsToken ? `?token=${encodeURIComponent(_wsToken)}` : "";
+  const wsUrl = API_BASE.replace(/^http/, "ws") + "/ws/stream" + tokenQs;
+  const ws = new WebSocket(wsUrl);
+
+  ws.onmessage = (event) => {
+    try {
+      onMessage(JSON.parse(event.data));
+    } catch {
+      // ignore parse errors
+    }
+  };
+
+  ws.onclose = () => {
+    // Auto-reconnect after 3s
+    setTimeout(() => wsConnect(onMessage), 3000);
+  };
+
+  return ws;
+}
+
+// ── Health check (for Circuit Breaker) ───────────────────────────────
+//
+// Uses /api/status which is public (no session token required), making it
+// the ideal endpoint for connectivity checks.
+export async function checkHealth(): Promise<{
+  ok: boolean;
+  kind?: ErrorKind;
+  message?: string;
+}> {
+  try {
+    await api<unknown>("/api/status", { timeout: 5_000 });
+    return { ok: true };
+  } catch (err) {
+    if (err instanceof ApiError) {
+      return { ok: false, kind: err.kind, message: err.message };
+    }
+    return { ok: false, kind: "network", message: "Unknown error" };
+  }
+}
+
+// ── Typed API calls ──────────────────────────────────────────────────
+
+export interface SkillInfo {
+  name: string;
+  path: string;
+  description: string;
+  size: number;
+  last_modified: string;
+  providers: string[];
+  provider_count: number;
+  category: string;
+}
+
+export interface SkillDetail {
+  name: string;
+  path: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  raw: string;
+  size: number;
+}
+
+export interface EvolutionRun {
+  skill_name: string;
+  timestamp: string;
+  baseline_score: number;
+  evolved_score: number;
+  improvement: number;
+  elapsed_seconds: number;
+  constraints_passed: boolean;
+  iterations: number;
+  optimizer_model: string;
+}
+
+export interface MetricsData {
+  total_runs: number;
+  skills_evolved: number;
+  avg_improvement: number;
+  best_improvement: number;
+  total_time_seconds: number;
+  avg_time_seconds: number;
+  success_rate: number;
+  runs: EvolutionRun[];
+}
+
+export interface DatasetInfo {
+  skill: string;
+  path: string;
+  splits: Record<string, number>;
+  total: number;
+}
+
+export interface ConstraintResult {
+  passed: boolean;
+  constraint: string;
+  message: string;
+  details: string | null;
+}
+
+export const fetchSkills = () => api<SkillInfo[]>("/api/skills");
+export const fetchSkill = (name: string) => api<SkillDetail>(`/api/skills/${name}`);
+export const fetchSkillHistory = (name: string) =>
+  api<EvolutionRun[]>(`/api/skills/${name}/evolution-history`);
+
+// Skill management helpers
+export interface ProviderSummary {
+  name: string;
+  total: number;
+  enabled: number;
+  skills: {
+    name: string;
+    description: string;
+    enabled: boolean;
+    tags: string[];
+    is_fork?: boolean;
+    category: string;
+  }[];
+}
+
+export const fetchSkillProviders = () =>
+  api<{ status: string; providers: ProviderSummary[] }>("/api/skills/providers");
+
+export const toggleSkillEnabled = (provider: string, skillName: string, enabled: boolean) =>
+  api<{ status: string; enabled: boolean }>("/api/skills/toggle", {
+    method: "POST",
+    body: JSON.stringify({ provider, skill_name: skillName, enabled }),
+  });
+
+export const deleteProviderSkill = (provider: string, skillName: string) =>
+  api<{ status: string; message: string }>(`/api/skills/${provider}/${encodeURIComponent(skillName)}`, {
+    method: "DELETE",
+  });
+
+export const deleteGlobalSkill = (skillName: string) =>
+  api<{ status: string; message: string }>(`/api/skills/global/${encodeURIComponent(skillName)}`, {
+    method: "DELETE",
+  });
+
+export const refreshSkills = () =>
+  api<{ status: string; providers: ProviderSummary[] }>("/api/skills/refresh");
+export const fetchEvolutionRuns = () => api<EvolutionRun[]>("/api/evolution/runs");
+
+export interface SkillDiff {
+  skill_name: string;
+  run_dir: string;
+  baseline: string | null;
+  evolved: string | null;
+  metrics: Record<string, unknown> | null;
+}
+
+export const fetchSkillDiff = (skillName: string, runDir: string) =>
+  api<SkillDiff>(`/api/skills/${encodeURIComponent(skillName)}/evolution/${encodeURIComponent(runDir)}/diff`);
+
+// ── Job tracking ─────────────────────────────────────────────────────
+
+export interface EvolutionJob {
+  id: string;
+  skill_name: string;
+  status: string;
+  iterations: number;
+  current_iteration: number;
+  pid: number | null;
+  started_at: string;
+  completed_at: string;
+  baseline_score: number | null;
+  current_best_score: number | null;
+  evolved_score: number | null;
+  improvement: number | null;
+  error: string;
+  progress: number;
+  logs: string[];
+}
+
+export const fetchJobs = (activeOnly = false) =>
+  api<EvolutionJob[]>(`/api/jobs?active_only=${activeOnly}`);
+
+export const fetchJob = (jobId: string) =>
+  api<EvolutionJob>(`/api/jobs/${jobId}`);
+
+export const fetchJobLogs = (jobId: string, since = 0) =>
+  api<{ job_id: string; total_lines: number; logs: string[]; status: string; progress: number }>(
+    `/api/jobs/${jobId}/logs?since=${since}`
+  );
+
+export const cancelJob = (jobId: string) =>
+  api<{ status: string; job_id: string }>(`/api/jobs/${jobId}`, { method: "DELETE" });
+
+export const startEvolution = (skillName: string, iterations: number) =>
+  api<{ job_id: string; skill: string; status: string; error?: string }>("/api/evolution/start", {
+    method: "POST",
+    body: JSON.stringify({ skill_name: skillName, iterations, eval_source: "synthetic" }),
+  });
+export const fetchMetrics = () => api<MetricsData>("/api/metrics");
+export const fetchDatasets = () => api<DatasetInfo[]>("/api/datasets");
+export const fetchDataset = (skill: string) =>
+  api<Record<string, unknown[]>>(`/api/datasets/${skill}`);
+export const validateSkill = (name: string) =>
+  api<ConstraintResult[]>(`/api/constraints/validate/${name}`);
+export const fetchHealth = () =>
+  api<{
+    status: string;
+    hermes_repo: string;
+    hermes_repo_exists: boolean;
+    evolution_dir: string;
+    evolution_dir_exists: boolean;
+    skills_count: number;
+    categories: Record<string, number>;
+  }>("/api/health");
+
+    

package/.brv/context-tree/frontend/src/lib/api_client_library.overview.md

@@ -0,0 +1,69 @@
+## API Client Library Overview
+
+**File:** `src/lib/api.ts`
+**Type:** TypeScript API client with typed endpoints and WebSocket support
+**Purpose:** Frontend API client for Hermes backend (skills, evolution, jobs, WebSocket)
+
+---
+
+### Key Points
+
+- **Typed API client** using a central `api<T>()` wrapper with AbortController timeouts (default 15s)
+- **Hermes session authentication** via `X-Hermes-Session-Token` header with automatic token refresh on 401
+- **Environment resolution:** Supports `NEXT_PUBLIC_API_BASE` and legacy `NEXT_PUBLIC_API_URL`; falls back to `http://127.0.0.1:9119`
+- **Typed errors** via `ApiError` class with `ErrorKind`: `network`, `timeout`, `server`, `client`
+- **WebSocket helper** (`wsConnect`) with auto-reconnect after 3s and JSON message parsing
+- **Health check endpoint** uses `/api/status` (no auth required) for circuit breaker connectivity checks
+- **Comprehensive typed interfaces** for skills, evolution runs, jobs, datasets, and constraints
+
+---
+
+### Structure / Sections Summary
+
+1. **Infrastructure Setup**
+   - Base URL resolution with fallback to `127.0.0.1:9119`
+   - Session token fetching from HTML `__HERMES_SESSION_TOKEN__`
+
+2. **Error Handling**
+   - `ApiError` class with status, kind, endpoint tracking
+   - `isApiError` type guard
+
+3. **Core Fetch Wrapper**
+   - `executeRequest<T>()` — low-level fetch with AbortController
+   - `api<T>()` — high-level wrapper with token injection and 401 retry logic
+
+4. **WebSocket Helper**
+   - `wsConnect(onMessage)` — lazy token, query param auth, auto-reconnect
+
+5. **Health Check**
+   - `checkHealth()` — returns `{ok, kind?, message?}`
+
+6. **Typed API Endpoints**
+   - Skills: `fetchSkills`, `fetchSkill`, `fetchSkillHistory`, `fetchSkillProviders`, `toggleSkillEnabled`, `deleteProviderSkill`, `deleteGlobalSkill`, `refreshSkills`
+   - Evolution: `fetchEvolutionRuns`, `fetchSkillDiff`, `startEvolution`
+   - Jobs: `fetchJobs`, `fetchJob`, `fetchJobLogs`, `cancelJob`
+   - Metrics/Datasets: `fetchMetrics`, `fetchDatasets`, `fetchDataset`
+   - Constraints: `validateSkill`
+   - Health: `fetchHealth`
+
+---
+
+### Notable Interfaces
+
+| Interface | Fields |
+|-----------|--------|
+| `SkillInfo` | name, path, description, size, providers, category |
+| `EvolutionRun` | skill_name, baseline_score, evolved_score, improvement, iterations |
+| `EvolutionJob` | id, status, current_iteration, pid, progress, logs |
+| `MetricsData` | total_runs, avg_improvement, success_rate, runs |
+| `ConstraintResult` | passed, constraint, message, details |
+| `ApiError` | kind (ErrorKind), status, endpoint |
+
+---
+
+### Notable Patterns
+
+- **Token caching** via `_sessionToken` / `_tokenPromise` with lazy initialization
+- **AbortController** for request timeout with `setTimeout` + `controller.abort()`
+- **WebSocket auto-reconnect** on `onclose` event (3s delay)
+- **URL encoding** via `encodeURIComponent` for skill names in paths

package/.brv/context-tree/frontend/src/page.md

@@ -0,0 +1,103 @@
+---
+title: page
+summary: ''
+tags: []
+related: []
+keywords: []
+createdAt: '2026-04-28T01:33:30.559Z'
+updatedAt: '2026-04-28T01:33:30.559Z'
+---
+## Reason
+Preserving complete src/app/page.tsx from hermes-dashboard project
+
+## Raw Concept
+**Task:**
+Preserve src/app/page.tsx
+
+**Files:**
+- src/app/page.tsx
+
+**Timestamp:** 2026-04-28
+
+**Patterns:**
+- `OverviewPage` - Component or function
+- `SkillStudioPage` - Component or function
+- `EvolutionPage` - Component or function
+- `DatasetPage` - Component or function
+- `MemoryPage` - Component or function
+- `MetricsPage` - Component or function
+- `LogsPage` - Component or function
+- `SettingsPage` - Component or function
+- `Home` - Component or function
+- `PageComponent` - Component or function
+
+## Narrative
+### Structure
+TSX file with 10 components/functions
+
+### Highlights
+Source: hermes-dashboard/src/app/page.tsx
+
+---
+
+
+"use client";
+
+import { useState } from "react";
+import Sidebar from "@/components/Sidebar";
+import dynamic from "next/dynamic";
+import type { Page } from "@/components/Sidebar";
+
+// Lazy load page components with loading states
+const OverviewPage = dynamic(() => import("@/components/pages/OverviewPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Overview...</div>,
+});
+const SkillStudioPage = dynamic(() => import("@/components/pages/SkillStudioPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Skill Studio...</div>,
+});
+const EvolutionPage = dynamic(() => import("@/components/pages/EvolutionPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Evolution...</div>,
+});
+const DatasetPage = dynamic(() => import("@/components/pages/DatasetPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Datasets...</div>,
+});
+const MemoryPage = dynamic(() => import("@/components/pages/MemoryPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Memory...</div>,
+});
+const MetricsPage = dynamic(() => import("@/components/pages/MetricsPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Metrics...</div>,
+});
+const LogsPage = dynamic(() => import("@/components/pages/LogsPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Logs...</div>,
+});
+const SettingsPage = dynamic(() => import("@/components/pages/SettingsPage"), {
+  loading: () => <div className="min-h-[20rem] flex items-center justify-center">Cargando Settings...</div>,
+});
+
+
+const pages: Record<Page, React.ComponentType> = {
+  overview: OverviewPage,
+  skills: SkillStudioPage,
+  evolution: EvolutionPage,
+  datasets: DatasetPage,
+  memory: MemoryPage,
+  metrics: MetricsPage,
+  logs: LogsPage,
+  settings: SettingsPage,
+};
+
+export default function Home() {
+  const [activePage, setActivePage] = useState<Page>("overview");
+  const PageComponent = pages[activePage];
+
+  return (
+    <div className="flex min-h-screen">
+      <Sidebar activePage={activePage} onNavigate={setActivePage} />
+      <main className="flex-1 p-6 lg:p-8 overflow-y-auto">
+        <PageComponent />
+      </main>
+    </div>
+  );
+}
+
+    

package/.brv/context-tree/frontend/src/page.overview.md

@@ -0,0 +1,7 @@
+# Structured Overview: hermes-dashboard page.tsx
+
+## Key Points
+
+- **Client-side React component** using `"use client"` directive for Next.js App Router
+- **Dynamic lazy loading** implemented for all 8 page components using `next/dynamic` with custom Spanish loading states
+- **State-driven navigation**: Uses `use