# raianrashidrimon/research-ai-agent architecture

> Architecture diagram of the GitHub repository raianrashidrimon/research-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raianrashidrimon/research-ai-agent
- Repository: https://github.com/raianrashidrimon/research-ai-agent

## Overview

1. **Overall shape**
   - This repo is a single Python application organized around a **serial multi-agent research pipeline**.
   - The architectural center is: **User query → Researcher → Writer → Fact Checker → final answer**.
   - The code is split into small boundaries for orchestration, agent behavior, external tools, persistence, and presentation.

2. **Primary package boundary**
   - The `Agent/` directory is the application package.
   - `Agent/agents/` holds the three specialized agent implementations.
   - `Agent/graph.py` appears to be the workflow coordinator.
   - `Agent/tools.py`, `Agent/memory.py`, `Agent/ui.py`, and `Agent/main.py` are supporting subsystems around that core pipeline.

3. **Workflow orchestration**
   - `graph.py` is the key architectural component for agent coordination.
   - It likely defines the execution order and message passing between the Researcher, Writer, and Fact Checker.
   - This is the place where the “serial pipeline” described in the README is enforced, rather than letting agents run independently.

4. **Agent responsibilities**
   - `agents/researcher.py` gathers raw material from external sources.
   - `agents/writer.py` converts raw findings into a readable summary.
   - `agents/fact_checker.py` verifies claims, flags uncertainty, and assigns a confidence level.
   - `agents/__init__.py` exposes these roles as a cohesive subpackage.

5. **External data acquisition boundary**
   - `tools.py` is the integration layer for external knowledge sources.
   - The README says it uses **DuckDuckGo Search**, **Wikipedia**, and **ArXiv**, so this module is the main boundary between the app and the outside world.
   - This is also where the architecture depends on network access and third-party search/content services.

6. **Memory and persistence**
   - `memory.py` provides cross-session memory, which is an important stateful subsystem in an otherwise query-driven workflow.
   - The README indicates the assistant “remembers what it has researched before,” so memory is not just in-request context; it persists across restarts.
   - This creates a second data path besides live search: prior research is loaded and reused when relevant.

7. **Presentation layer**
   - `ui.py` is the Streamlit-based chat UI.
   - The UI likely submits the user query into the pipeline, then renders the final summary plus supporting artifacts.
   - The README specifically mentions a sidebar for **sources** and **flagged claims**, so the UI is not just a text box; it visualizes provenance and verification status.

8. **Terminal entrypoint**
   - `main.py` is the non-UI entrypoint for running the assistant from the terminal.
   - This suggests two operating modes that share the same core workflow: CLI/terminal and Streamlit.
   - For an architecture diagram, both entrypoints should converge into the same orchestration layer, not duplicate the agent logic.

9. **LLM and framework dependencies**
   - The repo uses **Google Gemini** as the model provider, via a `.env`-supplied `GEMINI_API_KEY`.
   - The README also names **LangGraph** and **LangChain**, so the agent pipeline is framework-driven rather than hand-rolled.
   - These are enabling technologies for orchestration and tool use, but the important architectural fact is that the app is model-backed and tool-augmented.

10. **Output and trust model**
   - The fact checker produces a **confidence score**: HIGH, MEDIUM, or LOW.
   - It also flags uncertain or unverified claims, which means the final output is not just summarized text but a response annotated with trust signals.
   - This makes the system a research assistant with a verification layer, not a pure summarizer.

11. **Report persistence**
   - The README says reports can be saved to a local text file.
   - That implies a simple file-based output path for exporting the final research result outside the UI/session.
   - This is likely a lightweight persistence/output feature, separate from the long-term memory store.

12. **End-to-end data flow**
   - The main flow is: user query enters via Streamlit or terminal, the orchestrator dispatches to the Researcher, raw sources are summarized by the Writer, the Fact Checker validates the claims, and the final annotated answer is returned.
   - Along the way, source references and memory state are carried through the system.
   - For an architecture diagram, the most important boundaries are: **entrypoints**, **agent orchestration**, **external search tools**, **persistent memory**, and **presentation/output**.

Main entry points: [`Agent/agents/fact_checker.py`](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/fact_checker.py) (Fact checker), [`Agent/graph.py`](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/graph.py) (Workflow graph), [`Agent/tools.py`](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/tools.py) (Search tools), [`Agent/agents/researcher.py`](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/researcher.py) (Researcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["Agent package"]
  node_node_ui["Streamlit UI<br/>presentation<br/>[ui.py]"]
  node_node_cli["Terminal app<br/>entrypoint<br/>[main.py]"]
  node_node_graph{{"Workflow graph<br/>orchestrator<br/>[graph.py]"}}
  node_node_researcher["Researcher<br/>agent<br/>[researcher.py]"]
  node_node_writer["Writer<br/>agent<br/>[writer.py]"]
  node_node_checker["Fact checker<br/>agent<br/>[fact_checker.py]"]
  node_node_agents_init["Agents API<br/>subpackage<br/>[__init__.py]"]
  node_node_tools["Search tools<br/>integration<br/>[tools.py]"]
  node_node_memory[("Memory store<br/>state<br/>[memory.py]")]
  node_node_output["Saved report<br/>export"]
end

subgraph group_group_external["External systems"]
  node_node_gemini(("Gemini model<br/>llm provider"))
  node_node_duckduckgo(("DuckDuckGo<br/>search source"))
  node_node_wikipedia(("Wikipedia<br/>knowledge source"))
  node_node_arxiv(("ArXiv<br/>paper source"))
end

node_node_query["User query<br/>input"]

node_node_query -->|"submit"| node_node_ui
node_node_query -->|"run"| node_node_cli
node_node_ui -->|"dispatch"| node_node_graph
node_node_cli -->|"dispatch"| node_node_graph
node_node_graph -->|"step 1"| node_node_researcher
node_node_researcher -->|"retrieve"| node_node_tools
node_node_tools -->|"search"| node_node_duckduckgo
node_node_tools -->|"lookup"| node_node_wikipedia
node_node_tools -->|"search"| node_node_arxiv
node_node_researcher -->|"reuse"| node_node_memory
node_node_graph -->|"step 2"| node_node_writer
node_node_writer -->|"generate"| node_node_gemini
node_node_graph -->|"step 3"| node_node_checker
node_node_checker -->|"verify"| node_node_gemini
node_node_checker -->|"update"| node_node_memory
node_node_checker -->|"return"| node_node_ui
node_node_checker -->|"return"| node_node_cli
node_node_checker -->|"save"| node_node_output
node_node_agents_init -->|"expose"| node_node_researcher
node_node_agents_init -->|"expose"| node_node_writer
node_node_agents_init -->|"expose"| node_node_checker

click node_node_ui "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/ui.py"
click node_node_cli "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/main.py"
click node_node_graph "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/graph.py"
click node_node_researcher "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/researcher.py"
click node_node_writer "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/writer.py"
click node_node_checker "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/fact_checker.py"
click node_node_agents_init "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/__init__.py"
click node_node_tools "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/tools.py"
click node_node_memory "https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/memory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_ui,node_node_cli,node_node_graph,node_node_researcher,node_node_writer,node_node_checker,node_node_agents_init,node_node_tools,node_node_memory,node_node_output toneBlue
class node_node_gemini,node_node_duckduckgo,node_node_wikipedia,node_node_arxiv toneAmber
class node_node_query toneNeutral
```

## Components

### Agent package

Core application package containing orchestration, agents, entrypoints, and support subsystems.

- [Streamlit UI](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/ui.py): presentation · Chat interface for submitting queries and viewing sources and flags. · `Agent/ui.py`
- [Terminal app](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/main.py): entrypoint · Command-line entrypoint for running the assistant without the UI. · `Agent/main.py`
- [Workflow graph](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/graph.py): orchestrator · Coordinates the serial research pipeline and message passing between agents. · `Agent/graph.py`
- [Researcher](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/researcher.py): agent · Collects raw evidence from external sources and prior context. · `Agent/agents/researcher.py`
- [Writer](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/writer.py): agent · Turns research findings into a readable draft summary. · `Agent/agents/writer.py`
- [Fact checker](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/fact_checker.py): agent · Verifies claims, flags uncertainty, and assigns confidence. · `Agent/agents/fact_checker.py`
- [Agents API](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/agents/__init__.py): subpackage · Exports the agent roles as a cohesive package boundary. · `Agent/agents/__init__.py`
- [Search tools](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/tools.py): integration · Tooling layer for external knowledge sources and retrieval. · `Agent/tools.py`
- [Memory store](https://github.com/raianrashidrimon/research-ai-agent/blob/main/Agent/memory.py): state · Cross-session research memory reused across runs. · `Agent/memory.py`
- **Saved report**: export · Local text-file output for persisted research reports.

### External systems

Model provider and knowledge sources used by the application.

- **Gemini model**: llm provider · LLM backend used for generation and verification tasks.
- **DuckDuckGo**: search source · Web search source used by the research agent.
- **Wikipedia**: knowledge source · Reference source used during research.
- **ArXiv**: paper source · Scientific paper source used during research.

### Other components

- **User query**: input · Incoming research question or prompt.

## Connections

- User query → Streamlit UI: submit · User enters a question through the Streamlit interface.
- User query → Terminal app: run · User passes a question through the terminal entrypoint.
- Streamlit UI → Workflow graph: dispatch · UI forwards the request into the shared workflow.
- Terminal app → Workflow graph: dispatch · CLI forwards the request into the shared workflow.
- Workflow graph → Researcher: step 1 · Orchestrator sends the query to the research agent.
- Researcher → Search tools: retrieve · Researcher uses tools to gather evidence.
- Search tools → DuckDuckGo: search · Tooling queries web search.
- Search tools → Wikipedia: lookup · Tooling pulls reference material from Wikipedia.
- Search tools → ArXiv: search · Tooling searches academic papers.
- Researcher → Memory store: reuse · Researcher consults prior research memory.
- Workflow graph → Writer: step 2 · Orchestrator passes research findings to the writer.
- Writer → Gemini model: generate · Writer uses the model to compose the summary.
- Workflow graph → Fact checker: step 3 · Orchestrator sends the draft to fact checking.
- Fact checker → Gemini model: verify · Fact checker uses the model to assess claims and confidence.
- Fact checker → Memory store: update · Verified research can be stored for later reuse.
- Fact checker → Streamlit UI: return · Final annotated answer is rendered in the chat UI.
- Fact checker → Terminal app: return · Final annotated answer is printed or returned in terminal mode.
- Fact checker → Saved report: save · Reports can be exported to a local text file.
- Agents API → Researcher: expose · Package exports the researcher role.
- Agents API → Writer: expose · Package exports the writer role.
- Agents API → Fact checker: expose · Package exports the fact-checker role.