syllable-sdk 0.1.0-alpha.29 → 0.1.0-alpha.30

package/src/models/components/{sdktooldefinition.ts → tooldefinition.ts}

@@ -8,17 +8,17 @@ import { ClosedEnum } from "../../types/enums.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 import {
-  HttpEndpoint,
-  HttpEndpoint$inboundSchema,
-  HttpEndpoint$Outbound,
-  HttpEndpoint$outboundSchema,
-} from "./httpendpoint.js";
+  InternalTool,
+  InternalTool$inboundSchema,
+  InternalTool$Outbound,
+  InternalTool$outboundSchema,
+} from "./internaltool.js";
 import {
-  SDKInternalTool,
-  SDKInternalTool$inboundSchema,
-  SDKInternalTool$Outbound,
-  SDKInternalTool$outboundSchema,
-} from "./sdkinternaltool.js";
+  ToolHttpEndpoint,
+  ToolHttpEndpoint$inboundSchema,
+  ToolHttpEndpoint$Outbound,
+  ToolHttpEndpoint$outboundSchema,
+} from "./toolhttpendpoint.js";
 import {
   ToolParameterDefault,
   ToolParameterDefault$inboundSchema,
@@ -43,19 +43,111 @@ export type Defaults = One | { [k: string]: ToolParameterDefault };
 
 export type Result = {};
 
-export type SDKToolDefinition = {
+/**
+ * A tool that can be called from an LLM during the conversation.
+ *
+ * @remarks
+ *
+ * The tool can result in one of the following actions depending on the `type` field:
+ * - `action`:
+ *   A request to perform an action.
+ * - `endpoint`:
+ *   An HTTP API call to an external tool. Requires the `endpoint` field to be set too.
+ * - `context`:
+ *   Sets context variables based on the tool arguments, e.g. to change the session language. Only
+ *   `language` and `say` context vars are currently supported, but this will be made more generic.
+ *
+ * For example, to change the current session language:
+ * {
+ *   "type": "context",
+ *   "tool": {
+ *     "function": {
+ *       "name": "set_language",
+ *       "parameters": {
+ *         "language": {
+ *           "type": "string",
+ *           "description": "The ISO 639 language code to set for the session e.g. 'en-US'."
+ *         },
+ *         "message": {
+ *           "type": "string",
+ *           "description": "Inform the caller we're now speaking in the new language."
+ *         }
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * If `defaults` is provided, it will be used as the default values for the parameters of the
+ * tool call, if the LLM doesn't provide them:
+ * "defaults": {
+ *   "hospital": "Queens Hospital"
+ * }
+ *
+ * Some special "transform" handling is supported if the value is a dict with a single `transform`
+ * key. The parameter value will be transformed by the given `action` before being used as the
+ * default value:
+ *
+ * Removing an unwanted parameter:
+ * "defaults": {
+ *   "hospital": {
+ *     "transform": {
+ *       "action": "remove"
+ *     }
+ *   }
+ * }
+ *
+ * Using a value from another parameter and converting it to a dictionary:
+ * "defaults": {
+ *   "tags.hospital": "{vars.hospital}",
+ *   "tags.foo": "{params.foo}",
+ *   "foo": {
+ *     "transform": {
+ *       "action": "remove"
+ *     }
+ *   }
+ * }
+ *
+ * Add custom parameters from other parameters using Python's `format`:
+ * "defaults": {
+ *   "hello": {
+ *     "transform": {
+ *       "format": "Hello, {name}!"
+ *     }
+ *   }
+ * }
+ *
+ * Modify a value conditionally, e.g. change a `city` parameter with value "Bronx" to "The Bronx":
+ * {
+ *   "defaults": {
+ *     "city": {
+ *       "transform": {
+ *         "when": {"operator": "eq", "key": "city", "value": "Bronx"},
+ *         "action": "override",
+ *         "format": "The {city}"
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * Some common transform actions can be abbreviated using the `@` prefix to support a string syntax:
+ * "defaults": {
+ *   "foo": "@remove",
+ *   "name": "@override Hello, {name}!"
+ * }
+ */
+export type ToolDefinition = {
   /**
-   * The action to take when GPT calls the tool.
+   * The action to take when the LLM calls the tool.
    */
   type?: Type | null | undefined;
   /**
    * A tool definition to be used by the OpenAI API.
    */
-  tool: SDKInternalTool;
+  tool: InternalTool;
   /**
    * The configuration for an HTTP API call.
    */
-  endpoint?: HttpEndpoint | null | undefined;
+  endpoint?: ToolHttpEndpoint | null | undefined;
   /**
    * The default values for the parameters of the function/tool call.
    */
@@ -218,14 +310,14 @@ export function resultFromJSON(
 }
 
 /** @internal */
-export const SDKToolDefinition$inboundSchema: z.ZodType<
-  SDKToolDefinition,
+export const ToolDefinition$inboundSchema: z.ZodType<
+  ToolDefinition,
   z.ZodTypeDef,
   unknown
 > = z.object({
   type: z.nullable(Type$inboundSchema).optional(),
-  tool: SDKInternalTool$inboundSchema,
-  endpoint: z.nullable(HttpEndpoint$inboundSchema).optional(),
+  tool: InternalTool$inboundSchema,
+  endpoint: z.nullable(ToolHttpEndpoint$inboundSchema).optional(),
   defaults: z.nullable(
     z.union([
       z.lazy(() => One$inboundSchema),
@@ -236,10 +328,10 @@ export const SDKToolDefinition$inboundSchema: z.ZodType<
 });
 
 /** @internal */
-export type SDKToolDefinition$Outbound = {
+export type ToolDefinition$Outbound = {
   type?: string | null | undefined;
-  tool: SDKInternalTool$Outbound;
-  endpoint?: HttpEndpoint$Outbound | null | undefined;
+  tool: InternalTool$Outbound;
+  endpoint?: ToolHttpEndpoint$Outbound | null | undefined;
   defaults?:
     | One$Outbound
     | { [k: string]: ToolParameterDefault$Outbound }
@@ -249,14 +341,14 @@ export type SDKToolDefinition$Outbound = {
 };
 
 /** @internal */
-export const SDKToolDefinition$outboundSchema: z.ZodType<
-  SDKToolDefinition$Outbound,
+export const ToolDefinition$outboundSchema: z.ZodType<
+  ToolDefinition$Outbound,
   z.ZodTypeDef,
-  SDKToolDefinition
+  ToolDefinition
 > = z.object({
   type: z.nullable(Type$outboundSchema).optional(),
-  tool: SDKInternalTool$outboundSchema,
-  endpoint: z.nullable(HttpEndpoint$outboundSchema).optional(),
+  tool: InternalTool$outboundSchema,
+  endpoint: z.nullable(ToolHttpEndpoint$outboundSchema).optional(),
   defaults: z.nullable(
     z.union([
       z.lazy(() => One$outboundSchema),
@@ -270,29 +362,25 @@ export const SDKToolDefinition$outboundSchema: z.ZodType<
  * @internal
  * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
  */
-export namespace SDKToolDefinition$ {
-  /** @deprecated use `SDKToolDefinition$inboundSchema` instead. */
-  export const inboundSchema = SDKToolDefinition$inboundSchema;
-  /** @deprecated use `SDKToolDefinition$outboundSchema` instead. */
-  export const outboundSchema = SDKToolDefinition$outboundSchema;
-  /** @deprecated use `SDKToolDefinition$Outbound` instead. */
-  export type Outbound = SDKToolDefinition$Outbound;
+export namespace ToolDefinition$ {
+  /** @deprecated use `ToolDefinition$inboundSchema` instead. */
+  export const inboundSchema = ToolDefinition$inboundSchema;
+  /** @deprecated use `ToolDefinition$outboundSchema` instead. */
+  export const outboundSchema = ToolDefinition$outboundSchema;
+  /** @deprecated use `ToolDefinition$Outbound` instead. */
+  export type Outbound = ToolDefinition$Outbound;
 }
 
-export function sdkToolDefinitionToJSON(
-  sdkToolDefinition: SDKToolDefinition,
-): string {
-  return JSON.stringify(
-    SDKToolDefinition$outboundSchema.parse(sdkToolDefinition),
-  );
+export function toolDefinitionToJSON(toolDefinition: ToolDefinition): string {
+  return JSON.stringify(ToolDefinition$outboundSchema.parse(toolDefinition));
 }
 
-export function sdkToolDefinitionFromJSON(
+export function toolDefinitionFromJSON(
   jsonString: string,
-): SafeParseResult<SDKToolDefinition, SDKValidationError> {
+): SafeParseResult<ToolDefinition, SDKValidationError> {
   return safeParse(
     jsonString,
-    (x) => SDKToolDefinition$inboundSchema.parse(JSON.parse(x)),
-    `Failed to parse 'SDKToolDefinition' from JSON`,
+    (x) => ToolDefinition$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ToolDefinition' from JSON`,
   );
 }

package/src/models/components/{function.ts → toolfunction.ts}

@@ -13,14 +13,14 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 export type ParametersT = {};
 
 /**
- * A tool definition to be used by the OpenAI API.
+ * A function available to an agent.
  *
  * @remarks
  *
  * See:
  * - https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/function-calling
  */
-export type FunctionT = {
+export type ToolFunction = {
   /**
    * The name of the function/tool call.
    */
@@ -80,8 +80,8 @@ export function parametersFromJSON(
 }
 
 /** @internal */
-export const FunctionT$inboundSchema: z.ZodType<
-  FunctionT,
+export const ToolFunction$inboundSchema: z.ZodType<
+  ToolFunction,
   z.ZodTypeDef,
   unknown
 > = z.object({
@@ -91,17 +91,17 @@ export const FunctionT$inboundSchema: z.ZodType<
 });
 
 /** @internal */
-export type FunctionT$Outbound = {
+export type ToolFunction$Outbound = {
   name: string;
   description: string;
   parameters: ParametersT$Outbound;
 };
 
 /** @internal */
-export const FunctionT$outboundSchema: z.ZodType<
-  FunctionT$Outbound,
+export const ToolFunction$outboundSchema: z.ZodType<
+  ToolFunction$Outbound,
   z.ZodTypeDef,
-  FunctionT
+  ToolFunction
 > = z.object({
   name: z.string(),
   description: z.string(),
@@ -112,25 +112,25 @@ export const FunctionT$outboundSchema: z.ZodType<
  * @internal
  * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
  */
-export namespace FunctionT$ {
-  /** @deprecated use `FunctionT$inboundSchema` instead. */
-  export const inboundSchema = FunctionT$inboundSchema;
-  /** @deprecated use `FunctionT$outboundSchema` instead. */
-  export const outboundSchema = FunctionT$outboundSchema;
-  /** @deprecated use `FunctionT$Outbound` instead. */
-  export type Outbound = FunctionT$Outbound;
+export namespace ToolFunction$ {
+  /** @deprecated use `ToolFunction$inboundSchema` instead. */
+  export const inboundSchema = ToolFunction$inboundSchema;
+  /** @deprecated use `ToolFunction$outboundSchema` instead. */
+  export const outboundSchema = ToolFunction$outboundSchema;
+  /** @deprecated use `ToolFunction$Outbound` instead. */
+  export type Outbound = ToolFunction$Outbound;
 }
 
-export function functionToJSON(functionT: FunctionT): string {
-  return JSON.stringify(FunctionT$outboundSchema.parse(functionT));
+export function toolFunctionToJSON(toolFunction: ToolFunction): string {
+  return JSON.stringify(ToolFunction$outboundSchema.parse(toolFunction));
 }
 
-export function functionFromJSON(
+export function toolFunctionFromJSON(
   jsonString: string,
-): SafeParseResult<FunctionT, SDKValidationError> {
+): SafeParseResult<ToolFunction, SDKValidationError> {
   return safeParse(
     jsonString,
-    (x) => FunctionT$inboundSchema.parse(JSON.parse(x)),
-    `Failed to parse 'FunctionT' from JSON`,
+    (x) => ToolFunction$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ToolFunction' from JSON`,
   );
 }

package/src/models/components/toolhttpendpoint.ts

@@ -0,0 +1,111 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { remap as remap$ } from "../../lib/primitives.js";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+import {
+  ToolArgumentLocation,
+  ToolArgumentLocation$inboundSchema,
+  ToolArgumentLocation$outboundSchema,
+} from "./toolargumentlocation.js";
+import {
+  ToolHttpMethod,
+  ToolHttpMethod$inboundSchema,
+  ToolHttpMethod$outboundSchema,
+} from "./toolhttpmethod.js";
+
+/**
+ * The configuration for an HTTP API call by a tool.
+ */
+export type ToolHttpEndpoint = {
+  /**
+   * The endpoint URL of the external service to call.
+   */
+  url: string;
+  /**
+   * The HTTP method to use for a tool HTTP request.
+   */
+  method: ToolHttpMethod;
+  /**
+   * The location of the argument in a tool HTTP request.
+   *
+   * @remarks
+   * 'body' is used for JSON data in the POST request body.
+   * 'form' is used for form data in the POST request body.
+   * 'path' is used for URL path parameters.
+   * 'query' is used for query parameters in the URL.
+   */
+  argumentLocation: ToolArgumentLocation;
+};
+
+/** @internal */
+export const ToolHttpEndpoint$inboundSchema: z.ZodType<
+  ToolHttpEndpoint,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  url: z.string(),
+  method: ToolHttpMethod$inboundSchema,
+  argument_location: ToolArgumentLocation$inboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    "argument_location": "argumentLocation",
+  });
+});
+
+/** @internal */
+export type ToolHttpEndpoint$Outbound = {
+  url: string;
+  method: string;
+  argument_location: string;
+};
+
+/** @internal */
+export const ToolHttpEndpoint$outboundSchema: z.ZodType<
+  ToolHttpEndpoint$Outbound,
+  z.ZodTypeDef,
+  ToolHttpEndpoint
+> = z.object({
+  url: z.string(),
+  method: ToolHttpMethod$outboundSchema,
+  argumentLocation: ToolArgumentLocation$outboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    argumentLocation: "argument_location",
+  });
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace ToolHttpEndpoint$ {
+  /** @deprecated use `ToolHttpEndpoint$inboundSchema` instead. */
+  export const inboundSchema = ToolHttpEndpoint$inboundSchema;
+  /** @deprecated use `ToolHttpEndpoint$outboundSchema` instead. */
+  export const outboundSchema = ToolHttpEndpoint$outboundSchema;
+  /** @deprecated use `ToolHttpEndpoint$Outbound` instead. */
+  export type Outbound = ToolHttpEndpoint$Outbound;
+}
+
+export function toolHttpEndpointToJSON(
+  toolHttpEndpoint: ToolHttpEndpoint,
+): string {
+  return JSON.stringify(
+    ToolHttpEndpoint$outboundSchema.parse(toolHttpEndpoint),
+  );
+}
+
+export function toolHttpEndpointFromJSON(
+  jsonString: string,
+): SafeParseResult<ToolHttpEndpoint, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ToolHttpEndpoint$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ToolHttpEndpoint' from JSON`,
+  );
+}

package/src/models/components/toolhttpmethod.ts

@@ -0,0 +1,39 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { ClosedEnum } from "../../types/enums.js";
+
+/**
+ * The HTTP method to use for a tool HTTP request.
+ */
+export const ToolHttpMethod = {
+  Get: "get",
+  Post: "post",
+} as const;
+/**
+ * The HTTP method to use for a tool HTTP request.
+ */
+export type ToolHttpMethod = ClosedEnum<typeof ToolHttpMethod>;
+
+/** @internal */
+export const ToolHttpMethod$inboundSchema: z.ZodNativeEnum<
+  typeof ToolHttpMethod
+> = z.nativeEnum(ToolHttpMethod);
+
+/** @internal */
+export const ToolHttpMethod$outboundSchema: z.ZodNativeEnum<
+  typeof ToolHttpMethod
+> = ToolHttpMethod$inboundSchema;
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace ToolHttpMethod$ {
+  /** @deprecated use `ToolHttpMethod$inboundSchema` instead. */
+  export const inboundSchema = ToolHttpMethod$inboundSchema;
+  /** @deprecated use `ToolHttpMethod$outboundSchema` instead. */
+  export const outboundSchema = ToolHttpMethod$outboundSchema;
+}

package/src/models/components/toolparameterdefault.ts

@@ -14,11 +14,11 @@ import {
 } from "./toolparametertransform.js";
 
 /**
- * The default value for a parameter of the tool call.
+ * The default value for a parameter of a tool call.
  */
 export type ToolParameterDefault = {
   /**
-   * A transform to be applied to the value of a parameter.
+   * A transform to be applied to the value of a tool parameter.
    *
    * @remarks
    *

package/src/models/components/toolparametertransform.ts

@@ -15,7 +15,7 @@ import {
 } from "./toolparametertransformcondition.js";
 
 /**
- * The action to perform on the value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
+ * The action to perform on the tool parameter value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
  */
 export const Action = {
   Default: "default",
@@ -23,12 +23,12 @@ export const Action = {
   Remove: "remove",
 } as const;
 /**
- * The action to perform on the value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
+ * The action to perform on the tool parameter value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
  */
 export type Action = ClosedEnum<typeof Action>;
 
 /**
- * A transform to be applied to the value of a parameter.
+ * A transform to be applied to the value of a tool parameter.
  *
  * @remarks
  *
@@ -38,7 +38,7 @@ export type Action = ClosedEnum<typeof Action>;
  */
 export type ToolParameterTransform = {
   /**
-   * The action to perform on the value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
+   * The action to perform on the tool parameter value: `default` means only set the value (using the `format` field) if the parameter doesn't exist or is empty, `override` means always set the value, and `remove` means remove the parameter value.
    */
   action?: Action | undefined;
   /**

package/src/models/components/toolparametertransformcondition.ts

@@ -8,7 +8,7 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * A condition to be met for a transform to be applied to the value of a parameter.
+ * A condition to be met for a transform to be applied to the value of a tool parameter.
  */
 export type ToolParameterTransformCondition = {
   /**