juan/forja
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

proyecto generalizado

Browse Source
This commit is contained in:
juan
2026-05-23 16:44:45 +02:00
parent 2f990ea636
commit b4964261ec
94 changed files with 1032 additions and 320 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/walkthrough.html
+21 -21
View File
@@ -3,8 +3,8 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Walkthrough completo de AgentForge — de alto a bajo nivel, con diagramas.">
<title>AgentForge · Walkthrough</title>
<meta name="description" content="Walkthrough completo de Forja — de alto a bajo nivel, con diagramas.">
<title>Forja · Walkthrough</title>
<script>
(function () {
try {
@@ -255,7 +255,7 @@ details.dd .body{padding:4px 16px 14px}
<div class="topbar">
<button class="icon-btn" id="menuBtn" aria-label="Abrir índice">☰</button>
<span class="tt">🛡️ AgentForge · Walkthrough</span>
<span class="tt">🛡️ Forja · Walkthrough</span>
<button class="icon-btn" id="themeBtnM" aria-label="Cambiar tema" style="margin-left:auto">◐</button>
</div>
<div class="scrim" id="scrim"></div>
@@ -266,7 +266,7 @@ details.dd .body{padding:4px 16px 14px}
<div class="brand">
<span class="logo">🛡️</span>
<span>
<span class="t1">AgentForge</span>
<span class="t1">Forja</span>
<span class="t2">Walkthrough · de alto a bajo nivel</span>
</span>
</div>
@@ -274,7 +274,7 @@ details.dd .body{padding:4px 16px 14px}
<button class="btn" id="themeBtn" style="flex:1; justify-content:center">◐ Tema</button>
<button class="btn" onclick="window.print()" style="flex:1; justify-content:center">⎙ Imprimir</button>
</div>
<div class="meta">HTML autocontenido · <code>docs/walkthrough.html</code> · AgentForge v0.1.0</div>
<div class="meta">HTML autocontenido · <code>docs/walkthrough.html</code> · Forja v0.1.0</div>
<nav>
<ul class="toc" id="toc">
<li class="group">Panorama</li>
@@ -314,7 +314,7 @@ details.dd .body{padding:4px 16px 14px}
<header class="hero">
<div class="crumbs">Plataforma de gobernanza de agentes IA · documento generado para entender el proyecto completo</div>
<h1>🛡️ AgentForge — Walkthrough</h1>
<h1>🛡️ Forja — Walkthrough</h1>
<p class="tagline">Catalogación y versionado de agentes y políticas, guardrails en runtime, ejecución <em>stateful</em> con Human-in-the-Loop, observabilidad y trazabilidad de extremo a extremo. Aquí está todo: <strong>de la vista de pájaro al cableado de cada módulo</strong>, con diagramas.</p>
<div class="badges">
<span class="badge k">🐍 <b>Python 3.11+</b></span>
@@ -338,7 +338,7 @@ details.dd .body{padding:4px 16px 14px}
<section id="intro">
<h2><span class="kicker">00</span> Qué es y por qué</h2>
<p class="lead">Poner agentes de IA en producción <strong>sin una capa de gobierno</strong> produce sistemas opacos: prompts que cambian sin historial, validaciones inconsistentes, acciones de alto impacto sin supervisión y ninguna auditoría de lo que decidió el agente.</p>
<p><strong>AgentForge es el "plano de control" que pones <em>delante</em> de tus agentes</strong> antes de dejarlos tocar nada importante. No es un framework para <em>construir</em> agentes; es la capa que los <strong>cataloga, versiona, valida, ejecuta de forma supervisada y audita</strong>.</p>
<p><strong>Forja es el "plano de control" que pones <em>delante</em> de tus agentes</strong> antes de dejarlos tocar nada importante. No es un framework para <em>construir</em> agentes; es la capa que los <strong>cataloga, versiona, valida, ejecuta de forma supervisada y audita</strong>.</p>
<div class="callout key">
<div class="ct">🧭 El caso de ejemplo del repo</div>
<p>Un agente de operaciones de telco — <code>incident_analyzer</code>: recibe la descripción de un incidente de plataforma de voz (caída de registros SIP, degradación de MOS, saturación de HSS…) y propone acciones con <strong>análisis de riesgo</strong> y <strong>plan de rollback</strong>. Las acciones de riesgo alto quedan <strong>pausadas esperando aprobación humana</strong>. Todo queda registrado con un <code>trace_id</code>.</p>
@@ -393,10 +393,10 @@ details.dd .body{padding:4px 16px 14px}
<!-- ============================================================= -->
<section id="vista">
<h2><span class="kicker">02</span> Vista de pájaro: dos servicios</h2>
<p>AgentForge son <strong>dos procesos</strong> que se hablan por HTTP/JSON, levantados por <code>docker-compose</code>:</p>
<p>Forja son <strong>dos procesos</strong> que se hablan por HTTP/JSON, levantados por <code>docker-compose</code>:</p>
<ul>
<li><strong><code>agentforge-core</code></strong> (FastAPI, puerto <strong>8000</strong>) — todo el dominio: registry de agentes, motor de guardrails, runtime de ejecución, persistencia. <em>No tiene UI.</em></li>
<li><strong><code>agentforge-dashboard</code></strong> (Streamlit, puerto <strong>8501</strong>) — una consola visual con cinco páginas. <strong>No contiene lógica de negocio</strong>: es un cliente HTTP del core.</li>
<li><strong><code>forja-core</code></strong> (FastAPI, puerto <strong>8000</strong>) — todo el dominio: registry de agentes, motor de guardrails, runtime de ejecución, persistencia. <em>No tiene UI.</em></li>
<li><strong><code>forja-dashboard</code></strong> (Streamlit, puerto <strong>8501</strong>) — una consola visual con cinco páginas. <strong>No contiene lógica de negocio</strong>: es un cliente HTTP del core.</li>
</ul>
<p>La separación importa: el core podría servir a una CLI, a otro servicio, a un pipeline… el dashboard es solo una de las caras posibles. (Y este documento es otra cara más: el HTML que estás leyendo.)</p>
@@ -416,14 +416,14 @@ details.dd .body{padding:4px 16px 14px}
<!-- dashboard -->
<rect class="dg-box accent" x="56" y="60" width="300" height="106" rx="13"/>
<text class="dg-t" x="206" y="92" text-anchor="middle">agentforge-dashboard</text>
<text class="dg-t" x="206" y="92" text-anchor="middle">forja-dashboard</text>
<text class="dg-s" x="206" y="112" text-anchor="middle">Streamlit · :8501 · "la consola"</text>
<text class="dg-m dim" x="206" y="132" text-anchor="middle">5 páginas · sin lógica de negocio</text>
<text class="dg-m dim" x="206" y="150" text-anchor="middle">CoreClient (httpx) → habla solo HTTP</text>
<!-- core -->
<rect class="dg-box violet" x="600" y="60" width="344" height="106" rx="13"/>
<text class="dg-t" x="772" y="92" text-anchor="middle">agentforge-core</text>
<text class="dg-t" x="772" y="92" text-anchor="middle">forja-core</text>
<text class="dg-s" x="772" y="112" text-anchor="middle">FastAPI · :8000 · "el cerebro"</text>
<text class="dg-m dim" x="772" y="132" text-anchor="middle">dominio · runtime · guardrails · persistencia</text>
<text class="dg-m dim" x="772" y="150" text-anchor="middle">/health · /agents · /executions · /policies · /violations</text>
@@ -513,7 +513,7 @@ details.dd .body{padding:4px 16px 14px}
<!-- ============================================================= -->
<section id="modulos">
<h2><span class="kicker">04</span> El grafo de módulos (quién depende de quién)</h2>
<p>El código del core vive bajo <code>core/src/agentforge_core/</code>. Es un <strong>DAG</strong>: las capas de abajo no importan nada de las de arriba. El "nivel" es la profundidad topológica. Lee de abajo hacia arriba: el vocabulario primero, la composición de la app al final.</p>
<p>El código del core vive bajo <code>core/src/forja_core/</code>. Es un <strong>DAG</strong>: las capas de abajo no importan nada de las de arriba. El "nivel" es la profundidad topológica. Lee de abajo hacia arriba: el vocabulario primero, la composición de la app al final.</p>
<div class="bands">
<div class="band">
<div class="lvl"><b>6</b><span>app</span></div>
@@ -980,7 +980,7 @@ details.dd .body{padding:4px 16px 14px}
<p>El estado que fluye por el grafo es un <code>TypedDict</code>. <code>decision_path</code> usa un <em>reducer</em> (<code>Annotated[list, operator.add]</code>) para que cada nodo <strong>añada</strong> pasos en vez de sobrescribir:</p>
<div class="code">
<div class="hd"><span class="dot"></span><span class="fn">core/src/agentforge_core/runtime/state.py</span><span class="lang">python</span></div>
<div class="hd"><span class="dot"></span><span class="fn">core/src/forja_core/runtime/state.py</span><span class="lang">python</span></div>
<pre><span class="k">class</span> <span class="y">AgentState</span>(TypedDict, total=<span class="k">False</span>):
trace_id: <span class="y">str</span>; agent_name: <span class="y">str</span>; agent_version: <span class="y">str</span>; user_input: <span class="y">str</span>
messages: <span class="y">list</span>[<span class="y">dict</span>]; raw_llm_output: <span class="y">str</span> | <span class="k">None</span>; parsed_output: <span class="y">dict</span> | <span class="k">None</span>
@@ -1097,7 +1097,7 @@ g.add_edge(<span class="s">"finalize"</span>, END)
<!-- divider -->
<rect class="dg-band" x="14" y="460" width="1092" height="34" rx="6"/>
<line class="dg-divider" x1="14" y1="460" x2="1106" y2="460"/><line class="dg-divider" x1="14" y1="494" x2="1106" y2="494"/>
<text class="dg-s" x="560" y="481" text-anchor="middle" style="font-style:italic">· · · más tarde — incluso tras reiniciar agentforge-core: el estado pausado sigue en checkpoints.sqlite · · ·</text>
<text class="dg-s" x="560" y="481" text-anchor="middle" style="font-style:italic">· · · más tarde — incluso tras reiniciar forja-core: el estado pausado sigue en checkpoints.sqlite · · ·</text>
<!-- ACT 2 label -->
<rect class="dg-box ok" x="18" y="504" width="232" height="22" rx="6"/><text class="dg-t sm" x="28" y="520" style="font-size:11.5px;fill:var(--ok)">ACTO 2 · el humano decide → completed</text>
@@ -1222,7 +1222,7 @@ curl -s localhost:8000/executions/$TRACE/approve \
<!-- ============================================================= -->
<section id="persistencia">
<h2><span class="kicker">11</span> Persistencia: cuatro formas, cuatro razones</h2>
<p>AgentForge no usa una sola base de datos; usa la herramienta adecuada para cada cosa.</p>
<p>Forja no usa una sola base de datos; usa la herramienta adecuada para cada cosa.</p>
<figure class="diagram">
<svg viewBox="0 0 1020 420" role="img" aria-label="Mapa de persistencia: quién escribe y lee qué">
@@ -1230,7 +1230,7 @@ curl -s localhost:8000/executions/$TRACE/approve \
<!-- core in the middle -->
<rect class="dg-box violet" x="396" y="170" width="228" height="80" rx="12"/>
<text class="dg-t sm" x="510" y="196" text-anchor="middle">agentforge-core</text>
<text class="dg-t sm" x="510" y="196" text-anchor="middle">forja-core</text>
<text class="dg-s" x="510" y="214" text-anchor="middle">registry · orchestrator</text>
<text class="dg-s" x="510" y="230" text-anchor="middle">api/persistence · runtime/checkpointer</text>
@@ -1489,11 +1489,11 @@ curl -s localhost:8000/executions/$TRACE/approve \
<div>
<h4>El ciclo de vida del proceso core</h4>
<ol>
<li>Importar <code>agentforge_core.main</code> ejecuta <code>app = create_app()</code>: <code>Settings()</code> → <code>configure_logging(level)</code> → <code>FastAPI(...)</code> → <code>add_middleware(TraceIdMiddleware)</code> → registra <code>GET /health</code> → importa los routers → <code>include_router</code> (agents, executions ×2, policies, violations).</li>
<li>Importar <code>forja_core.main</code> ejecuta <code>app = create_app()</code>: <code>Settings()</code> → <code>configure_logging(level)</code> → <code>FastAPI(...)</code> → <code>add_middleware(TraceIdMiddleware)</code> → registra <code>GET /health</code> → importa los routers → <code>include_router</code> (agents, executions ×2, policies, violations).</li>
<li>Las dependencias (<code>get_registry</code>, <code>get_policy_store</code>, <code>get_llm_provider</code>, <code>get_guardrail_engine</code>, <code>get_orchestrator</code>) <strong>no</strong> se construyen aún; se construyen y cachean en la <strong>primera request</strong> que las inyecta.</li>
<li>Cada request: <code>TraceIdMiddleware.dispatch</code> → router → resuelve <code>Depends(...)</code> (que puede disparar la construcción perezosa) → handler → respuesta con <code>X-Trace-Id</code>.</li>
</ol>
<p class="muted">En contenedores: <code>uvicorn agentforge_core.main:app --host 0.0.0.0 --port 8000</code>; <code>HEALTHCHECK</code> → <code>curl /health</code>; monta <code>./agents:ro</code>, <code>./policies:ro</code>, <code>./data:rw</code>; <code>DATA_DIR=/app/data</code>, etc. El dashboard depende de <code>core: service_healthy</code> y usa <code>AGENTFORGE_CORE_URL=http://core:8000</code>. La imagen del core instala <code>en_core_web_sm</code> de spaCy para Presidio.</p>
<p class="muted">En contenedores: <code>uvicorn forja_core.main:app --host 0.0.0.0 --port 8000</code>; <code>HEALTHCHECK</code> → <code>curl /health</code>; monta <code>./agents:ro</code>, <code>./policies:ro</code>, <code>./data:rw</code>; <code>DATA_DIR=/app/data</code>, etc. El dashboard depende de <code>core: service_healthy</code> y usa <code>FORJA_CORE_URL=http://core:8000</code>. La imagen del core instala <code>en_core_web_sm</code> de spaCy para Presidio.</p>
</div>
<div>
<h4>Variables de entorno (<code>config.py</code> · <code>.env</code>)</h4>
@@ -1510,7 +1510,7 @@ curl -s localhost:8000/executions/$TRACE/approve \
<tr><td><code>DATA_DIR</code></td><td><code>./data</code></td><td>checkpointer · índice · JSONL</td></tr>
<tr><td><code>AGENTS_DIR</code></td><td><code>./agents</code></td><td><code>FileSystemAgentRegistry</code></td></tr>
<tr><td><code>POLICIES_DIR</code></td><td><code>./policies</code></td><td><code>FileSystemPolicyStore</code></td></tr>
<tr><td><code>AGENTFORGE_CORE_URL</code></td><td><code>http://core:8000</code></td><td>el dashboard (<code>CoreClient</code>)</td></tr>
<tr><td><code>FORJA_CORE_URL</code></td><td><code>http://core:8000</code></td><td>el dashboard (<code>CoreClient</code>)</td></tr>
</tbody>
</table>
</div>
@@ -1721,7 +1721,7 @@ open docs/walkthrough.html <span class="c"># macOS</span>
<div class="footer">
<p><strong>AgentForge · Walkthrough.</strong> Documento autocontenido (sin recursos externos). Acompaña a <code>README.md</code>, <code>ARCHITECTURE.md</code>, <code>docs/explicacion.md</code> (narrativa) y <code>docs/componentes.md</code> (referencia de cableado). Refleja el repo en <code>v0.1.0</code>.</p>
<p><strong>Forja · Walkthrough.</strong> Documento autocontenido (sin recursos externos). Acompaña a <code>README.md</code>, <code>ARCHITECTURE.md</code>, <code>docs/explicacion.md</code> (narrativa) y <code>docs/componentes.md</code> (referencia de cableado). Refleja el repo en <code>v0.1.0</code>.</p>
<p class="muted">Documento HTML autocontenido (<code>docs/walkthrough.html</code>) — sin recursos externos: ábrelo en cualquier navegador.</p>
</div>
</main>