fauna-api 0.0.0-stage → 1.0.676

package/dist/src/ant/persona.d.ts

@@ -0,0 +1,151 @@
+import { ApiKey, Credentials } from "../authentification.js";
+import { Group } from "../groups.js";
+export declare enum Sex {
+    MALE = "MALE",
+    FEMALE = "FEMALE"
+}
+export declare enum Race {
+    WHITE = "WHITE",
+    BLACK = "BLACK",
+    NATIVE_AMERICAN = "NATIVE_AMERICAN",
+    ALASKAN_NATIVE = "ALASKAN_NATIVE",
+    HAWAIIAN = "HAWAIIAN",
+    ASIAN = "ASIAN",
+    PACIFIC_ISLANDER = "PACIFIC_ISLANDER",
+    HISPANIC = "HISPANIC"
+}
+export declare enum Ethnicity {
+    ITALIAN = "ITALIAN",
+    IRISH = "IRISH",
+    GERMAN = "GERMAN",
+    FRENCH = "FRENCH",
+    SPANISH = "SPANISH",
+    PORTUGUESE = "PORTUGUESE",
+    POLISH = "POLISH",
+    SCOTTISH = "SCOTTISH",
+    NORWEGIAN = "NORWEGIAN",
+    DANISH = "DANISH",
+    SWEDISH = "SWEDISH",
+    FINNISH = "FINNISH",
+    ICELANDIC = "ICELANDIC",
+    DUTCH = "DUTCH",
+    UKRAINIAN = "UKRAINIAN",
+    MEXICAN = "MEXICAN",
+    JEWISH = "JEWISH",
+    KOREAN = "KOREAN",
+    CHINESE = "CHINESE",
+    JAPANESE = "JAPANESE",
+    FILIPINO = "FILIPINO",
+    VIETNAMESE = "VIETNAMESE",
+    INDIAN = "INDIAN",
+    TAMIL = "TAMIL",
+    PERSIAN = "PERSIAN",
+    ARAB = "ARAB",
+    ARMENIAN = "ARMENIAN",
+    RUSSIAN = "RUSSIAN",
+    GREEK = "GREEK",
+    BRAZILIAN = "BRAZILIAN",
+    PUERTO_RICAN = "PUERTO_RICAN",
+    HAITIAN = "HAITIAN"
+}
+export declare enum Religion {
+    CHRISTIAN = "CHRISTIAN",
+    JEWISH = "JEWISH",
+    MUSLIM = "MUSLIM",
+    HINDU = "HINDU",
+    BUDDHIST = "BUDDHIST",
+    SIKH = "SIKH",
+    SPIRITUAL = "SPIRITUAL",
+    AGNOSTIC = "AGNOSTIC",
+    ATHEIST = "ATHEIST",
+    NONE = "NONE"
+}
+export declare enum MaritalStatus {
+    MARRIED = "MARRIED",
+    SEPERATED = "SEPERATED",
+    DIVORCED = "DIVORCED",
+    WIDOWED = "WIDOWED",
+    NEVER_MARRIED = "NEVER_MARRIED"
+}
+export declare enum Education {
+    DOCTORAL = "DOCTORAL",
+    PROFESSIONAL = "PROFESSIONAL",
+    MASTER = "MASTER",
+    BACHELOR = "BACHELOR",
+    ASSOCIATE = "ASSOCIATE",
+    SOME_COLLEGE = "SOME_COLLEGE",
+    HIGHSCHOOL = "HIGH_SCHOOL",
+    NONE = "NONE"
+}
+export type Demographic = {
+    age: number;
+    sex: Sex;
+    race: Race;
+    ethnicity: Ethnicity[];
+    religion: Religion;
+    birthplace: [number, number];
+    location: [number, number];
+    marital: MaritalStatus;
+    education: Education;
+    occupation: string;
+    income: number;
+};
+export type Identity = {
+    id: string;
+    demographic: Demographic;
+    background: string;
+    dialect: string;
+};
+export declare function all(authorization: Credentials | ApiKey, opts?: {
+    group?: Group;
+}): Promise<string[]>;
+export declare function get(authorization: Credentials | ApiKey, id: string, opts?: {
+    group?: Group;
+}): Promise<Identity>;
+export type DemographicQuery = Partial<{
+    age: number;
+    sex: Sex;
+    race: Race | Race[];
+    location: [number, number];
+    occupation: string;
+    income: number;
+    interests: string[];
+}>;
+export type DemographicFilters = {
+    sex?: string[];
+    race?: string[];
+    age?: {
+        min: number;
+        max: number;
+    };
+    income?: {
+        min: number;
+        max: number;
+    };
+    occupation?: string;
+};
+/** Catalog browse (filters plus cursor and max) or weighted seed (slices, where max is the sample size). */
+export declare function queryPersonas(authorization: Credentials | ApiKey, opts: {
+    cursor: number;
+    max: number;
+    filters?: DemographicFilters;
+    slices?: {
+        weight: number;
+        demographic: DemographicQuery;
+    }[];
+    group?: Group;
+}): Promise<Identity[]>;
+export type PriorReason = "hnsw" | "occupation" | "demo";
+export type PriorEdge = {
+    to: string;
+    weight: number;
+    reasons: PriorReason[];
+};
+export type Prior = {
+    embedder: string;
+    k: number;
+    edges: PriorEdge[];
+};
+export declare function prior(authorization: Credentials | ApiKey, id: string, opts?: {
+    group?: Group;
+}): Promise<Prior>;

package/dist/src/ant/persona.js

@@ -0,0 +1,136 @@
+import { Ant } from "./index.js";
+export var Sex;
+(function (Sex) {
+    Sex["MALE"] = "MALE";
+    Sex["FEMALE"] = "FEMALE";
+})(Sex || (Sex = {}));
+export var Race;
+(function (Race) {
+    Race["WHITE"] = "WHITE";
+    Race["BLACK"] = "BLACK";
+    Race["NATIVE_AMERICAN"] = "NATIVE_AMERICAN";
+    Race["ALASKAN_NATIVE"] = "ALASKAN_NATIVE";
+    Race["HAWAIIAN"] = "HAWAIIAN";
+    Race["ASIAN"] = "ASIAN";
+    Race["PACIFIC_ISLANDER"] = "PACIFIC_ISLANDER";
+    Race["HISPANIC"] = "HISPANIC";
+})(Race || (Race = {}));
+export var Ethnicity;
+(function (Ethnicity) {
+    Ethnicity["ITALIAN"] = "ITALIAN";
+    Ethnicity["IRISH"] = "IRISH";
+    Ethnicity["GERMAN"] = "GERMAN";
+    Ethnicity["FRENCH"] = "FRENCH";
+    Ethnicity["SPANISH"] = "SPANISH";
+    Ethnicity["PORTUGUESE"] = "PORTUGUESE";
+    Ethnicity["POLISH"] = "POLISH";
+    Ethnicity["SCOTTISH"] = "SCOTTISH";
+    Ethnicity["NORWEGIAN"] = "NORWEGIAN";
+    Ethnicity["DANISH"] = "DANISH";
+    Ethnicity["SWEDISH"] = "SWEDISH";
+    Ethnicity["FINNISH"] = "FINNISH";
+    Ethnicity["ICELANDIC"] = "ICELANDIC";
+    Ethnicity["DUTCH"] = "DUTCH";
+    Ethnicity["UKRAINIAN"] = "UKRAINIAN";
+    Ethnicity["MEXICAN"] = "MEXICAN";
+    Ethnicity["JEWISH"] = "JEWISH";
+    Ethnicity["KOREAN"] = "KOREAN";
+    Ethnicity["CHINESE"] = "CHINESE";
+    Ethnicity["JAPANESE"] = "JAPANESE";
+    Ethnicity["FILIPINO"] = "FILIPINO";
+    Ethnicity["VIETNAMESE"] = "VIETNAMESE";
+    Ethnicity["INDIAN"] = "INDIAN";
+    Ethnicity["TAMIL"] = "TAMIL";
+    Ethnicity["PERSIAN"] = "PERSIAN";
+    Ethnicity["ARAB"] = "ARAB";
+    Ethnicity["ARMENIAN"] = "ARMENIAN";
+    Ethnicity["RUSSIAN"] = "RUSSIAN";
+    Ethnicity["GREEK"] = "GREEK";
+    Ethnicity["BRAZILIAN"] = "BRAZILIAN";
+    Ethnicity["PUERTO_RICAN"] = "PUERTO_RICAN";
+    Ethnicity["HAITIAN"] = "HAITIAN";
+})(Ethnicity || (Ethnicity = {}));
+export var Religion;
+(function (Religion) {
+    Religion["CHRISTIAN"] = "CHRISTIAN";
+    Religion["JEWISH"] = "JEWISH";
+    Religion["MUSLIM"] = "MUSLIM";
+    Religion["HINDU"] = "HINDU";
+    Religion["BUDDHIST"] = "BUDDHIST";
+    Religion["SIKH"] = "SIKH";
+    Religion["SPIRITUAL"] = "SPIRITUAL";
+    Religion["AGNOSTIC"] = "AGNOSTIC";
+    Religion["ATHEIST"] = "ATHEIST";
+    Religion["NONE"] = "NONE";
+})(Religion || (Religion = {}));
+export var MaritalStatus;
+(function (MaritalStatus) {
+    MaritalStatus["MARRIED"] = "MARRIED";
+    MaritalStatus["SEPERATED"] = "SEPERATED";
+    MaritalStatus["DIVORCED"] = "DIVORCED";
+    MaritalStatus["WIDOWED"] = "WIDOWED";
+    MaritalStatus["NEVER_MARRIED"] = "NEVER_MARRIED";
+})(MaritalStatus || (MaritalStatus = {}));
+export var Education;
+(function (Education) {
+    Education["DOCTORAL"] = "DOCTORAL";
+    Education["PROFESSIONAL"] = "PROFESSIONAL";
+    Education["MASTER"] = "MASTER";
+    Education["BACHELOR"] = "BACHELOR";
+    Education["ASSOCIATE"] = "ASSOCIATE";
+    Education["SOME_COLLEGE"] = "SOME_COLLEGE";
+    Education["HIGHSCHOOL"] = "HIGH_SCHOOL";
+    Education["NONE"] = "NONE";
+})(Education || (Education = {}));
+export async function all(authorization, opts) {
+    const response = await fetch(`${Ant.getURL()}/personas`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        }
+    });
+    return await response.json();
+}
+export async function get(authorization, id, opts) {
+    const response = await fetch(`${Ant.getURL()}/personas/${encodeURIComponent(id)}`, {
+        method: "GET",
+        headers: {
+            "Authorization": 'email' in authorization ? `Token ${authorization.token}` : `ApiKey ${authorization.id}`,
+            ...(opts?.group ? { Group: opts.group.id } : {}),
+        }
+    });
+    return await response.json();
+}
+/** Catalog browse (filters plus cursor and max) or weighted seed (slices, where max is the sample size). */
+export async function queryPersonas(authorization, opts) {
+    const response = await fetch(`${Ant.getURL()}/persona/query`, {
+        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({
+            cursor: opts.cursor,
+            max: opts.max,
+            ...(opts.filters ? { filters: opts.filters } : {}),
+            ...(opts.slices ? { slices: opts.slices } : {}),
+        }),
+    });
+    if (!response.ok)
+        throw new Error(await response.text());
+    return await response.json();
+}
+export async function prior(authorization, id, opts) {
+    const response = await fetch(`${Ant.getURL()}/persona/prior/${encodeURIComponent(id)}`, {
+        method: "GET",
+        headers: {
+            "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();
+}

package/dist/src/ant/timeline.d.ts

@@ -0,0 +1,283 @@
+import { Identity } from "./persona.js";
+import { Format } from "../parrot/format.js";
+import { GraphEdge, GraphNode, type Stimuli } from "./graph.js";
+export { GraphNode, StartNode, TextNode, WebsiteNode, FileNode, XNode, LinkedInNode, GraphEdge, type Stimuli, type GraphNodeWire, } from "./graph.js";
+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 { StreamEvent, type Content, type Tool } from "../parrot/generative.js";
+import * as Drive from "../drive.js";
+import { Memory } from "../parrot/agent.js";
+import type { Repository } from "../termite/versioning.js";
+export declare function listTimelines(authorization: Credentials | ApiKey, opts?: {
+    group?: Group;
+}): Promise<{
+    name: string;
+    id: string;
+}[]>;
+/** Create a timeline. `repository` (the owner's) is the computer its personas start from. */
+export declare function createTimeline(authorization: Credentials | ApiKey, name: string, opts?: {
+    group?: Group;
+    audience?: string[];
+    repository?: Repository;
+}): Promise<{
+    name: string;
+    id: string;
+}>;
+export declare function deleteTimeline(authorization: Credentials | ApiKey, id: string, opts?: {
+    group?: Group;
+}): Promise<void>;
+export declare function renameTimeline(authorization: Credentials | ApiKey, id: string, name: string, opts?: {
+    group?: Group;
+}): Promise<void>;
+export declare function getTrust(authorization: Credentials | ApiKey, timelineId: string, opts?: {
+    group?: Group;
+    accessCode?: string;
+}): Promise<{
+    edges: {
+        from: string;
+        to: string;
+        weight: number;
+        updatedAt?: number;
+    }[];
+}>;
+export type TrustEdge = {
+    from: string;
+    to: string;
+    weight: number;
+    updatedAt?: number;
+};
+type FileAccessCodeMeta = {
+    code: string;
+    name: string;
+    contentType: string;
+};
+export declare class Poll {
+    readonly id: string;
+    goal: string;
+    query: Format<any>[];
+    results: unknown;
+    constructor(id: string, goal: string, query: Format<any>[], results?: unknown);
+    static fromJSON(json: any): Poll;
+    toJSON(): {
+        id: string;
+        goal: string;
+        query: any[];
+        results: unknown;
+    };
+}
+export declare class Run {
+    readonly id: string;
+    pollId: string;
+    iteration: number;
+    status: "QUEUED" | "RUNNING" | "DONE" | "ABORTED" | "FAILED";
+    trajectories: {
+        id: string;
+        nodes: {
+            id: string;
+            kind: string;
+            title: string;
+        }[];
+        reflections?: {
+            agentId: string;
+            text: string;
+            to?: string;
+            error?: string;
+        }[];
+        thread?: {
+            post: string;
+            comments: {
+                agentId: string;
+                text: string;
+                to?: string;
+                error?: string;
+            }[];
+        };
+        forwards?: {
+            agentId: string;
+            text: string;
+            to?: string;
+            error?: string;
+        }[];
+    }[];
+    polls?: unknown;
+    progress?: {
+        activeNodeIds: string[];
+        activeEdgeIds: string[];
+        clusterHits: Record<string, number>;
+        clusterRequired: Record<string, number>;
+        byStimulus: Record<string, {
+            stimulusLabel: string;
+            phase: "browse" | "reflect" | "discuss" | "forward" | "answer";
+            done: number;
+            total: number;
+            browsers?: Record<string, {
+                url: string;
+                reference: string;
+                code: string;
+            }>;
+            feed?: {
+                id: string;
+                agentId: string;
+                text: string;
+            }[];
+        }>;
+    };
+    agentIds: string[];
+    reach?: Record<string, string[]>;
+    startedAt: number;
+    finishedAt?: number;
+    error?: string;
+    constructor(wire: any);
+}
+export declare function runIsActive(status: Run["status"] | string | undefined): boolean;
+export declare class Agent {
+    readonly parent: TimelineRoom;
+    readonly id: string;
+    persona: Identity;
+    /** A repository picked in this agent's own chat, used directly; null when it follows the timeline's. */
+    repository: number | null;
+    constructor(parent: TimelineRoom, id: string, persona: Identity, repository?: number | null);
+    static fromJSON(json: any, parent: TimelineRoom): Agent;
+    /** Pick a repository for this agent's chats (used directly), or null to follow the timeline's again. */
+    setRepository(repository: Repository | null): void;
+    /** Lazily mint/open this agent's Parrot ChatRoom. */
+    getChat(hooks?: RoomHooks): Promise<{
+        room: ChatRoom;
+        self: Presence;
+        chatId: string;
+    }>;
+    observe(content: string): Promise<Memory>;
+    /** Stream a reply as this agent, under the room's own authorization. `tools` answer the persona's calls to them. */
+    generate(messages: Content[], opts?: {
+        signal?: AbortSignal;
+        tools?: Tool[];
+    }): AsyncGenerator<StreamEvent>;
+    toJSON(): {
+        id: string;
+        persona: Identity;
+    };
+}
+export declare class TimelineRoom extends Room {
+    /** Client-facing timeline id within the current principal. */
+    timelineId: string;
+    name: string;
+    agents: Map<string, Agent>;
+    polls: Map<string, Poll>;
+    runs: Map<string, Run>;
+    nodes: Map<string, GraphNode>;
+    edges: Map<string, GraphEdge>;
+    /** Short-lived Drive codes for file nodes (hydrate + upload + remint). */
+    fileAccessCodes: Map<string, FileAccessCodeMeta>;
+    trustEdges: Map<string, TrustEdge>;
+    status: string;
+    /** Set when the timeline is deleted while this room is open. */
+    removed: boolean;
+    /** The owner's Termite repository personas start from, by id; null when it has none. */
+    repository: number | null;
+    /** Who owns the timeline: `credentials:{id}` or `group:{id}`. */
+    owner: string;
+    private readonly repositoryWatchers;
+    constructor(endpoint: string, ws: WebSocket, authorization: Authorization, id: string);
+    /** The group that owns the timeline, whose repositories it takes; undefined for a person's. */
+    get group(): Group | undefined;
+    /** Attach one of the owner's repositories, or null to detach. Personas' chat forks of the old one are deleted. */
+    setRepository(repository: Repository | null): Promise<void>;
+    /** Hear about every repository change, from anyone in the room. Returns a function that stops listening. */
+    watchRepository(listener: (repository: number | null) => void): () => void;
+    private applyRepository;
+    /**
+     * The trust graph a run ended with: the timeline's graph as the run started,
+     * plus everything it changed. `trustEdges` is the graph every run starts from.
+     */
+    runTrust(runId: string): Promise<TrustEdge[]>;
+    hydrate(state: any): void;
+    private attachDriveFile;
+    handleEvent(packet: any): void | Promise<void>;
+    upsertGraphNode(node: GraphNode): GraphNode;
+    removeGraphNode(id: string): void;
+    upsertGraphEdge(edge: GraphEdge): GraphEdge;
+    removeGraphEdge(id: string): void;
+    /** Upload bytes to the host drive and create/update a durable file node. */
+    uploadFileNode(file: Blob | ArrayBuffer | Uint8Array, opts: {
+        name: string;
+        contentType?: string;
+        x: number;
+        y: number;
+        nodeId?: string;
+        kind?: Stimuli;
+    }): Promise<{
+        node: GraphNode;
+        accessCode: FileAccessCodeMeta;
+    }>;
+    remintFileAccessCode(nodeId: string): Promise<FileAccessCodeMeta>;
+    /** Build a Drive.File handle for a graph file node (remints if needed). */
+    fileForNode(nodeId: string): Promise<Drive.File>;
+    /** Remint if needed and return the short-lived Drive access code for a file node.
+     *  Viewer URL opening stays in the app layer (avoids importing Fauna into ant/). */
+    openGraphFile(nodeId: string): Promise<FileAccessCodeMeta>;
+    upsertAgent(identity: Identity): Agent;
+    removeAgent(id: string): void;
+    upsertPoll(goal: string, query: Format<any>[]): Poll;
+    removePoll(id: string): void;
+    /** Create the poll and queue its run in one request. Resolves the run id;
+     *  the run itself arrives through the room's `upsert-run` delta. */
+    startRun(goal: string, query: Format<any>[]): Promise<string>;
+    abortRun(runId: string): Promise<void>;
+    /** Lazily mint/open the architect Parrot ChatRoom. */
+    getChat(hooks?: RoomHooks): Promise<{
+        room: ChatRoom;
+        self: Presence;
+        chatId: string;
+    }>;
+    /**
+     * Ensure a Parrot chat (architect when `agentId` is empty) and connect live.
+     * Timeline members join by reference (non-guest); access-code guests use the
+     * short-lived code so leave/reap semantics stay correct.
+     */
+    openChat(agentId: string, hooks?: RoomHooks): Promise<{
+        room: ChatRoom;
+        self: Presence;
+        chatId: string;
+    }>;
+    /**
+     * Connect to an owned timeline.
+     * Principal is resolved server-side from auth (+ optional Group).
+     * `Server` carries only the timeline id for own/group; grant joins may
+     * pass a full `principalId:timelineId` via opts.server when needed.
+     */
+    static connect(authorization: Credentials | ApiKey, target: {
+        id: string;
+    }, opts?: {
+        group?: Group;
+        hooks?: ServerHooks;
+        server?: string;
+    }): Promise<{
+        room: TimelineRoom;
+        self: Presence;
+    }>;
+    static join(authorization: Credentials | ApiKey, target: {
+        accessCode: string;
+    }, hooks?: ServerHooks): Promise<{
+        room: TimelineRoom;
+        self: Presence;
+    }>;
+}
+/** Write a standalone fact onto this agent's Parrot graph (`ant/timelines/…/memory`). */
+export declare function observeAgent(authorization: Credentials | ApiKey, timelineId: string, agentId: string, content: string, opts?: {
+    group?: Group;
+    accessCode?: string;
+}): Promise<Memory>;
+/**
+ * Stream a persona reply for one agent (Gemini Flash + medium thinking + memories).
+ * Parrot-compatible StreamEvents for UI.Chat generate mode, plus `tool` and
+ * `tool-result` events for the persona's own tools. `tools` are answered here
+ * when the persona calls them, like `use_desktop` asking for a computer.
+ */
+export declare function generateAgent(authorization: Credentials | ApiKey, timelineId: string, agentId: string, messages: Content[], opts?: {
+    group?: Group;
+    accessCode?: string;
+    signal?: AbortSignal;
+    tools?: Tool[];
+}): AsyncGenerator<StreamEvent>;