@jambonz/tools 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,139 @@
+/**
+ * JSON Schema for a tool's parameters, following the OpenAI function-calling format.
+ */
+interface ToolParameters {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+}
+/**
+ * The schema definition passed to llmOptions.tools in a jambonz pipeline verb.
+ * Compatible with OpenAI, Anthropic, Google, and Bedrock function-calling formats.
+ */
+interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: ToolParameters;
+}
+/**
+ * A pre-built, reusable tool for jambonz pipeline voice AI agents.
+ *
+ * Each tool bundles:
+ * - `schema` — the tool definition the LLM needs to know how to call it
+ * - `execute` — the handler that runs when the LLM invokes the tool
+ */
+interface JambonzTool {
+    /** Tool schema for llmOptions.tools */
+    schema: ToolSchema;
+    /** Execute the tool and return a text result for the LLM */
+    execute(args: Record<string, any>): Promise<string>;
+}
+/**
+ * Minimal session interface — matches @jambonz/sdk WebSocket session
+ * without requiring a hard dependency on the SDK.
+ */
+interface SessionLike {
+    on(event: string, handler: (evt: any) => void): void;
+    sendToolOutput(toolCallId: string, data: unknown): void;
+}
+
+interface ToolCallEvent {
+    tool_call_id: string;
+    name: string;
+    arguments: Record<string, any>;
+}
+/**
+ * Register one or more tools on a jambonz session.
+ *
+ * Listens on the given hook path for tool-call events, dispatches to the
+ * matching tool's execute() method, and sends the result back via
+ * session.sendToolOutput(). Unknown tool names are reported as errors.
+ *
+ * @param session  - A jambonz WebSocket session (or any object with .on() and .sendToolOutput())
+ * @param hookPath - The toolHook path used in the pipeline verb (e.g. '/tool-call')
+ * @param tools    - Array of JambonzTool instances to register
+ * @param options  - Optional configuration
+ * @param options.logger - A pino-compatible logger for debug/error output
+ * @param options.onUnknownTool - Custom handler for unrecognized tool names
+ */
+declare function registerTools(session: SessionLike, hookPath: string, tools: JambonzTool[], options?: {
+    logger?: {
+        info: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+    onUnknownTool?: (session: SessionLike, evt: ToolCallEvent) => void;
+}): void;
+
+interface TavilySearchOptions {
+    /** Tavily API key (required) */
+    apiKey: string;
+    /** Maximum number of results to return (default: 3) */
+    maxResults?: number;
+    /** Search depth: 'basic' is faster, 'advanced' is more thorough (default: 'basic') */
+    searchDepth?: 'basic' | 'advanced';
+    /** Topic category (default: 'general') */
+    topic?: 'general' | 'news' | 'finance';
+    /** Only include results from these domains */
+    includeDomains?: string[];
+    /** Exclude results from these domains */
+    excludeDomains?: string[];
+}
+/**
+ * Create a web search tool powered by the Tavily Search API.
+ *
+ * Useful for answering questions about current events, recent news,
+ * or any topic that requires up-to-date information.
+ *
+ * Requires a Tavily API key — sign up at https://tavily.com
+ */
+declare function createTavilySearch(options: TavilySearchOptions): JambonzTool;
+
+interface WeatherOptions {
+    /** Temperature scale (default: 'celsius') */
+    scale?: 'celsius' | 'fahrenheit';
+}
+/**
+ * Create a weather lookup tool using the free Open-Meteo API.
+ *
+ * No API key required. Provides current temperature, wind speed,
+ * and weather conditions for any location worldwide.
+ */
+declare function createWeather(options?: WeatherOptions): JambonzTool;
+
+interface WikipediaOptions {
+    /** Maximum number of sentences to return from the article summary (default: 5) */
+    maxSentences?: number;
+    /** Wikipedia language edition (default: 'en') */
+    language?: string;
+}
+/**
+ * Create a Wikipedia lookup tool using the free Wikipedia REST API.
+ *
+ * No API key required. Searches Wikipedia and returns article summaries,
+ * ideal for answering general knowledge questions in voice conversations.
+ */
+declare function createWikipedia(options?: WikipediaOptions): JambonzTool;
+
+/**
+ * Create a safe math calculator tool.
+ *
+ * Uses a recursive descent parser — no eval() — to safely evaluate
+ * arithmetic expressions. Ideal for voice agents handling calculations
+ * like tips, conversions, or simple math.
+ */
+declare function createCalculator(): JambonzTool;
+
+interface DateTimeOptions {
+    /** Default timezone when none is specified (default: 'UTC') */
+    defaultTimezone?: string;
+}
+/**
+ * Create a date/time tool using the built-in Intl API.
+ *
+ * No API key required. Returns the current date, time, and timezone
+ * for any IANA timezone. Handles common city-to-timezone mapping for
+ * cases where the LLM sends a city name instead of an IANA zone.
+ */
+declare function createDateTime(options?: DateTimeOptions): JambonzTool;
+
+export { type DateTimeOptions, type JambonzTool, type SessionLike, type TavilySearchOptions, type ToolParameters, type ToolSchema, type WeatherOptions, type WikipediaOptions, createCalculator, createDateTime, createTavilySearch, createWeather, createWikipedia, registerTools };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * JSON Schema for a tool's parameters, following the OpenAI function-calling format.
+ */
+interface ToolParameters {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+}
+/**
+ * The schema definition passed to llmOptions.tools in a jambonz pipeline verb.
+ * Compatible with OpenAI, Anthropic, Google, and Bedrock function-calling formats.
+ */
+interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: ToolParameters;
+}
+/**
+ * A pre-built, reusable tool for jambonz pipeline voice AI agents.
+ *
+ * Each tool bundles:
+ * - `schema` — the tool definition the LLM needs to know how to call it
+ * - `execute` — the handler that runs when the LLM invokes the tool
+ */
+interface JambonzTool {
+    /** Tool schema for llmOptions.tools */
+    schema: ToolSchema;
+    /** Execute the tool and return a text result for the LLM */
+    execute(args: Record<string, any>): Promise<string>;
+}
+/**
+ * Minimal session interface — matches @jambonz/sdk WebSocket session
+ * without requiring a hard dependency on the SDK.
+ */
+interface SessionLike {
+    on(event: string, handler: (evt: any) => void): void;
+    sendToolOutput(toolCallId: string, data: unknown): void;
+}
+
+interface ToolCallEvent {
+    tool_call_id: string;
+    name: string;
+    arguments: Record<string, any>;
+}
+/**
+ * Register one or more tools on a jambonz session.
+ *
+ * Listens on the given hook path for tool-call events, dispatches to the
+ * matching tool's execute() method, and sends the result back via
+ * session.sendToolOutput(). Unknown tool names are reported as errors.
+ *
+ * @param session  - A jambonz WebSocket session (or any object with .on() and .sendToolOutput())
+ * @param hookPath - The toolHook path used in the pipeline verb (e.g. '/tool-call')
+ * @param tools    - Array of JambonzTool instances to register
+ * @param options  - Optional configuration
+ * @param options.logger - A pino-compatible logger for debug/error output
+ * @param options.onUnknownTool - Custom handler for unrecognized tool names
+ */
+declare function registerTools(session: SessionLike, hookPath: string, tools: JambonzTool[], options?: {
+    logger?: {
+        info: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+    onUnknownTool?: (session: SessionLike, evt: ToolCallEvent) => void;
+}): void;
+
+interface TavilySearchOptions {
+    /** Tavily API key (required) */
+    apiKey: string;
+    /** Maximum number of results to return (default: 3) */
+    maxResults?: number;
+    /** Search depth: 'basic' is faster, 'advanced' is more thorough (default: 'basic') */
+    searchDepth?: 'basic' | 'advanced';
+    /** Topic category (default: 'general') */
+    topic?: 'general' | 'news' | 'finance';
+    /** Only include results from these domains */
+    includeDomains?: string[];
+    /** Exclude results from these domains */
+    excludeDomains?: string[];
+}
+/**
+ * Create a web search tool powered by the Tavily Search API.
+ *
+ * Useful for answering questions about current events, recent news,
+ * or any topic that requires up-to-date information.
+ *
+ * Requires a Tavily API key — sign up at https://tavily.com
+ */
+declare function createTavilySearch(options: TavilySearchOptions): JambonzTool;
+
+interface WeatherOptions {
+    /** Temperature scale (default: 'celsius') */
+    scale?: 'celsius' | 'fahrenheit';
+}
+/**
+ * Create a weather lookup tool using the free Open-Meteo API.
+ *
+ * No API key required. Provides current temperature, wind speed,
+ * and weather conditions for any location worldwide.
+ */
+declare function createWeather(options?: WeatherOptions): JambonzTool;
+
+interface WikipediaOptions {
+    /** Maximum number of sentences to return from the article summary (default: 5) */
+    maxSentences?: number;
+    /** Wikipedia language edition (default: 'en') */
+    language?: string;
+}
+/**
+ * Create a Wikipedia lookup tool using the free Wikipedia REST API.
+ *
+ * No API key required. Searches Wikipedia and returns article summaries,
+ * ideal for answering general knowledge questions in voice conversations.
+ */
+declare function createWikipedia(options?: WikipediaOptions): JambonzTool;
+
+/**
+ * Create a safe math calculator tool.
+ *
+ * Uses a recursive descent parser — no eval() — to safely evaluate
+ * arithmetic expressions. Ideal for voice agents handling calculations
+ * like tips, conversions, or simple math.
+ */
+declare function createCalculator(): JambonzTool;
+
+interface DateTimeOptions {
+    /** Default timezone when none is specified (default: 'UTC') */
+    defaultTimezone?: string;
+}
+/**
+ * Create a date/time tool using the built-in Intl API.
+ *
+ * No API key required. Returns the current date, time, and timezone
+ * for any IANA timezone. Handles common city-to-timezone mapping for
+ * cases where the LLM sends a city name instead of an IANA zone.
+ */
+declare function createDateTime(options?: DateTimeOptions): JambonzTool;
+
+export { type DateTimeOptions, type JambonzTool, type SessionLike, type TavilySearchOptions, type ToolParameters, type ToolSchema, type WeatherOptions, type WikipediaOptions, createCalculator, createDateTime, createTavilySearch, createWeather, createWikipedia, registerTools };