fauna-api 0.0.0-stage → 1.0.679

package/dist/src/parrot/format.js

@@ -0,0 +1,639 @@
+import { generateEmbedding, generateTextSync } from "./generative.js";
+export class Format {
+    constructor(instruction, tool) {
+        Object.defineProperty(this, "instruction", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "tool", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "response", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: undefined
+        });
+        this.instruction = instruction;
+        this.tool = tool;
+    }
+    answer(response) {
+        this.response = response;
+    }
+    async llm(authorization, model, options = {}) {
+        const prompt = this.instruction + (this.tool.instruction ? '\n' + this.tool.instruction({}) : '');
+        const response = await generateTextSync(authorization, model, { content: (options.content ?? []) });
+        response.content.parts.push({
+            type: 'TEXT',
+            text: prompt
+        });
+        const invocations = response.content.parts.filter((part) => part.type === 'INVOCATION');
+        if (invocations.length > 0) {
+            this.answer(JSON.parse(await this.tool.evaluate(invocations[0].args)));
+        }
+        return response;
+    }
+    getResponse() {
+        return this.response;
+    }
+    static optional(format) {
+        const clone = format.clone();
+        const original = { ...clone.tool };
+        const { required, ...rest } = clone.tool.function.parameters;
+        clone.tool.function.parameters = rest;
+        clone.tool.instruction = (params) => {
+            return format.tool.instruction(params) + ' This is optional. If you would opt out of answering, you may skip the parameters.';
+        };
+        clone.tool.evaluate = async (params) => {
+            if (!params) {
+                return JSON.stringify(null);
+            }
+            try {
+                const response = await original.evaluate(params);
+                return response ?? JSON.stringify(null);
+            }
+            catch (err) {
+                return JSON.stringify(null);
+            }
+        };
+        return clone;
+    }
+    static calculateDistance(a, b) {
+        switch (true) {
+            case a instanceof NumericalFormat && b instanceof NumericalFormat: {
+                return NumericalFormat.distance(a, b);
+            }
+            case a instanceof VectorFormat && b instanceof VectorFormat: {
+                return VectorFormat.distance(a, b);
+            }
+            case a instanceof CategoricalFormat && b instanceof CategoricalFormat: {
+                return CategoricalFormat.distance(a, b);
+            }
+            case a instanceof SelectionFormat && b instanceof SelectionFormat: {
+                return SelectionFormat.distance(a, b);
+            }
+            case a instanceof UtteranceFormat && b instanceof UtteranceFormat: {
+                return UtteranceFormat.distance(a, b);
+            }
+        }
+        throw new Error(`Invalid format type: ${a.constructor.name} and ${b.constructor.name}`);
+    }
+    // Serialization
+    static fromJSON(json) {
+        var format = undefined;
+        switch (json.type) {
+            case 'numerical': {
+                format = new NumericalFormat(json.instruction, json.bounds);
+                break;
+            }
+            case 'vector': {
+                format = new VectorFormat(json.instruction, json.dimension, json.bounds);
+                break;
+            }
+            case 'categorical': {
+                format = new CategoricalFormat(json.instruction, json.categories);
+                break;
+            }
+            case 'selection': {
+                format = new SelectionFormat(json.instruction, json.options);
+                break;
+            }
+            case 'utterance': {
+                format = new UtteranceFormat(json.instruction, json.time);
+                break;
+            }
+        }
+        if (format) {
+            format.answer(json.answer);
+            return format;
+        }
+        throw new Error(`Invalid format type: ${json.type} for format:\n${JSON.stringify(json)}`);
+    }
+}
+export class NumericalFormat extends Format {
+    constructor(instruction, bounds) {
+        super(instruction, NumericalFormat.tool());
+        Object.defineProperty(this, "bounds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.bounds = bounds;
+    }
+    clone() {
+        return new NumericalFormat(this.instruction, this.bounds);
+    }
+    getResponse() {
+        if (this.bounds != undefined && this.response != undefined) {
+            var formattedResponse = this.response;
+            if (this.bounds[0] != undefined && formattedResponse < this.bounds[0]) {
+                formattedResponse = this.bounds[0];
+            }
+            if (this.bounds[1] != undefined && formattedResponse > this.bounds[1]) {
+                formattedResponse = this.bounds[1];
+            }
+            return formattedResponse;
+        }
+        const response = super.getResponse();
+        if (typeof response !== 'number') {
+            return undefined;
+        }
+        return super.getResponse();
+    }
+    toJSON() {
+        return {
+            type: 'numerical',
+            instruction: this.instruction,
+            bounds: this.bounds,
+            answer: this.getResponse()
+        };
+    }
+    /**
+     * 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() {
+        const x = this.getResponse();
+        if (x === undefined)
+            return [];
+        const norm = Math.sqrt(x * x + 1);
+        return [x / norm, 1 / norm];
+    }
+    static compare(a, b) {
+        const EPSILON = 1e-8;
+        const denom = Math.max(Math.abs(a), Math.abs(b), EPSILON);
+        const relativeDiff = Math.abs(a - b) / denom;
+        return 1 / (1 + relativeDiff);
+    }
+    static distance(a, b) {
+        const numA = a.getResponse();
+        const numB = b.getResponse();
+        if (numA == undefined || numB == undefined) {
+            return 0;
+        }
+        return NumericalFormat.compare(numA, numB);
+    }
+    static tool(bounds) {
+        return {
+            function: {
+                name: "return_float",
+                description: "Return a number as a float.",
+                parameters: {
+                    type: 'OBJECT',
+                    properties: {
+                        number: {
+                            type: 'NUMBER',
+                            description: "The numeric answer."
+                        }
+                    },
+                    required: ["number"]
+                }
+            },
+            evaluate: async (params) => {
+                return JSON.stringify(params['number']);
+            },
+            instruction: (_params) => {
+                if (bounds != undefined) {
+                    if (bounds[0] != undefined && bounds[1] != undefined) {
+                        return `Use the tool "return_float" to return your answer as a number on the scale of ${bounds[0]} to ${bounds[1]}.`;
+                    }
+                    else if (bounds[0] != undefined) {
+                        return `Use the tool "return_float" to return your answer as a number greater than ${bounds[0]}.`;
+                    }
+                    else {
+                        return `Use the tool "return_float" to return your answer as a number less than ${bounds[1]}.`;
+                    }
+                }
+                return `Use the tool "return_float" to return your answer as a number.`;
+            }
+        };
+    }
+}
+export class VectorFormat extends Format {
+    constructor(instruction, dimension, bounds) {
+        super(instruction, VectorFormat.tool(dimension, bounds));
+        Object.defineProperty(this, "dimension", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "bounds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.dimension = dimension;
+        this.bounds = bounds;
+    }
+    clone() {
+        return new VectorFormat(this.instruction, this.dimension, this.bounds);
+    }
+    getResponse() {
+        if (this.bounds && this.response) {
+            var formattedResponse = [];
+            for (let i = 0; i < this.response.length; i++) {
+                var number = this.response[i];
+                if (i < this.bounds.length) {
+                    const bounds = this.bounds[i];
+                    if (bounds) {
+                        if (bounds[0] != undefined && number < bounds[0]) {
+                            number = bounds[0];
+                        }
+                        if (bounds[1] != undefined && number > bounds[1]) {
+                            number = bounds[1];
+                        }
+                    }
+                }
+                formattedResponse.push(number);
+            }
+            return formattedResponse;
+        }
+        return super.getResponse();
+    }
+    toJSON() {
+        return {
+            type: 'vector',
+            instruction: this.instruction,
+            dimension: this.dimension,
+            bounds: this.bounds,
+            answer: this.getResponse()
+        };
+    }
+    toVector() {
+        const v = this.getResponse();
+        if (v === undefined || v.length === 0)
+            return [];
+        let normSquared = 0;
+        for (const x of v)
+            normSquared += x * x;
+        if (normSquared === 0)
+            return [];
+        const norm = Math.sqrt(normSquared);
+        return v.map((x) => x / norm);
+    }
+    static distance(a, b) {
+        const vectorA = a.getResponse();
+        const vectorB = b.getResponse();
+        if (vectorA == undefined || vectorB == undefined) {
+            return 0;
+        }
+        var aggregate = 0;
+        for (let i = 0; i < vectorA.length; i++) {
+            aggregate += NumericalFormat.compare(vectorA[i], vectorB[i]);
+        }
+        return aggregate / vectorA.length;
+    }
+    static tool(dimension, bounds) {
+        return {
+            function: {
+                name: "return_vector",
+                description: `Return a vector of ${dimension} numbers.`,
+                parameters: {
+                    type: 'OBJECT',
+                    properties: {
+                        vector: {
+                            type: 'ARRAY',
+                            items: { type: 'NUMBER' },
+                            minimum: dimension,
+                            maximum: dimension,
+                            description: `A vector of exactly ${dimension} numbers.`
+                        }
+                    },
+                    required: ["vector"]
+                }
+            },
+            evaluate: async (params) => {
+                return JSON.stringify(params['vector']);
+            },
+            instruction: (_params) => {
+                if (bounds == undefined) {
+                    return `Use the tool "return_vector" to return your answer as a numerical vector of dimension ${dimension}.`;
+                }
+                var lowerBound = '[';
+                var upperBound = '[';
+                for (let i = 0; i < dimension; i++) {
+                    if (bounds[i] == undefined || (bounds[i][0] == undefined && bounds[i][1] == undefined)) {
+                        lowerBound = lowerBound + '-infinity';
+                        upperBound = upperBound + 'infinity';
+                    }
+                    else if (bounds[i][0] != undefined) {
+                        lowerBound = lowerBound + `>${bounds[i][0].toString()}`;
+                        upperBound = upperBound + `infinity`;
+                    }
+                    else {
+                        lowerBound = lowerBound + `-infinity`;
+                        upperBound = upperBound + `<${bounds[i][1].toString()}`;
+                    }
+                    if (i < dimension - 1) {
+                        lowerBound = lowerBound + ', ';
+                        upperBound = upperBound + ', ';
+                    }
+                }
+                lowerBound = lowerBound + ']';
+                upperBound = upperBound + ']';
+                return `Use the tool "return_vector" to return your answer as a numerical vector of dimension ${dimension} of scale ${lowerBound} to ${upperBound}.`;
+            }
+        };
+    }
+}
+export class CategoricalFormat extends Format {
+    constructor(instruction, categories) {
+        super(instruction, CategoricalFormat.tool(categories));
+        Object.defineProperty(this, "categories", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.categories = categories;
+    }
+    clone() {
+        return new CategoricalFormat(this.instruction, this.categories);
+    }
+    getCategories() {
+        return this.categories;
+    }
+    getResponse() {
+        if (this.response) {
+            for (const category of this.categories) {
+                if (category == this.response) {
+                    return category;
+                }
+            }
+            console.error(`Response: ${this.response} not in categories: ${JSON.stringify(this.categories)}`);
+            return undefined;
+        }
+        return super.getResponse();
+    }
+    toJSON() {
+        return {
+            type: 'categorical',
+            instruction: this.instruction,
+            categories: this.categories,
+            answer: this.getResponse()
+        };
+    }
+    /** One-hot over the category set — already unit-length. */
+    toVector() {
+        const category = this.getResponse();
+        if (category === undefined)
+            return [];
+        const vector = new Array(this.categories.length).fill(0);
+        const index = this.categories.indexOf(category);
+        if (index < 0)
+            return [];
+        vector[index] = 1;
+        return vector;
+    }
+    static distance(a, b) {
+        const categoryA = a.getResponse();
+        const categoryB = b.getResponse();
+        if (categoryA == undefined || categoryB == undefined) {
+            return 0;
+        }
+        return categoryA === categoryB ? 1 : 0;
+    }
+    static tool(categories) {
+        return {
+            function: {
+                name: "return_category",
+                description: "Return one of the predefined categories.",
+                parameters: {
+                    type: 'OBJECT',
+                    properties: {
+                        category: {
+                            type: 'STRING',
+                            enum: categories,
+                            description: "The selected category."
+                        }
+                    },
+                    required: ["category"]
+                }
+            },
+            evaluate: async (params) => {
+                return JSON.stringify(params['category']);
+            },
+            instruction: (_params) => {
+                return `Use the tool "return_category" to return your answer as one of the categories: ${JSON.stringify(categories)}.`;
+            }
+        };
+    }
+}
+export class SelectionFormat extends Format {
+    constructor(instruction, options) {
+        super(instruction, SelectionFormat.tool(options));
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.options = options;
+    }
+    clone() {
+        return new SelectionFormat(this.instruction, this.options);
+    }
+    getOptions() {
+        return this.options;
+    }
+    getResponse() {
+        if (this.response) {
+            const selections = [];
+            for (const selection of this.response) {
+                if (this.options.includes(selection)) {
+                    selections.push(selection);
+                }
+            }
+            return selections;
+        }
+        return [];
+    }
+    toJSON() {
+        return {
+            type: 'selection',
+            instruction: this.instruction,
+            options: this.options,
+            answer: this.getResponse()
+        };
+    }
+    /** Multi-hot scaled by 1/sqrt(count) so the vector is unit-length. */
+    toVector() {
+        const selections = this.getResponse();
+        if (!selections || selections.length === 0)
+            return [];
+        const vector = new Array(this.options.length).fill(0);
+        let count = 0;
+        for (const selection of selections) {
+            const index = this.options.indexOf(selection);
+            if (index >= 0) {
+                vector[index] = 1;
+                count++;
+            }
+        }
+        if (count === 0)
+            return [];
+        const scale = 1 / Math.sqrt(count);
+        for (let i = 0; i < vector.length; i++)
+            vector[i] *= scale;
+        return vector;
+    }
+    static distance(a, b) {
+        const selectionsA = a.getResponse();
+        const selectionsB = b.getResponse();
+        if (!selectionsA || !selectionsB || selectionsA.length === 0 && selectionsB.length === 0) {
+            return 1;
+        }
+        if (selectionsA.length === 0 || selectionsB.length === 0) {
+            return 0;
+        }
+        const setA = new Set(selectionsA);
+        const setB = new Set(selectionsB);
+        let intersectionSize = 0;
+        for (const value of setA) {
+            if (setB.has(value)) {
+                intersectionSize += 1;
+            }
+        }
+        const unionSize = new Set([...selectionsA, ...selectionsB]).size;
+        return intersectionSize / unionSize;
+    }
+    static tool(options) {
+        return {
+            function: {
+                name: "return_selections",
+                description: "Return one or more selected options.",
+                parameters: {
+                    type: 'OBJECT',
+                    properties: {
+                        selections: {
+                            type: 'ARRAY',
+                            items: {
+                                type: 'STRING',
+                                enum: options
+                            },
+                            description: "The selected options."
+                        }
+                    },
+                    required: ["selections"]
+                }
+            },
+            evaluate: async (params) => {
+                return JSON.stringify(params['selections']);
+            },
+            instruction: (_params) => {
+                return `Use the tool "return_selections" to return your answer as a categorical vector of one or more in ${JSON.stringify(options)}`;
+            }
+        };
+    }
+}
+export class UtteranceFormat extends Format {
+    constructor(instruction, time) {
+        super(instruction, UtteranceFormat.tool());
+        Object.defineProperty(this, "time", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "embedding", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.time = time;
+    }
+    clone() {
+        return new UtteranceFormat(this.instruction, this.time);
+    }
+    toJSON() {
+        return {
+            type: 'utterance',
+            instruction: this.instruction,
+            time: this.time,
+            answer: this.getResponse()
+        };
+    }
+    /**
+     * 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() {
+        if (this.embedding === undefined || this.embedding.length === 0)
+            return [];
+        let normSquared = 0;
+        for (const x of this.embedding)
+            normSquared += x * x;
+        if (normSquared === 0)
+            return [];
+        const norm = Math.sqrt(normSquared);
+        return this.embedding.map((x) => x / norm);
+    }
+    async embed(authorization, model) {
+        const utterance = this.getResponse();
+        if (utterance == undefined) {
+            throw new Error('Cannot embed an utterance format without an answer.');
+        }
+        const result = await generateEmbedding(authorization, model, utterance);
+        this.embedding = result.embedding;
+    }
+    static distance(a, b) {
+        function linearCosineSimilarity(a, b) {
+            let dotProduct = 0;
+            let normA = 0;
+            let normB = 0;
+            for (let i = 0; i < a.length; i++) {
+                dotProduct += a[i] * b[i];
+                normA += a[i] ** 2;
+                normB += b[i] ** 2;
+            }
+            normA = Math.sqrt(normA);
+            normB = Math.sqrt(normB);
+            const similarity = normA && normB ? dotProduct / (normA * normB) : 0;
+            const linearized = 1 - (Math.acos(Math.min(1, Math.max(-1, similarity))) / Math.PI);
+            return linearized;
+        }
+        if (a.embedding == undefined || b.embedding == undefined) {
+            throw new Error('Both utterance formats must be embedded before computing distance. Call embed() first.');
+        }
+        return linearCosineSimilarity(a.embedding, b.embedding);
+    }
+    static tool(time) {
+        return {
+            function: {
+                name: "return_text",
+                description: `Return a free-form text response ${time ? ` within ${time} seconds)` : ''}.`,
+                parameters: {
+                    type: 'OBJECT',
+                    properties: {
+                        content: {
+                            type: 'STRING',
+                            description: "The text response."
+                        }
+                    },
+                    required: ["content"]
+                }
+            },
+            evaluate: async (params) => {
+                return JSON.stringify(params['content']);
+            },
+            instruction: (_params) => {
+                return `Use the tool "return_text" to return your answer as a string of ${time ? `length within ${time} seconds` : 'any length'}.`;
+            }
+        };
+    }
+}