# cvxtz/document_ai_agents architecture

> Architecture diagram of the GitHub repository cvxtz/document_ai_agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cvxtz/document_ai_agents
- Repository: https://github.com/cvxtz/document_ai_agents

## Overview

The repository provides document parsing and image-based question-answering, a parse-to-index-to-retrieve RAG workflow, a separate answer-verification workflow, and an optional tool-calling research agent. The README documents the parsing and RAG stages; source confirms their state-graph operations and the additional agents. The graph follows documented pipeline handoff and sampled calls; no UI workflow is inferred from the dependency list.

Main entry points: [`document_ai_agents/document_parsing_agent.py`](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_parsing_agent.py) (Render pages), [`document_ai_agents/document_rag_agent.py`](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py) (Retrieve and answer), [`document_ai_agents/tools.py`](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/tools.py) (Search and fetch tools), [`document_ai_agents/document_multi_tool_agent.py`](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_multi_tool_agent.py) (Tool-calling agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parse["Document Parsing"]
  node_parse_images["Render pages"]
  node_pdf_utils["PDF utilities<br/>[document_utils.py]"]
  node_image_utils["Image conversion<br/>[image_utils.py]"]
  node_layout["Find layout items"]
  node_chunks["Summarized chunks"]
end

subgraph group_rag["Retrieval QA"]
  node_rag_index["Index documents"]
  node_vector_store[("Chroma vector store")]
  node_rag_answer["Retrieve and answer"]
  node_rag_result["Contextual answer"]
end

subgraph group_verify["Document Verification"]
  node_qa_input["Page images or text"]
  node_qa_answer["Answer with context"]
  node_qa_reformulate["Reformulate assertion"]
  node_qa_verify["Verify entailment"]
  node_qa_result["Answer and verification"]
end

subgraph group_tools["Research Tools"]
  node_llm_agent["Tool-calling agent"]
  node_tool_dispatch["Dispatch tool calls"]
  node_research_tools["Search and fetch tools<br/>[tools.py]"]
end

node_document_user(("Document provider"))
node_questioner(("Questioner"))
node_pdf["PDF document"]
node_gemini_parse{{"Gemini"}}
node_gemini_rag{{"Gemini"}}
node_gemini_qa{{"Gemini"}}
node_research_user(("Research questioner"))
node_gemini_tools{{"Gemini"}}
node_wikipedia{{"Wikipedia"}}
node_duckduckgo{{"DuckDuckGo"}}
node_web_pages{{"Web pages"}}

node_document_user -->|"provides"| node_pdf
node_pdf -->|"parse"| node_parse_images
node_parse_images -->|"render pages"| node_pdf_utils
node_parse_images -->|"encode pages"| node_image_utils
node_parse_images -->|"dispatch pages"| node_layout
node_layout -->|"analyze pages"| node_gemini_parse
node_layout -->|"emit summaries"| node_chunks
node_chunks -->|"index input"| node_rag_index
node_questioner -->|"asks question"| node_rag_answer
node_rag_index -->|"store embeddings"| node_vector_store
node_rag_answer -->|"retrieve chunks"| node_vector_store
node_rag_answer -->|"generate answer"| node_gemini_rag
node_rag_answer -->|"returns answer"| node_rag_result
node_questioner -->|"asks about pages"| node_qa_input
node_qa_input -->|"provide context"| node_qa_answer
node_qa_answer -->|"generate answer"| node_gemini_qa
node_qa_answer -->|"pass answer"| node_qa_reformulate
node_qa_reformulate -->|"reformulate"| node_gemini_qa
node_qa_reformulate -->|"pass assertion"| node_qa_verify
node_qa_verify -->|"check entailment"| node_gemini_qa
node_qa_verify -->|"returns result"| node_qa_result
node_research_user -->|"asks question"| node_llm_agent
node_llm_agent -->|"request response"| node_gemini_tools
node_llm_agent -->|"dispatch calls"| node_tool_dispatch
node_tool_dispatch -->|"invoke tools"| node_research_tools
node_research_tools -.->|"search pages"| node_wikipedia
node_research_tools -.->|"search web"| node_duckduckgo
node_research_tools -.->|"fetch content"| node_web_pages
node_tool_dispatch -->|"return tool results"| node_llm_agent

click node_parse_images "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_parsing_agent.py"
click node_pdf_utils "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_utils.py"
click node_image_utils "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/image_utils.py"
click node_layout "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_parsing_agent.py"
click node_rag_index "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py"
click node_vector_store "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py"
click node_rag_answer "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py"
click node_qa_answer "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py"
click node_qa_reformulate "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py"
click node_qa_verify "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py"
click node_llm_agent "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_multi_tool_agent.py"
click node_tool_dispatch "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_multi_tool_agent.py"
click node_research_tools "https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/tools.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_parse_images,node_pdf_utils,node_image_utils,node_layout,node_chunks toneBlue
class node_rag_index,node_vector_store,node_rag_answer,node_rag_result toneAmber
class node_qa_input,node_qa_answer,node_qa_reformulate,node_qa_verify,node_qa_result toneMint
class node_llm_agent,node_tool_dispatch,node_research_tools toneRose
class node_document_user,node_questioner,node_pdf,node_gemini_parse,node_gemini_rag,node_gemini_qa,node_research_user,node_gemini_tools,node_wikipedia,node_duckduckgo,node_web_pages toneIndigo
```

## Components

### Document Parsing

- [Render pages](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_parsing_agent.py): `document_ai_agents/document_parsing_agent.py`
- [PDF utilities](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_utils.py): `document_ai_agents/document_utils.py`
- [Image conversion](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/image_utils.py): `document_ai_agents/image_utils.py`
- [Find layout items](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_parsing_agent.py): `document_ai_agents/document_parsing_agent.py`
- **Summarized chunks**

### Retrieval QA

- [Index documents](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py): `document_ai_agents/document_rag_agent.py`
- [Chroma vector store](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py): `document_ai_agents/document_rag_agent.py`
- [Retrieve and answer](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_rag_agent.py): `document_ai_agents/document_rag_agent.py`
- **Contextual answer**

### Document Verification

- **Page images or text**
- [Answer with context](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py): `document_ai_agents/document_qa_agent.py`
- [Reformulate assertion](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py): `document_ai_agents/document_qa_agent.py`
- [Verify entailment](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_qa_agent.py): `document_ai_agents/document_qa_agent.py`
- **Answer and verification**

### Research Tools

- [Tool-calling agent](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_multi_tool_agent.py): `document_ai_agents/document_multi_tool_agent.py`
- [Dispatch tool calls](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/document_multi_tool_agent.py): `document_ai_agents/document_multi_tool_agent.py`
- [Search and fetch tools](https://github.com/cvxtz/document_ai_agents/blob/master/document_ai_agents/tools.py): `document_ai_agents/tools.py`

### Other components

- **Document provider**
- **Questioner**
- **PDF document**
- **Gemini**
- **Gemini**
- **Gemini**
- **Research questioner**
- **Gemini**
- **Wikipedia**
- **DuckDuckGo**
- **Web pages**

## Connections

- Document provider → PDF document: provides
- PDF document → Render pages: parse
- Render pages → PDF utilities: render pages
- Render pages → Image conversion: encode pages
- Render pages → Find layout items: dispatch pages
- Find layout items → Gemini: analyze pages
- Find layout items → Summarized chunks: emit summaries
- Summarized chunks → Index documents: index input
- Questioner → Retrieve and answer: asks question
- Index documents → Chroma vector store: store embeddings
- Retrieve and answer → Chroma vector store: retrieve chunks
- Retrieve and answer → Gemini: generate answer
- Retrieve and answer → Contextual answer: returns answer
- Questioner → Page images or text: asks about pages
- Page images or text → Answer with context: provide context
- Answer with context → Gemini: generate answer
- Answer with context → Reformulate assertion: pass answer
- Reformulate assertion → Gemini: reformulate
- Reformulate assertion → Verify entailment: pass assertion
- Verify entailment → Gemini: check entailment
- Verify entailment → Answer and verification: returns result
- Research questioner → Tool-calling agent: asks question
- Tool-calling agent → Gemini: request response
- Tool-calling agent → Dispatch tool calls: dispatch calls
- Dispatch tool calls → Search and fetch tools: invoke tools
- Search and fetch tools → Wikipedia: search pages
- Search and fetch tools → DuckDuckGo: search web
- Search and fetch tools → Web pages: fetch content
- Dispatch tool calls → Tool-calling agent: return tool results