diff --git a/README.md b/README.md index 6cf5be9..803208b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,44 @@ # EMUAdvisor -EMUAdvisor is an independent, local-only English/Turkish retrieval assistant for public Eastern Mediterranean University regulations. It is a research/demo project, not an official university service, decision-maker, or production deployment. +EMUAdvisor is an independent, local-only English/Turkish retrieval assistant for public Eastern Mediterranean University regulations. It combines deterministic routing, hybrid retrieval, cited answers, refusal and clarification behavior, and optional local generation behind a FastAPI application. + +It is a research/demo project, not an official university service, decision-maker, or production deployment. + +## What it demonstrates + +- **Grounded retrieval:** deterministic routing with hybrid local/Qdrant retrieval over an explicitly selected corpus. +- **Evidence-first answering:** cited extractive answers, clarification paths, and refusal behavior rather than answering every query at any cost. +- **Bilingual application surface:** English/Turkish retrieval-assistant workflow with a static user and diagnostic UI. +- **Local runtime boundary:** answering, retrieval, and optional generation remain local; no external answering or model API is required. +- **Optional local generation:** Ollama can provide generation while remaining inside the local runtime boundary. +- **Controlled ingestion:** official-source ingestion is restricted to exact-host HTTPS on `mevzuat.emu.edu.tr`, including redirect/final-URL validation. +- **Privacy-aware sessions:** public continuation/read/export/clear operations require a server-issued session ID plus a separate per-session capability. +- **Evaluation tooling:** tracked regression sets, automated proxy metrics, review-status tooling, and publication guards keep software behavior separate from unsupported answer-quality claims. + +## System boundary + +```text +Official public regulations + │ + │ controlled HTTPS ingestion + ▼ + corpus / local artifacts + │ + ▼ + deterministic routing + │ + ▼ + hybrid retrieval ───────────► local / Qdrant path + │ + ▼ + evidence + answerability + │ + ├──► cited extractive answer + ├──► clarification / refusal + └──► optional local Ollama generation +``` + +Fixture mode is explicit, limited to development/test, visibly labeled, and never attributed to the official source domain. Artifact-backed mode fails closed when required corpus artifacts are missing or invalid. ## Current status @@ -8,6 +46,8 @@ The software path is active, but benchmark, board-demo, publication, release, an Historical percentages in older project records were produced by automated retrieval/behavior proxies. They did not semantically grade answer correctness, citation precision, or claim-level grounding. New metric output uses schema `emu-advisor-automated-proxy/v2` and labels those observations explicitly. +Current blockers include independent human adjudication, immutable run manifests and an artifact-backed reproducible rerun, corpus rights/distribution decisions, live Qdrant/Ollama/target-hardware validation, and an Internet-grade identity/threat model. + ## Trust boundary - Runtime answering and optional generation remain local. No external answering, retrieval, or model API is used.