Knowledge Graph enhancements: relationship types, auto-update, definitions

[usmanali434]

Summary
Implements 5 of 6 enhancement tasks from the post-deployment gap review (Section 6, Team Lambda). Page/section metadata (task 4b) is intentionally deferred — see note below.

Task 1 & 2 — Data quality guards
Added explicit checks preventing self-linking documents and duplicate edges between the same pair, in both the document-level and topic-level graph builders.

Task 3 — Real relationship types
Replaced the flat "related_to" placeholder with actual LLM-based classification (Groq, openai/gpt-oss-20b) — each edge is now labeled prerequisite_of, example_of, contrasts_with, or related_to based on the actual content, not just a similarity threshold. Falls back safely to related_to on any API failure.

Task 4a — Document definitions
Each document node now includes an auto-generated one-sentence definition, created once when the document is added (not regenerated on every read).

Task 4b (page/section reference) is deferred** — it requires restructuring ingestion's PDF/YouTube/article extraction to preserve page/timestamp/section boundaries, which isn't something to change without syncing with whoever owns that code first.

Task 5 — Auto-update on upload
Previously, the graph only updated via a manual /graph/rebuild call. Now, ingesting a new document automatically compares it against existing documents and adds new edges immediately — verified live, confirmed working through the real ingestion path, not just in isolation.

Task 6 — API format + documentation
Documented the full Knowledge Graph API (endpoints, request/response shapes, relationship_type field) in docs/api-contracts.md, matching the format already used for Chatbot and Quiz Generation.

Notable bug found and fixed along the way
The LLM model used (openai/gpt-oss-20b) is a reasoning model — Groq bills its internal "thinking" tokens against max_tokens. At default settings, longer-output prompts (like generating a definition) could exhaust the entire token budget on reasoning and return empty content. Fixed by setting reasoning_effort="low" on all calls to this model.

Testing
25 automated tests passing, all isolated from the real database (a separate bug found earlier — tests were previously writing directly into the real shared ChromaDB collection). Verified end-to-end against real ingested documents throughout.

[vercel]

@usmanali434 is attempting to deploy a commit to the mrymfarid684-3634's projects Team on Vercel.

A member of the Team first needs to authorize it.