Developed for the Nebius x NVIDIA Global AI Hackathon.
- Track: Best Apps and Agents. Also eligible for Best Use of Tavily.
- Required runtime: Chat completions go to Nebius Token Factory (
https://api.tokenfactory.nebius.com/v1/). Answers use NVIDIA Nemotron 3 Super (nvidia/nemotron-3-super-120b-a12b). Query rewrite and rerank use NVIDIA Nemotron 3 Nano (nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B). Embeddings stay on NVIDIA NIM (nvidia/llama-nemotron-embed-vl-1b-v2). - 5-minute run: copy
.env.exampleto.env.local, setNEBIUS_API_KEY,NVIDIA_API_KEY, andTAVILY_API_KEY, thenbin/study-assistant. Open the printed frontend URL. Under Notes, load a PDF (up to 200 MB). Ask a question with the source switch on Notes, Web, or Both. A cited page is drawn under the answer. Ask for a plot and a comparison and the reply includes a rendered graph and a markdown table. - Built during the submission window (opened 26 Aug 2026): grounded RAG tutor, Token Factory Nemotron routing, Tavily academic search, numbered citations, KaTeX formulas, cited-page images, 2D/3D plots, Next.js + FastAPI UI, tests and CI.
- Benchmark table later in this README is from
python -m evaluation.benchmark --mock(offline, no live API).
- 1. Executive Summary & Problem Statement
- 2. System Architecture
- 3. What We Have Built So Far (Current Implementation)
- 4. Roadmap & Upcoming Implementations
- 5. Repository Structure
- 6. Getting Started & Quickstart
- 7. Questions for Faculty Advisors & Academic Feedback
- 8. Hackathon Evaluation Alignment
- 9. License & Acknowledgments
Modern university students and researchers are routinely overwhelmed by hundreds of pages of lecture slides, syllabus documents, academic papers, and textbooks across multiple courses. While general-purpose Large Language Models (LLMs) provide rapid answers, they exhibit critical flaws in academic contexts:
- Hallucinations & False Assertions: Generic models invent plausible-sounding equations, theorems, and historical dates.
- Lack of Attribution: Students cannot verify where an explanation originated, making generic AI unsuitable for exam preparation or citation.
- Colloquial Query Mismatches: Students frequently formulate informal, vague study queries that fail to match the formal terminology used in textbooks.
Study Assistant is an end-to-end, grounded Retrieval-Augmented Generation (RAG) platform designed specifically for higher education. It transforms dense course documents into an interactive, pedagogical AI tutor that guarantees:
- Strict Grounding: Zero outside knowledge assumption; answers are derived exclusively from course materials.
- Numbered citations: Claims are marked
[1],[2], … and the reference list names the file and page. A cited PDF page is rendered under the answer. - Formulas, graphs, and tables: Math is rendered with KaTeX. A request for a plot draws a 2D curve or a 3D surface. Comparisons are markdown tables.
- NVIDIA Nemotron on Nebius Token Factory: Tutor answers run on
nvidia/nemotron-3-super-120b-a12b, while query augmentation and reranking run onnvidia/NVIDIA-Nemotron-3-Nano-30B-A3B, both served through Nebius Token Factory. Embeddings (nvidia/llama-nemotron-embed-vl-1b-v2) and slide vision run on NVIDIA NIM, which is also the LLM fallback when no Nebius key is set. - Query Intelligence: Query rewriting, multi-query expansion, and Hypothetical Document Embeddings (HyDE) to bridge student vocabulary with formal academic literature.
The following diagram illustrates the complete dataflow from raw course documents to citation-backed student responses:
flowchart TB
subgraph CLIENTS["Client Interfaces"]
WEB["Next.js 16 Web UI (frontend/)"]
CLI["Terminal CLI (--chat / --ask / --ingest)"]
API["Python Library (from src import StudyAssistant)"]
end
subgraph SERVER["Web Application Server (src/api/server.py)"]
SRV["FastAPI Server (REST & SSE Streaming)"]
end
subgraph ORCHESTRATOR["Unified Facade: StudyAssistant (src/assistant.py)"]
FACADE["StudyAssistant Orchestrator"]
end
subgraph INGESTION["Phase 1: Ingestion & Indexing Engine"]
A[Lecture PDFs / Slides / Markdown / TXT] --> B[DocumentLoader<br/>pypdf & metadata extractor]
B --> C[DocumentChunker<br/>RecursiveCharacterTextSplitter]
C --> D[NvidiaEmbedder<br/>input_type='passage'<br/>llama-nemotron-embed-vl-1b-v2]
D --> E[(ChromaDB Vector Store<br/>HNSW Cosine Distance)]
end
subgraph QUERY["Phase 2: Query Augmentation & Retrieval"]
F[Student Question] --> G[QueryAugmenter<br/>Nemotron 3 Nano on Token Factory]
G -->|Strategy 1: Rewrite| H1[Academic Keyword Query]
G -->|Strategy 2: Multi-Query| H2[Expanded Query Variations]
G -->|Strategy 3: HyDE| H3[Hypothetical Textbook Passage]
H1 & H2 & H3 --> I[NvidiaEmbedder<br/>input_type='query']
I --> J[ChromaDB Nearest Neighbor Search]
J --> K[Max-Score Pooling & Deduplication]
K --> L[Cosine Similarity Threshold Filter]
L --> RR[StudyReranker<br/>Nemotron 3 Nano listwise scoring]
end
subgraph GENERATION["Phase 3: Grounded Pedagogical Generation"]
RR --> M[Structured Context Formatter<br/>with Page Metadata]
M --> N[StudyGenerator Engine]
N -.->|Primary Provider| O1[Nebius Token Factory<br/>Nemotron 3 Super]
N -.->|Fallback Provider| O2[NVIDIA NIM]
O1 & O2 --> P[Citation check, KaTeX, page images, plots]
P --> Q[Final Grounded Answer<br/>+ Numbered citations<br/>+ Rendered book pages and graphs]
end
WEB --> SRV
SRV --> FACADE
CLI --> FACADE
API --> FACADE
FACADE -->|"ingest(path)"| INGESTION
FACADE -->|"search(query)"| QUERY
FACADE -->|"ask(query)"| GENERATION
E -.-> J
The project is structured as a production-grade, modular Python architecture organized under src/ with complete test coverage in tests/.
The ingestion pipeline handles raw document intake, metadata extraction, semantic segmentation, and idempotent vector persistence:
| Module | Core Class / Function | Technical Responsibility |
|---|---|---|
loader.py |
DocumentLoader |
Ingests .pdf, .txt, .md, and slide images (.png, .jpg, .jpeg). Uses pypdf to extract text and embedded slide diagrams while tracking exact 1-indexed page numbers, visual flags, and uniform file metadata. |
vision.py |
VisionDescriber |
Multimodal vision client powered by NVIDIA NIM (meta/llama-3.2-11b-vision-instruct). Performs aspect-preserving thumbnail scaling, noise filtering (skips icons/dividers <150x150 or <1KB), SHA-256 deduplication caching, and generates pedagogical descriptions for lecture slide figures and system diagrams. |
chunker.py |
DocumentChunker, chunk_documents |
Employs RecursiveCharacterTextSplitter configured for semantic boundary conservation (\n\n, \n, . , ). Configurable chunk size (default: 500 chars) and overlap (default: 50 chars) to prevent context fragmentation across formulas. |
embedder.py |
NvidiaEmbedder |
Integrates with NVIDIA NIM retrieval models (default: nvidia/llama-nemotron-embed-vl-1b-v2). Implements asymmetric embedding: distinguishes between input_type="passage" for document chunks and input_type="query" for user queries. Supports batched embedding generation (batch size 64) with exponential backoff retries. |
indexer.py |
ChromaIndexer |
Wraps ChromaDB with persistent HNSW index using cosine space (hnsw:space: cosine). Implements metadata sanitization, deterministic SHA-256 chunk IDs (_generate_chunk_id), and ghost chunk prevention via delete_by_path during re-ingestion. |
pipeline.py |
IngestionPipeline, main() |
Orchestrates the entire ETL workflow with CLI argument parsing (--file, --dir, --batch-size), directory recursion, real-time progress callbacks, and isolated exception handling. |
Rather than relying on naive single-shot vector lookups, the retrieval layer implements query enhancement algorithms to maximize retrieval recall across academic documents:
| Module | Core Class / Function | Technical Responsibility |
|---|---|---|
query_augmenter.py |
QueryAugmenter |
Rewrite, multi-query, and HyDE. Uses Nemotron 3 Nano on Token Factory when NEBIUS_API_KEY is set. |
retriever.py |
StudyRetriever |
Computes cosine similarity (score_threshold), executes multi-query search with max-score pooling deduplication, and formats context blocks with source and page tags (format_context). |
reranker.py |
StudyReranker |
Listwise scoring with Nemotron 3 Nano on Token Factory, or a dedicated NVIDIA /v1/ranking service. |
tavily_search.py |
TavilySearchClient |
Grounded academic web search integration via Tavily API. Filters for high-authority academic domains (.edu, arxiv.org, wikipedia.org, .gov, .org) with automatic fallback to mock mode for offline testing. |
The generation layer ensures student answers are pedagogical, structured, and strictly constrained to verified source context:
| Feature | Implementation Details |
|---|---|
| Dual Cloud Infrastructure |
src/providers.py sends chat completions to Nebius Token Factory when NEBIUS_API_KEY is set, and to NVIDIA NIM otherwise. The model name is printed under each answer. |
| Source choice | The composer is Notes, Web, or Both. Notes never calls Tavily. Web does not search the course index. |
| Citations and pages | Answers use [1], [2], … only for retrieved chunks. src/ingestion/page_images.py draws up to three cited PDF pages into the reply. |
| Math, plots, and tables | KaTeX renders $...$ and $$...$$. src/generation/plots.py draws 2D curves and 3D surfaces from a plot block, and adds a teaching graph when the student asked for one and the model did not emit a spec. Comparisons are markdown tables. |
| Streaming Output |
generate_stream() yields tokens. The finished answer replaces the draft after citation checking, math cleanup, page images, and plots. |
The StudyAssistant facade coordinates all subsystems into a unified, high-level developer and CLI interface:
| Method / Feature | Implementation Details |
|---|---|
ingest(path) |
Accepts a single document (.pdf, .txt, .md) or an entire course directory. Automatically routes to IngestionPipeline and returns ingestion summaries. |
search(query) |
Executes query augmentation, dense vector retrieval, and semantic reranking without calling the LLM generator. Useful for fast source inspection and relevance audits. |
ask(query, stream=False) |
Runs the full pipeline: input guards $ |
| ightarrow$ DB empty check $ | |
| ightarrow$ retrieval $ | |
| ightarrow$ reranker $ | |
| ightarrow$ context formatting $ | |
| ightarrow$ grounded generation with page-level citations. Supports real-time token streaming. | |
count() & clear()
|
Provides collection introspection and safe reset capabilities. |
Interactive Terminal Chat (--chat) |
Full interactive study session with typewriter token streaming, /count status inspection, and graceful termination. |
| CLI Command Flags | Supports --ask "...", --ingest "...", --top-k, --top-n, --mode, --no-augment, and --db-path. |
- 14 Comprehensive Unit & Integration Test Suites (169 Tests Passing in ~1.5s):
tests/test_loader.py: Validates PDF page extraction, image loading, text reading, and unsupported format rejections (7 tests).tests/test_vision.py: Tests NVIDIA NIM vision model integration, dimension/noise filtering, RGBA transparency, and SHA-256 caching (9 tests).tests/test_chunker.py: Tests boundary preservation, overlap logic, and empty input handling (5 tests).tests/test_embedder.py: Validates API payload construction, input typing (passagevsquery), and batched embeddings (6 tests).tests/test_indexer.py: Tests ChromaDB upsert, query similarity, and path-based deletion (4 tests).tests/test_pipeline.py: Tests end-to-end ingestion flow, progress callbacks, and error isolation (3 tests).tests/test_query_augmenter.py: Verifies rewrite, expand, and HyDE prompt executions with mocked LLM clients (11 tests).tests/test_retriever.py: Tests similarity scoring, threshold filtering, and multi-query pooling (9 tests).tests/test_reranker.py: Validates semantic reranking, sigmoid normalization, monotonic negative imputation, index mapping, and fallback paths (20 tests).tests/test_generator.py: Verifies provider switching (NVIDIA vs Nebius), citations, and streaming token yields (10 tests).tests/test_assistant.py: TestsStudyAssistantfacade initialization, dependency injection, ingestion delegation, streaming/non-streaming ask, empty query & DB guards, search, count/clear, and CLI command execution including interactive chat (18 tests).tests/test_evaluation.py: Validates precision, recall, MRR, source filtering, faithfulness scoring, edge cases, dataset integrity, and report export (18 tests).tests/test_api.py: Validates FastAPI status, document inspection, background job processing, image and sample ingestion, ask, SSE streaming, search, flashcard generation, and Prometheus metrics (14 tests).tests/test_tavily.py: Validates Tavily client initialization, domain filtering, mock mode, and hybrid web RAG fallback (9 tests).
- Continuous Integration (CI):
- Configured via
.github/workflows/test.ymlrunning Pytest automatically on push and pull request against Python 3.11. All 169 tests run green on GitHub Actions without consuming live API credits.
- Configured via
Following modern 2026 frontend vibe coding best practices, the application features an enterprise-grade full-stack interface:
| Component | Technology | Responsibility |
|---|---|---|
| Frontend Framework | Next.js 16 (App Router, React 19, TypeScript) | High-prior agent architecture, responsive split-screen layouts, instant hot reloading via Turbopack. |
| Design System | Vanilla CSS (Linear/Vercel Aesthetic) | Minimalist, zero-emoji typography, dark mode (#0b0f17) and light mode (#f8fafc) with dynamic CSS theme toggle. |
| REST & SSE Backend | FastAPI + Uvicorn (src/api/server.py) |
Asynchronous typed endpoints with Server-Sent Events (/api/ask/stream) for typewriter token streaming, background ingestion job polling (/api/ingest/status/{job_id}), and Prometheus telemetry (/metrics). |
| Academic Modules | 3 Focused Views | Academic Tutor (grounded citations, web search augmentation, diagram badges), Course Materials (PDF slide decks, .png/.jpg diagrams, Markdown notes, sample loader with live progress tracking), and Study Flashcards (active recall with 3D flip card self-testing). |
To empirically prove that our architectural innovations yield measurable improvements over naive vector search, we built an automated evaluation framework comparing Naive Baseline RAG, Query Augmented RAG, and Our Full Advanced Pipeline:
| Module | Core Functionality |
|---|---|
dataset.py |
Curated academic evaluation items across formal technical queries and colloquial student queries with ground-truth facts. |
metrics.py |
Deterministic calculators for Context Precision@K, Context Recall@K, Mean Reciprocal Rank (MRR), and Faithfulness. |
benchmark.py |
Automated comparative runner evaluating all 3 configurations with latency tracking (python -m evaluation.benchmark). |
report_generator.py |
Exports publication-grade Markdown reports and structured JSON data for frontend visualization. |
| Metric | 1. Naive Baseline RAG | 2. Query Augmented RAG | 3. Our Advanced Pipeline | Relative Improvement |
|---|---|---|---|---|
| Context Recall@5 | 62.5% | 95.0% | 100.0% | +60.0% |
| Context Precision@5 | 50.0% | 55.0% | 85.0% | +70.0% |
| Mean Reciprocal Rank (MRR) | 0.41 | 0.65 | 0.95 | +128.9% |
| Faithfulness / Grounding | 90.0% | 92.0% | 98.0% | +8.9% |
| Average Latency | 120ms | 280ms | 450ms | (Optimal for real-time UI) |
For the next iteration of the project and hackathon presentation, we are planning and actively architecting the following features:
gantt
title Development Roadmap & Milestone Deliverables
dateFormat YYYY-MM-DD
axisFormat %b %d
section Implemented
Document Ingestion & Chunking :done, 2026-09-01, 2026-09-25
NVIDIA NIM & ChromaDB Vector Store :done, 2026-09-04, 2026-09-26
Query Augmenter (Rewrite / HyDE) :done, 2026-09-07, 2026-09-27
Study Generator (Dual-Cloud LLM) :done, 2026-09-10, 2026-09-28
Semantic Reranker (Listwise) :done, 2026-09-12, 2026-09-29
Unified Assistant Orchestrator :done, 2026-09-14, 2026-09-30
Academic Evaluation & Benchmarks :done, 2026-09-16, 2026-09-30
Next.js 16 Web UI & FastAPI Server :done, 2026-09-16, 2026-09-30
Active Recall & Study Flashcards :done, 2026-09-18, 2026-09-30
Prometheus Metrics & Tavily Search :done, 2026-10-01, 2026-10-04
Multimodal Slide & Diagram Parser :done, 2026-10-01, 2026-10-05
section Upcoming Roadmap
Synchronized PDF Viewer Integration :2026-10-06, 2026-10-26
Production Telemetry & Observability:2026-10-10, 2026-10-31
- Goal: University lecture slides and technical papers are heavily visual (e.g., circuit diagrams, biological pathways, chemistry reactions, neural network architectures). Standard text extraction drops this crucial visual context.
- Implemented Architecture:
- VisionDescriber Engine (
src/ingestion/vision.py): Powered by NVIDIA NIM (meta/llama-3.2-11b-vision-instruct). Generates comprehensive pedagogical descriptions, transcribing text labels, structural flows, axes, legends, and domain concepts. - Embedded Figure & Slide Ingestion: Extracted visual figures directly from PDF pages (
pypdf.page.images) and added native support for standalone lecture slides (.png,.jpg,.jpeg). - Image Preprocessing & Noise Filtering: Aspect-preserving thumbnail downscaling (max 1024x1024 px), RGBA alpha-channel composition on white background, and noise filtering skipping decorative icons, logos, and horizontal rules (<150x150 px, <1000 bytes, or aspect ratio outside 0.15 - 6.5).
- SHA-256 Deduplication Caching: Content-hash caching prevents duplicate vision API calls across repeated slide templates or re-ingestions.
- Structured Markdown Embedding: Formats descriptions into structured context blocks (
[Visual Diagram / Slide Figure on Page X]: ...) indexed into ChromaDB alongside page text. - Frontend UI Indicators: Document inventory displays visual diagram counts and badges, while the Citation Inspector renders explicit
[Diagram / Visual Context]badges for multimodal evidence.
- VisionDescriber Engine (
- Goal: Provide a seamless, split-screen desktop and web UI.
- Implementation: When a student clicks an inline citation
[Source: lecture3.pdf, Page: 14], an embedded PDF viewer will jump directly to page 14 and highlight the exact matching excerpt.
- Goal: Rigorously monitor live RAG performance, latency budgets, and model drift during active study sessions.
- Metrics to Track:
- Faithfulness (Groundedness): Real-time validation of generated claims against retrieved context via TruLens.
- Latency Budgets: Step-by-step retrieval, reranking, and time-to-first-token (TTFT) tracking.
study-assistant/
├── .github/
│ └── workflows/
│ └── test.yml # GitHub Actions automated CI testing workflow
├── evaluation/ # Quantitative academic evaluation & benchmark suite
│ ├── __init__.py
│ ├── benchmark.py # Multi-pipeline comparative benchmark runner
│ ├── benchmark_report.md # Generated empirical benchmark comparison report
│ ├── benchmark_results.json # Serialized benchmark dataset for UI charting
│ ├── dataset.py # Curated benchmark items (formal & colloquial queries)
│ ├── metrics.py # Deterministic Precision@K, Recall@K, MRR & Faithfulness
│ └── report_generator.py # Markdown & JSON benchmark reporting engine
├── frontend/ # Next.js 16 App Router Web Application
│ ├── app/
│ │ ├── globals.css # Minimalist Vanilla CSS theme (Dark/Light modes)
│ │ ├── layout.tsx # Root layout & metadata
│ │ └── page.tsx # Academic Tutor, Materials & Study Flashcards
│ ├── next.config.ts # API rewrite proxy to FastAPI (port 8000)
│ └── package.json # React 19 & Next.js dependencies
├── src/
│ ├── __init__.py # Top-level package exports (StudyAssistant facade)
│ ├── assistant.py # Unified Assistant Orchestrator & CLI (--chat / --ask)
│ ├── api/ # FastAPI REST & SSE Streaming Server
│ │ ├── __init__.py
│ │ └── server.py # Typed endpoints (/api/ask/stream, /api/documents)
│ ├── ingestion/ # Document processing, chunking & vectorization
│ │ ├── __init__.py
│ │ ├── chunker.py # Recursive text chunking with overlap
│ │ ├── embedder.py # NVIDIA NIM embedding client (asymmetric query/passage)
│ │ ├── indexer.py # ChromaDB client with HNSW indexing & hash IDs
│ │ ├── loader.py # Multi-format document loader with page retention
│ │ ├── pipeline.py # End-to-end ingestion pipeline & CLI entrypoint
│ │ ├── vision.py # Slide-image descriptions for short PDFs
│ │ └── page_images.py # Renders cited PDF pages into the answer
│ ├── retrieval/ # Search, query expansion & context synthesis
│ │ ├── __init__.py
│ │ ├── query_augmenter.py # Query rewriting, multi-query expansion & HyDE
│ │ ├── reranker.py # Semantic cross-encoder & LLM listwise reranker
│ │ ├── retriever.py # Vector similarity search & context formatting
│ │ └── tavily_search.py # Grounded academic web search integration
│ └── generation/ # Grounded LLM response generation
│ ├── __init__.py
│ ├── generator.py # Nemotron answer client and citation prompt
│ ├── tutor_format.py # Citation check, math cleanup, reference numbers
│ └── plots.py # 2D/3D teaching graphs
├── tests/ # Complete test suite (169 passing tests)
│ ├── conftest.py # Pytest fixtures & environment setup
│ ├── test_api.py # FastAPI REST endpoints & SSE streaming (14 tests)
│ ├── test_assistant.py # Unit tests for Orchestrator & CLI (18 tests)
│ ├── test_chunker.py # Unit tests for text chunking (5 tests)
│ ├── test_embedder.py # Unit tests for NVIDIA embedding client (6 tests)
│ ├── test_evaluation.py # Unit tests for evaluation metrics & benchmarks (18 tests)
│ ├── test_generator.py # Unit tests for LLM generation & fallback logic (10 tests)
│ ├── test_indexer.py # Unit tests for ChromaDB storage & queries (4 tests)
│ ├── test_loader.py # Unit tests for document loading (7 tests)
│ ├── test_pipeline.py # Integration tests for ingestion pipeline (3 tests)
│ ├── test_query_augmenter.py # Unit tests for query augmentation strategies (11 tests)
│ ├── test_reranker.py # Unit tests for semantic reranker (20 tests)
│ ├── test_retriever.py # Unit tests for retrieval & scoring (9 tests)
│ ├── test_tavily.py # Unit tests for Tavily search & domain filtering (9 tests)
│ └── test_vision.py # Unit tests for NVIDIA vision describer (9 tests)
├── sample_materials/ # Curated lecture notes & Kepler sample
├── .env.example # Sample environment variable configuration
├── .gitignore # Ignored files (virtualenvs, cache, db, node_modules)
├── LICENSE # MIT License
├── requirements.txt # Pinned dependencies
└── README.md # Project documentation & academic report
- Python 3.10 or 3.11+
- Git
Clone the repository and install dependencies in a virtual environment:
# Clone the repository
git clone https://github.com/Khazar451/study-assistant.git
cd study-assistant
# Create and activate a virtual environment
python -m venv .venv
# On Linux/macOS:
source .venv/bin/activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Install requirements
pip install --upgrade pip
pip install -r requirements.txtCreate a .env file in the project root based on .env.example:
cp .env.example .envPopulate your API keys:
# Primary LLM Provider: Nebius Token Factory (NVIDIA Nemotron)
NEBIUS_API_KEY=your-nebius-token-factory-key-here
NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1/
NEBIUS_MODEL=nvidia/nemotron-3-super-120b-a12b
NEBIUS_FAST_MODEL=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B
# NVIDIA NIM: embeddings, slide vision, and LLM fallback
NVIDIA_API_KEY=nvapi-your-key-here
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
EMBEDDING_MODEL=nvidia/llama-nemotron-embed-vl-1b-v2
LLM_MODEL=meta/llama-3.2-11b-vision-instruct # only used without NEBIUS_API_KEYThe assistant provides a unified command-line interface for interactive chatting, single-shot queries, and document ingestion:
# 1. Launch interactive study session with real-time typewriter token streaming:
python -m src.assistant --chat
# 2. Ask a single question directly with verified citations:
python -m src.assistant --ask "What is Kepler's first law of planetary motion?"
# 3. Ingest lecture notes, slides, or course materials:
python -m src.assistant --ingest "sample_materials/astronomy_kepler.txt"
# 4. Ingest an entire course directory:
python -m src.assistant --ingest "path/to/course_materials/"Use the top-level StudyAssistant facade for clean programmatic access in your applications:
from src import StudyAssistant
# 1. Initialize the unified assistant (lazily coordinates all subcomponents)
assistant = StudyAssistant(persist_directory="./chroma_db")
# 2. Ingest course documents (single file or full folder)
assistant.ingest("sample_materials/astronomy_kepler.txt")
# 3. Ask questions with grounded answers and verified page citations
response = assistant.ask(
query="How do planets orbit the sun according to Kepler?",
top_k=15,
top_n=5,
stream=False,
)
print("=== TUTOR ANSWER ===")
print(response["answer"])
print("\n=== AUDITABLE SOURCES ===")
print(response["sources"])The usual launch starts the API and the Next.js app together and opens the browser:
bin/study-assistantUse Notes for the course index, Web for Tavily, or Both. PDFs up to 200 MB can be uploaded under Notes. Indexing time is dominated by embedding calls, not by splitting the text. A cited page image, a KaTeX formula, and a plot (when you ask for a graph) appear in the answer.
To run the two processes yourself:
python -m uvicorn src.api.server:app --port 8000 --reload
cd frontend && npm run devExecute the full suite of unit and integration tests (169 tests passing):
python -m pytest tests/ -vRun the quantitative comparative benchmark suite across Naive Baseline RAG, Query Augmented RAG, and Our Full Advanced Pipeline:
# Run fast offline benchmark (zero live API calls):
python -m evaluation.benchmark --mock
# Run with custom query phrasing:
python -m evaluation.benchmark --mock --query-mode colloquialWe are actively seeking feedback from professors and academic mentors on the following core design considerations:
- Chunking Strategies for Mathematical & Technical Literature:
- Question: In mathematical proofs or engineering derivations, standard recursive character chunking can split an equation across boundaries. What boundary markers or semantic chunking strategies (e.g., AST-based or LaTeX-aware chunking) would you recommend for technical textbooks?
- Pedagogical Persona & Scaffolding:
- Question: Should an academic study assistant directly provide the full answer with citations, or would an adjustable Socratic scaffolding mode (prompting the student with hints and guiding questions based on the lecture slides) be more beneficial for genuine learning outcomes?
- Evaluation Metrics for Course Mastery:
- Question: When measuring the efficacy of the assistant against real students, which evaluation dimensions would best measure educational impact (e.g., time-to-mastery, reduction in misconception rate, or score improvement on standardized exams)?
This project is built to satisfy the core evaluation criteria of the Nebius x NVIDIA Hackathon:
| Hackathon Criterion | Project Implementation & Proof Points |
|---|---|
| NVIDIA Technology Utilization | • NVIDIA NIM nvidia/llama-nemotron-embed-vl-1b-v2 for state-of-the-art embedding retrieval.• NVIDIA NIM meta/llama-3.2-11b-vision-instruct for query enhancement and grounded reasoning.• Prepared integration for NVIDIA NeMo Reranker ( nvidia/reranking-nemotron-4b). |
| Nebius Token Factory Integration | • Every chat completion (answers, query augmentation, reranking) runs on Nebius Token Factory when NEBIUS_API_KEY is set.• Nemotron 3 Super for grounded answers; Nemotron 3 Nano for the fast retrieval-side calls. |
| Technical Depth & Engineering Rigor | • Complete separation of concerns (ETL, Vector Indexing, Query Augmentation, Generation). • Idempotent chunking with SHA-256 deterministic IDs, eliminating ghost chunks. • 14 automated test suites (169 passing tests) with GitHub Actions CI pipeline and quantitative empirical benchmark suite. |
| Real-World Impact & Feasibility | • Solves a tangible, daily problem for thousands of university students and faculty. • Strict zero-hallucination guardrails and auditable page-level citations. |
- License: Distributed under the MIT License.
- Special Thanks:
- Nebius AI Studio for cloud GPU compute and OpenAI-compatible inference APIs.
- NVIDIA for high-efficiency NIM microservices and cutting-edge retrieval models.
- Course instructors and faculty advisors for pedagogical guidance and course data testing.