# RAGHeat: Unified Production Prompt for Multi-AI Agentic Stock Market Analysis Platform > **PURPOSE**: This is a single, self-contained prompt to generate the complete RAGHeat production system — a Dockerized, multi-AI agentic chatbot for stock, options, and portfolio recommendations powered by physics-inspired heat diffusion on financial knowledge graphs. Feed this prompt to an AI code-generation model to scaffold the entire project. --- ## SYSTEM IDENTITY You are a senior financial software architect and full-stack engineer. You will generate a complete, production-ready, Docker-orchestrated monorepo called `ragheat-platform` implementing the RAGHeat framework — a physics-inspired heat diffusion system for financial market prediction and recommendation, built as a multi-agent conversational AI chatbot. --- ## ARCHITECTURAL OVERVIEW Generate a monorepo with the following structure. Each sub-project has its own `Dockerfile`. A root `docker-compose.yml` orchestrates everything. Documentation lives in a Docusaurus site. ``` ragheat-platform/ ├── docker-compose.yml # Root orchestrator (ALL services) ├── docker-compose.override.yml # Dev overrides (hot reload, debug ports) ├── .env.example # All environment variable templates ├── Makefile # Convenience targets: up, down, logs, test, seed │ ├── backend/ # Python FastAPI + LangGraph orchestrator │ ├── Dockerfile │ ├── pyproject.toml # uv/poetry managed │ ├── app/ │ │ ├── main.py # FastAPI entrypoint, lifespan events │ │ ├── config.py # Pydantic Settings (env-driven) │ │ ├── dependencies.py # Shared deps (Neo4j driver, Redis, LLM clients) │ │ │ │ │ ├── agents/ # LangGraph multi-agent system │ │ │ ├── orchestrator.py # Supervisor/router agent (LangGraph StateGraph) │ │ │ ├── fundamental_agent.py # SEC filings, financial statements │ │ │ ├── sentiment_agent.py # News + social media NLP │ │ │ ├── technical_agent.py # Technical indicators, momentum │ │ │ ├── options_agent.py # Greeks, volatility surface, strategies │ │ │ ├── portfolio_agent.py # Mean-variance optimization, risk mgmt │ │ │ ├── heat_diffusion_agent.py # Physics engine agent (core IP) │ │ │ ├── knowledge_graph_agent.py # Neo4j Cypher generation + GraphRAG │ │ │ └── explanation_agent.py # Chain-of-thought recommendation narratives │ │ │ │ │ ├── core/ # RAGHeat scientific core │ │ │ ├── heat_engine.py # Heat diffusion PDE solver │ │ │ ├── graph_laplacian.py # L = D - A computation, spectral decomposition │ │ │ ├── heat_kernel.py # h(τ) = exp(-βLτ) · h₀ matrix exponential │ │ │ ├── regime_detector.py # HMM-based Bull/Bear/Neutral classification │ │ │ ├── kalman_filter.py # Dynamic weight normalization (Patent 2) │ │ │ ├── gat_embeddings.py # Graph Attention Network with heat priors │ │ │ ├── portfolio_optimizer.py # Heat-diffused covariance Σ_heat(τ) optimization │ │ │ └── options_pricer.py # Heat variance σ²_h(τ) → vol signal │ │ │ │ │ ├── graph/ # Neo4j knowledge graph layer │ │ │ ├── neo4j_client.py # Async Neo4j driver wrapper │ │ │ ├── schema.py # Graph schema definitions (Cypher DDL) │ │ │ ├── financial_ontology.py # 25+ entity types, relationship taxonomy │ │ │ ├── graph_builder.py # Real-time graph construction from data │ │ │ ├── vector_index.py # Neo4j vector search index management │ │ │ ├── gds_algorithms.py # FastRP, Louvain, Node Similarity calls │ │ │ └── context_graph.py # Decision tracing (context graph pattern) │ │ │ │ │ ├── data/ # Real-time data ingestion │ │ │ ├── market_streamer.py # WebSocket + REST market data feeds │ │ │ ├── yahoo_finance.py # yfinance integration │ │ │ ├── news_fetcher.py # Financial news API integration │ │ │ ├── social_sentiment.py # Reddit/Twitter sentiment pipeline │ │ │ ├── fred_macro.py # FRED API macroeconomic data │ │ │ ├── options_flow.py # Options chain data fetcher │ │ │ ├── synthetic_generator.py # Off-hours synthetic data with GARCH │ │ │ └── market_hours.py # NYSE/NASDAQ calendar, session detection │ │ │ │ │ ├── streaming/ # Kafka real-time pipeline │ │ │ ├── producer.py # Market data → Kafka topics │ │ │ ├── consumer.py # Kafka → processing pipeline │ │ │ ├── flink_processor.py # Stream processing (heat recalc triggers) │ │ │ └── topics.py # Topic definitions + schema registry │ │ │ │ │ ├── retrieval/ # Hybrid RAG retrieval │ │ │ ├── hybrid_retriever.py # Graph + Semantic fusion retriever │ │ │ ├── graph_rag.py # Subgraph extraction by heat scores │ │ │ ├── path_rag.py # Multi-hop reasoning path discovery │ │ │ ├── vector_retriever.py # FAISS / Neo4j vector search │ │ │ └── reranker.py # Heat-score weighted reranking │ │ │ │ │ ├── api/ # REST + WebSocket endpoints │ │ │ ├── routes/ │ │ │ │ ├── chat.py # POST /api/chat — main chatbot endpoint │ │ │ │ ├── stocks.py # CRUD stock data + heat scores │ │ │ │ ├── portfolio.py # Portfolio construction + optimization │ │ │ │ ├── options.py # Options analysis + strategies │ │ │ │ ├── market.py # Market regime + overview │ │ │ │ ├── graph.py # Knowledge graph structure + queries │ │ │ │ ├── heat.py # Heat distribution + propagation │ │ │ │ └── health.py # Health checks + readiness probes │ │ │ ├── websockets.py # WS /ws/heat-updates, /ws/chat-stream │ │ │ └── middleware.py # CORS, rate limiting, auth, logging │ │ │ │ │ ├── langsmith/ # Observability │ │ │ ├── tracing.py # LangSmith trace configuration │ │ │ └── evaluators.py # Custom evaluation metrics │ │ │ │ │ └── mcp/ # Model Context Protocol servers │ │ ├── neo4j_mcp.py # Neo4j Cypher MCP tool server │ │ └── market_data_mcp.py # Market data MCP tool server │ │ │ ├── scripts/ │ │ ├── seed_graph.py # Populate Neo4j with initial data │ │ ├── seed_stocks.py # Load stock universe (495+ stocks) │ │ └── migrate.py # Schema migrations │ │ │ └── tests/ │ ├── test_heat_engine.py │ ├── test_agents.py │ ├── test_graph_operations.py │ ├── test_api_endpoints.py │ └── conftest.py │ ├── middleware/ # Message broker + stream processing │ ├── kafka/ │ │ ├── Dockerfile │ │ └── config/ │ │ └── server.properties │ └── redis/ │ └── redis.conf # Cache config with eviction policies │ ├── frontend/ # Chainlit chatbot UI │ ├── Dockerfile │ ├── pyproject.toml │ ├── chainlit.md # Welcome message / branding │ ├── .chainlit/ │ │ └── config.toml # Chainlit configuration │ ├── app.py # Chainlit application entry │ ├── components/ │ │ ├── graph_visualizer.py # Interactive Neo4j graph (D3.js/NVL) │ │ ├── heat_map.py # Real-time heat distribution display │ │ ├── portfolio_dashboard.py # Portfolio allocation visualization │ │ ├── options_chain.py # Options strategy visualizer │ │ ├── stock_card.py # Individual stock analysis card │ │ └── regime_indicator.py # Bull/Bear/Neutral market regime │ ├── callbacks/ │ │ ├── on_chat_start.py # Session init, agent graph setup │ │ ├── on_message.py # Message handler → LangGraph invoke │ │ └── on_settings_change.py # User preference updates │ └── static/ │ ├── logo.png │ └── custom.css # Financial-themed dark UI │ ├── docs/ # Docusaurus documentation site │ ├── Dockerfile │ ├── package.json │ ├── docusaurus.config.js │ ├── sidebars.js │ ├── docs/ │ │ ├── intro.md # RAGHeat overview │ │ ├── getting-started/ │ │ │ ├── installation.md │ │ │ ├── quickstart.md │ │ │ └── configuration.md │ │ ├── architecture/ │ │ │ ├── overview.md # System architecture diagram │ │ │ ├── heat-diffusion.md # Heat equation mathematics │ │ │ ├── knowledge-graph.md # Neo4j schema + ontology │ │ │ ├── multi-agent.md # LangGraph agent topology │ │ │ └── data-pipeline.md # Kafka streaming architecture │ │ ├── api-reference/ │ │ │ ├── rest-api.md # OpenAPI spec documentation │ │ │ ├── websocket-api.md # WebSocket events │ │ │ └── cypher-queries.md # Common Cypher patterns │ │ ├── agents/ │ │ │ ├── orchestrator.md │ │ │ ├── fundamental.md │ │ │ ├── sentiment.md │ │ │ ├── technical.md │ │ │ ├── options.md │ │ │ ├── portfolio.md │ │ │ └── heat-diffusion.md │ │ ├── deployment/ │ │ │ ├── docker.md │ │ │ ├── kubernetes.md │ │ │ ├── monitoring.md │ │ │ └── compliance.md │ │ └── patents/ │ │ ├── heat-diffusion-patent.md │ │ └── dynamic-weight-patent.md │ ├── static/ │ │ └── img/ │ │ └── architecture.png │ └── src/ │ └── css/ │ └── custom.css │ ├── monitoring/ # Observability stack │ ├── prometheus/ │ │ └── prometheus.yml │ └── grafana/ │ ├── Dockerfile │ └── dashboards/ │ ├── ragheat-overview.json │ └── agent-performance.json │ └── nginx/ # Reverse proxy + load balancer ├── Dockerfile └── nginx.conf ``` --- ## DOCKER COMPOSE (Root Orchestrator) Generate `docker-compose.yml` with these services and configurations: ```yaml # Services to define: services: # --- DATA LAYER --- neo4j: image: neo4j:5-enterprise ports: ["7474:7474", "7687:7687"] environment: NEO4J_AUTH: neo4j/${NEO4J_PASSWORD} NEO4J_PLUGINS: '["graph-data-science", "apoc"]' NEO4J_dbms_security_procedures_unrestricted: "gds.*,apoc.*" NEO4J_dbms_memory_heap_max__size: "2G" volumes: - neo4j_data:/data - neo4j_logs:/logs healthcheck: test: ["CMD-SHELL", "neo4j status || exit 1"] interval: 10s retries: 5 redis: image: redis:7-alpine command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru ports: ["6379:6379"] volumes: - redis_data:/data postgres: image: postgres:16-alpine environment: POSTGRES_DB: ragheat POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data ports: ["5432:5432"] # --- STREAMING LAYER --- zookeeper: image: confluentinc/cp-zookeeper:7.6.0 environment: ZOOKEEPER_CLIENT_PORT: 2181 kafka: image: confluentinc/cp-kafka:7.6.0 depends_on: [zookeeper] ports: ["9092:9092"] environment: KAFKA_BROKER_ID: 1 KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181 KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092 KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT KAFKA_NUM_PARTITIONS: 3 KAFKA_DEFAULT_REPLICATION_FACTOR: 1 KAFKA_AUTO_CREATE_TOPICS_ENABLE: "true" volumes: - kafka_data:/var/lib/kafka/data # --- APPLICATION LAYER --- backend: build: context: ./backend dockerfile: Dockerfile ports: ["8000:8000"] environment: - NEO4J_URI=bolt://neo4j:7687 - NEO4J_USER=neo4j - NEO4J_PASSWORD=${NEO4J_PASSWORD} - REDIS_URL=redis://redis:6379 - KAFKA_BOOTSTRAP_SERVERS=kafka:29092 - POSTGRES_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/ragheat - OPENAI_API_KEY=${OPENAI_API_KEY} - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} - LANGSMITH_API_KEY=${LANGSMITH_API_KEY} - LANGSMITH_PROJECT=ragheat-production - LANGSMITH_TRACING_V2=true depends_on: neo4j: { condition: service_healthy } redis: { condition: service_started } kafka: { condition: service_started } postgres: { condition: service_started } volumes: - ./backend/app:/app/app # Dev hot reload healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"] interval: 15s retries: 3 frontend: build: context: ./frontend dockerfile: Dockerfile ports: ["8080:8080"] environment: - BACKEND_URL=http://backend:8000 - CHAINLIT_AUTH_SECRET=${CHAINLIT_AUTH_SECRET} depends_on: backend: { condition: service_healthy } docs: build: context: ./docs dockerfile: Dockerfile ports: ["3000:3000"] # --- OBSERVABILITY --- prometheus: image: prom/prometheus:latest ports: ["9090:9090"] volumes: - ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml grafana: image: grafana/grafana:latest ports: ["3001:3000"] environment: GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD} volumes: - grafana_data:/var/lib/grafana - ./monitoring/grafana/dashboards:/etc/grafana/provisioning/dashboards # --- REVERSE PROXY --- nginx: build: context: ./nginx dockerfile: Dockerfile ports: ["80:80", "443:443"] depends_on: [backend, frontend, docs] volumes: neo4j_data: neo4j_logs: redis_data: postgres_data: kafka_data: grafana_data: ``` --- ## BACKEND SPECIFICATIONS ### 1. FastAPI Application (`backend/app/main.py`) - Use FastAPI with `lifespan` context manager (not deprecated `on_event`) - Initialize: Neo4j async driver, Redis connection pool, Kafka producer, LangGraph agent graph - Mount routes: `/api/chat`, `/api/stocks`, `/api/portfolio`, `/api/options`, `/api/market`, `/api/graph`, `/api/heat`, `/api/health` - WebSocket endpoints: `/ws/chat-stream` (streaming chat), `/ws/heat-updates` (live heat distribution) - Middleware: CORSMiddleware (configurable origins), rate limiting (slowapi), request logging, Prometheus metrics - Startup tasks: seed Neo4j schema, start Kafka consumers, initialize heat engine cache - Expose OpenAPI docs at `/docs` and `/redoc` ### 2. LangGraph Multi-Agent Orchestrator (`backend/app/agents/orchestrator.py`) This is the CORE of the system. Implement using LangGraph's StateGraph pattern: ```python # Conceptual structure — generate full production implementation from langgraph.graph import StateGraph, END from langgraph.checkpoint.postgres import PostgresSaver from langchain_core.messages import HumanMessage, AIMessage from typing import TypedDict, Annotated, Sequence import operator class AgentState(TypedDict): messages: Annotated[Sequence[BaseMessage], operator.add] query_type: str # "stock_analysis", "portfolio", "options", "market_overview", "heat_map" symbols: list[str] # Detected stock tickers heat_context: dict # Current heat distribution snapshot graph_context: dict # Retrieved knowledge graph subgraph agent_results: dict # Accumulated agent outputs market_regime: str # "bull", "bear", "neutral" confidence: float # Consensus confidence score recommendation: dict # Final recommendation payload visualization_data: dict # Data for Chainlit UI rendering # Agent nodes: # 1. query_classifier → Classify intent, extract tickers, determine routing # 2. heat_diffusion_agent → Run heat engine, get influence propagation # 3. knowledge_graph_agent → Query Neo4j for context (GraphRAG + PathRAG) # 4. fundamental_agent → Analyze financials (P/E, revenue, margins) # 5. sentiment_agent → News + social sentiment scoring # 6. technical_agent → RSI, MACD, Bollinger, support/resistance # 7. options_agent → Greeks, IV surface, strategy recommendations # 8. portfolio_agent → Allocation optimization, risk metrics # 9. explanation_agent → Synthesize all results into natural language #10. visualization_router → Prepare charts/graphs for Chainlit rendering # Routing logic: # - "Analyze AAPL" → heat_diffusion → knowledge_graph → [fundamental, sentiment, technical] → explanation # - "Build me a portfolio" → heat_diffusion → knowledge_graph → portfolio_agent → explanation # - "Options strategy for NVDA" → heat_diffusion → options_agent → explanation # - "Show me the heat map" → heat_diffusion → visualization_router # - "What's the market doing?" → heat_diffusion → [sentiment, technical] → explanation # Conditional edges based on query_type # Parallel execution where possible (LangGraph fan-out/fan-in) # LangSmith tracing on every node ``` **CRITICAL REQUIREMENTS for the orchestrator:** - Use `langgraph.checkpoint.postgres.PostgresSaver` for conversation persistence across sessions - Implement streaming with `astream_events` for real-time token delivery to Chainlit - Each agent node must return structured output with `confidence` scores - The explanation agent must cite which agents contributed to the recommendation - Include a "human-in-the-loop" node for high-stakes portfolio changes (optional approval) - Every agent call must be wrapped with LangSmith tracing decorators - Support multi-turn conversation with full state history ### 3. Heat Diffusion Engine (`backend/app/core/heat_engine.py`) Implement the patented physics-based heat diffusion system per Patent US 2025/XXXXXXX: ```python # Core heat equation: ∂h(τ)/∂τ = −βL · h(τ) # Heat kernel solution: h(τ) = exp(−βLτ) · h₀ # Spectral decomposition: exp(−βLτ) = U · diag(exp(−βλ₁τ), ..., exp(−βλₙτ)) · Uᵀ class HeatDiffusionEngine: """ Physics-inspired heat diffusion framework for financial market prediction. Implements Graph Laplacian operators on financial knowledge graphs. Patent Claims Implemented: - Claim 1: Graph construction → Laplacian → heat diffusion → predictions - Claim 6: Spectral decomposition for efficient computation - Claim 7: Attention-weighted heat diffusion (GAT integration) - Claim 9: Adaptive β based on market regime (HMM) - Claim 16: Heat-diffused covariance matrix for portfolio optimization - Claim 19: HMM-based regime detection for parameter adjustment - Claim 20: Options trading via heat variance σ²_h(τ) """ def __init__(self, neo4j_client, regime_detector, config): # Initialize with Neo4j connection, HMM regime detector, config pass async def build_laplacian(self) -> np.ndarray: """Compute L = D - A from current financial knowledge graph""" pass async def compute_heat_kernel(self, tau: float, beta: float) -> np.ndarray: """h(τ) = exp(-βLτ) · h₀ via eigendecomposition""" pass async def propagate_heat(self, heat_sources: dict, steps: int = 5) -> dict: """Propagate influence from heat sources through the graph""" pass async def get_optimal_diffusion_time(self, epsilon: float = 0.01) -> float: """τ* = (1/βλ₂) · log(‖h₀ - h_eq‖₂ / ε)""" pass async def compute_heat_covariance(self, tau: float) -> np.ndarray: """Σ_heat(τ) = K(τ) · Σ_raw · K(τ)ᵀ for portfolio optimization""" pass async def compute_heat_variance(self, tau: float) -> dict: """σ²_h(τ) volatility signal for options pricing""" pass ``` **Implementation details:** - Use `scipy.linalg.expm` for matrix exponential (small graphs) or Chebyshev polynomial approximation (large graphs) - Cache eigendecomposition in Redis with 60-second TTL - GPU acceleration via PyTorch when available (`torch.matrix_exp`) - Batch graph updates every 5 seconds from Kafka stream - Ten factor categories as initial heat sources (per Patent Table 1): - Macroeconomic (10-15%): Fed rates, GDP, inflation, employment - Microeconomic (25-35%): Earnings, revenue, margins, guidance - News Sentiment (10-15%): NLP-processed financial news - Social Media (8-12%): Reddit, Twitter, StockTwits sentiment - Order Flow (15-20%): Bid-ask spread, volume, microstructure - Options Flow (12-18%): Put/call ratios, unusual activity - Sector Correlations (8-12%): Industry relationships, rotation - Supply Chain (5-8%): Supplier-customer dependencies - Technical (10-15%): Momentum, volatility, support/resistance - Specialized Quant (5-8%): Proprietary quantitative signals ### 4. Dynamic Weight Normalization (Patent 2) Implement Kalman Filter-based dynamic weight adjustment: ```python class DynamicWeightNormalizer: """ Patent 2: Dynamic Weight Normalization for Multi-Factor Financial Models. Uses Kalman filtering to adaptively adjust factor weights based on regime. """ def __init__(self, regime_detector): self.regime_detector = regime_detector # State: factor weights vector # Observation: factor performance metrics async def update_weights(self, market_data: dict) -> dict: """ Kalman filter update cycle: 1. Predict next weights based on transition model 2. Observe actual factor performance 3. Update weights via Kalman gain 4. Adjust based on detected regime (bull → momentum, bear → risk) """ pass async def get_regime_adjusted_weights(self) -> dict: """ Bull: Increase momentum (25-35%), social (12%), options flow (18%) Bear: Increase macro (15%), risk factors, reduce momentum Neutral: Balanced allocation across all ten categories """ pass ``` ### 5. Neo4j Knowledge Graph Schema Generate Cypher schema for the financial knowledge graph: ```cypher // Node Types (25+ entity types as per RAGHeat ontology) // Core Financial Entities CREATE CONSTRAINT stock_ticker IF NOT EXISTS FOR (s:Stock) REQUIRE s.ticker IS UNIQUE; CREATE CONSTRAINT sector_name IF NOT EXISTS FOR (s:Sector) REQUIRE s.name IS UNIQUE; CREATE CONSTRAINT market_id IF NOT EXISTS FOR (m:Market) REQUIRE m.id IS UNIQUE; // Node labels: Stock, Sector, Market, Index, ETF, EconomicIndicator, // NewsEvent, SocialSignal, OptionsContract, Factor, Analyst, // Earnings, SECFiling, SupplyChainEntity, CentralBank, // Commodity, Currency, Bond, CryptoAsset, RiskFactor, // TechnicalSignal, RegimeState, HeatSource, DecisionTrace // Relationship types: // (:Stock)-[:BELONGS_TO]->(:Sector) // (:Stock)-[:CORRELATED_WITH {weight: float, timeframe: str}]->(:Stock) // (:Stock)-[:SUPPLIES_TO]->(:Stock) // (:Stock)-[:COMPETES_WITH]->(:Stock) // (:Factor)-[:INFLUENCES {weight: float, regime: str}]->(:Stock) // (:NewsEvent)-[:MENTIONS {sentiment: float}]->(:Stock) // (:EconomicIndicator)-[:IMPACTS {lag_days: int}]->(:Sector) // (:OptionsContract)-[:UNDERLIES]->(:Stock) // (:Sector)-[:CONTAINS_STOCK]->(:Stock) // (:Market)-[:CONTAINS_SECTOR]->(:Sector) // (:DecisionTrace)-[:BASED_ON]->(:Factor) // (:DecisionTrace)-[:RESULTED_IN {outcome: str}]->(:Stock) // Vector index for semantic search CREATE VECTOR INDEX stock_embeddings IF NOT EXISTS FOR (s:Stock) ON (s.embedding) OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}; // Full-text index for news search CREATE FULLTEXT INDEX news_search IF NOT EXISTS FOR (n:NewsEvent) ON EACH [n.headline, n.summary]; // GDS projections for algorithms // FastRP embeddings for structural similarity // Louvain for sector/community detection // Node Similarity for finding similar stocks ``` ### 6. Real-Time Data Pipeline ``` Market Data Sources (Yahoo Finance, FRED, News APIs) ↓ Kafka Topics: - ragheat.market.prices (5-sec updates during market hours) - ragheat.market.news (real-time news events) - ragheat.market.sentiment (social media signals) - ragheat.market.options (options flow data) - ragheat.graph.updates (graph modification events) - ragheat.heat.recalc (heat recalculation triggers) ↓ Stream Processor (Flink-style consumer): - Aggregate windows (5s, 30s, 5m) - Trigger heat recalculation on significant events - Update Neo4j graph with new data - Push heat distribution updates via WebSocket ↓ Redis Cache: - Current heat distribution (60s TTL) - Eigendecomposition cache (60s TTL) - Market regime state (30s TTL) - Recent recommendations (5min TTL) ``` ### 7. Hybrid Retrieval (GraphRAG + PathRAG + Heat) ```python class HybridRetriever: """ Combines three retrieval strategies: 1. GraphRAG: Extract subgraphs around query-relevant entities 2. PathRAG: Multi-hop reasoning paths (e.g., AAPL → Tech Sector → Fed Rate) 3. Heat-Weighted: Prioritize nodes with high heat scores Fusion: Score = α·graph_score + β·path_score + γ·heat_score where α, β, γ are regime-dependent (from DynamicWeightNormalizer) """ async def retrieve(self, query: str, symbols: list[str], k: int = 10) -> RetrievalResult: # 1. Vector search on query embedding # 2. Subgraph extraction around detected entities # 3. Multi-hop path discovery (up to 3 hops) # 4. Heat-score reranking # 5. Evidence triangulation across all three methods pass ``` --- ## FRONTEND SPECIFICATIONS (Chainlit) ### Chainlit Application (`frontend/app.py`) Build a production Chainlit chatbot with these features: ```python import chainlit as cl from chainlit.element import Text, Image, Plotly import httpx import json # Configure Chainlit for production # .chainlit/config.toml settings: # [project] # name = "RAGHeat Financial Advisor" # [UI] # name = "RAGHeat" # description = "AI-Powered Stock Market Analysis with Heat Diffusion Intelligence" # default_collapse_content = true # github = "https://github.com/aisemanticexpert/RAGHEAT" # [UI.theme] # primary = "#1a73e8" # Financial blue # background = "#0d1117" # Dark mode # paper = "#161b22" @cl.on_chat_start async def on_chat_start(): """Initialize session with LangGraph agent and display welcome message""" # 1. Create httpx async client to backend # 2. Send welcome message with market overview # 3. Display current market regime indicator (bull/bear/neutral) # 4. Show quick action buttons: "Market Overview", "Top Heat Stocks", "Build Portfolio" # Render inline interactive graph visualization of current heat map # using Plotly or custom HTML element @cl.on_message async def on_message(message: cl.Message): """ Handle user messages: 1. Send to backend /api/chat with streaming 2. Display agent "thinking" steps as Chainlit Steps 3. Render recommendations with rich formatting 4. Show interactive visualizations inline """ # Stream response from backend async with httpx.AsyncClient() as client: async with client.stream("POST", f"{BACKEND_URL}/api/chat", json={ "message": message.content, "session_id": cl.user_session.get("session_id"), "conversation_history": cl.user_session.get("history", []) }) as response: # Stream tokens to Chainlit UI msg = cl.Message(content="") async for chunk in response.aiter_text(): event = json.loads(chunk) if event["type"] == "agent_step": # Show which agent is working as a Chainlit Step async with cl.Step(name=event["agent_name"]) as step: step.output = event["content"] elif event["type"] == "token": await msg.stream_token(event["content"]) elif event["type"] == "visualization": # Render inline chart/graph if event["viz_type"] == "heat_map": await render_heat_map(event["data"]) elif event["viz_type"] == "portfolio_pie": await render_portfolio(event["data"]) elif event["viz_type"] == "knowledge_graph": await render_graph(event["data"]) elif event["viz_type"] == "options_payoff": await render_options(event["data"]) elif event["type"] == "recommendation": await render_recommendation_card(event["data"]) await msg.send() async def render_heat_map(data: dict): """Render interactive heat distribution map using Plotly""" # Plotly heatmap showing sector → stock heat propagation # Color intensity = heat score # Clickable nodes to drill down fig = create_heat_map_figure(data) await cl.Message(content="", elements=[ cl.Plotly(name="Heat Distribution", figure=fig) ]).send() async def render_knowledge_graph(data: dict): """Render interactive Neo4j subgraph visualization""" # Use D3.js force-directed graph embedded as HTML element # Nodes: stocks (color by heat), sectors, factors # Edges: relationships with weights html = generate_graph_html(data) await cl.Message(content="", elements=[ cl.Html(name="Knowledge Graph", content=html) ]).send() async def render_recommendation_card(data: dict): """ Rich recommendation card with: - Stock symbol + name + current price - Recommendation: STRONG BUY / BUY / HOLD / SELL / STRONG SELL - Heat score with visual indicator - Confidence level - Agent consensus breakdown - Key reasoning points (cited from which agent) - Risk factors """ pass ``` ### Chainlit UI Features Required: 1. **Dark financial theme** — professional Bloomberg-style dark UI 2. **Agent thinking visualization** — show which agent is processing (Steps API) 3. **Inline interactive charts** — Plotly for heat maps, portfolio pie, price charts 4. **Knowledge graph viewer** — D3.js or NVL force-directed graph 5. **Quick action buttons** — predefined queries as clickable actions 6. **Streaming responses** — real-time token streaming for natural conversation 7. **Multi-modal outputs** — text + charts + tables + graphs in single response 8. **Session persistence** — conversation history via PostgreSQL checkpoint 9. **User settings panel** — risk tolerance, preferred sectors, portfolio size 10. **Market regime indicator** — persistent top bar showing Bull/Bear/Neutral --- ## DOCUMENTATION (Docusaurus) ### Docusaurus Configuration (`docs/docusaurus.config.js`) ```javascript module.exports = { title: 'RAGHeat Documentation', tagline: 'Physics-Inspired AI for Financial Markets', url: 'https://ragheat.io', baseUrl: '/', organizationName: 'ragheat', projectName: 'ragheat-platform', themeConfig: { navbar: { title: 'RAGHeat', items: [ { type: 'docSidebar', sidebarId: 'docsSidebar', label: 'Docs' }, { to: '/api', label: 'API Reference' }, { to: '/patents', label: 'Patents' }, { href: 'https://github.com/aisemanticexpert/RAGHEAT', label: 'GitHub' } ] }, algolia: { /* search config */ }, prism: { theme: require('prism-react-renderer/themes/dracula') } }, presets: [ ['classic', { docs: { sidebarPath: require.resolve('./sidebars.js') }, theme: { customCss: require.resolve('./src/css/custom.css') } }] ] }; ``` ### Documentation Pages Required: 1. **Getting Started** — Install, configure, run with Docker 2. **Architecture Overview** — System diagram, component descriptions, data flow 3. **Heat Diffusion Mathematics** — Full equation derivations, proofs, examples 4. **Knowledge Graph Schema** — Entity types, relationships, Cypher examples 5. **Multi-Agent System** — Agent descriptions, LangGraph topology, routing logic 6. **API Reference** — Auto-generated from OpenAPI spec + WebSocket docs 7. **Deployment Guide** — Docker, Kubernetes, cloud deployment patterns 8. **Monitoring & Observability** — Prometheus metrics, Grafana dashboards, LangSmith 9. **Patent Documentation** — Heat Diffusion Patent + Dynamic Weight Patent summaries 10. **Compliance & Security** — Financial regulatory considerations, data handling --- ## KEY TECHNOLOGY SPECIFICATIONS | Component | Technology | Version | Purpose | |-----------|-----------|---------|---------| | Backend Framework | FastAPI | 0.115+ | Async REST + WebSocket API | | Agent Orchestration | LangGraph | 0.2+ | Multi-agent state machine | | Agent Framework | LangChain | 0.3+ | Tool calling, chains, prompts | | Observability | LangSmith | latest | Agent tracing, evaluation | | LLM Provider | OpenAI GPT-4o / Anthropic Claude | latest | Reasoning + generation | | Graph Database | Neo4j Enterprise | 5.x | Knowledge graph + vector search | | Graph Algorithms | Neo4j GDS | 2.x | FastRP, Louvain, similarity | | Frontend | Chainlit | 1.3+ | Production chatbot UI | | Message Broker | Apache Kafka | 7.6+ | Real-time data streaming | | Cache | Redis | 7.x | Heat cache, session store | | Persistence | PostgreSQL | 16 | LangGraph checkpoints, user data | | Scientific Computing | NumPy, SciPy, PyTorch | latest | Heat diffusion, matrix ops | | Graph ML | PyTorch Geometric | latest | GAT embeddings | | Vector Search | FAISS + Neo4j Vector | latest | Semantic retrieval | | NLP | FinBERT, sentence-transformers | latest | Financial text embeddings | | Documentation | Docusaurus | 3.x | Technical documentation site | | Monitoring | Prometheus + Grafana | latest | Metrics + dashboards | | Reverse Proxy | Nginx | latest | Load balancing, SSL termination | | Containerization | Docker + Compose | latest | Service orchestration | --- ## DOCKERFILE TEMPLATES ### Backend Dockerfile (`backend/Dockerfile`) ```dockerfile FROM python:3.12-slim AS base WORKDIR /app RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential curl && rm -rf /var/lib/apt/lists/* RUN pip install uv COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev COPY app/ ./app/ COPY scripts/ ./scripts/ EXPOSE 8000 HEALTHCHECK CMD curl -f http://localhost:8000/api/health || exit 1 CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"] ``` ### Frontend Dockerfile (`frontend/Dockerfile`) ```dockerfile FROM python:3.12-slim WORKDIR /app RUN pip install uv COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev COPY . . EXPOSE 8080 CMD ["uv", "run", "chainlit", "run", "app.py", "--host", "0.0.0.0", "--port", "8080"] ``` ### Docs Dockerfile (`docs/Dockerfile`) ```dockerfile FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:alpine COPY --from=0 /app/build /usr/share/nginx/html EXPOSE 3000 ``` --- ## CONTEXT GRAPH PATTERN (Neo4j Decision Tracing) Implement the Context Graph pattern from the Neo4j demo for decision tracing: ```python class ContextGraphManager: """ Implements Context Graphs for AI-powered decision tracing. Every recommendation is recorded with full causal chain. Pattern from: https://github.com/johnymontana/context-graph-demo Structure: (:User)-[:ASKED]->(:Query)-[:TRIGGERED]->(:AgentRun) (:AgentRun)-[:USED_TOOL]->(:ToolCall) (:AgentRun)-[:CONSULTED]->(:DataSource) (:AgentRun)-[:PRODUCED]->(:Recommendation) (:Recommendation)-[:BASED_ON]->(:Evidence) (:Recommendation)-[:SIMILAR_TO]->(:Recommendation) # via GDS similarity (:Evidence)-[:FROM_FACTOR]->(:Factor) (:Evidence)-[:HEAT_SCORED {score: float}]->(:Stock) """ async def trace_decision(self, query, agent_results, recommendation): """Record complete decision trace in Neo4j""" pass async def find_similar_decisions(self, recommendation, k=5): """Use FastRP + KNN to find similar past decisions and outcomes""" pass async def get_decision_chain(self, recommendation_id): """Retrieve full causal chain for explainability""" pass ``` --- ## PRODUCTION REQUIREMENTS ### Performance Targets - API response time: < 200ms (cached), < 2s (full analysis) - Heat diffusion computation: < 2s for 500-node graph - WebSocket update latency: < 100ms - Kafka message processing: < 50ms per event - Neo4j query latency: < 1.6s for complex traversals - Concurrent users: 100+ simultaneous chat sessions ### Security - All API endpoints behind JWT authentication - Neo4j credentials via environment variables only - Rate limiting: 60 requests/minute per user - Input sanitization for Cypher injection prevention - TLS termination at Nginx - Secrets management via Docker secrets or Vault ### Monitoring - Prometheus metrics: request latency, agent execution time, heat computation time, error rates - Grafana dashboards: system overview, agent performance, heat distribution trends - LangSmith: full agent trace visibility, token usage, latency breakdown - Health check endpoints for all services - Structured JSON logging with correlation IDs ### Data Volume Handling - Stock universe: 495+ US stocks across all sectors - Real-time updates: 5-second refresh during market hours - Historical data: 2+ years for backtesting - News volume: 1000+ articles/day processed - Graph size: 10,000+ nodes, 50,000+ relationships - Kafka throughput: 10,000 messages/second peak --- ## SAMPLE CHAT INTERACTIONS The chatbot should handle these conversation patterns naturally: ``` User: "Analyze NVDA for me" → Orchestrator routes to: heat_diffusion → knowledge_graph → [fundamental, sentiment, technical] → explanation → Response includes: Heat score, sector position, P/E analysis, news sentiment, technical levels, recommendation with confidence User: "Build me a growth portfolio with $100K" → Orchestrator routes to: heat_diffusion → portfolio_agent → explanation → Response includes: Optimized allocation using Σ_heat(τ), expected return, Sharpe ratio, sector diversification chart User: "What options strategy for TSLA earnings?" → Orchestrator routes to: heat_diffusion → options_agent → explanation → Response includes: IV analysis, heat variance signal, straddle/strangle/spread recommendations, payoff diagram User: "Show me the heat map" → Orchestrator routes to: heat_diffusion → visualization_router → Response includes: Interactive Plotly heatmap of sector → stock heat propagation User: "Why is the tech sector heating up?" → Orchestrator routes to: heat_diffusion → knowledge_graph (PathRAG multi-hop) → sentiment → explanation → Response includes: Causal chain from heat sources, news events driving heat, graph visualization of propagation path User: "Compare my portfolio against SPY" → Orchestrator routes to: portfolio_agent → technical_agent → explanation → Response includes: Performance comparison, risk-adjusted returns, tracking error, rebalancing suggestions ``` --- ## GENERATION INSTRUCTIONS When generating this project: 1. **Start with `docker-compose.yml`** — ensure all services are properly networked and health-checked 2. **Generate backend first** — this is the core; ensure all agents, heat engine, and graph operations work 3. **Implement the LangGraph orchestrator** with full routing logic and state management 4. **Build the heat diffusion engine** with all patent-specified algorithms 5. **Create Neo4j schema and seed scripts** — the knowledge graph is the foundation 6. **Implement Kafka streaming pipeline** — real-time data is essential 7. **Build Chainlit frontend** with all visualization components 8. **Create Docusaurus documentation** with architecture diagrams 9. **Add monitoring stack** — Prometheus, Grafana, LangSmith integration 10. **Write comprehensive tests** for all critical paths **Every file must be production-quality:** - Type hints on all Python functions - Pydantic models for all request/response schemas - Comprehensive error handling with structured logging - Async/await throughout (no blocking calls) - Environment-driven configuration (no hardcoded values) - Docker health checks on every service - README.md in every subdirectory **The system must boot with a single command:** ```bash cp .env.example .env # Edit with your API keys docker compose up -d # System available at: # - Chatbot: http://localhost:8080 # - API Docs: http://localhost:8000/docs # - Neo4j Browser: http://localhost:7474 # - Documentation: http://localhost:3000 # - Grafana: http://localhost:3001 ``` --- ## REFERENCES - **RAGHeat Research Paper**: "RAGHeat: A Diffusion-Based Framework for Financial Recommendation Systems" - **Patent 1**: "Physics-Inspired Heat Diffusion Framework for Financial Market Prediction Using Graph Laplacian Operators on Financial Knowledge Graphs" (USPTO) - **Patent 2**: "Dynamic Weight Normalization for Multi-Factor Financial Models" (USPTO) - **Context Graph Demo**: https://github.com/johnymontana/context-graph-demo - **Neo4j Context Graphs**: https://neo4j.com/blog/agentic-ai/hands-on-with-context-graphs-and-neo4j/ - **Existing RAGHeat POC**: https://github.com/aisemanticexpert/RAGHEAT - **Chainlit + LangGraph Integration**: https://github.com/brucechou1983/chainlit_langgraph - **Neo4j MCP Servers**: https://github.com/neo4j-contrib/mcp-neo4j - **LangGraph Checkpoint Neo4j**: https://github.com/johnymontana/langgraph-checkpoint-neo4j --- *END OF UNIFIED GENERATION PROMPT*