ask-pesu

A retrieval-augmented question answering system for PES University, answering from r/PESU discussions.

This monorepo holds two services:

Path	Service	What it does	Hugging Face Spaces
services/api	AskPESU	Answers questions: a FastAPI + LangChain RAG backend, and the React frontend it serves	askpesu (production), askpesu-dev (development)
services/db	AskPESU DB	Streams new r/PESU comment threads into Qdrant, and holds the scripts that backfill its history	askpesu-db, one instance for both api environments

How it works

flowchart LR
    reddit([r/PESU]) --> db["services/db<br/>listener and backfill"]
    db -- "dense + BM25 vectors" --> qdrant[(Qdrant)]
    browser([Browser]) -- "POST /ask" --> api["services/api<br/>RAG pipeline"]
    api -- "hybrid search" --> qdrant
    api -- "NDJSON stream" --> browser
    contract[/conf/collection.yaml/] -.- db
    contract -.- api

Loading

The db service indexes r/PESU threads into Qdrant. The api service searches them for each question and streams back an answer, with the threads it drew on. See Architecture and The answering pipeline for the details.

Quick start

You need uv and, for frontend work, Node.js 24. uv fetches Python 3.12 itself.

git clone https://github.com/pesu-dev/ask-pesu.git
cd ask-pesu
uv sync --extra api --extra db
cp .env.example .env               # then fill it in

Run the api with a working UI and no credentials, serving canned answers:

cd services/api
ENV=test uv run python -m app.app  # http://localhost:7860

# in a second terminal
cd services/api/frontend
npm ci
npm run dev                        # http://localhost:8080

To answer real questions, set the Qdrant variables and HF_TOKEN in .env, then run the api without ENV=test. Development covers the full setup, running the db listener, answering from a local ollama, and Docker.

Documentation

Document	Covers
Architecture	The two services, the repository layout, and where to make a change
The answering pipeline	How services/api turns a question into a streamed answer
Ingestion	How services/db indexes threads, and how to backfill history
The collection contract	conf/collection.yaml, the Qdrant collections, and how shared files reach each Space
HTTP API	Every route of both services, and the NDJSON streaming protocol
Configuration	Environment variables and services/api/conf/config.yaml
Frontend	The React app in services/api/frontend
Failure handling	Quota cooldowns, and what happens when each dependency fails
Development	Dependencies, running the services, Docker, tests and linting
CI and deployment	Workflows, deploying to the Spaces, and rollback
Design decisions	Settled decisions, and the issues that record why

Contributing

Pull requests come from a fork, from a branch other than main, and target dev. Read CONTRIBUTING.md and the Code of Conduct first. Security issues go to the maintainers privately; see SECURITY.md.

License

MIT.