diff --git a/js/testapps/basic-gemini/README.md b/js/testapps/basic-gemini/README.md new file mode 100644 index 0000000000..6a93657c14 --- /dev/null +++ b/js/testapps/basic-gemini/README.md @@ -0,0 +1,105 @@ +# Basic Gemini + +Comprehensive demo of the Google GenAI plugin — from basic generation to +thinking modes, tool calling, structured output, multimodal, image generation, +TTS, and advanced features like search grounding and URL context. + +## Features Demonstrated + +| Feature | Flow | Description | +|---------|------|-------------| +| Simple Generation | `basic-hi` | Basic text generation with Gemini | +| Retry Middleware | `basic-hi-with-retry` | Generation with automatic retry on failure | +| Fallback Middleware | `basic-hi-with-fallback` | Model fallback chain on failure | +| Thinking (Pro) | `thinking-level-pro` | Chain-of-thought reasoning (Gemini 2.5 Pro) | +| Thinking (Flash) | `thinking-level-flash` | Chain-of-thought reasoning (Gemini 2.5 Flash) | +| Vision (Image) | `describe-image` | Describe a base64-encoded image | +| YouTube Videos | `youtube-videos` | Transcribe YouTube video content | +| Search Grounding | `search-grounding` | Web search for real-time info | +| URL Context | `url-context` | Analyze content from web pages | +| File Search (RAG) | `file-search` | Search uploaded documents | +| Tool Calling | `toolCalling` | Streaming tool use (weather + unit conversion) | +| Screenshot Tool | `screenshot-tool-calling` | Screenshot-based tool use | +| Structured Tool Calling | `structured-tool-calling` | Tool calling with structured output | +| Structured Output | `structured-output` | JSON output with Zod schema (RPG character) | +| Thinking + Structured | `thinking-structured-output` | Structured output with thinking budget | +| Media Resolution | `gemini-media-resolution` | Image editing with Gemini 2.5 Pro | +| Image Generation | `nano-banana-pro` | Image generation with Gemini 2.5 Pro Image | +| Imagen | `imagen-image-generation` | Image generation with Imagen 3 | +| Text-to-Speech | `basic-tts` | Text-to-speech with Gemini 2.5 Flash | +| Vertex AI | `basic-hi-vertexai` | Same features via Vertex AI backend | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### How to Get Your Gemini API Key + +1. Visit [Google AI Studio](https://aistudio.google.com/). +2. Click on "Get API key" and create a key in a new or existing Google Cloud project. + +For more details, check out the [official documentation](https://ai.google.dev/gemini-api/docs/api-key). + +```bash +export GEMINI_API_KEY='' +``` + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Sample + +### Google AI backend + +```bash +pnpm run genkit:dev:googleai +``` + +### Vertex AI backend + +```bash +pnpm run genkit:dev:vertexai +``` + +## Testing This Demo + +1. **Open DevUI** at http://localhost:4000 + +2. **Test basic flows**: + - [ ] `basic-hi` — Simple greeting generation + - [ ] `basic-hi-with-retry` — Generation with retry middleware + - [ ] `basic-hi-with-fallback` — Fallback chain on model error + +3. **Test thinking modes**: + - [ ] `thinking-level-pro` — Input: `HIGH` (or `MINIMAL`, `LOW`, `MEDIUM`) + - [ ] `thinking-level-flash` — Input: `MINIMAL`, `LOW`, `MEDIUM`, or `HIGH` + +4. **Test multimodal**: + - [ ] `describe-image` — Image description from base64 + - [ ] `youtube-videos` — YouTube video transcription + +5. **Test tools**: + - [ ] `toolCalling` — Weather tool with streaming + - [ ] `structured-tool-calling` — Tool calling with structured output + +6. **Test advanced features**: + - [ ] `search-grounding` — Web search grounding + - [ ] `url-context` — URL content analysis + - [ ] `file-search` — File search RAG + - [ ] `structured-output` — RPG character generation + - [ ] `imagen-image-generation` — Image generation + +7. **Expected behavior**: + - All flows complete without errors + - Streaming shows incremental output + - Structured output matches Zod schemas + - Tools are called and responses processed diff --git a/js/testapps/context-caching/README.md b/js/testapps/context-caching/README.md index 6fa3ffe685..97ff99292a 100644 --- a/js/testapps/context-caching/README.md +++ b/js/testapps/context-caching/README.md @@ -50,7 +50,7 @@ You can configure the API key in two ways: 1. **Environment Variable**: ```bash - export GOOGLE_GENAI_API_KEY=your_api_key_here + export GEMINI_API_KEY=your_api_key_here ``` 2. **Inline Configuration** (for testing only, not recommended for production): diff --git a/js/testapps/context-caching2/README.md b/js/testapps/context-caching2/README.md index 19363038de..fa267950f0 100644 --- a/js/testapps/context-caching2/README.md +++ b/js/testapps/context-caching2/README.md @@ -50,7 +50,7 @@ You can configure the API key in two ways: 1. **Environment Variable**: ```bash - export GOOGLE_GENAI_API_KEY=your_api_key_here + export GEMINI_API_KEY=your_api_key_here ``` 2. **Inline Configuration** (for testing only, not recommended for production): diff --git a/js/testapps/dev-ui-gallery/README.md b/js/testapps/dev-ui-gallery/README.md new file mode 100644 index 0000000000..65ea9a8a8e --- /dev/null +++ b/js/testapps/dev-ui-gallery/README.md @@ -0,0 +1,66 @@ +# Dev UI Gallery + +Loads plugins and flows to demonstrate and test Genkit Dev UI features. + +This test app registers a wide variety of flows, prompts, and tools to +exercise the Dev UI — including Firebase Functions-compatible flows, +Dotprompt templates, custom tools, evaluators, and multiple vector store +backends. + +## Features Demonstrated + +| Feature | Module | Description | +|---------|--------|-------------| +| Flows | `flows.ts` | Various generation flows (streaming, structured output, etc.) | +| Firebase Functions | `flows-firebase-functions.ts` | Flows wrapped for Firebase Functions compatibility | +| Dotprompt | `prompts.ts` | Prompt file templates with schemas | +| Tools | `tools.ts` | Custom tools for model use | +| Multiple Plugins | `genkit.ts` | Google AI, Vertex AI, Ollama, ChromaDB, Pinecone, Firebase | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### API Keys + +```bash +export GEMINI_API_KEY='' +``` + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Sample + +```bash +pnpm run genkit:dev +``` + +## Testing This Demo + +1. **Open DevUI** at http://localhost:4000 + +2. **Verify UI features**: + - [ ] Flows panel lists all defined flows + - [ ] Prompts panel lists all Dotprompt templates + - [ ] Tools panel lists all defined tools + - [ ] Actions panel shows registered actions + +3. **Test flows**: + - [ ] Run various flows from the Dev UI + - [ ] Test streaming flows and verify incremental output + - [ ] Test structured output flows + +4. **Expected behavior**: + - All flows, prompts, and tools appear in the Dev UI + - Flows execute and return results + - Streaming shows incremental output diff --git a/js/testapps/durable-streaming/README.md b/js/testapps/durable-streaming/README.md new file mode 100644 index 0000000000..b2b0af6e4e --- /dev/null +++ b/js/testapps/durable-streaming/README.md @@ -0,0 +1,89 @@ +# Durable Streaming + +Demonstrates durable streaming with multiple stream manager backends — +in-memory, Firestore, and Realtime Database. This allows clients to +reconnect and resume consuming stream chunks even after disconnection. + +## Features Demonstrated + +| Feature | Flow | Description | +|---------|------|-------------| +| Basic Streaming | `streamy` | Counts to N, streaming each step | +| Error Handling | `streamyThrowy` | Throws an error after 3 chunks | +| In-Memory Backend | `/streamy` | Stream manager using in-memory storage | +| Firestore Backend | `/streamyFirestore` | Stream manager backed by Cloud Firestore | +| RTDB Backend | `/streamyRtdb` | Stream manager backed by Realtime Database | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager +- **Firebase project** with Firestore and/or Realtime Database enabled + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +### Firebase Configuration + +Set up Application Default Credentials for Firebase: + +```bash +export GOOGLE_APPLICATION_CREDENTIALS='/path/to/service-account-key.json' +``` + +Or use `gcloud`: + +```bash +gcloud auth application-default login +``` + +## Run the Sample + +```bash +pnpm build && pnpm start +``` + +The Express server starts on port `3500`. + +## Testing This Demo + +1. **Test in-memory streaming**: + ```bash + curl -X POST http://localhost:3500/streamy \ + -H "Content-Type: application/json" \ + -d '{"data": 5}' + ``` + +2. **Test Firestore-backed streaming**: + ```bash + curl -X POST http://localhost:3500/streamyFirestore \ + -H "Content-Type: application/json" \ + -d '{"data": 5}' + ``` + +3. **Test RTDB-backed streaming**: + ```bash + curl -X POST http://localhost:3500/streamyRtdb \ + -H "Content-Type: application/json" \ + -d '{"data": 5}' + ``` + +4. **Test error handling**: + ```bash + curl -X POST http://localhost:3500/streamyThrowy \ + -H "Content-Type: application/json" \ + -d '{"data": 5}' + ``` + +5. **Expected behavior**: + - `streamy` streams count objects `{count: 0}` through `{count: N-1}` + - `streamyThrowy` streams 3 chunks then throws an error + - All three backends (in-memory, Firestore, RTDB) behave identically diff --git a/js/testapps/esm/README.md b/js/testapps/esm/README.md new file mode 100644 index 0000000000..e1f612e023 --- /dev/null +++ b/js/testapps/esm/README.md @@ -0,0 +1,60 @@ +# ESM Compatibility Test + +Verifies that all Genkit packages and plugins can be imported and used in +an ESM (ECMAScript Modules) project with `"type": "module"` in `package.json`. + +This is a build-time smoke test, not a runtime sample — it imports every +plugin and core module to ensure there are no CommonJS/ESM interop issues. + +## Plugins Tested + +| Plugin | Import | +|--------|--------| +| `genkit` | Core library | +| `@genkit-ai/google-genai` | Google AI + Vertex AI | +| `@genkit-ai/googleai` | Legacy Google AI | +| `@genkit-ai/vertexai` | Legacy Vertex AI (evaluation, model garden, rerankers) | +| `@genkit-ai/firebase` | Firebase telemetry + context | +| `@genkit-ai/google-cloud` | Google Cloud telemetry | +| `@genkit-ai/express` | Express handler | +| `@genkit-ai/next` | Next.js integration | +| `@genkit-ai/mcp` | MCP client/server/host | +| `@genkit-ai/evaluator` | Evaluation framework | +| `@genkit-ai/dev-local-vectorstore` | Local vector store | +| `@genkit-ai/checks` | Checks plugin | +| `@genkit-ai/compat-oai` | OpenAI-compatible (OpenAI, DeepSeek, xAI) | +| `genkitx-ollama` | Ollama | +| `genkitx-chromadb` | ChromaDB | +| `genkitx-pinecone` | Pinecone | +| `genkitx-cloud-sql-pg` | Cloud SQL Postgres | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Test + +```bash +pnpm test +``` + +This builds the TypeScript and then runs the compiled output. If any +ESM import fails, the process will exit with an error. + +## Expected Behavior + +- All imports resolve without errors +- A simple `hello` flow is defined and can be invoked +- `expressHandler` and `appRoute` wrappers work with the flow diff --git a/js/testapps/express/README.md b/js/testapps/express/README.md new file mode 100644 index 0000000000..5a3f69516e --- /dev/null +++ b/js/testapps/express/README.md @@ -0,0 +1,78 @@ +# Express Integration + +Demonstrates integrating Genkit flows with an Express.js server — including +authentication context, streaming responses, and the `expressHandler` utility. + +## Features Demonstrated + +| Feature | Endpoint | Description | +|---------|----------|-------------| +| Flow via `expressHandler` | `POST /jokeFlow` | Genkit flow exposed via Express with auth context | +| Flow handler (no auth) | `POST /jokeHandler` | Flow exposed without auth validation | +| Direct flow invocation | `GET /jokeWithFlow` | Call a flow directly from a route handler | +| Raw streaming | `GET /jokeStream` | Chunked transfer encoding with `ai.generate` | +| Auth context | `Authorization` header | Token-based auth with context validation | +| Context providers | `auth()` factory | Reusable auth context provider pattern | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### API Keys + +```bash +export GEMINI_API_KEY='' +``` + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Sample + +```bash +pnpm build && pnpm start +``` + +The Express server starts on port `5000` (or `$PORT`). + +## Testing This Demo + +1. **Test with auth** (requires `Authorization: open sesame` header): + ```bash + curl http://localhost:5000/jokeFlow?stream=true \ + -d '{"data": "banana"}' \ + -H "Content-Type: application/json" \ + -H "Authorization: open sesame" + ``` + +2. **Test without auth**: + ```bash + curl http://localhost:5000/jokeHandler?stream=true \ + -d '{"data": "banana"}' \ + -H "Content-Type: application/json" + ``` + +3. **Test direct flow invocation**: + ```bash + curl "http://localhost:5000/jokeWithFlow?subject=banana" + ``` + +4. **Test raw streaming**: + ```bash + curl "http://localhost:5000/jokeStream?subject=banana" + ``` + +5. **Expected behavior**: + - Authenticated requests (`open sesame`) succeed + - Unauthenticated requests return `PERMISSION_DENIED` + - Streaming endpoints deliver text incrementally + - `?stream=true` enables streaming on `expressHandler` endpoints diff --git a/js/testapps/flow-sample1/README.md b/js/testapps/flow-sample1/README.md new file mode 100644 index 0000000000..a36c02d3dc --- /dev/null +++ b/js/testapps/flow-sample1/README.md @@ -0,0 +1,83 @@ +# Flow Fundamentals + +Demonstrates core Genkit flow primitives — multi-step tracing, streaming, +context propagation, error handling, and long-running flows. No AI model +is used; these flows exercise the framework itself. + +## Features Demonstrated + +| Feature | Flow | Description | +|---------|------|-------------| +| Basic Flow | `basic` | Multi-step flow with `ai.run()` traced steps | +| Context Propagation | `withContext` | Access flow context from within a flow | +| Streaming | `streamy` | Stream count objects at 1-second intervals | +| Error Handling | `throwy` | Flow that throws an error | +| Error in Steps | `throwy2` | Error thrown from a nested traced step | +| Multi-Step Tracing | `multiSteps` | Multiple traced steps with data transformation | +| Large Step Data | `largeSteps` | Steps with large payloads (~1MB strings) | +| Long-Running | `test-long-broadcast` | Multi-minute flow for broadcast testing | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Sample + +```bash +pnpm build && pnpm start +``` + +Or via CLI: + +```bash +genkit flow:run basic '"hello"' +genkit flow:run streamy 5 -s +``` + +## Testing This Demo + +1. **Test basic flow**: + ```bash + genkit flow:run basic '"hello"' + ``` + +2. **Test streaming**: + ```bash + genkit flow:run streamy 5 -s + ``` + Should output `{count: 0}` through `{count: 4}` at 1-second intervals. + +3. **Test error handling**: + ```bash + genkit flow:run throwy '"hello"' + ``` + Should throw an error. + +4. **Test multi-step**: + ```bash + genkit flow:run multiSteps '"world"' + ``` + Should return a number after processing through multiple steps. + +5. **Test long-running flow** (2-3 minutes): + ```bash + genkit flow:run test-long-broadcast '{"steps": 5, "stepDelay": 5000}' + ``` + +6. **Expected behavior**: + - `basic` returns a string after two traced steps + - `streamy` streams objects at regular intervals + - `throwy` / `throwy2` demonstrate error propagation in flows + - `multiSteps` shows trace spans for each step in DevUI diff --git a/js/testapps/flow-simple-ai/README.md b/js/testapps/flow-simple-ai/README.md new file mode 100644 index 0000000000..f7024438c6 --- /dev/null +++ b/js/testapps/flow-simple-ai/README.md @@ -0,0 +1,83 @@ +# Flow + AI Kitchen Sink + +Comprehensive test app that exercises nearly every Genkit feature — generation, +streaming, structured output, tool calling, Dotprompt, RAG, multimodal, +evaluators, TTS, and custom model middleware. Uses Google AI (Gemini) with +Google Cloud telemetry. + +## Features Demonstrated + +| Feature | Flow | Description | +|---------|------|-------------| +| Joke Generation | `jokeFlow` | Generate jokes with configurable model | +| Streaming (Vertex) | `streamFlowVertex` | Streaming generation with Vertex AI | +| Streaming JSON | `streamJsonFlow` | Stream structured JSON (RPG characters) | +| Structured Output | `jokeWithOutputFlow` | JSON output with Zod schema | +| Multimodal | `multimodalFlow` | Describe an image from URL | +| RAG | `ragFlow` | Retrieval-augmented generation | +| Dotprompt | `dotpromptContext` | Prompt templates with context | +| Tool Calling | `toolTester` | Generate joke using a tool | +| Math Tool | `gablorkenFlow` | Custom gablorken calculator tool | +| TTS | `tts-flow` | Text-to-speech generation | +| LLM-as-Judge | `llmJudgeFlow` | Evaluate output quality with a model | +| Custom Middleware | `constrainedFlow` | Simulated constrained generation | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### API Keys + +```bash +export GEMINI_API_KEY='' +``` + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Sample + +```bash +pnpm run genkit:dev +``` + +Or: + +```bash +pnpm start +``` + +## Testing This Demo + +1. **Open DevUI** at http://localhost:4000 + +2. **Test basic flows**: + - [ ] `jokeFlow` — Joke generation (input: `{"modelName": "vertexai/gemini-2.5-pro", "subject": "cats"}`) + - [ ] `streamFlowVertex` — Streaming response + - [ ] `streamJsonFlow` — Streaming JSON (RPG characters) + +3. **Test structured output**: + - [ ] `jokeWithOutputFlow` — JSON output with schema + +4. **Test tools**: + - [ ] `toolTester` — Tool-assisted joke generation + - [ ] `gablorkenFlow` — Gablorken calculator + +5. **Test multimodal + RAG**: + - [ ] `multimodalFlow` — Image description + - [ ] `ragFlow` — Retrieval-augmented generation + +6. **Expected behavior**: + - All flows complete without errors + - Streaming shows incremental output + - Structured output matches Zod schemas + - Tools are called and responses integrated diff --git a/js/testapps/format-tester/README.md b/js/testapps/format-tester/README.md new file mode 100644 index 0000000000..7646adabb1 --- /dev/null +++ b/js/testapps/format-tester/README.md @@ -0,0 +1,72 @@ +# Format Tester + +Automated test harness for Genkit's output format support — text, JSON, array, +JSONL, and enum — across multiple models. Runs all format × model combinations +and reports pass/fail results. + +## Formats Tested + +| Format | Prompt | Output Schema | +|--------|--------|---------------| +| `text` | Short pirate story | Plain text | +| `json` | RPG creature | `{name, backstory, hitPoints, attacks[]}` | +| `array` | Futurama characters | `[{name, description, friends[], enemies[]}]` | +| `jsonl` | Pet store products | `[{name, description, price, stock, color, tags[]}]` | +| `enum` | Skydiving risk level | `VERY_LOW \| LOW \| MEDIUM \| HIGH \| VERY_HIGH` | + +## Models Tested (default) + +- `vertexai/gemini-2.5-pro` +- `vertexai/gemini-2.5-flash` +- `googleai/gemini-2.5-pro` +- `googleai/gemini-2.5-flash` +- Vertex AI Model Garden: Claude 3.5 Sonnet (v1 and v2) + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager + +### API Keys + +```bash +export GEMINI_API_KEY='' +``` + +For Vertex AI models, also configure GCP credentials: + +```bash +gcloud auth application-default login +``` + +### Build and Install + +From the repo root: + +```bash +pnpm install +pnpm run setup +``` + +## Run the Test + +```bash +pnpm build && pnpm start +``` + +### Custom models + +Pass model names as command-line arguments: + +```bash +pnpm build && node lib/index.js googleai/gemini-2.5-flash vertexai/gemini-2.5-pro +``` + +## Expected Behavior + +- Each format × model combination is tested +- Streaming output is printed chunk-by-chunk +- Final structured output is printed after each test +- A summary of failures is printed at the end diff --git a/js/testapps/model-armor/README.md b/js/testapps/model-armor/README.md new file mode 100644 index 0000000000..c6b72421d2 --- /dev/null +++ b/js/testapps/model-armor/README.md @@ -0,0 +1,65 @@ +# Model Armor + +Demonstrates the [Model Armor](https://cloud.google.com/security/products/model-armor) +middleware for content safety filtering. Model Armor scans prompts for +prompt injection, jailbreak attempts, and sensitive data before sending +them to the model. + +## Features Demonstrated + +| Feature | Flow | Description | +|---------|------|-------------| +| Content Filtering | `modelArmorFlow` | Generation with Model Armor middleware for PI/jailbreak and SDP filters | + +## Setup + +### Prerequisites + +- **Node.js** (v18 or higher) +- **pnpm** package manager +- **Google Cloud project** with Model Armor enabled + +### API Keys + +```bash +export GEMINI_API_KEY='' +``` + +### Model Armor Template + +Create a Model Armor template in your GCP project, then set: + +```bash +export MODEL_ARMOR_TEMPLATE='projects//locations//templates/