effect-assistant 0.1.0 → 0.3.0

package/dist/Timeline.d.ts

@@ -0,0 +1,482 @@
+import { AnyEntry, AppEventSchema, AssistantEvent_d_exports } from "./AssistantEvent.js";
+import { Assistant_d_exports, Entry } from "./Assistant.js";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+declare namespace Timeline_d_exports {
+  export { Activity, AssistantMessage, Block, BlockStatus, Change, ChangesOptions, Definition, EventItem, Item, ShowOptions, Shown, SpecialistWorking, Timeline, UserMessage, apply, changes, empty, fold, fromEntries, isIdle, snapshot };
+}
+/**
+ * Schema for the status of a block. A block is `"open"` while it accepts an answer, `"answered"`
+ * once the user has used it, and `"closed"` when it closed without an answer because the user
+ * answered in words or moved on.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const BlockStatus: Schema.Literals<readonly ["open", "answered", "closed"]>;
+/**
+ * The status of a block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type BlockStatus = typeof BlockStatus.Type;
+/**
+ * Schema for a block on an assistant's message. It holds the block's kind, its props (JSON, as
+ * the block's props schema encodes them), its status, and the user's answer (JSON, as the block's
+ * answer schema encodes it).
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Block: Schema.Struct<{
+  readonly kind: Schema.String;
+  readonly props: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+  readonly status: Schema.Literals<readonly ["open", "answered", "closed"]>;
+  readonly answer: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/**
+ * Represents a block on an assistant's message.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Block = typeof Block.Type;
+/**
+ * Schema for a message the user sent. `at` is when it was stored, in epoch
+ * milliseconds.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const UserMessage: Schema.TaggedStruct<"UserMessage", {
+  readonly id: Schema.brand<Schema.String, "~effect-assistant/InputId">;
+  readonly text: Schema.String;
+  readonly attachments: Schema.optional<Schema.$Array<Schema.Struct<{
+    readonly fileId: Schema.String;
+    readonly name: Schema.String;
+    readonly mediaType: Schema.String;
+    readonly size: Schema.Finite;
+  }>>>;
+  readonly at: Schema.Finite;
+}>;
+/**
+ * Represents a message the user sent.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type UserMessage = typeof UserMessage.Type;
+/**
+ * Schema for a message the assistant sent the user, including its block if it has one.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const AssistantMessage: Schema.TaggedStruct<"AssistantMessage", {
+  readonly id: Schema.String;
+  readonly text: Schema.String;
+  readonly at: Schema.Finite;
+  readonly block: Schema.optional<Schema.Struct<{
+    readonly kind: Schema.String;
+    readonly props: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly status: Schema.Literals<readonly ["open", "answered", "closed"]>;
+    readonly answer: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  }>>;
+}>;
+/**
+ * Represents a message the assistant sent the user.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type AssistantMessage = typeof AssistantMessage.Type;
+/**
+ * Represents one of the app's own events in the timeline: an item between the messages, in the
+ * order the chat stored it.
+ *
+ * **Details**
+ *
+ * The item's `_tag` is the event's, so a match over a timeline's items takes a handler per event
+ * beside `UserMessage` and `AssistantMessage`. The event, decoded with its schema, is in `event`,
+ * and the item's own fields sit beside it rather than spread into it: an event may have an `id` or
+ * an `at` of its own, and a class instance keeps its prototype. `id` is fixed per entry of the
+ * chat's log, and `at` is when the event was stored, in epoch milliseconds.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export type EventItem<E> = E extends {
+  readonly _tag: infer Tag extends string;
+} ? {
+  readonly _tag: Tag;
+  readonly id: string;
+  readonly at: number;
+  readonly event: E;
+} : never;
+/**
+ * Represents an item in the chat's timeline: a message the user or the assistant sent, or one of
+ * the app's own events it shows (see {@link EventItem}).
+ *
+ * **Example** (Showing each item of a chat)
+ *
+ * ```ts
+ * import { Timeline } from "effect-assistant"
+ * import * as Match from "effect/Match"
+ * import * as Schema from "effect/Schema"
+ *
+ * class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+ *
+ * const line = (item: Timeline.Item<DailyBudgetReached>) =>
+ *   Match.valueTags(item, {
+ *     UserMessage: (sent) => `You: ${sent.text}`,
+ *     AssistantMessage: (sent) => `Assistant: ${sent.text}`,
+ *     DailyBudgetReached: () => "You've reached today's budget."
+ *   })
+ * ```
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export type Item<Events = never> = UserMessage | AssistantMessage | EventItem<Events>;
+/**
+ * Schema for a specialist that is working for the assistant. It holds the specialist's name and
+ * when it started, in epoch milliseconds.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SpecialistWorking: Schema.Struct<{
+  readonly specialist: Schema.String;
+  readonly since: Schema.Finite;
+}>;
+/**
+ * Represents a specialist that is working for the assistant.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SpecialistWorking = typeof SpecialistWorking.Type;
+/**
+ * Schema for what is working in the chat.
+ *
+ * `working` is true while the assistant runs a turn, or when a turn is about to start for
+ * something that arrived. `specialists` lists the specialists that are working. When the chat is
+ * idle, nothing is working, even if a workflow is waiting on a timer or on the user.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Activity: Schema.Struct<{
+  readonly working: Schema.Boolean;
+  readonly specialists: Schema.$Array<Schema.Struct<{
+    readonly specialist: Schema.String;
+    readonly since: Schema.Finite;
+  }>>;
+}>;
+/**
+ * Represents what is working in the chat.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Activity = typeof Activity.Type;
+/**
+ * Represents a chat's timeline: the chat as its user sees it, typed with the app's events it shows.
+ * It holds the chat's items in order, what is working in it, whether the last turn failed, and
+ * whether the chat was deleted. `seq` is the position in the chat's log that the timeline is up to.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export interface Timeline<Events = never> {
+  readonly seq: number;
+  readonly items: ReadonlyArray<Item<Events>>;
+  readonly activity: Activity;
+  /** Whether the last turn failed with no message after it. */
+  readonly failed: boolean;
+  /** Whether the chat was deleted. A deleted chat accepts nothing more, and its stream ends. */
+  readonly deleted: boolean;
+}
+/**
+ * Represents a change to a chat's timeline, typed with the app's events it shows.
+ *
+ * **Details**
+ *
+ * A change holds each item that is new or changed (for example, a message whose block was
+ * answered or closed), in full. It also holds the current activity, whether the last turn failed,
+ * and whether the chat was deleted. `seq` is the position in the chat's log that the change is up
+ * to.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export interface Change<Events = never> {
+  readonly seq: number;
+  readonly items: ReadonlyArray<Item<Events>>;
+  readonly activity: Activity;
+  readonly failed: boolean;
+  readonly deleted: boolean;
+}
+/**
+ * Creates the schema for the changes to a chat's timeline, with items for the given app events,
+ * in JSON.
+ *
+ * **Details**
+ *
+ * It is the success schema of the RPC that streams a chat's timeline: name the events the chat's
+ * users see, the same ones the handler passes to {@link changes} as `show`. Each item decodes its
+ * event with that event's schema, so the client gets `Change<Events>` typed with them and folds it
+ * with {@link fold}, no definition needed. `Change()` carries no app events.
+ *
+ * A handler whose changes show an event the schema doesn't name doesn't compile.
+ *
+ * **Example** (An RPC that streams a chat's timeline, with the budget notice)
+ *
+ * ```ts
+ * import { ChatId, Timeline } from "effect-assistant"
+ * import * as Rpc from "effect/rpc/Rpc"
+ * import * as Schema from "effect/Schema"
+ *
+ * class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+ *
+ * const Subscribe = Rpc.make("Subscribe", {
+ *   payload: { chatId: ChatId.ChatId },
+ *   success: Timeline.Change([DailyBudgetReached]),
+ *   stream: true
+ * })
+ * ```
+ *
+ * @category schemas
+ * @since 0.3.0
+ */
+export declare const Change: <const Events extends ReadonlyArray<AppEventSchema> = readonly []>(events?: Events) => Schema.Codec<Change<Events[number]["Type"]>, Schema.Json>;
+/**
+ * The timeline of a chat before anything has happened in it, with no items and nothing working.
+ * Use it as the starting point when folding changes with {@link apply}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const empty: Timeline;
+/**
+ * Returns the timeline after a change.
+ *
+ * **Details**
+ *
+ * Each item in the change replaces the item with the same id, in place, and new items are added
+ * after the rest. The change's activity, `failed`, and `deleted` replace the timeline's. Applying a
+ * change twice changes nothing, so a client that resubscribes from the start can fold again and get
+ * the same timeline.
+ *
+ * The timeline is typed with the change's events, as its RPC's schema decoded them (see
+ * {@link Change}). To fold a stream of changes, use {@link fold}: in
+ * `Stream.scan(() => Timeline.empty, Timeline.apply)`, TypeScript fixes the state's type from
+ * `empty` before it sees the changes' events, so that form needs the timeline's type written out.
+ *
+ * **Example** (Folding changes into your own state)
+ *
+ * ```ts
+ * import { Timeline } from "effect-assistant"
+ *
+ * interface State<Events> {
+ *   readonly timeline: Timeline.Timeline<Events>
+ *   readonly unread: number
+ * }
+ *
+ * const next = <Events>(state: State<Events>, change: Timeline.Change<Events>): State<Events> => ({
+ *   timeline: Timeline.apply(state.timeline, change),
+ *   unread: state.unread + change.items.length
+ * })
+ * ```
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const apply: <Events>(timeline: Timeline<Events>, change: Change<Events>) => Timeline<Events>;
+/**
+ * Returns the timelines a stream of changes folds to, from {@link empty}, typed with the changes'
+ * events.
+ *
+ * **Example** (A chat's timeline on the client)
+ *
+ * ```ts
+ * import { Timeline } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ * import * as Stream from "effect/Stream"
+ *
+ * class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+ *
+ * // The stream of an RPC whose success schema is `Timeline.Change([DailyBudgetReached])`.
+ * declare const changes: Stream.Stream<Timeline.Change<DailyBudgetReached>>
+ *
+ * const timelines = changes.pipe(Timeline.fold) // Stream<Timeline.Timeline<DailyBudgetReached>>
+ * ```
+ *
+ * @category combinators
+ * @since 0.3.0
+ */
+export declare const fold: <Events, E, R>(changes: Stream.Stream<Change<Events>, E, R>) => Stream.Stream<Timeline<Events>, E, R>;
+/**
+ * Returns whether nothing is working in the chat: no turn is running or about to start, and no
+ * specialist is working.
+ *
+ * @category guards
+ * @since 0.1.0
+ */
+export declare const isIdle: <Events>(timeline: Timeline<Events>) => boolean;
+/**
+ * Represents the options for building a chat's timeline from its log.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export interface ShowOptions<Show extends ReadonlyArray<AppEventSchema>> {
+  /**
+   * The schemas of the app's events the chat's users see. Each becomes an item in the timeline;
+   * the app's other events are left out. Defaults to none.
+   */
+  readonly show?: Show | undefined;
+}
+/**
+ * Represents the schemas an assistant's timeline may show: some of its own events.
+ *
+ * @category utility types
+ * @since 0.3.0
+ */
+export type Shown<Events> = ReadonlyArray<AppEventSchema & {
+  readonly Type: Events;
+}>;
+/**
+ * Returns a chat's whole timeline as one change, built from the entries of its log.
+ *
+ * **When to use**
+ *
+ * Use it on the server for an RPC that returns a whole chat at once: its success schema is
+ * {@link Change} with the same events as `show`, and the client applies it to {@link empty}.
+ *
+ * **Details**
+ *
+ * Only the app's events in `show` become items; without it, the timeline has none.
+ *
+ * @category constructors
+ * @since 0.3.0
+ */
+export declare const snapshot: {
+  (entries: ReadonlyArray<AnyEntry>): Change;
+  <Events, const Show extends Shown<Events> = readonly []>(entries: ReadonlyArray<AnyEntry>, definition: Definition<Events>, options?: ShowOptions<Show>): Change<Show[number]["Type"]>;
+};
+/**
+ * Returns a chat's timeline, built from the entries of its log.
+ *
+ * **When to use**
+ *
+ * Use it in server-side code that reads a whole chat. A client gets the timeline as a stream from
+ * {@link changes} instead, and an RPC that returns a whole chat sends a {@link snapshot}.
+ *
+ * **Details**
+ *
+ * Only the app's events in `show` become items, typed with their schemas; without it, the timeline
+ * has none.
+ *
+ * **Example** (Building a chat's timeline from its log)
+ *
+ * ```ts
+ * import { type ChatId, ChatLog, Timeline } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ *
+ * const timelineOf = (chatId: ChatId.ChatId) =>
+ *   ChatLog.ChatLog.use((log) => log.read(chatId)).pipe(
+ *     Effect.map((entries) => Timeline.fromEntries(entries))
+ *   )
+ * ```
+ *
+ * @see {@link changes} for a stream of changes instead of a whole timeline
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fromEntries: {
+  (entries: ReadonlyArray<AnyEntry>): Timeline;
+  <Events, const Show extends Shown<Events> = readonly []>(entries: ReadonlyArray<AnyEntry>, definition: Definition<Events>, options?: ShowOptions<Show>): Timeline<Show[number]["Type"]>;
+};
+/**
+ * Represents an assistant's definition as the timeline reads it. An assistant made with
+ * `Assistant.make` fits it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Definition<Events = never> {
+  /** The schemas of the assistant's events. */
+  readonly events: ReadonlyArray<AppEventSchema>;
+  /** The schema of the chat's entries, typed with the assistant's events: it types `show`. */
+  readonly Entry: Schema.Codec<Entry<Events>, Schema.Json>;
+}
+/**
+ * Represents the options accepted by {@link changes}.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export interface ChangesOptions<Show extends ReadonlyArray<AppEventSchema> = readonly []> extends ShowOptions<Show> {
+  /**
+   * The `seq` up to which the client already has the timeline. The result contains only the
+   * changes after it. Defaults to `0`, every change.
+   */
+  readonly after?: number | undefined;
+}
+/**
+ * Returns the stream of changes to a chat's timeline that its entries produce, for a chat client.
+ *
+ * **Details**
+ *
+ * The entries must stream from the start of the chat's log, as `assistant.subscribe(chatId)` does
+ * without `after`. The fold reads every entry, because a message depends on earlier entries: its
+ * block is answered or closed later. `after` only skips emitting the changes up to that `seq`, so a
+ * client that has the timeline up to a `seq` receives only what changed since. Pass `after` here,
+ * not to `subscribe`: a subscription that starts after a `seq` gives the fold an incomplete log,
+ * and the changes it produces are wrong.
+ *
+ * Each chunk of entries becomes one change; the stored entries, for example, arrive as one chunk.
+ *
+ * **Only the app's events in `show` reach the client.** Each one becomes an item between the
+ * messages (see {@link EventItem}); the app's other events, like a summary of the chat for the
+ * model, are left out. Without `show`, none are shown. The changes are typed with the events shown,
+ * so the RPC's success schema names the same ones (`Timeline.Change([...])`), and a handler that
+ * shows one the schema doesn't name doesn't compile. A timeline shows a turn as working once it
+ * starts, or from the user's input.
+ *
+ * **Example** (Streaming a chat's timeline to a client, with the one app event its user sees)
+ *
+ * ```ts
+ * import { Assistant, type ChatId, Timeline } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ * import * as Stream from "effect/Stream"
+ *
+ * class Summary extends Schema.TaggedClass<Summary>()("Summary", { text: Schema.String, throughSeq: Schema.Int }) {}
+ * class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+ *
+ * const MyAssistant = Assistant.make("my-assistant", { events: [Summary, DailyBudgetReached] })
+ *
+ * // The summary is for the model: only the budget notice reaches the user.
+ * const watch = (chatId: ChatId.ChatId, after: number) =>
+ *   Stream.unwrap(
+ *     MyAssistant.useSync((assistant) =>
+ *       assistant.subscribe(chatId).pipe(Timeline.changes(MyAssistant, { show: [DailyBudgetReached], after }))
+ *     )
+ *   )
+ * ```
+ *
+ * @see {@link fold} for folding the changes into a timeline on the client
+ *
+ * @category utils
+ * @since 0.3.0
+ */
+export declare const changes: {
+  <Events, const Show extends Shown<Events> = readonly []>(definition: Definition<Events>, options?: ChangesOptions<Show>): <E, R>(entries: Stream.Stream<AnyEntry, E, R>) => Stream.Stream<Change<Show[number]["Type"]>, E, R>;
+  <E, R, Events, const Show extends Shown<Events> = readonly []>(entries: Stream.Stream<AnyEntry, E, R>, definition: Definition<Events>, options?: ChangesOptions<Show>): Stream.Stream<Change<Show[number]["Type"]>, E, R>;
+};
+//#endregion
+export { Timeline_d_exports };
+//# sourceMappingURL=Timeline.d.ts.map

package/dist/Timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeline.d.ts","names":[],"sources":["../src/Timeline.ts"],"mappings":";;;;;;;;;;;;;;;qBAyCa,aAAW,OAAA;;;;;;;YAQZ,qBAAqB,YAAY;;;;;;;;;qBAUhC,OAAK,OAAA;;;;;;;;;;;;YAaN,eAAe,MAAM;;;;;;;;qBASpB,aAAW,OAAA;;;;;;;;;;;;;;;;;YAaZ,qBAAqB,YAAY;;;;;;;qBAQhC,kBAAgB,OAAA;;;;;;;;;;;;;;;;;YAajB,0BAA0B,iBAAiB;;;;;;;;;;;;;;;;YAiB3C,UAAU,KAAK;WAAqB,YAAY;;WAC7C,MAAM;WAAc;WAAqB;WAAqB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;YA2BxE,KAAK,kBAAkB,cAAc,mBAAmB,UAAU;;;;;;;;qBASjE,mBAAiB,OAAA;;;;;;;;;;YAWlB,2BAA2B,kBAAkB;;;;;;;;;;;qBAY5C,UAAQ,OAAA;;;;;;;;;;;;;YAWT,kBAAkB,SAAS;;;;;;;;;iBAUtB,SAAS;WACf;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;;WAEV;;WAEA;;;;;;;;;;;;;;;iBAgBM,OAAO;WACb;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;WACV;WACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkEE,eAAe,eAAe,cAAc,+BACvD,SAAS,WACN,OAAO,MAAM,OAAO,yBAAyB,OAAO;;;;;;;;qBAS5C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0CP,QAAS,QAAM,UAAY,SAAS,SAAO,QAAU,OAAO,YAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;qBAsC/E,OAAQ,QAAQ,GAAG,GAAC,SACtB,OAAO,OAAO,OAAO,SAAS,GAAG,OACzC,OAAO,OAAO,SAAS,SAAS,GAAG;;;;;;;;qBASzB,SAAU,QAAM,UAAY,SAAS;;;;;;;iBAyBjC,YAAY,aAAa,cAAc;;;;;WAK7C,OAAO;;;;;;;;YASN,MAAM,UAAU,cAAc;WAA2C,MAAM;;;;;;;;;;;;;;;;;qBAmC9E;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmDC;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,SAAS;;;;;;;;;iBA4MG,WAAW;;WAEjB,QAAQ,cAAc;;WAEtB,OAAO,OAAO,MAAM,MAAgB,SAAS,OAAO;;;;;;;;iBAS9C,eACf,aAAa,cAAc,uCACnB,YAAY;;;;;WAKX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgFE;GACV,cAAc,aAAa,MAAM,uBAChC,YAAY,WAAW,SACvB,UAAU,eAAe,SACvB,GAAG,GAAG,SAAS,OAAO,OAAO,UAAyB,GAAG,OAAO,OAAO,OAAO,OAAO,uBAAuB,GAAG;GAClH,GAAG,GAAG,cAAc,aAAa,MAAM,uBACtC,SAAS,OAAO,OAAO,UAAyB,GAAG,IACnD,YAAY,WAAW,SACvB,UAAU,eAAe,QACxB,OAAO,OAAO,OAAO,uBAAuB,GAAG"}