@adia-ai/llm 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# @adia-ai/llm
+
+All notable changes to this package are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+_No pending changes._
+
+## [0.3.0] - 2026-05-05
+
+**Initial release as the 9th `@adia-ai/*` lockstep package.** Joins the lockstep at the cut version. All 9 published `@adia-ai/*` packages now share one version, governed by [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy).
+
+### Added
+
+- Provider-agnostic LLM client. Three adapters (anthropic / openai / gemini) behind a single `chat()` + `streamChat()` facade. Works in browser (with `proxyUrl`) and Node.
+- `chat()`, `streamChat()`, `createClient()` facade in `@adia-ai/llm` (default export).
+- `createAdapter()` bridge for the A2UI generation pipeline at `@adia-ai/llm/bridge`.
+- `StubLLMAdapter` for deterministic tests at `@adia-ai/llm/stub`.
+- Direct adapter access at `@adia-ai/llm/adapters/{anthropic,openai,gemini}` for callers that need the raw adapter object.
+- **Browser proxy mode.** Pass `proxyUrl` to `streamChat`/`chat` and the client speaks a provider-neutral protocol to your proxy: `{ provider, model, messages, system?, maxTokens?, temperature?, thinking?, stream }`. The proxy holds the real API key and reformats per upstream; the adapter still parses the SSE response stream verbatim. Reference proxy implementation ships at `packages/llm/server.js` (run via `npm run proxy` from the chat-ui repo root).
+
+### Why this is its own package
+
+The LLM adapters previously lived under `@adia-ai/a2ui-compose/llm` but were consumed by `chat-shell` (web-modules) outside any A2UI generation concern — leaking the boundary. `chat-shell` shouldn't depend on `@adia-ai/a2ui-compose` to talk to OpenAI. As a sibling-shaped foundational primitive, `@adia-ai/llm` lets compose, chat, MCP synthesis, and any other surface depend on the LLM client without pulling the generator graph.
+
+### Migration from `@adia-ai/a2ui-compose/llm`
+
+Consumers should rewrite imports:
+
+```diff
+- import { streamChat } from '@adia-ai/a2ui-compose/llm/adapters/index.js';
++ import { streamChat } from '@adia-ai/llm';
+
+- import { createAdapter } from '@adia-ai/a2ui-compose/llm/llm-bridge.js';
++ import { createAdapter } from '@adia-ai/llm/bridge';
+
+- import { StubLLMAdapter } from '@adia-ai/a2ui-compose/llm/llm-stub.js';
++ import { StubLLMAdapter } from '@adia-ai/llm/stub';
+```
+
+`@adia-ai/a2ui-compose@0.3.0` no longer exports `./llm` — see its CHANGELOG.
+
+### Proxy-mode protocol fix
+
+In v0.3.0, proxy-mode requests now correctly include `provider` in the body and drop the `Authorization: Bearer ${apiKey}` header (which was previously emitted with `apiKey: undefined` when `proxyUrl` was set). Two stacked bugs that affected anyone using `proxyUrl` in v0.2.x:
+1. The proxy received bodies without `provider`, defaulted to `anthropic`, and routed `gpt-4o-mini` requests to Anthropic → 404 model-not-found.
+2. `Authorization: Bearer undefined` appeared in headers when the client didn't carry an API key (proxy-only deployments).
+
+Both fixed in v0.3.0. The chat playground at `apps/chat/app/chat.html` exercises this path.

package/README.md

@@ -0,0 +1,67 @@
+# `@adia-ai/llm`
+
+Provider-agnostic LLM client. Three adapters (anthropic / openai / gemini)
+behind a single `chat()` + `streamChat()` facade. Works in browser and Node.
+
+```js
+import { chat, streamChat } from '@adia-ai/llm';
+
+// Direct API call (apiKey owned by the caller)
+const reply = await chat({
+  apiKey: 'sk-...',
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+
+// Streaming
+for await (const chunk of streamChat({
+  apiKey: 'sk-...',
+  model: 'claude-haiku-4-5-20251001',
+  messages: [{ role: 'user', content: 'Hello' }],
+})) {
+  if (chunk.type === 'text') process.stdout.write(chunk.text);
+}
+```
+
+## Browser proxy mode
+
+Pass `proxyUrl` to route through your server-side proxy (which holds the
+API key). The client speaks a provider-neutral protocol to the proxy:
+
+```js
+for await (const chunk of streamChat({
+  proxyUrl: '/api/chat',
+  provider: 'openai',          // optional — auto-detected from model
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello' }],
+})) { /* ... */ }
+```
+
+The body sent to the proxy:
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "system": "...optional...",
+  "maxTokens": 4096,
+  "temperature": 0.7,
+  "stream": true
+}
+```
+
+The proxy reformats per upstream provider and pipes the SSE bytes
+verbatim. The reference proxy implementation is at `server.js` in the
+chat-ui repo root.
+
+## Subpath exports
+
+| Subpath | Purpose |
+|---------|---------|
+| `@adia-ai/llm` | Default: `chat`, `streamChat`, `createClient` |
+| `@adia-ai/llm/bridge` | `createAdapter` — wraps the facade in the A2UI pipeline's adapter interface |
+| `@adia-ai/llm/stub` | `StubLLMAdapter` — deterministic adapter for tests |
+| `@adia-ai/llm/adapters/anthropic` | Direct adapter object |
+| `@adia-ai/llm/adapters/openai` | Direct adapter object |
+| `@adia-ai/llm/adapters/gemini` | Direct adapter object |

package/adapters/anthropic.js

@@ -0,0 +1,106 @@
+/**
+ * Anthropic Messages API adapter.
+ * Endpoint: https://api.anthropic.com/v1/messages
+ */
+
+import { readSSE } from './sse.js';
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const DEFAULT_MAX_TOKENS = 4096;
+
+export const anthropic = {
+  name: 'anthropic',
+
+  buildRequest(opts) {
+    const body = {
+      model: opts.model,
+      max_tokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
+      messages: opts.messages,
+      stream: !!opts.stream,
+    };
+    if (opts.system) {
+      // Prompt caching: the AdiaUI system prompt is ~23KB and constant across
+      // a session. Emitting it as a cached block marks it as a cache breakpoint
+      // (ephemeral, ~5 min TTL). First call = cache write (+25% cost), every
+      // subsequent call in the window = cache read (−90% cost). No-op below
+      // the model's minimum cacheable size (1024 tok Sonnet/Opus, 2048 Haiku).
+      body.system = opts.cache
+        ? [{ type: 'text', text: opts.system, cache_control: { type: 'ephemeral' } }]
+        : opts.system;
+    }
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.thinking) {
+      body.thinking = { type: 'enabled', budget_tokens: opts.thinkingBudget || 10000 };
+    }
+
+    return {
+      url: API_URL,
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': opts.apiKey,
+        'anthropic-version': API_VERSION,
+      },
+      body,
+    };
+  },
+
+  parseResponse(data) {
+    const text = data.content?.find(b => b.type === 'text')?.text ?? '';
+    return {
+      text,
+      usage: {
+        input: data.usage?.input_tokens ?? 0,
+        output: data.usage?.output_tokens ?? 0,
+        // Cache telemetry: non-zero cacheRead on turn 2+ is the signal that
+        // caching is actually kicking in. Recorded per-turn for hit-rate analysis.
+        cacheCreation: data.usage?.cache_creation_input_tokens ?? 0,
+        cacheRead: data.usage?.cache_read_input_tokens ?? 0,
+      },
+      stopReason: data.stop_reason ?? 'end',
+    };
+  },
+
+  async *parseStream(response) {
+    let snapshot = '';
+    let usage = { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 };
+    let stopReason = 'end';
+
+    for await (const event of readSSE(response.body)) {
+      if (event.done) break;
+      let data;
+      try { data = JSON.parse(event.data); } catch { continue; }
+      const eventType = event.event ?? data.type;
+
+      switch (eventType) {
+        case 'message_start':
+          if (data.message?.usage) {
+            usage.input = data.message.usage.input_tokens ?? 0;
+            usage.cacheCreation = data.message.usage.cache_creation_input_tokens ?? 0;
+            usage.cacheRead = data.message.usage.cache_read_input_tokens ?? 0;
+          }
+          break;
+        case 'content_block_delta': {
+          const delta = data.delta;
+          if (delta?.type === 'text_delta') {
+            snapshot += delta.text;
+            yield { type: 'text', text: delta.text, snapshot };
+          } else if (delta?.type === 'thinking_delta') {
+            yield { type: 'thinking', text: delta.thinking };
+          }
+          break;
+        }
+        case 'message_delta':
+          if (data.delta?.stop_reason) stopReason = data.delta.stop_reason;
+          if (data.usage) usage.output = data.usage.output_tokens ?? 0;
+          break;
+        case 'message_stop':
+          yield { type: 'done', text: snapshot, usage, stopReason };
+          break;
+        case 'error':
+          yield { type: 'error', error: new Error(data.error?.message ?? 'Stream error') };
+          break;
+      }
+    }
+  },
+};

package/adapters/gemini.js

@@ -0,0 +1,99 @@
+/**
+ * Google Gemini generateContent API adapter.
+ * Endpoint: https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
+ * Streaming: .../{model}:streamGenerateContent?alt=sse
+ */
+
+import { readSSE } from './sse.js';
+
+const API_URL = 'https://generativelanguage.googleapis.com/v1beta/models';
+const DEFAULT_MAX_TOKENS = 4096;
+
+export const gemini = {
+  name: 'gemini',
+
+  buildRequest(opts) {
+    const model = opts.model;
+    const contents = [];
+    for (const msg of opts.messages) {
+      contents.push({
+        role: msg.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: msg.content }],
+      });
+    }
+
+    const body = { contents };
+
+    if (opts.system) {
+      body.systemInstruction = { parts: [{ text: opts.system }] };
+    }
+
+    const generationConfig = {
+      maxOutputTokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
+    };
+    if (opts.temperature != null) generationConfig.temperature = opts.temperature;
+    body.generationConfig = generationConfig;
+
+    const action = opts.stream
+      ? `streamGenerateContent?alt=sse`
+      : 'generateContent';
+
+    return {
+      url: `${API_URL}/${model}:${action}`,
+      headers: {
+        'content-type': 'application/json',
+        'x-goog-api-key': opts.apiKey,
+      },
+      body,
+    };
+  },
+
+  parseResponse(data) {
+    const parts = data.candidates?.[0]?.content?.parts ?? [];
+    const text = parts.map(p => p.text ?? '').join('');
+    return {
+      text,
+      usage: {
+        input: data.usageMetadata?.promptTokenCount ?? 0,
+        output: data.usageMetadata?.candidatesTokenCount ?? 0,
+      },
+      stopReason: data.candidates?.[0]?.finishReason === 'STOP' ? 'end' : 'end',
+    };
+  },
+
+  async *parseStream(response) {
+    let snapshot = '';
+    let usage = { input: 0, output: 0 };
+    let stopReason = 'end';
+
+    for await (const event of readSSE(response.body)) {
+      if (event.done) break;
+      let data;
+      try { data = JSON.parse(event.data); } catch { continue; }
+
+      if (data.usageMetadata) {
+        usage.input = data.usageMetadata.promptTokenCount ?? 0;
+        usage.output = data.usageMetadata.candidatesTokenCount ?? 0;
+      }
+
+      const candidate = data.candidates?.[0];
+      if (!candidate) continue;
+
+      if (candidate.finishReason && candidate.finishReason !== 'STOP') {
+        stopReason = candidate.finishReason;
+      }
+
+      const parts = candidate.content?.parts;
+      if (!parts?.length) continue;
+
+      for (const part of parts) {
+        if (part.text != null) {
+          snapshot += part.text;
+          yield { type: 'text', text: part.text, snapshot };
+        }
+      }
+    }
+
+    yield { type: 'done', text: snapshot, usage, stopReason };
+  },
+};

package/adapters/index.js

@@ -0,0 +1,170 @@
+/**
+ * LLM Client — Provider-agnostic chat interface.
+ *
+ * Usage:
+ *   import { createClient, chat, streamChat } from './llm/index.js';
+ *
+ *   // Quick use (provider auto-detected from model name)
+ *   const reply = await chat({
+ *     apiKey: 'sk-ant-...',
+ *     model: 'claude-sonnet-4-20250514',
+ *     messages: [{ role: 'user', content: 'Hello' }],
+ *   });
+ *
+ *   for await (const chunk of streamChat({
+ *     apiKey: 'sk-...',
+ *     model: 'gpt-4o',
+ *     messages: [{ role: 'user', content: 'Hello' }],
+ *   })) {
+ *     if (chunk.type === 'text') process.stdout.write(chunk.text);
+ *   }
+ *
+ *   // Explicit provider
+ *   const reply = await chat({ provider: 'gemini', apiKey: '...', model: 'gemini-2.5-flash', ... });
+ *
+ *   // Reusable client instance
+ *   const client = createClient({ provider: 'anthropic', apiKey: '...' });
+ *   const reply = await client.chat({ model: 'claude-sonnet-4-20250514', messages: [...] });
+ *   for await (const chunk of client.stream({ model: '...', messages: [...] })) { ... }
+ *
+ * Chunk types (streaming):
+ *   { type: 'text',     text: 'delta', snapshot: 'full text so far' }
+ *   { type: 'thinking', text: 'thinking delta' }
+ *   { type: 'done',     text: 'full response', usage: { input, output }, stopReason }
+ *   { type: 'error',    error: Error }
+ */
+
+import { anthropic } from './anthropic.js';
+import { openai } from './openai.js';
+import { gemini } from './gemini.js';
+
+// ── Provider registry ──
+
+const providers = { anthropic, openai, gemini };
+
+/** Detect provider from model name. */
+function detectProvider(model) {
+  if (!model) return null;
+  const m = model.toLowerCase();
+  if (m.includes('claude') || m.startsWith('anthropic/')) return 'anthropic';
+  if (m.includes('gpt') || m.includes('o1') || m.includes('o3') || m.includes('o4') || m.startsWith('openai/')) return 'openai';
+  if (m.includes('gemini') || m.startsWith('google/')) return 'gemini';
+  return null;
+}
+
+function resolveAdapter(opts) {
+  const name = opts.provider || detectProvider(opts.model);
+  if (!name) throw new Error(`Cannot detect provider for model "${opts.model}". Set provider explicitly.`);
+  const adapter = providers[name];
+  if (!adapter) throw new Error(`Unknown provider "${name}". Available: ${Object.keys(providers).join(', ')}`);
+  return adapter;
+}
+
+// ── Proxy mode ──
+//
+// When `proxyUrl` is set, the client speaks a provider-neutral protocol
+// to the proxy: { provider, model, messages, system?, maxTokens?,
+// temperature?, thinking?, stream }. The proxy holds the real API key
+// and reformats per upstream provider. Each adapter still parses the
+// upstream's streamed body via its own parseStream — the proxy pipes
+// the SSE bytes verbatim.
+
+function proxyRequest(opts, stream) {
+  const provider = opts.provider || detectProvider(opts.model);
+  const body = {
+    provider,
+    model: opts.model,
+    messages: opts.messages,
+    stream,
+  };
+  if (opts.system != null)      body.system = opts.system;
+  if (opts.maxTokens != null)   body.maxTokens = opts.maxTokens;
+  if (opts.temperature != null) body.temperature = opts.temperature;
+  if (opts.thinking != null)    body.thinking = opts.thinking;
+  return {
+    url: opts.proxyUrl,
+    headers: { 'content-type': 'application/json' },
+    body,
+  };
+}
+
+// ── Standalone functions ──
+
+/**
+ * Non-streaming chat completion.
+ * @returns {Promise<{text: string, usage: {input: number, output: number}, stopReason: string}>}
+ */
+export async function chat(opts) {
+  const adapter = resolveAdapter(opts);
+  const { url, headers, body } = opts.proxyUrl
+    ? proxyRequest(opts, false)
+    : adapter.buildRequest({ ...opts, stream: false });
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: opts.signal,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err?.error?.message || `${adapter.name} API error ${res.status}`);
+  }
+
+  return adapter.parseResponse(await res.json());
+}
+
+/**
+ * Streaming chat — yields chunks as they arrive.
+ * @returns {AsyncGenerator<{type: string, text?: string, snapshot?: string, usage?: object, error?: Error}>}
+ */
+export async function* streamChat(opts) {
+  const adapter = resolveAdapter(opts);
+  const { url, headers, body } = opts.proxyUrl
+    ? proxyRequest(opts, true)
+    : adapter.buildRequest({ ...opts, stream: true });
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: opts.signal,
+    });
+  } catch (err) {
+    yield { type: 'error', error: err };
+    return;
+  }
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    yield { type: 'error', error: new Error(err?.error?.message || `${adapter.name} API error ${res.status}`) };
+    return;
+  }
+
+  yield* adapter.parseStream(res);
+}
+
+// ── Client factory ──
+
+/**
+ * Create a reusable client instance with defaults baked in.
+ *
+ * @param {object} defaults
+ * @param {string} defaults.provider — 'anthropic' | 'openai' | 'gemini'
+ * @param {string} defaults.apiKey
+ * @param {string} [defaults.model] — default model
+ * @param {string} [defaults.proxyUrl] — proxy URL (for CORS)
+ * @param {string} [defaults.system] — default system prompt
+ */
+export function createClient(defaults = {}) {
+  return {
+    chat: (opts) => chat({ ...defaults, ...opts }),
+    stream: (opts) => streamChat({ ...defaults, ...opts }),
+  };
+}
+
+// Re-export adapters for direct use
+export { anthropic, openai, gemini };

package/adapters/openai.js

@@ -0,0 +1,85 @@
+/**
+ * OpenAI Chat Completions API adapter.
+ * Endpoint: https://api.openai.com/v1/chat/completions
+ * Also compatible with: Groq, Together, Mistral, any OpenAI-compatible API.
+ */
+
+import { readSSE } from './sse.js';
+
+const API_URL = 'https://api.openai.com/v1/chat/completions';
+const DEFAULT_MAX_TOKENS = 4096;
+
+export const openai = {
+  name: 'openai',
+
+  buildRequest(opts) {
+    const messages = [];
+    if (opts.system) messages.push({ role: 'system', content: opts.system });
+    for (const msg of opts.messages) {
+      messages.push({ role: msg.role, content: msg.content });
+    }
+
+    const body = {
+      model: opts.model,
+      messages,
+      stream: !!opts.stream,
+    };
+    if (opts.maxTokens) body.max_tokens = opts.maxTokens;
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.stream) body.stream_options = { include_usage: true };
+
+    return {
+      url: API_URL,
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${opts.apiKey}`,
+      },
+      body,
+    };
+  },
+
+  parseResponse(data) {
+    const choice = data.choices?.[0];
+    const text = choice?.message?.content ?? '';
+    return {
+      text,
+      usage: { input: data.usage?.prompt_tokens ?? 0, output: data.usage?.completion_tokens ?? 0 },
+      stopReason: choice?.finish_reason === 'stop' ? 'end' : (choice?.finish_reason ?? 'end'),
+    };
+  },
+
+  async *parseStream(response) {
+    let snapshot = '';
+    let usage = { input: 0, output: 0 };
+    let stopReason = 'end';
+
+    for await (const event of readSSE(response.body)) {
+      if (event.done) break;
+      let data;
+      try { data = JSON.parse(event.data); } catch { continue; }
+
+      if (data.usage) {
+        usage.input = data.usage.prompt_tokens ?? 0;
+        usage.output = data.usage.completion_tokens ?? 0;
+      }
+
+      const choice = data.choices?.[0];
+      if (!choice) continue;
+
+      if (choice.finish_reason) {
+        stopReason = choice.finish_reason === 'stop' ? 'end' : choice.finish_reason;
+      }
+
+      const delta = choice.delta;
+      if (delta?.content) {
+        snapshot += delta.content;
+        yield { type: 'text', text: delta.content, snapshot };
+      }
+      if (delta?.reasoning_content) {
+        yield { type: 'thinking', text: delta.reasoning_content };
+      }
+    }
+
+    yield { type: 'done', text: snapshot, usage, stopReason };
+  },
+};

package/adapters/sse.js

@@ -0,0 +1,50 @@
+/**
+ * SSE Parser — shared by Anthropic, OpenAI, and Gemini adapters.
+ * Handles partial line buffering, double-newline splitting, and [DONE] detection.
+ */
+
+export async function* readSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const { events, remainder } = parse(buffer);
+      buffer = remainder;
+      for (const event of events) yield event;
+    }
+    if (buffer.trim()) {
+      const { events } = parse(buffer + '\n\n');
+      for (const event of events) yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parse(text) {
+  const events = [];
+  const parts = text.split(/\n\n|\r\n\r\n/);
+  const remainder = parts.pop() ?? '';
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    let eventType;
+    const dataLines = [];
+    for (const line of trimmed.split(/\r?\n/)) {
+      if (line.startsWith(':')) continue;
+      if (line.startsWith('event:')) eventType = line.slice(6).trim();
+      else if (line.startsWith('data:')) {
+        const v = line.slice(5);
+        dataLines.push(v.startsWith(' ') ? v.slice(1) : v);
+      }
+    }
+    if (!dataLines.length) continue;
+    const data = dataLines.join('\n');
+    events.push({ event: eventType, data, done: data === '[DONE]' });
+  }
+  return { events, remainder };
+}

package/index.js

@@ -0,0 +1,17 @@
+/**
+ * @adia-ai/llm — provider-agnostic LLM client.
+ *
+ * Re-exports the adapters facade so `@adia-ai/llm` is the single entry
+ * point for chat-shell, the a2ui generation pipeline, and any other
+ * consumer that needs to talk to anthropic / openai / gemini.
+ *
+ *   import { chat, streamChat, createClient } from '@adia-ai/llm';
+ *   import { createAdapter } from '@adia-ai/llm/bridge';
+ *   import { StubLLMAdapter } from '@adia-ai/llm/stub';
+ */
+
+export {
+  chat,
+  streamChat,
+  createClient,
+} from './adapters/index.js';

package/llm-bridge.js

@@ -0,0 +1,214 @@
+/**
+ * LLM Bridge — Wraps AdiaUI's llm module into the AdiaUI createAdapter() API.
+ *
+ * This is the single integration point between the AdiaUI pipeline and the
+ * LLM module. It handles:
+ *   - Env var reading (VITE_* in browser, process.env in Node)
+ *   - CORS proxy routing in browser (Vite dev server at /api/llm/*)
+ *   - API translation (AdiaUI's simple { messages, systemPrompt } → llm module's interface)
+ *
+ * Consumers call createAdapter() and get an object with .complete() and .stream()
+ * matching the AdiaUI pipeline interface.
+ */
+
+import { StubLLMAdapter } from './llm-stub.js';
+
+// Lazy-loaded — ../llm/index.js uses Vite aliases that don't resolve in Node
+let _createClient = null;
+async function getCreateClient() {
+  if (!_createClient) {
+    try {
+      const mod = await import('./adapters/index.js');
+      _createClient = mod.createClient;
+    } catch {
+      _createClient = null;
+    }
+  }
+  return _createClient;
+}
+
+// ── Environment ──────────────────────────────────────────────────────────
+
+function getEnv(key) {
+  try {
+    const env = import.meta.env;
+    if (env) {
+      const val = env[`VITE_${key}`] || env[key];
+      if (val) return val;
+    }
+  } catch {}
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env[key] || '';
+  }
+  return '';
+}
+
+const IS_BROWSER = typeof window !== 'undefined';
+
+function resolveBaseUrl(provider) {
+  if (!IS_BROWSER) return undefined; // Let the module use its defaults
+  const proxyMap = {
+    anthropic: '/api/llm/anthropic/v1/messages',
+    openai: '/api/llm/openai/v1/chat/completions',
+    google: '/api/llm/google',
+  };
+  return proxyMap[provider];
+}
+
+// ── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create an LLM adapter for the AdiaUI pipeline.
+ *
+ * Auto-detects provider from env vars. Returns an object with .complete()
+ * and .stream() that match the AdiaUI interface (simple messages + systemPrompt).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.provider] — 'anthropic' | 'openai' | 'google' | 'stub'
+ * @param {string} [opts.apiKey] — explicit API key (overrides env)
+ * @param {string} [opts.model] — model override
+ * @returns {StubLLMAdapter | AdiaUILLMBridge}
+ */
+export async function createAdapter(opts = {}) {
+  const provider = opts.provider || getEnv('LLM_PROVIDER') || detectProvider();
+  const model = opts.model || getEnv('LLM_MODEL') || undefined;
+
+  if (provider === 'stub') return new StubLLMAdapter();
+
+  // Resolve API key for the detected provider
+  const apiKey = opts.apiKey || getEnv(`${provider.toUpperCase()}_API_KEY`) || getEnv('ANTHROPIC_API_KEY') || getEnv('OPENAI_API_KEY') || getEnv('GOOGLE_API_KEY');
+
+  // No key found → fall back to stub
+  if (!apiKey) {
+    console.warn('LLM Bridge: No API keys found. Using stub adapter.');
+    return new StubLLMAdapter();
+  }
+
+  const createClient = await getCreateClient();
+  if (!createClient) {
+    console.warn('LLM Bridge: LLM module not available. Using stub adapter.');
+    return new StubLLMAdapter();
+  }
+
+  const proxyUrl = resolveBaseUrl(provider);
+  const client = createClient({
+    provider,
+    apiKey,
+    model: model || DEFAULT_MODELS[provider] || 'claude-sonnet-4-20250514',
+    ...(proxyUrl ? { proxyUrl } : {}),
+  });
+
+  return new AdiaUILLMBridge(client, model || DEFAULT_MODELS[provider] || 'claude-sonnet-4-20250514', provider);
+}
+
+function detectProvider() {
+  if (getEnv('ANTHROPIC_API_KEY')) return 'anthropic';
+  if (getEnv('OPENAI_API_KEY')) return 'openai';
+  if (getEnv('GOOGLE_API_KEY')) return 'google';
+  return 'stub';
+}
+
+// ── Bridge class ─────────────────────────────────────────────────────────
+
+/** Default models per provider */
+const DEFAULT_MODELS = {
+  anthropic: 'claude-sonnet-4-20250514',
+  openai: 'gpt-4o',
+  google: 'gemini-2.0-flash',
+};
+
+/**
+ * Wraps the AdiaUI llm client to match the AdiaUI pipeline's simpler interface.
+ *
+ * AdiaUI calls: adapter.complete({ messages, systemPrompt })
+ * LLM module expects: client.chat({ model, messages, system, ... })
+ */
+class AdiaUILLMBridge {
+  #client;
+  #model;
+  #provider;
+
+  constructor(client, model, provider) {
+    this.#client = client;
+    this.#model = model;
+    this.#provider = provider;
+  }
+
+  /**
+   * Non-streaming completion. Matches AdiaUI interface.
+   *
+   * 32k max_tokens: A2UI JSON for moderately complex UIs (kanban, dashboard,
+   * pricing table) routinely exceeds 8k. Truncation produced silent fallbacks
+   * that the validator rubber-stamped at ~89/100 — see diagnosis report
+   * 2026-04-19. Modern Claude/GPT/Gemini all support ≥32k output cleanly.
+   *
+   * @param {{ messages: { role: string, content: string }[], systemPrompt?: string }} opts
+   * @returns {Promise<{ content: string, stopReason: string, usage: { inputTokens: number, outputTokens: number } }>}
+   */
+  async complete({ messages, systemPrompt }) {
+    const response = await this.#client.chat({
+      model: this.#model,
+      messages,
+      system: systemPrompt,
+      maxTokens: 32768,
+      // Anthropic-only: mark the system prompt as a cache breakpoint. No-op
+      // on other providers (unknown opt silently ignored) and no-op below the
+      // model's minimum cacheable size.
+      cache: this.#provider === 'anthropic',
+    });
+    return {
+      content: response.text,
+      // 'max_tokens' / 'length' / 'MAX_TOKENS' (Gemini) signal truncation;
+      // downstream parser uses this to refuse silent fallback rendering.
+      stopReason: response.stopReason ?? 'end',
+      usage: {
+        inputTokens: response.usage?.input ?? 0,
+        outputTokens: response.usage?.output ?? 0,
+        cacheCreationTokens: response.usage?.cacheCreation ?? 0,
+        cacheReadTokens: response.usage?.cacheRead ?? 0,
+      },
+    };
+  }
+
+  /**
+   * Streaming completion. Matches AdiaUI interface.
+   *
+   * @param {{ messages: { role: string, content: string }[], systemPrompt?: string }} opts
+   * @yields {{ type: 'text', content: string } | { type: 'done', stopReason: string, usage: { inputTokens: number, outputTokens: number, cacheCreationTokens: number, cacheReadTokens: number } }}
+   */
+  async *stream({ messages, systemPrompt }) {
+    for await (const chunk of this.#client.stream({
+      model: this.#model,
+      messages,
+      system: systemPrompt,
+      maxTokens: 32768,
+      cache: this.#provider === 'anthropic',
+    })) {
+      if (chunk.type === 'text') {
+        yield { type: 'text', content: chunk.text };
+      } else if (chunk.type === 'done') {
+        // Surface the terminal stopReason + cache telemetry so the consumer
+        // can detect max_tokens truncation and the dialog recorder can log
+        // cache hit-rate per turn.
+        yield {
+          type: 'done',
+          stopReason: chunk.stopReason ?? 'end',
+          usage: {
+            inputTokens: chunk.usage?.input ?? 0,
+            outputTokens: chunk.usage?.output ?? 0,
+            cacheCreationTokens: chunk.usage?.cacheCreation ?? 0,
+            cacheReadTokens: chunk.usage?.cacheRead ?? 0,
+          },
+        };
+      }
+      // Other chunk types (thinking, error) are still available on the
+      // underlying adapter but the AdiaUI pipeline doesn't consume them yet.
+    }
+  }
+
+  /** Expose the underlying client for advanced use. */
+  get adapter() { return this.#client; }
+
+  /** Expose provider name for detection. */
+  get provider() { return this.#provider; }
+}

package/llm-stub.js

@@ -0,0 +1,69 @@
+/**
+ * StubLLMAdapter — Deterministic LLM adapter for testing.
+ *
+ * Returns canned A2UI responses for known prompts. Implements the same
+ * interface that a real LLM adapter would (complete, stream) so pipeline
+ * code can develop against it without API keys.
+ */
+
+export class StubLLMAdapter {
+  /**
+   * Complete a prompt and return a full A2UI response.
+   *
+   * @param {object} opts
+   * @param {object[]} opts.messages — Chat messages (system + user turns)
+   * @param {string} [opts.systemPrompt] — System prompt override
+   * @returns {Promise<{ content: string, usage: { inputTokens: number, outputTokens: number } }>}
+   */
+  async complete({ messages, systemPrompt }) {
+    const lastMessage = messages?.[messages.length - 1]?.content || '';
+    const components = this.#buildResponse(lastMessage);
+
+    return {
+      content: JSON.stringify([
+        {
+          type: 'updateComponents',
+          surfaceId: 'default',
+          components,
+        },
+      ]),
+      usage: {
+        inputTokens: estimateTokens(JSON.stringify(messages)),
+        outputTokens: estimateTokens(JSON.stringify(components)),
+      },
+    };
+  }
+
+  /**
+   * Stream a response as an async iterable of chunks.
+   *
+   * @param {object} request — Same shape as complete()
+   * @yields {{ type: 'text', content: string }}
+   */
+  async *stream(request) {
+    const result = await this.complete(request);
+    // Simulate progressive streaming by yielding the full response
+    yield { type: 'text', content: result.content };
+  }
+
+  /**
+   * Build a canned component tree from the intent text.
+   * @param {string} intent
+   * @returns {object[]}
+   */
+  #buildResponse(intent) {
+    return [
+      { id: 'root', component: 'Card', children: ['hdr', 'sec'] },
+      { id: 'hdr', component: 'Header', children: ['title'] },
+      { id: 'title', component: 'Text', variant: 'h3', textContent: 'Generated UI' },
+      { id: 'sec', component: 'Section', children: ['col'] },
+      { id: 'col', component: 'Column', children: ['desc'] },
+      { id: 'desc', component: 'Text', variant: 'body', textContent: intent || 'No intent provided' },
+    ];
+  }
+}
+
+/** Rough token estimate (~4 chars per token) */
+function estimateTokens(text) {
+  return Math.ceil((text?.length || 0) / 4);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adia-ai/llm",
+  "version": "0.3.0",
+  "description": "Provider-agnostic LLM client — anthropic / openai / gemini adapters with a unified chat() + streamChat() facade. Used by AdiaUI's chat-shell and the A2UI generation pipeline; works in browser (with proxyUrl) and Node.",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./adapters/*": "./adapters/*.js",
+    "./bridge": "./llm-bridge.js",
+    "./stub": "./llm-stub.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "adapters/",
+    "llm-bridge.js",
+    "llm-stub.js",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
+    "directory": "packages/llm"
+  },
+  "license": "MIT"
+}