README.md

metadata

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 and the personas in 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. 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

# 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):

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):

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. 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.

Brand

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