README.md

---
title: AIUniversityFinder
emoji: 🎓
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860
---

# AIUniversityFinder Panel

An AI college and university finder for **high school seniors** and **mid-career / adult learners** (including online and hybrid paths). Built on Neon AI's Collaborative Conversational AI (CCAI) framework. Ask about fit, net price, accommodations, transfer credit, and admissions timelines — and get diverse perspectives from a panel of five advisors.

This repository is a **complete, deployable application** — the CCAI multi-advisor stack (FastAPI backend + React frontend) wired to the AIUniversityFinder configuration in [`university_finder_config.yaml`](university_finder_config.yaml) and the personas in [`personas/university_advisors/`](personas/university_advisors).

## Live links

| Resource | URL |
|----------|-----|
| GitHub | https://github.com/NeonKennedy-005/AIUniversityFinder-Panel |
| Hugging Face Space | https://huggingface.co/spaces/BrainForge/AIUniversityFinder |

> If the Space URL 404s, create `BrainForge/AIUniversityFinder` (Docker SDK) in the HF UI, then push the `hf` remote (see below).

## Advisors

1. **College Fit Strategist** — goals, modality, campus vs online, culture, life stage
2. **Financial Aid Navigator** — tuition, net price, scholarships, FAFSA/aid, ROI, employer tuition benefits
3. **Accessibility & Accommodations Advisor** — Disability Services, housing/ADA, learning supports
4. **Adult & Online Learner Coach** — transfer credit, flexible programs, prior learning, work–life balance
5. **Admissions Roadmap Planner** — timelines, essays, visits/virtual tours, deadlines

## Path gate + guest mode

- First-run **path gate**: High school / traditional vs Returning adult / online (steers advisors via profile `cyber_role`)
- **Try without an account** creates a disposable guest session with EmailStr-safe addresses like `guest-…@guests.aiuniversityfinder.ai`

## Hugging Face Spaces deployment

This Space ships as a single Docker image built from the repository-root [`Dockerfile`](Dockerfile). The container:

1. Builds the React frontend (CRA) at image-build time with `REACT_APP_API_URL=""` so every `fetch` issues a relative URL.
2. Serves the bundled SPA from FastAPI at `/`, with the API on `/api/...`, `/auth/...`, etc. — all on the same `:7860` origin.
3. Persists user data (auth, profiles, chat sessions) in **SQLite via `aiosqlite`** at `${DATA_DIR}/aiuniversityfinder_panel.db`. Mount a Hugging Face Storage Bucket at `/data` to make the database survive Space rebuilds. There is **no MongoDB** and no third-party data plane.

### Required Space secrets

| Secret | Purpose |
|--------|---------|
| `JWT_SECRET_KEY` | Signs auth tokens. Set this to a long random string. |
| `OPENAI_API_KEY` | Powers the default OpenAI provider (`gpt-5.4-mini`). |
| `GEMINI_API_KEY` | Optional — only if you switch `llm.provider` back to `gemini`. |

Set these under **Settings → Variables and secrets** on the Space.

## Local deployment

### Option A — Docker

```bash
# From the repo root, create a .env with at least:
#   JWT_SECRET_KEY=some-long-random-string
#   OPENAI_API_KEY=your-openai-key
docker compose up --build
```

Open <http://localhost:7860>. Override the host port with `UNIVERSITY_FINDER_HOST_PORT` if 7860 is taken.

### Option B — Native (no Docker)

**Backend** (terminal 1):

```bash
cd multi_llm_chatbot_backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
CONFIG_PATH=../university_finder_config.yaml uvicorn app.main:app --reload --port 8000
```

**Frontend** (terminal 2):

```bash
cd phd-advisor-frontend
npm install
REACT_APP_API_URL=http://localhost:8000 npm start
```

Open <http://localhost:3000> — you should see **AIUniversityFinder** with five college advisors.

## Configuration

App UI, login fields, chat examples, orchestrator keywords, and LLM/RAG settings live in [`university_finder_config.yaml`](university_finder_config.yaml). The five advisor YAMLs in `personas/university_advisors/` load automatically. Point the app at a different config with `CONFIG_PATH`.

The workshop draft that generated this panel is saved as [`advisor-panel-draft.json`](advisor-panel-draft.json).

## Brand

Calm academic **cyan / blue-teal** (`#0E7490`) with soft sky surfaces — approachable and readable, not purple-AI cliché.