fauna-api 0.0.0-stage → 1.0.679

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

@@ -0,0 +1,90 @@
+import { Decision, Embedding, Image, Speech, Text, Transcription, Video, Voice } from "./generative.js";
+import { Credentials, ApiKey } from "../authentification.js";
+export type Garden = {
+    providers: Record<string, {
+        apiKey?: string;
+        systemPrompt?: string;
+        temperature?: number;
+    }>;
+    memories: number;
+};
+export declare function getPrice(model: Text | Embedding | Image | Video | Speech | Transcription | Voice | Decision): Promise<{
+    inputPer1M?: number;
+    outputPer1M?: number;
+    perUnit?: number;
+    unit?: string;
+}>;
+export declare function getDimensions(model: Embedding): Promise<number>;
+export type CatalogModel = {
+    model: string;
+    name: string;
+    provider: string;
+    baseURL: string;
+    icon: string;
+    inputPer1M?: number;
+    outputPer1M?: number;
+    cachedInputPer1M?: number;
+    perUnit?: number;
+    unit?: string;
+    kind?: string;
+    dimensions?: number;
+    reasoning?: string[];
+    /** Decision models: image input and the limits the model accepts. */
+    images?: boolean;
+    maxQuestions?: number;
+    maxOptions?: number;
+    inputContextWindow?: number;
+};
+export declare function getAll(): Promise<{
+    text: CatalogModel[];
+    embedding: CatalogModel[];
+    image: CatalogModel[];
+    video: CatalogModel[];
+    speech: CatalogModel[];
+    transcription: CatalogModel[];
+    voice: CatalogModel[];
+    decision: CatalogModel[];
+}>;
+export declare function getLastUsedModels(authorization: Credentials | ApiKey): Promise<{
+    text?: {
+        model: Text;
+        reasoning?: string;
+    };
+    embedding?: Embedding;
+    image?: Image;
+    video?: Video;
+    speech?: Speech;
+    transcription?: Transcription;
+}>;
+export declare function getUsage(authorization: Credentials | ApiKey): Promise<{
+    text: [string, string, {
+        input: number;
+        output: number;
+    }][];
+    embedding: [string, string, {
+        cost: number;
+    }][];
+    image: [string, string, {
+        cost: number;
+    }][];
+    video: [string, string, {
+        cost: number;
+    }][];
+    speech: [string, string, {
+        cost: number;
+    }][];
+    transcription: [string, string, {
+        cost: number;
+    }][];
+    voice: [string, string, {
+        cost: number;
+    }][];
+    decision: [string, string, {
+        cost: number;
+    }][];
+}>;
+export declare function getGarden(authorization: Credentials | ApiKey): Promise<Garden>;
+export declare function setGarden(authorization: Credentials | ApiKey, update: Partial<Garden> & {
+    provider?: string;
+    providerConfig?: Garden['providers'][string];
+}): Promise<void>;

package/dist/src/parrot/routing.js

@@ -0,0 +1,78 @@
+import { Parrot } from "./index.js";
+export async function getPrice(model) {
+    const response = await fetch(`${Parrot.getURL()}/routing/price/${encodeURIComponent(model)}`, {
+        method: "GET"
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function getDimensions(model) {
+    const response = await fetch(`${Parrot.getURL()}/routing/dimensions/${encodeURIComponent(model)}`, {
+        method: "GET"
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return Number(await response.text());
+}
+export async function getAll() {
+    const response = await fetch(`${Parrot.getURL()}/routing/all`, {
+        method: "GET",
+        headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function getLastUsedModels(authorization) {
+    const response = await fetch(`${Parrot.getURL()}/routing/last`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function getUsage(authorization) {
+    const response = await fetch(`${Parrot.getURL()}/routing/usage`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function getGarden(authorization) {
+    const response = await fetch(`${Parrot.getURL()}/routing/garden`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        }
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+    return await response.json();
+}
+export async function setGarden(authorization, update) {
+    const response = await fetch(`${Parrot.getURL()}/routing/garden`, {
+        method: "PUT",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`
+        },
+        body: JSON.stringify(update)
+    });
+    if (!response.ok) {
+        throw new Error(await response.text());
+    }
+}

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

@@ -0,0 +1,126 @@
+import { Parrot } from "./index.js";
+import { Credentials, ApiKey, Profile } from "../authentification.js";
+import { Content, Function, Role } from "./generative.js";
+import * as Drive from "../drive.js";
+/**
+ * Address a live room by a redeemable access code or by its globally-unique
+ * reference (`parrot:chat:{chatId}` for a durable-bound room, `parrot:room:{uuid}`
+ * for an unbound ephemeral one).
+ */
+export type ChatTarget = {
+    code: string;
+} | {
+    reference: string;
+};
+export declare function moveChatToGroup(credentials: Credentials, chatId: string, groupId: string): Promise<{
+    chatId: string;
+    groupId: string;
+}>;
+/**
+ * Host a live room server-side. Pass `chatId` to bind the room to a durable
+ * chat (reference becomes `parrot:chat:{chatId}`, billed to the chat's
+ * balance-holder) and seed the newest window from durable; omit it for an
+ * unbound ephemeral room. `messages` seeds only ephemeral rooms. `share: true`
+ * also mints an access code. Returns the room's `reference` (+ `code` when shared).
+ */
+export declare function openRoom(authorization: Credentials | ApiKey, options?: {
+    chatId?: string;
+    messages?: Content[];
+    share?: boolean;
+}): Promise<{
+    reference: string;
+    roomId: string;
+    code?: string;
+}>;
+/** One transcript message on the wire (parts keep file refs as streaming
+ *  `FaunaFile`s). Matches the room's live `chat-message` shape. */
+export type WireMessage = {
+    id: string;
+    position: number;
+    role: Role;
+    parts: any[];
+    author?: Profile;
+    replyTo?: string;
+    model?: string;
+    created: number;
+    /** The name of the API key an agent posted this with, for its author. */
+    via?: string;
+};
+export declare const WireMessage: {
+    /** FILE parts arrive as `{ accessCode | path | ref }` and stream lazily through `FaunaFile`. */
+    fromJSON(json: any, authorization: Credentials | ApiKey, target: ChatTarget): WireMessage;
+};
+/**
+ * Page older room transcript messages, newest first. `cursor` is how many
+ * messages to skip from the newest.
+ */
+export declare function pageMessages(authorization: Credentials | ApiKey, target: ChatTarget, query: {
+    cursor: number;
+    max: number;
+}): Promise<WireMessage[]>;
+/** Result of appending to a live room: either the durable transcript row (when
+ *  the room was idle) or a queued buffer row (when the model was mid-reply). */
+export type AppendResult = {
+    queued: false;
+    id?: string;
+} | {
+    queued: true;
+    queueId?: string;
+};
+/**
+ * Append one message to a live room's single transcript. Any member may append;
+ * USER messages are attributed to the caller and nudge the server's debounced
+ * model reply. If the room is currently replying the server BUFFERS the send
+ * into the shared queue (`{ queued: true, queueId }`); it drains FIFO when the
+ * reply finishes. Otherwise it lands in the transcript (`{ queued: false, id }`).
+ * File parts are already-online Drive refs (path / accessCode); the body is JSON.
+ */
+export declare function appendRoomMessage(authorization: Credentials | ApiKey, target: ChatTarget, message: import("./generative.js").Content, options?: {
+    replyTo?: string;
+    model?: string;
+    reasoning?: string;
+    /** Function schemas (array = available; singular = force that tool). */
+    tools?: Function | Function[];
+}): Promise<AppendResult>;
+/** A file in a chat: one a person attached, or one Parrot opened. */
+export type Attachment = {
+    file: Drive.File;
+    /** The chat it's in and its name in the chat folder, so a file room can let chat members edit it. */
+    chat: string;
+    ref: string;
+    /** Position of the message it came in; unset while the reply attaching it is still being written. */
+    message?: number;
+    author?: Profile;
+    createdAt: Date;
+};
+export declare const Attachment: {
+    fromJSON(json: any, authorization: Credentials | ApiKey): Attachment;
+};
+/** Every file in the chat behind a live room, newest first. */
+export declare function listRoomAttachments(authorization: Credentials | ApiKey, target: ChatTarget): Promise<Attachment[]>;
+/**
+ * Attach a repository to the chat behind a live room, or detach it with null.
+ * The repository must be the chat owner's; only the chat's members may change it.
+ */
+export declare function setRoomRepository(authorization: Credentials | ApiKey, target: ChatTarget, repository: number | null): Promise<void>;
+/**
+ * Remove a queued (buffered) message from a live room. The message was buffered
+ * while the model was mid-reply and never entered the transcript, so this is not
+ * an unsend — the server just drops the queue row and fans it out to every member.
+ */
+export declare function unqueueRoomMessage(authorization: Credentials | ApiKey, target: ChatTarget, queueId: string): Promise<void>;
+/**
+ * Steer a live room: stop the in-progress model reply and have the server
+ * re-answer after the normal debounce window. Any member may steer. `queueId`
+ * releases just that one queued row into the transcript first (per-item steer);
+ * `all` flushes the whole queue in FIFO order (steer-all). Released rows behave
+ * like idle sends — the model does NOT reply immediately.
+ * `stop` cancels the current reply without scheduling a new one.
+ */
+export declare function steerRoom(authorization: Credentials | ApiKey, target: ChatTarget, options?: {
+    queueId?: string;
+    all?: boolean;
+    stop?: boolean;
+    model?: string;
+    reasoning?: string;
+}): Promise<void>;

package/dist/src/parrot/share.js

@@ -0,0 +1,261 @@
+import { Parrot } from "./index.js";
+import * as Drive from "../drive.js";
+export async function moveChatToGroup(credentials, chatId, groupId) {
+    const response = await fetch(`${Parrot.getURL()}/chat/move`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Token ${credentials.token}`
+        },
+        body: JSON.stringify({ chatId, groupId })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+// ─── Ephemeral live rooms (host / seed / page / append / steer) ───────────────
+/**
+ * Host a live room server-side. Pass `chatId` to bind the room to a durable
+ * chat (reference becomes `parrot:chat:{chatId}`, billed to the chat's
+ * balance-holder) and seed the newest window from durable; omit it for an
+ * unbound ephemeral room. `messages` seeds only ephemeral rooms. `share: true`
+ * also mints an access code. Returns the room's `reference` (+ `code` when shared).
+ */
+export async function openRoom(authorization, options = {}) {
+    const messages = options.messages ? await serializeTranscript(options.messages) : undefined;
+    const response = await fetch(`${Parrot.getURL()}/chat/live/open`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+        },
+        body: JSON.stringify({ chatId: options.chatId, messages, share: options.share }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export const WireMessage = {
+    /** FILE parts arrive as `{ accessCode | path | ref }` and stream lazily through `FaunaFile`. */
+    fromJSON(json, authorization, target) {
+        const parts = (json.parts ?? []).map((part) => {
+            if (part.type !== "FILE")
+                return part;
+            const meta = { ...part, name: part.name ?? "file", contentType: part.contentType ?? "application/octet-stream" };
+            if (part.accessCode)
+                return { type: "FILE", file: Drive.File.fromJSON(meta, { authorization, accessCode: part.accessCode }) };
+            if (part.path)
+                return { type: "FILE", file: Drive.File.fromJSON(meta, { authorization, path: part.path, group: part.group }) };
+            if ("code" in target)
+                return { type: "FILE", file: Drive.File.fromJSON(meta, { authorization, accessCode: target.code }) };
+            if (part.ref)
+                return { type: "FILE", file: Drive.File.fromJSON(meta, { authorization, path: part.ref }) };
+            return { type: "FILE", file: Drive.File.fromJSON(meta, { authorization, accessCode: "" }) };
+        });
+        return {
+            id: String(json.id ?? ""),
+            position: Number(json.position ?? 0),
+            role: json.role,
+            parts,
+            author: json.author,
+            replyTo: json.replyTo,
+            model: json.model,
+            created: Number(json.created ?? 0),
+        };
+    },
+};
+/**
+ * Page older room transcript messages, newest first. `cursor` is how many
+ * messages to skip from the newest.
+ */
+export async function pageMessages(authorization, target, query) {
+    const params = new URLSearchParams({ cursor: String(query.cursor), max: String(query.max) });
+    const response = await fetch(`${Parrot.getURL()}/chat/live/messages?${params}`, {
+        method: "GET",
+        headers: {
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return (Array.isArray(json) ? json : []).map((m) => WireMessage.fromJSON(m, authorization, target));
+}
+/**
+ * Append one message to a live room's single transcript. Any member may append;
+ * USER messages are attributed to the caller and nudge the server's debounced
+ * model reply. If the room is currently replying the server BUFFERS the send
+ * into the shared queue (`{ queued: true, queueId }`); it drains FIFO when the
+ * reply finishes. Otherwise it lands in the transcript (`{ queued: false, id }`).
+ * File parts are already-online Drive refs (path / accessCode); the body is JSON.
+ */
+export async function appendRoomMessage(authorization, target, message, options = {}) {
+    const serializedParts = [];
+    for (const part of message.parts) {
+        if (part.type === "FILE") {
+            serializedParts.push(fileRef(part.file));
+        }
+        else {
+            serializedParts.push(part);
+        }
+    }
+    const response = await fetch(`${Parrot.getURL()}/chat/live/append`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+        body: JSON.stringify({
+            role: message.role,
+            parts: serializedParts,
+            replyTo: options.replyTo,
+            model: options.model,
+            reasoning: options.reasoning,
+            ...(options.tools !== undefined ? { tools: options.tools } : {}),
+        }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json().catch(() => ({}));
+    return json;
+}
+export const Attachment = {
+    fromJSON(json, authorization) {
+        const meta = {
+            name: json.name ?? json.ref ?? "file",
+            contentType: json.contentType ?? "application/octet-stream",
+            contentLength: Number(json.contentLength ?? 0),
+        };
+        return {
+            file: Drive.File.fromJSON(meta, { authorization, accessCode: String(json.accessCode ?? "") }),
+            chat: String(json.chat ?? ""),
+            ref: String(json.ref ?? ""),
+            ...(typeof json.message === "number" ? { message: json.message } : {}),
+            ...(json.author ? { author: json.author } : {}),
+            createdAt: new Date(json.created ?? Date.now()),
+        };
+    },
+};
+/** Every file in the chat behind a live room, newest first. */
+export async function listRoomAttachments(authorization, target) {
+    const response = await fetch(`${Parrot.getURL()}/chat/live/attachments`, {
+        method: "GET",
+        headers: {
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    const json = await response.json();
+    return (Array.isArray(json) ? json : []).map((row) => Attachment.fromJSON(row, authorization));
+}
+/**
+ * Attach a repository to the chat behind a live room, or detach it with null.
+ * The repository must be the chat owner's; only the chat's members may change it.
+ */
+export async function setRoomRepository(authorization, target, repository) {
+    const response = await fetch(`${Parrot.getURL()}/chat/repository`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+        body: JSON.stringify({ repository }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+/**
+ * Remove a queued (buffered) message from a live room. The message was buffered
+ * while the model was mid-reply and never entered the transcript, so this is not
+ * an unsend — the server just drops the queue row and fans it out to every member.
+ */
+export async function unqueueRoomMessage(authorization, target, queueId) {
+    const response = await fetch(`${Parrot.getURL()}/chat/live/unqueue`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+        body: JSON.stringify({ queueId }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+/**
+ * Steer a live room: stop the in-progress model reply and have the server
+ * re-answer after the normal debounce window. Any member may steer. `queueId`
+ * releases just that one queued row into the transcript first (per-item steer);
+ * `all` flushes the whole queue in FIFO order (steer-all). Released rows behave
+ * like idle sends — the model does NOT reply immediately.
+ * `stop` cancels the current reply without scheduling a new one.
+ */
+export async function steerRoom(authorization, target, options = {}) {
+    const response = await fetch(`${Parrot.getURL()}/chat/live/steer`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...("code" in target ? { "Access-Code": target.code } : { "Server": target.reference }),
+        },
+        body: JSON.stringify({
+            queueId: options.queueId,
+            all: options.all,
+            stop: options.stop,
+            model: options.model,
+            reasoning: options.reasoning,
+        }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+// ─── serialization helpers (shared by open-seed + page hydration) ─────────────
+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 } : {}),
+    };
+}
+/** Serialize a transcript for the seed body: online FILE parts are path /
+ *  accessCode refs only. Offline files are uploaded to tmp/ first. */
+async function serializeTranscript(messages) {
+    const out = [];
+    for (const message of messages) {
+        const parts = [];
+        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(file.authorization.authorization, dest, file.contentType, bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+                    await file.upload();
+                }
+                parts.push(fileRef(file));
+            }
+            else {
+                parts.push(part);
+            }
+        }
+        out.push({
+            role: message.role,
+            parts,
+            author: message.author,
+            replyTo: message.replyTo,
+            model: message.model,
+        });
+    }
+    return out;
+}

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

@@ -0,0 +1,41 @@
+import { Credentials, ApiKey } from "../authentification.js";
+import type { Group } from "../groups.js";
+import type { Demographic } from "../ant/persona.js";
+import { type Content, type StreamEvent, type TextResponse, type Tool, type VoiceEvent } from "./generative.js";
+/** A Parrot socket URL; `group` adds the Group header (shared memory, group billing). */
+export declare function socketUrl(path: string, authorization: Credentials | ApiKey, group?: Group): string;
+/** FILE parts become path or access code refs (uploading offline files first); no binaries go up. */
+export declare function prepareMessages(authorization: Credentials | ApiKey, messages: Content[]): Promise<unknown[]>;
+/** One generate frame in, one TextResponse (with any files) out. */
+export declare function generateMedia(authorization: Credentials | ApiKey, path: string, model: string, options: {
+    content?: Content[];
+    group?: Group;
+} & Record<string, unknown>, fallbackType: string): Promise<TextResponse>;
+type TextOptions = Partial<{
+    content: Content[];
+    tools: Tool[] | Tool;
+    maxTools: number;
+    memories: number;
+    reasoning: string;
+    group: Group;
+    signal: AbortSignal;
+}>;
+/** Streaming text generation on `path`. A singular Tool forces it; an array lets the model choose. */
+export declare function streamText(authorization: Credentials | ApiKey, path: string, model: string, options?: TextOptions): AsyncGenerator<StreamEvent>;
+/** Buffers a text stream into a TextResponse. */
+export declare function collectText(stream: AsyncGenerator<StreamEvent>): Promise<TextResponse>;
+type VoiceOptions = Partial<{
+    content: Content[];
+    audio: AsyncIterable<Uint8Array>;
+    tools: Tool[] | Tool;
+    maxTools: number;
+    voice: Partial<Demographic>;
+    memories: number;
+    group: Group;
+    signal: AbortSignal;
+}>;
+/** Realtime voice on `path`: PCM16 16 kHz in from `audio`, PCM16 24 kHz out as audio events. */
+export declare function streamVoice(authorization: Credentials | ApiKey, path: string, model: string, options?: VoiceOptions): AsyncGenerator<VoiceEvent>;
+/** Buffers a voice stream: the audio as one PCM file, then the input and output transcripts. */
+export declare function collectVoice(authorization: Credentials | ApiKey, stream: AsyncGenerator<VoiceEvent>): Promise<TextResponse>;
+export {};