🪨 PROJECT LITHOS

Institutionelle quantitative Intelligenz, Calera FinSec SEC-Auditing & ICX-Infinite-Context-Architektur für allgemeine LLMs über Model Context Protocol (MCP)

„Unerschütterliche Grundwahrheit für Hochgeschwindigkeitsmärkte: Project Lithos ist das solide, deterministische Fundament unter moderner quantitativer KI.“

🌋 Projekt-Hintergrund & der Ursprung des Vibe-Codings

Project Lithos wurde während des Live-Stream-Vibe-Coding-Streams als offene pädagogische Referenzumgebung und Pilot-Testumgebung für die Calera Labs ICX Infinite Context API und den Calera Labs FinSec (FinanceSec) MCP-Server erstellt.

In der Geologie ist die Lithosphäre die unerschütterliche äußere Kruste und das Grundgestein der Erde.

Im finanziellen quantitativen Engineering erfordert die Kombination kommerzieller Reasoning-LLMs (Google Gemini 3.1 Flash-Lite, Claude 3.5 Sonnet oder GPT-4o) mit Hochgeschwindigkeits-Marktdaten und Handelsinfrastruktur deterministische Grundwahrheit und null Halluzination:

1. Deterministische SEC-Einreichungs-Herkunft (Calera FinSec MCP — Enterprise-Geschwindigkeit $<2\text{ms}$ GAAP-Extraktion, Covenants, Segmentmix, 0% Berechnungsfehler).

2. Unendlicher Kontextspeicher & Echtzeit-Delta-Sync (Calera ICX A4 Lattice — Sub-Millisekunden-assoziativer Abruf $<1\text{ms}$, null Token-Inflation).

3. Level-2-Orderbuch-Tiefe & Squeeze-Engine (Echtzeit-Geld-/Brief-Leitern, Order-Imbalance-Verhältnisse, Liquiditäts-Squeeze-Erkennung).

4. HFT-Post-Trade-Telemetrie-Audit (Lokalisierung von Routing-Engpässen, TCP-Retransmissionen und Latenz-Slippage von $>50\text{ms}$).

5. Topologische Widerspruchserkennung ($Betti-2$-Scherungslücken zwischen Lieferantenwarnungen und Unternehmensprognosen).

6. Lokales 5-Jahres-SQL-Alpha-Backtesting (Dip-and-Rebound-Muster, Volumenakkumulationsanomalien).

7. Kryptografisch geschützte Broker-Ausführung (Human-in-the-loop-HMAC-Token + Prompt-Injection-Shield).

Related MCP server: Sablier MCP Server

🏛️ Systemarchitektur

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

1. Repository klonen & Umgebung einrichten

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. API-Schlüssel konfigurieren (.env)

Kopieren Sie die Vorlagenkonfiguration:

cp .env.example .env

Bearbeiten Sie .env mit Ihren persönlichen Bring-Your-Own-Key-Anmeldedaten:

# 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. Diagnoseprüfung ausführen

Führen Sie das integrierte Systemverifizierungstool aus, um Ihre Umgebung zu prüfen, die Datenbank zu initialisieren und die Konnektivität zu testen:

python verify_setup.py

4. Interaktives quantitatives Terminal starten

python chat.py

💡 Dynamische Prompt-Koordination

Die Terminal-CLI prüft dynamisch den Zustand aller drei Substrate und aktualisiert den Prompt in Echtzeit:

🛠️ Vollständiger MCP-Toolkatalog (18 Tools)

Wenn server.py als MCP-Server ausgeführt wird, stellt Project LITHOS Ihrem KI-Agenten 18 Tools bereit:

1. Calera Labs FinSec (FinanceSec) SEC-Einreichungsprüfung (7 offizielle Tools)

• query_financial_sec(query, low_tokens, usd_only): Zertifizierter SEC-EDGAR-Faktenabruf in natürlicher Sprache mit Accession-Provenienz oder sicherer Verweigerung.

• query_sec_metric_exact(company, metric, period): Exakter EDGAR-Kennzahlabruf für Unternehmen + Kennzahl + Zeitraum (gross_margin, total_revenue).

• query_sec_sector_peers(sector_or_industry, period, limit): Zertifizierte XBRL-Kennzahlen über Branchen-Peergruppen, die dynamisch aus SIC-Codes abgeleitet werden.

• compute_sec_cagr(company, metric, start_period, end_period): Berechnung der durchschnittlichen jährlichen Wachstumsrate (CAGR) auf Basis verifizierter SEC-Einreichungsfakten mit 0% Berechnungsfehler.

• lattice_arith_evaluate(op, company, metric, start_period, end_period): Deterministischer fehlerfreier Algebra-Löser (cagr, ratio, multiply, divide, yoy_series).

• valuation_inputs(company, pack, period): Zertifiziertes SEC-Bewertungseingabepaket (12 Pakete verfügbar: 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(): Vollständiger Katalog zertifizierter Bewertungsmodelle und arithmetischer Löser.

2. Calera Labs ICX-Substrat für unendlichen Kontextspeicher

• query_icx_infinite_memory(query, session_id): Fundiertes Reasoning im Calera ICX Volumetric Lattice Network (VLN), betrieben mit Google Gemini 3.1 Flash-Lite BYOK.

• sync_market_to_icx_lattice(news_title, text, family): Streamt Eilmeldungen, Transkripte oder Einreichungen in das A4-Lattice ohne LLM-Kontext-Token-Inflation.

• query_icx_symbolic_ledger(query): Sub-Millisekunden-assoziativer Abruf ($<1\text{ms}$) für exakte numerische Invarianten.

• quote_icx_memory_slot(family, index): Deterministischer Scoped Recall zum Zitieren exakter Dokumentregister mit null LLM-Inferenz.

• detect_market_contradictions(): Erkennt $Betti-2$-topologische Lücken und Prognoseabweichungen zwischen Lieferanten und Wettbewerbern.

• get_icx_lattice_stats(): Untersucht aktive simpliziale Knoten, Speicherspalten, kristallisierte Bytes und die 4D-A4-Mannigfaltigkeitsgeometrie.

• reset_icx_session(session_id): Setzt Konversationsrunden zurück, während kristallisierte Fakten im zugrunde liegenden Lattice-Raum erhalten bleiben.

3. Live-Marktdaten & Level-2-Orderbuch-Mikrostruktur

• get_live_quote(ticker): Echtzeitkurse, Tagesspannen, Volumen und VWAP.

• get_order_book_depth(ticker, depth): Berechnet Geld-/Brief-Leitern, Order-Imbalance-Verhältnisse und Liquiditäts-Squeeze-Bedingungen.

4. Lokale Datenbankprüfung & Alpha-Backtesting

• get_financial_db_schema(): Tabellenschemata und Zeilenkennzahlen über lokale Zeitreihentabellen.

• query_financial_db(sql_query): Sichere Sandbox-SQL-Ausführung mit Leserechten (destruktive Anweisungen werden blockiert).

• backtest_alpha_pattern(ticker, min_morning_drop_pct, require_green_close): Prüft 5-Jahres-Tages-/Intradaydaten auf Morgen-Dip-Reversals mit Volumenanalyse.

5. Post-Trade-Analyse & Ausführungstelemetrie

• audit_execution_logs(min_latency_ms, ticker_filter): Isoliert Aufträge mit Latenz/Slippage von $>50\text{ms}$ und identifiziert Routing-Engpässe an Börsen.

6. Systematisches Rebalancing & sichere Ausführungs-Gateways

• get_portfolio_summary(): Bestände, Eigenkapital, Bargeld und Sektor-Expositionsgewichte.

• propose_portfolio_rebalance(macro_rationale, tech_shift_pct, fixed_income_shift_pct): Systematischer regelbasierter Rebalancer, der Aufträge mit HMAC-Tokens vorbereitet.

• execute_broker_order(order_id, confirmation_token): Führt Trades erst nach Überprüfung des menschlichen Bestätigungstokens aus.

🕹️ Interaktive Terminalbefehle

Verwenden Sie in python chat.py Slash-Befehle für sofortige deterministische Operationen:

🔌 Verbinden mit Claude Desktop & Cursor

Mit Claude Desktop verbinden

Fügen Sie Project Lithos zu Ihrer claude_desktop_config.json hinzu:

{
  "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"
      }
    }
  }
}

🧪 Tests

Project LITHOS enthält umfassende Testsuites, die Befehls-Handler, dynamische Statuskoordination, Bewertungspakete und Prompt-Injection-Abwehrmaßnahmen abdecken:

# Run all tests
pytest

# Run tests with verbose output
pytest -v

📜 Lizenz & Pilotbedingungen

Project LITHOS ist unter der Calera Labs Source-Available Evaluation & Educational License lizenziert.

• Kostenlos nutzbar: Sie dürfen Project LITHOS für Bildungs-, Forschungs-, akademische und interne Pilotbewertungszwecke mit Ihren eigenen BYOK-KI-Modellen klonen, studieren, ausführen, testen und pilotieren.

• Lizenzbeschränkung & kein kommerzielles Kopieren: Die kommerzielle Weiterverbreitung, der Weiterverkauf oder das Kopieren proprietärer Integrations-Harnesses für kommerzielle SaaS-Produkte ohne ausdrückliche schriftliche Genehmigung von Calera Labs ist strengstens untersagt.

• Die vollständigen Details finden Sie in der LICENSE-Datei.

📚 Zusätzliche Dokumentation

• Erste-Schritte-Anleitung

• Systemarchitektur im Detail

• Sicherheitsrichtlinie & Schutzmaßnahmen

• Beitragsrichtlinien