signalwire-agents 0.1.0

package/src/skills/builtin/weather_api.ts

@@ -0,0 +1,193 @@
+/**
+ * Weather API Skill - Fetches current weather data from OpenWeatherMap.
+ *
+ * Tier 2 built-in skill: requires WEATHER_API_KEY environment variable.
+ * Uses the OpenWeatherMap API to retrieve current weather conditions
+ * for a specified location.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** Response shape from the OpenWeatherMap current weather endpoint. */
+interface WeatherApiResponse {
+  name: string;
+  sys: { country: string };
+  main: {
+    temp: number;
+    feels_like: number;
+    humidity: number;
+    pressure: number;
+    temp_min: number;
+    temp_max: number;
+  };
+  weather: Array<{ main: string; description: string }>;
+  wind: { speed: number; deg: number };
+  visibility?: number;
+  clouds?: { all: number };
+  cod: number;
+  message?: string;
+}
+
+/**
+ * Fetches current weather data from OpenWeatherMap for any location worldwide.
+ *
+ * Tier 2 built-in skill. Requires the `WEATHER_API_KEY` environment variable
+ * containing a valid OpenWeatherMap API key. Supports metric, imperial, and
+ * standard temperature units via the `units` config option.
+ */
+export class WeatherApiSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `units` ("metric"|"imperial"|"standard").
+   */
+  constructor(config?: SkillConfig) {
+    super('weather_api', config);
+  }
+
+  /** @returns Manifest declaring WEATHER_API_KEY as required and config schema for units. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'weather_api',
+      description:
+        'Fetches current weather data from OpenWeatherMap for any location worldwide.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['weather', 'api', 'openweathermap', 'external'],
+      requiredEnvVars: ['WEATHER_API_KEY'],
+      configSchema: {
+        units: {
+          type: 'string',
+          description:
+            'Temperature units: "metric" (Celsius), "imperial" (Fahrenheit), or "standard" (Kelvin).',
+          default: 'metric',
+        },
+      },
+    };
+  }
+
+  /** @returns A single `get_weather` tool that fetches current weather for a location. */
+  getTools(): SkillToolDefinition[] {
+    const units = this.getConfig<string>('units', 'metric');
+
+    return [
+      {
+        name: 'get_weather',
+        description:
+          'Get the current weather conditions for a specified location. Returns temperature, humidity, wind speed, and weather description.',
+        parameters: {
+          location: {
+            type: 'string',
+            description:
+              'The city name, optionally with country code (e.g., "London", "Paris,FR", "New York,US").',
+          },
+        },
+        required: ['location'],
+        handler: async (args: Record<string, unknown>) => {
+          const location = args.location as string | undefined;
+
+          if (!location || typeof location !== 'string' || location.trim().length === 0) {
+            return new SwaigFunctionResult(
+              'Please provide a location to get the weather for.',
+            );
+          }
+
+          const apiKey = process.env['WEATHER_API_KEY'];
+          if (!apiKey) {
+            return new SwaigFunctionResult(
+              'Weather service is not configured. The WEATHER_API_KEY environment variable is missing.',
+            );
+          }
+
+          try {
+            const encodedLocation = encodeURIComponent(location.trim());
+            const url = `https://api.openweathermap.org/data/2.5/weather?q=${encodedLocation}&appid=${apiKey}&units=${units}`;
+
+            const response = await fetch(url);
+            const data = (await response.json()) as WeatherApiResponse;
+
+            if (!response.ok || data.cod !== 200) {
+              const errorMessage = data.message ?? `HTTP ${response.status}`;
+              return new SwaigFunctionResult(
+                `Could not retrieve weather for "${location}": ${errorMessage}. Please check the location name and try again.`,
+              );
+            }
+
+            const unitLabel = units === 'imperial' ? 'F' : units === 'standard' ? 'K' : 'C';
+            const speedUnit = units === 'imperial' ? 'mph' : 'm/s';
+
+            const weatherDesc =
+              data.weather.length > 0
+                ? data.weather.map((w) => w.description).join(', ')
+                : 'unknown';
+
+            const parts: string[] = [
+              `Weather for ${data.name}, ${data.sys.country}:`,
+              `Conditions: ${weatherDesc}.`,
+              `Temperature: ${data.main.temp}\u00B0${unitLabel} (feels like ${data.main.feels_like}\u00B0${unitLabel}).`,
+              `High: ${data.main.temp_max}\u00B0${unitLabel}, Low: ${data.main.temp_min}\u00B0${unitLabel}.`,
+              `Humidity: ${data.main.humidity}%.`,
+              `Wind: ${data.wind.speed} ${speedUnit}.`,
+              `Pressure: ${data.main.pressure} hPa.`,
+            ];
+
+            if (data.visibility !== undefined) {
+              const visKm = (data.visibility / 1000).toFixed(1);
+              parts.push(`Visibility: ${visKm} km.`);
+            }
+
+            if (data.clouds?.all !== undefined) {
+              parts.push(`Cloud cover: ${data.clouds.all}%.`);
+            }
+
+            return new SwaigFunctionResult(parts.join(' '));
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Failed to fetch weather data for "${location}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing weather lookup capabilities and configured units. */
+  getPromptSections(): SkillPromptSection[] {
+    const units = this.getConfig<string>('units', 'metric');
+    const unitDesc =
+      units === 'imperial'
+        ? 'Fahrenheit'
+        : units === 'standard'
+          ? 'Kelvin'
+          : 'Celsius';
+
+    return [
+      {
+        title: 'Weather Information',
+        body: 'You can look up current weather conditions for any location worldwide.',
+        bullets: [
+          'Use the get_weather tool when a user asks about current weather conditions.',
+          'You can specify a city name, optionally with a country code (e.g., "London", "Paris,FR").',
+          `Temperature is reported in ${unitDesc}.`,
+          'The weather data includes temperature, humidity, wind speed, pressure, and general conditions.',
+          'If the user asks about a forecast or future weather, let them know you can only provide current conditions.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating WeatherApiSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new WeatherApiSkill instance.
+ */
+export function createSkill(config?: SkillConfig): WeatherApiSkill {
+  return new WeatherApiSkill(config);
+}

package/src/skills/builtin/web_search.ts

@@ -0,0 +1,212 @@
+/**
+ * Web Search Skill - Searches the web using Google Custom Search API.
+ *
+ * Tier 3 built-in skill: requires GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_CX
+ * environment variables. Uses the Google Custom Search JSON API to perform
+ * web searches and return formatted results.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** A single search result item from the Google Custom Search API. */
+interface GoogleSearchItem {
+  /** Title of the search result. */
+  title: string;
+  /** URL of the search result. */
+  link: string;
+  /** Brief text snippet from the page. */
+  snippet: string;
+  /** Display-friendly domain name. */
+  displayLink?: string;
+  /** Structured page metadata. */
+  pagemap?: Record<string, unknown>;
+}
+
+/** Response shape from the Google Custom Search JSON API. */
+interface GoogleSearchResponse {
+  /** Array of search result items. */
+  items?: GoogleSearchItem[];
+  /** Metadata about the search execution. */
+  searchInformation?: {
+    totalResults: string;
+    searchTime: number;
+    formattedTotalResults: string;
+    formattedSearchTime: string;
+  };
+  /** Error details if the request failed. */
+  error?: {
+    code: number;
+    message: string;
+    errors: Array<{ message: string; domain: string; reason: string }>;
+  };
+}
+
+/**
+ * Searches the web using the Google Custom Search JSON API.
+ *
+ * Tier 3 built-in skill. Requires `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX`
+ * environment variables. Supports `max_results` (1-10) and `safe_search`
+ * ("off"|"medium"|"high") config options.
+ */
+export class WebSearchSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `max_results` and `safe_search`.
+   */
+  constructor(config?: SkillConfig) {
+    super('web_search', config);
+  }
+
+  /** @returns Manifest declaring GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_CX as required. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'web_search',
+      description:
+        'Searches the web using Google Custom Search API and returns formatted results with titles, links, and snippets.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['search', 'web', 'google', 'api', 'external'],
+      requiredEnvVars: ['GOOGLE_SEARCH_API_KEY', 'GOOGLE_SEARCH_CX'],
+      configSchema: {
+        max_results: {
+          type: 'number',
+          description:
+            'Maximum number of results to return (1-10). Defaults to 5.',
+          default: 5,
+        },
+        safe_search: {
+          type: 'string',
+          description:
+            'Safe search level: "off", "medium", or "high". Defaults to "medium".',
+          default: 'medium',
+        },
+      },
+    };
+  }
+
+  /** @returns A single `web_search` tool that performs a Google search and returns formatted results. */
+  getTools(): SkillToolDefinition[] {
+    const configMaxResults = this.getConfig<number>('max_results', 5);
+    const safeSearch = this.getConfig<string>('safe_search', 'medium');
+
+    return [
+      {
+        name: 'web_search',
+        description:
+          'Search the web for information on any topic. Returns a list of results with titles, links, and brief descriptions.',
+        parameters: {
+          query: {
+            type: 'string',
+            description: 'The search query to look up on the web.',
+          },
+          num_results: {
+            type: 'number',
+            description: `Number of results to return (1-10). Defaults to ${configMaxResults}.`,
+          },
+        },
+        required: ['query'],
+        handler: async (args: Record<string, unknown>) => {
+          const query = args.query as string | undefined;
+          const numResults = args.num_results as number | undefined;
+
+          if (!query || typeof query !== 'string' || query.trim().length === 0) {
+            return new SwaigFunctionResult(
+              'Please provide a search query.',
+            );
+          }
+
+          const apiKey = process.env['GOOGLE_SEARCH_API_KEY'];
+          const cx = process.env['GOOGLE_SEARCH_CX'];
+
+          if (!apiKey || !cx) {
+            return new SwaigFunctionResult(
+              'Web search is not configured. The GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_CX environment variables are required.',
+            );
+          }
+
+          const count = Math.max(1, Math.min(10, numResults ?? configMaxResults));
+
+          try {
+            const encodedQuery = encodeURIComponent(query.trim());
+            const safeParam = safeSearch !== 'off' ? `&safe=${safeSearch}` : '';
+            const url =
+              `https://www.googleapis.com/customsearch/v1` +
+              `?key=${apiKey}&cx=${cx}&q=${encodedQuery}&num=${count}${safeParam}`;
+
+            const response = await fetch(url);
+            const data = (await response.json()) as GoogleSearchResponse;
+
+            if (data.error) {
+              return new SwaigFunctionResult(
+                `Web search failed: ${data.error.message}`,
+              );
+            }
+
+            if (!data.items || data.items.length === 0) {
+              return new SwaigFunctionResult(
+                `No results found for "${query}".`,
+              );
+            }
+
+            const totalResults = data.searchInformation?.formattedTotalResults ?? 'unknown';
+            const searchTime = data.searchInformation?.formattedSearchTime ?? 'unknown';
+
+            const parts: string[] = [
+              `Web search results for "${query}" (${totalResults} results in ${searchTime} seconds):`,
+              '',
+            ];
+
+            for (let i = 0; i < data.items.length; i++) {
+              const item = data.items[i];
+              parts.push(`${i + 1}. ${item.title}`);
+              parts.push(`   URL: ${item.link}`);
+              if (item.snippet) {
+                parts.push(`   ${item.snippet.replace(/\n/g, ' ').trim()}`);
+              }
+              parts.push('');
+            }
+
+            return new SwaigFunctionResult(parts.join('\n').trim());
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Failed to perform web search for "${query}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing web search capabilities and usage guidance. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Web Search',
+        body: 'You can search the web for current information on any topic.',
+        bullets: [
+          'Use the web_search tool when the user asks about current events, facts, or any information you may not have.',
+          'You can specify the number of results to return (1-10).',
+          'Results include titles, URLs, and brief descriptions/snippets.',
+          'If a search returns no results, try rephrasing the query or using different terms.',
+          'Summarize the search results for the user rather than reading them verbatim.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating WebSearchSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new WebSearchSkill instance.
+ */
+export function createSkill(config?: SkillConfig): WebSearchSkill {
+  return new WebSearchSkill(config);
+}

package/src/skills/builtin/wikipedia_search.ts

@@ -0,0 +1,248 @@
+/**
+ * Wikipedia Search Skill - Searches Wikipedia for article summaries.
+ *
+ * Tier 3 built-in skill: no external API key required.
+ * Uses the Wikipedia REST API to fetch article summaries and extracts
+ * for any given topic.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** Response shape from the Wikipedia REST API page summary endpoint. */
+interface WikipediaSummaryResponse {
+  /** Page type (e.g., "standard", "disambiguation"). */
+  type: string;
+  /** Article title. */
+  title: string;
+  /** HTML-formatted display title. */
+  displaytitle?: string;
+  /** Plain-text article extract/summary. */
+  extract: string;
+  /** HTML-formatted extract. */
+  extract_html?: string;
+  /** Short description of the article. */
+  description?: string;
+  /** URLs to the full article. */
+  content_urls?: {
+    desktop?: { page: string };
+    mobile?: { page: string };
+  };
+  /** Thumbnail image information. */
+  thumbnail?: {
+    source: string;
+    width: number;
+    height: number;
+  };
+}
+
+/** Response shape from the Wikipedia search API. */
+interface WikipediaSearchResponse {
+  /** Array of matching page results. */
+  pages?: Array<{
+    id: number;
+    key: string;
+    title: string;
+    description?: string;
+    excerpt?: string;
+  }>;
+}
+
+/**
+ * Searches Wikipedia for article summaries and extracts.
+ *
+ * Tier 3 built-in skill with no external API key required. Uses the Wikipedia
+ * REST API to fetch article summaries for any given topic, with a configurable
+ * number of sentences.
+ */
+export class WikipediaSearchSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration (no config keys used by this skill).
+   */
+  constructor(config?: SkillConfig) {
+    super('wikipedia_search', config);
+  }
+
+  /** @returns Manifest with skill metadata (no required env vars). */
+  getManifest(): SkillManifest {
+    return {
+      name: 'wikipedia_search',
+      description:
+        'Searches Wikipedia for article summaries and extracts. No API key required.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['search', 'wikipedia', 'encyclopedia', 'knowledge', 'external'],
+    };
+  }
+
+  /** @returns A single `search_wikipedia` tool that fetches article summaries from Wikipedia. */
+  getTools(): SkillToolDefinition[] {
+    return [
+      {
+        name: 'search_wikipedia',
+        description:
+          'Search Wikipedia for information about a topic. Returns a summary of the most relevant article.',
+        parameters: {
+          query: {
+            type: 'string',
+            description:
+              'The topic or term to search for on Wikipedia.',
+          },
+          sentences: {
+            type: 'number',
+            description:
+              'Number of sentences to return in the summary (1-10). Defaults to 3.',
+          },
+        },
+        required: ['query'],
+        handler: async (args: Record<string, unknown>) => {
+          const query = args.query as string | undefined;
+          const sentences = args.sentences as number | undefined;
+
+          if (!query || typeof query !== 'string' || query.trim().length === 0) {
+            return new SwaigFunctionResult(
+              'Please provide a topic to search for on Wikipedia.',
+            );
+          }
+
+          const sentenceCount = Math.max(1, Math.min(10, sentences ?? 3));
+
+          try {
+            // First, try a direct page summary lookup
+            const encodedQuery = encodeURIComponent(query.trim().replace(/\s+/g, '_'));
+            const summaryUrl = `https://en.wikipedia.org/api/rest_v1/page/summary/${encodedQuery}`;
+
+            const summaryResponse = await fetch(summaryUrl, {
+              headers: { 'Accept': 'application/json', 'User-Agent': 'SignalWireAgentsSDK/1.0' },
+            });
+
+            if (summaryResponse.ok) {
+              const data = (await summaryResponse.json()) as WikipediaSummaryResponse;
+
+              if (data.type !== 'disambiguation' && data.extract) {
+                const extractSentences = data.extract.split(/(?<=[.!?])\s+/);
+                const trimmedExtract = extractSentences
+                  .slice(0, sentenceCount)
+                  .join(' ')
+                  .trim();
+
+                const pageUrl = data.content_urls?.desktop?.page ?? '';
+                const parts: string[] = [
+                  `Wikipedia: ${data.title}`,
+                ];
+                if (data.description) {
+                  parts.push(`(${data.description})`);
+                }
+                parts.push('');
+                parts.push(trimmedExtract);
+                if (pageUrl) {
+                  parts.push('');
+                  parts.push(`Read more: ${pageUrl}`);
+                }
+
+                return new SwaigFunctionResult(parts.join('\n').trim());
+              }
+            }
+
+            // If direct lookup failed, use the search API
+            const searchUrl = `https://en.wikipedia.org/w/rest.php/v1/search/page?q=${encodeURIComponent(query.trim())}&limit=1`;
+
+            const searchResponse = await fetch(searchUrl, {
+              headers: { 'Accept': 'application/json', 'User-Agent': 'SignalWireAgentsSDK/1.0' },
+            });
+
+            if (!searchResponse.ok) {
+              return new SwaigFunctionResult(
+                `Wikipedia search failed with status ${searchResponse.status}. Please try a different search term.`,
+              );
+            }
+
+            const searchData = (await searchResponse.json()) as WikipediaSearchResponse;
+
+            if (!searchData.pages || searchData.pages.length === 0) {
+              return new SwaigFunctionResult(
+                `No Wikipedia article found for "${query}". Try a different search term.`,
+              );
+            }
+
+            // Fetch the summary for the best match
+            const bestMatch = searchData.pages[0];
+            const matchUrl = `https://en.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(bestMatch.key)}`;
+
+            const matchResponse = await fetch(matchUrl, {
+              headers: { 'Accept': 'application/json', 'User-Agent': 'SignalWireAgentsSDK/1.0' },
+            });
+
+            if (!matchResponse.ok) {
+              // Fall back to the search excerpt
+              const excerpt = bestMatch.excerpt
+                ? bestMatch.excerpt.replace(/<[^>]*>/g, '').trim()
+                : 'No summary available.';
+              return new SwaigFunctionResult(
+                `Wikipedia: ${bestMatch.title}\n\n${excerpt}`,
+              );
+            }
+
+            const matchData = (await matchResponse.json()) as WikipediaSummaryResponse;
+            const extractSentences = matchData.extract.split(/(?<=[.!?])\s+/);
+            const trimmedExtract = extractSentences
+              .slice(0, sentenceCount)
+              .join(' ')
+              .trim();
+
+            const pageUrl = matchData.content_urls?.desktop?.page ?? '';
+            const parts: string[] = [`Wikipedia: ${matchData.title}`];
+            if (matchData.description) {
+              parts.push(`(${matchData.description})`);
+            }
+            parts.push('');
+            parts.push(trimmedExtract);
+            if (pageUrl) {
+              parts.push('');
+              parts.push(`Read more: ${pageUrl}`);
+            }
+
+            return new SwaigFunctionResult(parts.join('\n').trim());
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Failed to search Wikipedia for "${query}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing Wikipedia search capabilities and usage guidance. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Wikipedia Search',
+        body: 'You can search Wikipedia for information about any topic.',
+        bullets: [
+          'Use the search_wikipedia tool when the user asks about a specific topic, person, place, or concept.',
+          'Wikipedia provides encyclopedic summaries that are generally reliable for factual information.',
+          'You can specify the number of sentences to return (1-10) for shorter or more detailed summaries.',
+          'If a search returns no results, try rephrasing with the most common name or spelling.',
+          'Summarize the information naturally rather than reading it verbatim.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating WikipediaSearchSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new WikipediaSearchSkill instance.
+ */
+export function createSkill(config?: SkillConfig): WikipediaSearchSkill {
+  return new WikipediaSearchSkill(config);
+}

package/src/skills/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Skills framework for SignalWire AI Agents.
+ *
+ * Exports the base class, manager, registry, and all associated types
+ * needed to create, register, and manage agent skills.
+ */
+
+export { SkillBase } from './SkillBase.js';
+export type { SkillConfig, SkillToolDefinition, SkillPromptSection, SkillManifest } from './SkillBase.js';
+export { SkillManager } from './SkillManager.js';
+export { SkillRegistry } from './SkillRegistry.js';
+export type { SkillFactory } from './SkillRegistry.js';