How pacovk/ollama-deep-researcher-ts works
Main Components
a. Agent Module:
• Located in src/agent, this module handles crucial functionality such as managing configurations (src/agent/configuration.ts), keeping graph state (src/agent/graph.ts), handling prompts (src/agent/prompts.ts) and tracking state (src/agent/state.ts).
• It is the orchestrator that triggers and tracks the iterative research workflow.
b. Nodes (Processing Steps):
• Found in src/nodes, the nodes represent the individual steps of the research process:
• generateQuery: Creates the web search query using the local LLM.
• webResearch: Invokes a search engine (via Tavily) to retrieve search results.
• summarizeSources: Summarizes the collected search results.
• reflectSummary: Analyses the summary to identify knowledge gaps.
• finalizeSummary: Produces the final markdown summary that includes the research findings.
c. Routing / API Layer:
• In src/route, specifically src/route/research.ts, this part likely exposes an interface (e.g., a REST API endpoint) to trigger the research process.
d. External Integrations:
• Local LLM via Ollama: Configured in the agent configuration to hit endpoints like “http://localhost:11434” and set to pull models (e.g., deepseek-r1).
• Tavily API: Used for performing web searches as part of the research nodes.
• LangGraph Studio: The project integrates with LangGraph’s visualization and graph state management, as suggested by the docker-compose setup and references in the README.
e. Infrastructure and Deployment:
• Docker & docker-compose: The docker files (docker/Dockerfile and docker-compose.yml) indicate containerized deployment.
• Configuration files (.env.example, tsconfig.json, package.json, etc.) set up the environment for running TypeScript and Docker.
• CI/CD: The GitHub workflows (under .github/workflows) for unit tests indicate automated testing integration.
Relationships and Interactions
• How the Agent Module interacts with each “Node” in sequence:
• generateQuery → webResearch → summarizeSources → reflectSummary → finalizeSummary.
• “Agent Module” to external systems:
• How the output from nodes gets accumulated and stored in the “Graph State”, which is then visualized in LangGraph Studio.
• Use of Docker containers (deployment boundaries) via a container for the LangGraph server and possibly separate containers for the assistant.
Architectural Patterns and Design Principles
• The design resembles a pipeline or workflow orchestration where each node performs an independent step in the research process.
• There is a clear separation of concerns:
• Agent manages the overall workflow.
• Nodes perform specific, testable functions.
• Routing isolates the API layer from business logic.
• Containerization with Docker is used to ensure a reproducible environment across development and deployment.
Technologies, Frameworks, and Libraries
• TypeScript serves as the main programming language.
• Docker and docker-compose for container orchestration.
• LangGraph framework for visualizing and running the graph-based research workflow.
• ESLint, Jest (jest.config.js), and configuration files to enforce code standards and enable testing.
• External APIs – Ollama (for LLM processing) and Tavily (for web search).