tribai.co
trib·ai·.co = tributaria + AI + Colombia

tribai — Plataforma Tributaria IA de Colombia

La plataforma tributaria mas completa de Colombia. 40 calculadoras fiscales, 1,301 articulos del Estatuto Tributario indexados con Contextual Retrieval, asistente IA con RAG avanzado de 12 modulos sobre ~93,000 vectores en 7 namespaces (Pinecone), doctrina DIAN (15K+), jurisprudencia CC/CE (17K+ vectores), DUR 1625 (2,142 articulos), 207 leyes, calendario fiscal 2026 (17 obligaciones), indicadores economicos, guias interactivas, glosario tributario y herramientas de productividad profesional.

Produccion: tribai.co

---

Indice

• Stack Tecnologico
• Asistente IA — Pipeline RAG
• 40 Calculadoras Tributarias
• Modulos de Referencia
• Explorador del Estatuto Tributario
• Sistema de Chat — Workspace Profesional
• App Nativa iOS (SwiftUI)
• Normograma DIAN
• Arquitectura de Archivos
• Base de Conocimiento
• Evaluacion RAG
• Testing
• CI/CD
• Desarrollo Local
• Variables de Entorno
• Constantes Tributarias 2026
• Roadmap — Proximos Pasos
  • Palanca 1: WhatsApp Bot
  • Palanca 2: Gemini Live Voice Agent
  • Palanca 3: API Publica + Widget
  • Backlog Tecnico
  • Backlog de Producto
  • Timeline
• Licencia

---

Stack Tecnologico

Capa	Tecnologia	Version
Framework	Next.js (App Router, Turbopack)	16.1.6
UI	React	19.2.3
Estilos	Tailwind CSS v4 (CSS-first, @theme inline)	4.x
Lenguaje	TypeScript (strict mode)	5.x
IA — LLM	Claude Sonnet 4.5 via Vercel AI SDK	@ai-sdk/anthropic 3.0.44
IA — Query rewrite	Claude Haiku 4.5	claude-haiku-4-5-20251001
IA — Fallback	OpenAI GPT-4o	@ai-sdk/openai 3.0.33
IA — Embeddings	multilingual-e5-large (1024d)	Pinecone Inference
Vector DB	Pinecone (7 namespaces, ~93,000 vectores)	SDK 7.x
Auth	Clerk	@clerk/nextjs 7.0.4
Pagos	Stripe	20.4.1
KV / Rate Limit	Vercel KV (Redis)	@vercel/kv 3.0.0
Graficas	Recharts	3.7
Grafos	react-force-graph-2d + Cytoscape + graphology
Markdown	react-markdown + remark-gfm	10.1.0
Sanitizacion	isomorphic-dompurify	3.0.0
Precision financiera	decimal.js	10.6.0
Validacion	Zod v4	4.3.6
Documentos	pdf-parse + mammoth (DOCX) + xlsx
Iconos	lucide-react	0.564.0
Temas	next-themes (dark mode)	0.4.6
Analytics	Vercel Analytics	1.6.1
PWA	Service Worker + manifest.json
iOS	SwiftUI (Xcode, Swift Package Manager)
E2E	Playwright	1.58.2
Deploy	Vercel (auto-deploy on push to main)

46 dependencias de produccion, 10 de desarrollo.

---

Asistente IA — Pipeline RAG

Pipeline RAG de 12 modulos con recuperacion multi-hop en 7 namespaces, confidence scoring, deteccion de contradicciones, formato dictamen auditado y preferencias de tono.

Flujo del Pipeline (8 etapas)

Query del usuario
    |
[0] Cache Check — LRU (500 entries, 24h TTL, normalized key)
    | (miss)
[1] Query Enhancement (Haiku 4.5)
    |-- Early-exit: queries directas (Art. X) saltan LLM calls (<100ms)
    |-- Rewrite: reformula con terminologia legal colombiana
    |-- HyDE: genera respuesta hipotetica para embedding
    |-- Decomposition: descompone queries complejas en sub-queries
    |-- Query expansion: sinonimos y terminos legales
    |
[2] Query Routing (namespace-router.ts)
    |-- classifyQueryType: factual | comparative | procedural | temporal | doctrina | sanctions
    |-- getQueryRoutingConfig: topK, maxReranked, namespaces dinamicos por tipo
    |-- Detect article slugs para multi-hop
    |
[3] Retrieval (Pinecone — 7 namespaces)
    |-- Ronda 1: ET (namespace default) — topK: 20, threshold: 0.28
    |-- Ronda 1b: 6 namespaces externos — topK: 15, umbrales especificos
    |-- Ronda 2 (Multi-hop): busca fuentes que citen articulos recuperados
    |-- Speculative retrieval: threshold 0.80 para fast-path
    |-- Cross-namespace normalization (min-max scaling)
    |
[4] Heuristic Reranking (2 pipelines paralelos)
    |-- ET Reranking: chunk_type boost, article mention, title overlap, derogated penalty
    |-- Multi-Source Reranking: PageRank, community, doctrina vigente, sentencia SU/C
    |
[5] Context Assembly
    |-- Sibling retrieval: todos los chunks del mismo articulo
    |-- Token budget: 13,000 tokens max
    |-- Namespace diversity: round-robin + greedy fill
    |
[6] Evidence Check (heuristic, <5ms)
    |-- Confidence: high (>= 0.75 + 3 sources) | medium (>= 0.55) | low
    |-- Contradiction detection: derogated+vigente conflicts
    |-- Namespace contribution tracking
    |
[7] Prompt Building
    |-- System prompt con constantes 2026 + tone preset inyectado
    |-- 40 sugerencias de calculadoras (dinamicas por keyword)
    |-- Contexto RAG en XML: <context>, <evidence>, <contradiction_warning>
    |-- <obsolete_norms> block: normas derogadas
    |
[8] Streaming Response (Sonnet 4.5)
    |-- Metadata on finish: sources, ragMetadata, timestamp
    |-- smoothStream (10ms delay, word chunking)
    |-- Multi-provider fallback: Anthropic -> OpenAI

Configuracion RAG

topK: 20                      similarityThreshold: 0.28
maxContextTokens: 16,000      maxRerankedResults: 10
useHyDE: true                 useQueryExpansion: true
useSiblingRetrieval: true      useMultiNamespace: true
speculativeThreshold: 0.75     externalSourceBudgetRatio: 0.30

Namespaces: "", doctrina, jurisprudencia, decretos, resoluciones, leyes, procedimientos
Embedding: multilingual-e5-large (1024d, cache 5,000 entries)
Hybrid: BM25 + Vector RRF fusion (alpha=0.08)
Contextual Retrieval: 3,757 chunks enriched with Haiku context prefixes
Neural Reranker: Cloud Run cross-encoder (with heuristic fallback)

Metricas RAG (Post Content Expansion — Marzo 2026)

Metrica	Valor	Target	Status
P@5 adj	0.853	>= 0.85	MET
Recall@5	0.571	>= 0.55	MET
MRR	0.414	>= 0.38	MET
Citation Acc	0.667	>= 0.65	MET
Completeness	0.902	>= 0.91	-0.9%
Error Rate	26.6%	< 35%	MET
Abstention Quality	0.629	>= 0.57	MET
Avg Latency	1,120ms	<= 1,200	MET
Complex P@5	0.208	>= 0.29	In progress
Ext Src Retrieved	0.993	>= 0.99	MET
Ext Src in Context	0.820	>= 0.88	In progress

Modos de Respuesta

Modo	LLM	Descripcion
Rapido	Haiku 4.5	Respuestas agiles, sin deep retrieval
Profundo	Sonnet 4.5	Analisis completo con RAG + Chain of Thought
Agente	Opus 4.6 + herramientas	Investigacion agentica multi-step

Tonos de Respuesta (Phase 3 — User Preferences)

Tono	Descripcion
Profesional	Formal, terminologia tecnica precisa, citacion completa
Didactico	Paso a paso, ejemplos practicos, analogias claras
Tecnico	Conciso, solo citas normativas y tablas numericas
Ejecutivo	Bullet points, resumen arriba, max 2 parrafos

---

40 Calculadoras Tributarias

Categoria	Calculadoras
Renta (11)	Renta PN, Renta PJ, Dividendos PN, Dividendos PJ, Anticipo de Renta, Beneficio Auditoria, Descuentos Tributarios, Zonas Francas, Comparador Regimenes, Residencia Fiscal, Limites de Beneficios
Laboral (9)	Nomina Completa, Comparador Contratacion, Seguridad Social, Retencion Salarios Proc. 1, Liquidacion Laboral, Horas Extras, Licencia Maternidad/Paternidad, Pension, Utilidades Gravadas
Patrimonio (4)	Impuesto al Patrimonio, Ganancias Ocasionales (Inmuebles), Herencias y Donaciones, Comparacion Patrimonial
Sanciones (3)	Extemporaneidad, Sanciones Ampliadas, Intereses Moratorios DIAN
IVA (2)	Referencia IVA, Impuesto al Consumo
Otros (11)	Conversor UVT, GMF (4x1000), Timbre, ICA Municipal, Ganancias Loterias, Depreciacion Fiscal, Debo Declarar?, SIMPLE (RST), Descuento Exterior

Top 5 destacadas: Retencion en la Fuente, Renta PN, Comparador Contratacion, Debo Declarar?, Nomina Completa.

Cada calculadora incluye: articulos del ET vinculados, badges ("Actualizado 2026", "Incluye reforma", "Nuevo"), calculadoras relacionadas, tags de busqueda e intents para el command palette.

---

Modulos de Referencia

Modulo	Ruta	Descripcion
Calendario Tributario 2026	/calendario	Vencimientos con filtros por obligacion y digito NIT, integracion calendario personal (ICS)
Tabla de Retencion	/tablas/retencion	Conceptos, bases y tarifas de retencion con calculadora inline
Indicadores Economicos	/indicadores	UVT, SMLMV, inflacion, tasa de usura con graficas historicas (Recharts)
Glosario Tributario	/glosario	Terminos clave del derecho tributario colombiano A-Z
Doctrina DIAN	/doctrina	Conceptos y oficios curados de la DIAN
Novedades Normativas	/novedades	Timeline de cambios legislativos y reformas tributarias
Guias Interactivas	/guias	Arboles de decision para procesos tributarios comunes
Declaracion de Renta	/declaracion-renta	Wizard de planificacion fiscal PN
Declaracion Renta PJ	/declaracion-renta-juridicas	Wizard de planificacion fiscal PJ
Planes y Precios	/planes	Suscripciones con Stripe

---

Explorador del Estatuto Tributario

• 1,294 articulos del ET navegables con SSG (build-time)
• Busqueda por numero, titulo o contenido
• Clasificacion por 7 libros y titulos
• Comparador de articulos (diff entre versiones)
• Knowledge graph interactivo con 540 nodos (react-force-graph-2d)
• Metricas por articulo: PageRank, community detection (Louvain), degree centrality
• Dashboard analitico con estadisticas del corpus
• Sistema de favoritos con notas y workspaces de productividad
• Cross-references bidireccionales entre articulos
• Concordancias: DUR 1625, Resolucion Unica, CDIs

---

Sistema de Chat — Workspace Profesional

Funcionalidades Core (P0)

• Sidebar workspace con historial de conversaciones
• Busqueda full-text con trigrams + substring matching
• Mobile drawer responsivo
• Conversation header con titulo editable, metadatos y badges
• Separadores temporales entre mensajes (>30 min gap)
• URL deep-linking (?conv=<id>)
• Panel de evidencia RAG (confidence + pipeline details)
• Lead capture funnel (3 free → lead → 8 free → auth)

Funcionalidades Avanzadas (10-Phase Plan)

Fase	Feature	Descripcion
1	Cmd+K Unificado	Command palette federado con 4 fuentes: navegacion, conversaciones, 40 calculadoras, 1,294 articulos. Filtros: art:, #, mode:
2	Starter Packs	5 packs de prompts por categoria (Renta PN, IVA, Retencion, Planificacion, Litigio) en el empty state
3	User Preferences + Tono	Preferencias persistentes (localStorage) con 4 tonos inyectados en system prompt
4	ChatContainer Decomp	Monolito de 1,265 lineas reducido a 681 extrayendo 8 modulos
5	Cmd+F In-Conversation	Busqueda dentro de mensajes con highlighting, conteo de matches, navegacion
6	Keyboard Navigation	j/k mensajes, n nuevo chat, / focus composer
7	Share Conversation	Export markdown con Web Share API, fallback clipboard
8	Pinned Messages	Panel colapsable de mensajes fijados con scroll-to-message
9	Auto-Summary	Resumen heuristico: articulos citados, terminos fiscales, montos, tipo persona
10	Batch Actions	Multi-select en sidebar con archivar/eliminar masivo

Export

• PDF — HTML formateado con print dialog
• JSON — Datos crudos de la conversacion
• CSV — Resultados de simulacion o chat plano
• Clipboard — Texto completo
• Share — Markdown con Web Share API

---

App Nativa iOS (SwiftUI)

• 40 calculadoras portadas a SwiftUI nativo
• Explorador del Estatuto Tributario offline
• Chat RAG conectado al backend
• Navegacion con 5 tabs (Home, Calculadoras, ET, Chat, Mas)
• 8 features de contenido (calendario, glosario, indicadores, doctrina, guias, novedades, favoritos, tablas)
• Widget de escritorio
• Screenshots para App Store

---

Normograma DIAN

Modulo independiente de scraping y gestion del marco regulatorio colombiano.

• Scraper de normativa DIAN
• Clasificacion de vigencia con IA
• Concordancias: DUR 1625, Resolucion Unica DIAN, CDIs
• Export a Excel completo
• Actualizaciones semanales automatizadas (GitHub Actions)
• 17 scripts de procesamiento (Python)

---

Arquitectura de Archivos

tribai/
|-- src/                                    # 450 archivos TypeScript
|   |-- app/                                # 67 paginas (App Router)
|   |   |-- api/chat/route.ts               # Streaming RAG chat endpoint
|   |   |-- api/chat/agent/route.ts         # Agent mode endpoint (Opus + tools)
|   |   |-- api/declaracion/                # Declaracion de renta endpoints
|   |   |-- api/health/route.ts             # Health check + circuit breaker
|   |   |-- api/feedback/route.ts           # User feedback endpoint
|   |   |-- api/documents/route.ts          # Document upload + parsing
|   |   |-- articulo/[slug]/page.tsx        # 1,294 articulos SSG
|   |   |-- calculadoras/                   # 40 calculadoras (client components)
|   |   |-- asistente/page.tsx              # Chat IA standalone
|   |   |-- planificacion/page.tsx          # Tax planning workspace
|   |   `-- ...                             # 18 modulos de referencia
|   |
|   |-- components/                         # 206 componentes en 24 directorios
|   |   |-- chat/                           # Chat container, bubbles, citations
|   |   |   |-- canvas/                     # Header, toolbar, empty-state, simulation
|   |   |   |-- sidebar/                    # Workspace sidebar, groups, items, actions
|   |   |   |-- hooks/                      # useKeyboardNavigation
|   |   |   |-- conversation-search.tsx     # Cmd+F in-conversation
|   |   |   |-- pinned-messages-panel.tsx   # Pinned messages
|   |   |   `-- preferences-panel.tsx       # User preferences slide-out
|   |   |-- calculators/                    # Cards, results, inputs, charts
|   |   |-- article/                        # Content, header, sidebar, timeline
|   |   |-- explorer/                       # Grid, filters, search, graph
|   |   |-- dashboard/                      # Stats, charts, tables
|   |   |-- workspace/                      # Bookmarks, notes, productivity
|   |   |-- landing/                        # Hero, sections, social proof
|   |   |-- auth/                           # Sign-in, sign-up, gates
|   |   `-- ui/                             # Reveal, skeleton, spinner, toast, command-palette
|   |
|   |-- config/                             # 24 archivos de datos estaticos
|   |   |-- calculators-catalog.ts          # 40 calculadoras con metadata
|   |   |-- starter-packs.ts               # 5 packs de prompts
|   |   |-- calendar-data.ts               # Calendario fiscal 2026
|   |   |-- glosario-data.ts               # Glosario A-Z
|   |   |-- guias-data.ts                  # Arboles de decision
|   |   |-- tax-data*.ts                   # UVT, tarifas, retencion
|   |   |-- constants.ts                   # RAG config, Pinecone host
|   |   `-- obsolete-norms.ts              # Normas derogadas
|   |
|   |-- lib/                                # 162 modulos en 32 subdirectorios
|   |   |-- rag/                            # Pipeline RAG (12 modulos)
|   |   |   |-- pipeline.ts                 # Orchestrador master
|   |   |   |-- query-enhancer.ts           # Rewrite + HyDE + decompose
|   |   |   |-- namespace-router.ts         # Query classification + routing
|   |   |   |-- retriever.ts               # Multi-namespace + multi-hop
|   |   |   |-- graph-retriever.ts          # PageRank + community boost
|   |   |   |-- reranker.ts                # Heuristic scoring
|   |   |   |-- context-assembler.ts        # Sibling + token budget + diversity
|   |   |   |-- evidence-checker.ts         # Confidence + contradictions
|   |   |   |-- prompt-builder.ts           # XML context + tone injection
|   |   |   |-- bm25-search.ts             # Lexical fallback search
|   |   |   |-- keyword-retriever.ts        # Keyword fallback
|   |   |   `-- current-regime-choice.ts    # Regime selection logic
|   |   |-- chat/                           # Chat utilities (12 modulos)
|   |   |   |-- system-prompt.ts            # Dynamic system prompt + tone presets
|   |   |   |-- export-helpers.ts           # PDF, CSV, JSON, clipboard
|   |   |   |-- share-conversation.ts       # Web Share API + markdown
|   |   |   |-- conversation-summary.ts     # Auto-summary heuristic
|   |   |   |-- conversation-metadata.ts    # Meta extraction + search index
|   |   |   |-- history-storage.ts          # localStorage (30 conv, 80 msgs)
|   |   |   |-- search-engine.ts            # Full-text search (trigrams)
|   |   |   |-- session-memory.ts           # 5-turn context
|   |   |   |-- message-content.ts          # Text extraction + follow-up parsing
|   |   |   |-- calculator-context.ts       # Calculator suggestions by keyword
|   |   |   |-- chat-error.ts              # Error classification
|   |   |   `-- timestamps.ts              # Message timestamp utils
|   |   |-- cache/                          # LRU response cache (500 entries)
|   |   |-- pinecone/                       # Client singleton + embedder (2K cache)
|   |   |-- ai/                             # Provider fallback logic
|   |   |-- api/                            # Rate limiter + Zod validation
|   |   |-- auth/                           # Plans, query counters, free-use gates
|   |   |-- command-palette/                # Federated search sources
|   |   `-- ...                             # export, documents, calculators, utils
|   |
|   |-- types/                              # Type definitions
|   |   |-- rag.ts                          # EnhancedQuery, SourceCitation, RAGConfig
|   |   |-- chat-history.ts                 # ChatConversation, ChatMessageFeedback
|   |   |-- user-preferences.ts             # TonePreset, UserPreferences
|   |   `-- pinecone.ts                     # ChunkMetadata (14+ campos)
|   |
|   |-- hooks/                              # Custom React hooks
|   |   |-- useChatHistory.ts               # useSyncExternalStore for conversations
|   |   |-- useUserPreferences.ts           # Persistent user preferences
|   |   `-- useDocumentUpload.ts            # File upload hook
|   |
|   `-- contexts/                           # React contexts
|       `-- chat-layout-context.tsx         # Sidebar width, collapsed, mobile drawer
|
|-- public/data/                            # Static data assets
|   |-- articles/                           # 1,294 JSON individuales
|   |-- articles-index.json                 # 443 KB — indice rapido
|   |-- articles-index.enriched.json        # 1.4 MB — indice con metadata
|   |-- bm25-index.json                     # 1.3 MB — indice lexical
|   |-- graph-data.json                     # 376 KB — 540 nodos
|   |-- graph-metrics.json                  # 292 KB — PageRank + communities
|   |-- dashboard-stats.json                # Estadisticas del ET
|   `-- explorer-facets.json                # Facetas de filtros
|
|-- ios/                                    # App nativa SwiftUI
|   |-- SuperAppTributaria/                 # Source code (16 subdirs)
|   |-- SuperAppTributariaTests/            # Unit tests
|   |-- SuperAppTributariaUITests/          # UI tests
|   |-- SuperAppTributariaWidget/           # Widget
|   `-- Package.swift                       # SPM manifest
|
|-- normograma/                             # Normograma DIAN
|   |-- data/                               # Datos regulatorios (11 subdirs)
|   |-- scripts/                            # 17 scripts Python
|   `-- .github/workflows/                  # Actualizacion semanal
|
|-- eval/                                   # Suite de evaluacion RAG
|   |-- run_eval.ts                         # 350 queries, 17 metricas
|   |-- smoke-test.ts                       # 15 smoke tests (pass/fail)
|   |-- dataset.json                        # 300 standard + 40 complex
|   |-- baseline-results.json               # Resultados de referencia
|   |-- experiments/config-grid.ts          # Grid para sweeps
|   |-- metrics/                            # retrieval, answer-quality, faithfulness
|   `-- results/                            # Historial por timestamp
|
|-- tests/                                  # 46 archivos de test
|   |-- unit/                               # 34 unit tests
|   |-- integration/                        # 3 integration tests
|   |-- security/                           # 4 security tests
|   |-- e2e/                                # 5 Playwright specs
|   |-- load/                               # k6 load test
|   `-- helpers/                            # Mocks, fixtures
|
|-- scripts/                                # 8 build scripts
|   |-- orchestrator.ts                     # Master pipeline: scrape -> embed -> upsert
|   |-- build-analytics-datasets.mjs        # Graph, stats, facets
|   |-- build-bm25-index.mjs               # BM25 inverted index
|   `-- verify-data-integrity.mjs           # Data validation
|
|-- docs/                                   # 7 documentos operativos
|   |-- RAG-PERFECTION-PLAN.md
|   |-- RAG-V3-OPERATIONAL-PLAN.md
|   |-- V3.1-SPRINT-OPERATIONAL-PLAN.md
|   |-- release-runbook.md
|   `-- vercel-environment-matrix.md
|
`-- .github/workflows/ci.yml               # CI: lint + typecheck + build + test + e2e

---

Base de Conocimiento

~93,000 vectores en Pinecone distribuidos en 7 namespaces:

Namespace	Fuente	Documentos	Vectores	Threshold
"" (default)	Estatuto Tributario (Contextual Retrieval)	1,301 articulos	3,762	0.28
doctrina	DIAN conceptos + oficios	~15,495	56,111	0.20
jurisprudencia	Corte Constitucional + Consejo de Estado	~968 sentencias	17,455	0.20
decretos	DUR 1625/2016 + decretos varios	~2,142 articulos DUR	5,566	0.23
resoluciones	Resoluciones + Circulares DIAN	~925 docs	5,385	0.23
leyes	Leyes tributarias (207 leyes)	~207	4,546	0.23
procedimientos	Procedimientos DIAN	Var.	41	0.22

Esquema de Chunk (Pinecone metadata)

id_articulo, titulo, libro, estado, chunk_type, chunk_index,
total_chunks, complexity_score, total_mods, has_normas, vigente,
cross_references, pagerank, community, degree, articulos_slugs

Pipeline de Datos (scripts/)

Scraping (7 scrapers) -> Parsing (3 parsers) -> Chunking (512 tokens, legal-aware)
-> Metadata enrichment (PageRank, community, cross-refs) -> Embedding (multilingual-e5-large)
-> Batch upsert (96/batch, 16s delay, exponential backoff) -> Validation

---

Evaluacion RAG

Comandos

npm run smoke-test   # 20 tests, ~20s, pass/fail con exit code
npm run eval         # 350 queries, 17 metricas, ~6 min
npm run eval:judge   # + LLM Judge: 30 sample con Haiku evaluador + Sonnet respuestas (~15 min)

Dataset

• 350 queries (300 standard + 40 complejas + 10 derogation)
• Categorias: factual, comparative, procedural, temporal, edge_case, negative, sanctions, doctrina, multi_source
• Dificultad: easy (28), medium (99), hard (223)

17 Metricas

Metrica	Descripcion
P@5 adj	Precision@5 ajustada
Recall@5	Cobertura de articulos esperados
MRR	Mean Reciprocal Rank
NDCG@5	Normalized DCG
Citation Accuracy	Articulos citados correctos
Source Presence	Fuentes esperadas presentes
Contains Expected	Contenido esperado presente
Error Rate	Tasa de errores
Ext Src Retrieved	Fuentes externas recuperadas
Ext Src in Context	Fuentes externas en contexto
Abstention Quality	Calidad de abstencion
Completeness	Cobertura de aspectos
Avg Latency	Latencia promedio (ms)
P95 Latency	Percentil 95 latencia
Complex P@5	Precision para queries complejas
Complex Completeness	Completeness queries complejas
Judge Composite*	LLM Judge: faithfulness + completeness + relevance + citation + clarity

---

Testing

46 archivos de test en 5 categorias:

Tipo	Archivos	Herramienta
Unit	34	Vitest / Node test runner
Integration	3	API route testing
Security	4	XSS, injection, rate-limit abuse, cron auth
E2E	5	Playwright (Chromium)
Load	1	k6

Cobertura de Unit Tests

• Calculadoras: renta, patrimonio, ICA, dividendos, comparador, formato, popularidad, busqueda, URL state
• RAG: evidence-checker, namespace-router, reranker, regime-choice, keyword-retriever, obsolete-norms, semantic-cache
• Chat: session-memory, contextual-questions, error, message-content, search-engine, conversation-metadata, calculator-context
• Calendario: ICS export, NIT parsing, status
• API: rate-limiter, validation, feedback
• Storage: history, productivity, anonymous-query-counter
• Utils: data-integrity, comparison-diff, normalization

E2E Specs (Playwright)

• article-navigation.spec.ts — Navegacion del ET
• calculadora-flow.spec.ts — Flujo completo de calculadora
• dark-mode.spec.ts — Toggle de tema
• landing-page.spec.ts — Landing page load + sections
• responsive-mobile.spec.ts — Layout mobile

npm test                        # Unit + security
npx playwright test             # E2E (requires build)
npm run smoke-test              # RAG smoke tests

---

CI/CD

GitHub Actions (.github/workflows/ci.yml)

3 jobs con concurrency control:

1. Verify (30 min timeout)

   • npm run lint:strict — 0 warnings max
   • npm run typecheck — full TS validation
   • npm run build:ci — production build

2. Test (10 min timeout)

   • npm test — unit + security tests

3. E2E (20 min timeout, depends on Verify)

   • Install Playwright Chromium
   • npm run build:ci
   • npx playwright test

Deploy

Auto-deploy via Vercel en push a main. Cada PR genera preview deployment.

---

Desarrollo Local

git clone https://github.com/Cespial/tribai.git
cd tribai

npm install

cp .env.example .env.local
# Configurar variables requeridas (ver seccion abajo)

npm run dev          # Dev server con Turbopack (http://localhost:3000)

Comandos Utiles

npm run dev              # Dev server (Turbopack)
npm run build            # Production build (1,300+ paginas SSG)
npm run lint             # ESLint
npm run lint:strict      # Falla con warnings
npm run typecheck        # TypeScript check
npm run verify           # lint + typecheck + build

npm run smoke-test       # 15 smoke tests RAG
npm run eval             # 350 queries, 17 metricas
npm run eval:judge       # + LLM Judge

npm run data:build       # Rebuild analytics datasets
npm run data:verify      # Verificar integridad de datos

---

Variables de Entorno

Requeridas

Variable	Descripcion
ANTHROPIC_API_KEY	API key de Anthropic (Claude)
PINECONE_API_KEY	API key de Pinecone
PINECONE_INDEX_NAME	Nombre del indice (default: estatuto-tributario)

Opcionales — LLM

Variable	Descripcion
CHAT_MODEL	Modelo del chat (default: claude-sonnet-4-5-20250929)
OPENAI_API_KEY	Fallback de enhancement/reranking
OPENAI_CHAT_MODEL	Modelo OpenAI fallback (default: gpt-4o)

Opcionales — Auth y Pagos

Variable	Descripcion
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk publishable key
CLERK_SECRET_KEY	Clerk secret key
STRIPE_SECRET_KEY	Stripe secret key
STRIPE_WEBHOOK_SECRET	Stripe webhook secret
NEXT_PUBLIC_STRIPE_PRO_PRICE_ID	Stripe price ID

Opcionales — Rate Limiting

Variable	Descripcion
KV_REST_API_URL	Vercel KV (Redis) URL
KV_REST_API_TOKEN	Vercel KV token

---

Constantes Tributarias 2026

UVT 2026:               $52,374 COP (Resolucion DIAN)
SMLMV 2026:             $1,750,905 COP (Decreto 0025 de 2025)
Auxilio de transporte:   $249,095 COP (Decreto 1470 de 2025)
Tarifa renta PJ:         35% (Art. 240 ET)
Tarifa renta PN:         progresiva 0%-39% (Art. 241 ET)
IVA general:             19% (Art. 468 ET)
GMF:                     4x1000 (Art. 871 ET)
Reforma vigente:         Ley 2277 de 2022

---

---

Roadmap — Proximos Pasos

Vision: El mejor RAG tributario de Colombia + canales conversacionales

Con 93K vectores, 1,301 articulos ET, y metricas de clase mundial (MRR 0.414, P@5adj 0.853), el RAG esta maduro. El siguiente paso es distribucion — llevar la inteligencia tributaria a donde estan los 328K contadores y 6M+ declarantes.

---

Palanca 1: WhatsApp Bot — Consultor Tributario por WhatsApp

Por que: 328K contadores colombianos viven en WhatsApp. Zero competidores ofrecen un asistente tributario IA con citaciones del ET por WhatsApp. Costo: $0 por respuesta (Meta Cloud API, customer-initiated = gratis).

Sprint WA-1: Core Bot (4-6h)

#	Tarea	Detalle
WA-1.1	Setup Meta Business App	Crear app en developers.facebook.com, agregar producto WhatsApp, obtener tokens
WA-1.2	Webhook route	POST /api/whatsapp/webhook — recibe mensajes, responde 200 inmediato, procesa en after()
WA-1.3	Webhook verification	GET /api/whatsapp/webhook — verificacion Meta (hub.mode, hub.verify_token, hub.challenge)
WA-1.4	Sender module	lib/whatsapp/sender.ts — envia mensajes via Meta Cloud API (texto, botones, documentos)
WA-1.5	WhatsApp formatter	lib/whatsapp/formatter.ts — markdown RAG → formato WhatsApp (bold, listas, URLs completas)
WA-1.6	Answer generator	lib/whatsapp/generate-answer.ts — runRAGPipeline() + generateText() (non-streaming)
WA-1.7	Session store	lib/whatsapp/session.ts — Map en memoria keyed por telefono, ultimos 5 turnos, TTL 24h
WA-1.8	Env vars en Vercel	WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN
WA-1.9	Deploy + configurar webhook	Apuntar webhook URL de Meta a tribai.co/api/whatsapp/webhook
WA-1.10	Test en modo desarrollo	Probar con 2-3 telefonos

Sprint WA-2: UX + Compliance (3-4h)

#	Tarea	Detalle
WA-2.1	Consent flow (Ley 1581)	Primer mensaje → boton "Acepto politica de datos" antes de responder
WA-2.2	Mensaje bienvenida	List message con opciones: IVA, Renta, Retencion, Sanciones, Otra consulta
WA-2.3	Quick reply buttons	Despues de cada respuesta: "Mas detalles", "Nueva consulta", "Calculadora"
WA-2.4	Typing indicator	Status "escribiendo..." mientras RAG procesa
WA-2.5	Error handling	Mensajes amigables, opcion "hablar con asesor"
WA-2.6	Split largo	Auto-split respuestas >4096 chars en multiples mensajes
WA-2.7	Off-topic	Greeting, off-topic, media → respuesta apropiada
WA-2.8	Rate limiting	Max 20 consultas/hora por telefono
WA-2.9	Template messages	Crear templates para aprobacion Meta (bienvenida, re-engagement, alerta normativa)

Sprint WA-3: Produccion + Analytics (2-3h)

#	Tarea	Detalle
WA-3.1	Logging a Supabase	Conversaciones: telefono hash, query, respuesta, latencia, fuentes
WA-3.2	Dashboard metricas	queries/dia, topics populares, tasa de exito, latencia
WA-3.3	Acceso produccion Meta	Verificacion de negocio + phone number permanente (+57)
WA-3.4	Webhook security	Verificar X-Hub-Signature-256 de Meta
WA-3.5	Escalation	Comando "agente" → notifica por email (Resend)
WA-3.6	QR code + link wa.me	Assets para distribucion en redes sociales
WA-3.7	Politica de datos	Pagina /politica-datos-whatsapp en tribai.co

Arquitectura:

Usuario WhatsApp (+57)
    |
    v
Meta Cloud API --webhook--> /api/whatsapp/webhook (Vercel)
                               |
                               +-- 200 OK (inmediato)
                               +-- after() background:
                                    |-- Session store (historial)
                                    |-- Rate limit check
                                    |-- RAG Pipeline (~1-3s)
                                    |-- generateText (Claude)
                                    |-- Formatter (md → WhatsApp)
                                    |-- Send reply (Meta API)
                                    +-- Log to Supabase

Costos mensuales (piloto 100 usuarios):

Item	Costo
Meta WhatsApp (replies customer-initiated)	$0
Anthropic Claude	~$30-50/mes
Vercel + Pinecone	Ya pagado
Total incremental	~$30-50/mes

---

Palanca 2: Gemini Live API — Consultor Tributario por Voz

Por que: Gemini 3.1 Flash Live permite construir agentes de voz en tiempo real con <300ms de latencia, tool calling durante la conversacion, y soporte multilingue (90+ idiomas incluyendo espanol). Un contador podria llamar a Tribai y preguntar verbalmente sobre el Art. 240 mientras maneja.

Sprint VOZ-1: Prototipo Voice Agent (1 semana)

#	Tarea	Detalle
VOZ-1.1	Setup Google AI Studio	Obtener API key, configurar proyecto
VOZ-1.2	Crear voice agent backend	WebSocket endpoint en Next.js que conecta Gemini Live API con RAG pipeline
VOZ-1.3	Tool definitions	Definir tools para que Gemini llame al RAG pipeline durante la conversacion: consultarET, calcularRetencion, buscarDoctrina
VOZ-1.4	Session management	Manejar sesiones de voz con contexto persistente
VOZ-1.5	System instructions	Prompt de voz: "Eres un consultor tributario colombiano. Responde de forma concisa y cita articulos."
VOZ-1.6	Prototipo web	Widget de voz en tribai.co con boton "Hablar con Tribai"

Sprint VOZ-2: Integracion RAG + Calidad (1 semana)

#	Tarea	Detalle
VOZ-2.1	Function calling con RAG	Gemini Live detecta intent tributario → llama consultarET(query) → RAG pipeline → responde con audio
VOZ-2.2	Calculadoras por voz	"Calcula la retencion en la fuente para un salario de 8 millones" → ejecuta calculadora
VOZ-2.3	Confirmacion de citaciones	Despues de cada respuesta, el agente dice "Segun el Articulo 240 del Estatuto Tributario..."
VOZ-2.4	Manejo de ruido	Optimizar para ambientes ruidosos (oficina, transporte)
VOZ-2.5	Transcripcion + log	Guardar transcripcion texto de cada sesion de voz

Sprint VOZ-3: Produccion + Telefonia (1 semana)

#	Tarea	Detalle
VOZ-3.1	WebRTC frontend	Widget de voz optimizado con indicadores visuales
VOZ-3.2	Integracion telefonica	Conectar con servicio de telefonia (Twilio Voice) para llamadas tradicionales
VOZ-3.3	Numero telefonico	Numero colombiano (+57) dedicado para consultas por llamada
VOZ-3.4	Analytics de voz	Duracion, temas, satisfaction, completion rate
VOZ-3.5	A/B test voz vs texto	Comparar calidad de respuestas voz vs chat texto

Arquitectura Gemini Live:

Usuario (microfono/telefono)
    |
    v (audio stream)
Gemini 3.1 Flash Live API (WebSocket)
    |
    |-- Detecta intent tributario
    |-- Function call: consultarET("tarifa IVA")
    |       |
    |       v
    |   Tribai RAG Pipeline (1-3s)
    |       |
    |       v
    |   {articulos, fuentes, confianza}
    |
    |-- Genera respuesta de voz con citaciones
    |
    v (audio response)
Usuario escucha respuesta

Costos estimados:

Item	Costo
Gemini 3.1 Flash Live	~$0.04/min audio input, ~$0.16/min audio output
Consulta promedio (~2 min)	~$0.40/consulta
100 consultas/dia	~$40/dia = ~$1,200/mes
Alternativa: solo web (WebRTC, sin telefonia)	~$200-400/mes

---

Palanca 3: API Publica + Widget Embeddable

Por que: Siigo (300K+ usuarios), Alegra, World Office no tienen consulta tributaria IA. Un widget embeddable les da la funcionalidad sin construirla. Revenue: per-query pricing.

Sprint API-1: API v1 (3-4h)

#	Tarea	Detalle
API-1.1	Endpoint /api/v1/consulta	POST con API key auth, JSON request/response (no streaming)
API-1.2	API key management	Tabla en Supabase: api_keys (key, org, plan, queries_used, rate_limit)
API-1.3	Rate limiting por API key	Configurable por plan (100/dia free, 1000/dia pro, unlimited enterprise)
API-1.4	Response format	{ respuesta, fuentes: [{articulo, url}], confianza, calculadoras_sugeridas }
API-1.5	Documentacion	OpenAPI spec + pagina /developers con ejemplos

Sprint API-2: Widget Embeddable (4-6h)

#	Tarea	Detalle
API-2.1	Widget React	<TribaiConsulta apiKey="..." /> — chat flotante embeddable
API-2.2	Script loader	<script src="tribai.co/widget.js"> para integracion sin React
API-2.3	Theming	CSS variables para match con la app host
API-2.4	Sandbox mode	Demo sin API key con 3 queries gratis

---

Backlog Tecnico Restante

#	Item	Impacto	Esfuerzo	Prioridad
T-1	Contextual Retrieval en namespaces externos (doctrina 56K, decretos)	Recall +5-10%	8-12h, ~$15 Haiku	P2
T-2	Fine-tune embeddings con triplets en GCP A100	Recall +8-15%	5-7 dias	P2
T-3	Fine-tune cross-encoder reranker (dataset listo, 1,768 pares)	P@5 +15-20%	3-5 dias	P2
T-4	Multi-agent decomposition para queries complejas	Complex P@5 +50%	7-10 dias	P3
T-5	Temporal reasoning — ontologia de versiones por articulo	Queries historicas	10-15 dias	P3
T-6	DUR 1625 completo (Parte 2-5: aduanas, cambiario)	Cobertura reglamentaria	1-2 semanas	P3
T-7	Conceptos Unificados DIAN — scraping + tagging	Mayor autoridad doctrinaria	2-3 dias	P2
T-8	CDI documents — scraping tratados internacionales	Tributacion internacional	3-4 dias	P3
T-9	Parent Document Retrieval real (child index + parent lookup)	Completeness +5%	3-4 dias	P3
T-10	BGE-M3 evaluation (hybrid nativo, 100+ idiomas)	Alternativa embedding	2-3 dias	P3

Backlog de Producto

#	Item	Target	Esfuerzo
P-1	Generador de declaraciones (F210/F110)	Competir con Tributi ($159K-539K)	2-3 semanas
P-2	Alertas normativas push	Notificar cambios en articulos seguidos	1 semana
P-3	Comparador temporal de articulos	"Art. 240 antes vs despues de Ley 2277"	3-4 dias
P-4	SEO para temporada de renta (ago-oct 2026)	6M+ declarantes buscando	1 semana
P-5	Partnership con INCP o universidades	Trust signal institucional	Ongoing
P-6	Chrome extension para portal DIAN	Panel de consulta al lado de Muisca	1 semana

---

Timeline Sugerido

Abril 2026:
  Semana 1-2: [WhatsApp Bot: Sprints WA-1 + WA-2]
  Semana 3:   [WhatsApp Bot: Sprint WA-3 + API v1]
  Semana 4:   [Gemini Voice: Sprint VOZ-1]

Mayo 2026:
  Semana 1-2: [Gemini Voice: Sprints VOZ-2 + VOZ-3]
  Semana 3-4: [Widget embeddable + Fine-tuning ML]

Junio-Julio 2026:
  [Generador declaraciones F210]
  [SEO temporada de renta]
  [Partnerships]

Agosto-Octubre 2026:
  === TEMPORADA DE RENTA ===
  6M+ declarantes, WhatsApp bot + web + voz activos

---

Licencia

Proyecto privado. Todos los derechos reservados.

tribai.co — inplux