rony-chat-bot/docs/architecture.es.md

📋 Rony Chat Bot — Technical Design Document

🌐 Idioma: English | Español

Versión: 1.0
Autor: Victor Hugo Vargas
Fecha: 2026-06-28
Estado: Especificación completa para implementación Path: rony-chat-bot/docs/architecture.md

📚 Workspace: Este proyecto es parte del workspace Rony/. Ver ../README.md.

🔑 Depende de: rony-llm-agent — librería core que provee agent loop, LLM clients, RAG, persona system.

📐 Metodología: Este proyecto sigue el enfoque SDD + DDD + Hexagonal Architecture. Los Requisitos Funcionales se numeran como CRF-XXX. Ver ../../METHODOLOGY.md.

---

🎯 1. Visión del Proyecto

1.1 ¿Qué es Chat-Bot?

Un chatbot HTTP que responde preguntas sobre Victor Hugo Vargas y sus proyectos. Usa RAG (Retrieval-Augmented Generation) sobre archivos markdown que describen cada proyecto, y un LLM local (o cloud) para generar respuestas.

1.2 Caso de uso primario

Victor tiene un portfolio web (Astro + React). En el sitio hay un widget de chat donde visitantes pueden preguntar:

• "¿Qué proyectos ha hecho Victor?"
• "¿Cuál es su experiencia con Go?"
• "¿Cómo funciona Rony TUI?"
• "¿Victor ha trabajado con PostgreSQL?"

El bot responde con información precisa extraída de los archivos markdown de proyectos + bio + skills.

1.3 Casos de uso secundarios (futuro)

• Adaptación a clientes: El mismo bot, con otra data y otra persona, sirve para concesionarios, restaurantes, etc.
• Standalone CLI: ./chat-bot ask "¿qué sabes de X?" para uso desde terminal.
• Slack/Discord bot: Wrapper que consume el HTTP API.

1.4 Filosofía

• Self-hosted por defecto — funciona 100% local con Ollama + modelos 1-3B
• Cloud opcional — si se necesita más calidad, swap a Anthropic API
• Portable — fácil de fork/customizar para otros contextos
• Streaming — respuestas token-por-token con SSE (no espera a respuesta completa)
• Reutiliza rony-llm-agent — no reinventar el agent loop

---

🏗️ 2. Arquitectura

2.1 Vista general

┌─────────────────────────────────────────────────────────────────┐
│  Browser (Astro site)                                            │
│      ↓ HTTP POST /api/chat                                       │
│  Astro SSR (proxy)  ←────────── Sirve portfolio + proxy chat    │
│      ↓ HTTP POST /api/chat                                       │
│  Chat-Bot HTTP server (:7331)                                    │
│      ↓                                                           │
│  Agent loop (rony-llm-agent)                                       │
│      ↓                                                           │
│  RAG híbrido → SQLite FTS5 (BM25) ⊕ vectores, fusionados con RRF  │
│      ↓                  sobre data/projects/ + data/docs/         │
│      ├─→ servidor de embeddings (:9200, nomic-embed-v2-moe)       │
│      ↓                                                           │
│  LLM (llama.cpp local default / Ollama o Anthropic opcionales)   │
└─────────────────────────────────────────────────────────────────┘

Dos servidores de modelos locales, no uno. Ambos son procesos llama-server comunes con los que el bot habla por HTTP; ninguno se enlaza dentro del binario.

2.2 Componentes principales

Componente	Path	Responsabilidad
HTTP server	internal/server/	chi handlers, SSE streaming
Agent runner	internal/agent/	Wrapper sobre rony-llm-agent: armado del prompt, recuperación, selección de idioma, compactación
Portfolio loader	internal/portfolio/	Lee data/projects/ y data/docs/ (.md + .mdx), indexa en SQLite FTS5 + vectores, búsqueda híbrida
Cliente de embeddings	internal/embed/	Embeddings compatibles con OpenAI, normalización, códec float32
Persona	internal/persona/	Carga persona desde configs/portfolio-bot.yaml
CLI	cmd/chat-bot/	Comandos: serve, reindex, ask, version

2.3 Stack tecnológico

Capa	Tecnología	Razón
Lenguaje	Go 1.26+	Mismo que harness, aprovechar os.Root, iter.Seq
HTTP router	net/http + chi	Stdlib + chi para middleware (CORS, logging)
SSE	net/http Flusher	Stdlib es suficiente, no necesita librería externa
Config	gopkg.in/yaml.v3	Mismo que harness
RAG backend	SQLite + FTS5 (BM25) ⊕ vectores densos	Sin dependencias externas, un solo archivo. Sin índice ANN: un portafolio son cientos de chunks, así que un scan completo son microsegundos
LLM	llama.cpp (qwen2.5-3b-instruct Q4_K_M) — default; Ollama como alternativa	Self-hosted por defecto. 3B y no 1.5B: ver el benchmark en configs/portfolio-bot.yaml
Embeddings	nomic-embed-v2-moe Q5_K_M, 768 dims	Multilingüe — el punto entero es casar preguntas en español con documentos en inglés
Tests	stdlib + testify	Consistencia con el resto

---

🔌 3. HTTP API

3.1 Endpoints

POST /api/chat — Chat con streaming SSE

Request:

{
  "messages": [
    {"role": "user", "content": "¿Qué proyectos tiene Victor?"}
  ],
  "stream": true
}

Response (SSE):

data: {"type":"start","conversation_id":"abc123"}

data: {"type":"chunk","content":"Victor"}
data: {"type":"chunk","content":" tiene"}
data: {"type":"chunk","content":" varios"}
data: {"type":"chunk","content":" proyectos"}

data: {"type":"sources","documents":["rony-tui.md","rony-llm-agent.md"]}

data: {"type":"done","usage":{"input_tokens":245,"output_tokens":38}}

Sin streaming ("stream": false):

{
  "content": "Victor tiene varios proyectos...",
  "sources": ["rony-tui.md", "rony-llm-agent.md"],
  "usage": {"input_tokens": 245, "output_tokens": 38}
}

POST /api/reindex — Re-indexar portfolio

Útil cuando se modifican archivos en data/projects/.

Request: vacío Response:

{
  "indexed_files": 12,
  "total_chunks": 87,
  "duration_ms": 4321
}

GET /api/health — Health check (real)

Prueba el LLM provider y el store SQLite en paralelo y reporta su estado. Pensado para monitoring / load balancers. Devuelve 200 cuando está healthy o degraded, 503 cuando está unhealthy.

• ?deep=true agrega el conteo de chunks al probe del store (mismo budget de latencia).

Taxonomía de status:

status	HTTP	Significado
healthy	200	LLM up, store up
degraded	200	LLM up, store down — el bot igual responde, sin RAG
unhealthy	503	LLM down — el bot no puede responder, no tiene sentido rutear tráfico acá

Probes:

Componente	Probe	Latencia típica
llm	GET {provider}/health (llamacpp, ollama) o /models (openai)	~1ms para llama-server local
store	SELECT 1 sobre el handle SQLite	~100µs

Cada probe tiene 2s de timeout; toda la llamada vuelve en ~2.5s aunque una dependencia esté colgada.

Shape de respuesta (healthy):

{
  "status": "healthy",
  "version": "0.2.0-dev",
  "checked_at": "2026-07-17T05:02:07Z",
  "components": {
    "llm": {
      "status": "up",
      "latency": "1.028ms",
      "details": {"provider": "llamacpp", "model": "qwen2.5-3b-instruct", "url": "http://localhost:9100/health"}
    },
    "store": {
      "status": "up",
      "latency": "107µs"
    }
  }
}

Shape (degraded, con ?deep=true):

{
  "status": "degraded",
  "version": "0.2.0-dev",
  "checked_at": "2026-07-17T05:02:07Z",
  "components": {
    "llm": {"status": "up", "latency": "0.8ms", "details": {...}},
    "store": {"status": "up", "latency": "70µs", "details": {"chunks": 28}}
  }
}

Shape (unhealthy): HTTP 503, mismo JSON con "status": "unhealthy" y el componente fallido reportando "status": "down" más un campo error.

GET /api/info — Metadata del bot

{
  "name": "Asistente de Victor Hugo Vargas",
  "model": "qwen2.5-3b-instruct",
  "persona": "...",
  "topics": ["proyectos", "experiencia", "skills técnicas"]
}

3.2 SSE Implementation

// internal/server/chat.go
package server

import (
    "encoding/json"
    "fmt"
    "net/http"
    "github.com/VictorVargas/rony-llm-agent/pkg/agent"
)

func (s *Server) handleChat(w http.ResponseWriter, r *http.Request) {
    // Headers SSE
    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")
    w.Header().Set("X-Accel-Buffering", "no")
    
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "SSE no soportado", http.StatusInternalServerError)
        return
    }
    
    // Parse request
    var req ChatRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, flusher, "invalid request", err)
        return
    }
    
    // Start event
    writeSSE(w, flusher, "start", map[string]string{
        "conversation_id": generateConvID(),
    })
    
    // Run agent con streaming
    sources := []string{}
    for chunk, err := range s.agent.RunStream(r.Context(), req.Messages) {
        if err != nil {
            writeSSE(w, flusher, "error", map[string]string{"message": err.Error()})
            return
        }
        if chunk.Type == "source" {
            sources = append(sources, chunk.Source)
        }
        writeSSE(w, flusher, chunk.Type, chunk.Data)
    }
    
    // Done event
    writeSSE(w, flusher, "done", map[string]any{
        "usage": map[string]int{
            "input_tokens":  245,
            "output_tokens": 38,
        },
    })
}

func writeSSE(w http.ResponseWriter, flusher http.Flusher, eventType string, data any) {
    payload, _ := json.Marshal(data)
    fmt.Fprintf(w, "data: {\"type\":%q,\"data\":%s}\n\n", eventType, payload)
    flusher.Flush()
}

3.3 Middleware

// internal/server/middleware.go
package server

func (s *Server) loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        // Wrap response writer para capturar status
        rw := &statusRecorder{ResponseWriter: w, status: 200}
        next.ServeHTTP(rw, r)
        
        slog.Info("http.request",
            "method", r.Method,
            "path", r.URL.Path,
            "status", rw.status,
            "duration_ms", time.Since(start).Milliseconds(),
            "ip", r.RemoteAddr,
        )
    })
}

func (s *Server) corsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        origin := r.Header.Get("Origin")
        for _, allowed := range s.config.Server.CORSOrigins {
            if origin == allowed {
                w.Header().Set("Access-Control-Allow-Origin", origin)
                w.Header().Set("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
                w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
                break
            }
        }
        if r.Method == "OPTIONS" {
            w.WriteHeader(204)
            return
        }
        next.ServeHTTP(w, r)
    })
}

func (s *Server) rateLimitMiddleware(next http.Handler) http.Handler {
    limiter := rate.NewLimiter(rate.Every(time.Minute/time.Duration(s.config.Server.RateLimit.RequestsPerMinute)), s.config.Server.RateLimit.Burst)
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if !limiter.Allow() {
            http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
            return
        }
        next.ServeHTTP(w, r)
    })
}

---

🧠 4. RAG (Retrieval-Augmented Generation)

✅ Las cuatro decisiones que esta sección dejaba abiertas ya se tomaron y se midieron:

• Tokenizer FTS5 — unicode61 remove_diacritics 2, como decía el spec. El stemming no era el cuello de botella; el salto de idioma sí, y eso lo cierran los embeddings.
• Driver SQLite — modernc.org/sqlite (puro Go, sin CGO). Benchmark abajo.
• Chunking — por heading de markdown, no por tamaño fijo, y las secciones demasiado grandes se parten en ### antes de caer al corte por bytes. §4.1.
• Similitud semántica — agregada. BM25 solo devolvía absolutamente nada ante una pregunta en español sobre un documento en inglés. §4.2.

4.0 Decisión de driver: resultados del benchmark

Reproducible con CGO_ENABLED=1 go test -tags sqlite_fts5 -bench=. ./bench/. Datos: 4 markdowns → 11 chunks.

Operación	mattn (CGO)	modernc (puro Go)	Diferencia
Insert (11 chunks)	2,802,843 ns/op	1,465,646 ns/op	modernc 1.9× más rápido
Insert alloc	2,124,299 B/op	9,770 B/op	modernc usa 217× menos memoria
Query (8 queries BM25)	244,047 ns/op	555,162 ns/op	mattn 2.3× más rápido
Round-trip (insert + 8 queries)	3,543,417 ns/op	2,267,669 ns/op	modernc 1.6× más rápido
Tamaño binario	11 MB	11 MB	igual
Dependencias build	gcc, CGO=1	ninguna	gana modernc
CI/CD portable	requiere toolchain C	go build puro	gana modernc

Decisión: modernc.org/sqlite.

Justificación:

1. Ambas latencias de query (~250µs vs ~550µs) son 2 órdenes de magnitud por debajo del target de 50ms — imperceptible vs el LLM (varios segundos).
2. modernc gana en inserts (1.9×) y round-trip (1.6×), que es el path de reindex.
3. Sin CGO = CI/CD más simple (sin gcc, sin Alpine musl-dev, binarios reproducibles).
4. Si en el futuro el cuello de botella pasa a ser query latency (corpus >10k chunks), se puede reconsiderar. Hoy no.

4.1 Pipeline de indexación

data/projects/*.{md,mdx}   kind=project → se anuncia en el catálogo
data/docs/*.{md,mdx}       kind=doc     → se busca, nunca se anuncia
    ↓ (se salta el README de cada carpeta — son instrucciones, no contenido)
Markdown crudo
    ↓ (split por heading; las secciones grandes se parten en ###, luego por tamaño)
    ↓ (se descarta el chunk de frontmatter)
Chunks
    ├─→ tabla virtual FTS5 "portfolio_chunks"
    └─→ endpoint de embeddings → "portfolio_vectors" (id, content_hash, dim, vec)
Corpus indexado

Dos tipos de fuente. Todo lo que está bajo data_path es un proyecto de Victor y se lista en el catálogo que se inyecta en cada prompt. Todo lo que está bajo docs_path es evidencia buscable que no es un proyecto: su CV, una página "sobre mí". El CV es el documento que de verdad lee quien está decidiendo si contratarlo, y era irrecuperable mientras vivía solo en el sitio de Astro; pero meterlo en projects hacía que el bot listara "cv" como uno de sus trabajos.

Tres cosas se excluyen o se reorganizan, cada una por una falla medida:

Regla	Falla que arregla
Saltar README* en ambas carpetas	data/projects/README.md se indexaba, así que el catálogo anunciaba "README" y "README.es" como proyectos de Victor
Descartar el chunk de frontmatter	Metadata densa en un chunk muy corto es un imán para consultas breves — el campo location: de un CV respondía "¿Dónde ha trabajado Victor?" con una ciudad en vez del historial laboral
Partir las secciones grandes en ###	La sección Experience de un CV es una lista de empleos; el corte por tamaño partía una entrada a mitad de palabra y dejaba el nombre del empleador huérfano en el chunk anterior. Ahora cada chunk es un empleo, llamado Experience — Metrimex — Frontend Developer

Cuándo se ejecuta:

• Manualmente: ./chat-bot reindex
• Al arrancar, con serve --reindex-on-start
• Vía HTTP: POST /api/reindex

Los vectores se construyen al indexar, así que activar embeddings exige un reindex. La tabla de chunks es dato derivado: OpenStore la reconstruye cuando le faltan columnas, de modo que actualizar una instalación existente no requiere migración. Esa reconstrucción nunca toca las tablas de conversaciones.

4.2 Pipeline de retrieval

Consulta "¿Con qué se paga en la tienda de ropa?"
    ↓
    ├─→ FTS5 MATCH, ranking BM25        → top 15 (topK × 3)
    └─→ embed(query) → coseno vs vecs   → top 15 (topK × 3)
    ↓ (Reciprocal Rank Fusion, k=60)
Top 5 chunks
    ↓ (system prompt + catálogo + extractos + directiva de idioma)
El LLM genera la respuesta

Las dos mitades hacen falta. La búsqueda por palabras hace coincidencia exacta: sin stemming, sin traducción. El corpus está escrito en inglés y los visitantes preguntan en español, así que las palabras con carga semántica puntúan cero: medido sobre el corpus real, "paga" aparece 0 veces en un documento que dice "Payments: Stripe" y "trabajado" 0 veces en uno que dice "worked". La pregunta de arriba no recuperaba nada. Los embeddings (nomic-embed-v2-moe, multilingüe) ponen los tres chunks de tienda-ropa arriba — pero difuminan los términos raros exactos, donde BM25 es preciso.

Por qué RRF y no una puntuación ponderada. Un score BM25 y un coseno no comparten escala, así que mezclarlos numéricamente significa inventar un factor de conversión y reajustarlo cada vez que cambia el corpus. RRF ignora las magnitudes y ordena por acuerdo entre los dos rankings: cada lista aporta 1/(60 + rank). Un chunk que le gusta a ambas mitades le gana a uno que solo una adora.

Degradación. Si el endpoint de embeddings se cae o se desactiva, la mitad vectorial devuelve vacío y la recuperación sigue en modo keyword-only en vez de fallar la petición.

Vectores obsoletos. Los ids de chunk se derivan de la posición, así que sobreviven a las ediciones del cuerpo. Sin una guarda, editar un documento deja vectores que siguen describiendo el texto que se eliminó — reproducido en vivo cambiando el medio de pago de un proyecto y viendo cómo el anterior seguía apareciendo. Cada vector guarda un hash del texto exacto con el que se construyó, y las filas cuyo hash ya no coincide se ignoran con un warning hasta el siguiente reindex.

El catálogo. El top-K devuelve las secciones que mejor coinciden, así que una pregunta amplia como "¿qué ha construido Victor?" no se puede responder solo con recuperación, y un modelo pequeño al que se le pide enumerar a partir de resultados parciales inventa el resto. La lista completa de proyectos se inyecta en cada turno a un costo de ~10 tokens por proyecto. Esto es lo que detuvo que el bot nombrara proyectos inexistentes.

4.3 Esquema

// internal/portfolio/indexer.go
const schema = `
CREATE VIRTUAL TABLE IF NOT EXISTS portfolio_chunks USING fts5(
    id UNINDEXED,
    project_id UNINDEXED,
    kind UNINDEXED,          -- 'project' | 'doc'
    source_file UNINDEXED,
    section UNINDEXED,       -- el heading del que salió el chunk
    chunk_index UNINDEXED,
    content,
    tokenize = 'unicode61 remove_diacritics 2'
);
`

// Los vectores viven en una tabla común indexada por chunk id. No hay índice
// ANN: un portafolio son cientos de chunks, no millones, así que un scan
// completo con producto punto son microsegundos y no necesita extensiones.
const vectorSchema = `
CREATE TABLE IF NOT EXISTS portfolio_vectors (
    chunk_id     TEXT PRIMARY KEY,
    content_hash TEXT NOT NULL,   -- sha256 del texto exacto embebido
    dim          INTEGER NOT NULL,
    vec          BLOB NOT NULL    -- float32 little-endian, normalizado
);
`

FTS5 no tiene ALTER TABLE ADD COLUMN, así que ensureChunkSchema dropea y recrea portfolio_chunks cuando una base vieja no tiene alguna columna. Es seguro precisamente porque la tabla es un índice derivado: cada fila se regenera desde el markdown en el siguiente reindex. Toca deliberadamente solo las tablas del índice; las conversaciones viven en el mismo archivo y son datos reales del usuario.

Los vectores se normalizan al escribirlos, así que el producto punto es el coseno y la búsqueda no necesita una división por comparación. dim se guarda para que un cambio de modelo de embeddings se detecte en vez de producir similitudes basura en silencio: las filas cuya dimensión no coincide con el vector de consulta se ignoran.

API principal:

Función	Archivo	Para qué
SourcesFor(dataPath, docsPath)	indexer.go	Arma el par []Source; un path vacío se salta, así que docs_path es opcional sin ramificar
Store.Reindex(ctx, sources, cfg)	indexer.go	Reconstruye ambas tablas desde disco
Store.Search(ctx, query, topK)	indexer.go	Solo BM25, excluye section = 'frontmatter'
Store.HybridSearch(ctx, emb, q, topK)	hybrid.go	BM25 + vectores fusionados con RRF
Store.Catalog(ctx)	indexer.go	Lista de proyectos para el prompt; filtra kind = 'project'
embed.Client.Embed(ctx, texts)	internal/embed/	Embeddings compatibles con OpenAI, reordenados por el campo index de la respuesta

4.4 Armado del prompt

agent.Runner.BuildMessages corre una vez por petición y produce exactamente un mensaje de sistema seguido de los turnos de conversación. El orden de las operaciones importa:

// internal/agent/runner.go
func (r *Runner) BuildMessages(ctx context.Context, history []Message) ([]Message, string, error) {
    // 1. Saca los mensajes de sistema (el resumen del compactador) de los turnos.
    notes, history := foldSystemNotes(history)

    // 2. El idioma del visitante decide sobre qué versión del prompt
    //    construimos, así que se resuelve antes que nada.
    lang := detectLanguage(history)
    systemPrompt := r.promptFor(lang)

    // 3. Se resuelve antes del retrieval para que el presupuesto de
    //    extractos lo tenga en cuenta.
    catalog := r.catalogBlock(ctx)

    // 4. Recuperación híbrida sobre el último turno del usuario.
    hits, err := r.store.HybridSearch(ctx, r.embedder, last.Content, r.topK)
    ragContext = r.limitRAGContext(systemPrompt, catalog, formatHits(hits), history)

    // 5. prompt → catálogo → extractos → resumen → directiva de idioma.
    system := botpersona.BuildSystemPrompt(systemPrompt, catalog, ragContext)
    system += "\n\n" + strings.Join(notes, "\n\n")
    system += "\n\n" + r.languageDirective(lang)

    history, err = r.fitHistory(system, history)
    return append([]Message{{Role: RoleSystem, Content: system}}, history...), ragContext, nil
}

Por qué exactamente un mensaje de sistema. La plantilla de chat de Gemma 3 lanza "Conversation roles must alternate user/assistant/..." ante cualquier mensaje de sistema que no sea el primero, y llama-server lo devuelve como HTTP 400 — activar la compactación mataba la conversación la primera vez que se disparaba. La API de Anthropic también rechaza mensajes de sistema a mitad de conversación, así que plegarlos es el comportamiento portable y no un parche para Gemma. foldSystemNotes nunca aliasea el slice del llamador; el handler reutiliza el historial que le pasa.

Por qué la directiva de idioma va al final. Es la instrucción que un modelo pequeño tiene más probabilidad de seguir reteniendo cuando empieza a generar. Aunque la posición sola no alcanzó — ver abajo.

Responder en el idioma del visitante costó tres intentos, medidos sobre gemma-3-1b con las mismas cinco preguntas en español:

Enfoque	Resultado
Prompt en inglés + "respondé en el idioma del usuario"	1/5 respuestas en español
Prompt en inglés + ejemplos few-shot en español	5/5 en español, pero ~2/5 eran el ejemplo copiado literal en vez de una respuesta
Una versión completa del prompt en español (system_prompt_es)	4/5 en español, 4/5 respuestas reales

Así que internal/i18n detecta el idioma y promptFor elige la versión; la directiva refuerza un prompt que ya está escrito en el idioma correcto en vez de intentar sobreescribir uno escrito en el equivocado. Las dos versiones del YAML hay que mantenerlas sincronizadas a mano.

Por qué la búsqueda por palabras no alcanzó. El plan original daba tres razones para no usar embeddings: no hay modelo que ejecutar, un solo archivo y un solo driver, y BM25 es fuerte sobre documentos estructurados. Las dos primeras siguen siendo ciertas y costaron lo previsto (~0.91 GB residentes, un proceso más). La tercera acertó sobre el corpus y erró sobre las preguntas: BM25 es excelente recuperando documentos en inglés dadas palabras en inglés, y a este bot le preguntan en español. Eso no es un problema de morfología que arregle un tokenizer trigram — es un problema de traducción. De ahí §4.2, y de ahí que se conserven las dos mitades.

---

🗜️ 4.5 Auto-compactación

Las conversaciones largas eventualmente agotan el contexto. La auto-compactación pliega la parte más antigua de la conversación en un único mensaje-resumen del sistema cuando los tokens de entrada del turno anterior cruzan un umbral configurable.

Cuánto margen hay en realidad. Medido sobre 20 peticiones reales con context_size: 4096, el prompt más grande que este bot llegó a construir fue de 1255 tokens — system prompt, catálogo de proyectos, cinco chunks recuperados y la pregunta — con una mediana de 1069. Eso deja espacio para una docena larga de turnos cortos antes de llegar al umbral del 75% (~3070 tokens), no los 2–3 que estimaba un borrador anterior de este documento. La compactación es entonces una red de seguridad para hilos genuinamente largos, no algo que se dispare en una visita típica: en todo el benchmark no se activó nunca y no se truncó nada.

Cuándo se dispara

agent.Runner.Compact corre una vez por request a /api/chat, antes de la búsqueda RAG. Compara los Usage.InputTokens más recientes del runner (reportados por el provider en el chunk streameado previo) contra client.Capabilities().MaxContextWindow × threshold_ratio.

Config	Default	Qué controla
compaction.enabled	false	Switch maestro.
compaction.threshold_ratio	0.75	Dispara cuando tokens usados ≥ ventana × ratio.
compaction.keep_recent_turns	4	Cuántos turnos recientes del usuario se preservan literales tras la compactación.
compaction.summary_system_prompt	(bilingüe built-in)	Override de la instrucción enviada al LLM al resumir.

Sale silenciosamente cuando la compactación está deshabilitada, el provider no reporta ventana (Capabilities().MaxContextWindow == 0), la historia es más corta que keep_recent_turns, o el usage aún es desconocido (primer turno).

Cómo se hace el resumen

1. splitByTurns(history, keep_recent_turns) divide los mensajes en (older, recent) cortando en límites de rol user, así el par user/assistant de un turno preservado queda siempre junto.
2. renderTranscript(older) aplana los mensajes antiguos en una transcripción User: / Assistant: (saltando mensajes tool y placeholders vacíos de assistant).
3. El runner llama a client.Generate(...) con el prompt de resumen + la transcripción y un cap de 512 tokens para que la compactación en sí misma sea barata.
4. El texto devuelto se antepone como mensaje de sistema ("Earlier conversation summary:\n…"), seguido por la cola reciente.
5. LastCompaction() devuelve CompactionStats para que el handler SSE emita el evento compaction justo antes de los chunks streameados.

Modo de falla

Si Generate falla o devuelve un resumen vacío, la compactación cae a truncateToBudget: descarta turnos antiguos del usuario uno por uno hasta que el slice restante entre en threshold tokens (heurística: len(s) / 4 + 1). El turno actual del usuario siempre se preserva. El fallback se loggea a nivel WARN y el request sigue — un fallo del resumidor nunca rompe la request del usuario.

Protocolo de cable

Las respuestas streameadas ganan un evento opcional compaction:

data: {"type":"compaction","older_turns":6,"kept_turns":2,"summary_tokens":120,"window_tokens":4096,"used_tokens":3500}

Se emite después del start (cuando aplica) y antes de sources / chunk. El widget puede renderizar esto como un hint sutil "Contexto compactado" o ignorarlo — ambas son válidas.

Persistencia

La compactación es por-request. La transcripción completa igual se guarda en messages en data/portfolio.db literal, así que GET /api/conversations/{id} siempre devuelve la historia original. Sólo se reduce lo que se le manda al LLM — la próxima sesión puede releer el thread completo desde la DB.

---

🌐 5. Embebiendo el widget

El bot viene con un widget vanilla-JS drop-in. Agrega dos archivos a tu sitio y funciona.

5.1 El widget (cualquier sitio)

<link rel="stylesheet" href="/path/to/chat-widget.css">
<script src="/path/to/chat-widget.js"
        data-api-url="https://chat.example.com"
        data-title="Pregúntame lo que sea"
        data-greeting="¡Hola! Pregúntame sobre los proyectos."
        data-position="bottom-right"
        data-theme="auto"
        defer></script>

Aparece una burbuja abajo a la derecha, abre un panel, habla SSE con /api/chat, streamea la respuesta y cita las fuentes. Sin build step, sin React/Vue, sin lock-in de framework.

Opciones browser→bot:

Topología	Trade-offs
Directo (browser → bot, mismo dominio o CORS)	Lo más simple. Agrega el origen del bot a cors_origins en YAML.
Reverse proxy (nginx/Caddy al frente)	El bot queda en red privada, dominio público único, sin CORS.
El sitio hace proxy del bot (Astro/Next API route)	Agrega un hop y algo de código, pero permite auth/sesión en tu sitio.

El widget funciona igual en las tres. Elige la que se ajuste a tu infra.

El setup dev default es directo + CORS. cors_origins en configs/portfolio-bot.yaml controla qué sitios pueden llamar al bot. Agregá el origen de tu sitio ahí.

5.2 Astro: drop-in vía Layout

El widget funciona en Astro sin escribir un componente React. Agregá esto a tu layout compartido:

---
// src/layouts/BaseLayout.astro
import "../path/to/chat-widget.css";
const apiUrl = import.meta.env.PUBLIC_CHAT_API_URL || "http://localhost:7331";
---
<html>
  <body>
    <slot />
    <script src="/path/to/chat-widget.js"
            data-api-url={apiUrl}
            data-title="Pregúntame lo que sea"
            data-position="bottom-right"
            data-theme="auto"
            defer is:inline></script>
  </body>
</html>

is:inline evita que Astro transforme/hash el <script>, así los atributos data-* sobreviven.

5.3 React / Next.js: el mismo <script>

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link rel="stylesheet" href="/chat-widget.css" />
        <Script src="/chat-widget.js"
                data-api-url={process.env.NEXT_PUBLIC_CHAT_API_URL}
                data-title="Pregúntame lo que sea"
                data-position="bottom-right"
                data-theme="auto"
                strategy="afterInteractive" />
      </head>
      <body>{children}</body>
    </html>
  );
}

5.4 Si querés un proxy server-side (Astro/Next API route)

El widget también puede llamar a un endpoint same-origin que reenvía al bot. Esto tiene sentido cuando necesitás:

• Auth en /api/chat (solo usuarios logueados)
• Rate limiting centralizado a nivel sitio
• Ocultar el origen del bot al browser

// src/pages/api/chat.ts (Astro) o app/api/chat/route.ts (Next)
const CHAT_BOT_URL = process.env.CHAT_BOT_URL || "http://localhost:7331";

export const POST = async ({ request }) => {
    const body = await request.json();
    // (opcional) auth check, rate limit, session lookup acá

    const resp = await fetch(`${CHAT_BOT_URL}/api/chat`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(body),
    });

    return new Response(resp.body, {
        status: resp.status,
        headers: {
            "Content-Type": "text/event-stream",
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
        },
    });
};

Entonces apuntás el widget a /api/chat (mismo origen) en vez de la URL del bot.

5.5 Referencia de configuración del widget

Todas las opciones son atributos data-* en el <script>:

Atributo	Default	Notas
data-api-url	(requerido)	URL base del bot. Sin slash final.
data-title	"Chat"	Texto del header.
data-greeting	""	Primer mensaje del asistente al abrir el panel.
data-position	"bottom-right"	"bottom-right" o "bottom-left".
data-theme	"auto"	"auto" (sigue el OS), "light", "dark".

El theming se hace vía CSS custom properties en .rony-chat-widget-root (ver web/chat-widget.css):

.rony-chat-widget-root {
  --rony-accent: #ff6b35;
  --rony-radius: 4px;
  --rony-font: "Inter", sans-serif;
}

5.6 Lo que el widget NO hace (aún)

• Persistencia de conversación — cada visita es nueva. El bot es stateless.
• Markdown enriquecido (tablas, imágenes) — el renderer built-in cubre los casos comunes; para CommonMark completo, cambiá renderMarkdown por marked o markdown-it.
• Swipe-to-dismiss en mobile — el panel pasa a full-screen en mobile, sin gesto.
• Historial de conversaciones — solo se ve la conversación activa.

---

🤖 6. Self-hosting con llama.cpp (default)

6.1 Setup

llama-server es un proceso separado al que el bot se conecta por HTTP. Ambos puertos (el del bot y el de llama-server) son configurables — elegí lo que se ajuste a tu entorno.

# 1. Asegúrate de tener un modelo GGUF disponible
# Descárgalo de Hugging Face, ej.:
#   https://huggingface.co/Qwen/Qwen2.5-3B-Instruct-GGUF
export RONY_MODELS_PATH=/path/to/models
ls $RONY_MODELS_PATH/qwen2.5-3b-instruct-q4_k_m.gguf

# 2. Arrancar llama-server (puerto configurable; default de llama.cpp es 8080)
llama-server \
  -m $RONY_MODELS_PATH/Qwen2.5/qwen2.5-3b-instruct-q4_k_m.gguf \
  --port 9100 --host 127.0.0.1 \
  --ctx-size 4096 --parallel 1 \
  --device none --threads 2 --mlock \
  --temp 0.7 --top-k 20 --top-p 0.8 --repeat-penalty 1.05

# 3. Arrancar el servidor de embeddings (segundo proceso, segunda terminal)
llama-server \
  -m $RONY_MODELS_PATH/embeddings/nomic-embed-v2-moe.Q5_K_M.gguf \
  --port 9200 --embedding --pooling mean \
  --ctx-size 2048 --parallel 1 --device none --threads 2

# 4. Verifica que configs/portfolio-bot.yaml apunte a los mismos puertos
#    providers[0].endpoint: http://localhost:9100/v1
#    embeddings.endpoint:   http://localhost:9200/v1

# 5. Construir el índice (necesita el embebedor arriba — los vectores se crean acá)
./bin/chat-bot reindex

# 6. Arrancar el bot (puerto default 7331, también configurable)
./bin/chat-bot serve
# → Sirve en http://localhost:7331
# → Override: ./bin/chat-bot serve --port 9101 --host 127.0.0.1

Flags que no son opcionales, cada una por una razón medida:

Flag	Por qué
--device none	llama.cpp levanta el backend de GPU compilado aunque pases -ngl 0, y en un host sin GPU esos buffers salen de la RAM del sistema. Medido en qwen2.5-3b: 2,54 GB con una GPU absorbiéndolos, 3,66 GB sin ella. Presupuestá con el segundo número
--parallel 1	--ctx-size se reparte entre slots y el default son 4, así que --ctx-size 4096 sin esto le deja 1024 tokens a cada petición
--mlock	Previene swap — crítico en un VPS compartido
--temp / --top-k / --top-p	Usá los valores que publican los autores del modelo, no los defaults de llama.cpp. gemma-3-1b con temperature 0.7 y el resto sin setear devolvía respuestas de 16 tokens
--pooling mean (embebedor)	Sin ella el endpoint no devuelve un vector por entrada y el cliente rechaza la respuesta

Referencia de puertos:

Qué	Default	Cómo cambiarlo
Puerto HTTP de llama-server	8080 (convención de llama.cpp)	flag --port N al arrancar llama-server
Puerto del llama-server de embeddings	8080 (misma convención)	--port N; este repo usa 9200
Puerto HTTP del chat-bot	7331	flag --port N en serve, o server.port en YAML
URL bot → llama-server	http://localhost:8080/v1	campo endpoint del provider en YAML

Mantené context_size en el YAML igual a --ctx-size: el bot calcula sus presupuestos de RAG y compactación a partir de ese número y nunca le pregunta al servidor qué tiene en realidad, así que un desacople significa prompts que el servidor rechaza.

El provider llamacpp se importa desde rony-llm-agent/pkg/llm/providers/llamacpp y habla HTTP con el servidor de arriba — sin CGO, sin enlazar contra llama.cpp.

6.2 Alternativa: Ollama (más fácil para desarrollo)

Si prefieres no gestionar archivos GGUF manualmente, Ollama ofrece los mismos modelos con un flujo más simple:

# 1. Instalar Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 2. Descargar modelo de chat
ollama pull qwen2.5:1.5b

# 3. Verificar
ollama list

# 4. Editar configs/portfolio-bot.yaml para marcar ollama-local como default:
#    providers[0].default: true (y quitar default de llamacpp-local)
#    Ollama expone una API OpenAI-compatible en :11434/v1

# 5. Arrancar el bot
ollama serve &
./bin/chat-bot serve

6.3 Alternativa: llama.cpp directo (avanzado)

Para más control o si Ollama no funciona en tu setup:

providers:
  - name: llamacpp-local
    type: llamacpp
    model: qwen2.5-3b-instruct
    endpoint: http://localhost:9100/v1   # configurable, ver §6.1
    context_size: 4096                   # debe coincidir con --ctx-size
    max_tokens: 640
    temperature: 0.7                     # defaults publicados de Qwen instruct
    top_k: 20
    top_p: 0.8
    repeat_penalty: 1.05
    default: true

El adapter llamacpp se importa desde rony-llm-agent/pkg/llm/providers/llamacpp y habla HTTP con llama-server — sin CGO, sin enlazar contra llama.cpp.

---

📦 7. CLI del bot

7.1 Comandos

# Arrancar servidor HTTP
chat-bot serve [--port 7331] [--host 0.0.0.0] [--reindex-on-start]

# Re-indexar (lee data/projects/ + data/docs/ *.md y *.mdx → FTS5 + vectores)
# Necesita el servidor de embeddings arriba si los embeddings están activos.
chat-bot reindex

# Pregunta única (sin servidor, útil para tests)
chat-bot ask "¿Qué proyectos tiene Victor?" [--no-rag]

# Validar config
chat-bot config validate

# Health check (útil para monitoring)
chat-bot health

# Versión
chat-bot version

7.2 Implementación con Cobra

// cm./rony-chat-bot/main.go
package main

import (
    "github.com/spf13/cobra"
)

func main() {
    root := &cobra.Command{
        Use:   "chat-bot",
        Short: "Portfolio chatbot HTTP server",
    }
    
    root.AddCommand(serveCmd())
    root.AddCommand(reindexCmd())
    root.AddCommand(askCmd())
    root.AddCommand(configCmd())
    root.AddCommand(healthCmd())
    root.AddCommand(versionCmd())
    
    if err := root.Execute(); err != nil {
        os.Exit(1)
    }
}

func serveCmd() *cobra.Command {
    var port int
    var host string
    var reindexOnStart bool
    
    cmd := &cobra.Command{
        Use:   "serve",
        Short: "Start HTTP server",
        RunE: func(cmd *cobra.Command, args []string) error {
            return server.Serve(server.Config{
                Port:           port,
                Host:           host,
                ReindexOnStart: reindexOnStart,
            })
        },
    }
    
    cmd.Flags().IntVar(&port, "port", 7331, "HTTP port")
    cmd.Flags().StringVar(&host, "host", "0.0.0.0", "HTTP host")
    cmd.Flags().BoolVar(&reindexOnStart, "reindex-on-start", false, "Re-index RAG before serving")
    
    return cmd
}

---

🚀 8. Deployment

8.1 Recomendación: Self-hosted en VPS

Target: 2 cores de CPU, 8 GB de RAM, sin GPU. Tres procesos — el bot y dos instancias de llama-server — así que tres units. El bot depende de los dos.

# 1. Build
go build -o /usr/local/bin/chat-bot ./cmd/chat-bot

# 2. El LLM
cat > /etc/systemd/system/llama-chat.service <<EOF
[Unit]
Description=llama-server (modelo de chat)
After=network.target

[Service]
Type=simple
User=chatbot
ExecStart=/usr/local/bin/llama-server \\
  -m /opt/models/Qwen2.5/qwen2.5-3b-instruct-q4_k_m.gguf \\
  --port 9100 --host 127.0.0.1 \\
  --ctx-size 4096 --parallel 1 \\
  --device none --threads 2 --mlock \\
  --temp 0.7 --top-k 20 --top-p 0.8 --repeat-penalty 1.05
Restart=on-failure
# --mlock necesita que la memoria se pueda bloquear
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target
EOF

# 3. El embebedor
cat > /etc/systemd/system/llama-embed.service <<EOF
[Unit]
Description=llama-server (embeddings)
After=network.target

[Service]
Type=simple
User=chatbot
ExecStart=/usr/local/bin/llama-server \\
  -m /opt/models/embeddings/nomic-embed-v2-moe.Q5_K_M.gguf \\
  --port 9200 --host 127.0.0.1 \\
  --embedding --pooling mean \\
  --ctx-size 2048 --parallel 1 --device none --threads 2
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

# 4. El bot
cat > /etc/systemd/system/chat-bot.service <<EOF
[Unit]
Description=Portfolio Chat Bot
After=network.target llama-chat.service llama-embed.service
Wants=llama-chat.service llama-embed.service

[Service]
Type=simple
User=chatbot
WorkingDirectory=/opt/chat-bot
ExecStart=/usr/local/bin/chat-bot serve
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now llama-chat llama-embed chat-bot

# 5. Construir el índice una vez que los dos servidores estén arriba
sudo -u chatbot /usr/local/bin/chat-bot reindex

Presupuesto de memoria. 3,64 GB (LLM) + 0,91 GB (embebedor) + 0,02 GB (bot) ≈ 4,6 GB residentes, dejando ~3,4 GB para lo demás que comparta el VPS. Presupuestá con --device none puesto: sin esa flag los números se ven ~1,1 GB más chicos en una máquina con GPU y después no se reproducen en producción. Ver vps-context-sizing.md.

reindex hay que volver a correrlo después de editar el markdown y después de activar o cambiar el modelo de embeddings — los vectores se construyen al indexar, y un cambio de modelo altera la dimensión.

8.2 Reverse proxy (Caddy)

# /etc/caddy/Caddyfile
chat.victorvargas.dev {
    reverse_proxy localhost:7331
}

8.3 Monitoring

# Health check periódico
curl -s http://localhost:7331/api/health | jq

# Logs
journalctl -u chat-bot -f

---

🧪 9. Testing

9.1 Unit tests

// internal/server/chat_test.go
package server

func TestHandleChat_ValidRequest(t *testing.T) {
    s := newTestServer(t)
    
    req := httptest.NewRequest("POST", "/api/chat", strings.NewReader(`{
        "messages": [{"role": "user", "content": "hola"}]
    }`))
    req.Header.Set("Content-Type", "application/json")
    
    w := httptest.NewRecorder()
    s.handleChat(w, req)
    
    assert.Equal(t, 200, w.Code)
    assert.Equal(t, "text/event-stream", w.Header().Get("Content-Type"))
}

func TestHandleChat_RateLimit(t *testing.T) {
    s := newTestServerWithConfig(t, server.Config{
        RateLimit: 1, // 1 request per minute
    })
    
    // First request OK
    req1 := newChatRequest("hola")
    w1 := httptest.NewRecorder()
    s.handleChat(w1, req1)
    assert.Equal(t, 200, w1.Code)
    
    // Second request denied
    req2 := newChatRequest("hola de nuevo")
    w2 := httptest.NewRecorder()
    s.handleChat(w2, req2)
    assert.Equal(t, 429, w2.Code)
}

9.2 Integration tests con mock LLM

// internal/agent/runner_test.go
func TestRunner_RAGContextIsInjected(t *testing.T) {
    mockLLM := mock.New(mock.Responses{
        {Match: "proyectos", Response: "Victor tiene varios proyectos..."},
    })
    
    memory := newMockMemoryWithDocs(t, []rag.Fragment{
        {Content: "Rony TUI: AI agent harness...", ProjectID: "rony-tui"},
        {Content: "rony-llm-agent: librería Go...", ProjectID: "rony-llm-agent"},
    })
    
    runner := agent.NewRunner(agent.Config{
        LLM:    mockLLM,
        Memory: memory,
        Persona: testPersona,
    })
    
    resp, _ := runner.Run(context.Background(), []llm.Message{
        {Role: llm.RoleUser, Content: "¿qué proyectos tiene Victor?"},
    })
    
    // Verify LLM received context chunks in system prompt
    lastReq := mockLLM.LastRequest()
    assert.Contains(t, lastReq.Messages[0].Content, "Rony TUI")
    assert.Contains(t, lastReq.Messages[0].Content, "rony-llm-agent")
}

9.3 E2E test con Astro

# 1. Arrancar chat-bot en :7331
./bin/chat-bot serve &

# 2. Arrancar Astro en :4321
cd ../portfolio && npm run dev &

# 3. Hacer request al proxy de Astro
curl -X POST http://localhost:4321/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hola"}]}'

# 4. Verificar SSE stream

9.4 Tests de recuperación

La recuperación es la parte de este bot donde una regresión es silenciosa — nada falla, las respuestas simplemente empeoran de a poco — así que cada falla encontrada en las pruebas tiene un test que la fija. Los ejemplos de código de arriba son ilustrativos; estos son reales.

Test	Qué fija
TestHybridSearchFindsChunkKeywordSearchCannot	El hueco pregunta-en-español / documento-en-inglés, la razón de ser de los embeddings
TestHybridSearchFallsBackWhenEmbedderFails	Un endpoint de embeddings caído degrada a keyword-only, nunca falla la petición
TestVectorSearchIgnoresVectorsWhoseChunkChanged	Los vectores obsoletos tras editar un cuerpo se ignoran
TestVectorSearchIgnoresMismatchedDimensions	Cambiar el modelo de embeddings no produce similitudes basura
TestReindexSkipsTheDirectoryReadmes	El catálogo nunca anuncia README como proyecto
TestReindexIndexesMdxAndSeparatesDocsFromProjects	El .mdx se indexa; el CV se busca pero nunca se lista
TestOpenStoreMigratesIndexWithoutKindColumn	Actualizar una instalación existente no requiere migración
TestSubSplitPrefersH3BoundariesOverByteOffsets	Los empleos del CV quedan enteros en vez de cortados a mitad de palabra
TestBuildMessagesFoldsSystemNotesIntoOneSystemMessage	La compactación no puede reintroducir el HTTP 400
TestLanguageDirectiveIsLastInSystemPrompt	La directiva conserva la posición que necesita para funcionar

Corren contra SQLite real y un embebedor de prueba, así que no hace falta ningún servidor de modelos: go test ./... alcanza.

---

📂 10. Estructura del Proyecto

rony-chat-bot/
├── cmd/
│   └── chat-bot/
│       └── main.go                 # Entrypoint CLI
│
├── internal/
│   ├── server/                     # HTTP handlers
│   │   ├── server.go               # chi router + middleware
│   │   ├── handlers.go             # /api/chat, /api/health, /api/info, /api/reindex
│   │   └── middleware.go           # RequestID, Logging, CORS, RateLimit
│   │
│   ├── agent/                      # LLM client + RAG runner
│   │   ├── runner.go               # Wrapper Stream, inyección de RAG en system prompt
│   │   └── client.go               # Factory NewClient: llamacpp / ollama / openai / anthropic
│   │
│   ├── portfolio/                  # RAG: markdown → SQLite FTS5 + vectores
│   │   ├── chunker.go              # Heading-based splitter, sub-split en ###
│   │   ├── indexer.go              # Store: schema, Reindex, Search (BM25), Catalog
│   │   ├── hybrid.go               # HybridSearch: BM25 ⊕ vectores vía RRF, EmbedChunks
│   │   └── chunker_test.go / store_test.go / hybrid_test.go
│   │
│   ├── embed/                      # Cliente de embeddings
│   │   ├── embed.go                # Embed, Normalize, Similarity, Encode/Decode
│   │   └── embed_test.go
│   │
│   ├── persona/                    # Bridge persona → rony-llm-agent
│   │   └── persona.go              # FromConfig, BuildSystemPrompt (con contexto RAG)
│   │
│   ├── streaming/                  # Helpers protocolo SSE
│   │   └── sse.go                  # WriteStart/Chunk/Sources/Done/Error
│   │
│   ├── i18n/                       # Detección de idioma (ES/EN) para la respuesta
│   │
│   └── config/                     # Loader YAML + validación
│
├── web/                            # ← WIDGET DE CHAT DROP-IN
│   ├── chat-widget.js              # Vanilla JS, ~12 KB
│   ├── chat-widget.css             # Estilos scoped, themable vía CSS custom props
│   ├── example.html                # Demo local (python -m http.server)
│   └── README.md                   # Guía de integración (HTML, Astro, Next.js)
│
├── data/
│   ├── projects/                   # ← Un .md/.mdx por proyecto — se lista en el catálogo
│   │   ├── rony-tui.md
│   │   ├── rony-llm-agent.md
│   │   ├── example-project.md
│   │   └── README.md               # Instrucciones; el indexer lo salta
│   │
│   └── docs/                       # ← Material de referencia que NO es proyecto
│       ├── cv.mdx                  # Normalmente un símlink; gitignoreado
│       └── README.md               # Instrucciones; el indexer lo salta
│
├── configs/
│   └── portfolio-bot.yaml          # Provider + RAG + persona config
│
├── docs/
│   ├── architecture.md             # ← THIS FILE
│   └── architecture.es.md
│
├── bench/                          # Benchmark reproducible de drivers SQLite
│
├── go.mod                          # require rony-llm-agent, modernc.org/sqlite
└── README.md

---

📅 11. Roadmap

Fase 1: MVP — hecho

• Setup proyecto (go mod init, estructura)
• HTTP server con un endpoint /api/chat
• SSE streaming funcional
• RAG indexer (data/projects/ + data/docs/, .md + .mdx → FTS5)
• RAG retriever (query → top-k chunks)
• Persona loader desde YAML
• Integración con llama.cpp — qwen2.5-3b, no el 1.5b planeado
• CLI: serve, reindex, ask
• Tests básicos

Fase 2: Integración con Astro — hecho, de otra forma

• Widget drop-in en vanilla JS — reemplazó al componente React y a la ruta proxy de Astro que estaban planeados. Sin build step, sin atarse a un framework, y funciona en las tres topologías de §5.1 en vez de solo detrás de un proxy
• Styling del widget — CSS scoped con custom properties, no TailwindCSS; un widget drop-in no puede asumir el toolchain del sitio
• E2E test automatizado: Astro → chat-bot → respuesta (sigue siendo manual, §9.3)

Fase 3: Polish — hecho

• Rate limiting por IP
• Logging estructurado (JSON)
• Health checks para monitoring
• systemd service files (§8.1)
• README + docs de deployment

Fase 4: Opcionales — casi todo hecho

• Múltiples conversaciones (session ID)
• Historial de chats persistido
• Multi-idioma (EN/ES) — detección más un prompt completo en español, §4.4
• Auto-compactación para hilos largos, §4.5
• Análisis de preguntas frecuentes
• Versión standalone CLI más pulida (chat-bot ask)

Fase 5: Calidad de respuesta — hecho

Todo lo de acá salió de medir respuestas reales, no del plan original; cada punto existe porque algo estaba observablemente mal.

• Recuperación híbrida (BM25 ⊕ embeddings, RRF) — §4.2
• Guarda de content-hash contra vectores obsoletos — §4.2
• Catálogo de proyectos inyectado en cada turno, para frenar los nombres inventados
• Documentos de referencia separados de los proyectos, para que el CV se pueda buscar sin quedar listado como proyecto — §4.1
• Parámetros de sampling del fabricante cableados desde la config a llama.cpp
• context_size bajado de 8192 a 4096 según el uso medido — §4.5

Conocido y sin arreglar

Anotado para que no se vuelva a reportar como bug nuevo:

• El modelo lee bien las fechas del CV pero hace mal la aritmética sobre ellas — "Jul 2024 – Jun 2026" reportado como tres años.
• A veces atribuye un dato al archivo fuente equivocado.
• "¿Dónde ha trabajado Victor?" responde con proyectos en vez de empleadores. Depende del fraseo: "¿En qué empresas ha trabajado?" y "¿Cuánto tiempo estuvo en Metrimex?" responden bien.

---

📐 12. Especificaciones de Calidad

12.1 Métricas de rendimiento

Métrica	Target	Medido en el target de 2 cores solo-CPU
Latencia de recuperación (top-5, híbrida)	<50ms	~40ms — 37ms son el round-trip de embeber la consulta; BM25 y el scan de vectores son sub-milisegundo
Memoria del proceso del bot	<150MB	~20MB
Huella total (bot + LLM + embebedor)	entra en 8GB con margen	~4,6GB (3,64 + 0,91 + 0,02), dejando ~3,4GB para el resto del host
Throughput de generación	—	21,0 tok/s en estado estable, ~11 tok/s en la primera petición en frío
TTFT (Time-to-first-token)	<500ms	No se cumple, y no es alcanzable acá. Dos threads tienen que hacer el prefill de un prompt de ~1100 tokens antes del primer token. El target original asumía una máquina con GPU
End-to-end (pregunta → respuesta completa)	<3s	No se cumple: ~21s para una respuesta típica. El bot no es el cuello de botella; un modelo 3B sobre 2 cores sí

Las dos últimas filas son el costo honesto de la restricción de hardware, y el widget está construido alrededor de eso: las respuestas se transmiten token a token, así que el visitante ve texto moviéndose en un par de segundos en vez de esperar 21s por un bloque. Recuperar cualquiera de los dos targets significa un modelo más chico, y el benchmark de 20 preguntas en configs/portfolio-bot.yaml mide lo que eso cuesta en precisión — gemma-3-1b promedia 13,8s contra los 21,0s de qwen, y responde 6 preguntas menos de cada 10 correctamente.

12.2 Pruebas requeridas

• Unit tests: cobertura ≥70%
• Integration tests: con mock LLM + SQLite FTS5 en memoria
• E2E: al menos un flujo completo Astro → chat-bot

---

🔒 13. Seguridad

13.1 Implementado

• Rate limiting por IP (default 30 req/min)
• CORS restrictivo — solo origins configurados
• Input validation — JSON schema validation en requests
• No PII storage — no guardamos conversaciones por default
• Local-only por default — sin llamadas a APIs cloud

13.2 Diferido / Opcional

• Auth con API key (para uso privado)
• Logging de queries para analytics
• Anonymization de IPs en logs
• HTTPS via reverse proxy (Caddy/nginx)

---

📚 14. Referencias

• SSE Spec: https://html.spec.whatwg.org/multipage/server-sent-events.html
• Ollama API: https://github.com/ollama/ollama/blob/main/docs/api.md
• SQLite FTS5: https://www.sqlite.org/fts5.html
• Go SQLite driver: https://github.com/mattn/go-sqlite3 (CGO) o https://modernc.org/sqlite (Go puro)
• qwen2.5-3b-instruct: https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
• nomic-embed-text-v2-moe: https://huggingface.co/nomic-ai/nomic-embed-text-v2-moe-GGUF
• Reciprocal Rank Fusion: Cormack, Clarke & Büttcher (2009), Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods
• Astro API routes: https://docs.astro.build/en/guides/endpoints/
• rony-llm-agent: https://github.com/VictorVargas/rony-llm-agent

---

Documento listo para implementación. 🚀