effect-assistant 0.1.0 → 0.3.0

package/src/Skill.ts

@@ -7,6 +7,7 @@
  *
  * @since 0.1.0
  */
+import type * as Tool from "effect/ai/Tool"
 import type * as Instructions from "./Instructions.ts"
 
 /**
@@ -23,6 +24,11 @@ export interface Skill<R = never> {
   readonly description: string
   /** Text, or an Effect resolved each time the skill is loaded. */
   readonly instructions: Instructions.Instructions<R>
+  /**
+   * The tools its instructions use. A loop offers the skill only when its toolkit has every one of
+   * them, matched by name. Unset, a loop always offers it.
+   */
+  readonly tools?: ReadonlyArray<Tool.Any> | undefined
 }
 
 /**
@@ -34,6 +40,11 @@ export interface Skill<R = never> {
  * the skill. The instructions are text, or an Effect that is resolved each time the skill is
  * loaded.
  *
+ * `tools` lists the tools the instructions use. A loop whose toolkit lacks any of them, matched by
+ * name, leaves the skill out of its catalog and of `load_skill`, so a loop that gets its tools per
+ * user (by role, say) never offers a playbook it can't follow. A tool that only `ToolDiscovery`
+ * finds isn't in the toolkit, so it doesn't count. Without `tools`, every loop offers the skill.
+ *
  * **Example** (Defining a playbook for ordering campaigns)
  *
  * ```ts
@@ -51,6 +62,26 @@ export interface Skill<R = never> {
  * )
  * ```
  *
+ * **Example** (Offering a skill only with the tools it uses)
+ *
+ * ```ts
+ * import { Skill } from "effect-assistant"
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Schema from "effect/Schema"
+ *
+ * const StartCampaign = Tool.make("start_campaign", {
+ *   parameters: Schema.Struct({ campaignId: Schema.String, budget: Schema.Finite }),
+ *   success: Schema.String
+ * })
+ *
+ * // Left out of a loop whose toolkit has no start_campaign, like a viewer's.
+ * const orderingCampaigns = Skill.make("Ordering a campaign", {
+ *   description: "Use when the user wants to order or start a campaign.",
+ *   instructions: "When you know who it should reach and the budget, call start_campaign.",
+ *   tools: [StartCampaign]
+ * })
+ * ```
+ *
  * @category constructors
  * @since 0.1.0
  */
@@ -61,8 +92,10 @@ export const make = <R = never>(
     readonly description: string
     /** Text, or an Effect resolved each time the skill is loaded. */
     readonly instructions: Instructions.Instructions<R>
+    /** The tools its instructions use: a loop whose toolkit lacks one leaves the skill out. */
+    readonly tools?: ReadonlyArray<Tool.Any> | undefined
   }
-): Skill<R> => ({ name, description: options.description, instructions: options.instructions })
+): Skill<R> => ({ name, description: options.description, instructions: options.instructions, tools: options.tools })
 
 /**
  * Extracts the services that skills need when they're loaded.

package/src/Specialist.ts

@@ -127,7 +127,10 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
   readonly instructions: string | Instructions.Resolved
   /** The loop's tools, as a native toolkit whose handlers come from the layer. */
   readonly toolkit?: Toolkit.Toolkit<T> | undefined
-  /** Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. */
+  /**
+   * Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. A
+   * skill made with `tools` is left out when the toolkit lacks one of them.
+   */
   readonly skills?: ReadonlyArray<Skill<RS>> | undefined
   /** The model calls allowed per brief. Defaults to 8. */
   readonly maxSteps?: number | undefined