Beginner

// lib/ai/first-call.ts
import { generateText } from "ai"; // => imports core generation function from ai@6.0.168
import { openai } from "@ai-sdk/openai"; // => imports OpenAI provider adapter
 
export async function askAI(question: string): Promise<string> {
  // => async function: returns a Promise that resolves to the LLM's answer
 
  const result = await generateText({
    // => blocks until full response arrives
    model: openai("gpt-4o"), // => selects GPT-4o as the language model
    prompt: question, // => the user's question string
    maxTokens: 512, // => caps response at 512 tokens (~380 words)
  });
  // => result shape: { text, usage, finishReason, warnings }
 
  return result.text;
  // => result.text is the model's raw string response
  // => e.g. "The capital of France is Paris."
}
 
// Usage:
// const answer = await askAI('What is the capital of France?');
// => answer is "The capital of France is Paris."

// lib/ai/stream-text.ts
import { streamText } from "ai"; // => imports streaming generation function
import { openai } from "@ai-sdk/openai"; // => OpenAI provider adapter
 
export async function streamToConsole(prompt: string): Promise<void> {
  const result = await streamText({
    // => begins streaming immediately
    model: openai("gpt-4o"), // => GPT-4o produces output token-by-token
    prompt, // => shorthand: prompt: prompt
    maxTokens: 1024, // => max 1024 tokens in response
  });
  // => result.textStream is an AsyncIterable<string>
  // => each iteration yields the next text chunk (1–5 tokens typically)
 
  for await (const chunk of result.textStream) {
    // => loop runs once per streamed chunk from the model
    process.stdout.write(chunk);
    // => writes chunk without newline: "The", " capital", " of", " France", " is", " Paris"
  }
  // => after loop: full text has been written to stdout
 
  console.log("\n--- Stream complete ---");
  // => signals end of stream to the user
 
  const usage = await result.usage;
  // => usage resolves after stream ends: { promptTokens, completionTokens, totalTokens }
  console.log("Tokens used:", usage.totalTokens);
  // => e.g. "Tokens used: 87"
}

// app/api/chat/route.ts
import { streamText } from "ai"; // => streaming generation function
import { openai } from "@ai-sdk/openai"; // => OpenAI provider adapter
import { NextRequest } from "next/server"; // => typed Next.js request
 
export const runtime = "edge"; // => optional: runs on Vercel Edge Network
 
export async function POST(req: NextRequest) {
  // => POST handler: called when browser sends chat message
 
  const { messages } = await req.json();
  // => messages: [{ role: 'user', content: 'Hello!' }]
  // => array of prior conversation turns
 
  const result = await streamText({
    // => NEVER use StreamingTextResponse — removed in ai@6
    model: openai("gpt-4o"), // => model selection
    messages, // => full conversation history
    maxTokens: 2048, // => safety cap on response length
  });
  // => result holds the stream, not yet consumed
 
  return result.toDataStreamResponse();
  // => converts stream to HTTP Response with correct Content-Type
  // => Content-Type: text/event-stream (Server-Sent Events)
  // => the useChat hook reads this format automatically
  // => CRITICAL: toDataStreamResponse() replaces deprecated StreamingTextResponse
}

// lib/ai/openai-direct.ts
import OpenAI from "openai"; // => default export is the OpenAI client class
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY, // => reads from environment variable
  // => NEVER hardcode API keys: security risk and key rotation nightmare
});
// => client is a configured OpenAI API client
 
export async function chatCompletion(userMessage: string): Promise<string> {
  const completion = await client.chat.completions.create({
    // => creates a chat completion request (OpenAI's primary API endpoint)
 
    model: "gpt-4o", // => model identifier string (OpenAI naming)
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      // => system message sets assistant behavior and persona
 
      { role: "user", content: userMessage },
      // => user message is the prompt to respond to
    ],
    max_tokens: 512, // => OpenAI SDK uses snake_case (not camelCase)
  });
  // => completion shape: { id, choices, usage, model, created }
 
  const text = completion.choices[0].message.content ?? "";
  // => choices[0] is the first (and usually only) completion
  // => message.content is the assistant's reply string
  // => ?? '' handles the null case (content can be null for tool calls)
 
  return text;
  // => e.g. "Hello! How can I assist you today?"
}

// lib/ai/openai-stream.ts
import OpenAI from "openai"; // => OpenAI client
 
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// => client configured from environment
 
export async function streamOpenAI(prompt: string): Promise<void> {
  const stream = await client.chat.completions.create({
    model: "gpt-4o", // => model selection
    messages: [{ role: "user", content: prompt }],
    // => single-turn conversation
 
    stream: true, // => enables SSE streaming mode
    // => without stream: true, create() returns the full completion
  });
  // => stream is an AsyncIterable of ChatCompletionChunk events
 
  for await (const event of stream) {
    // => iterates over each SSE event as it arrives
 
    const delta = event.choices[0]?.delta?.content;
    // => delta is the incremental text chunk for this event
    // => e.g. "Hello", " there", "!", undefined (for final empty chunk)
    // => optional chaining (?.) guards against missing fields
 
    if (delta) {
      process.stdout.write(delta); // => writes chunk without newline
      // => outputs: "Hello there!" character by character
    }
  }
  // => loop ends when OpenAI sends the [DONE] SSE event
 
  console.log("\nStream finished.");
  // => signals completion to the user
}

// app/chat/page.tsx
'use client';                            // => Client Component: uses browser hooks
import { useChat } from 'ai/react';     // => import from ai/react subpath
 
export default function ChatPage() {
  const {
    messages,                            // => Message[]: full conversation history
    input,                               // => string: current text-input field value
    handleInputChange,                   // => (e) => void: syncs input state to field
    handleSubmit,                        // => (e) => void: sends message to /api/chat
    isLoading,                           // => boolean: true while waiting for response
    error,                               // => Error | undefined: last request error
  } = useChat({
    api: '/api/chat',                    // => POST endpoint (defaults to /api/chat)
  });
  // => useChat manages all message state and fetch lifecycle
 
  return (
    <div className="flex flex-col h-screen p-4">
      <div className="flex-1 overflow-y-auto space-y-2">
        {messages.map((msg) => (          // => renders each message in conversation
          <div
            key={msg.id}                  // => msg.id is unique UUID from SDK
            className={msg.role === 'user' ? 'text-right' : 'text-left'}
            // => right-align user messages, left-align assistant
          >
            <span className="font-bold capitalize">{msg.role}:</span>
            {/* => displays "user:" or "assistant:" label */}
            <span className="ml-2">{msg.content}</span>
            {/* => msg.content is the text of this message */}
          </div>
        ))}
        {isLoading && <div className="text-gray-400">Thinking...</div>}
        {/* => shows loading indicator while model generates */}
      </div>
 
      <form onSubmit={handleSubmit} className="flex gap-2 mt-4">
        {/* => handleSubmit intercepts form submit, calls /api/chat */}
        <input
          value={input}                   // => controlled input bound to useChat state
          onChange={handleInputChange}    // => updates input state on each keystroke
          placeholder="Ask anything..."
          className="flex-1 border rounded px-3 py-2"
          disabled={isLoading}            // => prevents sending while model responds
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
 
      {error && (
        <p className="text-red-600 mt-2">Error: {error.message}</p>
        // => displays error message if request fails
      )}
    </div>
  );
}

// lib/ai/system-prompts.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
export async function classifyWithSystem(text: string): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"),
 
    system: `You are a precise text classifier.
Respond ONLY with one of these labels: POSITIVE, NEGATIVE, NEUTRAL.
Do not include any explanation or punctuation.`,
    // => system message sets strict output format
    // => model follows these instructions for the entire conversation
    // => system content is not shown to users in chat UIs
 
    prompt: text,
    // => user content: the text to classify
    // => short-form: equivalent to messages: [{ role: 'user', content: text }]
 
    maxTokens: 10,
    // => 10 tokens is enough for a single-word label
    // => low maxTokens prevents unexpected long responses
  });
  // => result.text is one of "POSITIVE", "NEGATIVE", "NEUTRAL"
 
  return result.text.trim();
  // => .trim() removes any trailing whitespace or newlines
  // => e.g. "POSITIVE" for "I love this product!"
}
 
// Example with explicit messages array (equivalent form):
export async function chatWithHistory(userQuestion: string): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"),
    messages: [
      {
        role: "system", // => 'system' sets overall behavior
        content: "You are a Sharia finance expert. Answer concisely.",
      },
      {
        role: "user", // => 'user' is the human turn
        content: userQuestion, // => the question to answer
      },
    ],
    // => messages array gives full control over conversation structure
  });
 
  return result.text;
  // => the assistant's answer to userQuestion
}

// lib/ai/multi-turn.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import type { CoreMessage } from "ai"; // => CoreMessage: { role, content } union type
 
// In-memory conversation store (use database in production)
const conversations = new Map<string, CoreMessage[]>();
// => Map<sessionId, messages[]> stores conversation per user session
 
export async function chat(sessionId: string, userInput: string): Promise<string> {
  // => sessionId: unique string identifying this user's conversation
 
  const history = conversations.get(sessionId) ?? [];
  // => retrieves existing history, or starts fresh with empty array
  // => e.g. history: [{ role: 'user', content: 'Hello' }, { role: 'assistant', content: 'Hi!' }]
 
  const messages: CoreMessage[] = [
    ...history, // => spread all prior turns
    { role: "user", content: userInput }, // => append the new user message
  ];
  // => messages now contains the FULL conversation history including new input
 
  const result = await generateText({
    model: openai("gpt-4o"),
    messages, // => send entire history to model
    // => model "remembers" conversation by reading all prior messages
  });
  // => result.text is the model's response to the full conversation context
 
  const updatedHistory: CoreMessage[] = [
    ...messages, // => include all previous messages
    { role: "assistant", content: result.text }, // => append model's response
  ];
  // => updatedHistory: full conversation including new assistant reply
 
  conversations.set(sessionId, updatedHistory);
  // => persist updated history for next turn
 
  return result.text;
  // => return just the new response to the caller
}

// lib/ai/provider-swap.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai"; // => OpenAI provider
import { anthropic } from "@ai-sdk/anthropic"; // => Anthropic provider
 
const PROMPT = "Explain Zakat calculation in one sentence.";
// => same prompt used for both providers
 
export async function withOpenAI(): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"), // => OpenAI GPT-4o
    prompt: PROMPT,
  });
  return result.text;
  // => "Zakat is 2.5% of savings held for one lunar year above the nisab threshold."
}
 
export async function withAnthropic(): Promise<string> {
  const result = await generateText({
    model: anthropic("claude-sonnet-4-5"), // => Anthropic Claude — ONLY this line changed
    prompt: PROMPT,
    // => identical prompt, identical result shape
  });
  return result.text;
  // => "Zakat requires paying 2.5% of qualifying wealth held above nisab for a full lunar year."
}
 
// Runtime provider selection based on environment:
export async function withEnvProvider(): Promise<string> {
  const provider = process.env.AI_PROVIDER ?? "openai";
  // => reads provider from env variable, defaults to 'openai'
 
  const model =
    provider === "anthropic"
      ? anthropic("claude-sonnet-4-5") // => Anthropic model
      : openai("gpt-4o"); // => OpenAI model (default)
  // => model variable holds whichever provider was selected
 
  const result = await generateText({ model, prompt: PROMPT });
  // => identical call regardless of provider
  return result.text;
}

// lib/ai/model-settings.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
export async function deterministicSummary(text: string): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"),
    prompt: `Summarize this in exactly 2 sentences: ${text}`,
 
    temperature: 0,
    // => 0 = fully deterministic: same input → same output every time
    // => 1.0 = default: moderate creativity
    // => 2.0 = maximum randomness (rarely useful)
 
    maxTokens: 150,
    // => hard cap: response truncates at 150 tokens
    // => 1 token ≈ 0.75 words in English
    // => 150 tokens ≈ 112 words (enough for 2 sentences)
 
    topP: 1,
    // => nucleus sampling: consider tokens in top 100% probability mass
    // => lower values (e.g. 0.9) restrict vocabulary to most likely tokens
 
    frequencyPenalty: 0.3,
    // => penalizes repeated tokens: 0 = no penalty, 2 = maximum penalty
    // => 0.3: gently discourages word repetition in summaries
 
    presencePenalty: 0,
    // => penalizes any token that appeared before: 0 = disabled
    // => higher values encourage new topics (useful for creative tasks)
  });
  // => result.finishReason: 'stop' (natural end) or 'length' (hit maxTokens)
 
  if (result.finishReason === "length") {
    console.warn("Response truncated — increase maxTokens");
    // => warns developer if the summary was cut off
  }
 
  return result.text;
  // => deterministic 2-sentence summary
}

// app/complete/page.tsx
'use client';
import { useCompletion } from 'ai/react'; // => imports completion hook
 
export default function CompletionPage() {
  const {
    completion,                           // => string: the streamed completion text so far
    input,                                // => string: current input field value
    handleInputChange,                    // => syncs input to state
    handleSubmit,                         // => submits to /api/completion
    isLoading,                            // => true while generating
    error,                                // => Error | undefined
  } = useCompletion({
    api: '/api/completion',              // => GET/POST endpoint for completion
    // => unlike useChat, manages a single prompt → completion cycle
  });
  // => useCompletion: no message history, just prompt → streamed text
 
  return (
    <div className="p-6 max-w-2xl mx-auto">
      <form onSubmit={handleSubmit} className="space-y-4">
        <textarea
          value={input}
          onChange={handleInputChange}    // => updates input on keystroke
          placeholder="Start a sentence and let AI complete it..."
          rows={3}
          className="w-full border rounded p-3"
        />
        <button
          type="submit"
          disabled={isLoading}
          className="px-4 py-2 bg-blue-600 text-white rounded"
        >
          {isLoading ? 'Generating...' : 'Complete'}
          {/* => button label changes based on loading state */}
        </button>
      </form>
 
      {completion && (
        <div className="mt-6 p-4 bg-gray-50 rounded">
          <h2 className="font-semibold mb-2">Completion:</h2>
          <p className="whitespace-pre-wrap">{completion}</p>
          {/* => completion streams in character by character */}
          {/* => whitespace-pre-wrap preserves line breaks */}
        </div>
      )}
 
      {error && (
        <p className="mt-4 text-red-600">Error: {error.message}</p>
        // => displays error if API call fails
      )}
    </div>
  );
}

// lib/ai/env-config.ts
// This file shows the CORRECT pattern for environment variable management.
// Never import this file in client components — it accesses server-only secrets.
 
function getOpenAIKey(): string {
  const key = process.env.OPENAI_API_KEY;
  // => process.env is only available server-side (Node.js / Edge runtime)
  // => OPENAI_API_KEY is read from .env.local on localhost
  // => On Vercel: set in Project → Settings → Environment Variables
 
  if (!key) {
    throw new Error("OPENAI_API_KEY is not set. Add it to .env.local or Vercel env vars.");
    // => fail fast: crash at startup rather than at request time
    // => makes misconfiguration immediately obvious
  }
 
  return key;
  // => returns the validated key string
}
 
// .env.local (NEVER commit this file):
// OPENAI_API_KEY=sk-proj-...
// ANTHROPIC_API_KEY=sk-ant-api03-...
// => .env.local is gitignored by default in Next.js
 
// .env.example (SAFE to commit — shows structure without values):
// OPENAI_API_KEY=your-openai-key-here
// ANTHROPIC_API_KEY=your-anthropic-key-here
 
export function createOpenAIConfig() {
  return {
    apiKey: getOpenAIKey(), // => validates key exists before use
  };
  // => return value used to initialize SDK clients
}
 
// WRONG — never do this:
// const client = new OpenAI({ apiKey: 'sk-proj-actual-key-here' });
// => hardcoded key: will be exposed in git history forever, even after deletion

// app/api/qa/route.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { NextRequest, NextResponse } from "next/server";
 
export async function POST(req: NextRequest) {
  // => handles POST /api/qa
 
  const body = await req.json();
  // => parses JSON request body: { question: string }
 
  const { question } = body as { question: string };
  // => extracts question from body
  // => in production: validate with Zod (see Example 24)
 
  if (!question || typeof question !== "string") {
    return NextResponse.json(
      { error: "question is required and must be a string" },
      { status: 400 },
      // => 400 Bad Request: client sent invalid data
    );
  }
  // => input validation before calling AI (saves tokens on bad requests)
 
  const result = await generateText({
    model: openai("gpt-4o"),
    system: "Answer concisely in 1-3 sentences. Be factual.",
    // => system prompt constrains response length and style
 
    prompt: question,
    maxTokens: 256, // => 256 tokens ≈ 192 words (sufficient for 3 sentences)
  });
  // => result.text is the model's answer
 
  return NextResponse.json({
    answer: result.text, // => the AI's response
    usage: {
      promptTokens: result.usage.promptTokens,
      // => tokens used for the input (question + system prompt)
      completionTokens: result.usage.completionTokens,
      // => tokens used for the output (the answer)
      totalTokens: result.usage.totalTokens,
      // => sum: used for cost tracking
    },
  });
  // => response: { answer: string, usage: { ... } }
}

// lib/ai/error-handling.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
export async function generateWithRetry(prompt: string, maxRetries = 3): Promise<string> {
  let lastError: Error | null = null;
  // => tracks the last error for final throw if all retries fail
 
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    // => attempt 1, 2, 3: try up to maxRetries times
 
    try {
      const result = await generateText({
        model: openai("gpt-4o"),
        prompt,
        maxTokens: 512,
      });
      // => if successful, returns immediately without retrying
      return result.text;
      // => e.g. "Your answer here..."
    } catch (error) {
      lastError = error as Error;
      // => captures the error for inspection
 
      const isRateLimit = lastError.message.includes("429") || lastError.message.includes("rate limit");
      // => 429 Too Many Requests: OpenAI rate limit exceeded
 
      const isServerError = lastError.message.includes("500") || lastError.message.includes("503");
      // => 5xx: transient server errors worth retrying
 
      if (!isRateLimit && !isServerError) {
        throw lastError;
        // => auth errors (401), invalid model (404): don't retry, fail fast
      }
 
      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 8000);
      // => exponential backoff: 1s, 2s, 4s (capped at 8s)
      // => prevents hammering the API during an outage
 
      console.warn(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
      // => waits before retrying
    }
  }
 
  throw new Error(`All ${maxRetries} attempts failed: ${lastError?.message}`);
  // => all retries exhausted: propagate error to caller
}

// lib/ai/token-tracking.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
interface UsageRecord {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
  estimatedCostUSD: number;
}
 
// GPT-4o pricing as of 2026 (check OpenAI pricing page for current rates)
const GPT4O_COST_PER_1K_INPUT = 0.0025; // => $0.0025 per 1K input tokens
const GPT4O_COST_PER_1K_OUTPUT = 0.01; // => $0.010 per 1K output tokens
 
export async function generateWithCostTracking(
  prompt: string,
  systemPrompt?: string,
): Promise<{ text: string; usage: UsageRecord }> {
  const result = await generateText({
    model: openai("gpt-4o"),
    system: systemPrompt,
    prompt,
    maxTokens: 512,
  });
  // => result.usage: { promptTokens, completionTokens, totalTokens }
 
  const { promptTokens, completionTokens, totalTokens } = result.usage;
  // => promptTokens: tokens in the input (system + prompt)
  // => completionTokens: tokens in the output (model's response)
  // => totalTokens: promptTokens + completionTokens
 
  const estimatedCostUSD =
    (promptTokens / 1000) * GPT4O_COST_PER_1K_INPUT + (completionTokens / 1000) * GPT4O_COST_PER_1K_OUTPUT;
  // => cost formula: (inputTokens/1000 * inputRate) + (outputTokens/1000 * outputRate)
  // => e.g. 500 prompt + 200 completion = $0.00325
 
  const usage: UsageRecord = {
    promptTokens,
    completionTokens,
    totalTokens,
    estimatedCostUSD: Math.round(estimatedCostUSD * 1_000_000) / 1_000_000,
    // => round to 6 decimal places: $0.003250
  };
 
  console.log(`Usage: ${totalTokens} tokens | Cost: $${usage.estimatedCostUSD}`);
  // => e.g. "Usage: 700 tokens | Cost: $0.003250"
 
  return { text: result.text, usage };
  // => returns both the response text and the usage record
}

// lib/ai/prompt-templates.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
interface SummaryOptions {
  text: string; // => content to summarize
  maxWords: number; // => target word count
  style: "bullet" | "paragraph" | "executive"; // => output format
  audience: string; // => target reader description
}
 
function buildSummaryPrompt(opts: SummaryOptions): string {
  // => builds a parameterized prompt string
  return `
Summarize the following text for ${opts.audience}.
 
Format: ${
    opts.style === "bullet"
      ? "Use bullet points (- item)"
      : opts.style === "executive"
        ? "Executive summary paragraph, formal tone"
        : "One continuous paragraph"
  }
Target length: approximately ${opts.maxWords} words.
 
Text to summarize:
${opts.text}
`.trim();
  // => .trim() removes leading/trailing whitespace from template literal
  // => produces a clean, formatted prompt string
}
// => e.g. for audience='developers', style='bullet', maxWords=50:
// => "Summarize the following text for developers.\n\nFormat: Use bullet points..."
 
export async function summarize(opts: SummaryOptions): Promise<string> {
  const prompt = buildSummaryPrompt(opts);
  // => prompt is the assembled string
 
  const result = await generateText({
    model: openai("gpt-4o"),
    prompt,
    temperature: 0, // => deterministic output for consistent summaries
    maxTokens: opts.maxWords * 2,
    // => generous token budget: maxWords * 2 handles token-to-word ratio variation
  });
 
  return result.text;
  // => the formatted summary matching the requested style and audience
}

// app/api/stream/route.ts — Server side
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { NextRequest } from "next/server";
 
export async function POST(req: NextRequest) {
  const { prompt } = await req.json();
  // => extracts prompt from request body
 
  const result = await streamText({
    model: openai("gpt-4o"),
    prompt,
    maxTokens: 1024,
  });
  // => result holds the pending stream
 
  return result.toDataStreamResponse({
    headers: {
      "Cache-Control": "no-cache", // => prevent caching of streaming response
      Connection: "keep-alive", // => maintain persistent HTTP connection
    },
  });
  // => returns SSE Response — browser receives text/event-stream
  // => each chunk: "data: {text chunk}\n\n"
}

// lib/client/stream-reader.ts — runs in browser
export async function streamFromAPI(prompt: string): Promise<void> {
  const response = await fetch("/api/stream", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt }),
    // => sends POST with prompt in body
  });
  // => response is a ReadableStream (streaming HTTP response)
 
  const reader = response.body!.getReader();
  // => creates a ReadableStreamDefaultReader
  const decoder = new TextDecoder();
  // => decodes Uint8Array chunks to strings
 
  while (true) {
    const { done, value } = await reader.read();
    // => reads next chunk: { done: boolean, value: Uint8Array | undefined }
 
    if (done) break;
    // => stream ended: exit loop
 
    const text = decoder.decode(value, { stream: true });
    // => decodes bytes to string, stream: true handles multi-byte chars
    console.log("Chunk:", text);
    // => e.g. "Chunk: data: Hello\n\n"
  }
}

// server/express-stream.ts — Express.js example
import express from "express";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
 
const app = express();
app.use(express.json());
 
app.post("/stream", async (req, res) => {
  // => POST /stream: accepts { prompt } and streams response
 
  const { prompt } = req.body;
  // => extracts prompt from Express request body
 
  const result = await streamText({
    model: openai("gpt-4o"),
    prompt,
    maxTokens: 1024,
  });
  // => result.toReadableStream() converts AI stream to Node.js ReadableStream
 
  res.setHeader("Content-Type", "text/event-stream");
  // => tells client this is an SSE response
 
  res.setHeader("Cache-Control", "no-cache");
  // => prevents proxy caching of streaming response
 
  res.setHeader("Connection", "keep-alive");
  // => keeps TCP connection open for streaming
 
  const readable = result.toReadableStream();
  // => Node.js ReadableStream: compatible with res.pipe()
  // => toReadableStream() is for non-Next.js environments
  // => In Next.js: use toDataStreamResponse() instead
 
  for await (const chunk of readable) {
    // => iterates Node.js ReadableStream chunks
    res.write(chunk); // => writes each chunk to Express response
  }
 
  res.end();
  // => signals end of streaming response to client
});
 
app.listen(3000);
// => Express server listens on port 3000

// lib/ai/cancellation.ts
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
 
export async function streamWithTimeout(
  prompt: string,
  timeoutMs = 15000, // => default 15 second timeout
): Promise<string> {
  const controller = new AbortController();
  // => AbortController provides a signal that can cancel async operations
 
  const timeoutId = setTimeout(() => {
    controller.abort(new Error(`Generation timed out after ${timeoutMs}ms`));
    // => calls abort() after timeout: cancels the AI request
    // => passes an Error as the abort reason
  }, timeoutMs);
  // => setTimeout schedules the abort after timeoutMs milliseconds
 
  try {
    const result = await streamText({
      model: openai("gpt-4o"),
      prompt,
      maxTokens: 2048,
      abortSignal: controller.signal, // => passes signal to AI SDK
      // => SDK monitors signal.aborted: cancels HTTP request if true
    });
    // => result is the stream, tied to controller.signal
 
    let text = "";
    for await (const chunk of result.textStream) {
      text += chunk; // => accumulates streamed chunks
    }
    // => loop ends naturally if model finishes before timeout
 
    clearTimeout(timeoutId);
    // => cancel the timeout timer since generation succeeded
 
    return text;
    // => returns complete generated text
  } catch (error) {
    if ((error as Error).name === "AbortError") {
      throw new Error("Generation cancelled: timeout exceeded");
      // => converts AbortError to user-friendly message
    }
    throw error;
    // => re-throw other errors (network failures, API errors)
  }
}
 
// Client-side cancel on user action:
export function createCancellableGeneration() {
  const controller = new AbortController();
  // => controller for user-initiated cancellation
 
  const cancel = () => controller.abort();
  // => call cancel() to stop generation immediately
 
  return { controller, cancel };
  // => return both: pass controller.signal to SDK, expose cancel to UI
}

// lib/ai/vision.ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
 
export async function analyzeImageFromURL(imageUrl: string): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"), // => gpt-4o supports vision
    messages: [
      {
        role: "user",
        content: [
          {
            type: "image", // => image content part
            image: new URL(imageUrl), // => URL to the image
            // => AI SDK handles image URL fetching
          },
          {
            type: "text", // => text content part (in same message)
            text: "Describe what you see in this image in detail.",
            // => the question/instruction for the model
          },
        ],
        // => content array enables multimodal messages
        // => text + image in one user turn
      },
    ],
    maxTokens: 512,
  });
  // => result.text is the model's description of the image
 
  return result.text;
  // => e.g. "The image shows a bar chart with monthly revenue data..."
}
 
export async function analyzeImageFromBase64(
  base64Data: string,
  mimeType: "image/jpeg" | "image/png" | "image/webp" = "image/jpeg",
): Promise<string> {
  const result = await generateText({
    model: openai("gpt-4o"),
    messages: [
      {
        role: "user",
        content: [
          {
            type: "image",
            image: base64Data, // => base64 string (without data: prefix)
            mimeType, // => MIME type required for base64 images
            // => supports jpeg, png, webp, gif
          },
          {
            type: "text",
            text: "Extract all text visible in this image.",
            // => OCR-style instruction
          },
        ],
      },
    ],
    maxTokens: 1024,
  });
 
  return result.text;
  // => extracted text from the image
}

// lib/ai/embeddings.ts
import { embed } from "ai"; // => embedding generation function
import { openai } from "@ai-sdk/openai"; // => OpenAI embedding models
 
export async function getEmbedding(text: string): Promise<number[]> {
  const { embedding, usage } = await embed({
    model: openai.embedding("text-embedding-3-small"),
    // => text-embedding-3-small: 1536 dimensions, fast and cheap
    // => text-embedding-3-large: 3072 dimensions, higher accuracy
 
    value: text,
    // => the text to embed: single string
 
    maxRetries: 3,
    // => retry on transient failures (rate limits, network errors)
  });
  // => embedding: number[] with 1536 values (for text-embedding-3-small)
  // => each value is between -1 and 1
  // => embedding.length === 1536
 
  console.log(`Embedding dimensions: ${embedding.length}`);
  // => "Embedding dimensions: 1536"
 
  console.log(`Tokens used: ${usage.tokens}`);
  // => e.g. "Tokens used: 7" (for short text)
 
  return embedding;
  // => e.g. [-0.023, 0.145, 0.002, ..., -0.067] (1536 values)
}
 
// Example:
// const v = await getEmbedding('Zakat is 2.5% of savings');
// => v: [-0.023, 0.145, ...] (1536 floats representing the text's meaning)

// lib/ai/similarity.ts
import { embed, cosineSimilarity } from "ai"; // => cosineSimilarity built into ai@6
import { openai } from "@ai-sdk/openai";
 
export async function measureSimilarity(text1: string, text2: string): Promise<number> {
  // Embed both texts in parallel for efficiency:
  const [result1, result2] = await Promise.all([
    embed({ model: openai.embedding("text-embedding-3-small"), value: text1 }),
    embed({ model: openai.embedding("text-embedding-3-small"), value: text2 }),
    // => Promise.all: runs both embedding calls simultaneously
    // => saves ~300ms compared to sequential calls
  ]);
  // => result1.embedding: number[] for text1
  // => result2.embedding: number[] for text2
 
  const similarity = cosineSimilarity(result1.embedding, result2.embedding);
  // => cosineSimilarity(vectorA, vectorB): number between -1 and 1
  // => 1.0: identical direction (same meaning)
  // => 0.0: orthogonal (unrelated)
  // => -1.0: opposite direction (very rare in practice)
  // => RAG relevance threshold: typically 0.5 or higher
 
  return similarity;
  // => e.g. cosineSimilarity("cat", "dog") ≈ 0.82 (related animals)
  // => e.g. cosineSimilarity("cat", "quantum physics") ≈ 0.15 (unrelated)
}
 
// Demo:
// await measureSimilarity("Zakat calculation", "2.5% of nisab")  => ~0.78
// await measureSimilarity("Zakat calculation", "pizza recipe")   => ~0.12

// lib/ai/semantic-search.ts
import { embed, cosineSimilarity } from "ai";
import { openai } from "@ai-sdk/openai";
 
interface Document {
  id: string;
  content: string;
  embedding?: number[]; // => optional: populated after indexing
}
 
// Pre-index documents (run once at startup):
export async function indexDocuments(documents: Document[]): Promise<Document[]> {
  const indexed = await Promise.all(
    documents.map(async (doc) => {
      const { embedding } = await embed({
        model: openai.embedding("text-embedding-3-small"),
        value: doc.content, // => embed each document's content
      });
      return { ...doc, embedding }; // => attach embedding to document
    }),
  );
  // => indexed: Document[] where each has embedding: number[]
  return indexed;
}
 
// Search indexed documents:
export function semanticSearch(
  query: number[], // => query embedding vector
  documents: Document[], // => pre-indexed documents
  topK = 3, // => return top 3 results
  minSimilarity = 0.5, // => discard results below 0.5
): Array<{ document: Document; score: number }> {
  const scored = documents
    .filter((doc) => doc.embedding != null)
    // => skip documents that were not indexed yet
 
    .map((doc) => ({
      document: doc,
      score: cosineSimilarity(query, doc.embedding!),
      // => compute similarity between query and each document
    }))
    // => scored: [{ document, score: 0.82 }, { document, score: 0.45 }, ...]
 
    .filter(({ score }) => score >= minSimilarity)
    // => discard documents below relevance threshold (default: 0.5)
 
    .sort((a, b) => b.score - a.score)
    // => sort descending: most similar documents first
 
    .slice(0, topK);
  // => take only top K results
 
  return scored;
  // => e.g. [{ document: { id: '1', content: 'Zakat...' }, score: 0.82 }, ...]
}

// lib/ai/structured-output.ts
import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod"; // => Zod schema library for type-safe validation
 
const ProductSchema = z.object({
  name: z.string().describe("Product name"),
  // => describe() provides hints to the model about expected content
 
  price: z.number().min(0).describe("Price in USD"),
  // => z.number().min(0): validates non-negative price
 
  category: z.enum(["electronics", "clothing", "food", "other"]).describe("Product category"),
  // => z.enum: restricts to specific values
 
  inStock: z.boolean().describe("Whether the product is currently available"),
  features: z.array(z.string()).describe("List of key product features"),
  // => z.array(z.string()): typed array of strings
});
// => ProductSchema: Zod schema defining the expected output shape
// => TypeScript type: z.infer<typeof ProductSchema>
 
type Product = z.infer<typeof ProductSchema>;
// => Product: { name: string; price: number; category: ...; inStock: boolean; features: string[] }
 
export async function extractProduct(description: string): Promise<Product> {
  const { object } = await generateObject({
    model: openai("gpt-4o"),
    schema: ProductSchema, // => Zod schema constrains output
    prompt: `Extract product information from this description: ${description}`,
    temperature: 0, // => deterministic for consistent extraction
  });
  // => object: Product (fully typed, validated against ProductSchema)
  // => no JSON.parse() needed — SDK handles parsing and validation
 
  return object;
  // => e.g. { name: "Wireless Headphones", price: 99.99, category: "electronics",
  //           inStock: true, features: ["30h battery", "ANC", "Bluetooth 5.0"] }
}

// lib/ai/classification.ts
import { generateObject } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
 
const SentimentSchema = z.object({
  sentiment: z.enum(["POSITIVE", "NEGATIVE", "NEUTRAL"]).describe("The overall sentiment of the text"),
  confidence: z.number().min(0).max(1).describe("Confidence score from 0 to 1"),
  reasoning: z.string().describe("Brief explanation of the sentiment classification"),
});
// => SentimentSchema constrains output to exactly three labels
// => plus a confidence score and brief reasoning
 
export async function analyzeSentiment(text: string) {
  const { object } = await generateObject({
    model: openai("gpt-4o"),
    schema: SentimentSchema,
    system: "You are a precise sentiment classifier. Be objective and consistent.",
    prompt: `Classify the sentiment of: "${text}"`,
    temperature: 0, // => zero temperature: maximally consistent classification
  });
  // => object: { sentiment: 'POSITIVE'|'NEGATIVE'|'NEUTRAL', confidence: 0-1, reasoning: string }
 
  return object;
  // => e.g. { sentiment: 'POSITIVE', confidence: 0.95,
  //           reasoning: 'Enthusiastic language and positive outcome described' }
}
 
// Multi-label classification example:
const CategorySchema = z.object({
  primaryCategory: z.enum(["finance", "tech", "health", "sports", "other"]),
  // => single primary category
 
  tags: z.array(z.enum(["breaking", "opinion", "analysis", "interview"])).describe("Applicable content tags (0 to 4)"),
  // => multiple tags from a fixed set
 
  isSpam: z.boolean().describe("True if this appears to be spam or low quality"),
});
// => CategorySchema: multi-field classification schema

// app/api/generate-report/route.ts
import { streamObject } from "ai";
import { openai } from "@ai-sdk/openai";
import { NextRequest } from "next/server";
import { z } from "zod";
 
const ReportSchema = z.object({
  title: z.string(),
  summary: z.string().describe("2-3 sentence executive summary"),
  keyFindings: z.array(z.string()).describe("Top 5 findings"),
  recommendations: z
    .array(
      z.object({
        action: z.string(),
        priority: z.enum(["high", "medium", "low"]),
        impact: z.string(),
      }),
    )
    .describe("Actionable recommendations"),
  riskLevel: z.enum(["low", "medium", "high", "critical"]),
});
// => ReportSchema: complex nested object schema
 
export async function POST(req: NextRequest) {
  const { topic } = await req.json();
  // => topic: string — the subject of the report
 
  const result = await streamObject({
    model: openai("gpt-4o"),
    schema: ReportSchema, // => constrains output to ReportSchema shape
    prompt: `Generate a comprehensive analysis report on: ${topic}`,
    maxTokens: 2048,
  });
  // => result streams partial objects as the model generates them
 
  return result.toTextStreamResponse();
  // => streams partial JSON to the client
  // => client receives incremental object as it's built
  // => use result.toTextStreamResponse() for streamObject (not toDataStreamResponse)
}

// app/report/page.tsx
'use client';
import { useObject } from 'ai/react';   // => streaming object hook
import { z } from 'zod';
 
const ReportSchema = z.object({
  title: z.string(),
  summary: z.string(),
  keyFindings: z.array(z.string()),
  recommendations: z.array(
    z.object({ action: z.string(), priority: z.enum(['high', 'medium', 'low']), impact: z.string() })
  ),
  riskLevel: z.enum(['low', 'medium', 'high', 'critical']),
});
// => same schema as the server (share via a shared types file in production)
 
type Report = z.infer<typeof ReportSchema>;
 
export default function ReportPage() {
  const { object, submit, isLoading, error } = useObject<Report>({
    api: '/api/generate-report',        // => POST endpoint using streamObject
    schema: ReportSchema,               // => validates incoming partial object
  });
  // => object: DeepPartial<Report> — fields appear as the model generates them
  // => object.title: string | undefined (undefined until model writes it)
  // => object.keyFindings: string[] | undefined
 
  return (
    <div className="max-w-3xl mx-auto p-6 space-y-6">
      <button
        onClick={() => submit({ topic: 'AI regulation in financial services' })}
        // => submit() triggers POST with body { topic: '...' }
        disabled={isLoading}
        className="px-4 py-2 bg-blue-600 text-white rounded"
      >
        {isLoading ? 'Generating Report...' : 'Generate Report'}
      </button>
 
      {object?.title && (
        <h1 className="text-2xl font-bold">{object.title}</h1>
        // => title appears first, while other fields still generating
      )}
 
      {object?.summary && (
        <p className="text-gray-700">{object.summary}</p>
        // => summary appears once model generates it
      )}
 
      {object?.keyFindings && object.keyFindings.length > 0 && (
        <ul className="list-disc list-inside space-y-1">
          {object.keyFindings.map((finding, i) => (
            <li key={i}>{finding}</li>
            // => each finding appears as the model generates it
            // => list grows in real-time
          ))}
        </ul>
      )}
 
      {error && <p className="text-red-600">Error: {error.message}</p>}
    </div>
  );
}

// app/api/chat/route.ts — the server half of the chatbot
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { NextRequest } from "next/server";
 
export const runtime = "edge"; // => run on Vercel Edge for lowest latency
 
export async function POST(req: NextRequest) {
  const { messages } = await req.json();
  // => messages: CoreMessage[] — full conversation history from useChat
 
  const result = await streamText({
    model: openai("gpt-4o"),
    system: `You are a helpful assistant specializing in productivity and learning.
Be concise, friendly, and practical.`,
    // => system prompt defines the assistant's persona
 
    messages, // => full history enables multi-turn conversation
    maxTokens: 1024, // => reasonable cap for conversational responses
    temperature: 0.7, // => slight creativity for natural conversation
  });
 
  return result.toDataStreamResponse();
  // => CRITICAL: toDataStreamResponse() not StreamingTextResponse (removed in v6)
}

// app/chatbot/page.tsx — the client half of the chatbot
'use client';
import { useChat } from 'ai/react';
import { useRef, useEffect } from 'react';
 
export default function ChatbotPage() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } =
    useChat({ api: '/api/chat' });
  // => complete chat state managed by useChat hook
 
  const bottomRef = useRef<HTMLDivElement>(null);
  // => ref for auto-scrolling to bottom of message list
 
  useEffect(() => {
    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
    // => scrolls to newest message after each update
  }, [messages]);
  // => dependency: re-run effect whenever messages change
 
  return (
    <div className="flex flex-col h-screen max-w-2xl mx-auto">
      <header className="p-4 border-b font-bold text-lg">
        AI Assistant
        {/* => page title */}
      </header>
 
      <div className="flex-1 overflow-y-auto p-4 space-y-4">
        {messages.length === 0 && (
          <p className="text-gray-400 text-center mt-8">
            Start a conversation above.
          </p>
          // => empty state: shown before first message
        )}
 
        {messages.map((msg) => (
          <div
            key={msg.id}
            className={`flex ${msg.role === 'user' ? 'justify-end' : 'justify-start'}`}
            // => user messages right, assistant messages left
          >
            <div
              className={`max-w-xs lg:max-w-md px-4 py-2 rounded-lg ${
                msg.role === 'user'
                  ? 'bg-blue-600 text-white'        // => blue bubble for user
                  : 'bg-gray-100 text-gray-900'     // => gray bubble for assistant
              }`}
            >
              {msg.content}
              {/* => message text content */}
            </div>
          </div>
        ))}
 
        {isLoading && (
          <div className="flex justify-start">
            <div className="bg-gray-100 px-4 py-2 rounded-lg text-gray-500">
              Thinking...
              {/* => shown while model generates response */}
            </div>
          </div>
        )}
 
        <div ref={bottomRef} />
        {/* => invisible div at bottom — scrolled to on new messages */}
      </div>
 
      {error && (
        <p className="px-4 py-2 text-red-600 text-sm border-t">
          Error: {error.message}
        </p>
        // => error banner below messages
      )}
 
      <form
        onSubmit={handleSubmit}
        className="p-4 border-t flex gap-2"
      >
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type a message..."
          disabled={isLoading}           // => disable during generation
          className="flex-1 border rounded-lg px-3 py-2 focus:outline-none focus:ring-2"
          autoFocus
        />
        <button
          type="submit"
          disabled={isLoading || !input.trim()}
          // => disable if loading OR input is empty/whitespace
          className="px-4 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50"
        >
          Send
        </button>
      </form>
    </div>
  );
}