effect-assistant 0.0.0-stage → 0.1.0

package/dist/Memory.d.ts

@@ -0,0 +1,190 @@
+import { ChatId } from "./ChatId.js";
+import { CurrentChat } from "./CurrentChat.js";
+import { ToolFailure, ToolFailure_d_exports } from "./ToolFailure.js";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+import * as DateTime from "effect/DateTime";
+declare namespace Memory_d_exports {
+  export { Fact, MemoryStore, NewFact, Tools, layerMemory, layerTools, render };
+}
+declare const Fact_base: Schema.Class<Fact, Schema.Struct<{
+  readonly id: Schema.String;
+  readonly text: Schema.String;
+  readonly expiresAt: Schema.optional<Schema.DateTimeUtc>;
+}>, {}>;
+/**
+ * Represents a fact the assistant remembers.
+ *
+ * It holds the fact's id, one short sentence, and when the fact stops mattering, if it does.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare class Fact extends Fact_base {}
+/**
+ * Represents a fact to keep, as the `remember` tool hands it to the store.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface NewFact {
+  readonly text: string;
+  readonly expiresAt?: DateTime.Utc | undefined;
+  /** The id of a fact this one replaces. */
+  readonly replaces?: string | undefined;
+}
+declare const MemoryStore_base: Context.ServiceClass<MemoryStore, "effect-assistant/Memory/MemoryStore", {
+  /** Returns the unexpired facts a chat should know. */
+  readonly facts: (chatId: ChatId) => Effect.Effect<ReadonlyArray<Fact>>;
+  /** Keeps a fact for the chat's owner, and returns its id. */
+  readonly remember: (chatId: ChatId, fact: NewFact) => Effect.Effect<string>;
+  /**
+   * Drops a fact. Fails with a message for the model when the chat's owner has no fact with
+   * that id.
+   */
+  readonly forget: (chatId: ChatId, id: string) => Effect.Effect<void, ToolFailure>;
+  /** Returns the chat owner's facts that match a query, best first. */
+  readonly recall: (chatId: ChatId, query: string) => Effect.Effect<ReadonlyArray<Fact>>;
+}>;
+/**
+ * Service that keeps facts, implemented by the application.
+ *
+ * Every method receives the chat it's for, and the application decides whose facts that means
+ * (the chat's user, their team, ...).
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class MemoryStore extends MemoryStore_base {}
+/**
+ * Renders facts as the model reads them, for a turn's instructions.
+ *
+ * Each fact is listed with its id, so the model can replace or forget it. The result is an empty
+ * string when there are no facts.
+ *
+ * @see {@link Tools} for an example
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const render: (facts: ReadonlyArray<Fact>) => string;
+/**
+ * Layer that provides a {@link MemoryStore} in memory, for tests and local runs.
+ *
+ * Every chat shares one set of facts.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerMemory: Layer.Layer<MemoryStore>;
+/**
+ * Toolkit with the `remember`, `forget`, and `recall` tools.
+ *
+ * **Details**
+ *
+ * Merge it into the loop's toolkit, and provide {@link layerTools} and a {@link MemoryStore}. Show
+ * the facts in the turn's instructions with {@link render}.
+ *
+ * **Example** (Giving an assistant memory)
+ *
+ * ```ts
+ * import { Assistant, Memory } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ * import * as Layer from "effect/Layer"
+ * import * as Stream from "effect/Stream"
+ *
+ * export const MyAssistant = Assistant.make("my-assistant")
+ *
+ * const MyAssistantLive = MyAssistant.toLayer(
+ *   Effect.gen(function* () {
+ *     const memory = yield* Memory.MemoryStore
+ *
+ *     return (turn) =>
+ *       Stream.unwrap(
+ *         Effect.map(memory.facts(turn.chatId), (facts) =>
+ *           turn.loop({
+ *             instructions: `You help a small team.\n\n${Memory.render(facts)}`,
+ *             toolkit: Memory.Tools
+ *           })
+ *         )
+ *       ).pipe(Stream.provideService(Memory.MemoryStore, memory))
+ *   })
+ * ).pipe(Layer.provide(Memory.layerTools), Layer.provide(Memory.layerMemory))
+ * ```
+ *
+ * @category tools
+ * @since 0.1.0
+ */
+export declare const Tools: Toolkit.Toolkit<{
+  readonly forget: Tool.Tool<"forget", {
+    readonly parameters: Schema.Struct<{
+      readonly id: Schema.String;
+    }>;
+    readonly success: Schema.String;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+  readonly recall: Tool.Tool<"recall", {
+    readonly parameters: Schema.Struct<{
+      readonly query: Schema.String;
+    }>;
+    readonly success: Schema.$Array<Schema.String>;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+  readonly remember: Tool.Tool<"remember", {
+    readonly parameters: Schema.Struct<{
+      readonly text: Schema.String;
+      readonly until: Schema.optional<Schema.String>;
+      readonly replaces: Schema.optional<Schema.String>;
+    }>;
+    readonly success: Schema.String;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+}>;
+/**
+ * Layer that provides the handlers of {@link Tools}.
+ *
+ * The handlers call the {@link MemoryStore} with the chat they run in.
+ *
+ * @see {@link Tools} for an example
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerTools: Layer.Layer<Tool.HandlersFor<{
+  readonly forget: Tool.Tool<"forget", {
+    readonly parameters: Schema.Struct<{
+      readonly id: Schema.String;
+    }>;
+    readonly success: Schema.String;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+  readonly recall: Tool.Tool<"recall", {
+    readonly parameters: Schema.Struct<{
+      readonly query: Schema.String;
+    }>;
+    readonly success: Schema.$Array<Schema.String>;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+  readonly remember: Tool.Tool<"remember", {
+    readonly parameters: Schema.Struct<{
+      readonly text: Schema.String;
+      readonly until: Schema.optional<Schema.String>;
+      readonly replaces: Schema.optional<Schema.String>;
+    }>;
+    readonly success: Schema.String;
+    readonly failure: typeof ToolFailure;
+    readonly failureMode: "error";
+  }, CurrentChat | MemoryStore>;
+}>, never, never>;
+//#endregion
+export { Memory_d_exports };
+//# sourceMappingURL=Memory.d.ts.map

package/dist/Memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Memory.d.ts","names":[],"sources":["../src/Memory.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;qBAiCa,aAAa;;;;;;;iBAYT;WACN;WACA,YAAY,SAAS;;WAErB;;;;WAgBS,QAAC,QAAQ,WAAW,OAAO,OAAO,cAAc;;WAE7C,WAAC,QAAQ,QAAQ,MAAM,YAAY,OAAO;;;;;WAK5C,SAAC,QAAQ,QAAQ,eAAe,OAAO,aAAa;;WAEpD,SAAC,QAAQ,QAAQ,kBAAkB,OAAO,OAAO,cAAc;;;;;;;;;;;qBAbvE,oBAAoB;;;;;;;;;;;;qBAiCpB,SAAM,OAAW,cAAc;;;;;;;;;qBA4B/B,aAAa,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA+GzB,OAAK,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAeL,YAAU,MAAA,MAAA,KAAA"}

package/dist/Memory.js

@@ -0,0 +1,216 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { make } from "./internal/uuid.js";
+import { CurrentChat } from "./CurrentChat.js";
+import { ToolFailure, fail } from "./ToolFailure.js";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+import * as Clock from "effect/Clock";
+import * as Ref from "effect/Ref";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+import * as DateTime from "effect/DateTime";
+//#region src/Memory.ts
+/**
+* Keeps facts an assistant remembers across chats.
+*
+* The model keeps facts with the `remember` tool, finds them with `recall`, and drops them with
+* `forget` ({@link Tools}). Where facts are stored and who shares them is up to the application,
+* which implements {@link MemoryStore}; every method receives the chat it's for. {@link render}
+* shows the facts in a turn's instructions.
+*
+* @since 0.1.0
+*/
+var Memory_exports = /* @__PURE__ */ __exportAll({
+	Fact: () => Fact,
+	MemoryStore: () => MemoryStore,
+	Tools: () => Tools,
+	layerMemory: () => layerMemory,
+	layerTools: () => layerTools,
+	render: () => render
+});
+/**
+* Represents a fact the assistant remembers.
+*
+* It holds the fact's id, one short sentence, and when the fact stops mattering, if it does.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var Fact = class extends Schema.Class("effect-assistant/Memory/Fact")({
+	id: Schema.String,
+	text: Schema.String,
+	expiresAt: Schema.optional(Schema.DateTimeUtc)
+}) {};
+/**
+* Service that keeps facts, implemented by the application.
+*
+* Every method receives the chat it's for, and the application decides whose facts that means
+* (the chat's user, their team, ...).
+*
+* @category services
+* @since 0.1.0
+*/
+var MemoryStore = class extends Context.Service()("effect-assistant/Memory/MemoryStore") {};
+const day = (at) => DateTime.formatIsoDateUtc(at);
+const line = (fact) => `- [${fact.id}] ${fact.text}${fact.expiresAt === void 0 ? "" : ` (until ${day(fact.expiresAt)})`}`;
+/**
+* Renders facts as the model reads them, for a turn's instructions.
+*
+* Each fact is listed with its id, so the model can replace or forget it. The result is an empty
+* string when there are no facts.
+*
+* @see {@link Tools} for an example
+*
+* @category utils
+* @since 0.1.0
+*/
+const render = (facts) => facts.length === 0 ? "" : `<memory>\nWhat you remember from earlier chats. Use it without saying where it came from; when their data or what they say now disagrees, that wins.\n${facts.map(line).join("\n")}\n</memory>`;
+const words = (text) => text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word.length > 2);
+const matches = (fact, query) => {
+	const own = words(fact.text);
+	return query.filter((word) => own.some((w) => w.startsWith(word) || word.startsWith(w))).length;
+};
+const live = (now) => (fact) => fact.expiresAt === void 0 || DateTime.toEpochMillis(fact.expiresAt) > now;
+/**
+* Layer that provides a {@link MemoryStore} in memory, for tests and local runs.
+*
+* Every chat shares one set of facts.
+*
+* @category layers
+* @since 0.1.0
+*/
+const layerMemory = Layer.effect(MemoryStore, Effect.gen(function* () {
+	const all = yield* Ref.make([]);
+	const current = Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		return (yield* Ref.get(all)).filter(live(now));
+	});
+	return MemoryStore.of({
+		facts: () => current,
+		remember: Effect.fnUntraced(function* (_chatId, fact) {
+			const id = (yield* current).find((kept) => kept.text === fact.text.trim())?.id ?? `f-${(yield* make).slice(0, 8)}`;
+			const kept = new Fact({
+				id,
+				text: fact.text.trim(),
+				expiresAt: fact.expiresAt
+			});
+			yield* Ref.update(all, (facts) => [kept, ...facts.filter((old) => old.id !== id && old.id !== fact.replaces)]);
+			return id;
+		}),
+		forget: Effect.fnUntraced(function* (_chatId, id) {
+			if (!(yield* current).some((fact) => fact.id === id)) return yield* fail(`Nothing remembered as ${id}.`);
+			yield* Ref.update(all, (facts) => facts.filter((fact) => fact.id !== id));
+		}),
+		recall: Effect.fnUntraced(function* (_chatId, query) {
+			const wanted = words(query);
+			return (yield* current).map((fact) => ({
+				fact,
+				score: matches(fact, wanted)
+			})).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, 10).map(({ fact }) => fact);
+		})
+	});
+}));
+const Remember = Tool.make("remember", {
+	description: `Remember something for later chats. Only what you can't look up again and that will still matter: a preference, a standing decision, how they like to work ("Rotterdam's copy is always Dutch"). For something short-lived ("out of office until Friday"), pass until. Not records your tools can read (orders, locations, budgets, people), not the state of a task in progress, and nothing you'd only need in this chat. One fact per call, in one short sentence that stands on its own. When it changes one you already have, pass that one's id as replaces.`,
+	parameters: Schema.Struct({
+		text: Schema.String,
+		until: Schema.optional(Schema.String).annotate({ description: "For something short-lived: the last day it matters, as YYYY-MM-DD." }),
+		replaces: Schema.optional(Schema.String).annotate({ description: "The id of a fact this one replaces." })
+	}),
+	success: Schema.String,
+	failure: ToolFailure,
+	dependencies: [CurrentChat, MemoryStore]
+});
+const Forget = Tool.make("forget", {
+	description: "Forget a fact you remember, by its id, when they ask or it's no longer true.",
+	parameters: Schema.Struct({ id: Schema.String }),
+	success: Schema.String,
+	failure: ToolFailure,
+	dependencies: [CurrentChat, MemoryStore]
+});
+const Recall = Tool.make("recall", {
+	description: "Search what you remember, by words that would be in it.",
+	parameters: Schema.Struct({ query: Schema.String }),
+	success: Schema.Array(Schema.String),
+	failure: ToolFailure,
+	dependencies: [CurrentChat, MemoryStore]
+});
+/**
+* Toolkit with the `remember`, `forget`, and `recall` tools.
+*
+* **Details**
+*
+* Merge it into the loop's toolkit, and provide {@link layerTools} and a {@link MemoryStore}. Show
+* the facts in the turn's instructions with {@link render}.
+*
+* **Example** (Giving an assistant memory)
+*
+* ```ts
+* import { Assistant, Memory } from "effect-assistant"
+* import * as Effect from "effect/Effect"
+* import * as Layer from "effect/Layer"
+* import * as Stream from "effect/Stream"
+*
+* export const MyAssistant = Assistant.make("my-assistant")
+*
+* const MyAssistantLive = MyAssistant.toLayer(
+*   Effect.gen(function* () {
+*     const memory = yield* Memory.MemoryStore
+*
+*     return (turn) =>
+*       Stream.unwrap(
+*         Effect.map(memory.facts(turn.chatId), (facts) =>
+*           turn.loop({
+*             instructions: `You help a small team.\n\n${Memory.render(facts)}`,
+*             toolkit: Memory.Tools
+*           })
+*         )
+*       ).pipe(Stream.provideService(Memory.MemoryStore, memory))
+*   })
+* ).pipe(Layer.provide(Memory.layerTools), Layer.provide(Memory.layerMemory))
+* ```
+*
+* @category tools
+* @since 0.1.0
+*/
+const Tools = Toolkit.make(Remember, Forget, Recall);
+const endOf = (date) => /^\d{4}-\d{2}-\d{2}$/.test(date) ? DateTime.make(`${date}T23:59:59Z`) : Option.none();
+/**
+* Layer that provides the handlers of {@link Tools}.
+*
+* The handlers call the {@link MemoryStore} with the chat they run in.
+*
+* @see {@link Tools} for an example
+*
+* @category layers
+* @since 0.1.0
+*/
+const layerTools = Tools.toLayer({
+	remember: Effect.fnUntraced(function* ({ text, until, replaces }) {
+		const chat = yield* CurrentChat;
+		const store = yield* MemoryStore;
+		const expiresAt = until === void 0 ? Option.none() : endOf(until);
+		if (until !== void 0 && Option.isNone(expiresAt)) return yield* fail(`until must be a date as YYYY-MM-DD, not ${until}.`);
+		return `Remembered as ${yield* store.remember(chat.chatId, {
+			text,
+			expiresAt: Option.getOrUndefined(expiresAt),
+			replaces
+		})}.`;
+	}),
+	forget: Effect.fnUntraced(function* ({ id }) {
+		const chat = yield* CurrentChat;
+		yield* (yield* MemoryStore).forget(chat.chatId, id);
+		return `Forgot ${id}.`;
+	}),
+	recall: Effect.fnUntraced(function* ({ query }) {
+		const chat = yield* CurrentChat;
+		return (yield* (yield* MemoryStore).recall(chat.chatId, query)).map(line);
+	})
+});
+//#endregion
+export { Fact, MemoryStore, Memory_exports, Tools, layerMemory, layerTools, render };
+
+//# sourceMappingURL=Memory.js.map

package/dist/Memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Memory.js","names":["Uuid.make","ToolFailure.fail","ToolFailure.ToolFailure"],"sources":["../src/Memory.ts"],"sourcesContent":["/**\n * Keeps facts an assistant remembers across chats.\n *\n * The model keeps facts with the `remember` tool, finds them with `recall`, and drops them with\n * `forget` ({@link Tools}). Where facts are stored and who shares them is up to the application,\n * which implements {@link MemoryStore}; every method receives the chat it's for. {@link render}\n * shows the facts in a turn's instructions.\n *\n * @since 0.1.0\n */\nimport * as Tool from \"effect/ai/Tool\"\nimport * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Clock from \"effect/Clock\"\nimport * as Context from \"effect/Context\"\nimport * as DateTime from \"effect/DateTime\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Option from \"effect/Option\"\nimport * as Ref from \"effect/Ref\"\nimport * as Schema from \"effect/Schema\"\nimport type { ChatId } from \"./ChatId.ts\"\nimport { CurrentChat } from \"./CurrentChat.ts\"\nimport * as Uuid from \"./internal/uuid.ts\"\nimport * as ToolFailure from \"./ToolFailure.ts\"\n\n/**\n * Represents a fact the assistant remembers.\n *\n * It holds the fact's id, one short sentence, and when the fact stops mattering, if it does.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class Fact extends Schema.Class<Fact>(\"effect-assistant/Memory/Fact\")({\n  id: Schema.String,\n  text: Schema.String,\n  expiresAt: Schema.optional(Schema.DateTimeUtc)\n}) {}\n\n/**\n * Represents a fact to keep, as the `remember` tool hands it to the store.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface NewFact {\n  readonly text: string\n  readonly expiresAt?: DateTime.Utc | undefined\n  /** The id of a fact this one replaces. */\n  readonly replaces?: string | undefined\n}\n\n/**\n * Service that keeps facts, implemented by the application.\n *\n * Every method receives the chat it's for, and the application decides whose facts that means\n * (the chat's user, their team, ...).\n *\n * @category services\n * @since 0.1.0\n */\nexport class MemoryStore extends Context.Service<\n  MemoryStore,\n  {\n    /** Returns the unexpired facts a chat should know. */\n    readonly facts: (chatId: ChatId) => Effect.Effect<ReadonlyArray<Fact>>\n    /** Keeps a fact for the chat's owner, and returns its id. */\n    readonly remember: (chatId: ChatId, fact: NewFact) => Effect.Effect<string>\n    /**\n     * Drops a fact. Fails with a message for the model when the chat's owner has no fact with\n     * that id.\n     */\n    readonly forget: (chatId: ChatId, id: string) => Effect.Effect<void, ToolFailure.ToolFailure>\n    /** Returns the chat owner's facts that match a query, best first. */\n    readonly recall: (chatId: ChatId, query: string) => Effect.Effect<ReadonlyArray<Fact>>\n  }\n>()(\"effect-assistant/Memory/MemoryStore\") {}\n\nconst day = (at: DateTime.Utc): string => DateTime.formatIsoDateUtc(at)\n\nconst line = (fact: Fact): string =>\n  `- [${fact.id}] ${fact.text}${fact.expiresAt === undefined ? \"\" : ` (until ${day(fact.expiresAt)})`}`\n\n/**\n * Renders facts as the model reads them, for a turn's instructions.\n *\n * Each fact is listed with its id, so the model can replace or forget it. The result is an empty\n * string when there are no facts.\n *\n * @see {@link Tools} for an example\n *\n * @category utils\n * @since 0.1.0\n */\nexport const render = (facts: ReadonlyArray<Fact>): string =>\n  facts.length === 0\n    ? \"\"\n    : `<memory>\\nWhat you remember from earlier chats. Use it without saying where it came from; when their data or what they say now disagrees, that wins.\\n${facts.map(line).join(\"\\n\")}\\n</memory>`\n\nconst words = (text: string): ReadonlyArray<string> =>\n  text\n    .toLowerCase()\n    .split(/[^\\p{L}\\p{N}]+/u)\n    .filter((word) => word.length > 2)\n\nconst matches = (fact: Fact, query: ReadonlyArray<string>): number => {\n  const own = words(fact.text)\n\n  return query.filter((word) => own.some((w) => w.startsWith(word) || word.startsWith(w))).length\n}\n\nconst live = (now: number) => (fact: Fact) =>\n  fact.expiresAt === undefined || DateTime.toEpochMillis(fact.expiresAt) > now\n\n/**\n * Layer that provides a {@link MemoryStore} in memory, for tests and local runs.\n *\n * Every chat shares one set of facts.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerMemory: Layer.Layer<MemoryStore> = Layer.effect(\n  MemoryStore,\n  Effect.gen(function* () {\n    // Newest first.\n    const all = yield* Ref.make<ReadonlyArray<Fact>>([])\n\n    const current = Effect.gen(function* () {\n      const now = yield* Clock.currentTimeMillis\n\n      return (yield* Ref.get(all)).filter(live(now))\n    })\n\n    return MemoryStore.of({\n      facts: () => current,\n      remember: Effect.fnUntraced(function* (_chatId: ChatId, fact: NewFact) {\n        const same = (yield* current).find((kept) => kept.text === fact.text.trim())\n        const id = same?.id ?? `f-${(yield* Uuid.make).slice(0, 8)}`\n        const kept = new Fact({ id, text: fact.text.trim(), expiresAt: fact.expiresAt })\n\n        yield* Ref.update(all, (facts) => [kept, ...facts.filter((old) => old.id !== id && old.id !== fact.replaces)])\n\n        return id\n      }),\n      forget: Effect.fnUntraced(function* (_chatId: ChatId, id: string) {\n        if (!(yield* current).some((fact) => fact.id === id))\n          return yield* ToolFailure.fail(`Nothing remembered as ${id}.`)\n\n        yield* Ref.update(all, (facts) => facts.filter((fact) => fact.id !== id))\n      }),\n      recall: Effect.fnUntraced(function* (_chatId: ChatId, query: string) {\n        const wanted = words(query)\n\n        return (yield* current)\n          .map((fact) => ({ fact, score: matches(fact, wanted) }))\n          .filter(({ score }) => score > 0)\n          .sort((a, b) => b.score - a.score)\n          .slice(0, 10)\n          .map(({ fact }) => fact)\n      })\n    })\n  })\n)\n\nconst Remember = Tool.make(\"remember\", {\n  description: `Remember something for later chats. Only what you can't look up again and that will still matter: a preference, a standing decision, how they like to work (\"Rotterdam's copy is always Dutch\"). For something short-lived (\"out of office until Friday\"), pass until. Not records your tools can read (orders, locations, budgets, people), not the state of a task in progress, and nothing you'd only need in this chat. One fact per call, in one short sentence that stands on its own. When it changes one you already have, pass that one's id as replaces.`,\n  parameters: Schema.Struct({\n    text: Schema.String,\n    until: Schema.optional(Schema.String).annotate({\n      description: \"For something short-lived: the last day it matters, as YYYY-MM-DD.\"\n    }),\n    replaces: Schema.optional(Schema.String).annotate({ description: \"The id of a fact this one replaces.\" })\n  }),\n  success: Schema.String,\n  failure: ToolFailure.ToolFailure,\n  dependencies: [CurrentChat, MemoryStore]\n})\n\nconst Forget = Tool.make(\"forget\", {\n  description: \"Forget a fact you remember, by its id, when they ask or it's no longer true.\",\n  parameters: Schema.Struct({ id: Schema.String }),\n  success: Schema.String,\n  failure: ToolFailure.ToolFailure,\n  dependencies: [CurrentChat, MemoryStore]\n})\n\nconst Recall = Tool.make(\"recall\", {\n  description: \"Search what you remember, by words that would be in it.\",\n  parameters: Schema.Struct({ query: Schema.String }),\n  success: Schema.Array(Schema.String),\n  failure: ToolFailure.ToolFailure,\n  dependencies: [CurrentChat, MemoryStore]\n})\n\n/**\n * Toolkit with the `remember`, `forget`, and `recall` tools.\n *\n * **Details**\n *\n * Merge it into the loop's toolkit, and provide {@link layerTools} and a {@link MemoryStore}. Show\n * the facts in the turn's instructions with {@link render}.\n *\n * **Example** (Giving an assistant memory)\n *\n * ```ts\n * import { Assistant, Memory } from \"effect-assistant\"\n * import * as Effect from \"effect/Effect\"\n * import * as Layer from \"effect/Layer\"\n * import * as Stream from \"effect/Stream\"\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\")\n *\n * const MyAssistantLive = MyAssistant.toLayer(\n *   Effect.gen(function* () {\n *     const memory = yield* Memory.MemoryStore\n *\n *     return (turn) =>\n *       Stream.unwrap(\n *         Effect.map(memory.facts(turn.chatId), (facts) =>\n *           turn.loop({\n *             instructions: `You help a small team.\\n\\n${Memory.render(facts)}`,\n *             toolkit: Memory.Tools\n *           })\n *         )\n *       ).pipe(Stream.provideService(Memory.MemoryStore, memory))\n *   })\n * ).pipe(Layer.provide(Memory.layerTools), Layer.provide(Memory.layerMemory))\n * ```\n *\n * @category tools\n * @since 0.1.0\n */\nexport const Tools = Toolkit.make(Remember, Forget, Recall)\n\nconst endOf = (date: string): Option.Option<DateTime.Utc> =>\n  /^\\d{4}-\\d{2}-\\d{2}$/.test(date) ? DateTime.make(`${date}T23:59:59Z`) : Option.none()\n\n/**\n * Layer that provides the handlers of {@link Tools}.\n *\n * The handlers call the {@link MemoryStore} with the chat they run in.\n *\n * @see {@link Tools} for an example\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerTools = Tools.toLayer({\n  remember: Effect.fnUntraced(function* ({ text, until, replaces }) {\n    const chat = yield* CurrentChat\n    const store = yield* MemoryStore\n    const expiresAt = until === undefined ? Option.none() : endOf(until)\n\n    if (until !== undefined && Option.isNone(expiresAt)) {\n      return yield* ToolFailure.fail(`until must be a date as YYYY-MM-DD, not ${until}.`)\n    }\n\n    const id = yield* store.remember(chat.chatId, { text, expiresAt: Option.getOrUndefined(expiresAt), replaces })\n\n    return `Remembered as ${id}.`\n  }),\n  forget: Effect.fnUntraced(function* ({ id }) {\n    const chat = yield* CurrentChat\n\n    yield* (yield* MemoryStore).forget(chat.chatId, id)\n\n    return `Forgot ${id}.`\n  }),\n  recall: Effect.fnUntraced(function* ({ query }) {\n    const chat = yield* CurrentChat\n    const found = yield* (yield* MemoryStore).recall(chat.chatId, query)\n\n    return found.map(line)\n  })\n})\n"],"mappings":"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"}

package/dist/RunId.d.ts

@@ -0,0 +1,41 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+declare namespace RunId_d_exports {
+  export { RunId, fromKey, make };
+}
+/**
+ * Schema for run ids of the form `` `run:${uuid}` ``, branded.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const RunId: Schema.brand<Schema.TemplateLiteral<readonly ["run:", Schema.String]>, "~effect-assistant/RunId">;
+/**
+ * Represents a run id.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RunId = typeof RunId.Type;
+/**
+ * Creates a new random run id using Effect's `Random`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: () => Effect.Effect<RunId>;
+/**
+ * Creates the run id for a key. The same key always gives the same id.
+ *
+ * **When to use**
+ *
+ * Use it for a run that a tool call starts, with the call's `AssistantToolCall.idempotencyKey` as
+ * the key, so running the call again finds the same run.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fromKey: (key: string) => RunId;
+//#endregion
+export { RunId_d_exports };
+//# sourceMappingURL=RunId.d.ts.map

package/dist/RunId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunId.d.ts","names":[],"sources":["../src/RunId.ts"],"mappings":";;;;;;;;;;;qBAgBa,OAAK,OAAA,MAAA,OAAA,kCAAA,OAAA;;;;;;;YAQN,eAAe,MAAM;;;;;;;qBAQpB,YAAW,OAAO,OAAO;;;;;;;;;;;;qBAazB,UAAO,gBAAkB"}

package/dist/RunId.js

@@ -0,0 +1,46 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { Uuid, fromKey as fromKey$1, make as make$1 } from "./internal/uuid.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+//#region src/RunId.ts
+/**
+* This module provides the id of a background run, such as a specialist run or a workflow started
+* from a tool. A run id is `run:` followed by a UUID.
+*
+* @since 0.1.0
+*/
+var RunId_exports = /* @__PURE__ */ __exportAll({
+	RunId: () => RunId,
+	fromKey: () => fromKey,
+	make: () => make
+});
+/**
+* Schema for run ids of the form `` `run:${uuid}` ``, branded.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const RunId = Schema.TemplateLiteral(["run:", Uuid]).pipe(Schema.brand("~effect-assistant/RunId"));
+/**
+* Creates a new random run id using Effect's `Random`.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = () => Effect.map(make$1, (uuid) => RunId.make(`run:${uuid}`));
+/**
+* Creates the run id for a key. The same key always gives the same id.
+*
+* **When to use**
+*
+* Use it for a run that a tool call starts, with the call's `AssistantToolCall.idempotencyKey` as
+* the key, so running the call again finds the same run.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const fromKey = (key) => RunId.make(`run:${fromKey$1(key)}`);
+//#endregion
+export { RunId, RunId_exports, fromKey, make };
+
+//# sourceMappingURL=RunId.js.map

package/dist/RunId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunId.js","names":["Uuid.Uuid","Uuid.make","Uuid.fromKey"],"sources":["../src/RunId.ts"],"sourcesContent":["/**\n * This module provides the id of a background run, such as a specialist run or a workflow started\n * from a tool. A run id is `run:` followed by a UUID.\n *\n * @since 0.1.0\n */\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as Uuid from \"./internal/uuid.ts\"\n\n/**\n * Schema for run ids of the form `` `run:${uuid}` ``, branded.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const RunId = Schema.TemplateLiteral([\"run:\", Uuid.Uuid]).pipe(Schema.brand(\"~effect-assistant/RunId\"))\n\n/**\n * Represents a run id.\n *\n * @category models\n * @since 0.1.0\n */\nexport type RunId = typeof RunId.Type\n\n/**\n * Creates a new random run id using Effect's `Random`.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (): Effect.Effect<RunId> => Effect.map(Uuid.make, (uuid) => RunId.make(`run:${uuid}`))\n\n/**\n * Creates the run id for a key. The same key always gives the same id.\n *\n * **When to use**\n *\n * Use it for a run that a tool call starts, with the call's `AssistantToolCall.idempotencyKey` as\n * the key, so running the call again finds the same run.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const fromKey = (key: string): RunId => RunId.make(`run:${Uuid.fromKey(key)}`)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAgBA,MAAa,QAAQ,OAAO,gBAAgB,CAAC,QAAQA,IAAS,CAAC,CAAC,CAAC,KAAK,OAAO,MAAM,yBAAyB,CAAC;;;;;;;AAgB7G,MAAa,aAAmC,OAAO,IAAIC,SAAY,SAAS,MAAM,KAAK,OAAO,MAAM,CAAC;;;;;;;;;;;;AAazG,MAAa,WAAW,QAAuB,MAAM,KAAK,OAAOC,UAAa,GAAG,GAAG"}

package/dist/Skill.d.ts

@@ -0,0 +1,72 @@
+import { Instructions, Instructions_d_exports } from "./Instructions.js";
+declare namespace Skill_d_exports {
+  export { Services, Skill, make, withCatalog };
+}
+/**
+ * Represents a skill.
+ *
+ * `R` is the services its instructions need when they're loaded.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Skill<R = never> {
+  readonly name: string;
+  /** When to use it, in one line. This is all the model sees until it loads the skill. */
+  readonly description: string;
+  /** Text, or an Effect resolved each time the skill is loaded. */
+  readonly instructions: Instructions<R>;
+}
+/**
+ * Creates a skill from its name, a description of when to use it, and its instructions.
+ *
+ * **Details**
+ *
+ * Write the description as a trigger ("Use when…"), since it's all the model sees until it loads
+ * the skill. The instructions are text, or an Effect that is resolved each time the skill is
+ * loaded.
+ *
+ * **Example** (Defining a playbook for ordering campaigns)
+ *
+ * ```ts
+ * import { Skill } from "effect-assistant"
+ *
+ * const orderingCampaigns = Skill.make("Ordering a campaign", {
+ *   description: "Use when the user wants to order or start a campaign.",
+ *   instructions: `1. Pick the product with list_campaign_products.
+ * 2. You need who it should reach and a budget. Ask for what's missing, one question at a time.
+ * 3. When you have both, call start_campaign.`
+ * })
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   turn.loop({ instructions, skills: [orderingCampaigns] })
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <R = never>(name: string, options: {
+  /** When to use it, in one line. This is all the model sees until it loads the skill. */
+  readonly description: string;
+  /** Text, or an Effect resolved each time the skill is loaded. */
+  readonly instructions: Instructions<R>;
+}) => Skill<R>;
+/**
+ * Extracts the services that skills need when they're loaded.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Services<S> = S extends Skill<infer R> ? R : never;
+/**
+ * Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no
+ * skills.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const withCatalog: <R>(prompt: string, skills: ReadonlyArray<Skill<R>>) => string;
+//#endregion
+export { Skill_d_exports };
+//# sourceMappingURL=Skill.d.ts.map

package/dist/Skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Skill.d.ts","names":[],"sources":["../src/Skill.ts"],"mappings":";;;;;;;;;;;;iBAmBiB,MAAM;WACZ;;WAEA;;WAEA,cAAc,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgCtC,OAAQ,WAAS,cAChB;;WAGD;;WAEA,cAAc,aAA0B;MAElD,MAAM;;;;;;;YAQG,SAAS,KAAK,UAAU,YAAY,KAAK;;;;;;;;qBASxC,cAAe,GAAC,gBAAgB,QAAU,cAAc,MAAM"}

package/dist/Skill.js

@@ -0,0 +1,58 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+//#region src/Skill.ts
+var Skill_exports = /* @__PURE__ */ __exportAll({
+	make: () => make,
+	withCatalog: () => withCatalog
+});
+/**
+* Creates a skill from its name, a description of when to use it, and its instructions.
+*
+* **Details**
+*
+* Write the description as a trigger ("Use when…"), since it's all the model sees until it loads
+* the skill. The instructions are text, or an Effect that is resolved each time the skill is
+* loaded.
+*
+* **Example** (Defining a playbook for ordering campaigns)
+*
+* ```ts
+* import { Skill } from "effect-assistant"
+*
+* const orderingCampaigns = Skill.make("Ordering a campaign", {
+*   description: "Use when the user wants to order or start a campaign.",
+*   instructions: `1. Pick the product with list_campaign_products.
+* 2. You need who it should reach and a budget. Ask for what's missing, one question at a time.
+* 3. When you have both, call start_campaign.`
+* })
+*
+* const MyAssistantLive = MyAssistant.toLayer((turn) =>
+*   turn.loop({ instructions, skills: [orderingCampaigns] })
+* )
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (name, options) => ({
+	name,
+	description: options.description,
+	instructions: options.instructions
+});
+/**
+* Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no
+* skills.
+*
+* @category utils
+* @since 0.1.0
+*/
+const withCatalog = (prompt, skills) => skills.length === 0 ? prompt : [
+	prompt,
+	"",
+	"## Skills",
+	"Playbooks for common tasks. When one matches what you're doing, load it with load_skill in the same step as your first lookups, and follow it.",
+	...skills.map((skill) => `- ${skill.name}: ${skill.description}`)
+].join("\n");
+//#endregion
+export { Skill_exports, make, withCatalog };
+
+//# sourceMappingURL=Skill.js.map