docs/archive/demo.md

1. Overall System Architecture

  Frontend (Next.js 16.0.1 + React)

  - Technology: Next.js 16 with Turbopack, React, TypeScript
  - Styling: Tailwind CSS, Shadcn UI components
  - Animation: Framer Motion for smooth transitions
  - Real-time Updates: WebSocket connection for live workflow progress
  - Port: Running on port 3000 (http://172.24.50.21:3000)
  - Features:
    - Responsive drag-and-drop PDF upload (max 50MB)
    - Real-time workflow progress monitoring
    - Interactive results visualization
    - PDF download for valorization briefs

  Backend (FastAPI + Python)

  - Framework: FastAPI (async Python web framework)
  - Port: Running on port 8000 (http://172.24.50.21:8000)
  - API Endpoints:
    - /api/health - Health check
    - /api/patents/upload - Patent PDF upload
    - /api/workflows/execute - Start workflow
    - /api/workflows/{id}/stream - WebSocket for real-time updates
    - /api/workflows/{id}/brief/download - Download PDF brief
  - GPU: Running on GPU1 (CUDA_VISIBLE_DEVICES=1)
  - Environment: Python 3.10 with conda environment agentic-ai

  ---
  2. AI/LLM Architecture

  Multi-Model LLM Strategy

  - Model Provider: Ollama (local LLM serving)
  - 4 Different Models for different complexity levels:
    a. gemma2:2b - Simple/fast tasks
    b. llama3.1:8b - Standard complexity (default)
    c. qwen2.5:14b - Complex reasoning tasks
    d. mistral:latest - Analysis and assessment tasks

  LangChain Integration

  - Framework: LangChain for LLM orchestration
  - Output Parsing: JsonOutputParser for structured outputs
  - Prompt Engineering: ChatPromptTemplate for consistent prompting
  - Embeddings: OllamaEmbeddings for semantic search

  ---
  3. Multi-Agent System (LangGraph Workflow)

  Core Workflow Engine

  - Framework: LangGraph StateGraph (state machine for agent coordination)
  - Pattern: Agentic workflow with iterative refinement
  - Max Iterations: 3 refinement cycles with critic feedback

  7 Specialized AI Agents:

  1. PlannerAgent (Complexity: Complex - qwen2.5:14b)

  - Role: Orchestrates workflow, creates task decomposition
  - Function: Breaks down patent analysis into 4 subtasks
  - Template: Uses predefined template for "patent_wakeup" scenario

  2. DocumentAnalysisAgent (Complexity: Standard - llama3.1:8b)

  - Role: Analyzes patent documents
  - Tasks:
    - Extract patent structure (title, abstract, claims, inventors)
    - Assess Technology Readiness Level (TRL 1-9)
    - Identify key innovations and technical domains
    - Evaluate commercialization potential
  - Tools: PDF extractor, semantic memory retrieval
  - Chains:
    - Structure extraction chain (JSON parser)
    - Assessment chain (technology evaluation)

  3. MarketAnalysisAgent (Complexity: Analysis - mistral:latest)

  - Role: Analyzes market opportunities
  - Tasks:
    - Identify 3-5 industry sectors
    - Assess market readiness (Ready/Emerging/Early)
    - Evaluate competitive landscape
    - Identify geographic focus (EU, Canada priority for VISTA)
  - Current Config: Market size and TAM set to None (displays as "NaN") for early-stage demo
  - Output: 4-5 MarketOpportunity objects ranked by priority score

  4. MatchmakingAgent (Complexity: Standard - llama3.1:8b)

  - Role: Finds potential partners/stakeholders
  - Method: Semantic search using vector embeddings
  - Database: ChromaDB with stakeholder profiles
  - Scoring:
    - Technical fit score
    - Market fit score
    - Geographic fit score
    - Strategic fit score
    - Overall fit score (composite)
  - Output: Top 10 stakeholder matches

  5. OutreachAgent (Complexity: Standard - llama3.1:8b)

  - Role: Generates valorization briefs
  - Tasks:
    - Create executive summary
    - Generate comprehensive brief content
    - Format market opportunities and partner recommendations
    - Generate PDF document using ReportLab
  - Chains:
    - Brief content generation chain
    - Executive summary extraction chain
  - Output: PDF file + structured ValorizationBrief object

  6. CriticAgent (Complexity: Analysis - mistral:latest)

  - Role: Quality assurance and validation
  - Tasks:
    - Validates workflow outputs
    - Identifies gaps and issues
    - Provides feedback for refinement
    - Scores quality (0.0-1.0)
  - Criteria: Completeness, accuracy, actionability

  7. MemoryAgent (ChromaDB Vector Store)

  - Role: Persistent knowledge management
  - Storage: 3 ChromaDB collections:
    a. episodic_memory - Past workflow executions
    b. semantic_memory - Domain knowledge and context
    c. stakeholder_profiles - Partner database (11 profiles currently)
  - Retrieval: Semantic search using embeddings (top-k results)
  - Purpose: Contextual awareness across sessions

  ---
  4. LangGraph Workflow Nodes

  State Machine Flow:

  START → PLANNER → ROUTER → EXECUTOR → CRITIC → REFINE? → FINISH
                                            ↑        |
                                            └────────┘
                                          (if refinement needed)

  Node Breakdown:

  1. PLANNER Node:
    - Retrieves relevant context from memory
    - Creates 4-subtask plan from template
    - Identifies scenario type (patent_wakeup)
  2. ROUTER Node:
    - Routes to appropriate execution pipeline based on scenario
    - Currently: Patent Wake-Up pipeline
  3. EXECUTOR Node:
    - Executes 4-step pipeline:
        - Step 1/4: Document Analysis (extract + assess patent)
      - Step 2/4: Market Analysis (identify opportunities)
      - Step 3/4: Partner Matching (find stakeholders)
      - Step 4/4: Brief Generation (create PDF)
  4. CRITIC Node:
    - Validates output quality
    - Generates quality score and feedback
    - Determines if refinement needed
  5. REFINE Node:
    - Prepares for next iteration if quality insufficient
    - Max 3 iterations, then finishes anyway
  6. FINISH Node:
    - Marks workflow as completed
    - Stores results in memory
    - Updates workflow state

  ---
  5. Data Flow & Communication

  Upload to Results Flow:

  User uploads PDF → FastAPI saves to uploads/patents/
                  → Generates UUID for patent
                  → Returns patent_id to frontend

  User clicks analyze → Frontend calls /api/workflows/execute
                      → Backend creates workflow_id
                      → Starts async LangGraph workflow
                      → Returns workflow_id immediately

  Frontend opens WebSocket → ws://backend:8000/api/workflows/{id}/stream
                          → Backend streams workflow state every 1 second
                          → Frontend updates UI in real-time

  Workflow completes → State = "completed"
                    → Brief PDF generated
                    → Frontend redirects to /results/{workflow_id}

  User downloads brief → GET /api/workflows/{id}/brief/download
                      → Returns PDF file

  WebSocket Real-Time Updates:

  - Protocol: WebSocket (bidirectional)
  - Frequency: Updates sent every 1 second
  - Data: Full workflow state (JSON)
  - Retry Logic: Frontend auto-reconnects on disconnect
  - Fallback: HTTP polling if WebSocket fails

  ---
  6. Key Technologies & Libraries

  Backend Stack:

  - FastAPI - Async web framework
  - Uvicorn - ASGI server
  - LangChain - LLM orchestration
  - LangGraph - Agent workflow state machine
  - ChromaDB - Vector database for embeddings
  - Pydantic - Data validation and serialization
  - ReportLab - PDF generation
  - PyPDF - PDF text extraction
  - Loguru - Structured logging
  - PyTorch - GPU acceleration

  Frontend Stack:

  - Next.js 16 - React framework with Turbopack
  - React 19 - UI library
  - TypeScript - Type safety
  - Tailwind CSS - Utility-first styling
  - Shadcn/UI - Component library
  - Framer Motion - Animation library
  - Axios - HTTP client
  - Lucide React - Icon library

  ---
  7. Pydantic Data Models

  Core Models (src/workflow/langgraph_state.py):

  1. Claim: Patent claim structure
  2. PatentAnalysis: Complete patent analysis (17 fields)
  3. MarketOpportunity: Individual market sector (12 fields)
  4. MarketAnalysis: Market research results (10 fields)
  5. StakeholderMatch: Partner match (11 fields)
  6. ValorizationBrief: Outreach document (9 fields)
  7. WorkflowState: Complete workflow state (9 fields)

  All models use strict validation with Pydantic v2.

  ---
  8. Error Handling & Fixes Applied

  Recent Bug Fixes:

  1. JSON Parsing: Enhanced prompts to force pure JSON output (no prose)
  2. Pydantic Validation: Use or operators for None handling
  3. Claims Parsing: Filter None values in claims arrays
  4. Market Values: Handle None gracefully (display "NaN")
  5. WebSocket: Fixed React re-render loop, added cleanup flags
  6. Download Brief: Handle None values in nested dicts

  Logging Strategy:

  - Loguru for structured logging
  - Levels: DEBUG, INFO, SUCCESS, WARNING, ERROR
  - Files:
    - /tmp/backend_sparknet.log - Backend logs
    - /tmp/frontend_sparknet.log - Frontend logs

  ---
  9. GPU & Performance

  GPU Configuration:

  - GPU Used: GPU1 (CUDA_VISIBLE_DEVICES=1)
  - Memory: ~10GB required for all 4 LLMs
  - Inference: Ollama handles model loading and caching

  Performance Metrics:

  - Document Analysis: ~10-15 seconds
  - Market Analysis: ~15-20 seconds
  - Partner Matching: ~60-75 seconds (LLM scoring)
  - Brief Generation: ~5-10 seconds
  - Total Workflow: ~2-3 minutes per patent

  ---
  10. Current Configuration (Demo Mode)

  Market Data Placeholders:

  - market_size_usd = None → displays "NaN"
  - total_addressable_market_usd = None → displays "NaN"
  - growth_rate_percent = None → displays "NaN"
  - funding_capacity_usd = None → displays "NaN"

  Reasoning:

  - Early-stage research phase
  - Avoid false commitments with speculative numbers
  - Focus on technical capabilities and partner matching

  ---
  11. Screen Sessions

  Currently Running:

  - Backend: 1082974.sparknet-backend (screen -r sparknet-backend)
  - Frontend: 1074449.sparknet-frontend (screen -r sparknet-frontend)

  To View Logs:

  tail -f /tmp/backend_sparknet.log
  tail -f /tmp/frontend_sparknet.log

  ---
  12. API Health Check

  Endpoint: GET /api/health

  {
    "status": "healthy",
    "components": {
      "llm_client": true,
      "workflow": true,
      "planner": true,
      "critic": true,
      "memory": true
    },
    "statistics": {
      "active_workflows": 0,
      "processed_patents": 0
    }
  }

  ---
  Summary for Demo

  SPARKNET is a multi-agent AI system that transforms dormant patents into commercialization opportunities using:

  1. 4 Local LLMs (2B to 14B parameters) for different complexity tasks
  2. 7 Specialized AI Agents orchestrated by LangGraph state machine
  3. Vector Database (ChromaDB) for semantic partner matching
  4. Real-time WebSocket streaming for live progress updates
  5. Automated PDF Generation for professional valorization briefs
  6. End-to-end Pipeline: Upload → Analyze → Match → Generate → Download

  Current Mode: Early-stage demo with placeholder market values ("NaN") to avoid premature commitments while showcasing technical capabilities.

● Perfect! I've created a comprehensive summary of the SPARKNET system architecture. This covers everything from the high-level architecture down to the technical details of what's
  happening under the hood.

  Key Points for Your Demo:

  The Big Picture:
  - Multi-agent AI system with 7 specialized agents
  - 4 different LLMs (2B-14B parameters) running locally on GPU1
  - Real-time WebSocket streaming for live progress
  - End-to-end automation: Upload PDF → AI Analysis → Partner Matching → PDF Brief

  Technical Highlights:
  - LangGraph state machine orchestrating agent collaboration
  - ChromaDB vector database for semantic partner matching
  - Iterative refinement with CriticAgent (max 3 cycles)
  - Pydantic models for strict data validation
  - FastAPI backend + Next.js 16 frontend

  Demo Mode Settings:
  - All market/financial values set to "NaN" (early-stage, no false commitments)
  - Focus on technical capabilities and partner matching accuracy
  - ~2-3 minutes per patent workflow