agentic rag for dummies

Technical Briefing – agentic‑rag‑for‑dummies Clone: git clone https://github.com/moses-y/agentic-rag-for-dummies

1. Project Snapshot

Entry point: project/app.py – starts a Flask server exposing /chat and /docs.
Core modules
project/core/rag_system.py: orchestrates retrieval, grounding, and answer generation.
project/rag_agent/graph.py: LangGraph definition (nodes, edges, state).
project/core/document_manager.py: loads PDFs via project/document_chunker.py and stores chunks in Qdrant.
UI: project/ui/gradio_app.py provides a web demo that calls the Flask API.
Data layer: project/db/vector_db_manager.py and parent_store_manager.py wrap Qdrant client.
Observability: project/core/observability.py logs LLM calls and tool usage to Langfuse.

Dependencies are listed in requirements.txt (no lockfile). Docker support via project/Dockerfile.

2. How the Flow Works

User Query → Flask route (/chat) in app.py.
app.py passes the query to RagSystem.run(query, user_id).
RagSystem builds a GraphState and invokes Graph().flow(state).
LangGraph executes: - Clarify node (rag_agent/nodes.py) rewrites ambiguous queries. - Retrieve node calls vector_db_manager.search() for top‑k chunks. - Compress node keeps working memory small. - Answer node calls the configured LLM via LangChain.
The generated answer, along with metadata, is returned to Flask and forwarded to the UI or API consumer.

The most impactful functions are rag_system.run, graph.Graph.flow, and vector_db_manager.search, each with a single responsibility and clear side‑effects (network calls to Qdrant or LLM provider).

3. Setup & Configuration

Environment ``bash cp project/.env.example .env # Edit .env: set OPENAI_API_KEY, QDRANT_URL, LANGFUSE_PUBLIC_KEY, etc. ``
Local run ``bash pip install -r requirements.txt python project/app.py ``
Docker ``bash docker build -t agentic-rag . docker run -p 8000:8000 --env-file .env agentic-rag ``

The README provides Colab and Gradio launch instructions; no CLI script exists.

4. Real‑World Use Case

A knowledge‑base chatbot for an internal HR portal. The PDF employee handbook is chunked, indexed in Qdrant, and the chat UI (via gradio_app.py) lets staff ask policy questions. The workflow automatically re‑queries if an answer is incomplete, thanks to the self‑correction loop in rag_agent/graph.py.

5. Code Health & Issues

Missing Tests – no tests/ directory; most functions are exercised only in notebooks.
No CI/CD – no .github/ workflow, GitHub Actions, or GitLab CI config.
Reproducibility – requirements.txt lacks a lockfile; environment may drift.
Documentation – README is comprehensive; each module has minimal inline comments but no docstrings.

All findings come from static analysis of the file list and content; no additional issues were detected.

6. Bottom Line

The repo offers a clean, modular Agentic RAG stack with a clear separation between retrieval, reasoning, and UI. Its use of LangGraph and Qdrant enables rapid experimentation, and the Dockerfile simplifies deployment. However, the absence of automated tests and CI limits confidence for production use. The architecture is suitable for teams that can add their own testing and CI pipelines, especially those familiar with LangChain and vector databases.

What the analyser found

Deployment readiness

4/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

40 files

Python24
Jupyter Notebook4
Markdown2
JSON1

FlaskDocker

Module dependencies

The 10 most depended-upon modules of 24, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_roject_rag_agent_graph_state["graph_state"] n1_project_rag_agent_nodes["nodes"] n2_project_rag_agent_edges["edges"] n3_project_rag_agent_prompts["prompts"] n4_project_rag_agent_schemas["schemas"] n5_project_rag_agent_graph["graph"] n6_project_app["app"] n7_project_config["config"] n8_project_core___init__["__init__"] n9_project_core_chat_interface["chat_interface"] n2_project_rag_agent_edges --> n0_roject_rag_agent_graph_state n5_project_rag_agent_graph --> n0_roject_rag_agent_graph_state n5_project_rag_agent_graph --> n1_project_rag_agent_nodes n5_project_rag_agent_graph --> n2_project_rag_agent_edges n1_project_rag_agent_nodes --> n0_roject_rag_agent_graph_state n1_project_rag_agent_nodes --> n4_project_rag_agent_schemas n1_project_rag_agent_nodes --> n3_project_rag_agent_prompts

Dependencies

16 declared dependencies, none a major version behind. Resolved 16 of 16 against the registry.

Findings

MediumNo test files detected - untested code paths repository-wide
MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
LowDependencies declared without a lockfile - non-reproducible builds requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium4

Upgrade the pinned dependency carrying a published advisoryhigh2 occurrences

ragas@0.4.3 CVE-2026-6587 (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Add a test suite; this repository has nonehigh24 occurrences

24 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Add a workflow that builds and tests this repositoryhigh

24 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh

project/Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

project/Dockerfile

python:3.13

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Split the oversized notebook cell into stepsmedium

notebooks/agentic_rag.ipynb

largest cell 14694 characters of 41173 (3 notebooks sampled)

A failure anywhere in a 22,000-character cell means rerunning the whole pipeline from load to model, so nothing can be debugged in isolation.

Fix: Break at the load, clean, feature, model and evaluate boundaries.

Move large binaries to Git LFS or out of the repositorymedium

assets/demo.gif

1 blobs over 5MB: demo.gif 5.1MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.