[!NOTE]
Polya is live at askpolya.com and in active development. Today each student chooses the study mode for their own courses. Instructor accounts and instructor-set rules are planned, not built. The screenshots in this README come from the real app, run locally with sample course data, and the tutor replies in them are hand-written samples, not model output.
Polya is named for George Pólya, whose How to Solve It taught problem solving through questions. It is the tutor in Scope, the course workspace. Company direction lives in ../scope-docs/ROADMAP.md. Polya is free for students.
Why
Students already use AI for coursework. A general chatbot doesn't know what their class actually covers, and its default is to finish the work rather than build understanding. Polya starts from the course itself. It answers from the class's own materials, shows where each claim came from, and follows a help ladder: a hint first, then one step, then a worked example of a similar problem, and the full explanation only when that serves the learning.
See it work
Recorded from the real app UI running locally against a stand-in backend loaded with the repo's sample course (fixtures/demo-course/). The two replies are hand-written samples, shaped by the tutor's system prompt and streamed through the app's real streaming protocol. They are not live model output.
How it works
All screenshots: the real app UI, run locally against a stand-in backend with sample data. Bio 1A (demo) is the repo's synthetic fixture course, and the other course names, the student, and the exam are placeholders.
Beyond the website
- Polya on iMessage (
imessage/): students text Polya for help under the same study modes, and get check-ins about upcoming and newly graded assignments and reminders for exams they added in Study. It is a separate deployable built on the eve agent framework.
- Open in Polya from Scope: the Scope browser extension can hand a signed-in student straight to Polya (
polya-handoff).
- Gradescope and Google Drive: students can connect Gradescope for submission-aware reminders, and a course file shared only inside the school's Google domain can be read through the student's Drive grant (
docs/DRIVE-SETUP.md).
Design decisions
- Course files are data, not instructions. Retrieved passages reach the model inside an explicitly untrusted wrapper, and any text in a course file that would close or forge that wrapper is neutralized first (
supabase/functions/_shared/prompts.ts). A PDF can't rewrite the tutor's rules.
- Cite only what the evidence supports. The tutor may cite
[n] only from the numbered evidence it was given, and says so when the course doesn't cover a question. Location labels claim only what can be opened: an untimed transcript is a "transcript passage", never a moment.
- Rules enforced below the prompt where it matters. Practice mode drops answer-key material at the SQL level, so the tutor never sees it, rather than relying on an instruction to hold it back.
- Hybrid retrieval, grouped results. Search runs pgvector similarity and Postgres full-text search per course and fuses them with Reciprocal Rank Fusion. Neighboring passages are merged, and a hit on one step of a numbered method pulls in the whole method, so the professor's procedure comes back intact.
- Secrets stay server-side. Canvas access tokens are encrypted at rest (AES-256-GCM) in a table that signed-in users can't read at all, and only edge functions touch them. Model API keys live only in edge-function environments.
- Careful fetching. Course-website crawls require HTTPS and a public host on every redirect hop, honor
robots.txt, and cap size, page count, and time.
Details are in docs/ARCHITECTURE.md. Some of its roadmap items, such as OCR and Kaltura transcripts, have since been built.
Architecture
flowchart LR
student(["Student browser"]) --> app["Next.js app (this repo)<br>pages · /mcp endpoint · OAuth consent"]
assistant(["Claude or ChatGPT"]) -- "MCP + OAuth 2.1" --> app
phone(["iMessage"]) --> imsg["imessage/<br>eve agent"]
app -- "student session, RLS" --> db[("Supabase<br>polya_* tables + pgvector<br>polya_documents storage")]
app -- "invoke / stream" --> fns["Edge functions (Deno)<br>polya-canvas · polya-import · polya-tutor<br>polya-search · polya-study · polya-coach<br>polya-google · polya-handoff"]
imsg --> db
imsg --> fns
fns --> db
fns --> sources["Canvas · course websites<br>Kaltura · Google Drive"]
fns --> models["Claude Sonnet 5: tutor, study, coach<br>Claude Haiku 5.5: OCR, iMessage agent<br>Gemini: embeddings"]
imsg --> models
The backend is the shared Scope Supabase project. Polya owns only polya_-prefixed tables, functions, and storage.
| Folder | What it holds |
|---|
src/app/ | Routes: the landing and marketing pages, /app (courses, chat, Study, materials), /connect (Gradescope, iMessage linking), and /mcp with its OAuth metadata routes |
src/components/ | UI: chat and source viewer, exam coach, import flow, study-mode panel |
src/lib/ | Client and server helpers; src/lib/mcp/ holds the connector's three read-only tools |
supabase/functions/ | Deno edge functions; _shared/ holds runtime-agnostic logic that the Node tests import |
supabase/migrations/ | The polya_ schema |
imessage/ | Polya on iMessage, deployed separately |
fixtures/ | The self-authored demo course and Canvas API fixtures, the only committed course content |
scripts/ | Fixture seeding, retrieval and study evals, the import integration test |
|
Tests and evals
- Unit tests.
npm test runs 521 tests over the shared logic: chunking, retrieval fusion, prompt assembly, prompt-injection handling, token encryption, crawl policy, study grading, and the MCP connector. npm test in imessage/ runs that agent's 363 tests. Both passed on October 26, 2026.
- Retrieval eval.
npm run eval sends the four golden questions in scripts/eval/golden-set.json through course search and fails below recall@5 of 0.8. docs/DEMO.md records recall@5 = 1.00 and MRR = 1.000 against the synthetic demo course. Four questions over five documents show that the pipeline works end to end. They don't measure retrieval quality on real courses.
- Study eval.
npm run eval:study counts how many generated practice questions pass the automatic answer-key checks, and writes the kept questions out for a person to check by hand. No result is recorded in the repo.
- Import integration test.
npm run test:integration runs a full Canvas import against the local Supabase stack and a mock Canvas server. Its setup steps are in the header of scripts/integration/run-import-integration.ts.
Run it
You need Node.js 22.6 or later (the iMessage agent needs Node 24), npm, and the Supabase CLI for local database work.
npm install
cp .env.template .env.local # defaults already point at the shared project
npm run dev # http://localhost:3000
The defaults point at the shared Scope Supabase project, so a dev server signed in with a real account reads and writes real data. For isolated work, run the Polya-only local stack with supabase start and supabase db reset, and point NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY at it. To load the sample course into a backend, use npm run seed:fixture; docs/DEMO.md lists its environment variables.
Checks: npm run lint · npm run typecheck · npm test · npm run eval.
[!WARNING]
Never run supabase db push, supabase db reset --linked, supabase migration repair, or supabase db pull against the linked project from this repo. Three repos share its migration history. Remote changes go through the process in CLAUDE.md.
Read first
Known limitations
- Students set each course's study mode themselves. There are no instructor accounts, assignment-level rules, or timed solution release yet.
- Connecting Canvas means pasting a Canvas access token. There is no LTI 1.3 install or institution admin, and Brightspace isn't supported.
- The Canvas address check is hostname-pattern filtering only, with no DNS-rebinding defense, as
docs/ARCHITECTURE.md notes.
- Course-website crawls stop at 120 pages, 40 PDFs per page, and 45 seconds, so a large site may import partly.
- The only recorded retrieval eval covers four questions on a five-document synthetic course.
Credits
Built and run by Noel Jubil Sason as part of Scope.
