{"id":32352624,"url":"https://github.com/aaalgieee/sysdev-genkit-workshop","last_synced_at":"2026-05-15T18:03:12.813Z","repository":{"id":318520237,"uuid":"1068416196","full_name":"aaalgieee/sysdev-genkit-workshop","owner":"aaalgieee","description":"Build Smarter Systems with GenKit Workshop Repo for ADDU's SYSDEV Build Forward 2025","archived":false,"fork":false,"pushed_at":"2025-10-07T16:17:40.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-24T10:08:52.610Z","etag":null,"topics":["genkit","nextjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaalgieee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T10:56:20.000Z","updated_at":"2025-10-07T16:34:54.000Z","dependencies_parsed_at":"2025-10-07T18:31:15.158Z","dependency_job_id":"50900507-4eea-4eef-8ab2-e1e079439bc9","html_url":"https://github.com/aaalgieee/sysdev-genkit-workshop","commit_stats":null,"previous_names":["aaalgieee/sysdev-genkit-workshop"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/aaalgieee/sysdev-genkit-workshop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaalgieee%2Fsysdev-genkit-workshop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaalgieee%2Fsysdev-genkit-workshop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaalgieee%2Fsysdev-genkit-workshop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaalgieee%2Fsysdev-genkit-workshop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaalgieee","download_url":"https://codeload.github.com/aaalgieee/sysdev-genkit-workshop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaalgieee%2Fsysdev-genkit-workshop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33074399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genkit","nextjs"],"created_at":"2025-10-24T10:01:49.095Z","updated_at":"2026-05-15T18:03:12.808Z","avatar_url":"https://github.com/aaalgieee.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SysDev Genkit Workshop | SYSDEV BUILD FORWARD 2025\n\nA minimal Next.js (App Router) app demonstrating Google Genkit flows and tools to generate personalized study plans via an API route, featuring \"Francis the StudyMate\" - a friendly AI-powered study plan generator.\n\n## Tech Stack\n- Next.js 15.5.4 (App Router)\n- React 19.1.0\n- TypeScript\n- Tailwind CSS v4 (via @tailwindcss/postcss)\n- Genkit ^1.21.0 with `@genkit-ai/google-genai` and `@genkit-ai/compat-oai`\n- Biome 2.2.0 for linting/formatting\n- Support for multiple AI models (Google Gemini 2.0 \u0026 OpenAI GPT-4o)\n\n## Project Structure\n```\nsrc/\n  app/\n    api/\n      generate/\n        route.ts       # POST /api/generate → calls Genkit flow\n    globals.css         # Tailwind base\n    layout.tsx\n    page.tsx            # Simple UI to call the API\n  index.ts              # Genkit flows/tools exported for server usage\n\ngenkit.config.ts        # Genkit plugin configuration (googleAI)\nnext.config.ts\npostcss.config.mjs\npackage.json\n```\n\n## Getting Started\n1) Install dependencies\n```bash\nbun install\n# or\nnpm install\n# or\nyarn\n# or\npnpm i\n```\n\n2) Configure environment\n- Set API credentials for your chosen AI providers:\n  - `GOOGLE_GENAI_API_KEY` (for Google Gemini models via AI Studio)\n  - `OPENAI_API_KEY` (for OpenAI GPT models)\n  - Or authenticate with Google Cloud if using Vertex AI models\n\nFor local development, create a `.env.local` file:\n```bash\n# .env.local\nGOOGLE_GENAI_API_KEY=your_google_api_key_here\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\n**Note:** You only need the API key for the model provider you plan to use. The app supports:\n- Google Gemini 2.0 Flash (default)\n- Google Gemini 2.0 Flash Thinking\n- OpenAI GPT-4o Mini\n\n3) Run the development server\n```bash\nbun dev\n# or\nnpm run dev\n# or\nyarn dev\n# or\npnpm dev\n```\nOpen `http://localhost:3000` to view the UI.\n\n## Available Scripts\n```bash\nbun dev            # next dev --turbopack\nbun run build      # next build --turbopack\nbun start          # next start\nbun run genkit     # genkit start (local Genkit tools console)\nbun run lint       # biome check\nbun run format     # biome format --write\n```\n(Use your chosen package manager equivalents.)\n\n## Core Concepts\nThis project demonstrates comprehensive usage of Genkit's core features:\n\n### Prompts (ai.definePrompt)\nReusable prompt templates defined for Dev UI visibility:\n- **`studyTopicsPromptDef`**: Generates study topics with customizable topic count (3-10)\n- **`structuredStudyPlanPromptDef`**: Creates detailed study plans with difficulty-based guidance\n- Both prompts use variable interpolation with `{{variable}}` syntax\n- Helper functions (`studyTopicsPrompt`, `structuredStudyPlanPrompt`) for direct flow usage\n\n### Tools (ai.defineTool)\nModular tool definitions with Zod schema validation:\n- **`findEducationalLink`**: Platform-specific resource discovery\n  - Supports YouTube, Khan Academy, Coursera, or any platform\n  - Returns title, URL, and platform information\n- **`estimateStudyTime`**: Difficulty-based time calculations\n  - Returns hours/week and total weeks needed\n  - Adjusts for beginner/intermediate/advanced levels\n- **`generateQuizQuestions`**: Assessment question generation\n  - Creates multiple-choice, true-false, and short-answer questions\n  - Includes answers and explanations\n  - Configurable question count (1-10 per topic)\n\n### Flows (ai.defineFlow)\nThree production-ready flows with typed schemas:\n- **`studyPlanGenerator`**: Simple text-based topic list\n  - Input: subject, model (optional), topicCount (3-10)\n  - Output: Plain text bullet list\n- **`studyPlanGeneratorStructured`**: Structured JSON output\n  - Input: subject, model (optional), difficulty\n  - Output: JSON with topics array and educational resource\n  - Uses: `findEducationalLink` tool\n- **`enhancedStudyPlanGenerator`**: Advanced flow with time estimates\n  - Input: subject, difficulty, model (optional), includeTimeEstimates\n  - Output: Enhanced JSON with per-topic time estimates and totals\n  - Uses: `findEducationalLink`, `estimateStudyTime` tools\n\n### API \u0026 UI\n- **`src/app/api/generate/route.ts`**: REST endpoint with intelligent flow routing\n  - Supports all three flow modes\n  - Optional quiz generation via `generateQuizQuestions` tool\n  - Returns metadata about tools/prompts used\n- **`src/app/page.tsx`**: \"Francis the StudyMate\" - Interactive UI with:\n  - Flow mode selection (Simple/Structured/Enhanced)\n  - Multi-provider model selection (Google Gemini \u0026 OpenAI)\n  - Difficulty level selection\n  - Topic count slider (for simple mode)\n  - Advanced options: time estimates, quiz generation\n  - Real-time tool usage display\n  - Beautiful quiz UI with show/hide answers\n\n## API Documentation\n\n### POST /api/generate\n\n**Endpoint**: `/api/generate`\n\n**Request Parameters**:\n```typescript\n{\n  subject: string;              // Required: The subject to study\n  model?: string;               // Optional: AI model to use (default: \"googleai/gemini-2.0-flash-exp\")\n  difficulty?: \"beginner\" | \"intermediate\" | \"advanced\"; // Default: \"beginner\"\n  flowMode?: \"simple\" | \"structured\" | \"enhanced\"; // Default: \"structured\"\n  enhanced?: boolean;           // Enable enhanced mode (uses estimateStudyTime)\n  includeTimeEstimates?: boolean; // Include time estimates per topic\n  includeQuiz?: boolean;        // Generate quiz questions\n  topicCount?: number;          // Topic count for simple mode (3-10, default: 5)\n}\n```\n\n**Supported Models**:\n- `googleai/gemini-2.0-flash-exp` (default)\n- `googleai/gemini-2.0-flash-thinking-exp`\n- `openai/gpt-4o-mini`\n\n**Example Request**:\n```json\n{\n  \"subject\": \"World History\",\n  \"difficulty\": \"beginner\",\n  \"model\": \"googleai/gemini-2.0-flash-exp\",\n  \"flowMode\": \"enhanced\",\n  \"enhanced\": true,\n  \"includeTimeEstimates\": true,\n  \"includeQuiz\": true,\n  \"topicCount\": 5\n}\n```\n\n**Response Structure**:\nAll responses include:\n- `data`: The study plan (format depends on flow mode)\n- `quiz`: Array of quiz questions (if `includeQuiz: true`)\n- `meta`: Metadata about the generation\n  - `flowMode`: Which flow was used\n  - `toolsUsed`: Array of Genkit tools/prompts used\n\n**Response Examples**:\n\n**1. Simple Mode** (`flowMode: \"simple\"`):\n```json\n{\n  \"data\": {\n    \"text\": \"• Ancient Civilizations - Mesopotamia, Egypt, and early societies\\n• Classical Antiquity - Greece and Rome\\n• Medieval Period - Feudalism and the Middle Ages\\n• Renaissance and Reformation\\n• Modern Era - Industrial Revolution to present\"\n  },\n  \"quiz\": null,\n  \"meta\": {\n    \"flowMode\": \"simple\",\n    \"toolsUsed\": [\"studyTopicsPrompt\"]\n  }\n}\n```\n\n**2. Structured Mode** (`flowMode: \"structured\"`):\n```json\n{\n  \"data\": {\n    \"subject\": \"World History\",\n    \"difficulty\": \"beginner\",\n    \"topics\": [\n      \"Ancient Civilizations\",\n      \"Classical Antiquity\",\n      \"Medieval Period\",\n      \"Renaissance and Reformation\"\n    ],\n    \"resource\": {\n      \"title\": \"Introduction to World History\",\n      \"url\": \"https://www.youtube.com/results?search_query=World+History+tutorial\",\n      \"platform\": \"YouTube\"\n    }\n  },\n  \"quiz\": null,\n  \"meta\": {\n    \"flowMode\": \"structured\",\n    \"toolsUsed\": [\"structuredStudyPlanPrompt\", \"findEducationalLink\"]\n  }\n}\n```\n\n**3. Enhanced Mode with Time Estimates \u0026 Quiz** (`flowMode: \"enhanced\"`, `includeTimeEstimates: true`, `includeQuiz: true`):\n```json\n{\n  \"data\": {\n    \"subject\": \"World History\",\n    \"difficulty\": \"beginner\",\n    \"topics\": [\n      {\n        \"name\": \"Ancient Civilizations\",\n        \"estimatedTime\": {\n          \"hoursPerWeek\": 5,\n          \"totalWeeks\": 4\n        }\n      },\n      {\n        \"name\": \"Classical Antiquity\",\n        \"estimatedTime\": {\n          \"hoursPerWeek\": 5,\n          \"totalWeeks\": 4\n        }\n      }\n    ],\n    \"resource\": {\n      \"title\": \"Introduction to World History\",\n      \"url\": \"https://www.youtube.com/results?search_query=World+History+tutorial\",\n      \"platform\": \"YouTube\"\n    },\n    \"totalEstimatedHours\": 40\n  },\n  \"quiz\": [\n    {\n      \"topic\": \"Ancient Civilizations\",\n      \"questions\": [\n        {\n          \"question\": \"What were the main characteristics of Mesopotamian civilization?\",\n          \"type\": \"short-answer\",\n          \"answer\": \"Writing systems (cuneiform), irrigation, city-states, and polytheistic religion\",\n          \"explanation\": \"Mesopotamia developed key innovations including writing and complex irrigation systems.\"\n        },\n        {\n          \"question\": \"The Great Pyramid of Giza was built during which Egyptian kingdom?\",\n          \"type\": \"multiple-choice\",\n          \"answer\": \"Old Kingdom\",\n          \"options\": [\"Old Kingdom\", \"Middle Kingdom\", \"New Kingdom\", \"Ptolemaic Period\"],\n          \"explanation\": \"The Great Pyramid was built during the Old Kingdom (c. 2580-2560 BCE) under Pharaoh Khufu.\"\n        }\n      ]\n    }\n  ],\n  \"meta\": {\n    \"flowMode\": \"enhanced\",\n    \"toolsUsed\": [\n      \"structuredStudyPlanPrompt\",\n      \"findEducationalLink\",\n      \"estimateStudyTime\",\n      \"generateQuizQuestions\"\n    ]\n  }\n}\n```\n\n**Error Responses**:\n```json\n{ \"error\": \"Missing subject\" }       // 400 Bad Request\n{ \"error\": \"Internal Server Error\" } // 500 Server Error\n```\n\n## Genkit Features Demonstrated\n\nThis project showcases all major Genkit capabilities in a production-ready application:\n\n### 1. Multi-Provider Support\n✅ **Plugin Configuration** (genkit.config.ts):\n- `@genkit-ai/google-genai`: Google Gemini models\n- `@genkit-ai/compat-oai`: OpenAI models\n- Seamless model switching in UI\n\n### 2. Prompts (ai.definePrompt)\n✅ **Two reusable prompts with Dev UI integration**:\n- **`studyTopicsPromptDef`**: Topic generation prompt\n  - Variable interpolation: `{{subject}}`, `{{topicCount}}`\n  - Typed Zod schema for inputs\n  - Used in simple flow\n- **`structuredStudyPlanPromptDef`**: Structured plan creation\n  - Variables: `{{subject}}`, `{{difficulty}}`\n  - Difficulty-aware guidance\n  - Used in structured \u0026 enhanced flows\n\n### 3. Tools (ai.defineTool)\n✅ **Three production tools with full Zod validation**:\n- **`findEducationalLink`**: Educational resource finder\n  - Input: topic, preferredPlatform (enum)\n  - Output: title, URL, platform\n  - Supports YouTube, Khan Academy, Coursera\n- **`estimateStudyTime`**: Time estimation calculator\n  - Input: topic, difficulty level\n  - Output: hours/week, total weeks, description\n  - Returns realistic study time estimates\n- **`generateQuizQuestions`**: AI-powered quiz generator\n  - Input: topic, count (1-10), difficulty\n  - Output: array of questions with answers \u0026 explanations\n  - Supports multiple question types\n  - Uses nested AI generation\n\n### 4. Flows (ai.defineFlow)\n✅ **Three flows demonstrating progressive complexity**:\n\n**Simple Flow** (`studyPlanGenerator`):\n- Clean text output\n- Configurable topic count\n- Fast generation\n- Perfect for brainstorming\n\n**Structured Flow** (`studyPlanGeneratorStructured`):\n- JSON output with typed schema\n- Tool integration (`findEducationalLink`)\n- Difficulty-based content\n- Educational resource included\n\n**Enhanced Flow** (`enhancedStudyPlanGenerator`):\n- Advanced tool composition\n- Multiple tool calls (`findEducationalLink`, `estimateStudyTime`)\n- Conditional logic (time estimates on/off)\n- Rich metadata output\n\n### 5. UI Features\n✅ **Interactive \"Francis the StudyMate\" interface**:\n- **Flow Mode Selection**: Switch between Simple/Structured/Enhanced\n- **Model Selection**: Choose from 3 AI models (Google \u0026 OpenAI)\n- **Difficulty Levels**: Beginner/Intermediate/Advanced\n- **Topic Count Slider**: 3-10 topics (simple mode)\n- **Advanced Options Panel**:\n  - Enhanced mode toggle\n  - Time estimates toggle\n  - Quiz generation toggle\n- **Real-time Tool Display**: Shows which Genkit tools/prompts were used\n- **Beautiful Quiz UI**:\n  - Purple-themed design\n  - Show/hide answers per question\n  - Question type badges\n  - Explanations included\n\n### 6. Type Safety\n✅ **Full TypeScript integration**:\n- Zod schemas for all inputs/outputs\n- Type inference from flows\n- Shared types between client and server\n- Runtime validation\n\n## Development Notes\n\n### Architecture\n- **API Route**: `src/app/api/generate/route.ts` imports `genkit.config.ts` to register plugins (googleAI, openAI) before calling flows\n- **Genkit Instance**: Single shared instance in `src/index.ts` with both providers configured\n- **Type Safety**: Shared types exported from `src/index.ts` and used in both API and UI\n- **Flow Selection**: Intelligent routing based on `flowMode` parameter\n\n### Styling\n- **Tailwind CSS v4**: Configured via `@tailwindcss/postcss` in `postcss.config.mjs`\n- **Global Styles**: Custom theme variables in `src/app/globals.css`\n- **Dark Mode**: Full dark mode support with CSS variables\n- **Custom Classes**: Blue textile background pattern, brand color system\n\n### Code Quality\n- **Biome**: Used for linting and formatting (see `biome.json`)\n- **TypeScript**: Strict mode enabled with Next.js 15 config\n- **Early Returns**: Used throughout for better readability\n- **No any types**: All code fully typed with Zod schemas\n\n### Genkit Dev Tools\nRun `bun run genkit` (or `npm run genkit`) to launch the Genkit Developer UI:\n- Test flows interactively\n- View prompt definitions\n- Debug tool calls\n- Inspect generation traces\n\n## Troubleshooting\n\n### API Key Issues\n**Problem**: 401/403 errors or \"Invalid API key\"\n- **For Google models**: Verify `GOOGLE_GENAI_API_KEY` is set in `.env.local`\n  - Get your key from [Google AI Studio](https://makersuite.google.com/app/apikey)\n- **For OpenAI models**: Verify `OPENAI_API_KEY` is set in `.env.local`\n  - Get your key from [OpenAI Platform](https://platform.openai.com/api-keys)\n- **Check**: Ensure the selected model is accessible with your API key\n- **Note**: You only need the key for the provider you're using\n\n### Generation Failures\n**Problem**: `/api/generate` returns 500 error\n- **Check server logs**: Look at terminal running `bun dev` for detailed errors\n- **Verify request**: Ensure `subject` field is non-empty string\n- **Model availability**: Some models may have rate limits or regional restrictions\n- **Try different model**: Switch between Gemini and GPT models to isolate issues\n\n### Type Errors\n**Problem**: TypeScript errors after updates\n```bash\n# Clean install and rebuild\nrm -rf node_modules bun.lock\nbun install\nbun run lint\nbun run format\n```\n\n### Build Issues\n**Problem**: `next build` fails\n- **Clear cache**: `rm -rf .next`\n- **Check Turbopack**: Try without `--turbopack` flag if issues persist\n- **Verify imports**: Ensure all imports resolve correctly\n\n### Quiz Generation Issues\n**Problem**: Quiz questions not appearing or malformed\n- **Check model**: Some models handle structured output better (try Gemini 2.0 Flash)\n- **Verify topic**: Ensure topics are specific enough for meaningful questions\n- **Logs**: Check browser console and server logs for generation errors\n\n### UI Not Updating\n**Problem**: Changes not reflected in browser\n- **Hard refresh**: Ctrl+Shift+R (or Cmd+Shift+R on Mac)\n- **Clear cache**: Browser dev tools \u003e Network \u003e Disable cache\n- **Restart dev server**: Stop and restart `bun dev`\n\n### Genkit Dev UI Issues\n**Problem**: `bun run genkit` fails or shows no flows\n- **Check config**: Ensure `genkit.config.ts` exports default config\n- **Port conflicts**: Default port 4000 might be in use\n- **Rebuild**: Stop dev server, clear `.genkit/` folder, restart\n\n## Additional Resources\n- [Genkit Documentation](https://firebase.google.com/docs/genkit)\n- [Next.js 15 Docs](https://nextjs.org/docs)\n- [Tailwind CSS v4](https://tailwindcss.com/blog/tailwindcss-v4)\n- [Biome Linter](https://biomejs.dev/)\n- [Google AI Studio](https://makersuite.google.com/)\n- [OpenAI Platform](https://platform.openai.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaalgieee%2Fsysdev-genkit-workshop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaalgieee%2Fsysdev-genkit-workshop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaalgieee%2Fsysdev-genkit-workshop/lists"}