How eruaro/open-gemini-deep-research works
Project Type and Purpose
• This is an open-source CLI research assistant written in Python that orchestrates multi-layered queries through Google’s Gemini AI, processes results concurrently, tracks progress in a tree structure, and outputs a detailed report with citations.
File-Structure Analysis
• Top-level:
– main.py (CLI entry point)
– dockerfile & .devcontainer/ (Dev Container setup)
– requirements.txt & .env (dependencies and API key)
• src/:
– deep_research.py (core research engine)
• Outputs (implicit):
– final_report.md
– research_tree.json (progress tree)
• Patterns: monolithic service, modularized into CLI layer and research engine, uses external API, file-based persistence.
Key Architectural Insights from README
• Three research modes driving breadth/depth parameters
• Query Analysis → Query Generation → Research Tree Building → (recursive) Deep Research → Report Generation
• Concurrency for parallel queries
• ResearchProgress class implements a parent-child tree with UUIDs
• External dependency: Google Gemini AI API
a. Components
1. CLI Layer (main.py)
2. Research Engine (deep_research.py)
• Query Analyzer
• Query Generator
• ResearchProgress (tree manager)
• Deep Research Worker (recursive logic)
• Report Generator
3. Concurrency Manager (Python’s asyncio/threadpool)
4. External Service (Google Gemini AI)
5. Local Data Store (filesystem)
• research_tree.json
• final_report.md
6. Dev Container / Docker Environment
b. Data Flows
• User CLI → CLI Layer parses args → Research Engine
• Engine → Query Analyzer sets breadth/depth
• Query Generator emits seed queries → Concurrency Manager
• Workers call Gemini API → receive results → ResearchProgress updates tree
• Recursive calls for comprehensive mode
• Completed tree passed to Report Generator → writes final_report.md & research_tree.json
c. Architectural Patterns
– Modular layering (CLI vs. engine)
– Pipeline/chain of responsibility (analysis → generation → execution → aggregation)
– Recursive tree data structure
– Concurrent execution of tasks
d. Technologies
– Python 3.9+ with asyncio/concurrent.futures
– Google Gemini AI REST API
– Docker / Dev Container for environment consistency
– JSON for tree persistence; Markdown for final report