fauna-api 0.0.0-stage → 1.0.676

package/dist/src/marmot/workspace.d.ts

@@ -0,0 +1,81 @@
+import { ApiKey, Credentials } from "../authentification.js";
+import { Group } from "../groups.js";
+import { Authorization, Presence, Room, Hooks as ServerHooks } from "../shared/server.js";
+import { ChatRoom, RoomHooks } from "../parrot/room.js";
+import { Scraper } from "./scraper.js";
+export type WorkspaceFile = {
+    name: string;
+    contentType: string;
+    size: number;
+    key: string;
+};
+export type WorkspaceDatasetMeta = {
+    id: string;
+    name: string;
+    schema: unknown;
+    termination: unknown[];
+    contentTypes: string[];
+    proxy: string;
+    documentModes: string[];
+    createdAt: number;
+};
+export type WorkspaceSummary = {
+    id: string;
+    name: string;
+    description: string;
+    createdAt: number;
+    datasets: number;
+    files: number;
+};
+export declare function listWorkspaces(authorization: Credentials | ApiKey, opts?: {
+    group?: Group;
+}): Promise<WorkspaceSummary[]>;
+export declare function createWorkspace(authorization: Credentials | ApiKey, name: string, description?: string, opts?: {
+    group?: Group;
+}): Promise<string>;
+export declare function updateWorkspace(authorization: Credentials | ApiKey, id: string, update: Partial<{
+    name: string;
+    description: string;
+}>, opts?: {
+    group?: Group;
+}): Promise<void>;
+export declare function removeWorkspace(authorization: Credentials | ApiKey, id: string, opts?: {
+    group?: Group;
+}): Promise<void>;
+export declare class WorkspaceRoom extends Room {
+    workspaceId: string;
+    name: string;
+    description: string;
+    files: Map<string, WorkspaceFile>;
+    datasets: Map<string, WorkspaceDatasetMeta>;
+    /** Kept datasets, by dataset id. */
+    scrapers: Map<string, Scraper>;
+    /** The Termite repository whose machine runs the workspace's scrapers, once there is one. */
+    repositoryId: number | null;
+    /** The model the workspace's scraper agent thinks with. */
+    agentText: string;
+    constructor(endpoint: string, ws: WebSocket, authorization: Authorization, id: string);
+    hydrate(state: any): void;
+    handleEvent(packet: any): void;
+    getChat(hooks?: RoomHooks): Promise<{
+        room: ChatRoom;
+        self: Presence;
+        chatId: string;
+    }>;
+    static connect(authorization: Credentials | ApiKey, target: {
+        id: string;
+    }, opts?: {
+        group?: Group;
+        hooks?: ServerHooks;
+        server?: string;
+    }): Promise<{
+        room: WorkspaceRoom;
+        self: Presence;
+    }>;
+    static join(authorization: Credentials | ApiKey, target: {
+        accessCode: string;
+    }, hooks?: ServerHooks): Promise<{
+        room: WorkspaceRoom;
+        self: Presence;
+    }>;
+}

package/dist/src/marmot/workspace.js

@@ -0,0 +1,263 @@
+import { Marmot } from "./index.js";
+import { Room, connect as connectServer } from "../shared/server.js";
+import { connectRoom } from "../parrot/room.js";
+import { Scraper } from "./scraper.js";
+export async function listWorkspaces(authorization, opts) {
+    const response = await fetch(`${Marmot.getURL()}/marmot/workspace/list`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function createWorkspace(authorization, name, description = "", opts) {
+    const response = await fetch(`${Marmot.getURL()}/marmot/workspace/create`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+        body: JSON.stringify({ name, description }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.text();
+}
+export async function updateWorkspace(authorization, id, update, opts) {
+    const response = await fetch(`${Marmot.getURL()}/marmot/workspace/update`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+        body: JSON.stringify({ id, ...update }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export async function removeWorkspace(authorization, id, opts) {
+    const response = await fetch(`${Marmot.getURL()}/marmot/workspace/remove`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: "email" in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        },
+        body: JSON.stringify({ id }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+export class WorkspaceRoom extends Room {
+    constructor(endpoint, ws, authorization, id) {
+        super(endpoint, ws, authorization, id);
+        Object.defineProperty(this, "workspaceId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "description", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "files", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "datasets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Kept datasets, by dataset id. */
+        Object.defineProperty(this, "scrapers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The Termite repository whose machine runs the workspace's scrapers, once there is one. */
+        Object.defineProperty(this, "repositoryId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The model the workspace's scraper agent thinks with. */
+        Object.defineProperty(this, "agentText", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.workspaceId = id;
+        this.name = "";
+        this.description = "";
+        this.files = new Map();
+        this.datasets = new Map();
+        this.scrapers = new Map();
+        this.repositoryId = null;
+        this.agentText = "";
+    }
+    hydrate(state) {
+        this.workspaceId = state?.id ?? this.workspaceId;
+        this.name = state?.name ?? this.name;
+        this.description = state?.description ?? this.description;
+        this.files.clear();
+        for (const f of state?.files ?? []) {
+            if (f?.key)
+                this.files.set(f.key, f);
+        }
+        this.datasets.clear();
+        for (const d of state?.datasets ?? []) {
+            if (d?.id)
+                this.datasets.set(d.id, d);
+        }
+        this.scrapers.clear();
+        for (const s of state?.scrapers ?? []) {
+            if (s?.datasetId)
+                this.scrapers.set(String(s.datasetId), Scraper.fromJSON(s));
+        }
+        this.repositoryId = state?.repositoryId ? Number(state.repositoryId) : null;
+        this.agentText = state?.agentText ?? "";
+    }
+    handleEvent(packet) {
+        switch (packet.event) {
+            case "upsert-file": {
+                const file = packet.file ?? packet.data?.file;
+                if (file?.key)
+                    this.files.set(file.key, file);
+                break;
+            }
+            case "remove-file": {
+                const key = packet.key ?? packet.data?.key;
+                if (key)
+                    this.files.delete(key);
+                break;
+            }
+            case "upsert-dataset": {
+                const dataset = packet.dataset ?? packet.data?.dataset;
+                if (dataset?.id)
+                    this.datasets.set(dataset.id, dataset);
+                break;
+            }
+            case "remove-dataset": {
+                const id = packet.id ?? packet.data?.id;
+                if (id)
+                    this.datasets.delete(id);
+                break;
+            }
+            case "upsert-snapshot":
+            case "remove-snapshot":
+                break;
+            case "upsert-scraper": {
+                const scraper = packet.scraper ?? packet.data?.scraper;
+                if (scraper?.datasetId)
+                    this.scrapers.set(String(scraper.datasetId), Scraper.fromJSON(scraper));
+                break;
+            }
+            case "remove-scraper": {
+                const datasetId = packet.datasetId ?? packet.data?.datasetId;
+                if (datasetId)
+                    this.scrapers.delete(String(datasetId));
+                break;
+            }
+            case "update-workspace": {
+                const workspace = packet.workspace ?? packet.data?.workspace;
+                if (workspace?.name)
+                    this.name = workspace.name;
+                if (workspace?.description !== undefined)
+                    this.description = workspace.description;
+                if (workspace?.repositoryId !== undefined)
+                    this.repositoryId = workspace.repositoryId ? Number(workspace.repositoryId) : null;
+                if (workspace?.agentText !== undefined)
+                    this.agentText = workspace.agentText;
+                break;
+            }
+        }
+    }
+    async getChat(hooks) {
+        const auth = this.authorization;
+        const response = await fetch(`${Marmot.getURL()}/marmot/workspace/chat/ensure`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: "email" in auth.authorization ? `Token ${auth.authorization.token}` : `ApiKey ${auth.authorization.id}`,
+                ...("accessCode" in auth
+                    ? { "Access-Code": auth.accessCode }
+                    : { Server: this.workspaceId, ...(auth.group ? { Group: auth.group } : {}) }),
+            },
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        const { chatId, reference, code } = await response.json();
+        if (!chatId || !code)
+            throw new Error("Invalid ensure response.");
+        const guest = "accessCode" in this.authorization;
+        const target = guest
+            ? { code }
+            : { reference: reference || `parrot:chat:${chatId}` };
+        const { room, self } = await connectRoom(this.authorization.authorization, target, hooks ?? {});
+        return { room, self, chatId };
+    }
+    static async connect(authorization, target, opts) {
+        const server = opts?.server ?? target.id;
+        let room;
+        const user = opts?.hooks ?? {};
+        const self = await connectServer({ authorization, server, ...(opts?.group ? { group: opts.group.id } : {}) }, `${Marmot.getURL()}/marmot/workspace`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new WorkspaceRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyWorkspaceEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+    static async join(authorization, target, hooks) {
+        let room;
+        const user = hooks ?? {};
+        const self = await connectServer({ authorization, accessCode: target.accessCode }, `${Marmot.getURL()}/marmot/workspace`, {
+            ...user,
+            createRoom: (endpoint, ws, a, id, state) => {
+                room = (user.createRoom?.(endpoint, ws, a, id, state)
+                    ?? new WorkspaceRoom(endpoint, ws, a, id));
+                return room;
+            },
+            onConnection: (r, state) => {
+                r.hydrate(state);
+                user.onConnection?.(r, state);
+            },
+            onEvent: (r, packet) => applyWorkspaceEvent(r, packet, user),
+        });
+        return { room, self };
+    }
+}
+function applyWorkspaceEvent(room, packet, user) {
+    room.handleEvent(packet);
+    return user.onEvent?.(room, packet) ?? true;
+}

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

@@ -0,0 +1,53 @@
+import { Credentials, ApiKey } from "../authentification.js";
+import { Group } from "../groups.js";
+import type { Text, Voice, Image, Video, Content, Tool, StreamEvent, VoiceEvent, TextResponse, Demographic } from "./generative.js";
+export type Memory = {
+    id: number;
+    memory: string;
+    scope: string;
+    embedding: number[];
+};
+export type Memories = {
+    nodes: Memory[];
+    edges: [number, number][];
+    scopes: string[];
+};
+export declare function observe(authorization: Credentials | ApiKey, content: string, group?: Group): Promise<Memory>;
+export declare function recall(authorization: Credentials | ApiKey, query: string, scope?: string, group?: Group): Promise<Memory[]>;
+export declare function exportMemory(authorization: Credentials | ApiKey, group?: Group): Promise<Memories>;
+export declare function removeMemory(authorization: Credentials | ApiKey, id: number, group?: Group): Promise<void>;
+export declare function clearMemory(authorization: Credentials | ApiKey, group?: Group): Promise<void>;
+export declare function generateText(authorization: Credentials | ApiKey, model: Text, options?: Partial<{
+    content: Content[];
+    tools: Tool[] | Tool;
+    maxTools: number;
+    memories: number;
+    reasoning: string;
+    group: Group;
+    signal: AbortSignal;
+}>): AsyncGenerator<StreamEvent>;
+export declare function generateTextSync(authorization: Credentials | ApiKey, model: Text, options?: Parameters<typeof generateText>[2]): Promise<TextResponse>;
+export declare function generateVoice(authorization: Credentials | ApiKey, model: Voice, options?: Partial<{
+    content: Content[];
+    audio: AsyncIterable<Uint8Array>;
+    tools: Tool[] | Tool;
+    maxTools: number;
+    voice: Partial<Demographic>;
+    memories: number;
+    group: Group;
+    signal: AbortSignal;
+}>): AsyncGenerator<VoiceEvent>;
+export declare function generateVoiceSync(authorization: Credentials | ApiKey, model: Voice, options?: Parameters<typeof generateVoice>[2]): Promise<TextResponse>;
+export declare function generateImage(authorization: Credentials | ApiKey, model: Image, options?: Partial<{
+    content: Content[];
+    size: [number, number];
+    memories: number;
+    group: Group;
+}>): Promise<TextResponse>;
+export declare function generateVideo(authorization: Credentials | ApiKey, model: Video, options?: Partial<{
+    content: Content[];
+    duration: number;
+    size: [number, number];
+    memories: number;
+    group: Group;
+}>): Promise<TextResponse>;

package/dist/src/parrot/agent.js

@@ -0,0 +1,93 @@
+import { Parrot } from "./index.js";
+import { collectText, collectVoice, generateMedia, streamText, streamVoice } from "./socket.js";
+// Observe — store a new memory. Pass `group` to act on that group's shared
+// memory graph instead of the caller's personal one (caller must be a member).
+export async function observe(authorization, content, group) {
+    const response = await fetch(`${Parrot.getURL()}/agent/memories`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ content })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+// Recall — query associative memory. Pass `group` for that group's shared graph.
+export async function recall(authorization, query, scope, group) {
+    const response = await fetch(`${Parrot.getURL()}/agent/recall`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        },
+        body: JSON.stringify({ query, scope })
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+// Export — get full memory graph. Pass `group` for that group's shared graph.
+export async function exportMemory(authorization, group) {
+    const response = await fetch(`${Parrot.getURL()}/agent/memories`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+// Remove — delete a specific memory node. Pass `group` for that group's graph.
+export async function removeMemory(authorization, id, group) {
+    const response = await fetch(`${Parrot.getURL()}/agent/memories/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+// Clear — wipe entire memory graph. Pass `group` for that group's graph.
+export async function clearMemory(authorization, group) {
+    const response = await fetch(`${Parrot.getURL()}/agent/memories`, {
+        method: "DELETE",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(group ? { "Group": group.id } : {})
+        }
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+}
+// Agent generation: each mirrors its Generative function, plus `memories` (how
+// many to recall on the latest request) and `group` (whose memory graph). Where
+// the model can call tools it can also save memories with observe_memory.
+// Streaming text generation. A singular Tool forces it; an array lets the model choose.
+export async function* generateText(authorization, model, options) {
+    yield* streamText(authorization, '/agent/text', model, options);
+}
+export async function generateTextSync(authorization, model, options) {
+    return collectText(generateText(authorization, model, options));
+}
+// Realtime voice: PCM16 16 kHz in from `audio`, PCM16 24 kHz out as audio events.
+export async function* generateVoice(authorization, model, options) {
+    yield* streamVoice(authorization, '/agent/voice', model, options);
+}
+export async function generateVoiceSync(authorization, model, options) {
+    return collectVoice(authorization, generateVoice(authorization, model, options));
+}
+export async function generateImage(authorization, model, options = {}) {
+    return generateMedia(authorization, '/agent/image', model, options, 'image/png');
+}
+export async function generateVideo(authorization, model, options = {}) {
+    return generateMedia(authorization, '/agent/video', model, options, 'video/mp4');
+}

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

@@ -0,0 +1,84 @@
+import { Parrot } from "./index.js";
+import { Content } from "./generative.js";
+import { Credentials, ApiKey, Profile } from "../authentification.js";
+import { Group } from "../groups.js";
+import { ChatRoom, RoomHooks } from "./room.js";
+import { Presence } from "../shared/server.js";
+import type { Repository } from "../termite/versioning.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 declare function openChat(authorization: Credentials | ApiKey, options?: {
+    chatId?: string;
+    messages?: Content[];
+    share?: boolean;
+    hooks?: RoomHooks;
+}): Promise<{
+    room: ChatRoom;
+    self: Presence;
+    reference: string;
+    code?: string;
+}>;
+/**
+ * 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 declare function createChat(authorization: Credentials | ApiKey, name?: string, group?: Group, options?: {
+    human?: boolean;
+    systemPrompt?: string;
+    locked?: boolean;
+    repository?: Repository;
+}): Promise<string>;
+export declare function deleteChat(authorization: Credentials | ApiKey, id: string, group?: Group): Promise<void>;
+export type LastMessage = {
+    parts: unknown[];
+    role: string;
+    createdAt: Date;
+    position: number;
+    author?: Profile;
+    model?: string;
+};
+export declare const LastMessage: {
+    fromJSON(json: unknown): LastMessage | null;
+};
+export type ChatSummary = {
+    id: string;
+    name: string;
+    principalId: string;
+    /** People only: sends never start a model reply. */
+    human: boolean;
+    /** Only whoever made it can delete it or move it. */
+    locked: boolean;
+    /** The repository Parrot works in, by id. */
+    repository: number | null;
+    created: number;
+    updated: number;
+    last: LastMessage | null;
+    /** Messages the caller hasn't read. A person and each of their API keys keep
+     *  their own place; one that never marked the chat sees only its newest 20. */
+    unread: number;
+};
+export declare function listChats(authorization: Credentials | ApiKey, group?: Group): Promise<ChatSummary[]>;
+export declare function renameChat(authorization: Credentials | ApiKey, id: string, name: string, group?: Group): Promise<void>;
+/**
+ * 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 declare function markRead(authorization: Credentials | ApiKey, id: string, position?: number, group?: Group): Promise<number>;
+/** One page of a chat, newest first. */
+export declare function readChat(authorization: Credentials | ApiKey, id: string, group: Group | undefined, query: {
+    cursor: number;
+    max: number;
+}): Promise<Content[]>;
+export declare function writeChat(authorization: Credentials | ApiKey, id: string, messages: Content[], group?: Group): Promise<void>;