Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

feat(ai_agents): add citation-aware document research agent (LlamaParse + Ollama)

cyberholics316818cfabc4
diff --git a/ai_agents/citation_deep_research_agent/.env.example b/ai_agents/citation_deep_research_agent/.env.example
new file mode 100644
index 0000000..914720d
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/.env.example
@@ -0,0 +1,23 @@
+# LlamaCloud API key -- the only cloud dependency. Used by LlamaParse to parse PDFs.
+# Get it at https://cloud.llamaindex.ai (Settings -> API Keys). Free $250 credits on signup.
+LLAMA_CLOUD_API_KEY=llx-your-key-here
+
+# Ollama (local). Defaults assume Ollama is running on this machine.
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=qwen3:4b-instruct
+OLLAMA_EMBED_MODEL=nomic-embed-text
+
+# Retrieval / citation tuning (optional; sensible defaults).
+# Fewer chunks -> shorter prompts -> fewer refine passes -> faster on small models.
+SIMILARITY_TOP_K=4
+CITATION_CHUNK_SIZE=512
+# The citation engine runs several sequential generations per question, and the
+# first call also loads the model into memory. Keep this high to avoid timeouts.
+OLLAMA_REQUEST_TIMEOUT=600
+
+# Context window. Keep modest so Ollama does not try to allocate a huge KV cache
+# (some models default to 100k+ context). 8192 is plenty; drop to 4096 on low RAM.
+OLLAMA_NUM_CTX=8192
+
+# Where parsed docs and the vector index are cached (so a PDF is parsed once).
+CACHE_DIR=.cache
diff --git a/ai_agents/citation_deep_research_agent/.gitignore b/ai_agents/citation_deep_research_agent/.gitignore
new file mode 100644
index 0000000..9ede65f
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/.gitignore
@@ -0,0 +1,10 @@
+.env
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+.cache/
+.DS_Store
diff --git a/ai_agents/citation_deep_research_agent/README.md b/ai_agents/citation_deep_research_agent/README.md
new file mode 100644
index 0000000..68b19ce
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/README.md
@@ -0,0 +1,110 @@
+# Citation-Aware Deep Research Agent
+
+![Demo](assets/demo.gif)
+
+Ask questions about a long PDF and get answers that cite the exact pages they came from. Parsing is done by [LlamaParse by LlamaIndex](https://www.llamaindex.ai/llamaparse); the answers run locally on Ollama.
+
+## Overview
+
+Most "chat with your PDF" demos give you an answer and leave you to trust it. This one grounds every answer: you upload a document, ask a question in plain English, and the agent answers using only the pages it retrieved, with numbered `[1]`, `[2]` citations you can expand to see the exact source text and the page it lives on.
+
+The one thing that leaves your machine is the parse. That is on purpose, and it is the point. Long documents (research papers, annual reports, technical specs) hide their most useful content in tables, figures, and multi-column layouts that generic PDF parsers mangle. LlamaParse reads them properly and keeps the page each piece came from, which is exactly what makes the citations trustworthy. Everything after the parse (embeddings, retrieval, and the answers) runs locally on Ollama, so your questions and the model never leave your machine.
+
+## How It Works
+
+![How It Works](assets/how_it_works.png)
+
+1. **Upload a PDF.** The file is parsed once and cached by its content hash, so re-opening it is instant and costs no credits.
+2. **Parse with LlamaParse.** The document becomes layout-aware markdown, one chunk per page, with the page number attached to every chunk.
+3. **Embed and index, locally.** Ollama produces the embeddings; the vector index is stored on disk.
+4. **Ask a question.** The most relevant pages are retrieved and passed to the local model.
+5. **Answer, grounded.** The model answers using only those pages and cites them inline.
+6. **Verify.** Expand any citation to read the exact source text and see its page.
+
+## Tech Stack
+
+| Layer | Choice |
+|---|---|
+| Document parsing | LlamaParse (LlamaCloud), layout-aware markdown with page metadata |
+| Framework | LlamaIndex (`VectorStoreIndex`, `CitationQueryEngine`) |
+| LLM | Local, via Ollama (default `qwen3:4b-instruct`) |
+| Embeddings | Local, via Ollama (default `nomic-embed-text`) |
+| Vector store | LlamaIndex on-disk index (no external database) |
+| UI | Streamlit |
+| Packaging | Python 3.10+, `uv`, `pyproject.toml` |
+
+## Prerequisites
+
+**1. Ollama, running locally, with a chat model and an embedding model.** Install from https://ollama.com. The default chat model is `qwen3:4b-instruct` (small, fast, clean instruct output); any instruct model works. You always need an embedding model:
+
+```bash
+ollama pull qwen3:4b-instruct # the chat model (or use one you already have; set OLLAMA_MODEL in .env)
+ollama pull nomic-embed-text # the embedding model (required)
+```
+
+The Ollama app keeps the server running at `http://localhost:11434`. For higher answer quality on a stronger machine, pull an 8B model (for example `llama3.1:8b` or `qwen2.5:7b-instruct`) and set `OLLAMA_MODEL` in `.env`.
+
+**2. A LlamaCloud API key.** Create one at https://cloud.llamaindex.ai (Settings -> API Keys). Signup includes $250 in free credits, which is far more than this project needs (a PDF is parsed once and cached).
+
+**3. Python 3.10+ and `uv`.** Install `uv` from https://docs.astral.sh/uv/ if you don't have it.
+
+## Installation
+
+```bash
+uv venv
+source .venv/bin/activate # Windows: .venv\Scripts\activate
+uv pip install -e .
+cp .env.example .env # then open .env and paste your LLAMA_CLOUD_API_KEY
+```
+
+## Running
+
+Make sure Ollama is running, then:
+
+```bash
+streamlit run app.py
+```
+
+Streamlit opens `http://localhost:8501`. Upload a PDF, wait for the overview, and start asking questions. The first parse of a document takes a moment; after that it is cached.
+
+**How to verify it works:**
+- The sidebar shows your chat model, embedding model, and Ollama URL.
+- After upload, a short document overview appears.
+- Ask a question and you get an answer with `[1]`, `[2]` markers; each expander shows the source text and page.
+
+## Project Structure
+
+```
+citation_deep_research_agent/
+├── app.py # Streamlit UI (upload -> overview -> chat with citations)
+├── citation_agent/
+│ ├── config.py # env settings + wiring LlamaIndex to local Ollama
+│ ├── parser.py # LlamaParse: PDF -> page-level Documents (cached by file hash)
+│ ├── indexer.py # build/load the on-disk vector index (Ollama embeddings)
+│ ├── query.py # CitationQueryEngine: grounded answers + citations
+│ └── overview.py # short document overview before Q&A
+├── assets/
+│ └── how_it_works.png
+├── pyproject.toml
+├── .env.example
+├── .gitignore
+└── README.md
+```
+
+## Customising
+
+- **Swap the model.** Set `OLLAMA_MODEL` in `.env` to any model you have pulled.
+- **Tune retrieval.** `SIMILARITY_TOP_K` (how many pages to retrieve) and `CITATION_CHUNK_SIZE` (how granular each citation is) are in `.env`.
+- **Use LlamaExtract for the overview.** `overview.py` uses the local model. For a schema-validated structured overview (title, authors, key findings as JSON), swap in `LlamaExtract` from `llama_cloud_services`.
+- **Deep-link citations into the PDF.** The page number is on every citation. A next step is to render the PDF and jump to that page when a citation is clicked.
+
+## Demo
+
+Upload a research paper or an annual report and ask something whose answer lives in a table (for example "what were the reported results on the benchmark?" or "what were total revenues by segment?"). The answer cites the page and the expander shows the table it came from.
+
+## Resources
+
+- LlamaParse: https://www.llamaindex.ai/llamaparse
+- LlamaParse docs (Python usage): https://developers.llamaindex.ai/llamaparse/
+- CitationQueryEngine: https://developers.llamaindex.ai/python/examples/query_engine/citation_query_engine/
+- Ollama: https://ollama.com
diff --git a/ai_agents/citation_deep_research_agent/app.py b/ai_agents/citation_deep_research_agent/app.py
new file mode 100644
index 0000000..87c2e39
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/app.py
@@ -0,0 +1,225 @@
+"""
+Citation-Aware Deep Research Agent -- Streamlit app.
+
+Upload a long PDF, get a quick overview, then ask questions and receive answers
+that cite the exact pages they came from. Parsing is done by LlamaParse; the
+answers are generated locally by Ollama.
+
+The UI is built around the point of the project: every answer sits next to the
+source text it came from, with the matching words highlighted, the page stamped
+on it, and a relevance bar -- so you can see the answer is grounded, not guessed.
+
+Run with: streamlit run app.py
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+import tempfile
+from pathlib import Path
+
+import streamlit as st
+
+from citation_agent.config import SETTINGS, configure_settings
+from citation_agent.indexer import build_or_load_index
+from citation_agent.overview import generate_overview
+from citation_agent.parser import parse_pdf
+from citation_agent.query import Citation, ask, make_query_engine
+
+st.set_page_config(page_title="Citation-Aware Research Agent", page_icon="📄", layout="wide")
+
+configure_settings()
+
+# Doc-agnostic questions that demo well on almost any long PDF.
+SUGGESTED_QUESTIONS = [
+ "Summarize this document in a few sentences.",
+ "What are the key findings or main claims?",
+ "What are the most important numbers or results?",
+ "What limitations or caveats are mentioned?",
+]
+
+_STOPWORDS = {
+ "what", "which", "does", "this", "that", "with", "from", "have", "were",
+ "are", "the", "and", "for", "how", "many", "much", "into", "over", "about",
+ "document", "mentioned", "reported", "important", "most",
+}
+
+
+# ---------------------------------------------------------------------------
+# Small HTML helpers for the source cards
+# ---------------------------------------------------------------------------
+
+def _highlight(text: str, question: str, limit: int = 700) -> str:
+ """Escape source text and <mark> the meaningful words from the question."""
+ snippet = text.strip()
+ if len(snippet) > limit:
+ snippet = snippet[:limit].rsplit(" ", 1)[0] + " …"
+ escaped = html.escape(snippet)
+
+ terms = {
+ w for w in re.findall(r"[A-Za-z0-9]+", question.lower())
+ if len(w) > 3 and w not in _STOPWORDS
+ }
+ if not terms:
+ return escaped
+ pattern = re.compile(
+ "|".join(re.escape(t) for t in sorted(terms, key=len, reverse=True)),
+ re.IGNORECASE,
+ )
+ return pattern.sub(lambda m: f"<mark>{m.group(0)}</mark>", escaped)
+
+
+def _score_bar(score: float | None) -> str:
+ """A thin relevance bar; retrieval scores are roughly 0..1."""
+ if score is None:
+ return ""
+ pct = int(max(0.0, min(1.0, score)) * 100)
+ return (
+ f'<div style="display:flex;align-items:center;gap:8px;margin:6px 0 2px">'
+ f'<div style="flex:1;background:#E5E7EB;border-radius:4px;height:6px">'
+ f'<div style="width:{pct}%;background:#4F46E5;height:6px;border-radius:4px"></div>'
+ f'</div>'
+ f'<span style="font-size:11px;color:#64748B">relevance {score:.2f}</span>'
+ f'</div>'
+ )
+
+
+def _render_card(c: Citation, question: str) -> None:
+ page = f"p. {c.page}" if c.page is not None else "page n/a"
+ st.markdown(
+ f'<div style="border:1px solid #E5E7EB;border-radius:10px;padding:12px 14px;'
+ f'margin-bottom:12px;background:#FFFFFF">'
+ f'<div style="display:flex;justify-content:space-between;align-items:center">'
+ f'<span style="font-weight:700;color:#4F46E5">[{c.number}] {page}</span>'
+ f'<span style="font-size:12px;color:#64748B">{html.escape(c.file_name)}</span>'
+ f'</div>'
+ f'{_score_bar(c.score)}'
+ f'<div style="font-size:13px;color:#1E293B;line-height:1.55;margin-top:8px;'
+ f'max-height:240px;overflow:auto">{_highlight(c.text, question)}</div>'
+ f'</div>',
+ unsafe_allow_html=True,
+ )
+
+
+def _render_turn(turn: dict, rich: bool) -> None:
+ """Render one Q&A turn. The latest turn gets the side-by-side source view."""
+ with st.chat_message("user"):
+ st.markdown(turn["question"])
+ with st.chat_message("assistant"):
+ if rich and turn["citations"]:
+ answer_col, source_col = st.columns([3, 2], gap="large")
+ with answer_col:
+ st.markdown(turn["answer"])
+ with source_col:
+ st.markdown("**Sources**")
+ for c in turn["citations"]:
+ _render_card(c, turn["question"])
+ else:
+ st.markdown(turn["answer"])
+ for c in turn["citations"]:
+ page = f"p. {c.page}" if c.page is not None else "page n/a"
+ score = f" · relevance {c.score:.2f}" if c.score is not None else ""
+ with st.expander(f"[{c.number}] {c.file_name} · {page}{score}"):
+ st.markdown(c.text)
+
+
+def _prepare_document(file_bytes: bytes, file_name: str):
+ """Parse + index a PDF (both cached), returning a citation-aware query engine."""
+ doc_key = hashlib.md5(file_bytes).hexdigest()
+
+ with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp:
+ tmp.write(file_bytes)
+ tmp_path = Path(tmp.name)
+
+ with st.status("Parsing with LlamaParse and indexing locally...", expanded=False):
+ documents = parse_pdf(tmp_path, file_name=file_name)
+ index = build_or_load_index(documents, doc_key)
+ engine = make_query_engine(index)
+
+ return documents, engine
+
+
+# ---------------------------------------------------------------------------
+# Sidebar
+# ---------------------------------------------------------------------------
+
+with st.sidebar:
+ st.subheader("Setup")
+ st.text(f"Chat model : {SETTINGS.ollama_model}")
+ st.text(f"Embeddings : {SETTINGS.ollama_embed_model}")
+ st.text(f"Ollama : {SETTINGS.ollama_base_url}")
+ if not SETTINGS.llama_cloud_api_key:
+ st.error("LLAMA_CLOUD_API_KEY is not set. Add it to .env.")
+ st.caption(
+ "LlamaParse (cloud) parses the PDF. Everything else -- embeddings, "
+ "retrieval, and the answers -- runs locally on Ollama."
+ )
+ if st.button("New document", width="stretch"):
+ st.session_state.clear()
+ st.rerun()
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+st.title("Citation-Aware Deep Research Agent")
+st.caption("Upload a long PDF, ask questions, and get answers that cite their source pages.")
+
+# The main architectural point, made visible: one cloud call to parse, everything
+# else local.
+st.markdown(
+ '<div style="display:flex;gap:8px;margin:2px 0 14px">'
+ '<span style="background:#DCFCE7;color:#166534;padding:4px 12px;border-radius:999px;'
+ 'font-size:12px;font-weight:600">● Local · Ollama (embeddings + answers)</span>'
+ '<span style="background:#EEF2FF;color:#3730A3;padding:4px 12px;border-radius:999px;'
+ 'font-size:12px;font-weight:600">☁ Cloud · LlamaParse (parse only)</span>'
+ '</div>',
+ unsafe_allow_html=True,
+)
+
+uploaded = st.file_uploader("Upload a PDF (paper, report, spec, contract)", type=["pdf"])
+
+if uploaded is not None and st.session_state.get("file_name") != uploaded.name:
+ documents, engine = _prepare_document(uploaded.getvalue(), uploaded.name)
+ st.session_state.file_name = uploaded.name
+ st.session_state.engine = engine
+ st.session_state.overview = generate_overview(documents)
+ st.session_state.chat = []
+
+if "engine" in st.session_state:
+ with st.expander("Document overview", expanded=True):
+ st.markdown(st.session_state.overview)
+
+ chat = st.session_state.get("chat", [])
+
+ # Empty state: offer clickable starter questions so a cold demo lands instantly.
+ pending: str | None = None
+ if not chat:
+ st.markdown("**Try one of these:**")
+ cols = st.columns(2)
+ for i, q in enumerate(SUGGESTED_QUESTIONS):
+ if cols[i % 2].button(q, key=f"suggest_{i}", width="stretch"):
+ pending = q
+
+ # Render the conversation; only the last turn gets the rich side-by-side view.
+ for idx, turn in enumerate(chat):
+ _render_turn(turn, rich=(idx == len(chat) - 1))
+
+ typed = st.chat_input("Ask a question about the document")
+ question = typed or pending
+
+ if question:
+ with st.spinner("Reading the relevant pages and answering..."):
+ answer = ask(st.session_state.engine, question)
+ st.session_state.chat.append(
+ {"question": question, "answer": answer.text, "citations": answer.citations}
+ )
+ st.rerun()
+else:
+ st.info(
+ "Upload a PDF to begin. The first parse of a document takes a moment; "
+ "after that it is cached."
+ )
diff --git a/ai_agents/citation_deep_research_agent/assets/demo.gif b/ai_agents/citation_deep_research_agent/assets/demo.gif
new file mode 100644
index 0000000..e620f0b
Binary files /dev/null and b/ai_agents/citation_deep_research_agent/assets/demo.gif differ
diff --git a/ai_agents/citation_deep_research_agent/assets/how_it_works.png b/ai_agents/citation_deep_research_agent/assets/how_it_works.png
new file mode 100644
index 0000000..a8c7336
Binary files /dev/null and b/ai_agents/citation_deep_research_agent/assets/how_it_works.png differ
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/__init__.py b/ai_agents/citation_deep_research_agent/citation_agent/__init__.py
new file mode 100644
index 0000000..61af20a
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/__init__.py
@@ -0,0 +1,3 @@
+"""Citation-aware document Q&A over long PDFs."""
+
+__all__ = ["config", "parser", "indexer", "query", "overview"]
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/config.py b/ai_agents/citation_deep_research_agent/citation_agent/config.py
new file mode 100644
index 0000000..ee1fc2a
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/config.py
@@ -0,0 +1,90 @@
+"""
+Configuration and one-time wiring of LlamaIndex to local Ollama.
+
+Everything is read from environment variables (see .env.example), so nothing
+is hardcoded. `configure_settings()` points LlamaIndex at your local Ollama for
+both the chat model and the embedding model; call it once at startup.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+ """All runtime settings, resolved from the environment with sane defaults."""
+
+ # LlamaParse (cloud) -- the only thing that leaves your machine.
+ llama_cloud_api_key: str = os.getenv("LLAMA_CLOUD_API_KEY", "")
+
+ # Ollama (local) -- the chat model and the embedding model both run here.
+ ollama_base_url: str = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
+ ollama_model: str = os.getenv("OLLAMA_MODEL", "llama3.1:8b")
+ ollama_embed_model: str = os.getenv("OLLAMA_EMBED_MODEL", "nomic-embed-text")
+
+ # Retrieval / citation granularity. Fewer chunks = shorter prompts = fewer
+ # refine passes, which keeps a small local model responsive.
+ similarity_top_k: int = int(os.getenv("SIMILARITY_TOP_K", "4"))
+ citation_chunk_size: int = int(os.getenv("CITATION_CHUNK_SIZE", "512"))
+
+ # Local model can be slow, and the citation engine may run several sequential
+ # generations per question (compact-and-refine). The first call also loads the
+ # model into memory. Give it plenty of room to avoid httpx ReadTimeout.
+ request_timeout_s: float = float(os.getenv("OLLAMA_REQUEST_TIMEOUT", "600"))
+
+ # Context window. Keep this modest: some models (e.g. qwen3) default to a
+ # huge context, and Ollama then tries to allocate a KV cache far bigger than
+ # your RAM. 8192 is plenty for page-level Q&A. Lower to 4096 if still OOM.
+ ollama_num_ctx: int = int(os.getenv("OLLAMA_NUM_CTX", "8192"))
+
+ # On-disk caches so we never re-parse or re-index the same file (saves credits).
+ cache_dir: Path = Path(os.getenv("CACHE_DIR", ".cache"))
+
+ @property
+ def parse_cache_dir(self) -> Path:
+ return self.cache_dir / "parse"
+
+ @property
+ def index_cache_dir(self) -> Path:
+ return self.cache_dir / "index"
+
+
+SETTINGS = Settings()
+
+
+def configure_settings() -> None:
+ """Wire LlamaIndex's global Settings to local Ollama. Call once at startup."""
+ # Imported lazily so importing this module stays cheap (and testable).
+ from llama_index.core import Settings as LlamaSettings
+ from llama_index.embeddings.ollama import OllamaEmbedding
+ from llama_index.llms.ollama import Ollama
+
+ LlamaSettings.llm = Ollama(
+ model=SETTINGS.ollama_model,
+ base_url=SETTINGS.ollama_base_url,
+ request_timeout=SETTINGS.request_timeout_s,
+ context_window=SETTINGS.ollama_num_ctx,
+ # Force Ollama to load with this context size (caps the KV-cache memory).
+ additional_kwargs={"num_ctx": SETTINGS.ollama_num_ctx},
+ )
+ LlamaSettings.embed_model = OllamaEmbedding(
+ model_name=SETTINGS.ollama_embed_model,
+ base_url=SETTINGS.ollama_base_url,
+ )
+
+
+def require_api_key() -> str:
+ """Return the LlamaCloud API key or raise a clear error if it is missing."""
+ if not SETTINGS.llama_cloud_api_key:
+ raise RuntimeError(
+ "LLAMA_CLOUD_API_KEY is not set. Copy .env.example to .env and add your "
+ "key from https://cloud.llamaindex.ai (Settings -> API Keys)."
+ )
+ return SETTINGS.llama_cloud_api_key
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/indexer.py b/ai_agents/citation_deep_research_agent/citation_agent/indexer.py
new file mode 100644
index 0000000..7ae5ba6
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/indexer.py
@@ -0,0 +1,41 @@
+"""
+Build (or load) a vector index over the parsed pages.
+
+Embeddings run locally through Ollama. The index is persisted to disk keyed by
+the same content hash as the parse cache, so re-opening the same PDF is instant
+and costs nothing. Page metadata rides along on every node, so it survives all
+the way to the citations.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from llama_index.core import (
+ StorageContext,
+ VectorStoreIndex,
+ load_index_from_storage,
+)
+from llama_index.core.schema import Document
+
+from citation_agent.config import SETTINGS
+
+
+def build_or_load_index(documents: list[Document], doc_key: str) -> VectorStoreIndex:
+ """
+ Return a VectorStoreIndex for these documents. If one was already built for
+ `doc_key`, load it from disk; otherwise build it and persist it.
+
+ `configure_settings()` must have been called first so the embedding model is
+ the local Ollama one.
+ """
+ persist_dir = SETTINGS.index_cache_dir / doc_key
+
+ if persist_dir.exists():
+ storage = StorageContext.from_defaults(persist_dir=str(persist_dir))
+ return load_index_from_storage(storage)
+
+ index = VectorStoreIndex.from_documents(documents)
+ persist_dir.mkdir(parents=True, exist_ok=True)
+ index.storage_context.persist(persist_dir=str(persist_dir))
+ return index
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/overview.py b/ai_agents/citation_deep_research_agent/citation_agent/overview.py
new file mode 100644
index 0000000..a7a9948
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/overview.py
@@ -0,0 +1,49 @@
+"""
+A quick structured overview of the document, shown before the Q&A.
+
+This uses the local Ollama model over the first few parsed pages to produce a
+short title / what-it-is / key-points summary, so the user gets their bearings
+before asking questions. It is intentionally simple and best-effort.
+
+Note: LlamaExtract (from llama_cloud_services) is the production-grade way to do
+this -- give it a schema and it returns validated JSON. We keep the local-LLM
+version here so the app has zero extra cloud calls by default; swapping in
+LlamaExtract is a small change and is noted in the README.
+"""
+
+from __future__ import annotations
+
+from llama_index.core.schema import Document
+
+_OVERVIEW_PROMPT = """You are summarizing a document for a reader who has not opened it yet.
+Using only the text below, produce a short overview in this exact format:
+
+Title: <the document's title, or a best guess>
+What it is: <one sentence on what kind of document this is and what it covers>
+Key points:
+- <point 1>
+- <point 2>
+- <point 3>
+
+Do not invent facts. If something is unclear, say so briefly.
+
+DOCUMENT (first pages):
+---
+{context}
+---
+"""
+
+
+def generate_overview(documents: list[Document], max_chars: int = 6000) -> str:
+ """Return a short plain-text overview of the document."""
+ from llama_index.core import Settings
+
+ context = ""
+ for doc in documents:
+ context += doc.text.strip() + "\n\n"
+ if len(context) >= max_chars:
+ break
+ context = context[:max_chars]
+
+ prompt = _OVERVIEW_PROMPT.format(context=context)
+ return str(Settings.llm.complete(prompt)).strip()
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/parser.py b/ai_agents/citation_deep_research_agent/citation_agent/parser.py
new file mode 100644
index 0000000..e3ef5f2
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/parser.py
@@ -0,0 +1,86 @@
+"""
+Parse a PDF with LlamaParse into page-level LlamaIndex Documents.
+
+LlamaParse is the one cloud call in this project. It is also the whole point:
+it reads tables, figures, multi-column layouts and scans that generic parsers
+mangle, and it keeps the page each chunk came from -- which is what makes the
+citations trustworthy.
+
+We cache the parsed result on disk keyed by the file's content hash, so the same
+PDF is never parsed twice (that keeps LlamaParse credit use flat during
+development, where you re-run constantly).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from llama_index.core.schema import Document
+
+from citation_agent.config import SETTINGS, require_api_key
+
+# Metadata keys LlamaParse may use for the page number, in order of preference.
+_PAGE_KEYS = ("page_label", "page", "page_number", "page_index")
+
+
+def _file_hash(path: str | Path) -> str:
+ """Content hash of the file, used as the cache key."""
+ h = hashlib.md5()
+ with open(path, "rb") as f:
+ for block in iter(lambda: f.read(1 << 20), b""):
+ h.update(block)
+ return h.hexdigest()
+
+
+def _normalize_page(metadata: dict, fallback_index: int) -> int:
+ """Pull a page number out of whatever key LlamaParse used; fall back to order."""
+ for key in _PAGE_KEYS:
+ if key in metadata and metadata[key] is not None:
+ try:
+ return int(metadata[key])
+ except (TypeError, ValueError):
+ pass
+ return fallback_index + 1 # 1-based
+
+
+def parse_pdf(path: str | Path, file_name: str | None = None) -> list[Document]:
+ """
+ Parse `path` into a list of Documents, one per page, each carrying its
+ `page` and `file_name` in metadata. Cached by file content hash.
+ """
+ path = Path(path)
+ name = file_name or path.name
+ cache_file = SETTINGS.parse_cache_dir / f"{_file_hash(path)}.json"
+
+ if cache_file.exists():
+ raw = json.loads(cache_file.read_text(encoding="utf-8"))
+ return [Document(text=d["text"], metadata=d["metadata"]) for d in raw]
+
+ # Import here so the module imports without the SDK installed (e.g. for tests).
+ from llama_cloud_services import LlamaParse
+
+ parser = LlamaParse(
+ api_key=require_api_key(),
+ result_type="markdown", # layout-aware markdown keeps tables readable
+ verbose=True,
+ )
+ parsed = parser.load_data(str(path))
+
+ documents: list[Document] = []
+ for i, doc in enumerate(parsed):
+ meta = dict(doc.metadata or {})
+ meta["page"] = _normalize_page(meta, i)
+ meta["file_name"] = name
+ documents.append(Document(text=doc.text, metadata=meta))
+
+ cache_file.parent.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(
+ json.dumps(
+ [{"text": d.text, "metadata": d.metadata} for d in documents],
+ ensure_ascii=False,
+ ),
+ encoding="utf-8",
+ )
+ return documents
diff --git a/ai_agents/citation_deep_research_agent/citation_agent/query.py b/ai_agents/citation_deep_research_agent/citation_agent/query.py
new file mode 100644
index 0000000..6bd091a
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/citation_agent/query.py
@@ -0,0 +1,78 @@
+"""
+Answer questions over the index with inline citations.
+
+We use LlamaIndex's CitationQueryEngine: it splits retrieved context into
+numbered sources, tells the model to cite them inline as [1], [2], and returns
+the source nodes so we can show the exact text (and page) behind each number.
+The model only sees the retrieved pages, so the answer is grounded in the
+document, not the model's memory.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from llama_index.core import VectorStoreIndex
+from llama_index.core.query_engine import CitationQueryEngine
+
+from citation_agent.config import SETTINGS
+
+_PAGE_KEYS = ("page", "page_label", "page_number")
+
+
+@dataclass
+class Citation:
+ """One numbered source behind an answer."""
+
+ number: int
+ page: int | None
+ file_name: str
+ text: str
+ score: float | None
+
+
+@dataclass
+class Answer:
+ """An answer plus the sources it cited."""
+
+ text: str
+ citations: list[Citation]
+
+
+def make_query_engine(index: VectorStoreIndex) -> CitationQueryEngine:
+ """Build a citation-aware query engine over the index."""
+ return CitationQueryEngine.from_args(
+ index,
+ similarity_top_k=SETTINGS.similarity_top_k,
+ citation_chunk_size=SETTINGS.citation_chunk_size,
+ )
+
+
+def _page_of(metadata: dict) -> int | None:
+ for key in _PAGE_KEYS:
+ if metadata.get(key) is not None:
+ try:
+ return int(metadata[key])
+ except (TypeError, ValueError):
+ return None
+ return None
+
+
+def ask(engine: CitationQueryEngine, question: str) -> Answer:
+ """Run one question and return the grounded answer with its citations."""
+ response = engine.query(question)
+
+ citations: list[Citation] = []
+ for i, source in enumerate(response.source_nodes, start=1):
+ meta = source.node.metadata or {}
+ citations.append(
+ Citation(
+ number=i,
+ page=_page_of(meta),
+ file_name=str(meta.get("file_name", "document")),
+ text=source.node.get_text(),
+ score=getattr(source, "score", None),
+ )
+ )
+
+ return Answer(text=str(response), citations=citations)
diff --git a/ai_agents/citation_deep_research_agent/pyproject.toml b/ai_agents/citation_deep_research_agent/pyproject.toml
new file mode 100644
index 0000000..ab5c843
--- /dev/null
+++ b/ai_agents/citation_deep_research_agent/pyproject.toml
@@ -0,0 +1,20 @@
+[project]
+name = "citation-deep-research-agent"
+version = "1.0.0"
+description = "Citation-aware document Q&A over long PDFs: LlamaParse for parsing, local Ollama for answers, every answer cited back to the source."
+requires-python = ">=3.10"
+dependencies = [
+ "llama-index>=0.12.0",
+ "llama-index-llms-ollama>=0.4.0",
+ "llama-index-embeddings-ollama>=0.4.0",
+ "llama-cloud-services>=0.6.0",
+ "streamlit>=1.36.0",
+ "python-dotenv>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["citation_agent"]