Answer questions about university Moodle courses from the student's own course files, with cited sources, on a local machine.
Evidence
01 / 06
Recorded Ask AAOS answer to “what is KNIME based on my past courses?”. The reply is labelled as coming from an archived course and lists the file, page, and version of each source. It was captured with the optional Gemini model selected, which is why the top bar shows the cloud badge.
Screenshot 1 of 6: Cited answer from a past course
Interface
The AAOS Overview page in light and dark mode. Drag across the image, or focus the handle and use the arrow keys, to compare them.
Problem
Course material is scattered across Moodle courses, files, and announcements, and generic chatbots answer from the open web instead of what a student was actually taught. AAOS answers from the student's own course files with citations, or says it does not have enough evidence.
Role / contribution
Project author responsible for the Python backend, Moodle connector, document pipeline, RAG and verification, agent orchestration, approvals, notifications, and the Next.js dashboard, built in gated phases with written acceptance criteria.
System context
Architecture flow
What happens
Playwright drives a dedicated Edge profile to sync courses, assignments, deadlines, announcements, and files without ever writing to Moodle.
Why it matters
A sync is used only when it is complete, so downstream answers and alerts never act on a partial snapshot.
What happens
Files are stored by SHA-256 hash, and text is extracted from PDF and Word files with page numbers kept for every passage.
Why it matters
Page-level provenance lets every answer point back to the exact file and page it came from.
What happens
A deterministic English and Arabic router sends known intents to typed tools; other questions enter a bounded agent loop where the model proposes tool calls.
Why it matters
Common questions need no model guess, and model proposals are validated against a closed schema before anything runs.
What happens
BGE-M3 dense search in Chroma is combined with SQLite FTS5 lexical search over the course passages.
Why it matters
Dense and lexical search cover each other's misses on mixed English and Arabic course material.
What happens
The answer's claims must cite evidence IDs, and an NLI model verifies each claim against its passage; unsupported claims are dropped.
Why it matters
The system answers with sources or says it lacks evidence, instead of inventing deadlines, files, or facts.
Engineering decisions
Decision 01
The database, documents, search index, and models run on the user's machine; the optional Gemini cloud model is off by default and confirmed in the app before use.
Decision 02
Model output, retrieved text, and tool results are treated as untrusted input; typed tools validate arguments and permissions before executing.
Decision 03
A Google Calendar event is only created after the user approves a durable approval record, and unclear outcomes are shown as unknown rather than success.
Under the hood
Four short excerpts from the AAOS source, copied verbatim from the public repository. Line numbers match the linked commit on GitHub.
DRAGOX7/aaos @ 621288d
Intent routing
src/aaos/agent/intent_router.py L375–415
A deterministic English/Arabic router sends known questions to typed tools. Anything that writes is never routed, so it has to go through the agent loop's permission checks.
def route_intent(question: str) -> RoutedIntent:
"""Classify a question into one closed intent, or UNROUTED.
Precedence: write/task/calendar requests are never routed; announcements
or changes combined with each other or with a summary are ambiguous;
changes outrank entity words; announcements outrank document and
assignment words; a summary needs a document reference to be a document
summary; a document reference outranks assignment and course facts.
"""
text = normalize_arabic(question)
if not text or has_bilingual_write_intent(text) or _TASK_OR_CALENDAR.search(text):
return RoutedIntent.UNROUTED
if asks_about_assistant(question):
return RoutedIntent.UNROUTED
summary = _SUMMARY.search(text) is not None
document = _DOCUMENT.search(text) is not None or _COURSE_DETAILS.search(text) is not None
announcements = _ANNOUNCEMENTS.search(text) is not None
changes = _CHANGES.search(text) is not None
course_facts = _COURSE_FACTS.search(text) is not None
assignments = _ASSIGNMENTS.search(text) is not None
if (changes and (announcements or summary)) or (announcements and summary):
return RoutedIntent.UNROUTED
if changes:
return RoutedIntent.MOODLE_CHANGES
if announcements:
return RoutedIntent.ANNOUNCEMENTS
if summary:
if assignments and not document:
return RoutedIntent.UNROUTED
return RoutedIntent.DOCUMENT_SUMMARY if document else RoutedIntent.COURSE_SUMMARY
if document:
return RoutedIntent.DOCUMENT_QUESTION
if assignments:
return RoutedIntent.ASSIGNMENT_FACTS
if course_facts:
return RoutedIntent.COURSE_FACTS
if _CONCEPT.search(text) and not _PERSONAL.search(_PAST_COURSES.sub("", text)):
return RoutedIntent.DOCUMENT_QUESTION
return RoutedIntent.UNROUTEDTechnical implementation
A browser-based connector syncs courses, assignments, deadlines, announcements, and files from Moodle read-only through a dedicated Edge profile, and only complete snapshots are used.
Downloaded files go into a SHA-256 content-addressed store; PDF and Word text, including Arabic, is extracted with page-level provenance.
Retrieval combines BGE-M3 dense vectors in Chroma with SQLite FTS5 lexical search, and an mDeBERTa NLI model checks every cited claim before it is shown.
A local chat model served by LM Studio proposes actions as JSON; a closed schema and typed tools decide what actually runs.
aaos — Local setup and run
PowerShellStack
Limits and next steps
Project explainer
A case-study guide to the architecture and decisions behind AAOS — Academic AI OS.