fauna-api 0.0.0-stage → 1.0.676

package/dist/src/parrot/chat.js

@@ -0,0 +1,237 @@
+import { Parrot } from "./index.js";
+import { Profile } from "../authentification.js";
+import * as Drive from "../drive.js";
+import { openRoom } from "./share.js";
+import { connectRoom } from "./room.js";
+/**
+ * Open a chat as a live room: host it server-side, seed the newest window from
+ * durable, then connect. Pass a durable `chatId` to bind the room
+ * (`parrot:chat:{chatId}`, persisted + billed to the chat's balance-holder);
+ * omit it for an unbound ephemeral room. `share: true` also mints an access code
+ * others can redeem. Every chat — solo or group — opens through this single
+ * always-host path. Returns the connected `ChatRoom`, the caller's `Presence`,
+ * the room `reference`, and the access `code` when shared.
+ */
+export async function openChat(authorization, options = {}) {
+    const opened = await openRoom(authorization, {
+        chatId: options.chatId,
+        messages: options.messages,
+        share: options.share,
+    });
+    const target = opened.code ? { code: opened.code } : { reference: opened.reference };
+    const { room, self } = await connectRoom(authorization, target, options.hooks ?? {});
+    return { room, self, reference: opened.reference, code: opened.code };
+}
+/**
+ * Create a chat, owned by the caller or by `group`. `human: true` makes it a
+ * people only chat for good: sends never start a model reply. `systemPrompt`
+ * instructs every model reply in the chat. `locked: true` lets only you delete
+ * it or move it to another group; it still goes away with its group.
+ * `repository` is a Termite repository Parrot works in during replies: yours
+ * for a personal chat, the group's for a group chat.
+ */
+export async function createChat(authorization, name = 'New Chat', group, options = {}) {
+    const response = await fetch(`${Parrot.getURL()}/chat/create`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({
+            name,
+            human: options.human === true,
+            systemPrompt: options.systemPrompt,
+            locked: options.locked === true,
+            repository: options.repository?.id,
+        })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return json.id;
+}
+export async function deleteChat(authorization, id, group) {
+    const response = await fetch(`${Parrot.getURL()}/chat/delete`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export const LastMessage = {
+    fromJSON(json) {
+        if (!json || typeof json !== "object")
+            return null;
+        const row = json;
+        const createdAt = row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt);
+        if (Number.isNaN(createdAt.getTime()) || typeof row.position !== "number")
+            return null;
+        return {
+            parts: Array.isArray(row.parts) ? row.parts : [],
+            role: String(row.role ?? ""),
+            createdAt,
+            position: row.position,
+            author: Profile.fromJSON(row.author),
+            model: row.model ? String(row.model) : undefined,
+        };
+    },
+};
+export async function listChats(authorization, group) {
+    const response = await fetch(`${Parrot.getURL()}/chat/all`, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const rows = await response.json();
+    return (Array.isArray(rows) ? rows : []).map((row) => ({
+        ...row,
+        human: row.human === true,
+        locked: row.locked === true,
+        repository: typeof row.repository === 'number' && row.repository > 0 ? row.repository : null,
+        last: LastMessage.fromJSON(row.last),
+        unread: typeof row.unread === 'number' ? row.unread : 0,
+    }));
+}
+export async function renameChat(authorization, id, name, group) {
+    const response = await fetch(`${Parrot.getURL()}/chat/rename`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id, name })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+/**
+ * Mark a chat read for the caller, up to `position` (the next unread one) or all
+ * of it. Signed in with an API key, the key keeps its own place, apart from its
+ * person. Sending a message reads the chat for its sender. Returns what's left unread.
+ */
+export async function markRead(authorization, id, position, group) {
+    const response = await fetch(`${Parrot.getURL()}/chat/mark-read`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id, position })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return typeof json.unread === 'number' ? json.unread : 0;
+}
+function fileRef(file) {
+    const authorization = file.authorization;
+    if ('accessCode' in authorization) {
+        return { type: 'FILE', name: file.name, contentType: file.contentType, accessCode: authorization.accessCode };
+    }
+    return {
+        type: 'FILE',
+        name: file.name,
+        contentType: file.contentType,
+        path: authorization.path,
+        ...(authorization.group ? { group: authorization.group } : {}),
+    };
+}
+function hydrateFilePart(authorization, part, group) {
+    const name = part.name ?? 'file';
+    const contentType = part.contentType ?? 'application/octet-stream';
+    if (part.accessCode) {
+        return { type: 'FILE', file: Drive.File.fromJSON({ ...part, name, contentType }, { authorization, accessCode: part.accessCode }) };
+    }
+    if (part.path) {
+        return { type: 'FILE', file: Drive.File.fromJSON({ ...part, name, contentType }, { authorization, path: part.path, group: part.group ?? group?.id }) };
+    }
+    return { type: 'FILE', file: Drive.fromBytes(authorization, name, contentType, new Uint8Array()) };
+}
+/** One page of a chat, newest first. */
+export async function readChat(authorization, id, group, query) {
+    const response = await fetch(`${Parrot.getURL()}/chat/read`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id, cursor: query.cursor, max: query.max })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    const messages = [];
+    for (const message of Array.isArray(json) ? json : []) {
+        const parts = [];
+        for (const part of message.parts ?? []) {
+            if (part.type === 'FILE') {
+                parts.push(hydrateFilePart(authorization, part, group));
+            }
+            else {
+                parts.push(part);
+            }
+        }
+        messages.push({
+            parts,
+            role: message.role,
+            author: message.author,
+            model: message.model,
+            createdAt: new Date(message.createdAt),
+            ...(message.via ? { via: String(message.via) } : {}),
+        });
+    }
+    return messages;
+}
+export async function writeChat(authorization, id, messages, group) {
+    const serializedMessages = [];
+    for (const message of messages) {
+        const serializedParts = [];
+        for (const part of message.parts) {
+            if (part.type === 'FILE') {
+                let file = part.file;
+                if (!file.online) {
+                    const dest = `tmp/${crypto.randomUUID()}-${file.name}`;
+                    const bytes = await file.download();
+                    file = Drive.fromBytes(authorization, dest, file.contentType, bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+                    await file.upload();
+                }
+                serializedParts.push(fileRef(file));
+            }
+            else {
+                serializedParts.push(part);
+            }
+        }
+        serializedMessages.push({
+            parts: serializedParts,
+            role: message.role,
+            author: message.author,
+            model: message.model,
+            createdAt: message.createdAt,
+        });
+    }
+    const response = await fetch(`${Parrot.getURL()}/chat/write`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ id, messages: serializedMessages })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}

package/dist/src/parrot/format.d.ts

@@ -0,0 +1,128 @@
+import { Embedding, Text, TextResponse, Tool, type Content } from "./generative.js";
+import { Credentials, ApiKey } from "../authentification.js";
+export declare abstract class Format<T> {
+    readonly instruction: string;
+    tool: Tool;
+    protected response: T | undefined;
+    constructor(instruction: string, tool: Tool);
+    abstract clone(): Format<T>;
+    answer(response: T): void;
+    abstract toJSON(): any;
+    /**
+     * Returns a unit-length numerical representation of the format's current
+     * response. Used by the research agent's per-scope rank-dedup matrix to
+     * detect linearly-dependent rows (duplicates). Concatenated across an
+     * entity's atomic fields, the resulting vector is the row's identifier.
+     *
+     * Contract: all implementations return a vector with L2 norm == 1 when
+     * a response is present. If the response is missing or empty, an
+     * implementation may return a zero-length array — callers MUST skip such
+     * fields when concatenating (they correspond to optional / unfilled
+     * fields and are excluded from the rank check).
+     */
+    abstract toVector(): number[];
+    llm(authorization: Credentials | ApiKey, model: Text, options?: Partial<{
+        content: Content[];
+    }>): Promise<TextResponse>;
+    getResponse(): T | undefined;
+    static optional<T>(format: Format<T>): Format<T>;
+    static calculateDistance(a: Format<any>, b: Format<any>): number;
+    static fromJSON(json: any): Format<any>;
+}
+export declare class NumericalFormat extends Format<number> {
+    readonly bounds: [number | undefined, number | undefined] | undefined;
+    constructor(instruction: string, bounds?: [number | undefined, number | undefined]);
+    clone(): NumericalFormat;
+    getResponse(): number | undefined;
+    toJSON(): {
+        type: string;
+        instruction: string;
+        bounds: [number | undefined, number | undefined] | undefined;
+        answer: number | undefined;
+    };
+    /**
+     * Encode the scalar as a 2-dim unit vector `[x, 1] / sqrt(x²+1)`. Direct
+     * unit-norm on a 1-dim scalar would collapse to just the sign and discard
+     * magnitude; the 2-dim wrap preserves magnitude as the vector's angle so
+     * two identical scalars yield identical unit vectors and different scalars
+     * yield distinguishable directions.
+     */
+    toVector(): number[];
+    static compare(a: number, b: number): number;
+    static distance(a: Format<number>, b: Format<number>): number;
+    static tool(bounds?: [number | undefined, number | undefined]): Tool;
+}
+export declare class VectorFormat extends Format<number[]> {
+    readonly dimension: number;
+    readonly bounds: ([number | undefined, number | undefined] | undefined)[] | undefined;
+    constructor(instruction: string, dimension: number, bounds?: ([number | undefined, number | undefined] | undefined)[]);
+    clone(): VectorFormat;
+    getResponse(): number[] | undefined;
+    toJSON(): {
+        type: string;
+        instruction: string;
+        dimension: number;
+        bounds: ([number | undefined, number | undefined] | undefined)[] | undefined;
+        answer: number[] | undefined;
+    };
+    toVector(): number[];
+    static distance(a: Format<number[]>, b: Format<number[]>): number;
+    static tool(dimension: number, bounds?: ([number | undefined, number | undefined] | undefined)[]): Tool;
+}
+export declare class CategoricalFormat extends Format<string> {
+    private categories;
+    constructor(instruction: string, categories: string[]);
+    clone(): CategoricalFormat;
+    getCategories(): string[];
+    getResponse(): string | undefined;
+    toJSON(): {
+        type: string;
+        instruction: string;
+        categories: string[];
+        answer: string | undefined;
+    };
+    /** One-hot over the category set — already unit-length. */
+    toVector(): number[];
+    static distance(a: Format<string>, b: Format<string>): number;
+    static tool(categories: string[]): Tool;
+}
+export declare class SelectionFormat extends Format<string[]> {
+    private options;
+    constructor(instruction: string, options: string[]);
+    clone(): SelectionFormat;
+    getOptions(): string[];
+    getResponse(): string[] | undefined;
+    toJSON(): {
+        type: string;
+        instruction: string;
+        options: string[];
+        answer: string[] | undefined;
+    };
+    /** Multi-hot scaled by 1/sqrt(count) so the vector is unit-length. */
+    toVector(): number[];
+    static distance(a: Format<string[]>, b: Format<string[]>): number;
+    static tool(options: string[]): Tool;
+}
+export declare class UtteranceFormat extends Format<string> {
+    readonly time: number | undefined;
+    embedding?: number[];
+    constructor(instruction: string, time?: number);
+    clone(): UtteranceFormat;
+    toJSON(): {
+        type: string;
+        instruction: string;
+        time: number | undefined;
+        answer: string | undefined;
+    };
+    /**
+     * Returns the unit-normalized embedding. The caller MUST have populated
+     * `embedding` first (via `embed()` or the research agent's extraction
+     * pipeline) — otherwise we return an empty slice and the field is
+     * excluded from the rank check. Embedding-less utterances cannot
+     * participate in dedup.
+     */
+    toVector(): number[];
+    embed(authorization: Credentials | ApiKey, model: Embedding): Promise<void>;
+    static distance(a: UtteranceFormat, b: UtteranceFormat): number;
+    static tool(time?: number): Tool;
+}