@webknox/ai-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skycraft GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @webknox/ai-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WebKnox for the [AI SDK](https://ai-sdk.dev). One tool, `askWebknox`, answers everyday questions with a sourced card your app can show: weather, nutrition, recipes, comparisons with photos, translations, maths, media and [more](https://webknox.com/docs/cards).
+
+```bash
+npm install @webknox/ai-sdk
+```
+
+Set `WEBKNOX_API_KEY`, with a key from [the console](https://webknox.com/console), and add the tool:
+
+```js
+import {generateText, isStepCount} from 'ai';
+import {askWebknox} from '@webknox/ai-sdk';
+
+const {text, steps} = await generateText({
+  model: 'openai/gpt-5-mini',
+  prompt: 'Do I need an umbrella in Dresden tomorrow?',
+  tools: {askWebknox: askWebknox()},
+  stopWhen: isStepCount(3),
+});
+
+console.log(text);
+```
+
+## Showing the card
+
+The tool's result is the whole [answer](https://webknox.com/docs/reference). Hand it to [`<webknox-answer>`](https://webknox.com/docs/rendering) from `@webknox/elements`:
+
+```js
+const element = document.createElement('webknox-answer');
+element.answer = toolResult.output;
+```
+
+The model reads only the answer's text and sources, and is told the user already sees the card. That keeps a large card out of its context, and it won't read the card back.
+
+## Filters on a card
+
+Search cards have filters, sort and "Show more". A change fires `webknox-refine`. Answer it from your server with `refineAnswer`, so the card updates in place without a model turn:
+
+```js
+import {refineAnswer} from '@webknox/ai-sdk';
+
+const answer = await refineAnswer({question, locale, refine});
+```
+
+[The Next.js chat](https://github.com/webknox/webknox-examples/tree/main/examples/nextjs-chat) shows the whole loop.
+
+## Options
+
+```js
+askWebknox({
+  locale: 'de',                                        // en (default), de, fr, es, pt, it
+  context: {timezone: 'Europe/Berlin', units: 'metric'},
+  accept: ['weather.forecast', 'nutrition.facts'],     // card types your app can show
+});
+```
+
+`apiKey`, `baseUrl`, `render` (hosted embeds and images, on Pro and Scale) and `fetch` work the same way. Some models answer from memory rather than call a tool, so tell yours in the system prompt: "Use askWebknox for anything it covers, even in a follow-up." A question WebKnox can't answer comes back with `matched: false`, and the model answers it itself. A refused request throws a `WebKnoxError` with `status`, `code` and `retryAfterS`.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@webknox/ai-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "WebKnox for the AI SDK: a tool that answers everyday questions with sourced UI cards.",
+  "keywords": ["webknox", "ai-sdk", "vercel-ai-sdk", "tool", "generative-ui", "cards"],
+  "homepage": "https://webknox.com/docs/ai-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webknox/webknox-examples.git",
+    "directory": "packages/ai-sdk"
+  },
+  "bugs": {
+    "email": "hello@webknox.com"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0 || ^7.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "ai": "^7.0.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,78 @@
+import type {Tool} from 'ai';
+
+/** Card types, `null` when the answer has none. New types can appear: see https://webknox.com/docs/cards */
+export interface WebKnoxCard {
+  type: string;
+  version: number;
+  data: Record<string, unknown>;
+}
+
+export interface WebKnoxSource {
+  name: string;
+  url?: string;
+  license?: string;
+}
+
+/** An Answers API answer. New optional fields can appear: see https://webknox.com/docs/reference */
+export interface WebKnoxAnswer {
+  v: number;
+  id: string;
+  matched: boolean;
+  reason?: string;
+  locale: string;
+  skill?: string;
+  confidence?: number;
+  text: string | null;
+  speech?: string;
+  card: WebKnoxCard | null;
+  sources: WebKnoxSource[];
+  follow_ups: string[];
+  actions: Array<Record<string, unknown>>;
+  usage: {billable: boolean};
+  attribution?: {text: string; url: string};
+  render?: {embed_url?: string; image_url?: string; expires_at: string};
+}
+
+export interface AskWebknoxOptions {
+  /** Defaults to the WEBKNOX_API_KEY environment variable. */
+  apiKey?: string;
+  /** Defaults to https://api.webknox.com */
+  baseUrl?: string;
+  /** en (default), de, fr, es, pt or it: the language of the text and of localized card fields. */
+  locale?: string;
+  /** What to know about the user, for "today" and "here". */
+  context?: {
+    timezone?: string;
+    now?: string;
+    location?: {lat: number; lon: number};
+    units?: 'metric' | 'imperial';
+  };
+  /** Card types your client can render. Omit it to accept all. */
+  accept?: string[];
+  /** Hosted render URLs, on Pro and Scale. */
+  render?: {theme?: unknown; layout?: string; formats: Array<'embed' | 'image'>};
+  /** Defaults to the global fetch. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export function askWebknox(options?: AskWebknoxOptions): Tool<{question: string}, WebKnoxAnswer>;
+
+export interface RefineRequest {
+  /** What the card answered: its search's query, or the answer's text. */
+  question: string;
+  locale?: string;
+  /** `detail.refine` from the card's `webknox-refine` event. */
+  refine: Record<string, unknown>;
+}
+
+/** Answers a change to a search card straight from the API, without a model turn. Call it from your server. */
+export function refineAnswer(request: RefineRequest, connection?: Pick<AskWebknoxOptions, 'apiKey' | 'baseUrl' | 'fetch'>): Promise<WebKnoxAnswer>;
+
+/** What the model reads of an answer: its text and sources, not the card. */
+export function forModel(answer: WebKnoxAnswer): string;
+
+export class WebKnoxError extends Error {
+  status?: number;
+  code?: string;
+  retryAfterS?: number;
+}

package/src/index.js

@@ -0,0 +1,81 @@
+import {tool} from 'ai';
+import {z} from 'zod';
+
+const API = 'https://api.webknox.com';
+
+const DESCRIPTION = [
+  'Shows the user a sourced card in the chat, from live data: weather, nutrition, single recipes and recipe searches,',
+  'game and artwork searches, comparisons with photos, translations, definitions, conversions, maths, time and timers,',
+  'sunrise and sunset, videos, music and radio, pictures, jokes, quotes and this day in history.',
+  'Call it whenever the user asks for one of these, even if you could answer from memory: real recipes with photos and',
+  'filters beat a recipe you write yourself. Answer anything else yourself.',
+].join(' ');
+
+const QUESTION = 'The question as one self-contained sentence in the user\'s language that names the place, food or things it is about; a follow-up such as "and tomorrow?" written out as a full question.';
+
+/** A request the API refused: `code` is its error code, `retryAfterS` is set on a 429. */
+export class WebKnoxError extends Error {
+  constructor(message, {status, code, retryAfterS} = {}) {
+    super(message);
+    this.name = 'WebKnoxError';
+    this.status = status;
+    this.code = code;
+    this.retryAfterS = retryAfterS;
+  }
+}
+
+/** What the model reads: the answer's text and sources. The card stays in the tool result, for the UI. */
+export function forModel(answer) {
+  if (!answer.matched) return 'WebKnox has no answer for this. Answer from what you know.';
+  const sources = answer.sources.map((source) => source.name).filter(Boolean);
+  return [
+    answer.text,
+    sources.length ? `Sources: ${sources.join(', ')}.` : null,
+    answer.card ? 'The user already sees this as a card, so don\'t repeat it. Add only what the card doesn\'t say.' : null,
+  ].filter(Boolean).join('\n');
+}
+
+async function refused(response) {
+  const error = await response.json().then((body) => body?.error, () => null);
+  return new WebKnoxError(error?.message || `WebKnox answered ${response.status}`, {
+    status: response.status,
+    code: error?.code,
+    retryAfterS: error?.retry_after_s,
+  });
+}
+
+/** One POST to the Answers API. */
+async function post(body, {apiKey, baseUrl = API, fetch: fetchImpl = globalThis.fetch} = {}, signal) {
+  const key = apiKey ?? globalThis.process?.env?.WEBKNOX_API_KEY;
+  if (!key) throw new WebKnoxError('No API key: set WEBKNOX_API_KEY or pass apiKey. Get one at https://webknox.com/console');
+  const response = await fetchImpl(`${baseUrl}/v2/answers`, {
+    method: 'POST',
+    headers: {Authorization: `Bearer ${key}`, 'Content-Type': 'application/json'},
+    body: JSON.stringify(body),
+    signal,
+  });
+  if (!response.ok) throw await refused(response);
+  return response.json();
+}
+
+/**
+ * The WebKnox tool for `generateText`, `streamText` and agents. Its result is the Answers API's answer: hand it to
+ * `<webknox-answer>` to show the card.
+ */
+export function askWebknox({locale, context, accept, render, ...connection} = {}) {
+  return tool({
+    description: DESCRIPTION,
+    inputSchema: z.object({question: z.string().trim().min(1).max(1000).describe(QUESTION)}),
+    execute: ({question}, {abortSignal} = {}) =>
+      post({messages: [{role: 'user', content: question}], locale, context, accept, render}, connection, abortSignal),
+    toModelOutput: ({output}) => ({type: 'text', value: forModel(output)}),
+  });
+}
+
+/**
+ * A change to a search card: `refine` from its `webknox-refine` event, for its filters, sort, more results or one of its
+ * recipes. It goes straight to the API, so the card updates without a model turn. `question` is what the card answered.
+ */
+export function refineAnswer({question, locale, refine}, connection) {
+  return post({messages: [{role: 'user', content: question}], locale, refine}, connection);
+}