🪨 PROJECT LITHOS

Institutional Quantitative Intelligence, Calera FinSec SEC Auditing & ICX Infinite Context Architecture for General LLMs via Model Context Protocol (MCP)

"Unshakeable Ground Truth for High-Velocity Markets: Project Lithos is the solid, deterministic bedrock beneath modern quantitative AI."

---

🌋 Project Lore & The Vibe Coding Origin

Project Lithos was created during the Live Stream Vibe Coding Stream as an open educational reference harness and pilot testbed for the Calera Labs ICX Infinite Context API and the Calera Labs FinSec (FinanceSec) MCP Server.

In geology, the Lithosphere is the unshakeable outer crust and bedrock of the Earth.

In financial quantitative engineering, combining commercial reasoning LLMs (Google Gemini 3.1 Flash-Lite, Claude 3.5 Sonnet, or GPT-4o) with high-velocity market data and trading infrastructure requires deterministic ground truth and zero hallucination:

1. Deterministic SEC Filing Provenance (Calera FinSec MCP — Enterprise-speed $<2\text{ms}$ GAAP extraction, covenants, segment mix, 0% calculation error).
2. Infinite Context Memory & Real-Time Delta Sync (Calera ICX A4 Lattice — Sub-millisecond associative recall $<1\text{ms}$, zero token inflation).
3. Level-2 Order Book Depth & Squeeze Engine (Real-time bid/ask ladders, order imbalance ratios, liquidity squeeze detection).
4. HFT Post-Trade Telemetry Auditing (Pinpointing route bottlenecks, TCP retransmits, and $>50\text{ms}$ latency slippage).
5. Topological Contradiction Detection ($Betti-2$ shear voids between supplier warnings and corporate guidance).
6. Local 5-Year SQL Alpha Backtesting (Dip-and-rebound patterns, volume accumulation anomalies).
7. Cryptographically Guarded Broker Execution (Human-in-the-loop HMAC tokens + Prompt Injection Shield).

---

🏛️ System Architecture

                    ┌────────────────────────────────────────────────────────┐
                    │             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

---

⚡ 3-Minute Quickstart

1. Clone & Set Up Environment

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. Configure Your API Keys (.env)

Copy the template configuration:

cp .env.example .env

Edit .env with your personal Bring-Your-Own-Key credentials:

# 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. Run Diagnostic Verification

Run the built-in system verification tool to check your environment, seed the database, and test connectivity:

python verify_setup.py

4. Launch the Interactive Quantitative Terminal

python chat.py

---

💡 Dynamic Prompt Coordination

The terminal CLI dynamically inspects the health of all three substrates and updates the prompt in real time:

Prompt Display	Meaning / Active Substrates
LITHOS [ICX+Gemini] ❯	All 3 substrates healthy: Calera FinSec active (indicated by brackets [ ]), Calera ICX active, Gemini BYOK reasoning active.
LITHOS [ICX] ❯	Gemini down/unconfigured: Queries seamlessly execute via Zero-LLM Direct ICX Memory Recall on the A4 lattice.
LITHOS ICX+Gemini ❯	FinSec offline: ICX and Gemini active, brackets omitted.
LITHOS [Gemini] ❯	ICX offline: FinSec and Gemini active.
LITHOS OFFLINE ❯	All offline: Running in local fallback mode.

---

🛠️ Complete MCP Tool Catalog (18 Tools)

When running server.py as an MCP server, Project LITHOS exposes 18 tools to your AI agent:

1. Calera Labs FinSec (FinanceSec) SEC Filing Auditing (7 Official Tools)

• query_financial_sec(query, low_tokens, usd_only): Certified natural-language SEC EDGAR fact recall with accession provenance or safe refusal.
• query_sec_metric_exact(company, metric, period): Exact EDGAR metric recall for company + metric + period (gross_margin, total_revenue).
• query_sec_sector_peers(sector_or_industry, period, limit): Certified XBRL metrics across industry peer groups derived dynamically from SIC codes.
• compute_sec_cagr(company, metric, start_period, end_period): Compound annual growth rate calculation over verified SEC filing facts with 0% calculation error.
• lattice_arith_evaluate(op, company, metric, start_period, end_period): Deterministic zero-error algebraic solver (cagr, ratio, multiply, divide, yoy_series).
• valuation_inputs(company, pack, period): Certified SEC valuation inputs pack (12 packs available: segment_mix, equity_screen, quality_of_earnings, returns_screen, leverage_screen, piotroski_f, altman_z_prime, beneish_m_score, dupont_5step, working_capital_efficiency, dcf_valuation_inputs, ev_bridge).
• vln_capabilities_overview(): Complete catalog of certified valuation models and arithmetic solvers.

2. Calera Labs ICX Infinite Context Memory Substrate

• query_icx_infinite_memory(query, session_id): Grounded reasoning in the Calera ICX Volumetric Lattice Network (VLN) powered by Google Gemini 3.1 Flash-Lite BYOK.
• sync_market_to_icx_lattice(news_title, text, family): Streams breaking news, transcripts, or filings into the A4 lattice without LLM context token inflation.
• query_icx_symbolic_ledger(query): Sub-millisecond associative recall ($<1\text{ms}$) for exact numerical invariants.
• quote_icx_memory_slot(family, index): Deterministic Scoped Recall to quote exact document registers with zero LLM inference.
• detect_market_contradictions(): Detects $Betti-2$ topological voids and guidance divergence between suppliers and competitors.
• get_icx_lattice_stats(): Inspects active simplicial nodes, memory columns, crystallized bytes, and 4D A4 manifold geometry.
• reset_icx_session(session_id): Resets conversational turns while preserving crystallized facts in the underlying lattice space.

3. Live Market Data & Level-2 Order Book Microstructure

• get_live_quote(ticker): Real-time prices, day ranges, volume, and VWAP.
• get_order_book_depth(ticker, depth): Computes bid/ask ladders, order imbalance ratios, and liquidity squeeze conditions.

4. Local Database Auditing & Alpha Backtesting

• get_financial_db_schema(): Table schemas and row metrics across local time-series tables.
• query_financial_db(sql_query): Safe, sandboxed read-only SQL execution (destructive statements blocked).
• backtest_alpha_pattern(ticker, min_morning_drop_pct, require_green_close): Audits 5-year daily/intraday data for morning dip reversals with volume analysis.

5. Post-Trade Analysis & Execution Telemetry

• audit_execution_logs(min_latency_ms, ticker_filter): Isolates orders suffering $>50\text{ms}$ latency/slippage and identifies exchange routing bottlenecks.

6. Systematic Rebalancing & Safe Execution Gateways

• get_portfolio_summary(): Holdings, equity, cash, and sector exposure weights.
• propose_portfolio_rebalance(macro_rationale, tech_shift_pct, fixed_income_shift_pct): Systematic rule-based rebalancer that stages orders with HMAC tokens.
• execute_broker_order(order_id, confirmation_token): Dispatches trades only after verifying the human confirmation token.

---

🕹️ Interactive Terminal Commands

Inside python chat.py, use slash commands for instant deterministic operations:

Command	Syntax Example	Description
/sec	/sec NVDA gross margin FY2026	Query certified SEC EDGAR facts with paragraph provenance
/pack	/pack NVDA segment_mix	Extract one of 12 certified valuation input packs
/metric	/metric NVDA gross_margin	Query exact EDGAR XBRL concept recall
/cagr	/cagr NVDA revenue FY2022 FY2025	Zero-error compound annual growth rate calculation
/eval	/eval cagr NVDA revenue FY2022 FY2025	Deterministic zero-error algebraic evaluation
/peers	/peers semiconductors 5	XBRL metrics across dynamic SIC industry peers
/overview	/overview	Overview of all certified FinSec valuation packs
/backtest	/backtest AAPL -3.0	5-Year SQL alpha backtest for morning dip reversals
/book	/book NVDA 10	Level-2 order book depth and liquidity squeeze detector
/logs	/logs 50.0	Audit HFT execution logs for slippage $>50\text{ms}$
/ingest	/ingest TSMC lead times extended to 22 weeks	Ingest breaking news into Calera ICX A4 Lattice
/quote	/quote supply_chain.semiconductors 0	Quote exact document slot with zero LLM inference
/stats	/stats	Inspect ICX A4 lattice simplicial nodes & memory bytes
/contradictions	/contradictions	Detect $Betti-2$ topological guidance voids
/portfolio	/portfolio	Inspect current portfolio equity, cash, and sector weights
/rebalance	/rebalance Trim tech by 5%	Stage systematic macro rebalance with HMAC tokens
/execute	/execute LITHOS-STG-XXXX TOKEN	Execute staged order with human confirmation token
/model	/model claude-3-7-sonnet anthropic KEY	Dynamically switch active LLM reasoning model
/toggle	/toggle llm or /toggle icx	Dynamically toggle subsystems on or off
/status	/status	Full subsystem diagnostics and latency metrics
/reset	/reset	Clear session turns while preserving lattice facts
/help	/help	Display command help matrix
/exit	/exit or /quit	Disconnect from terminal

---

🔌 Connecting to Claude Desktop & Cursor

Connect to Claude Desktop

Add Project Lithos to your 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"
      }
    }
  }
}

---

🧪 Testing

Project LITHOS includes comprehensive test suites covering command handlers, dynamic status coordination, valuation packs, and prompt injection defenses:

# Run all tests
pytest

# Run tests with verbose output
pytest -v

---

📜 License & Pilot Terms

Project LITHOS is licensed under the Calera Labs Source-Available Evaluation & Educational License.

• Free to Use: You are free to clone, study, run, test, and pilot Project LITHOS for educational, research, academic, and internal pilot evaluation purposes with your own BYOK AI models.
• License Restricted & No Commercial Copying: Commercial redistribution, resale, or copying proprietary integration harnesses for commercial SaaS products without express written permission from Calera Labs is strictly prohibited.
• See the full LICENSE file for complete details.

---

📚 Additional Documentation

• Getting Started Guide
• System Architecture Deep Dive
• Security Policy & Guardrails
• Contributing Guidelines