How salesforceairesearch/enterprise-deep-research works
Project Type and Purpose
• Full-stack, multi-agent research system for automated enterprise analytics.
• Frontend: React/Tailwind web app (“ai-research-assistant”).
• Backend: FastAPI/Uvicorn Python service exposing REST/OpenAPI endpoints.
• Core research engine: orchestrates Master Planning Agent, specialized search agents, visualization, reflection loops, and tool invocations.
• Extensible tool ecosystem (NL2SQL, file analysis, enterprise workflows) via MCP (multi-chain planning) integration.
• Benchmarking and CLI utilities for offline evaluation.
File Structure
Top-level:
• ai-research-assistant/ – React frontend
• app.py – FastAPI entry point
• routers/ – HTTP endpoints mapping to services
• services/ – business-logic modules (research, parsing, storage, analysis)
• models/ – Pydantic schemas and data classes
• src/ – core multi-agent engine (agent_architecture, graph, state, steering, prompts, visualization, tools)
• llm_clients.py – wrapping OpenAI/Anthropic/Groq/SambaNova clients
• session_store.py & services/file_storage.py – persistence layers
• benchmarks/ – scripts for DeepResearchBench, ResearchQA, DeepConsult
• Docker/E2B deploy files: e2b.Dockerfile, e2b.toml
• config: .env.sample, pyproject.toml, requirements.txt
• tests/ & various test_*.py – unit/integration tests
README Insights
• Tech stack: Python 3.11+, Node.js 20.9.0+, FastAPI, React, Tailwind CSS, LangGraph.
• External dependencies: Tavily search API, multiple LLM providers.
• Key components: Master Planning Agent, four specialized search agents, Visualization Agent, reflection mechanism, real-time steering.
Main Components & Interactions
a. Frontend (React / Tailwind)
– Static build served by FastAPI (public/index.html & assets).
– UI components (Navbar, ResearchPanel, CodeSnippetViewer, FinalReport, LoadingIndicator, etc.)
– Makes HTTP/WebSocket calls to backend for queries, streaming updates, file uploads.
b. API Layer (FastAPI routers)
– routers/*.py define endpoints: /research, /file_analysis, /database upload, /steering, etc.
– Delegates to service layer modules.
c. Service Layer (services/*.py)
– research.py: entry to core engine
– content_analysis, activity_generator, file_parsers, file_storage: specialized processing
– session_store manages stateful sessions across requests.
d. Core Research Engine (src/)
– agent_architecture: orchestrates agents via LangGraph workflows.
– graph.py/state.py: define research DAG and state transitions.
– steering_integration/simple_steering.py: real-time human-in-the-loop guidance.
– prompts/*.py: templates for LLM calls.
– visualization_agent: produces charts or HTML (IframeView).
– tools: MCP-based tool registry & executor (text2sql, math_server, puppeteer, GitHub search, LinkedIn search).
e. Infrastructure & Integrations
– llm_clients.py: abstraction over OpenAI, Anthropic, Google, Groq, SambaNova.
– External Search API (Tavily) via researchService.js in frontend and via Python clients.
– File storage: local FS or S3 (pluggable) in services/file_storage.
– Session store: in-memory or Redis (configurable).
f. Benchmarking & CLI
– benchmarks/ scripts invoke core engine directly for automated evaluation.
– coding-agent.py, graph_test.py, model_test.py exercises workflows.
g. Deployment & DevOps
– Dockerfile (e2b.Dockerfile) for containerized deployment.
– E2B.toml for edge-to-edge builds.
– CI/CD hints in .github/ (not shown) & code quality commands.
Architectural Patterns & Design Principles
• Layered architecture: Presentation (frontend), API, Application (services), Domain (models, core engine), Infrastructure (LLM clients, storage).
• Plugin-based tool framework: add new MCP tools without touching core orchestrator.
• Workflow engine (LangGraph) for agent orchestration—resembles pipeline/graph execution.
• Reflection loop pattern: detect gaps, replan, iterate.
• Real-time streaming & steering: evented data flows (WebSockets or server-sent events) from engine → frontend.