chatbotlite 0.3.1 → 0.5.0

package/dist/client/index.d.cts

@@ -1,17 +1,24 @@
-import { P as Provider, c as ProviderConfig, b as ClientOptions, A as AttemptInfo } from '../types-J7BXpiRU.cjs';
-export { C as ChainEntry, a as ChainStep, i as isKnownProvider } from '../types-J7BXpiRU.cjs';
-import { K as Knowledge, M as Message } from '../types-4alyzg8O.cjs';
+import { P as Provider, K as Knowledge, c as ProviderConfig, b as ClientOptions, M as Message, A as AttemptInfo } from '../types-BFlAWQF4.cjs';
+export { C as ChainEntry, a as ChainStep, i as isKnownProvider } from '../types-BFlAWQF4.cjs';
+import { G as GuardsConfig, a as JudgeVerdict } from '../judges-CSRIUVlF.cjs';
 
 interface ProviderEndpoint {
     baseUrl: string;
     defaultModel: string;
+    /** Vision-capable model. If absent, provider doesn't support image inputs. */
+    visionModel?: string;
 }
 /**
  * Built-in OpenAI-compatible providers. All use /v1/chat/completions
  * with response in OpenAI format. Caller supplies API key per provider.
+ *
+ * Providers with `visionModel` set support image inputs via OpenAI-style
+ * `image_url` content blocks (data: URLs accepted).
  */
 declare const PROVIDER_ENDPOINTS: Record<Provider, ProviderEndpoint>;
 declare function isRetryableError(err: unknown): boolean;
+/** Convert a File/Blob to a `data:` URL for inline vision input. */
+declare function fileToDataUrl(file: File | Blob): Promise<string>;
 
 interface ChatBotInit {
     /** Markdown describing the business — services, hours, policies, anything. */
@@ -20,12 +27,20 @@ interface ChatBotInit {
     providers: ProviderConfig;
     /** Optional runtime overrides. */
     options?: ClientOptions;
+    /** Defense-in-depth: phrase redlines (default) + optional LLM input/output judges. */
+    guards?: GuardsConfig;
 }
 interface ReplyOptions {
     /** Conversation history (excluding the new user message). */
     history?: Message[];
     /** Override system prompt — advanced use only. */
     systemPrompt?: string;
+    /** Tool names that the widget will render (auto-injects examples into system prompt). */
+    enabledTools?: string[];
+}
+interface ReplyWithMediaOptions extends ReplyOptions {
+    /** Image files (PNG/JPEG/WebP) to include alongside the message. Skipped on providers without vision. */
+    images?: (File | Blob)[];
 }
 interface ReplyResult {
     reply: string;
@@ -39,8 +54,15 @@ interface ReplyResult {
     };
     /** Guard violations the bot caught and stripped, if any. */
     guardWarnings: string[];
+    /** LLM-judge verdicts if judges configured. */
+    judges?: {
+        input?: JudgeVerdict;
+        output?: JudgeVerdict;
+    };
     /** Debug trace of every attempt in the chain. */
     attempts: AttemptInfo[];
+    /** True when blocked by input judge — `reply` will be the refusal message. */
+    blockedByInputJudge?: boolean;
 }
 /**
  * The main ChatBot entry. Holds knowledge + provider chain.
@@ -64,9 +86,42 @@ declare class ChatBot {
     private readonly fetcher;
     private readonly timeoutMs;
     private readonly cachedSystemPrompt;
+    private readonly guards;
+    private readonly knowledge;
     constructor(init: ChatBotInit);
+    /** Build system prompt for given opts — uses cached if no enabledTools, else rebuilds. */
+    private resolveSystemPrompt;
+    /** Run an LLM judge against content. Fail-open on errors. */
+    private judge;
+    /**
+     * Stream a reply as SSE events. Returns a ReadableStream that yields tokens
+     * progressively. Designed to plug into Next.js/Hono/Express route handlers:
+     *
+     * ```ts
+     * export async function POST(req: Request) {
+     *   const { message, transcript } = await req.json();
+     *   const stream = await bot.replyStream(message, { history: transcript });
+     *   return new Response(stream, {
+     *     headers: { "Content-Type": "text/event-stream" }
+     *   });
+     * }
+     * ```
+     *
+     * Events emitted (one per `data:` line, SSE format):
+     *   event: token   data: "<text fragment>"
+     *   event: done    data: {"reply":"...","usedProvider":"...","usedModel":"...","attempts":[...]}
+     *   event: error   data: {"message":"...","attempts":[...]}
+     */
+    replyStream(message: string, opts?: ReplyOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Reply to a message with optional image attachments. Routes through vision-capable
+     * providers only — chain steps without `visionModel` are skipped (logged in attempts).
+     *
+     * Images are inlined as data: URLs. Keep total payload modest (<10MB).
+     */
+    replyWithMedia(message: string, opts?: ReplyWithMediaOptions): Promise<ReplyResult>;
     reply(message: string, opts?: ReplyOptions): Promise<ReplyResult>;
     private callProvider;
 }
 
-export { AttemptInfo, ChatBot, type ChatBotInit, ClientOptions, PROVIDER_ENDPOINTS, Provider, ProviderConfig, type ProviderEndpoint, type ReplyOptions, type ReplyResult, isRetryableError };
+export { AttemptInfo, ChatBot, type ChatBotInit, ClientOptions, PROVIDER_ENDPOINTS, Provider, ProviderConfig, type ProviderEndpoint, type ReplyOptions, type ReplyResult, type ReplyWithMediaOptions, fileToDataUrl, isRetryableError };

package/dist/client/index.d.ts

@@ -1,17 +1,24 @@
-import { P as Provider, c as ProviderConfig, b as ClientOptions, A as AttemptInfo } from '../types-J7BXpiRU.js';
-export { C as ChainEntry, a as ChainStep, i as isKnownProvider } from '../types-J7BXpiRU.js';
-import { K as Knowledge, M as Message } from '../types-4alyzg8O.js';
+import { P as Provider, K as Knowledge, c as ProviderConfig, b as ClientOptions, M as Message, A as AttemptInfo } from '../types-BFlAWQF4.js';
+export { C as ChainEntry, a as ChainStep, i as isKnownProvider } from '../types-BFlAWQF4.js';
+import { G as GuardsConfig, a as JudgeVerdict } from '../judges-B0AAZLS9.js';
 
 interface ProviderEndpoint {
     baseUrl: string;
     defaultModel: string;
+    /** Vision-capable model. If absent, provider doesn't support image inputs. */
+    visionModel?: string;
 }
 /**
  * Built-in OpenAI-compatible providers. All use /v1/chat/completions
  * with response in OpenAI format. Caller supplies API key per provider.
+ *
+ * Providers with `visionModel` set support image inputs via OpenAI-style
+ * `image_url` content blocks (data: URLs accepted).
  */
 declare const PROVIDER_ENDPOINTS: Record<Provider, ProviderEndpoint>;
 declare function isRetryableError(err: unknown): boolean;
+/** Convert a File/Blob to a `data:` URL for inline vision input. */
+declare function fileToDataUrl(file: File | Blob): Promise<string>;
 
 interface ChatBotInit {
     /** Markdown describing the business — services, hours, policies, anything. */
@@ -20,12 +27,20 @@ interface ChatBotInit {
     providers: ProviderConfig;
     /** Optional runtime overrides. */
     options?: ClientOptions;
+    /** Defense-in-depth: phrase redlines (default) + optional LLM input/output judges. */
+    guards?: GuardsConfig;
 }
 interface ReplyOptions {
     /** Conversation history (excluding the new user message). */
     history?: Message[];
     /** Override system prompt — advanced use only. */
     systemPrompt?: string;
+    /** Tool names that the widget will render (auto-injects examples into system prompt). */
+    enabledTools?: string[];
+}
+interface ReplyWithMediaOptions extends ReplyOptions {
+    /** Image files (PNG/JPEG/WebP) to include alongside the message. Skipped on providers without vision. */
+    images?: (File | Blob)[];
 }
 interface ReplyResult {
     reply: string;
@@ -39,8 +54,15 @@ interface ReplyResult {
     };
     /** Guard violations the bot caught and stripped, if any. */
     guardWarnings: string[];
+    /** LLM-judge verdicts if judges configured. */
+    judges?: {
+        input?: JudgeVerdict;
+        output?: JudgeVerdict;
+    };
     /** Debug trace of every attempt in the chain. */
     attempts: AttemptInfo[];
+    /** True when blocked by input judge — `reply` will be the refusal message. */
+    blockedByInputJudge?: boolean;
 }
 /**
  * The main ChatBot entry. Holds knowledge + provider chain.
@@ -64,9 +86,42 @@ declare class ChatBot {
     private readonly fetcher;
     private readonly timeoutMs;
     private readonly cachedSystemPrompt;
+    private readonly guards;
+    private readonly knowledge;
     constructor(init: ChatBotInit);
+    /** Build system prompt for given opts — uses cached if no enabledTools, else rebuilds. */
+    private resolveSystemPrompt;
+    /** Run an LLM judge against content. Fail-open on errors. */
+    private judge;
+    /**
+     * Stream a reply as SSE events. Returns a ReadableStream that yields tokens
+     * progressively. Designed to plug into Next.js/Hono/Express route handlers:
+     *
+     * ```ts
+     * export async function POST(req: Request) {
+     *   const { message, transcript } = await req.json();
+     *   const stream = await bot.replyStream(message, { history: transcript });
+     *   return new Response(stream, {
+     *     headers: { "Content-Type": "text/event-stream" }
+     *   });
+     * }
+     * ```
+     *
+     * Events emitted (one per `data:` line, SSE format):
+     *   event: token   data: "<text fragment>"
+     *   event: done    data: {"reply":"...","usedProvider":"...","usedModel":"...","attempts":[...]}
+     *   event: error   data: {"message":"...","attempts":[...]}
+     */
+    replyStream(message: string, opts?: ReplyOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Reply to a message with optional image attachments. Routes through vision-capable
+     * providers only — chain steps without `visionModel` are skipped (logged in attempts).
+     *
+     * Images are inlined as data: URLs. Keep total payload modest (<10MB).
+     */
+    replyWithMedia(message: string, opts?: ReplyWithMediaOptions): Promise<ReplyResult>;
     reply(message: string, opts?: ReplyOptions): Promise<ReplyResult>;
     private callProvider;
 }
 
-export { AttemptInfo, ChatBot, type ChatBotInit, ClientOptions, PROVIDER_ENDPOINTS, Provider, ProviderConfig, type ProviderEndpoint, type ReplyOptions, type ReplyResult, isRetryableError };
+export { AttemptInfo, ChatBot, type ChatBotInit, ClientOptions, PROVIDER_ENDPOINTS, Provider, ProviderConfig, type ProviderEndpoint, type ReplyOptions, type ReplyResult, type ReplyWithMediaOptions, fileToDataUrl, isRetryableError };

package/dist/client/index.js

@@ -18,25 +18,59 @@ function isKnownProvider(name) {
 
 // src/client/providers.ts
 var PROVIDER_ENDPOINTS = {
-  openai: { baseUrl: "https://api.openai.com/v1", defaultModel: "gpt-4o-mini" },
+  openai: { baseUrl: "https://api.openai.com/v1", defaultModel: "gpt-4o-mini", visionModel: "gpt-4o" },
   deepseek: { baseUrl: "https://api.deepseek.com/v1", defaultModel: "deepseek-chat" },
-  groq: { baseUrl: "https://api.groq.com/openai/v1", defaultModel: "llama-3.3-70b-versatile" },
-  gemini: { baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", defaultModel: "gemini-2.5-flash" },
-  anthropic: { baseUrl: "https://api.anthropic.com/v1", defaultModel: "claude-haiku-4-5" },
+  groq: { baseUrl: "https://api.groq.com/openai/v1", defaultModel: "llama-3.3-70b-versatile", visionModel: "llama-3.2-90b-vision-preview" },
+  gemini: { baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", defaultModel: "gemini-2.5-flash", visionModel: "gemini-2.5-flash" },
+  anthropic: { baseUrl: "https://api.anthropic.com/v1", defaultModel: "claude-haiku-4-5", visionModel: "claude-haiku-4-5" },
   cerebras: { baseUrl: "https://api.cerebras.ai/v1", defaultModel: "qwen-3-235b-a22b-instruct-2507" },
   sambanova: { baseUrl: "https://api.sambanova.ai/v1", defaultModel: "Meta-Llama-3.3-70B-Instruct" },
   fireworks: { baseUrl: "https://api.fireworks.ai/inference/v1", defaultModel: "accounts/fireworks/models/llama-v3p3-70b-instruct" },
   mistral: { baseUrl: "https://api.mistral.ai/v1", defaultModel: "mistral-small-latest" },
-  openrouter: { baseUrl: "https://openrouter.ai/api/v1", defaultModel: "deepseek/deepseek-chat" },
-  moonshot: { baseUrl: "https://api.moonshot.ai/v1", defaultModel: "moonshot-v1-32k" }
+  openrouter: { baseUrl: "https://openrouter.ai/api/v1", defaultModel: "deepseek/deepseek-chat", visionModel: "openai/gpt-4o" },
+  moonshot: { baseUrl: "https://api.moonshot.ai/v1", defaultModel: "moonshot-v1-32k", visionModel: "moonshot-v1-32k-vision-preview" }
 };
 function isRetryableError(err) {
   const msg = err instanceof Error ? err.message : String(err);
   return /\b(429|rate.?limit|quota|exceed|5\d\d|timeout|ECONNRESET|fetch failed)\b/i.test(msg);
 }
+async function fileToDataUrl(file) {
+  const buf = new Uint8Array(await file.arrayBuffer());
+  const base64 = bufferToBase64(buf);
+  const mime = file.type || "application/octet-stream";
+  return `data:${mime};base64,${base64}`;
+}
+function bufferToBase64(buf) {
+  let bin = "";
+  for (let i = 0; i < buf.length; i++) bin += String.fromCharCode(buf[i]);
+  if (typeof btoa === "function") return btoa(bin);
+  return globalThis.Buffer.from(bin, "binary").toString("base64");
+}
+
+// src/core/tools.ts
+function buildToolsPromptAddendum(enabledTools) {
+  if (enabledTools.length === 0) return "";
+  const examples = {
+    uploadForReview: '[SKILL:uploadForReview purpose="T4 slip" accept="image/*,application/pdf" maxMb=10] \u2014 collect a document for human review (bytes go to webhook, you never see content)',
+    scheduleCallback: '[SKILL:scheduleCallback durationMin=15 timezone="America/Vancouver"] \u2014 let the user pick a callback time slot',
+    requestPayment: '[SKILL:requestPayment amount=4250 currency="cad" reason="initial deposit"] \u2014 collect payment via inline card'
+  };
+  const lines = enabledTools.filter((t) => examples[t]).map((t) => `- ${examples[t]}`);
+  if (lines.length === 0) return "";
+  return [
+    "",
+    "## Available tools",
+    "When you need one of these workflows, emit the marker INLINE in your reply.",
+    "Write a short message first, THEN the marker. The marker will be replaced by an interactive card.",
+    "Pause the conversation after emitting \u2014 wait for the tool result before continuing.",
+    "",
+    ...lines
+  ].join("\n");
+}
 
 // src/core/prompts.ts
-function buildSystemPrompt(knowledge) {
+function buildSystemPrompt(knowledge, enabledTools = []) {
+  const toolsAddendum = buildToolsPromptAddendum(enabledTools);
   return [
     "You are an AI assistant on a business website. Use ONLY the knowledge below to answer.",
     "",
@@ -49,33 +83,23 @@ function buildSystemPrompt(knowledge) {
     "- For anything not covered in the knowledge above, say the owner will follow up \u2014 do NOT guess.",
     '- If the caller is clearly a vendor/sales pitch, say: "This does not look like a customer service request, so we will not continue this thread."',
     `- If wrong number or asked to stop, say: "Sorry about that. We won't text again."`,
-    "- Match the caller's language automatically."
-  ].join("\n");
+    "- Match the caller's language automatically.",
+    toolsAddendum
+  ].filter(Boolean).join("\n");
 }
 
 // src/core/guards.ts
 var FORBIDDEN_PHRASES = [
-  "help is coming",
-  "someone is on the way",
-  "technician is on the way",
-  "provider is on the way",
-  "dispatching someone",
   "i've booked",
+  // fake booking
   "i have booked",
-  "reservation confirmed",
   "your appointment is confirmed",
-  "i've scheduled",
-  "i have scheduled",
-  "we've dispatched",
-  "we have dispatched",
-  "i can confirm",
-  "i guarantee",
-  "guaranteed delivery",
-  "guaranteed arrival",
-  "will arrive at",
-  "arriving at",
-  "i'll send",
-  "i will send"
+  // fake confirmation
+  "reservation confirmed",
+  "someone is on the way",
+  // false dispatch
+  "i guarantee"
+  // legal liability
 ];
 function checkForbiddenPhrases(reply) {
   const lower = reply.toLowerCase();
@@ -100,6 +124,33 @@ function stripForbidden(reply) {
   return trimmed;
 }
 
+// src/core/judges.ts
+async function runJudge(config, apiKey, endpointUrl, content, fetcher) {
+  const res = await fetcher(`${endpointUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      model: config.model,
+      messages: [
+        { role: "system", content: config.prompt },
+        { role: "user", content }
+      ],
+      temperature: 0,
+      max_tokens: 10
+    })
+  });
+  if (!res.ok) {
+    return { decision: "PASS", raw: `judge HTTP ${res.status} \u2014 fail-open` };
+  }
+  const data = await res.json();
+  const raw = (data.choices?.[0]?.message?.content ?? "").trim().toUpperCase();
+  const decision = raw.startsWith("BLOCK") ? "BLOCK" : "PASS";
+  return { decision, raw };
+}
+
 // src/client/chatbot.ts
 var ChatBot = class {
   steps;
@@ -107,18 +158,258 @@ var ChatBot = class {
   fetcher;
   timeoutMs;
   cachedSystemPrompt;
+  guards;
+  knowledge;
   constructor(init) {
     if (!init.knowledge || typeof init.knowledge !== "string" || init.knowledge.trim().length === 0) {
       throw new Error("chatbotlite: knowledge is required (a non-empty markdown string).");
     }
+    this.knowledge = init.knowledge;
     this.keys = init.providers.keys ?? {};
     this.steps = resolveChain(init.providers);
     this.fetcher = init.options?.fetch ?? globalThis.fetch.bind(globalThis);
     this.timeoutMs = init.options?.timeoutMs ?? 3e4;
     this.cachedSystemPrompt = buildSystemPrompt(init.knowledge);
+    this.guards = init.guards ?? {};
+  }
+  /** Build system prompt for given opts — uses cached if no enabledTools, else rebuilds. */
+  resolveSystemPrompt(opts) {
+    if (opts.systemPrompt) return opts.systemPrompt;
+    if (opts.enabledTools && opts.enabledTools.length > 0) {
+      return buildSystemPrompt(this.knowledge, opts.enabledTools);
+    }
+    return this.cachedSystemPrompt;
+  }
+  /** Run an LLM judge against content. Fail-open on errors. */
+  async judge(config, content) {
+    const endpoint = PROVIDER_ENDPOINTS[config.provider];
+    const key = this.keys[config.provider];
+    if (!key) {
+      return { decision: "PASS", raw: `judge provider ${config.provider} has no key \u2014 fail-open` };
+    }
+    const model = config.model ?? endpoint.defaultModel;
+    return runJudge(
+      { provider: config.provider, model, prompt: config.prompt },
+      key,
+      endpoint.baseUrl,
+      content,
+      this.fetcher
+    );
+  }
+  /**
+   * Stream a reply as SSE events. Returns a ReadableStream that yields tokens
+   * progressively. Designed to plug into Next.js/Hono/Express route handlers:
+   *
+   * ```ts
+   * export async function POST(req: Request) {
+   *   const { message, transcript } = await req.json();
+   *   const stream = await bot.replyStream(message, { history: transcript });
+   *   return new Response(stream, {
+   *     headers: { "Content-Type": "text/event-stream" }
+   *   });
+   * }
+   * ```
+   *
+   * Events emitted (one per `data:` line, SSE format):
+   *   event: token   data: "<text fragment>"
+   *   event: done    data: {"reply":"...","usedProvider":"...","usedModel":"...","attempts":[...]}
+   *   event: error   data: {"message":"...","attempts":[...]}
+   */
+  async replyStream(message, opts = {}) {
+    const systemPrompt = this.resolveSystemPrompt(opts);
+    const messages = [
+      { role: "system", content: systemPrompt },
+      ...opts.history ?? [],
+      { role: "user", content: message }
+    ];
+    const steps = this.steps;
+    const fetcher = this.fetcher;
+    const keys = this.keys;
+    const timeoutMs = this.timeoutMs;
+    const encoder = new TextEncoder();
+    const sse = (event, data) => encoder.encode(`event: ${event}
+data: ${data}
+
+`);
+    return new ReadableStream({
+      async start(controller) {
+        const attempts = [];
+        let lastError;
+        let assembled = "";
+        for (const step of steps) {
+          const t0 = Date.now();
+          const endpoint = PROVIDER_ENDPOINTS[step.provider];
+          const key = keys[step.provider];
+          if (!key) {
+            attempts.push({ provider: step.provider, model: step.model, status: "error", error: "missing key", latencyMs: 0 });
+            continue;
+          }
+          const abortCtrl = new AbortController();
+          const timer = setTimeout(() => abortCtrl.abort(), timeoutMs);
+          try {
+            const res = await fetcher(`${endpoint.baseUrl}/chat/completions`, {
+              method: "POST",
+              headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+              body: JSON.stringify({ model: step.model, messages, temperature: 0.3, max_tokens: 300, stream: true }),
+              signal: abortCtrl.signal
+            });
+            if (!res.ok) {
+              const body = await res.text();
+              throw new Error(`${res.status}: ${body.slice(0, 200)}`);
+            }
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let sseBuffer = "";
+            while (true) {
+              const { done, value } = await reader.read();
+              if (done) break;
+              sseBuffer += decoder.decode(value, { stream: true });
+              const lines = sseBuffer.split("\n");
+              sseBuffer = lines.pop() ?? "";
+              for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith("data:")) continue;
+                const payload = trimmed.slice(5).trim();
+                if (payload === "[DONE]") continue;
+                try {
+                  const obj = JSON.parse(payload);
+                  const delta = obj.choices?.[0]?.delta?.content ?? obj.choices?.[0]?.delta?.reasoning_content ?? "";
+                  if (delta) {
+                    assembled += delta;
+                    controller.enqueue(sse("token", JSON.stringify(delta)));
+                  }
+                } catch {
+                }
+              }
+            }
+            attempts.push({ provider: step.provider, model: step.model, status: "ok", latencyMs: Date.now() - t0 });
+            const guard = checkForbiddenPhrases(assembled);
+            const finalReply = guard.ok ? assembled : stripForbidden(assembled);
+            controller.enqueue(sse("done", JSON.stringify({
+              reply: finalReply,
+              usedProvider: step.provider,
+              usedModel: step.model,
+              guardWarnings: guard.violations,
+              attempts
+            })));
+            controller.close();
+            return;
+          } catch (err) {
+            lastError = err;
+            const errMsg = err instanceof Error ? err.message : String(err);
+            attempts.push({ provider: step.provider, model: step.model, status: "error", error: errMsg, latencyMs: Date.now() - t0 });
+            assembled = "";
+            if (!isRetryableError(err)) {
+              controller.enqueue(sse("error", JSON.stringify({ message: `${step.label} failed (non-retryable): ${errMsg}`, attempts })));
+              controller.close();
+              return;
+            }
+          } finally {
+            clearTimeout(timer);
+          }
+        }
+        const summary = attempts.map((a) => `${a.provider}/${a.model}:${a.error ?? "ok"}`).join(" \u2192 ");
+        controller.enqueue(sse("error", JSON.stringify({
+          message: `all chain steps failed. Trace: ${summary}. Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+          attempts
+        })));
+        controller.close();
+      }
+    });
+  }
+  /**
+   * Reply to a message with optional image attachments. Routes through vision-capable
+   * providers only — chain steps without `visionModel` are skipped (logged in attempts).
+   *
+   * Images are inlined as data: URLs. Keep total payload modest (<10MB).
+   */
+  async replyWithMedia(message, opts = {}) {
+    const images = opts.images ?? [];
+    if (images.length === 0) {
+      return this.reply(message, opts);
+    }
+    const dataUrls = await Promise.all(images.map(fileToDataUrl));
+    const systemPrompt = this.resolveSystemPrompt(opts);
+    const userContent = [];
+    if (message) userContent.push({ type: "text", text: message });
+    for (const url of dataUrls) userContent.push({ type: "image_url", image_url: { url } });
+    const messages = [
+      { role: "system", content: systemPrompt },
+      ...opts.history ?? [],
+      { role: "user", content: userContent }
+    ];
+    const attempts = [];
+    let lastError;
+    for (const step of this.steps) {
+      const endpoint = PROVIDER_ENDPOINTS[step.provider];
+      if (!endpoint.visionModel) {
+        attempts.push({ provider: step.provider, model: step.model, status: "error", error: "no vision support", latencyMs: 0 });
+        continue;
+      }
+      const t0 = Date.now();
+      const visionStep = { provider: step.provider, model: endpoint.visionModel, label: `${step.provider}/${endpoint.visionModel}` };
+      try {
+        const key = this.keys[step.provider];
+        if (!key) throw new Error(`Missing API key for provider: ${step.provider}`);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          const res = await this.fetcher(`${endpoint.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ model: visionStep.model, messages, temperature: 0.3, max_tokens: 400 }),
+            signal: controller.signal
+          });
+          if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${res.status}: ${body.slice(0, 200)}`);
+          }
+          const data = await res.json();
+          const reply = (data.choices?.[0]?.message?.content ?? "").trim();
+          if (!reply) throw new Error("empty vision reply");
+          attempts.push({ provider: visionStep.provider, model: visionStep.model, status: "ok", latencyMs: Date.now() - t0 });
+          const guard = checkForbiddenPhrases(reply);
+          const finalReply = guard.ok ? reply : stripForbidden(reply);
+          return {
+            reply: finalReply,
+            usedProvider: visionStep.provider,
+            usedModel: visionStep.model,
+            ...data.usage ? { usage: data.usage } : {},
+            guardWarnings: guard.violations,
+            attempts
+          };
+        } finally {
+          clearTimeout(timer);
+        }
+      } catch (err) {
+        lastError = err;
+        const errMsg = err instanceof Error ? err.message : String(err);
+        attempts.push({ provider: visionStep.provider, model: visionStep.model, status: "error", error: errMsg, latencyMs: Date.now() - t0 });
+        if (!isRetryableError(err)) {
+          throw new Error(`chatbotlite: ${visionStep.label} vision failed (non-retryable). ${errMsg}`);
+        }
+      }
+    }
+    const summary = attempts.map((a) => `${a.provider}/${a.model}:${a.error ?? "ok"}`).join(" \u2192 ");
+    throw new Error(`chatbotlite: no vision-capable provider succeeded. Trace: ${summary}. Last error: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
   }
   async reply(message, opts = {}) {
-    const systemPrompt = opts.systemPrompt ?? this.cachedSystemPrompt;
+    let inputVerdict;
+    if (this.guards.inputJudge) {
+      inputVerdict = await this.judge(this.guards.inputJudge, message);
+      if (inputVerdict.decision === "BLOCK") {
+        return {
+          reply: "I can't process that request. Please ask in a different way.",
+          usedProvider: this.steps[0].provider,
+          usedModel: this.steps[0].model,
+          guardWarnings: [],
+          judges: { input: inputVerdict },
+          attempts: [],
+          blockedByInputJudge: true
+        };
+      }
+    }
+    const systemPrompt = this.resolveSystemPrompt(opts);
     const messages = [
       { role: "system", content: systemPrompt },
       ...opts.history ?? [],
@@ -132,13 +423,21 @@ var ChatBot = class {
         const result = await this.callProvider(step, messages);
         attempts.push({ provider: step.provider, model: step.model, status: "ok", latencyMs: Date.now() - t0 });
         const guard = checkForbiddenPhrases(result.reply);
-        const finalReply = guard.ok ? result.reply : stripForbidden(result.reply);
+        let finalReply = guard.ok ? result.reply : stripForbidden(result.reply);
+        let outputVerdict;
+        if (this.guards.outputJudge) {
+          outputVerdict = await this.judge(this.guards.outputJudge, finalReply);
+          if (outputVerdict.decision === "BLOCK") {
+            finalReply = "Let me check with the owner and get back to you on that.";
+          }
+        }
         return {
           reply: finalReply,
           usedProvider: step.provider,
           usedModel: step.model,
           ...result.usage ? { usage: result.usage } : {},
           guardWarnings: guard.violations,
+          ...inputVerdict || outputVerdict ? { judges: { ...inputVerdict ? { input: inputVerdict } : {}, ...outputVerdict ? { output: outputVerdict } : {} } } : {},
           attempts
         };
       } catch (err) {
@@ -224,6 +523,6 @@ function normalizeChainEntry(entry, keys) {
   return { provider, model, label: `${provider}/${model}` };
 }
 
-export { ChatBot, PROVIDER_ENDPOINTS, isKnownProvider, isRetryableError };
+export { ChatBot, PROVIDER_ENDPOINTS, fileToDataUrl, isKnownProvider, isRetryableError };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map