docs: Update README and example files for clarity and consistency in Cloudflare AI SDK usage

Author: professorice

packages/sdk/cloudflare-ai/README.md

@@ -1,11 +1,5 @@
 # LaunchDarkly AI SDK for Cloudflare Workers
 
-[![NPM][cf-ai-sdk-npm-badge]][cf-ai-sdk-npm-link]
-[![Actions Status][cf-ai-sdk-ci-badge]][cf-ai-sdk-ci]
-[![Documentation][cf-ai-sdk-ghp-badge]][cf-ai-sdk-ghp-link]
-[![NPM][cf-ai-sdk-dm-badge]][cf-ai-sdk-npm-link]
-[![NPM][cf-ai-sdk-dt-badge]][cf-ai-sdk-npm-link]
-
 # ⛔️⛔️⛔️⛔️
 
 > [!CAUTION]
@@ -19,17 +13,17 @@
 
 [![Twitter Follow](https://img.shields.io/twitter/follow/launchdarkly.svg?style=social&label=Follow&maxAge=2592000)](https://twitter.com/intent/follow?screen_name=launchdarkly)
 
-## Quick Setup
+## Quick start
 
-This assumes that you have already installed the LaunchDarkly Cloudflare server SDK and enabled the Cloudflare KV integration.
+Assumes you’ve installed the LaunchDarkly Cloudflare server SDK and enabled KV.
 
-1. Install this package with `npm` or `yarn`:
+1) Install:
 
 ```shell
 npm install @launchdarkly/cloudflare-server-sdk-ai --save
 ```
 
-2. Ensure Workers AI is bound and Node.js compatibility is enabled in `wrangler.toml`:
+2) Configure `wrangler.toml`:
 
 ```toml
 compatibility_flags = ["nodejs_compat"]
@@ -38,184 +32,59 @@ compatibility_flags = ["nodejs_compat"]
 binding = "AI"
 ```
 
-3. Create an AI SDK instance and evaluate a model configuration:
+3) Use in a Worker:
 
 ```typescript
 import { init } from '@launchdarkly/cloudflare-server-sdk';
 import { initAi } from '@launchdarkly/cloudflare-server-sdk-ai';
 
 export default {
-  async fetch(request, env, ctx) {
-    // Initialize the base LaunchDarkly client
+  async fetch(_request, env, ctx) {
     const ldClient = init(env.LD_CLIENT_ID, env.LD_KV, { sendEvents: true });
     await ldClient.waitForInitialization();
 
-    // Initialize the AI client (pass options to enable KV fast‑path)
-    const aiClient = initAi(ldClient, { clientSideID: env.LD_CLIENT_ID, kvNamespace: env.LD_KV });
-
-    // Set up the context properties
-    const context = {
-      kind: 'user',
-      key: 'example-user-key',
-      name: 'Sandy',
-    };
+    const ai = initAi(ldClient, { clientSideID: env.LD_CLIENT_ID, kvNamespace: env.LD_KV });
+    const context = { kind: 'user', key: 'example-user' };
 
-    // Get AI configuration
-    const aiConfig = await aiClient.config(
+    const config = await ai.config(
       'my-ai-config',
       context,
-      {
-        model: {
-          name: 'my-default-model',
-        },
-        enabled: true,
-      },
-      {
-        myVariable: 'My User Defined Variable',
-      },
+      { enabled: false, model: { name: '@cf/meta/llama-3-8b-instruct' } },
+      { username: 'Sandy' },
     );
-    const { tracker } = aiConfig;
-
-    if (aiConfig.enabled) {
-      // Map to Workers AI and run
-      const wc = aiConfig.toWorkersAI(env.AI);
-      const response = await env.AI.run(wc.model, wc);
 
-      // Ensure events are flushed after respond
-      ctx.waitUntil(ldClient.flush().finally(() => ldClient.close()));
+    if (!config.enabled) return new Response('AI disabled', { status: 503 });
 
-      return Response.json(response);
-    }
+    const wc = config.toWorkersAI(env.AI);
+    const result = await config.tracker.trackWorkersAIMetrics(() => env.AI.run(wc.model, wc));
 
-    return new Response('AI disabled', { status: 503 });
+    ctx.waitUntil(ldClient.flush().finally(() => ldClient.close()));
+    return Response.json(result);
   }
 };
 ```
 
-For a complete working example, see the `example/` directory.
-
-## API Reference
-
-### `initAi(ldClient, options?)`
-
-Initializes the AI client.
-
-**Parameters:**
-- `ldClient`: LaunchDarkly Cloudflare client instance
-- `options` (optional): `{ clientSideID?: string; kvNamespace?: KVNamespace }`
-  - If both `clientSideID` and `kvNamespace` are provided, the KV fast‑path is enabled.
-
-**Returns:** `LDAIClient`
-
-### `aiClient.config(key, context, defaultValue, variables?)`
-
-Retrieves an AI configuration from LaunchDarkly.
-
-**Parameters:**
-- `key`: Configuration key in LaunchDarkly
-- `context`: LaunchDarkly context for evaluation
-- `defaultValue`: Fallback configuration used only if evaluation data is unavailable
-- `variables` (optional): Variables for Mustache interpolation in `messages[].content`
-
-**Returns:** `Promise<LDAIConfig>`
-
-### `aiClient.agent(key, context, defaultValue, variables?)`
-
-Evaluates an AI Agent and returns interpolated `instructions` plus tracker and optional model/provider.
-
-**Parameters:** same shape as `config`, with `defaultValue` of type `LDAIAgentDefaults`.
-
-**Returns:** `Promise<LDAIAgent>`
-
-### `aiClient.agents(agentConfigs, context)`
-
-Evaluates multiple agents and returns a map of key to `LDAIAgent`.
-
-### `config.toWorkersAI(binding, options)`
-
-Converts the configuration to Cloudflare Workers AI format.
+See `example/` for a full working sample.
 
-**Parameters:**
-- `binding`: Workers AI binding (`env.AI`)
-- `options` (optional):
-  - `modelOverride`: Override the model
-  - `stream`: Enable streaming
-  - `additionalParams`: Additional parameters
+## API (brief)
 
-**Returns:** `WorkersAIConfig`
+• `initAi(ldClient, options?)` → `LDAIClient`
+• `aiClient.config(key, context, defaultValue, variables?)` → `Promise<LDAIConfig>`
+• `aiClient.agent(key, context, defaultValue, variables?)` → `Promise<LDAIAgent>`
+• `aiClient.agents(configs, context)` → `Promise<Record<key, LDAIAgent>>`
+• `config.toWorkersAI(env.AI, options?)` → `WorkersAIConfig`
 
-<!-- Optional convenience runner removed; call env.AI.run directly -->
-
-### Metrics Tracking
-
-```typescript
-config.tracker.trackSuccess();
-config.tracker.trackDuration(durationMs);
-config.tracker.trackMetrics({
-  durationMs: 150,
-  success: true,
-  usage: {
-    input: 50,
-    output: 100,
-    total: 150
-  }
-});
-config.tracker.trackFeedback('positive');
-```
-
-Workers AI helpers:
+Metrics:
 
 ```typescript
-// Non-streaming
-const result = await config.tracker.trackWorkersAIMetrics(async () => env.AI.run(wc.model, wc));
-
-// Streaming
+await config.tracker.trackWorkersAIMetrics(() => env.AI.run(wc.model, wc));
 const stream = config.tracker.trackWorkersAIStreamMetrics(() => env.AI.run(wc.model, { ...wc, stream: true }));
 ```
 
-Token usage normalization: Workers AI responses might include either `{ usage: { prompt_tokens, completion_tokens, total_tokens } }` or `{ usage: { input_tokens, output_tokens, total_tokens } }`. The SDK maps both to `{ input, output, total }`.
-
-## Supported Models
-
-Use full Workers AI model IDs in your LaunchDarkly AI configurations, for example:
-
-- `@cf/meta/llama-3.3-70b-instruct-fp8-fast`
-- `@cf/openai/gpt-oss-120b`
-- `@cf/mistralai/mistral-7b-instruct-v0.1`
+Notes:
+- Templates use Mustache. Variables you pass plus the LD context via `{{ldctx.*}}` are available.
+- Parameter names are normalized when mapping to Workers AI (e.g., `maxTokens`/`maxtokens` → `max_tokens`, `topP`/`topp` → `top_p`, `topK`/`topk` → `top_k`).
 
-See the Workers AI model catalog for more options: [Cloudflare Workers AI Models](https://developers.cloudflare.com/workers-ai/models/).
-
-## Roles and messages
-
-Supported roles in `messages` are `system`, `user`, and `assistant`. Example:
-
-```typescript
-const config = await aiClient.config('welcome_prompt', ctx, { enabled: true, model: { name: '@cf/meta/llama-3-8b-instruct' } }, {
-  username: 'Sandy',
-});
-
-// Messages are interpolated with Mustache
-// e.g., "Hello {{username}}" -> "Hello Sandy"
-const wc = config.toWorkersAI(env.AI);
-const res = await env.AI.run(wc.model, wc);
-```
-
-## Agents API
-
-```typescript
-const research = await aiClient.agent('research_agent', ctx, { enabled: true, instructions: 'You are a research assistant for {{topic}}.' }, { topic: 'climate change' });
-
-if (research.enabled) {
-  const wc = research.toWorkersAI(env.AI);
-  const res = await env.AI.run(wc.model, wc);
-  research.tracker.trackSuccess();
-}
-
-const agents = await aiClient.agents([
-  { key: 'research_agent', defaultValue: { enabled: true, instructions: 'You are a research assistant.' }, variables: { topic: 'climate change' } },
-  { key: 'writing_agent', defaultValue: { enabled: true, instructions: 'You are a writing assistant.' }, variables: { style: 'academic' } },
-] as const, ctx);
-```
 
 ## Contributing
 

packages/sdk/cloudflare-ai/example/README.md

@@ -63,9 +63,7 @@ Edit `wrangler.toml` and replace:
 ```toml
 compatibility_flags = ["nodejs_compat"]
 
-kv_namespaces = [
-  { binding = "LD_KV", id = "abc123...", preview_id = "def456..." }
-]
+kv_namespaces = [{ binding = "LD_KV", id = "YOUR_KV_ID", preview_id = "YOUR_PREVIEW_KV_ID" }]
 
 [vars]
 LD_CLIENT_ID = "LD_CLIENT_ID"
@@ -192,7 +190,7 @@ Expected response:
 1. **Initialize Clients**: Creates LaunchDarkly and AI clients
 2. **Get AI Config**: Retrieves `joke-ai-config` from LaunchDarkly with variables `{ joke_type, topic_section }`
 3. **Variable Interpolation**: Fills `{{joke_type}}` and `{{topic_section}}` in messages
-4. **Call AI Model**: Uses `env.AI.run(wc.model, wc)` to run the model
+4. **Call AI Model**: Map to Workers AI via `config.toWorkersAI(env.AI)` and run with metrics using `await config.tracker.trackWorkersAIMetrics(() => env.AI.run(wc.model, wc))`
 5. **Flush Events**: Uses `ctx.waitUntil(ldClient.flush().finally(() => ldClient.close()))`
 
 ## LaunchDarkly Features

packages/sdk/cloudflare-ai/example/src/index.ts

@@ -50,8 +50,10 @@ export default {
         );
       }
 
-      const wc = (config as any).toWorkersAI(env.AI);
-      const response = await env.AI.run(wc.model, wc);
+      const wc = config.toWorkersAI(env.AI);
+      // Workers AI bindings have many possible outputs; cast to a minimal type that includes optional usage.
+      type WorkersAIResultWithUsage = { usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number; input_tokens?: number; output_tokens?: number } } | unknown;
+      const response = (await config.tracker.trackWorkersAIMetrics(() => env.AI.run(wc.model as any, wc as any))) as WorkersAIResultWithUsage;
 
       // Ensure events are flushed after the response is returned
       ctx.waitUntil(ldClient.flush().finally(() => ldClient.close()));
@@ -63,7 +65,7 @@ export default {
           topic,
           model: config.model?.name,
           provider: config.provider?.name || 'cloudflare-workers-ai',
-          joke: (response as any).response || response,
+          joke: (response as any)?.response || (response as any),
           enabled: config.enabled,
         }),
         {

packages/sdk/cloudflare-ai/example/wrangler.toml

@@ -5,7 +5,7 @@ compatibility_flags = ["nodejs_compat"]
 
 # KV namespaces for LaunchDarkly data
 # Make sure this ID matches the namespace in your LaunchDarkly Cloudflare KV integration
-kv_namespaces = kv_namespaces = [{ binding = "LD_KV", id = "YOUR_KV_ID", preview_id = "YOUR_PREVIEW_KV_ID" }]
+kv_namespaces = [{ binding = "LD_KV", id = "YOUR_KV_ID", preview_id = "YOUR_PREVIEW_KV_ID" }]
 
 # Replace with your LaunchDarkly client-side ID
 [vars]