effect-assistant 0.0.0-stage → 0.2.0

package/dist/ChatView.d.ts

@@ -0,0 +1,408 @@
+import { AnyEntry, AssistantEvent_d_exports } from "./AssistantEvent.js";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+declare namespace ChatView_d_exports {
+  export { Activity, AssistantMessage, Block, BlockStatus, Definition, Message, Options, SpecialistWorking, Update, UpdatesOptions, UserMessage, View, apply, empty, fromEntries, isIdle, updates };
+}
+/**
+ * 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;
+/**
+ * Schema for a message in the chat, sent by either the user or the assistant.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Message: Schema.Union<readonly [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;
+}>, 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 in the chat.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Message = typeof Message.Type;
+/**
+ * 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;
+/**
+ * Schema for a chat as its user sees it. It holds the chat's messages, 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 view is up to.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const View: Schema.Struct<{
+  readonly seq: Schema.Int;
+  readonly messages: Schema.$Array<Schema.Union<readonly [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;
+  }>, 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>>;
+    }>>;
+  }>]>>;
+  readonly activity: Schema.Struct<{
+    readonly working: Schema.Boolean;
+    readonly specialists: Schema.$Array<Schema.Struct<{
+      readonly specialist: Schema.String;
+      readonly since: Schema.Finite;
+    }>>;
+  }>;
+  /** Whether the last turn failed with no message after it. */
+  readonly failed: Schema.Boolean;
+  /** Whether the chat was deleted. A deleted chat accepts nothing more, and its stream ends. */
+  readonly deleted: Schema.Boolean;
+}>;
+/**
+ * Represents a chat as its user sees it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type View = typeof View.Type;
+/**
+ * Schema for a change to a chat's view.
+ *
+ * An update holds each message that is new or changed (for example, a block 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 update is up
+ * to.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Update: Schema.Struct<{
+  readonly seq: Schema.Int;
+  readonly messages: Schema.$Array<Schema.Union<readonly [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;
+  }>, 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>>;
+    }>>;
+  }>]>>;
+  readonly activity: Schema.Struct<{
+    readonly working: Schema.Boolean;
+    readonly specialists: Schema.$Array<Schema.Struct<{
+      readonly specialist: Schema.String;
+      readonly since: Schema.Finite;
+    }>>;
+  }>;
+  readonly failed: Schema.Boolean;
+  readonly deleted: Schema.Boolean;
+}>;
+/**
+ * Represents a change to a chat's view.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Update = typeof Update.Type;
+/**
+ * The view of a chat before anything has happened in it, with no messages and nothing working.
+ * Use it as the starting point when folding updates with {@link apply}.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const empty: View;
+/**
+ * Returns the view after applying an update.
+ *
+ * **Details**
+ *
+ * Each message in the update replaces the message with the same id, in place, and new messages
+ * are added after the rest. The update's activity, `failed`, and `deleted` replace the view's.
+ * Applying an update twice changes nothing, so a client that resubscribes from the start can fold
+ * again and get the same view.
+ *
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const apply: (view: View, update: Update) => View;
+/**
+ * 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: (view: View) => boolean;
+/**
+ * Represents the options for building a view from a chat's log.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  /**
+   * The tags of the app's events that wake a turn. After such an event, the view shows a turn as
+   * about to start. Defaults to none.
+   */
+  readonly wakes?: ReadonlySet<string> | undefined;
+}
+/**
+ * Returns a chat's view, built from the entries of its log.
+ *
+ * **When to use**
+ *
+ * Use it in server-side code, for example to return a whole chat at once. A client gets the view
+ * as a stream from {@link updates} instead.
+ *
+ * **Example** (Building a chat's view from its log)
+ *
+ * ```ts
+ * import { type ChatId, ChatLog, ChatView } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ *
+ * const viewOf = (chatId: ChatId.ChatId) =>
+ *   ChatLog.ChatLog.use((log) => log.read(chatId)).pipe(
+ *     Effect.map((entries) => ChatView.fromEntries(entries))
+ *   )
+ * ```
+ *
+ * @see {@link updates} for a stream of changes instead of a whole view
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fromEntries: (entries: ReadonlyArray<AnyEntry>, options?: Options) => View;
+/**
+ * Represents an assistant's definition as {@link updates} reads it: the app's events it
+ * registered, and whether each one wakes a turn. An assistant made with `Assistant.make` fits it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Definition {
+  readonly events: ReadonlyArray<{
+    readonly tag: string;
+    readonly wakes: boolean;
+  }>;
+}
+/**
+ * Represents the options accepted by {@link updates}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface UpdatesOptions {
+  /**
+   * The `seq` up to which the client already has the view. The result contains only the updates
+   * after it. Defaults to `0`, every update.
+   */
+  readonly after?: number | undefined;
+}
+/**
+ * Returns the stream of view updates that a chat's 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's view depends on earlier
+ * entries: a block is answered or closed later. `after` only skips
+ * emitting the updates up to that `seq`, so a client that has the view 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 updates it produces are wrong.
+ *
+ * The definition tells the fold which of the app's events wake a turn, so the view shows a turn as
+ * about to start after one. Each chunk of entries becomes one update; the stored entries, for
+ * example, arrive as one chunk.
+ *
+ * **Example** (Streaming a chat's view to a client)
+ *
+ * ```ts
+ * import { Assistant, type ChatId, ChatView } from "effect-assistant"
+ * import * as Stream from "effect/Stream"
+ *
+ * const MyAssistant = Assistant.make("my-assistant")
+ *
+ * const watch = (chatId: ChatId.ChatId, after: number) =>
+ *   Stream.unwrap(
+ *     MyAssistant.useSync((assistant) =>
+ *       assistant.subscribe(chatId).pipe(ChatView.updates(MyAssistant, { after }))
+ *     )
+ *   )
+ * ```
+ *
+ * @see {@link apply} for folding the updates into a view on the client
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const updates: {
+  (definition: Definition, options?: UpdatesOptions): <E, R>(entries: Stream.Stream<AnyEntry, E, R>) => Stream.Stream<Update, E, R>;
+  <E, R>(entries: Stream.Stream<AnyEntry, E, R>, definition: Definition, options?: UpdatesOptions): Stream.Stream<Update, E, R>;
+};
+//#endregion
+export { ChatView_d_exports };
+//# sourceMappingURL=ChatView.d.ts.map

package/dist/ChatView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatView.d.ts","names":[],"sources":["../src/ChatView.ts"],"mappings":";;;;;;;;;;;;;;qBA+Ba,aAAW,OAAA;;;;;;;YAQZ,qBAAqB,YAAY;;;;;;;;;qBAUhC,OAAK,OAAA;;;;;;;;;;;;YAaN,eAAe,MAAM;;;;;;;;qBASpB,aAAW,OAAA;;;;;;;;;;;;;;;;;YAaZ,qBAAqB,YAAY;;;;;;;qBAQhC,kBAAgB,OAAA;;;;;;;;;;;;;;;;;YAajB,0BAA0B,iBAAiB;;;;;;;qBAQ1C,SAAO,OAAA,gBAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;YAQR,iBAAiB,QAAQ;;;;;;;;qBASxB,mBAAiB,OAAA;;;;;;;;;;YAWlB,2BAA2B,kBAAkB;;;;;;;;;;;qBAY5C,UAAQ,OAAA;;;;;;;;;;;;;YAWT,kBAAkB,SAAS;;;;;;;;;qBAU1B,MAAI,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAgBL,cAAc,KAAK;;;;;;;;;;;;qBAalB,QAAM,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAcP,gBAAgB,OAAO;;;;;;;;qBAStB,OAAO;;;;;;;;;;;;;;qBAqBP,QAAK,MAAU,MAAI,QAAU,WAAS;;;;;;;;qBAuBtC,SAAM,MAAU;;;;;;;iBAQZ;;;;;WAKN,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA4BN,cAAW,SAAa,cAAc,WAAwB,UAAY,YAAU;;;;;;;;iBAoLhF;WACN,QAAQ;aAAyB;aAAsB;;;;;;;;;iBASjD;;;;;WAKN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA2CE;GAET,YAAY,YACZ,UAAU,kBACR,GAAG,GAAG,SAAS,OAAO,OAAO,UAAyB,GAAG,OAAO,OAAO,OAAO,QAAQ,GAAG;GAC5F,GAAG,GACF,SAAS,OAAO,OAAO,UAAyB,GAAG,IACnD,YAAY,YACZ,UAAU,iBACT,OAAO,OAAO,QAAQ,GAAG"}