Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TEACHER.EXE

Study companion for chatting with sources, saving study material, and generating quizzes from your own documents and approved web sources.

Live: https://ai-studying.arshaan-bhimani.workers.dev/

What It Does

  • Chat with an AI study agent powered by OpenAI and Cloudflare AIChatAgent.
  • Attach images, PDFs, and plain text files by clicking, dragging, or pasting.
  • Use images and documents once in the current chat, or shelve PDFs and text files into the study library.
  • Ingest saved documents into R2, D1, and Vectorize for later retrieval.
  • Ask the agent to create 10-question multiple-choice quizzes from saved source material.
  • Review past quizzes in the quiz archive.
  • Search for supplemental web sources with Exa, review the candidates, then approve which ones get saved.

Architecture

  • front-end/ is a Next.js 16 app exported as static assets for Cloudflare Workers.
  • back-end/server.ts routes auth, document, quiz, asset, and agent requests.
  • ChatAgent extends AIChatAgent for persisted, resumable WebSocket chat.
  • Better Auth stores users, accounts, sessions, and verification records in D1.
  • R2 stores uploaded study documents.
  • Queues and DocumentIngestionWorkflow process R2 object-created events asynchronously.
  • unpdf extracts PDF text; text is chunked, embedded with text-embedding-3-small, and stored in Vectorize.
  • D1 stores document metadata, document chunks, quizzes, and staged web-source candidates.
  • shared/quiz.ts defines the shared Zod schemas used by both the Worker and frontend.

Quick Start

npm install
npm run dev

Open http://localhost:3000.

npm run dev starts the Cloudflare Worker on port 8787 and the Next.js frontend on port 3000. During local development, the frontend proxies /api/*, /agents/*, and /oauth/* to the Worker. It also rewrites quiz detail pages to the exported quiz page.

Environment Variables

Create a .dev.vars file for local development:

OPENAI_API_KEY=your-openai-key
BETTER_AUTH_SECRET=your-local-secret
BETTER_AUTH_URL=http://localhost:3000
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
EXA_API_KEY=your-exa-key

EXA_API_KEY is only required for supplemental web-source search.

For deployed Workers, set secrets with Wrangler:

npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put BETTER_AUTH_SECRET
npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
npx wrangler secret put EXA_API_KEY

Set non-secret deployed values in wrangler.jsonc or the Cloudflare dashboard:

  • BETTER_AUTH_URL
  • BETTER_AUTH_TRUSTED_ORIGINS
  • CLOUDFLARE_ACCOUNT_ID

Cloudflare Resources

The deployed Worker is configured in wrangler.jsonc and expects:

  • D1 database: ai-studying
  • R2 bucket: ai-studying-documents
  • Vectorize index: ai-studying-documents
  • Queue consumer: ai-studying-document-events
  • Workflow: ai-studying-document-ingestion
  • Durable Object binding: ChatAgent
  • Static assets served from front-end/out

Apply remote D1 migrations after provisioning or changing schema:

npm run db:migrations:apply

Configure R2 CORS with r2-cors.json so browser uploads can PUT directly to presigned R2 URLs. The R2 bucket should publish object-created events to the queue configured in wrangler.jsonc.

Run type generation after changing Worker bindings:

npm run types

Scripts

Command Purpose
npm run dev Start the Worker and frontend dev servers
npm run dev:back-end Start only Wrangler on port 8787
npm run dev:front-end Start only the Next.js frontend
npm run build Build the exported frontend
npm run deploy Build the frontend and deploy the Worker
npm run check Run formatting check, backend lint, TypeScript, frontend lint, and frontend build
npm run lint Run backend and frontend lint
npm run format Format the repo with oxfmt
npm run types Generate Worker Env types
npm run db:migrations:list List remote D1 migrations
npm run db:migrations:apply Apply remote D1 migrations
npm run stores:clear Clear remote D1, R2, and Vectorize app data

Project Structure

back-end/
  auth.ts                         # Better Auth setup and session helpers
  documents.ts                    # document upload, ingestion, chunking, retrieval
  quizzes.ts                      # quiz list/detail API and persistence
  server.ts                       # Worker entrypoint, agent, routing, queue handler
  tools/
    create-quiz.ts                # AI SDK tool for quiz persistence
    query-storage.ts              # AI SDK tool for Vectorize-backed retrieval
    supplemental-sources.ts       # Exa search and approved web-source ingestion
front-end/
  src/app/                        # Next.js App Router UI
  src/app/components/chat/         # chat surface and attachment handling
  src/app/components/quiz/         # quiz taking UI
  src/app/components/auth/         # account controls and sign-in UI
migrations/                       # D1 schema migrations
shared/
  quiz.ts                         # shared quiz schemas and types
scripts/
  clear-stores.mjs                # remote data reset helper
wrangler.jsonc                    # Cloudflare Worker and binding configuration

Roadmap

  • different types of questions can be asked in the quizzes
    • text, voice, short-answer, long-answer
    • has to be able to grade the answer provided
  • can re-test yourself throughout the day and be asked a varied set of questions
  • calculate a score for how well you're doing
    • allow score to be associated with a subject area
  • allow for easy, medium and hard questions
  • cron job daily quiz
  • allow for context from web search from good quality sources
  • Images should not remain chat-only. What are our options for inferring the text and visuals and whastever else is on an image and using that?
  • To dedupe documents uploaded, store file hash maybe SHA-256 and for same user + same document we should re-use old document.
  • Harden document ingestion dedupe: atomically claim unprocessed documents in D1 before starting the Workflow, so duplicate R2 queue events cannot race.
  • Require auth before issuing document upload URLs.
  • auto-deploy later, we can add a GitHub Actions workflow that runs on push to main
  • explanation can be enhanced i.e. for why it's b) and not c)
  • assessing texts to read
  • For production robustness, I’d move web-source ingestion into a workflow before this gets heavy use.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages