Assignment Feedback Service (scaffold)

A lightweight web service for accepting student assignments, generating constructive feedback using an LLM abstraction, and storing submissions for future reference (RAG-ready scaffold).

This repository contains a minimal, runnable starting point so you can iterate on features such as vector retrieval (RAG), background processing, and a nicer UI.

Contents

• app/main.py — FastAPI application with endpoints for submitting and viewing assignments
• app/models.py — Assignment model (SQLModel)
• app/db.py — SQLite (./assignments.db) initialization and simple CRUD utilities
• app/llm.py — LLM abstraction for generating feedback and computing embeddings (OpenAI-enabled with fallback)
• templates/ — basic Jinja2 templates: index.html, list.html, assignment.html
• requirements.txt — minimal Python dependencies
• README.md — this documentation

Quick start (local)

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. (Optional) Provide an OpenAI API key to enable real LLM feedback and embeddings:

export OPENAI_API_KEY="sk-..."

3. Run the development server:

uvicorn app.main:app --reload

4. Open your browser at http://127.0.0.1:8000 and try submitting an assignment.

How it works

• Submissions are stored in a local SQLite database (assignments.db).
• On submit, the app attempts to compute an embedding for the assignment content and stores it in the embedding field (as JSON).
• Feedback is generated via the app/llm.py abstraction; if OPENAI_API_KEY is set, the module will attempt to call OpenAI Chat + Embeddings APIs. When no API key is available, a deterministic offline fallback is used so the app remains usable for testing.
• A simple substring-based search is implemented as a fallback; full RAG (nearest-neighbor search by cosine similarity) is not yet integrated in the scaffold.

Notes & limitations

• Feedback generation currently runs synchronously during the POST /submit request. For production workloads, move feedback generation to a background job queue (e.g., Celery, RQ, or FastAPI BackgroundTasks) and surface job status to the user.
• Embeddings are stored as JSON in the database when available. The repository does not yet provide an efficient vector index — consider adding NumPy-based similarity search, FAISS, or a managed vector DB for production RAG features.
• The frontend is intentionally minimal (plain Jinja2). Styling, client-side validation, and improved UX are left as next steps.

Next steps / roadmap

• Implement full RAG: store numeric embeddings and add a cosine-similarity retrieval endpoint (NumPy or FAISS), plus unit tests.
• Move feedback generation to background processing with job status tracking.
• Improve the UI using a frontend framework or simple CSS framework (Bootstrap/Tailwind).
• Add authentication/authorization and rate limiting as needed.
• Add unit tests and CI pipeline for automated verification.

Contributing

Contributions are welcome. Open an issue or a PR describing the change you'd like to make. For larger features (background workers, RAG, or DB changes), open an issue first so we can agree on an approach.

License

See the top-level LICENSE file in the repository.

assignments-solution