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