@effect/ai 0.26.0 → 0.27.0

package/dist/esm/Toolkit.js

@@ -0,0 +1,269 @@
+/**
+ * The `Toolkit` module allows for creating and implementing a collection of
+ * `Tool`s which can be used to enhance the capabilities of a large language
+ * model beyond simple text generation.
+ *
+ * @example
+ * ```ts
+ * import { Toolkit, Tool } from "@effect/ai"
+ * import { Effect, Schema } from "effect"
+ *
+ * // Create individual tools
+ * const GetCurrentTime = Tool.make("GetCurrentTime", {
+ *   description: "Get the current timestamp",
+ *   success: Schema.Number
+ * })
+ *
+ * const GetWeather = Tool.make("GetWeather", {
+ *   description: "Get weather for a location",
+ *   parameters: { location: Schema.String },
+ *   success: Schema.Struct({
+ *     temperature: Schema.Number,
+ *     condition: Schema.String
+ *   })
+ * })
+ *
+ * // Create a toolkit with multiple tools
+ * const MyToolkit = Toolkit.make(GetCurrentTime, GetWeather)
+ *
+ * const MyToolkitLayer = MyToolkit.toLayer({
+ *   GetCurrentTime: () => Effect.succeed(Date.now()),
+ *   GetWeather: ({ location }) => Effect.succeed({
+ *     temperature: 72,
+ *     condition: "sunny"
+ *   })
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { CommitPrototype } from "effect/Effectable";
+import { identity } from "effect/Function";
+import { BaseProto as InspectableProto } from "effect/Inspectable";
+import * as Layer from "effect/Layer";
+import { pipeArguments } from "effect/Pipeable";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as AiError from "./AiError.js";
+import * as Tool from "./Tool.js";
+/**
+ * Unique identifier for toolkit instances.
+ *
+ * @since 1.0.0
+ * @category Type Ids
+ */
+export const TypeId = "~@effect/ai/Toolkit";
+const Proto = {
+  ...CommitPrototype,
+  ...InspectableProto,
+  of: identity,
+  toContext(build) {
+    return Effect.gen(this, function* () {
+      const context = yield* Effect.context();
+      const handlers = Effect.isEffect(build) ? yield* build : build;
+      const contextMap = new Map();
+      for (const [name, handler] of Object.entries(handlers)) {
+        const tool = this.tools[name];
+        contextMap.set(tool.id, {
+          handler,
+          context
+        });
+      }
+      return Context.unsafeMake(contextMap);
+    });
+  },
+  toLayer(build) {
+    return Layer.scopedContext(this.toContext(build));
+  },
+  commit() {
+    return Effect.gen(this, function* () {
+      const tools = this.tools;
+      const context = yield* Effect.context();
+      const schemasCache = new WeakMap();
+      const getSchemas = tool => {
+        let schemas = schemasCache.get(tool);
+        if (Predicate.isUndefined(schemas)) {
+          const handler = context.unsafeMap.get(tool.id);
+          const encodeSuccess = Schema.encodeUnknown(tool.successSchema);
+          const encodeFailure = Schema.encodeUnknown(tool.failureSchema);
+          const decodeFailure = Schema.decodeUnknown(tool.failureSchema);
+          const decodeParameters = Schema.decodeUnknown(tool.parametersSchema);
+          schemas = {
+            context: handler.context,
+            handler: handler.handler,
+            encodeSuccess,
+            encodeFailure,
+            decodeFailure,
+            decodeParameters
+          };
+          schemasCache.set(tool, schemas);
+        }
+        return schemas;
+      };
+      const handle = Effect.fn("Toolkit.handle", {
+        captureStackTrace: false
+      })(function* (name, params) {
+        yield* Effect.annotateCurrentSpan({
+          tool: name,
+          parameters: params
+        });
+        const tool = tools[name];
+        if (Predicate.isUndefined(tool)) {
+          const toolNames = Object.keys(tools).join(",");
+          return yield* new AiError.MalformedOutput({
+            module: "Toolkit",
+            method: `${name}.handle`,
+            description: `Failed to find tool with name '${name}' in toolkit - available tools: ${toolNames}`
+          });
+        }
+        const schemas = getSchemas(tool);
+        const decodedParams = yield* Effect.mapError(schemas.decodeParameters(params), cause => new AiError.MalformedOutput({
+          module: "Toolkit",
+          method: `${name}.handle`,
+          description: `Failed to decode tool call parameters for tool '${name}' from:\n'${JSON.stringify(params, undefined, 2)}'`,
+          cause
+        }));
+        const result = yield* schemas.handler(decodedParams).pipe(Effect.mapInputContext(input => Context.merge(schemas.context, input)), Effect.catchAll(error => schemas.decodeFailure(error).pipe(Effect.mapError(cause => new AiError.MalformedInput({
+          module: "Toolkit",
+          method: `${name}.handle`,
+          description: `Failed to decode tool call failure for tool '${name}'`,
+          cause
+        })), Effect.flatMap(Effect.fail))));
+        const encodedResult = yield* Effect.mapError(schemas.encodeSuccess(result), cause => new AiError.MalformedInput({
+          module: "Toolkit",
+          method: `${name}.handle`,
+          description: `Failed to encode tool call result for tool '${name}'`,
+          cause
+        }));
+        return {
+          result,
+          encodedResult
+        };
+      });
+      return {
+        tools,
+        handle
+      };
+    });
+  },
+  toJSON() {
+    return {
+      _id: "@effect/ai/Toolkit",
+      tools: Array.from(Object.values(this.tools)).map(tool => tool.name)
+    };
+  },
+  pipe() {
+    return pipeArguments(this, arguments);
+  }
+};
+const makeProto = tools => Object.assign(function () {}, Proto, {
+  tools
+});
+const resolveInput = (...tools) => {
+  const output = {};
+  for (const tool of tools) {
+    const value = Schema.isSchema(tool) ? Tool.fromTaggedRequest(tool) : tool;
+    output[tool.name] = value;
+  }
+  return output;
+};
+/**
+ * An empty toolkit with no tools.
+ *
+ * Useful as a starting point for building toolkits or as a default value. Can
+ * be extended using the merge function to add tools.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const empty = /*#__PURE__*/makeProto({});
+/**
+ * Creates a new toolkit from the specified tools.
+ *
+ * This is the primary constructor for creating toolkits. It accepts multiple tools
+ * and organizes them into a toolkit that can be provided to AI language models.
+ * Tools can be either Tool instances or TaggedRequest schemas.
+ *
+ * @example
+ * ```ts
+ * import { Toolkit, Tool } from "@effect/ai"
+ * import { Schema } from "effect"
+ *
+ * const GetCurrentTime = Tool.make("GetCurrentTime", {
+ *   description: "Get the current timestamp",
+ *   success: Schema.Number
+ * })
+ *
+ * const GetWeather = Tool.make("get_weather", {
+ *   description: "Get weather information",
+ *   parameters: { location: Schema.String },
+ *   success: Schema.Struct({
+ *     temperature: Schema.Number,
+ *     condition: Schema.String
+ *   })
+ * })
+ *
+ * const toolkit = Toolkit.make(GetCurrentTime, GetWeather)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = (...tools) => makeProto(resolveInput(...tools));
+/**
+ * Merges multiple toolkits into a single toolkit.
+ *
+ * Combines all tools from the provided toolkits into one unified toolkit.
+ * If there are naming conflicts, tools from later toolkits will override
+ * tools from earlier ones.
+ *
+ * @example
+ * ```ts
+ * import { Toolkit, Tool } from "@effect/ai"
+ *
+ * const mathToolkit = Toolkit.make(
+ *   Tool.make("add"),
+ *   Tool.make("subtract")
+ * )
+ *
+ * const utilityToolkit = Toolkit.make(
+ *   Tool.make("get_time"),
+ *   Tool.make("get_weather")
+ * )
+ *
+ * const combined = Toolkit.merge(mathToolkit, utilityToolkit)
+ * // combined now has: add, subtract, get_time, get_weather
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Toolkit, Tool } from "@effect/ai"
+ *
+ * // Incremental toolkit building
+ * const baseToolkit = Toolkit.make(Tool.make("base_tool"))
+ * const extendedToolkit = Toolkit.merge(
+ *   baseToolkit,
+ *   Toolkit.make(Tool.make("additional_tool")),
+ *   Toolkit.make(Tool.make("another_tool"))
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const merge = (
+/**
+ * The toolkits to merge together.
+ */
+...toolkits) => {
+  const tools = {};
+  for (const toolkit of toolkits) {
+    for (const [name, tool] of Object.entries(toolkit.tools)) {
+      tools[name] = tool;
+    }
+  }
+  return makeProto(tools);
+};
+//# sourceMappingURL=Toolkit.js.map

package/dist/esm/Toolkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toolkit.js","names":["Context","Effect","CommitPrototype","identity","BaseProto","InspectableProto","Layer","pipeArguments","Predicate","Schema","AiError","Tool","TypeId","Proto","of","toContext","build","gen","context","handlers","isEffect","contextMap","Map","name","handler","Object","entries","tool","tools","set","id","unsafeMake","toLayer","scopedContext","commit","schemasCache","WeakMap","getSchemas","schemas","get","isUndefined","unsafeMap","encodeSuccess","encodeUnknown","successSchema","encodeFailure","failureSchema","decodeFailure","decodeUnknown","decodeParameters","parametersSchema","handle","fn","captureStackTrace","params","annotateCurrentSpan","parameters","toolNames","keys","join","MalformedOutput","module","method","description","decodedParams","mapError","cause","JSON","stringify","undefined","result","pipe","mapInputContext","input","merge","catchAll","error","MalformedInput","flatMap","fail","encodedResult","toJSON","_id","Array","from","values","map","arguments","makeProto","assign","resolveInput","output","value","isSchema","fromTaggedRequest","empty","make","toolkits","toolkit"],"sources":["../../src/Toolkit.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}