🪨 PROJECT LITHOS

Inteligencia Cuantitativa Institucional, Auditoría SEC de Calera FinSec y Arquitectura de Contexto Infinito ICX para LLMs Generales mediante Model Context Protocol (MCP)

“Ground Truth Inquebrantable para Mercados de Alta Velocidad: Project Lithos es el lecho rocoso sólido y determinista de la IA cuantitativa moderna.”

🌋 Leyenda del Proyecto y Origen del Vibe Coding

Project Lithos se creó durante el Live Stream Vibe Coding Stream como un arnés de referencia educativa de código abierto y banco de pruebas piloto para la API de Contexto Infinito Calera Labs ICX y el Servidor MCP Calera Labs FinSec (FinanceSec).

En geología, la Litosfera es la corteza exterior y el lecho de roca inamovible de la Tierra.

En la ingeniería cuantitativa financiera, combinar LLMs comerciales de razonamiento (Google Gemini 3.1 Flash-Lite, Claude 3.5 Sonnet o GPT-4o) con los datos de mercado de alta velocidad y la infraestructura de trading requiere ground truth determinista y cero alucinación:

1. Procedencia determinista de las presentaciones SEC (Calera FinSec MCP: extracción GAAP a velocidad empresarial $<2\text{ms}$, covenants, mix de segmentos, 0% de error de cálculo).

2. Memoria de Contexto Infinito y Sincronización Delta en Tiempo Real (Calera ICX A4 Lattice — Recuperación asociativa submilisegundo $<1\text{milisegundo}$, cero inflación de tokens).

3. Profundidad de Libro de Órdenes de Nivel 2 y Motor de Crowding (escalas de oferta/demanda en tiempo real, ratios de desequilibrio de órdenes, detección de compresión de liquidez).

4. Auditoría de Telemetría Post-Trade HFT (localización de cuellos de botella de ruta, reintentos TCP y deslizamiento por latencia $>50\text{ms}$).

5. Detección Topológica de Contradicciones (huecos de corte $Betti-2$ entre advertencias de proveedores y previsiones corporativas).

6. Backtesting Alfa SQL Local de 5 Años (patrones de caída y rebetween, anomalías de acumulación de volumen).

7. Ejecución de Broker Protegida Criptográficamente (tokens HMAC con intervención humana y protección contra Inyección de Prompts).

Related MCP server: Sablier MCP Server

🏛️ Arquitectura del Sistema

                    ┌────────────────────────────────────────────────────────┐
                    │             Commercial Cloud Reasoning LLMs            │
                    │         (Claude 3.5 Sonnet / GPT-4o / Gemini BYOK)     │
                    └───────────────────────────┬────────────────────────────┘
                                                │
                                                ▼ ▲  (Secure JSON-RPC 2.0 / stdio / SSE)
                                                │
                    ┌───────────────────────────┴────────────────────────────┐
                    │                    Local MCP Host                      │
                    │        (Claude Desktop / Cursor / Antigravity CLI)     │
                    └───────────────────────────┬────────────────────────────┘
                                                │
                                                ▼ ▲
      ┌─────────────────────────────────────────┴─────────────────────────────────────────┐
      │                              PROJECT LITHOS MCP SERVER                            │
      │  ┌─────────────────────────────────────────────────────────────────────────────┐  │
      │  │     🛡️ SECURITY GUARD & HITL GATEWAY (HMAC Token + Prompt Injection Shield)   │  │
      │  └──────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────┘  │
      └─────────────┼──────────────┼──────────────┼──────────────┼──────────────┼─────────┘
                    │              │              │              │              │
         ┌──────────┴─────┐ ┌──────┴────────┐ ┌───┴──────────┐ ┌─┴────────────┐ ┌┴──────────┐
         │ Calera FinSec  │ │  Calera ICX   │ │ Live L2 Book │ │  Local SQL   │ │ Post-Trade│
         │   Hosted MCP   │ │Infinite Memory│ │Depth & Spread│ │ Database    │ │ Logs & ACK│
         │(SEC 10-K/10-Q) │ │  (A4 Lattice) │ │  (Microstr.) │ │(5-Yr Intrad.)│ │ (>50ms)   │
         └──────────┬─────┘ └──────┬────────┘ └───┬──────────┘ └─┬────────────┘ └┬──────────┘
                    │              │              │              │              │
                    ▼              ▼              ▼              ▼              ▼
             finsec.caleralabs  icx.api.caleralabs  Polygon.io /   SQLite /       Execution
               .com/mcp          .com/v1         Alpaca Feeds   TimescaleDB    Logs & CSVs

flowchart TD
    subgraph ClientLayer["AI Client & MCP Host Layer"]
        LLM["Commercial AI (Gemini BYOK / Claude / GPT)"]
        Host["MCP Host (Claude Desktop / Cursor / Antigravity CLI)"]
        LLM <--> Host
    end

    subgraph LithosCore["Project LITHOS Core Engine"]
        Server["Project LITHOS MCP Server (server.py)"]
        Guard["🛡️ Security Guard & HITL Gateway\n(HMAC Tokens + Prompt Injection Shield)"]
        Router["⚡ Autonomous Query Router\n& Slash Dispatcher (chat.py)"]
        Host <--> Server
        Server <--> Guard
        Server <--> Router
    end

    subgraph Substrates["Integrated Substrates & Data Feeds"]
        FinSec["🏛️ Calera FinSec MCP\n(Deterministic SEC 10-K/10-Q)"]
        ICX["🌌 Calera ICX\n(4D A4 Infinite Lattice Memory)"]
        L2["📊 Level-2 Order Book\n(Imbalance & Squeeze Engine)"]
        SQL["🗄️ 5-Year SQL Database\n(Alpha Backtester)"]
        Logs["📋 Execution Log Auditor\n(Latency Anomaly Detection)"]
        Broker["💼 Alpaca Paper Broker\n(Safe Order Staging)"]
    end

    Guard --> FinSec
    Guard --> ICX
    Guard --> L2
    Guard --> SQL
    Guard --> Logs
    Guard --> Broker

⚡ Guía de Inicio Rápido en 3 Minutos

1. Clonar y Configurar el Entorno

git clone https://github.com/Calera-Labs/PROJECT_LITHOS.git
cd PROJECT_LITHOS

# Create and activate virtual environment
python -m venv .venv

# On Linux/macOS:
source .venv/bin/activate

# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

2. Configura tus Claves de API (.env)

Copia la configuración de plantilla:

cp .env.example .env

Edita .env con tus credenciales personales de trae tu propia clave (Bring-Your-Own-Key):

# Google Gemini BYOK (Free API key from https://aistudio.google.com/app/apikey)
GEMINI_API_KEY=YOUR_GEMINI_API_KEY_HERE
GEMINI_MODEL=gemini-3.1-flash-lite
BYOK_PROVIDER=gemini

# Calera Labs ICX Gateway
ICX_BASE_URL=https://icx.api.caleralabs.com/v1
ICX_API_KEY=YOUR_CALERA_ICX_API_KEY_HERE
ICX_SPACE_ID=lithos_market_memory

# Calera Labs FinSec MCP (Set to true to run in local deterministic mode)
FINSEC_MCP_URL=https://finsec.caleralabs.com/mcp
FINSEC_API_KEY=STANDBY_FOR_KEY
FINSEC_STANDBY_MODE=true

# Safe Execution Sandbox
LITHOS_BROKER_ENV=paper

3. Ejecuta la Verificación de Diagnóstico

Ejecuta la herramienta de verificación del sistema para comprobar tu entorno, poblar la base de datos y probar la conectividad:

python verify_setup.py

4. Inicia la Terminal Cuantitativa Interactiva

python chat.py

💡 Coordinación Dinámica del Prompt

La CLI del terminal inspecciona dinámicamente el estado de cada uno de los tres sustratos y actualiza el prompt en tiempo real:

🚀 Catálogo Completo de Herramientas MCP (18 Herramientas)

Cuando se ejecuta server.py como servidor MCP, Project LITHIOS expone 18 herramientas a tu agente de IA:

1. Auditoría de Presentaciones SEC de Calera Labs FinSec (FinanceSEC) (7 herramientas oficiales)

• query_financial_sec(query, low_tokens, usd_only): Recuerdo certificado de hechos de la SEC EDGAR en lenguaje natural con procedencia odexion o rechazo ocuro.

• query_sec_metric_exact(company, metric, period): Recuerdo exacto de la métrica EDGAR para empresa + métrica + período (gross_margin, total_revenue).

• query_sec_sector_peers(sector_or_industry, period, limit): Métricas XBRL certificadas para los grupos de las mismas industrial groups derivadas dinámicamente de los códigos SIC.

• compute_sec_cagr(company, metric, start_period, end_period): Cálculo de la tasa anual compuesta de crecimiento sobre datos de presentación SEC verificados con un 0% de error de cálculo.

• lattice_arith_eval(op, company, metric, start_period, end_period): Solucionador algebraico determinista libre de errores (cagr, ratio, multiply, divide, yoy_series).

• valuation_inputs(company, pack, period): Paquete certificado de datos de valoración SEC (12 paquetes: segment_mix, equity_screen, quality_of_earnings, returns_screen, leverage_screen, piotrofski_f, altman_z_prime, beneish_m_score, dupont_5step, working_capital_efficiency, dcf_valuation_inputs, ev_bridge).

• vln_capabilities_overview(): Conjunto completo de modelos de valoración y solucionadores aritméticos certificados.

2. Sustrato de Memoria de la Red ICX Infinite Context de Calera Labs

• query_icx_infinite_memory(query, session_id): Razonamiento con base documental, fundamentado en la Red de Envolvente Volumétrica (VLCN) de Calera ICX, impulsado por Google Gemini 3.1 Flash-Lite vía BYOK.

• sync_market_to_icx_lattice(news_title, text, family): Transmite noticias de última hora, transcripciones o presentaciones al entramado móvil A4 sin inflar los tokens de contexto del LLM.

• query_icx_symbolic_ledger(query): Recuerdo asociativo submilisegundo ($<1\text{ms}$) para las invariantes numéricas exactas.

• quote_icx_memory_slot(family, index): Recuerdo de vez con Scope order, permite obtener documentos específicos sin inferencia del LM.

• detect_market_contradictions(): Detecta los huecos topológicos de $B. eta_{2}$ ($Betti-2$) y la divergencia de orientación entre proveedores y competidores.

• get_icx_lattice_stats(): Inspecciona los nodos simpliciales activos, las columnas de memoria, los bytes cristalizados y la geometría de la 4D A4 manifold.

• reset_icx_session(session_id): Reinicia los turnos de conversación, preservando los temas cristalizados en el espacio del lattice subyacente.

3. Microestructura de Mercado en Vivo y Libro de Órdenes de Nivel 2

• get_live_quote(ticker): Precios en directo, rangos diarios, volumen y VWAP.

• get_order_book_depth(ticker, depth): Cálcula escalera de oferta y demanda, ratios de desequilibrio de órdenes y condiciones de estrechamiento.

4. Auditoría de Base de Datos Local y Backtesting Alfa

• get_financial_db_schema(): Estructura de tablas y métricas de registros en las tablas de series temporales locales.

• query_financial_db(sql_query): Ejecución SQL sicura solo de lectura (las instrucciones destructivas están bloqueadas).

• backtest_alpha_pattern(ticker, min_morning_drop_pct, require_green_close): Audita 5 años de datos diarios/intradía para buscar reversiones en la caída matinal con análisis de volumen.

5. Análisis Posts Transaccionación y Telemetría de Ejecución

• audit_execution_logs(min_latency_ms, ticker_filter): Automáticamente aísla las órdenes con una latencia/desviaciones $>50\text{ms}$ y detecta los cuellosBotteneck de enrutado de cambio.

6. Reeéquilibrio Sistemático y Puertas de Ejecución Seguras

• get_portfolio_summary(): Posiciones, capital,, efectivo y sopes de exposición sectorial.

• propose_portfolio_rebalance(macro_rationale, tech_shift_pct, fixed_income_shift_pct): ReeEquilibrador sistemático basado en reglas que organiza las órdenes con tokens HMAC.

• execute_broker_order(order_id, confirmation_token): Despach my trades, but only after verifying the human confirmation token.

🕹️ Comandos de la Terminal Interactiva

Dentro de python chat.py, usa comandos con estaba para operaciones deterministas instantáneas:

🔌 Conexión con Claude Desktop y Cursor

Conectar a Claude Desktop

Agrega Project Lithos a tu claude_desktop_config.json:

{
  "mcpServers": {
    "project-lithos": {
      "command": "python",
      "args": [
        "/ABSOLUTE/PATH/TO/PROJECT_LITHOS/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "LITHOS_BROKER_ENV": "paper",
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
        "ICX_API_KEY": "YOUR_ICX_KEY",
        "FINSEC_STANDBY_MODE": "true"
      }
    }
  }
}

🧪 Pruebas

Project LITHOS incluye suites de pruebas exhaustivas que cubren manejadores de comandos, coordinación dinámica de estado, paquetes de valoración y defensas contra inyección de prompts:

# Run all tests
pytest

# Run tests with verbose output
pytest -v

📜 Términos de Licencia y Piloto

Project LITHOS está licenciado bajo la Calera Labs Source-Available Evaluation & Educational License.

• Uso gratuito: Eres libre de clonar, estudiar, ejecutar, probar y realizar pruebas piloto de Project LITHOS con fines educativos, de investigación, académicos y de evaluación piloto interna con tus propios modelos de IA BYOK.

• Licencia restringida y sin copia comercial: La redistribución comercial, la reventa o la copia de módulos de integración propietarios para productos SaaS comerciales sin el permiso expreso por escrito de Calera Labs está estrictamente prohibida.

• Consulta el archivo LICENSE completo para conocer todos los detalles.

📚 Documentación Adicional

• Guía de inicio

• Análisis en profundidad de la arquitectura del sistema

• Política de seguridad y salvaguardas

• Directrices para contribuir