# Knowledge Base — what's verified, what isn't

This document explains exactly what the Companion can confidently answer, what
it deflects to official sources, and how to grow the knowledge base safely.

Last reviewed: 2026-05-25.

## Architecture in one paragraph

The Companion answers from two retrieval sources combined in
`retrieval_engine_extended.py`:

1. **`alu_brain/*.json`** — curated, hand-written Q&A entries loaded into
   memory at app startup by `ALUBrainManager`. Edit these by editing the JSON
   files and restarting the Space.
2. **`data/vectordb/` (ChromaDB)** — chunks from documents you upload through
   `POST /api/documents/upload`. Edit by uploading or deleting documents
   through the frontend Documents page.

Both sources are pulled into context, ranked, and given to Claude
(`claude_engine.py`). Claude's system prompt is strict: it must not invent
specifics like course codes, fees, or names — when context is silent, it
points the student at the official ALU source.

## Verified knowledge files (in `alu_brain/`)

These were rewritten on 2026-05-25 to contain only information that can be
verified against `alueducation.com` or other authoritative sources. Each entry
includes official URLs.

| File | Covers |
|------|--------|
| `about_alu.json` | History, mission, founding, campuses, accreditation, official channels |
| `academic_programs.json` | BSc programmes (names only), curriculum model, duration, declaration process |
| `admissions.json` | How to apply, requirements, deadlines (deferred to live page), transfers |
| `financial_information.json` | Tuition (deferred to admissions team), scholarships, Mastercard Foundation, payment process |
| `campus_life.json` | Kigali and Mauritius campuses, housing, wellbeing, clubs |
| `student_resources.json` | Support portal, contacts, IT help, new-student priorities, safeguarding |
| `career_services.json` | Career model, internships, alumni network, entrepreneurship |

**What these files deliberately DO NOT contain:**

- Specific dollar/euro tuition amounts
- Course codes (LEAD101, COMM101, etc.)
- Credit-hour breakdowns
- Faculty names or titles
- Current-term dates or examination schedules
- Student enrolment statistics

These change every intake or are not publicly published. The Companion is
instructed to deflect those questions to official channels rather than guess.

## Quarantined files (in `alu_brain/_quarantine_unverified/`)

These were inherited from an earlier build of the chatbot and contain
unverifiable claims (specific course codes, faculty rosters with 47 names,
made-up statistics, exact dollar amounts). They are excluded from the brain
loader because `_quarantine_unverified/` is not scanned by
`ALUBrainManager.load_brain()` — only files directly in `alu_brain/` are
loaded.

Quarantined:

- `academic_policies.json`
- `faculty.json` (the 53KB "47 faculty members" file)
- `graduation.json`
- `learning_coach.json`
- `library_resources.json`
- `comprehensive_knowledge.json` (180KB)
- `visual_resources.json`

**To re-activate any of these**, first verify the content against a real ALU
source, then move it back to `alu_brain/` and add `"last_reviewed": "YYYY-MM-DD"`
at the top of the JSON.

## The `data/alu_knowledge/` directory

This directory is read separately by the vector indexing pipeline (not by
`ALUBrainManager`). It contains:

- `academic_calendar.json` — looks like real ALU calendar data (specific dated
  terms for 2024-2025). **Please visually verify** these dates match the
  official ALU calendar; if not, move to a `_quarantine/` subfolder.
- `alu_ultimate_knowledge_base.txt` — 61KB of dated calendar and policy info.
  **Same — please verify** before relying on it. If real, it's gold; if not,
  it's another source of confident lies.
- `spd_hub_info.json` — points to `spdhub.alueducation.com`, a real ALU
  subdomain. Safe.

## How to add new verified knowledge

Two paths, both safe.

### Path A — Add to a `alu_brain/*.json` file

Best for short, structured Q&A like "What is the application process?" or
"Where is the Kigali campus?".

1. Open the relevant file (or create a new category file).
2. Add an entry following the existing schema:
   ```json
   {
     "id": "category_XXX",
     "type": "long_response",
     "question": "...",
     "answer": "...",
     "links": [{ "text": "...", "url": "https://..." }]
   }
   ```
3. Update `"last_reviewed"` at the top of the file.
4. Commit and push. The Space restarts and reloads automatically.

### Path B — Upload a real ALU document (recommended for depth)

Best for long, authoritative content like the student handbook, fee schedule,
or academic catalog.

1. Sign in to the Companion frontend.
2. Go to the Documents page.
3. Upload the PDF/DOCX/TXT.
4. The backend extracts text, chunks it, embeds it, and indexes it into
   ChromaDB. From the next chat onward, Claude has access to the document's
   content as retrieval context.
5. Citations in answers will reference the document title.

This is the proper path to deep, real knowledge. Verified hand-written JSON
gives the Companion a solid floor; uploaded documents give it the ceiling.

## Editing policy — when to update

- **At each new intake cycle** — review `admissions.json` and
  `financial_information.json` for any general guidance that has changed.
- **When ALU publishes new official information** — link to it from the
  relevant entry.
- **Never** add a specific number (fee, deadline, statistic) without a URL
  in the same entry that backs it up.

## Auditing — how to spot lies

If a student tells you the Companion gave wrong information:

1. Ask which question they asked.
2. Search the `alu_brain/*.json` files for keywords from the answer — that's
   probably the source.
3. If the JSON is wrong, fix it.
4. If the JSON is silent but Claude still made something up, the system
   prompt needs to be tightened further — open `claude_engine.py` and add
   the specific failure mode to the "NEVER invent" list.

## Contact

For ALU-specific information that genuinely is public and authoritative but
not yet in the knowledge base, the right move is almost always to add it
yourself with the URL — not to ask Claude to "know more".