@kokimoki/app 2.1.0 → 3.0.0

package/docs/kokimoki-ai.instructions.md

@@ -0,0 +1,316 @@
+---
+description: "AI text generation and image transformation with Kokimoki SDK"
+applyTo: "**/*.ts,**/*.tsx"
+---
+
+# AI Integration
+
+Built-in methods for AI text generation and image transformation. No API keys required.
+All generation methods are **async job-based** - they submit a job and return immediately with a `jobId`.
+Use the corresponding poll method to wait for the result.
+
+For core SDK concepts, see [Kokimoki SDK](./kokimoki-sdk.instructions.md).
+
+Access AI API via `kmClient.ai`.
+
+## Key Features
+
+- Multiple AI models (GPT-4, GPT-5, Gemini variants)
+- Text generation with configurable creativity (temperature)
+- Structured JSON output with Zod schema validation
+- AI-powered image generation and modification
+- Job-based async processing with polling support
+- Resumable after page reload (persist jobId)
+
+## Available Models
+
+**Text Models:**
+
+- `gpt-4o`: OpenAI GPT-4 Optimized
+- `gpt-4o-mini`: Smaller, faster GPT-4 variant
+- `gpt-5`: OpenAI GPT-5 (latest)
+- `gpt-5-mini`: Smaller GPT-5 variant
+- `gpt-5-nano`: Smallest GPT-5 variant for lightweight tasks
+- `gemini-2.5-flash-lite`: Google Gemini lite variant
+- `gemini-2.5-flash`: Google Gemini fast variant
+- `gemini-3-flash-preview`: Google Gemini 3 Flash preview
+- `gemini-3-pro-preview`: Google Gemini 3 Pro preview
+
+**Image Models:**
+
+- `gemini-2.5-flash-image`: Google Gemini image generation
+- `gemini-3-pro-image-preview`: Google Gemini 3 Pro image preview
+
+## API Methods
+
+### ai.generateText(req): Promise<{ jobId: string }>
+
+Submits a text generation job. Use `pollText()` to wait for the result.
+
+**Parameters:**
+
+- **req.model**: `string` AI model to use (optional)
+- **req.systemPrompt**: `string` AI role/behavior (optional)
+- **req.prompt**: `string` The user's message or question to send to the AI
+- **req.temperature**: `number` Creativity level from 0.0 = factual to 1.0 = creative (optional)
+- **req.imageUrls**: `string[]` Image URLs to include with the prompt (Gemini models only) (optional)
+
+**Example:**
+
+```typescript
+// Submit text generation job
+const { jobId } = await kmClient.ai.generateText({
+  model: "gemini-2.5-flash-lite",
+  systemPrompt: "You are a fantasy story writer",
+  prompt: "Write a short quest description",
+  temperature: 0.8,
+});
+
+// Poll for result
+const text = await kmClient.ai.pollText(jobId);
+```
+
+### ai.generateJson<T>(req): Promise<{ jobId: string }>
+
+Submits a JSON generation job with Zod schema validation. Use `pollJson()` to wait for the result with type inference.
+
+**Parameters:**
+
+- **req.schema**: `ZodType` Zod schema that defines the expected JSON structure
+- **req.model**: `string` AI model to use (optional)
+- **req.systemPrompt**: `string` AI role/behavior (optional)
+- **req.prompt**: `string` The user's message or question to send to the AI
+- **req.temperature**: `number` Creativity level from 0.0 = factual to 1.0 = creative (optional)
+- **req.imageUrls**: `string[]` Image URLs to include with the prompt (Gemini models only) (optional)
+
+**Example:**
+
+```typescript
+import { z } from "zod/v4";
+
+// Define schema with Zod
+const enemySchema = z.object({
+  name: z.string(),
+  health: z.number(),
+  attack: z.number(),
+  abilities: z.array(z.string()),
+});
+
+// Submit JSON generation job
+const { jobId } = await kmClient.ai.generateJson({
+  schema: enemySchema,
+  prompt: "Create a level 5 goblin warrior",
+  temperature: 0.7,
+});
+
+// Save jobId to store for persistence across reloads
+await saveJobId(jobId);
+
+// Poll with schema for type inference and validation
+const enemy = await kmClient.ai.pollJson(jobId, { schema: enemySchema });
+console.log(enemy.name, enemy.health); // Fully typed!
+```
+
+```typescript
+// Generate quiz questions
+const questionSchema = z.array(
+  z.object({
+    question: z.string(),
+    options: z.array(z.string()),
+    correctAnswer: z.number(),
+  })
+);
+
+const { jobId } = await kmClient.ai.generateJson({
+  schema: questionSchema,
+  systemPrompt: "Generate quiz questions",
+  prompt: "Create 5 history quiz questions with 4 options each",
+});
+
+const questions = await kmClient.ai.pollJson(jobId, { schema: questionSchema });
+questions.forEach((q) => console.log(q.question));
+```
+
+### ai.generateImage(req): Promise<{ jobId: string }>
+
+Submits an image generation/modification job. Use `pollImage()` to wait for the result.
+The result is stored as `Upload` object (see [Storage](./kokimoki-storage.instructions.md)).
+
+**Parameters:**
+
+- **req.model**: `string` Image model to use (optional, default: `gemini-2.5-flash-image`)
+- **req.prompt**: `string` The prompt describing the image or modification
+- **req.imageUrls**: `string[]` Source image URLs to include in the generation (optional)
+- **req.tags**: `string[]` Tags for the result in `Upload` format (optional, default: [])
+
+**Example:**
+
+```typescript
+// Generate a new image
+const { jobId } = await kmClient.ai.generateImage({
+  prompt: "A fantasy castle on a mountain at sunset",
+  tags: ["background", "ai-generated"],
+});
+
+const upload = await kmClient.ai.pollImage(jobId);
+console.log(upload.url); // CDN URL to the generated image
+```
+
+```typescript
+// Modify an existing image
+const { jobId } = await kmClient.ai.generateImage({
+  imageUrls: ["https://static.kokimoki.com/game/image.jpg"],
+  prompt: "Make it look like pixel art",
+  tags: ["art", "ai-generated"],
+});
+
+const upload: Upload = await kmClient.ai.pollImage(jobId);
+```
+
+### ai.getJob(jobId): Promise<AiJob>
+
+Get the current status of an AI job without polling.
+
+**Parameters:**
+
+- **jobId**: `string` The job ID to check
+
+**Returns:** `AiJob` object with status and result
+
+```typescript
+interface AiJob {
+  jobId: string;
+  type: "text" | "json" | "image";
+  status: "processing" | "queued" | "completed" | "failed";
+  result?: unknown;
+  error?: { message: string; code?: string };
+  createdAt: number;
+}
+```
+
+**Example:**
+
+```typescript
+const job = await kmClient.ai.getJob(jobId);
+if (job.status === "completed") {
+  console.log("Result:", job.result);
+} else if (job.status === "failed") {
+  console.error("Error:", job.error?.message);
+}
+```
+
+### ai.pollText(jobId, options?): Promise<string>
+
+Poll a text generation job until completion.
+
+**Parameters:**
+
+- **jobId**: `string` The job ID to poll
+- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
+- **options.timeout**: `number` Timeout in ms (default: 120000)
+- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
+
+**Example:**
+
+```typescript
+const text = await kmClient.ai.pollText(jobId, {
+  timeout: 60000,
+  onProgress: (status) => console.log("Status:", status),
+});
+```
+
+### ai.pollJson<T>(jobId, options): Promise<T>
+
+Poll a JSON generation job until completion with schema validation.
+
+**Parameters:**
+
+- **jobId**: `string` The job ID to poll
+- **options.schema**: `ZodType` Zod schema for validation and type inference (required)
+- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
+- **options.timeout**: `number` Timeout in ms (default: 120000)
+- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
+
+**Example:**
+
+```typescript
+const enemy = await kmClient.ai.pollJson(jobId, {
+  schema: enemySchema,
+  timeout: 60000,
+  onProgress: (status) => console.log("Status:", status),
+});
+```
+
+### ai.pollImage(jobId, options?): Promise<Upload>
+
+Poll an image generation job until completion.
+
+**Parameters:**
+
+- **jobId**: `string` The job ID to poll
+- **options.pollInterval**: `number` Polling interval in ms (default: 2000, min: 1000)
+- **options.timeout**: `number` Timeout in ms (default: 120000)
+- **options.onProgress**: `(status: AiJobStatus) => void` Progress callback
+
+**Example:**
+
+```typescript
+const upload = await kmClient.ai.pollImage(jobId, {
+  timeout: 60000,
+  onProgress: (status) => console.log("Status:", status),
+});
+```
+
+## Common Patterns
+
+### Example: Persist Jobs Across Page Reloads
+
+```typescript
+// Store jobId in local store for persistence
+const { jobId } = await kmClient.ai.generateJson({
+  schema: questSchema,
+  prompt: "Generate an epic quest",
+});
+
+await kmClient.transact([localStore], ([state]) => {
+  state.pendingQuestJobId = jobId;
+});
+
+// On page load, resume polling if job is pending
+const pendingJobId = localStore.proxy.pendingQuestJobId;
+if (pendingJobId) {
+  const quest = await kmClient.ai.pollJson(pendingJobId, {
+    schema: questSchema,
+  });
+  // Clear pending job
+  await kmClient.transact([localStore], ([state]) => {
+    state.pendingQuestJobId = null;
+  });
+}
+```
+
+### Example: Show Loading State
+
+```typescript
+setLoading(true);
+const { jobId } = await kmClient.ai.generateText({
+  prompt: "Write a story",
+});
+
+const text = await kmClient.ai.pollText(jobId, {
+  onProgress: (status) => {
+    if (status === "queued") setLoadingText("Waiting in queue...");
+    if (status === "processing") setLoadingText("Generating...");
+  },
+});
+setLoading(false);
+```
+
+## Key Points
+
+- **Job-based**: All generation methods return `{ jobId }` immediately, use poll methods for results
+- **Resumable**: Save `jobId` to store to resume polling after page reload
+- **Zod Schemas**: Use Zod schemas for `generateJson` to get automatic type inference and validation
+- **Temperature**: Range 0.0 (factual) to 1.0 (creative)
+- **Polling Options**: Configure `pollInterval`, `timeout`, and `onProgress` callback
+- **Image URLs**: Gemini models support multimodal input via `imageUrls` parameter