@vertesia/client 0.78.0 → 0.79.1

package/src/InteractionOutput.test.ts

@@ -0,0 +1,305 @@
+import { CompletionResult } from '@llumiverse/common';
+import { describe, expect, it } from 'vitest';
+import { InteractionOutput, IS_INTERACTION_OUTPUT } from './InteractionOutput.js';
+
+describe('InteractionOutput', () => {
+    const sampleResults: CompletionResult[] = [
+        { type: 'text', value: 'Hello, ' },
+        { type: 'text', value: 'World!' },
+        { type: 'json', value: { name: 'Alice', age: 30 } },
+        { type: 'json', value: { title: 'Engineer', level: 'Senior' } },
+        { type: 'image', value: 'data:image/png;base64,iVBORw0K...' },
+        { type: 'image', value: 'https://example.com/image.jpg' }
+    ];
+
+    describe('text accessors', () => {
+        it('should concatenate all text results', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.text('')).toBe('Hello, World!');
+        });
+
+        it('should return empty string when no text results exist', () => {
+            const output = InteractionOutput.from([
+                { type: 'json', value: { foo: 'bar' } }
+            ]);
+            expect(output.text()).toBe('');
+        });
+
+        it('should return all text values as array', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.texts()).toEqual(['Hello, ', 'World!']);
+        });
+
+    });
+
+    describe('object accessors', () => {
+        it('should return first JSON object', () => {
+            const output = InteractionOutput.from<{ name: string; age: number }>(sampleResults);
+            const obj = output.object();
+            expect(obj).toEqual({ name: 'Alice', age: 30 });
+        });
+
+        it('should return all JSON objects', () => {
+            const output = InteractionOutput.from(sampleResults);
+            const objects = output.objects();
+            expect(objects).toEqual([
+                { name: 'Alice', age: 30 },
+                { title: 'Engineer', level: 'Senior' }
+            ]);
+        });
+
+        it('should parse text as JSON when no JSON result exists', () => {
+            const output = InteractionOutput.from([
+                { type: 'text', value: '{"foo":"bar"}' }
+            ]);
+            expect(output.object()).toEqual({ foo: 'bar' });
+        });
+
+        it('should throw error when no JSON result and text is not valid JSON', () => {
+            const output = InteractionOutput.from([
+                { type: 'text', value: 'not json' }
+            ]);
+            expect(() => output.object()).toThrow();
+        });
+
+        it('should throw error when no JSON result and no text', () => {
+            const output = InteractionOutput.from([
+                { type: 'image', value: 'data:image/png;base64,abc' }
+            ]);
+            expect(() => output.object()).toThrow('No JSON result found and no text available to parse');
+        });
+    });
+
+    describe('image accessors', () => {
+        it('should return first image', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.image()).toBe('data:image/png;base64,iVBORw0K...');
+        });
+
+        it('should return all images', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.images()).toEqual([
+                'data:image/png;base64,iVBORw0K...',
+                'https://example.com/image.jpg'
+            ]);
+        });
+
+        it('should throw error when no image result exists', () => {
+            const output = InteractionOutput.from([
+                { type: 'text', value: 'hello' }
+            ]);
+            expect(() => output.image()).toThrow('No image result found');
+        });
+
+    });
+
+    describe('utility methods', () => {
+        it('should convert to string (concatenated text)', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.toString()).toBe('Hello, \nWorld!');
+        });
+
+        it('should convert to JSON the resuilts array', () => {
+            const output = InteractionOutput.from(sampleResults);
+            expect(output.toJSON()).toEqual(sampleResults);
+        });
+
+        it('should stringify all parts with default separator and compact JSON', () => {
+            const output = InteractionOutput.from(sampleResults);
+            const result = output.stringify('\n', 0);  // Explicitly request compact JSON
+
+            expect(result).toBe(
+                'Hello, \n' +
+                'World!\n' +
+                '{"name":"Alice","age":30}\n' +
+                '{"title":"Engineer","level":"Senior"}\n' +
+                'data:image/png;base64,iVBORw0K...\n' +
+                'https://example.com/image.jpg'
+            );
+        });
+
+        it('should stringify all parts with formatted JSON', () => {
+            const mixed: CompletionResult[] = [
+                { type: 'text', value: 'Result:' },
+                { type: 'json', value: { score: 95, status: 'pass' } }
+            ];
+            const output = InteractionOutput.from(mixed);
+            const result = output.stringify('\n', 2);
+
+            expect(result).toBe(
+                'Result:\n' +
+                '{\n' +
+                '  "score": 95,\n' +
+                '  "status": "pass"\n' +
+                '}'
+            );
+        });
+
+        it('should stringify with custom separator', () => {
+            const mixed: CompletionResult[] = [
+                { type: 'text', value: 'A' },
+                { type: 'json', value: { x: 1 } },
+                { type: 'text', value: 'B' }
+            ];
+            const output = InteractionOutput.from(mixed);
+            const result = output.stringify(' | ', 0);  // Explicitly request compact JSON
+
+            expect(result).toBe('A | {"x":1} | B');
+        });
+
+        it('should stringify with empty separator', () => {
+            const mixed: CompletionResult[] = [
+                { type: 'text', value: 'Hello' },
+                { type: 'text', value: 'World' }
+            ];
+            const output = InteractionOutput.from(mixed);
+            const result = output.stringify('');
+
+            expect(result).toBe('HelloWorld');
+        });
+
+    });
+
+    describe('Proxy functionality', () => {
+        it('should work as an array', () => {
+            const output = InteractionOutput.from(sampleResults);
+
+            // Array access
+            expect(output[0]).toEqual({ type: 'text', value: 'Hello, ' });
+            expect(output[1]).toEqual({ type: 'text', value: 'World!' });
+
+            // Array properties
+            expect(output.length).toBe(6);
+
+            // Array methods
+            const types = output.map(r => r.type);
+            expect(types).toEqual(['text', 'text', 'json', 'json', 'image', 'image']);
+
+            const textResults = output.filter(r => r.type === 'text');
+            expect(textResults).toHaveLength(2);
+        });
+
+        it('should have convenience methods on the array', () => {
+            const output = InteractionOutput.from<{ name: string; age: number }>(sampleResults);
+
+            // Should work as array AND have custom methods
+            expect(output.length).toBe(6);
+            expect(output.text('')).toBe('Hello, World!');
+            expect(output.object()).toEqual({ name: 'Alice', age: 30 });
+        });
+
+        it('should be marked with IS_INTERACTION_OUTPUT symbol', () => {
+            const output = InteractionOutput.from(sampleResults);
+
+            // Check that the symbol marker is present
+            expect((output as any)[IS_INTERACTION_OUTPUT]).toBe(true);
+        });
+
+        it('should return the same instance when calling from() on an already wrapped array', () => {
+            const output1 = InteractionOutput.from(sampleResults);
+
+            // Calling from() again should return the same instance
+            const output2 = InteractionOutput.from(output1);
+
+            // Should be the exact same reference
+            expect(output2).toBe(output1);
+
+            // Verify it still works correctly
+            expect(output2.text()).toBe('Hello, \nWorld!');
+            expect(output2.length).toBe(6);
+        });
+
+        it('should not double-wrap when passing an InteractionOutputArray', () => {
+            const output1 = InteractionOutput.from<{ name: string; age: number }>(sampleResults);
+            const output2 = InteractionOutput.from(output1);
+            const output3 = InteractionOutput.from(output2);
+
+            // All should be the same reference
+            expect(output1).toBe(output2);
+            expect(output2).toBe(output3);
+
+            // Functionality should remain intact
+            expect(output3.object()).toEqual({ name: 'Alice', age: 30 });
+        });
+    });
+
+    describe('Direct class usage', () => {
+        it('should work when using class directly', () => {
+            const wrapper = new InteractionOutput<{ name: string; age: number }>(sampleResults);
+
+            expect(wrapper.text('')).toBe('Hello, World!');
+            expect(wrapper.object()).toEqual({ name: 'Alice', age: 30 });
+            expect(wrapper.results).toBe(sampleResults);
+        });
+    });
+
+    describe('Edge cases', () => {
+        it('should handle empty results array', () => {
+            const output = InteractionOutput.from([]);
+
+            expect(output.text()).toBe('');
+            expect(output.texts()).toEqual([]);
+            expect(output.objects()).toEqual([]);
+            expect(output.images()).toEqual([]);
+            expect(() => output.object()).toThrow();
+            expect(() => output.image()).toThrow();
+        });
+
+        it('should handle mixed content types', () => {
+            const mixed: CompletionResult[] = [
+                { type: 'text', value: 'Start' },
+                { type: 'json', value: { count: 5 } },
+                { type: 'text', value: 'End' }
+            ];
+
+            const output = InteractionOutput.from(mixed);
+            expect(output.text()).toBe('Start\nEnd');
+            expect(output.object()).toEqual({ count: 5 });
+        });
+
+        it('should handle results with only one type', () => {
+            const textOnly: CompletionResult[] = [
+                { type: 'text', value: 'Only text here' }
+            ];
+
+            const output = InteractionOutput.from(textOnly);
+            expect(output.text()).toBe('Only text here');
+            expect(output.objects()).toEqual([]);
+            expect(output.images()).toEqual([]);
+        });
+    });
+
+    describe('Type safety with generics', () => {
+        it('should provide type safety with generic parameter', () => {
+            interface User { name: string; age: number; }
+
+            const results: CompletionResult[] = [
+                { type: 'json', value: { name: 'Bob', age: 25 } }
+            ];
+
+            const output = InteractionOutput.from<User>(results);
+            const user = output.object(); // TypeScript knows this is User
+
+            expect(user.name).toBe('Bob');
+            expect(user.age).toBe(25);
+        });
+
+
+        it('should allow type override at method level', () => {
+            interface Person { name: string; age: number; }
+            interface Address { street: string; city: string; }
+
+            const results: CompletionResult[] = [
+                { type: 'json', value: { name: 'Alice', age: 30 } },
+                { type: 'json', value: { street: '123 Main', city: 'NYC' } }
+            ];
+
+            const output = InteractionOutput.from<Person>(results);
+            const person = output.objectAt<Person>(0);
+            const address = output.objectAt<Address>(1);
+
+            expect(person.name).toBe('Alice');
+            expect(address.city).toBe('NYC');
+        });
+    });
+});

package/src/InteractionOutput.ts

@@ -0,0 +1,328 @@
+import { CompletionResult } from '@llumiverse/common';
+import { ExecutionRun, InteractionExecutionResult } from '@vertesia/common';
+
+/**
+ * Symbol used to mark InteractionOutputArray instances.
+ * This allows us to detect if a CompletionResult[] has already been wrapped.
+ */
+export const IS_INTERACTION_OUTPUT = Symbol('InteractionOutput');
+
+export function enhanceInteractionExecutionResult<ResultT = any, ParamsT = any>(r: InteractionExecutionResult<ParamsT>): EnhancedInteractionExecutionResult<ResultT, ParamsT> {
+    (r as any).result = InteractionOutput.from<ResultT>(r.result);
+    return r as EnhancedInteractionExecutionResult<ResultT, ParamsT>;
+}
+
+export function enhanceExecutionRun<ResultT = any, ParamsT = any>(r: ExecutionRun<ParamsT>): EnhancedExecutionRun<ResultT, ParamsT> {
+    (r as any).result = InteractionOutput.from<ResultT>(r.result);
+    return r as EnhancedExecutionRun<ResultT, ParamsT>;
+}
+
+/**
+ * A convenient wrapper around CompletionResult[] that provides ergonomic accessors
+ * for different result types (text, JSON/objects, images) from interaction executions.
+ *
+ * Use the static from() method to create a proxied array that acts as both
+ * an array and has these convenience methods.
+ *
+ * @template T - The expected type of JSON/object results. Defaults to any.
+ *
+ * @example
+ * ```typescript
+ * // Recommended: Using the static from() method
+ * const output = InteractionOutput.from<MyResponse>(run.result);
+ * output[0];                        // CompletionResult (array access)
+ * output.length;                    // number (array property)
+ * const obj = output.object();      // MyResponse (custom method)
+ * const text = output.text();         // string (custom getter)
+ *
+ * // Alternative: Using the class directly (less common)
+ * const output = new InteractionOutput<MyResponse>(run.result);
+ * const obj = output.object();      // Returns MyResponse
+ * const objs = output.objects();    // Returns MyResponse[]
+ *
+ * // Override type for specific objects
+ * interface OtherType { title: string; }
+ * ```
+ */
+export class InteractionOutput<T = any> {
+    /**
+     * The raw completion results array.
+     * Access this when you need to work with the underlying CompletionResult[] directly.
+     */
+    constructor(public readonly results: CompletionResult[]) { }
+
+    /**
+     * Create an interaction output that acts as both an array and has convenience methods.
+     * This is the recommended way to work with interaction execution results.
+     *
+     * @template T - The expected type of JSON/object results. Defaults to any.
+     * @param results - The raw CompletionResult array from an interaction execution
+     * @returns A proxied array with convenience methods
+     *
+     * @example
+     * ```typescript
+     * interface MyResponse { name: string; age: number; }
+     * const output = InteractionOutput.from<MyResponse>(run.result);
+     *
+     * // Array access
+     * output[0];              // CompletionResult
+     * output.length;          // number
+     *
+     * // Convenience methods
+     * const obj = output.object();  // MyResponse
+     * const text = output.text();     // string
+     * ```
+     */
+    static from<T = any>(results: CompletionResult[] | InteractionOutputArray<T> | Record<string, any> | string | null | undefined): InteractionOutputArray<T> {
+        if (!results) {
+            return createInteractionOutput<T>([]);
+        }
+        // Check if already wrapped using the symbol marker        
+        if ((results as any)[IS_INTERACTION_OUTPUT]) {
+            return results as InteractionOutputArray<T>;
+        }
+        if (Array.isArray(results)) {
+            return createInteractionOutput<T>(results as CompletionResult[]);
+        } else if (typeof results === 'object') {
+            return createInteractionOutput<T>([{ type: 'json', value: results }]);
+        } else {
+            return createInteractionOutput<T>([{ type: 'text', value: String(results) }]);
+        }
+    }
+
+    static isInteractionOutputArray(obj: any): boolean {
+        return obj && obj[IS_INTERACTION_OUTPUT] === true;
+    }
+
+    get isEmpty() {
+        return this.results.length === 0;
+    }
+
+    hasObject() {
+        return this.results.some(r => r.type === 'json');
+    }
+
+    hasText() {
+        return this.results.some(r => r.type === 'text');
+    }
+
+    hasImage() {
+        return this.results.some(r => r.type === 'image');
+    }
+
+    /**
+     * Get the concatenated text from all text results.
+     * Returns an empty string if no text results exist.
+     */
+    text(delimiter = '\n'): string {
+        return this.results
+            .filter(r => r.type === 'text')
+            .map(r => r.value)
+            .join(delimiter);
+    }
+
+    /**
+     * Get an array of all text values from text results.
+     */
+    texts(): string[] {
+        return this.results
+            .filter(r => r.type === 'text')
+            .map(r => r.value);
+    }
+
+    /**
+     * Get the first JSON result as a parsed object.
+     * If no JSON result exists, attempts to parse the concatenated text as JSON.
+     * @returns The first JSON result typed as T (the class generic type)
+     * @throws Error if no JSON result found and text cannot be parsed as JSON
+     */
+    object(): T {
+        const jsonResult = this.results.find(r => r.type === 'json');
+        if (jsonResult) {
+            return jsonResult.value as T;
+        }
+
+        // Fallback: try to parse the other text parts as JSON
+        return parseCompletionResultAsJson(this.results);
+    }
+
+    /**
+     * Get all JSON results as parsed objects.
+     * @returns An array of all JSON results typed as T[] (the class generic type)
+     */
+    objects(): T[] {
+        return this.results
+            .filter(r => r.type === 'json')
+            .map(r => r.value as T);
+    }
+
+    /**
+     * Get a specific JSON result by index as a parsed object.
+     * @template U - The type of the object at this index. Defaults to T (the class generic).
+     * @param index - The zero-based index of the JSON result
+     * @returns The JSON result at the specified index typed as U
+     * @throws Error if the index is out of bounds
+     */
+    objectAt<U = T>(index: number): U {
+        let i = 0;
+        for (const result of this.results) {
+            if (result.type === 'json') {
+                if (i === index) {
+                    return result.value as U;
+                }
+                i++;
+            }
+        }
+        throw new Error(`Object at index ${index} not found`);
+    }
+
+    /**
+     * Get the first image result (base64 data URL or URL).
+     * @throws Error if no image result exists
+     */
+    image(): string {
+        const imageResult = this.results.find(r => r.type === 'image');
+        if (!imageResult) {
+            throw new Error('No image result found');
+        }
+        return imageResult.value;
+    }
+
+    /**
+     * Get an array of all image values (base64 data URLs or URLs).
+     */
+    images(): string[] {
+        return this.results
+            .filter(r => r.type === 'image')
+            .map(r => r.value);
+    }
+
+    /**
+     * Convert all results to a string representation.
+     * Text and image results are used as-is, JSON results are stringified with the specified indent.
+     * All parts are joined using the specified separator.
+     *
+     * @param separator - The separator to use between parts (default: '\n')
+     * @param indent - The indentation to use for JSON.stringify (default: 0 = no formatting)
+     * @returns A string representation of all results
+     *
+     * @example
+     * ```typescript
+     * const output = InteractionOutput.from(results);
+     * output.stringify();           // Each part on a new line, compact JSON
+     * output.stringify('\n\n', 2);  // Double newlines between parts, formatted JSON
+     * output.stringify(' ');        // Space-separated, compact JSON
+     * ```
+     */
+    stringify(separator = '\n', indent = 2): string {
+        return this.results
+            .map(r => {
+                switch (r.type) {
+                    case 'json':
+                        return JSON.stringify(r.value, null, indent);
+                    default:
+                        return String(r.value);
+                }
+            })
+            .join(separator);
+    }
+
+    /**
+     * Convert to string representation (concatenated text).
+     * Useful for template literals or string coercion.
+     */
+    toString(): string {
+        return this.text();
+    }
+
+    /**
+     * Convert to JSON representation.
+     * Attempts to return the first JSON object, falls back to concatenated text.
+     */
+    toJSON(): CompletionResult[] {
+        return this.results
+    }
+}
+
+/**
+ * Type representing a CompletionResult array enhanced with InteractionOutput methods.
+ * This is the return type of InteractionOutput.from() - it acts as both an array and has convenience methods.
+ */
+export type InteractionOutputArray<T = any> = CompletionResult[] & InteractionOutput<T>;
+
+export interface EnhancedInteractionExecutionResult<ResultT = any, ParamsT = any> extends InteractionExecutionResult<ParamsT> {
+    result: InteractionOutputArray<ResultT>;
+}
+
+export interface EnhancedExecutionRun<ResultT = any, ParamsT = any> extends ExecutionRun<ParamsT> {
+    result: InteractionOutputArray<ResultT>;
+}
+
+/**
+ * Creates a proxied array that acts as both a CompletionResult[] and has InteractionOutput convenience methods.
+ * Note: It's recommended to use InteractionOutput.from() instead of calling this function directly.
+ *
+ * @template T - The expected type of JSON/object results. Defaults to any.
+ * @param results - The raw CompletionResult array from the interaction execution
+ * @returns A proxy that behaves as both an array and has convenience methods
+ *
+ * @example
+ * ```typescript
+ * interface MyResponse { name: string; age: number; }
+ * const output = createInteractionOutput<MyResponse>(run.result);
+ *
+ * // Array access
+ * output[0];              // CompletionResult
+ * output.length;          // number
+ * output.map(r => r.type) // string[]
+ *
+ * // Convenience methods
+ * const obj = output.object();  // MyResponse
+ * const text = output.text();     // string
+ * const img = output.image();     // string
+ * ```
+ */
+export function createInteractionOutput<T = any>(results: CompletionResult[]): InteractionOutputArray<T> {
+    const wrapper = new InteractionOutput<T>(results);
+
+    return new Proxy(results, {
+        get(target, prop, receiver) {
+            // Return the marker symbol to identify wrapped arrays
+            if (prop === IS_INTERACTION_OUTPUT) {
+                return true;
+            }
+
+            // Check if the wrapper has this property/method
+            if (prop in wrapper) {
+                const value = (wrapper as any)[prop];
+                // If it's a function, bind it to the wrapper so 'this' works correctly
+                if (typeof value === 'function') {
+                    return value.bind(wrapper);
+                }
+                // For getters and regular properties, just return the value
+                return value;
+            }
+            // Otherwise delegate to the array
+            return Reflect.get(target, prop, receiver);
+        }
+    }) as InteractionOutputArray<T>;
+}
+
+
+function parseCompletionResultAsJson(data: CompletionResult[]) {
+    let lastError: Error | undefined;
+    for (const part of data) {
+        if (part.type === "text") {
+            const text = part.value.trim();
+            try {
+                return JSON.parse(text);
+            } catch (error: any) {
+                lastError = error;
+            }
+        }
+    }
+    if (!lastError) {
+        lastError = new Error("No JSON result found and no text available to parse");
+    }
+    throw lastError;
+}