A production-oriented AI research assistant that discovers academic papers, validates and reads open-access PDFs, builds a session-isolated RAG corpus, and generates citation-checked research PDFs.
The project demonstrates more than an LLM chat interface: it includes durable workflow state, caching, reliability controls, structured observability, offline evaluation gates, database migrations, tests, and a containerized local deployment.
- Searches Semantic Scholar and arXiv for relevant papers.
- Validates candidate links before treating them as PDFs.
- Extracts, chunks, and embeds selected papers.
- Retrieves relevant passages from a session-isolated FAISS index.
- Uses a LangGraph tool-calling workflow to analyze or write from that context.
- Validates LaTeX citations and compiles the final document with Tectonic.
flowchart LR
UI[Streamlit / FastAPI] --> AGENT[LangGraph agent]
AGENT --> SEARCH[Semantic Scholar / arXiv]
SEARCH <--> REDIS[(Redis search cache)]
AGENT --> PDF[PDF validation and extraction]
PDF --> CHUNKS[Chunking]
CHUNKS --> EMB[Gemini embeddings]
EMB --> FAISS[(Session-isolated FAISS)]
CHUNKS --> PG[(PostgreSQL)]
AGENT <--> FAISS
AGENT <--> CHECKPOINTS[PostgreSQL checkpoints]
UI <--> PG
AGENT --> LATEX[Citation validator and Tectonic]
LATEX --> OUTPUT[Generated PDF]
| Component | Responsibility |
|---|---|
| PostgreSQL | Durable sessions, messages, paper metadata, extracted chunks, feedback records, and LangGraph checkpoints |
| FAISS | Fast semantic similarity search over the current session's embedded corpus |
| Redis | Short-lived cache for public paper-search results |
| Streamlit memory | User-supplied Gemini key and active UI state |
PostgreSQL does not replace FAISS. PostgreSQL is the durable system of record; FAISS remains the retrieval index. If an in-memory FAISS index is lost, the application can rebuild it from the session's PostgreSQL chunks.
- Session isolation: PDF state, embedding clients, and FAISS indexes are isolated by random conversation UUID.
- Durable state: PostgreSQL persists chat history, source chunks, metadata, feedback-ready records, and LangGraph execution checkpoints.
- Caching: Redis caches repeat paper searches with configurable TTLs and degrades safely to a cache miss when unavailable.
- Reliability: External requests use bounded timeouts, retryable-status
rules, exponential backoff, jitter,
Retry-After, and safe user-facing errors. - Input boundaries: Limits cover message length, query length, result count,
PDF size/pages/text, retrieval
k, and LaTeX compilation time. - Observability: Structured JSON logs include request/session correlation, latency, status, retry, and tool metadata without prompt or API-key content.
- Optional tracing: LangSmith tracing is configurable and hides inputs and outputs by default.
- Citation safety: Generated LaTeX must have matching
\cite{}and\bibitem{}keys, complete reference metadata, URLs, and no unresolved compiler citation warnings. - Reproducible delivery: Locked dependencies, non-root container execution, service health checks, versioned Alembic migrations, and GitHub Actions gates.
- Every Streamlit user must provide their own Gemini API key.
- The Streamlit application never falls back to the deployer's
GOOGLE_API_KEY. - Gemini keys are not stored in PostgreSQL, graph state, logs, traces, or generated reports.
- PostgreSQL sessions use random UUIDs, never API keys, as identifiers.
- The database is authentication-ready:
users.idis an internal UUID andsessions.user_idis nullable until Google login/logout is implemented. - PostgreSQL and Redis are private inside the Docker Compose network.
Google authentication is intentionally future work; the current version does not claim multi-user authorization based on login identity.
The repository contains a deterministic offline challenge set with relevant
documents, paraphrases, lexical distractors, ambiguous tool routing, unsupported
claims, missing citations, and representative tool failures. Known failures
remain in the dataset so the report does not present artificial 1.0 scores.
Current checked-in baseline:
| Metric | Score |
|---|---|
| Retrieval hit rate | 0.8333 |
| Retrieval mean reciprocal rank | 0.8333 |
| Retrieval concept coverage | 0.8611 |
| Tool-selection accuracy | 0.9000 |
| Groundedness | 0.8333 |
| Citation completeness | 0.8333 |
| Tool success rate | 0.9000 |
The suite contains 12 retrieval cases, 10 tool-selection cases, 6 generation cases, and 10 tool events. It enforces both absolute minimums and maximum allowed drops from the reviewed baseline.
This is a repeatable regression gate, not a replacement for live-model evaluation or production monitoring.
| Area | Technology |
|---|---|
| Agent workflow | LangGraph and LangChain |
| Model and embeddings | Google Gemini |
| Vector retrieval | FAISS |
| Durable data | PostgreSQL and SQLAlchemy |
| Schema migrations | Alembic |
| Workflow checkpoints | LangGraph PostgreSQL checkpointer |
| Cache | Redis |
| Interactive UI | Streamlit |
| API | FastAPI |
| Academic sources | Semantic Scholar and arXiv |
| PDF processing | PyPDF2 and Tectonic |
| Observability | Structured JSON logging and optional LangSmith tracing |
| Packaging | uv with a committed lockfile |
| Delivery | Docker, Docker Compose, and GitHub Actions |
| Tool interoperability | Model Context Protocol (MCP) |
Ai_Researcher/
├── src/
│ ├── app.py # Streamlit interface and BYOK flow
│ ├── api.py # FastAPI interface
│ ├── graph.py # LangGraph agent workflow
│ ├── config.py # Validated environment configuration
│ ├── reliability.py # Validation, timeout, and retry policies
│ ├── observability.py # Structured logs and tracing
│ ├── cache.py # Redis cache boundary
│ ├── checkpointing.py # Memory/PostgreSQL checkpoint selection
│ ├── session_store.py # Session-isolated runtime resources
│ ├── evaluation_suite.py # Deterministic evaluation runner
│ ├── migrate.py # App and checkpoint migrations
│ ├── persistence/
│ │ ├── schema.py # SQLAlchemy application schema
│ │ └── repository.py # PostgreSQL persistence boundary
│ └── tools/
│ ├── semantic_scholar_tool.py
│ ├── arxiv_tool.py
│ ├── pdf_sources.py
│ ├── read_pdf.py
│ ├── vector_store.py
│ └── write_pdf.py
├── migrations/ # Versioned Alembic migrations
├── evals/ # Challenge set and reviewed baseline
├── scripts/run_evaluation.py # Evaluation CLI
├── tests/ # Unit, contract, and integration tests
├── .github/workflows/ci.yml # Tests, eval gate, and image build
├── Dockerfile # Non-root production image
├── compose.yaml # App, PostgreSQL, migration, and Redis stack
├── mcp_server.py # Standalone academic-search MCP server
├── .env.example
├── pyproject.toml
└── uv.lock
- Docker Desktop or Docker Engine with Compose
- A Gemini API key from Google AI Studio
Copy the example configuration and change the local PostgreSQL password:
cp .env.example .envOn PowerShell:
Copy-Item .env.example .envThen start the complete free local stack:
docker-compose up --buildOpen http://localhost:8501 and enter your Gemini API key in the password field. The migration container upgrades both the application schema and LangGraph checkpoint tables before Streamlit starts.
Stop the containers with:
docker-compose downNamed volumes preserve PostgreSQL data, generated papers, and the Tectonic
package cache. Use docker-compose down -v only when you intentionally want to
delete that local data.
Python 3.11 or newer and uv are required.
uv sync --locked
uv run python -m streamlit run src/app.pyWith the defaults in .env.example, PostgreSQL and Redis are disabled for this
host-run mode. The app uses in-memory sessions/checkpoints, and users still
provide their own Gemini key in the UI.
To enable a host-accessible PostgreSQL instance, configure:
DATABASE_ENABLED=true
DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:5432/DATABASEApply migrations before starting the application:
uv run python -m src.migrateThe FastAPI interface is server-controlled and requires GOOGLE_API_KEY in the
server environment. It does not accept API keys in request bodies.
uv run uvicorn src.api:app --reloadInteractive documentation is available at http://127.0.0.1:8000/docs.
Run the same quality checks used in CI:
uv sync --locked
uv run python -m unittest discover -s tests -v
uv run python scripts/run_evaluation.pyThe evaluation command writes local reports to output/evaluations/. Generated
reports and PDFs are intentionally ignored by Git. See
evals/README.md for baseline-management rules.
GitHub Actions additionally starts PostgreSQL, applies migrations, runs the database integration test, builds the production image, and verifies its Python and Tectonic runtimes.
The academic search tools are also exposed through a standalone Model Context Protocol server:
uv run python mcp_server.pyExample MCP client configuration:
{
"mcpServers": {
"academic-research": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/Ai_Researcher",
"python",
"mcp_server.py"
]
}
}
}- Google OIDC login/logout and user-owned conversation history
- Production deployment with managed secrets and TLS
- Live-model evaluation from reviewed production traces
- Database backups, retention policy, and restore drills