signalwire-agents 0.1.0

package/src/skills/builtin/datasphere.ts

@@ -0,0 +1,225 @@
+/**
+ * DataSphere Skill - Searches SignalWire DataSphere for knowledge base content.
+ *
+ * Tier 3 built-in skill: requires SIGNALWIRE_PROJECT_ID, SIGNALWIRE_TOKEN,
+ * and SIGNALWIRE_SPACE environment variables. Uses the SignalWire DataSphere
+ * API to perform semantic search across uploaded documents.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** A single search result from the DataSphere API. */
+interface DataSphereResult {
+  /** Matched text chunk content. */
+  text: string;
+  /** Distance score (lower is more similar). */
+  score: number;
+  /** ID of the source document. */
+  document_id?: string;
+  /** Document metadata. */
+  metadata?: Record<string, unknown>;
+  /** Index of the chunk within the document. */
+  chunk_index?: number;
+}
+
+/** Response shape from the SignalWire DataSphere search API. */
+interface DataSphereResponse {
+  /** Array of search results. */
+  results?: DataSphereResult[];
+  /** Error message if the request failed. */
+  error?: string;
+  /** Additional error information. */
+  message?: string;
+}
+
+/**
+ * Searches SignalWire DataSphere for knowledge base content using semantic search.
+ *
+ * Tier 3 built-in skill. Requires `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN`,
+ * and `SIGNALWIRE_SPACE` environment variables. Supports `max_results` and
+ * `distance_threshold` config options.
+ */
+export class DataSphereSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `max_results` and `distance_threshold`.
+   */
+  constructor(config?: SkillConfig) {
+    super('datasphere', config);
+  }
+
+  /** @returns Manifest declaring SignalWire credentials as required env vars. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'datasphere',
+      description:
+        'Searches SignalWire DataSphere for knowledge base content using semantic search across uploaded documents.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['search', 'datasphere', 'signalwire', 'knowledge', 'rag', 'external'],
+      requiredEnvVars: ['SIGNALWIRE_PROJECT_ID', 'SIGNALWIRE_TOKEN', 'SIGNALWIRE_SPACE'],
+      configSchema: {
+        max_results: {
+          type: 'number',
+          description: 'Maximum number of results to return. Defaults to 5.',
+          default: 5,
+        },
+        distance_threshold: {
+          type: 'number',
+          description:
+            'Maximum distance threshold for results (0-1, lower is more similar). Defaults to 0.7.',
+          default: 0.7,
+        },
+      },
+    };
+  }
+
+  /** @returns A single `search_datasphere` tool that performs semantic search on uploaded documents. */
+  getTools(): SkillToolDefinition[] {
+    const maxResults = this.getConfig<number>('max_results', 5);
+    const distanceThreshold = this.getConfig<number>('distance_threshold', 0.7);
+
+    return [
+      {
+        name: 'search_datasphere',
+        description:
+          'Search the SignalWire DataSphere knowledge base for relevant information. Returns the most relevant text chunks from uploaded documents.',
+        parameters: {
+          query: {
+            type: 'string',
+            description: 'The question or topic to search for in the knowledge base.',
+          },
+          document_id: {
+            type: 'string',
+            description:
+              'Optional: limit search to a specific document by its ID.',
+          },
+        },
+        required: ['query'],
+        handler: async (args: Record<string, unknown>) => {
+          const query = args.query as string | undefined;
+          const documentId = args.document_id as string | undefined;
+
+          if (!query || typeof query !== 'string' || query.trim().length === 0) {
+            return new SwaigFunctionResult(
+              'Please provide a query to search the knowledge base.',
+            );
+          }
+
+          const projectId = process.env['SIGNALWIRE_PROJECT_ID'];
+          const token = process.env['SIGNALWIRE_TOKEN'];
+          const space = process.env['SIGNALWIRE_SPACE'];
+
+          if (!projectId || !token || !space) {
+            return new SwaigFunctionResult(
+              'DataSphere is not configured. The SIGNALWIRE_PROJECT_ID, SIGNALWIRE_TOKEN, and SIGNALWIRE_SPACE environment variables are required.',
+            );
+          }
+
+          try {
+            const spaceHost = space.includes('.') ? space : `${space}.signalwire.com`;
+            const url = `https://${spaceHost}/api/datasphere/documents/search`;
+
+            const requestBody: Record<string, unknown> = {
+              query: query.trim(),
+              count: maxResults,
+              distance: distanceThreshold,
+            };
+
+            if (documentId && typeof documentId === 'string' && documentId.trim().length > 0) {
+              requestBody['document_id'] = documentId.trim();
+            }
+
+            const authHeader = Buffer.from(`${projectId}:${token}`).toString('base64');
+
+            const response = await fetch(url, {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Basic ${authHeader}`,
+              },
+              body: JSON.stringify(requestBody),
+            });
+
+            if (!response.ok) {
+              const errorText = await response.text();
+              let errorMsg: string;
+              try {
+                const errorData = JSON.parse(errorText) as DataSphereResponse;
+                errorMsg = errorData.error ?? errorData.message ?? `HTTP ${response.status}`;
+              } catch {
+                errorMsg = `HTTP ${response.status}: ${errorText.slice(0, 200)}`;
+              }
+              return new SwaigFunctionResult(
+                `DataSphere search failed: ${errorMsg}`,
+              );
+            }
+
+            const data = (await response.json()) as DataSphereResponse;
+
+            if (!data.results || data.results.length === 0) {
+              return new SwaigFunctionResult(
+                `No relevant results found in the knowledge base for "${query}".`,
+              );
+            }
+
+            const parts: string[] = [
+              `Knowledge base results for "${query}" (${data.results.length} results):`,
+              '',
+            ];
+
+            for (let i = 0; i < data.results.length; i++) {
+              const result = data.results[i];
+              const score = (1 - result.score).toFixed(2);
+              parts.push(`--- Result ${i + 1} (relevance: ${score}) ---`);
+              parts.push(result.text.trim());
+              if (result.document_id) {
+                parts.push(`[Document: ${result.document_id}]`);
+              }
+              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 search DataSphere for "${query}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing DataSphere knowledge base search capabilities. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Knowledge Base Search (DataSphere)',
+        body: 'You have access to a knowledge base of documents that can be searched for relevant information.',
+        bullets: [
+          'Use the search_datasphere tool when the user asks questions that might be answered by internal documentation or uploaded knowledge.',
+          'Results are ranked by relevance. Higher relevance scores indicate better matches.',
+          'You can optionally search within a specific document by providing its ID.',
+          'Synthesize information from multiple results when appropriate.',
+          'If no results are found, let the user know and suggest rephrasing their question.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating DataSphereSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new DataSphereSkill instance.
+ */
+export function createSkill(config?: SkillConfig): DataSphereSkill {
+  return new DataSphereSkill(config);
+}

package/src/skills/builtin/datasphere_serverless.ts

@@ -0,0 +1,194 @@
+/**
+ * DataSphere Serverless Skill - Searches SignalWire DataSphere using a DataMap.
+ *
+ * Tier 3 built-in skill: requires SIGNALWIRE_PROJECT_ID, SIGNALWIRE_TOKEN,
+ * and SIGNALWIRE_SPACE environment variables. Unlike the standard datasphere
+ * skill, this uses a DataMap to execute the search server-side without
+ * requiring a webhook endpoint. Ideal for serverless or edge deployments.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+import { DataMap } from '../../DataMap.js';
+
+/**
+ * Searches SignalWire DataSphere using a server-side DataMap for serverless execution.
+ *
+ * Tier 3 built-in skill. Requires `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_TOKEN`,
+ * and `SIGNALWIRE_SPACE` environment variables. Unlike the standard DataSphere
+ * skill, this generates a DataMap configuration that SignalWire executes directly
+ * without needing a webhook endpoint. Supports `max_results`, `distance_threshold`,
+ * and `document_id` config options.
+ */
+export class DataSphereServerlessSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `max_results`, `distance_threshold`, `document_id`.
+   */
+  constructor(config?: SkillConfig) {
+    super('datasphere_serverless', config);
+  }
+
+  /** @returns Manifest declaring SignalWire credentials as required env vars. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'datasphere_serverless',
+      description:
+        'Searches SignalWire DataSphere using a server-side DataMap. No webhook endpoint required; executes entirely on the SignalWire platform.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['search', 'datasphere', 'signalwire', 'knowledge', 'rag', 'serverless', 'datamap'],
+      requiredEnvVars: ['SIGNALWIRE_PROJECT_ID', 'SIGNALWIRE_TOKEN', 'SIGNALWIRE_SPACE'],
+      configSchema: {
+        max_results: {
+          type: 'number',
+          description: 'Maximum number of results to return. Defaults to 5.',
+          default: 5,
+        },
+        distance_threshold: {
+          type: 'number',
+          description:
+            'Maximum distance threshold for results (0-1, lower is more similar). Defaults to 0.7.',
+          default: 0.7,
+        },
+        document_id: {
+          type: 'string',
+          description: 'Optional: restrict search to a specific document ID.',
+        },
+      },
+    };
+  }
+
+  /**
+   * Build the DataMap-based SWAIG function definition for server-side
+   * DataSphere search. This generates a data_map configuration that
+   * SignalWire executes directly, without needing a webhook callback.
+   */
+  private buildDataMapFunction(): Record<string, unknown> {
+    const maxResults = this.getConfig<number>('max_results', 5);
+    const distanceThreshold = this.getConfig<number>('distance_threshold', 0.7);
+    const documentId = this.getConfig<string | undefined>('document_id', undefined);
+
+    const dm = new DataMap('search_datasphere');
+    dm.enableEnvExpansion(true);
+
+    dm.purpose(
+      'Search the SignalWire DataSphere knowledge base for relevant information. ' +
+      'Returns the most relevant text chunks from uploaded documents.',
+    );
+
+    dm.parameter('query', 'string', 'The question or topic to search for in the knowledge base.', {
+      required: true,
+    });
+
+    // Build the request body
+    const requestBody: Record<string, unknown> = {
+      query: '%{args.query}',
+      count: maxResults,
+      distance: distanceThreshold,
+    };
+
+    if (documentId) {
+      requestBody['document_id'] = documentId;
+    }
+
+    // Configure the webhook to call the DataSphere API
+    dm.webhook('POST', 'https://${ENV.SIGNALWIRE_SPACE}.signalwire.com/api/datasphere/documents/search', {
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': 'Basic ${ENV.SIGNALWIRE_AUTH}',
+      },
+    });
+
+    dm.body(requestBody);
+
+    dm.output(
+      new SwaigFunctionResult(
+        'Knowledge base results for the query: %{array[0].text} %{array[1].text} %{array[2].text}',
+      ),
+    );
+
+    dm.errorKeys(['error', 'message']);
+
+    dm.fallbackOutput(
+      new SwaigFunctionResult(
+        'No relevant results found in the knowledge base. Try rephrasing your question.',
+      ),
+    );
+
+    return dm.toSwaigFunction();
+  }
+
+  /**
+   * Return a stub tool definition since this skill uses DataMap-based execution.
+   * The actual DataMap function is provided by getDataMapTools().
+   * @returns A single stub `search_datasphere` tool that explains its DataMap nature.
+   */
+  getTools(): SkillToolDefinition[] {
+    // DataMap-based skills do not use handler-based tools.
+    // The tool is provided via getDataMapTools() instead.
+    // We return a stub handler that explains this to prevent confusion
+    // if something tries to invoke it as a regular tool.
+    return [
+      {
+        name: 'search_datasphere',
+        description:
+          'Search the SignalWire DataSphere knowledge base for relevant information. (Serverless DataMap mode)',
+        parameters: {
+          query: {
+            type: 'string',
+            description: 'The question or topic to search for in the knowledge base.',
+          },
+        },
+        required: ['query'],
+        handler: () => {
+          return new SwaigFunctionResult(
+            'This tool is configured for serverless DataMap execution. ' +
+            'It should be registered as a data_map function, not invoked via webhook.',
+          );
+        },
+      },
+    ];
+  }
+
+  /**
+   * Get DataMap-based tool definitions for server-side execution.
+   * These are registered directly in the SWML output as data_map functions
+   * rather than as webhook-backed SWAIG tools.
+   * @returns Array containing the DataSphere search DataMap function definition.
+   */
+  getDataMapTools(): Record<string, unknown>[] {
+    return [this.buildDataMapFunction()];
+  }
+
+  /** @returns Prompt section describing serverless DataSphere search capabilities. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Knowledge Base Search (DataSphere - Serverless)',
+        body: 'You have access to a knowledge base of documents that can be searched for relevant information. Searches are executed server-side for optimal performance.',
+        bullets: [
+          'Use the search_datasphere tool when the user asks questions that might be answered by internal documentation or uploaded knowledge.',
+          'Results are ranked by relevance and returned automatically.',
+          'This search runs entirely on the SignalWire platform without requiring external webhooks.',
+          'Synthesize information from the results when appropriate.',
+          'If no results are found, let the user know and suggest rephrasing their question.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating DataSphereServerlessSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new DataSphereServerlessSkill instance.
+ */
+export function createSkill(config?: SkillConfig): DataSphereServerlessSkill {
+  return new DataSphereServerlessSkill(config);
+}

package/src/skills/builtin/datetime.ts

@@ -0,0 +1,115 @@
+/**
+ * DateTime Skill - Provides current date/time with optional timezone support.
+ *
+ * Tier 1 built-in skill: no external dependencies required.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/**
+ * Provides the current date and time with optional timezone support.
+ *
+ * Tier 1 built-in skill with no external dependencies. Supports all IANA
+ * timezone identifiers via the Intl.DateTimeFormat API.
+ */
+export class DateTimeSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration (no config keys used by this skill).
+   */
+  constructor(config?: SkillConfig) {
+    super('datetime', config);
+  }
+
+  /** @returns Manifest with skill metadata and tags. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'datetime',
+      description: 'Provides current date and time information with timezone support.',
+      version: '1.0.0',
+      tags: ['utility', 'datetime', 'timezone'],
+    };
+  }
+
+  /** @returns A single `get_datetime` tool that returns the current date/time in a given timezone. */
+  getTools(): SkillToolDefinition[] {
+    return [
+      {
+        name: 'get_datetime',
+        description:
+          'Get the current date and time. Optionally specify a timezone to get the time in that timezone.',
+        parameters: {
+          timezone: {
+            type: 'string',
+            description:
+              'IANA timezone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo). Defaults to UTC if not specified.',
+          },
+        },
+        handler: (args: Record<string, unknown>) => {
+          const timezone = (args.timezone as string | undefined) ?? 'UTC';
+          const now = new Date();
+
+          try {
+            const dateFormatter = new Intl.DateTimeFormat('en-US', {
+              timeZone: timezone,
+              weekday: 'long',
+              year: 'numeric',
+              month: 'long',
+              day: 'numeric',
+            });
+
+            const timeFormatter = new Intl.DateTimeFormat('en-US', {
+              timeZone: timezone,
+              hour: '2-digit',
+              minute: '2-digit',
+              second: '2-digit',
+              hour12: true,
+              timeZoneName: 'short',
+            });
+
+            const dateStr = dateFormatter.format(now);
+            const timeStr = timeFormatter.format(now);
+
+            return new SwaigFunctionResult(
+              `The current date and time in ${timezone} is: ${dateStr}, ${timeStr}.`,
+            );
+          } catch {
+            return new SwaigFunctionResult(
+              `Invalid timezone "${timezone}". Please use a valid IANA timezone identifier such as America/New_York, Europe/London, or Asia/Tokyo.`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section instructing the AI how to use the datetime tool. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Date and Time',
+        body: 'You have the ability to check the current date and time.',
+        bullets: [
+          'Use the get_datetime tool to retrieve the current date and time.',
+          'You can specify a timezone using IANA timezone identifiers (e.g., America/New_York, Europe/London, Asia/Tokyo).',
+          'If no timezone is specified, UTC is used by default.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating DateTimeSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new DateTimeSkill instance.
+ */
+export function createSkill(config?: SkillConfig): DateTimeSkill {
+  return new DateTimeSkill(config);
+}