alaap-nair/adobe-deep-research

Purpose and Top-Level Shape

This repository compares two Biology Expert KG-RAG implementations for answering OpenStax Biology questions with lightweight LLMs rather than web search. Both implement ingestion, relation extraction, knowledge-graph construction, hybrid retrieval, grounded synthesis, and RAGAS-based evaluation, but are independently runnable subprojects:

• Unified Neo4j design: team_a/src/run_all.py, team_a/ask.py

• Dual-store Neo4j + Qdrant design: team_b/src/run_all.py, team_b/ask.py

• Separate personalized Graphiti demonstration: demo/backend/server.py, demo/web/app/page.tsx

Team A: Unified Neo4j Pipeline

Team A keeps graph entities/relations, source chunks, and vector embeddings in Neo4j, minimizing storage-service boundaries. The principal batch entry point orchestrates parsing, chunking, extraction, embeddings, and graph persistence; the CLI query surface answers a user question against that unified store.

• Pipeline orchestration: team_a/src/run_all.py

• KG construction and Neo4j access: team_a/src/build_graph.py, team_a/src/neo4j_engine.py

• Query/answer interfaces: team_a/ask.py, team_a/bio_qa.py

Its extraction boundary converts source text into schema-constrained entities and triples before Neo4j writes: team_a/src/extract_entitites.py, team_a/src/extract_triples.py, team_a/src/schema.py.

Team B: Decoupled KG-RAG Pipeline

Team B separates structural and semantic retrieval: Neo4j holds the canonicalized graph, while Qdrant indexes chunks/evidence vectors using shared deterministic IDs. Its main entry point runs corpus processing; its query engine combines vector candidates, graph traversal/context, optional reranking, and LLM synthesis.

• Pipeline orchestration: team_b/src/run_all.py

• Graph and vector-store builders: team_b/src/build_graph.py, team_b/src/build_vectorstore.py

• Hybrid query path: team_b/src/query_engine.py, team_b/src/qa_client.py

• Retrieval-quality stage: team_b/src/reranker.py

Canonicalization, graph schema, and domain constraints are explicit architectural controls that reduce duplicate entities and constrain relationship meaning: team_b/src/canonicalize.py, team_b/src/graph_schema.py, team_b/src/domain_schema.py.

Ingestion and Knowledge Artifacts

The shared domain is sourced from OpenStax-derived biology text and PDFs, covering photosynthesis, genetics, and fungi. Parsing/chunking creates retrievable source units; LLM extraction produces triples; these become graph and vector records. Generated triples, answers, traces, checkpoints, and coverage results are persisted as inspectable offline artifacts.

• Team A parsing/chunking: team_a/src/parse_pdf.py, team_a/src/chunking.py

• Team B parsing/chunking/extraction: team_b/src/parse_pdf.py, team_b/src/chunking.py, team_b/src/extract_triples.py

• Corpus and evaluation truth: team_b/data/ground_truth.curated.json, data/ground_truth.json

• Existing Qdrant local data: qdrant_data/collection/chunks/storage.sqlite

Query, Evaluation, and Output Flow

At serving time, a question enters ask.py or the Team B Streamlit UI, is embedded/retrieved against graph and/or vector stores, assembled into grounded context, then sent to a configured QA model. Answers and retrieval traces are saved as JSON, enabling comparison across model configurations. Evaluation uses ground truth and RAGAS, while coverage checks assess graph completeness.

• Team B UI/API-facing path: team_b/app.py, team_b/src/ui_backend.py

• Evaluation stages: team_b/src/evaluate.py, team_b/src/run_ragas.py, team_b/src/check_coverage.py

• Representative answer/trace artifacts: team_b/outputs/model_runs/mistral_rerank/, outputs/answers/

Runtimes and External Services

Python is the primary runtime; LLM access is configured through OpenRouter credentials and model names. Neo4j is required by both architectures. Team B additionally runs Qdrant via Docker Compose. Team B’s interactive UI uses Streamlit.

• Service definition: team_b/docker-compose.yml

• Environment contract: .env.example

• Dependency boundaries: team_a/requirements.txt, team_b/requirements.txt

• Neo4j-only Graphiti demo backend: demo/backend/graphiti_setup.py, demo/backend/seed_maya.py

Personalized Graphiti Demo

The demo/ subsystem is a distinct full-stack visualization of personalized graph memory, not the primary Team A/B benchmark pipeline. A Python API exposes seeded Graphiti state and snapshots; a Next.js frontend renders graph entities, episodes, and answer comparisons.

• Backend server and snapshot API: demo/backend/server.py, demo/backend/snapshot.py

• Frontend application and graph visualization: demo/web/app/page.tsx, demo/web/components/GraphCanvas.tsx

• Frontend-to-backend boundary: demo/web/lib/api.ts, demo/web/lib/types.ts