chore: runnable baseline (monorepo, seedable RAG, streaming fixes, tests, CI)

[Sal-Fakoya]

Makes AskTemoc runnable from one repo. A teammate clones it, picks a model provider (OpenAI or a local Ollama), seeds the vector store with one command, starts the API and the web app, and gets a streamed answer with sources at http://localhost:3000. No sign-in is needed. This is not the 10-week plan; anything left for that plan is listed in docs/KNOWN_ISSUES.md.

Merge with a merge commit, not squash. This branch brings in davis118/AskTemoc_Backend with git subtree, and squashing would flatten that history. It also contains 0415dde from fix/chat-streaming-markdown-and-docs, so that branch doesn't need its own PR.

What was tested

• Fresh clone on Windows, following the README quickstart. dev.ps1 setup, then seed (193 docs, 2047 chunks), then api and web.
• On the final branch state:
  • /chat loads with no sign-in.
  • POST /api/proxy/chat (the path the browser uses) streams 4 sources, the answer and done from the local API on Ollama.
  • GET /api/health works with and without the trailing slash.
• Tests: pytest passes 13 offline tests; npm run lint and npm run build pass. CI runs the same checks.
• Docker: docker compose up api comes up healthy, and seeding and chat work in the container.
• Not yet tested:
  • OpenAI. The test key's account had no credits, so the live checks ran on Ollama.
  • Answer quality. With llama3.1:8b, the BS CS question retrieves the right program page but its "Goals" and "Objectives" chunks rather than the course list, so the answer is weak. That's retrieval work for the 10-week plan.

What changed

1. One repo.
   • backend/ is AskTemoc_Backend main, added with git subtree and its full history.
   • The scraper moved to backend/scrapers/catalog/ and the scraped programs to data/catalog/. The backend had its own byte-identical copy of the catalog, which is removed; its housing pages moved to data/housing/ and aren't seeded.
   • backend/app/.env is untracked.
   • requirements.txt is now UTF-8 and holds only the pinned runtime set. Scraping packages are in requirements-scrape.txt and test tools in requirements-dev.txt.
2. Backend runs on a clean clone.
   • All settings go through app/core/config.py (pydantic-settings), and validation errors never echo setting values such as API keys.
   • The retriever and chain are built on first use, so importing the app never touches Chroma, OpenAI or Ollama.
   • /api/health answers with or without the trailing slash.
   • /api/chat streams answer pieces with astream instead of cumulative prefixes, then a final done event. The frontend appends the pieces, also accepts the older delta event shape, and ignores unknown types.
   • CORS origins come from CORS_ORIGINS.
   • backend/scripts/seed_catalog.py can be re-run safely and cites real catalog URLs from data/catalog/sources.json, which was generated once with the scraper's own link discovery.
   • The route collisions described in the original brief don't exist (every router has a prefix). A test now guards against duplicate routes.
3. Frontend talks to the local API. The /api/proxy/* rewrites and NEXT_PUBLIC_API_BASE_URL are unchanged from before, except that next dev now proxies to http://localhost:8000 by default. Production builds still use Cloud Run from .env.production and vercel.json.
4. Dev experience, tests, CI. docker-compose.yml (with optional Ollama), scripts/dev.sh / scripts/dev.ps1 plus a Makefile, the backend pytest suite, and .github/workflows/ci.yml.
5. Docs. A root README.md and docs/KNOWN_ISSUES.md.

Auth work

Sign-in isn't part of the baseline; it's a teammate's assignment in Weeks 2-4 of the 10-week plan. An implementation was built here and then removed with git revert:

• Auth.js with Microsoft Entra ID and Google, limited to @utdallas.edu.
• 5-minute HS256 tokens minted by the Next server and verified by the API.
• A users table and an AUTH_DISABLED dev escape hatch.

It's preserved on reference/auth-oauth (at 4a162a7), which also has its tests and docs/AUTH_SETUP.md.

Original commit	Reverted by
4f9c7fd feat(web): UTD sign-in with Auth.js and authenticated API proxy	7216e18
23a0f07 feat(api): require signed bearer token on /api/chat, persist users	9a22e04

To restore it, revert the reverts (newest first):

git revert 9a22e04 7216e18

The API half reapplies cleanly. The web half stops with conflicts in frontend/next.config.ts, frontend/src/lib/api.ts and frontend/.env.example (checked with a dry run), because they changed after the reverts; resolve them, then run git revert --continue. The auth tests and docs/AUTH_SETUP.md were removed in separate commits; bring them back with:

git checkout reference/auth-oauth -- backend/tests docs/AUTH_SETUP.md

Merging reference/auth-oauth will NOT bring auth back. Its commits are already in this branch's history, so git considers them merged and the reverts win.

Before merging

• CI passes on this PR.

Before the next Cloud Run deploy

• Confirm which AskTemoc_Backend branch production runs. The deployed API's streaming format matches the speedrun branch (12 commits ahead of main: a [n, "verbatim"] citation prompt, lower temperature, and delta plus cumulative message events), not main, which is what this PR imports.
• If it's speedrun, port its citation prompt and streaming changes in a follow-up PR first. Otherwise the next deploy silently drops the citation links in answers. The frontend already accepts both streaming formats.

What still has to be done by hand

• Give the OpenAI account credits (and rotate the key), then re-seed with OPENAI_API_KEY set.
• Archive davis118/AskTemoc_Backend, or point its README here, after this merges.

Deployment notes

Vercel (frontend): no new variables. ASKTEMOC_API_ORIGIN is committed in vercel.json and .env.production. Until app-level sign-in exists, keep Vercel Deployment Protection on.

Cloud Run (API)

Variable	Value
ENVIRONMENT	production
OPENAI_API_KEY	key with billing enabled
CORS_ORIGINS	https://<vercel domain>
DATABASE_URL	database connection URL
CHROMA_PERSIST_DIRECTORY	on persistent storage, then run python scripts/seed_catalog.py

The API has no authentication, so anyone with its URL can call it. See docs/KNOWN_ISSUES.md.

🤖 Generated with Claude Code