@~lyre/ai-agents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Britam Trust Services / Lyre
+
+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

@@ -0,0 +1,79 @@
+# @lyre/ai-agents
+
+Multi-provider AI agents SDK for SvelteKit and Node. Thin agent/tool/run/runStream API on top of the [Vercel AI SDK](https://ai-sdk.dev/) — supports OpenAI, Anthropic, Google Gemini, Mistral, Cohere, and any other provider the AI SDK targets.
+
+## Why
+
+The original `@kigathi/ai-agents` v1.1.0 (in `belva/axis/packages/lyre-ai-agents-node`) was OpenAI-only and built directly on `openai.responses.create()`. Locking the AI advisor to one vendor is bad insurance — when Anthropic ships a 10× cheaper model, you want to switch in a config line. This package preserves the original's developer-facing API (`createClient` → `registerTool` / `createAgent` / `run` / `runStream`) but routes everything through the AI SDK's provider-agnostic `generateText` / `streamText`.
+
+## Quick start
+
+```bash
+pnpm add @lyre/ai-agents ai zod
+pnpm add @ai-sdk/anthropic   # or @ai-sdk/openai, @ai-sdk/google, etc.
+```
+
+```ts
+import { createClient } from '@lyre/ai-agents';
+import { z } from 'zod';
+
+const ai = createClient();
+
+ai.registerTool({
+  name: 'book_advisor_call',
+  description: 'Capture the user\'s intent to speak with a human advisor.',
+  inputSchema: z.object({
+    reason: z.string(),
+    preferred_time: z.string().optional()
+  }),
+  execute: async (input, { app }) => {
+    // app.userId, app.guestUuid, app.locale, etc. — whatever you put in RunParams.context
+    return { booked: true, ticketId: 'demo-1234' };
+  }
+});
+
+ai.createAgent({
+  name: 'advisor',
+  model: 'anthropic/claude-sonnet-4.5',
+  instructions: 'You are a calm wealth advisor...',
+  tools: ['book_advisor_call'],
+  temperature: 0.7,
+  providerOptions: {
+    anthropic: { cacheControl: { type: 'ephemeral' } }  // prompt caching
+  }
+});
+
+// Non-streaming
+const result = await ai.run({
+  agent: 'advisor',
+  message: 'Should I write a will?',
+  history: [],
+  context: { userId: 'u_123' }
+});
+console.log(result.text);
+
+// Streaming
+for await (const ev of ai.runStream({ agent: 'advisor', message: 'Hi' })) {
+  if (ev.type === 'text-delta') process.stdout.write(ev.text);
+  if (ev.type === 'tool-call') console.log('\ntool-call:', ev.toolName, ev.input);
+  if (ev.type === 'tool-result') console.log('tool-result:', ev.toolName, ev.output);
+  if (ev.type === 'finish') console.log('\nusage:', ev.usage);
+}
+```
+
+Provider authentication uses environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, …). To use a non-standard endpoint or test fixture, pass a constructed `LanguageModel` object to `createAgent({ model })` instead of a string.
+
+## What's different from `@kigathi/ai-agents`
+
+| Surface | `@kigathi/ai-agents` v1.1.0 | `@lyre/ai-agents` |
+|---|---|---|
+| Providers | OpenAI only (Responses API) | OpenAI, Anthropic, Google, Mistral, Cohere, … (Vercel AI SDK) |
+| Streaming events | Text deltas only | Full event stream: `text-delta`, `tool-call`, `tool-result`, `tool-error`, `finish`, `error` |
+| Tool schemas | Loose JSON schema | Zod-typed `inputSchema`, type-safe `execute` |
+| Modes (direct / proxy / persistence) | Built in | **Dropped** — apps own their persistence and routing |
+| TTS, read-aloud | Built in | **Dropped** for the POC. Re-add if needed. |
+| Conversation state | In-memory `Map` | **Dropped** — apps own their conversation persistence |
+| Prompt caching | Not exposed | Forwarded via `agent.providerOptions` |
+| Language | JavaScript | TypeScript |
+
+If you need TTS or the read-aloud UI from the original, port those modules separately — they're orthogonal to the agent runtime.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@~lyre/ai-agents",
+  "version": "0.1.0",
+  "description": "Multi-provider AI agents SDK for SvelteKit + Node. Thin agent/tool/run/runStream surface over the Vercel AI SDK — OpenAI, Anthropic, Google Gemini, Mistral, Cohere. Zod-typed tools, full streaming event surface, optional HTML sanitizer.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "Britam Trust Services / Lyre",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/REPLACE_ME/britam-legacy.git",
+    "directory": "packages/ai-agents"
+  },
+  "homepage": "https://github.com/REPLACE_ME/britam-legacy/tree/main/packages/ai-agents#readme",
+  "bugs": {
+    "url": "https://github.com/REPLACE_ME/britam-legacy/issues"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "openai",
+    "anthropic",
+    "google-gemini",
+    "vercel-ai-sdk",
+    "tools",
+    "agents",
+    "streaming",
+    "sveltekit",
+    "lyre"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./sanitize": {
+      "types": "./src/sanitize.ts",
+      "import": "./src/sanitize.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0",
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "ai": "^6.0.0",
+    "typescript": "^6.0.2",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agents.ts

@@ -0,0 +1,53 @@
+import type { Agent, AgentDefinition, ToolDefinition } from './types';
+
+/**
+ * In-memory registry of agents and tools. One per `Client`.
+ */
+export class Registry {
+	readonly tools = new Map<string, ToolDefinition>();
+	readonly agents = new Map<string, Agent>();
+
+	registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O> {
+		this.tools.set(tool.name, tool as unknown as ToolDefinition);
+		return tool;
+	}
+
+	createAgent(definition: AgentDefinition): Agent {
+		const agent: Agent = {
+			id: definition.id ?? definition.name,
+			name: definition.name,
+			model: definition.model,
+			instructions: definition.instructions ?? '',
+			temperature: definition.temperature,
+			maxOutputTokens: definition.maxOutputTokens,
+			tools: definition.tools,
+			providerOptions: definition.providerOptions,
+			metadata: definition.metadata
+		};
+
+		this.agents.set(agent.id, agent);
+		// Also key by name when distinct from id, so consumers can look up by either.
+		if (agent.name !== agent.id) this.agents.set(agent.name, agent);
+		return agent;
+	}
+
+	resolveAgent(input: string | AgentDefinition): Agent {
+		if (typeof input !== 'string') {
+			// Allow callers to pass a fully-formed definition for one-off calls.
+			return this.createAgent(input);
+		}
+		const found = this.agents.get(input);
+		if (!found) throw new Error(`Unknown agent: ${input}`);
+		return found;
+	}
+
+	resolveTools(agent: Agent): ToolDefinition[] {
+		const names = agent.tools && agent.tools.length > 0 ? agent.tools : [...this.tools.keys()];
+		const out: ToolDefinition[] = [];
+		for (const name of names) {
+			const tool = this.tools.get(name);
+			if (tool) out.push(tool);
+		}
+		return out;
+	}
+}

package/src/client.ts

@@ -0,0 +1,52 @@
+import { Registry } from './agents';
+import { run, runStream } from './run';
+import type {
+	Agent,
+	AgentDefinition,
+	RunParams,
+	RunResult,
+	StreamEvent,
+	ToolDefinition
+} from './types';
+
+/**
+ * AI agents client. Stateless besides the agent/tool registry; create one per app
+ * (or per request — they're cheap).
+ */
+export class AiAgentsClient {
+	private readonly registry: Registry;
+
+	constructor() {
+		this.registry = new Registry();
+	}
+
+	registerTool<I, O>(tool: ToolDefinition<I, O>): ToolDefinition<I, O> {
+		return this.registry.registerTool(tool);
+	}
+
+	createAgent(definition: AgentDefinition): Agent {
+		return this.registry.createAgent(definition);
+	}
+
+	async run(params: RunParams): Promise<RunResult> {
+		return run(this.registry, params);
+	}
+
+	runStream(params: RunParams): AsyncGenerator<StreamEvent, void, unknown> {
+		return runStream(this.registry, params);
+	}
+
+	/** Direct access to the underlying registry for advanced introspection. */
+	get raw(): Registry {
+		return this.registry;
+	}
+}
+
+/**
+ * Factory. Provider auth comes from environment variables. To explicitly configure
+ * provider clients (e.g., for testing), pass `LanguageModel` instances to
+ * `createAgent({ model })` instead of string identifiers.
+ */
+export function createClient(): AiAgentsClient {
+	return new AiAgentsClient();
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Public API
+export { createClient, AiAgentsClient } from './client';
+export { Registry } from './agents';
+export { run, runStream } from './run';
+export { sanitizeRichHtml } from './sanitize';
+
+// Types
+export type {
+	ModelId,
+	ModelLike,
+	Message,
+	ToolDefinition,
+	ToolContext,
+	AgentDefinition,
+	Agent,
+	RunParams,
+	RunResult,
+	StreamEvent
+} from './types';

package/src/run.ts

@@ -0,0 +1,153 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+import { generateText, streamText, tool, type ModelMessage, type Tool } from 'ai';
+import type { Registry } from './agents';
+import type {
+	Message,
+	RunParams,
+	RunResult,
+	StreamEvent,
+	Agent,
+	ToolDefinition
+} from './types';
+
+function buildMessages(agent: Agent, params: RunParams): ModelMessage[] {
+	const messages: ModelMessage[] = [];
+
+	const history = params.history ?? [];
+	const hasSystem = history.some((m) => m.role === 'system');
+	if (!hasSystem && agent.instructions) {
+		messages.push({ role: 'system', content: agent.instructions });
+	}
+
+	for (const m of history) messages.push(m as unknown as ModelMessage);
+
+	if (params.message) {
+		messages.push({ role: 'user', content: params.message });
+	}
+
+	return messages;
+}
+
+function buildTools(
+	registry: Registry,
+	agent: Agent,
+	context: Record<string, unknown>
+): Record<string, Tool> {
+	const defs = registry.resolveTools(agent);
+	const out: Record<string, Tool> = {};
+	for (const def of defs as ToolDefinition[]) {
+		out[def.name] = tool({
+			description: def.description,
+			inputSchema: def.inputSchema,
+			execute: async (input, opts: { toolCallId: string }) =>
+				def.execute(input, { toolCallId: opts.toolCallId, app: context })
+		});
+	}
+	return out;
+}
+
+export async function run(registry: Registry, params: RunParams): Promise<RunResult> {
+	const agent = registry.resolveAgent(params.agent);
+	const messages = buildMessages(agent, params);
+	const tools = buildTools(registry, agent, params.context ?? {});
+
+	const result = await generateText({
+		model: agent.model,
+		messages,
+		tools,
+		temperature: params.temperature ?? agent.temperature,
+		maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
+		stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
+		providerOptions: agent.providerOptions
+	});
+
+	return {
+		text: result.text,
+		finishReason: result.finishReason as string,
+		usage: {
+			inputTokens: result.usage?.inputTokens ?? 0,
+			outputTokens: result.usage?.outputTokens ?? 0,
+			totalTokens: result.usage?.totalTokens ?? 0
+		},
+		toolCalls: (result.toolCalls ?? []).map((c) => ({
+			toolCallId: c.toolCallId,
+			toolName: c.toolName,
+			input: c.input
+		})),
+		toolResults: (result.toolResults ?? []).map((r) => ({
+			toolCallId: r.toolCallId,
+			toolName: r.toolName,
+			output: (r as { output: unknown }).output
+		})),
+		raw: result
+	};
+}
+
+export async function* runStream(
+	registry: Registry,
+	params: RunParams
+): AsyncGenerator<StreamEvent, void, unknown> {
+	const agent = registry.resolveAgent(params.agent);
+	const messages = buildMessages(agent, params);
+	const tools = buildTools(registry, agent, params.context ?? {});
+
+	const result = streamText({
+		model: agent.model,
+		messages,
+		tools,
+		temperature: params.temperature ?? agent.temperature,
+		maxOutputTokens: params.maxOutputTokens ?? agent.maxOutputTokens,
+		stopWhen: ({ steps }) => steps.length >= (params.maxSteps ?? 8),
+		providerOptions: agent.providerOptions
+	});
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	for await (const part of result.fullStream as AsyncIterable<any>) {
+		switch (part.type) {
+			case 'text-delta':
+				yield { type: 'text-delta', text: part.text ?? part.delta ?? '' };
+				break;
+			case 'tool-call':
+				yield {
+					type: 'tool-call',
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					input: part.input ?? part.args
+				};
+				break;
+			case 'tool-result':
+				yield {
+					type: 'tool-result',
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					output: part.output ?? part.result
+				};
+				break;
+			case 'tool-error':
+				yield {
+					type: 'tool-error',
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					error: part.error
+				};
+				break;
+			case 'finish':
+				yield {
+					type: 'finish',
+					finishReason: part.finishReason,
+					usage: {
+						inputTokens: part.usage?.inputTokens ?? 0,
+						outputTokens: part.usage?.outputTokens ?? 0,
+						totalTokens: part.usage?.totalTokens ?? 0
+					}
+				};
+				break;
+			case 'error':
+				yield { type: 'error', error: part.error };
+				break;
+			// Silently drop other chunk types (start/step boundaries, raw text accumulators, etc.).
+		}
+	}
+}
+
+export type { Message };

package/src/sanitize.ts

@@ -0,0 +1,80 @@
+/**
+ * Minimal HTML sanitizer for AI-generated rich text. Strips script/style/iframe and
+ * inline event handlers; keeps a small allowlist of tags and attributes suitable for
+ * advisor output.
+ *
+ * Ported from @kigathi/ai-agents v1.1.0 with minor TS typing tweaks.
+ */
+
+const ALLOWED_TAGS = new Set([
+	'a',
+	'b',
+	'blockquote',
+	'br',
+	'code',
+	'div',
+	'em',
+	'h1',
+	'h2',
+	'h3',
+	'h4',
+	'h5',
+	'h6',
+	'hr',
+	'i',
+	'li',
+	'ol',
+	'p',
+	'pre',
+	'span',
+	'strong',
+	'table',
+	'tbody',
+	'td',
+	'th',
+	'thead',
+	'tr',
+	'u',
+	'ul'
+]);
+
+const ALLOWED_ATTRS: Record<string, Set<string>> = {
+	a: new Set(['href', 'title', 'target', 'rel']),
+	'*': new Set(['class'])
+};
+
+const UNSAFE_PROTOCOLS = /^\s*(javascript|data|vbscript):/i;
+
+export function sanitizeRichHtml(input: string | null | undefined): string {
+	if (!input) return '';
+	let html = String(input);
+
+	// Strip dangerous tags wholesale.
+	html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, '');
+	html = html.replace(/<\s*(script|style|iframe|object|embed|link|meta)[^>]*\/?\s*>/gi, '');
+
+	// Strip on* attributes.
+	html = html.replace(/\s+on[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '');
+
+	// Strip unsafe href/src values.
+	html = html.replace(
+		/\s+(href|src)\s*=\s*("(?:[^"]*?)"|'(?:[^']*?)'|[^\s>]+)/gi,
+		(match, attr: string, value: string) => {
+			const v = value.replace(/^['"]|['"]$/g, '');
+			if (UNSAFE_PROTOCOLS.test(v)) return '';
+			return ` ${attr}="${v.replace(/"/g, '&quot;')}"`;
+		}
+	);
+
+	// Optional: drop tags not in allowlist. We do this last so attribute stripping above
+	// applies to the broader HTML stream first.
+	html = html.replace(/<\s*\/?\s*([a-zA-Z][a-zA-Z0-9]*)\b[^>]*>/g, (match, tagName: string) => {
+		const lower = tagName.toLowerCase();
+		if (ALLOWED_TAGS.has(lower)) return match;
+		return '';
+	});
+
+	return html;
+}
+
+export { ALLOWED_TAGS, ALLOWED_ATTRS };

package/src/types.ts

@@ -0,0 +1,110 @@
+import type { z } from 'zod';
+
+/**
+ * A model identifier. Vercel AI SDK v6 accepts strings like `'openai/gpt-4o'`,
+ * `'anthropic/claude-sonnet-4.5'`, `'google/gemini-2.5-flash'`. Provider auth comes
+ * from environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+ * `GOOGLE_GENERATIVE_AI_API_KEY`) unless you wire an explicit provider object.
+ */
+export type ModelId = string;
+
+/**
+ * Anything `streamText` / `generateText` accepts as `model`. Use a string for
+ * registry-resolved providers; pass a `LanguageModel` instance for custom wiring.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ModelLike = ModelId | { specificationVersion: string; [k: string]: any };
+
+export type ToolDefinition<Input = unknown, Output = unknown> = {
+	name: string;
+	description: string;
+	/**
+	 * Zod schema for the tool's input arguments. The AI SDK uses this to constrain
+	 * the model's function-call output and to type the `execute` callback.
+	 */
+	inputSchema: z.ZodSchema<Input>;
+	execute: (input: Input, context: ToolContext) => Promise<Output> | Output;
+};
+
+export type ToolContext = {
+	/** Unique tool call id from the model, useful for correlating tool-call → tool-result. */
+	toolCallId: string;
+	/** Forwarded from RunParams.context — apps thread per-request state (user id, locale, etc.). */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	app: Record<string, any>;
+};
+
+export type Message =
+	| { role: 'system'; content: string }
+	| { role: 'user'; content: string }
+	| { role: 'assistant'; content: string };
+
+export type AgentDefinition = {
+	/** Stable identifier; used as the lookup key. Defaults to `name`. */
+	id?: string;
+	name: string;
+	model: ModelLike;
+	/** System prompt. Inserted as a `system` message when no system message is in the history. */
+	instructions?: string;
+	temperature?: number;
+	maxOutputTokens?: number;
+	/**
+	 * Tool names this agent may call. If omitted, all globally-registered tools are available.
+	 */
+	tools?: readonly string[];
+	/**
+	 * Provider-specific options. Forwarded to Vercel AI SDK's `providerOptions`.
+	 * Example: `{ anthropic: { cacheControl: { type: 'ephemeral' } } }`.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	providerOptions?: Record<string, Record<string, any>>;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	metadata?: Record<string, any>;
+};
+
+export type Agent = Required<Pick<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>> &
+	Omit<AgentDefinition, 'id' | 'name' | 'model' | 'instructions'>;
+
+export type RunParams = {
+	/** Agent id, name, or definition object. */
+	agent: string | AgentDefinition;
+	/** The new user message. Combined with `history` to form the full conversation. */
+	message?: string;
+	/** Prior conversation. The agent's `instructions` is prepended as a system message. */
+	history?: readonly Message[];
+	/** Override `maxOutputTokens` per call. */
+	maxOutputTokens?: number;
+	/** Override `temperature` per call. */
+	temperature?: number;
+	/** Max number of tool-call iterations before bailing. Default 8. */
+	maxSteps?: number;
+	/** Forwarded to tool `execute(input, context)`. */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	context?: Record<string, any>;
+};
+
+export type RunResult = {
+	text: string;
+	finishReason: string;
+	usage: {
+		inputTokens: number;
+		outputTokens: number;
+		totalTokens: number;
+	};
+	toolCalls: { toolCallId: string; toolName: string; input: unknown }[];
+	toolResults: { toolCallId: string; toolName: string; output: unknown }[];
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	raw: any;
+};
+
+export type StreamEvent =
+	| { type: 'text-delta'; text: string }
+	| { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }
+	| { type: 'tool-result'; toolCallId: string; toolName: string; output: unknown }
+	| { type: 'tool-error'; toolCallId: string; toolName: string; error: unknown }
+	| {
+			type: 'finish';
+			finishReason: string;
+			usage: { inputTokens: number; outputTokens: number; totalTokens: number };
+	  }
+	| { type: 'error'; error: unknown };