@vibe-edu/sdk
v0.3.0
Published
Agentic K-8 education SDK for vibe-coding tools (Cursor, v0, Lovable). BYOK, schema-enforced slides, quizzes, and curriculum.
Maintainers
sdommeti0Readme
@vibe-edu/sdk
Agentic K-8 education toolkit for vibe-coding tools (Cursor, v0, Lovable). Bring your own LLM key. Schema-enforced slides, quizzes, and curriculum.
One npm install. Drop in
vibe-edu.cursorrules. Prompt your way to a working lesson app in minutes.
Docs
Full reference lives in /docs:
- docs/llm-guide.md — one-page LLM cheatsheet
- docs/endpoints/ — per-endpoint input/output reference
- docs/schemas.md — all output types
- docs/client.md —
EduClienttyped HTTP client - docs/errors.md — typed
EduErrorclasses - docs/retry.md — retry / rate-limit policy
- docs/instrumentation.md —
onEventhook - docs/caching.md —
EduCache/MemoryCache - docs/batch.md —
generateMany/searchMany - docs/auth.md — API-key + HMAC helpers
- docs/versioning.md — semver policy
- docs/openapi.yaml — machine-readable spec
- examples/ — Express, Hono, plain Node, batch, cache, auth, instrumented
- fixtures/ — sample valid outputs for mocking
- CHANGELOG.md
- docs/sdk-hardening-roadmap.md — what's next
Why
LLM-driven editors regularly hallucinate API shapes and dump brittle fetch
calls into your codebase. @vibe-edu/sdk gives the AI one API surface to
target, strict zod schemas for every output, and headless React hooks
that handle loading / error / data states. Your UI prompt stays focused on
look-and-feel.
Install
npm install @vibe-edu/sdkFirst-time setup (non-coders welcome)
npx vibe-edu initWalks you through getting API keys for Anthropic / OpenAI (required),
Firecrawl (optional, for scraping any URL), and OER Commons (optional,
institutional). Each step links to the signup page and explains what to do.
Writes a .env.local you can keep using forever.
After setup, try:
npx vibe-edu generate quiz --topic "Photosynthesis" --grade 3 --traceQuickstart (server)
import { EduSDK } from '@vibe-edu/sdk';
const edu = new EduSDK({
llmKey: process.env.OPENAI_API_KEY!,
llmProvider: 'openai', // or 'anthropic'
firecrawlKey: process.env.FIRECRAWL_API_KEY, // optional, enables fromUrl()
oerKey: process.env.OER_COMMONS_KEY, // optional
});
const deck = await edu.slides.generate({
topic: 'History of Columbus, Ohio',
gradeLevel: 4,
slideCount: 5,
visuals: true,
});
const quiz = await edu.quizzes.generate({
topic: 'The Water Cycle',
gradeLevel: 3,
questionCount: 5,
format: 'multiple_choice',
});
const courses = await edu.courses.search({
subject: 'Earth Science',
gradeLevel: 4,
source: 'oer_commons',
});Quickstart (Next.js + React hooks)
1. Server route — app/api/edu/[...action]/route.ts:
import { EduSDK } from '@vibe-edu/sdk';
const edu = new EduSDK({
llmKey: process.env.OPENAI_API_KEY!,
llmProvider: 'openai',
firecrawlKey: process.env.FIRECRAWL_API_KEY,
});
export async function POST(req: Request, { params }: { params: Promise<{ action: string[] }> }) {
const { action } = await params;
const body = await req.json();
switch (action.join('/')) {
case 'slides': return Response.json(await edu.slides.generate(body));
case 'slides/from-url': return Response.json(await edu.slides.fromUrl(body));
case 'quiz': return Response.json(await edu.quizzes.generate(body));
case 'quiz/from-url': return Response.json(await edu.quizzes.fromUrl(body));
case 'course': return Response.json(await edu.courses.search(body));
}
return new Response('Not found', { status: 404 });
}2. Wrap your app — app/layout.tsx:
import { EduProvider } from '@vibe-edu/sdk/react';
export default function Root({ children }) {
return <html><body><EduProvider>{children}</EduProvider></body></html>;
}3. Use the hook:
'use client';
import { useEduSlides } from '@vibe-edu/sdk/react';
export default function Lesson() {
const { slides, isLoading, error } = useEduSlides({
topic: 'History of Columbus, Ohio',
gradeLevel: 4,
});
if (isLoading) return <div className="animate-pulse">Synthesizing lesson…</div>;
if (error) return <div className="text-red-500">{error.message}</div>;
return (
<div className="grid gap-4">
{slides?.map((s) => (
<article key={s.id} className="rounded-2xl border p-6">
<h2 className="text-xl font-bold">{s.title}</h2>
<ul className="list-disc pl-5">{s.bullets.map((b) => <li key={b}>{b}</li>)}</ul>
<p className="mt-3 text-sm text-neutral-500">{s.speakerNotes}</p>
</article>
))}
</div>
);
}CLI
npx vibe-edu init # one-time setup
npx vibe-edu generate slides --topic "Photosynthesis" --grade 3 --visuals --out deck.json
npx vibe-edu generate quiz --topic "The Water Cycle" --grade 3 --count 5 --out quiz.json
npx vibe-edu generate course --subject "Earth Science" --grade 4 --source oer_commons--trace flag
Add --trace to any generate call (or trace: true to the SDK options)
to attach provenance metadata:
meta.source— which API the source text came from (Wikipedia URL, Firecrawl URL, etc.)meta.provider/meta.model— which LLM produced the outputmeta.generatedAt— ISO timestamp- Per item:
sourcePassage— a verbatim quote (≤40 words) from the source that grounds the question or slide
Use this for auditing AI output against ground truth before publishing to students.
Schemas
All outputs are validated by zod. The AI literally cannot return a malformed shape.
| Module | Schema | Key fields |
| --- | --- | --- |
| edu.slides | SlideDeck | topic, targetGrade, slides[] |
| edu.quizzes | Quiz | topic, targetGrade, format, questions[] |
| edu.courses | CourseSearchResult | query, results: Course[] |
Slide: id, title, bullets[], speakerNotes, visualCue, imagePrompt?
Question: id, prompt, format, choices[], correctAnswerIndex, explanation
Course: title, subject, targetGrade, description, modules[], source, sourceUrl?
For Cursor / v0 / Lovable
Copy vibe-edu.cursorrules (shipped in the package root) into your project as
.cursorrules. It teaches the model exactly how to wire up server routes,
the provider, and the hooks — and what not to do.
Environment variables
| Var | Purpose | Required |
| --- | --- | --- |
| OPENAI_API_KEY | LLM key when llmProvider: 'openai' | yes (one of) |
| ANTHROPIC_API_KEY | LLM key when llmProvider: 'anthropic' | yes (one of) |
| FIRECRAWL_API_KEY | Enables fromUrl() scraping | no |
| OER_COMMONS_KEY | Institutional OER Commons API key | no |
Architecture
Aggregator → Synthesizer → Presentation
(Wiki/ → (Vercel AI → (CLI + React
Firecrawl/ SDK + zod) hooks)
OER)Tier 1 pulls raw text. Tier 2 calls your LLM with a schema-locked
generateObject and a grade-tuned system prompt. Tier 3 hands you typed data.
License
MIT