gx402 1.3.5

package/README.md

@@ -0,0 +1,15 @@
+# uaiv2
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.13. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/index.ts

@@ -0,0 +1 @@
+console.log("Hello via Bun!");

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "gx402",
+  "module": "uai.ts",
+  "main": "./uai.ts",
+  "version": "1.3.5",
+  "type": "module",
+  "private": false,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@ments/utils": "1.0.2",
+    "zod": "^3.25.67"
+  }
+}

package/patch

@@ -0,0 +1,290 @@
+diff --git a/uai.ts b/uai.ts
+index 1234567..abcdefg 100644
+--- a/uai.ts
++++ b/uai.ts
+@@ -33,10 +33,17 @@ export interface AgentConfig<I extends z.ZodObject<any>, O extends z.ZodObject<
+ 
+ // ### Progress Callback Types
+ export interface ProgressUpdate {
+-  stage: "server_selection" | "tool_discovery" | "tool_invocation" | "response_generation";
++  stage: "server_selection" | "tool_discovery" | "tool_invocation" | "response_generation" | "streaming";
+   message: string;
+   data?: any;
+ }
+ 
++export interface StreamingUpdate {
++  stage: "streaming";
++  field: string;
++  value: string;
++}
++
+ export type ProgressCallback = (update: ProgressUpdate) => void;
++export type StreamingCallback = (update: StreamingUpdate) => void;
+ 
+ // ### XML Utilities
+@@ -102,10 +109,11 @@ function xmlToObj(xmlContent: string): any {
+ /** Calls an LLM API with measurement for logging. */
+ async function callLLM(
+   llm: LLMType,
+   messages: Array<{ role: string; content: string }>,
+   options: { temperature?: number; maxTokens?: number } = {},
+-  measureFn?: typeof measure
++  measureFn?: typeof measure,
++  streamingCallback?: StreamingCallback
+ ): Promise<string> {
+   const executeCall = async (measure: typeof measure) => {
+     const { temperature = 0.7, maxTokens = 4000 } = options;
+@@ -119,17 +127,20 @@ async function callLLM(
+       headers["x-api-key"] = process.env.ANTHROPIC_API_KEY!;
+       headers["anthropic-version"] = "2023-06-01";
+       url = "https://api.anthropic.com/v1/messages";
+-      body = { model: llm, max_tokens: maxTokens, messages };
++      body = { model: llm, max_tokens: maxTokens, messages, stream: !!streamingCallback };
+     } else if (llm.includes("deepseek")) {
+       headers["Authorization"] = `Bearer ${process.env.DEEPSEEK_API_KEY}`;
+       url = "https://api.deepseek.com/v1/chat/completions";
+-      body = { model: llm, temperature, messages, max_tokens: maxTokens };
++      body = { model: llm, temperature, messages, max_tokens: maxTokens, stream: !!streamingCallback };
+     } else {
+       headers["Authorization"] = `Bearer ${process.env.OPENAI_API_KEY}`;
+       url = "https://api.openai.com/v1/chat/completions";
+-      body = { model: llm, temperature, messages, max_tokens: maxTokens };
++      body = { model: llm, temperature, messages, max_tokens: maxTokens, stream: !!streamingCallback };
+     }
++
+     const requestBodyStr = JSON.stringify(body);
++    
++    if (!streamingCallback) {
+     const response = await measure(
+       async () => {
+         const res = await fetch(url, {
+@@ -144,7 +155,98 @@ async function callLLM(
+       `HTTP ${llm} API call - Body: ${requestBodyStr.substring(0, 200)}...`
+     );
+     const data = await response.json();
+     return llm.includes("claude") ? data.content[0].text : data.choices[0].message.content;
++    } else {
++      // Streaming response handling
++      const response = await measure(
++        async () => {
++          const res = await fetch(url, {
++            method: "POST",
++            headers,
++            body: requestBodyStr,
++          });
++          if (!res.ok) {
++            const errorText = await res.text();
++            throw new Error(`LLM API error: ${errorText}`);
++          }
++          return res;
++        },
++        `HTTP ${llm} streaming API call - Body: ${requestBodyStr.substring(0, 200)}...`
++      );
++
++      const reader = response.body?.getReader();
++      if (!reader) {
++        throw new Error("No readable stream available");
++      }
++
++      const decoder = new TextDecoder();
++      let fullResponse = "";
++      let currentField = "";
++      let currentValue = "";
++      let insideTag = false;
++      let buffer = "";
++
++      try {
++        while (true) {
++          const { done, value } = await reader.read();
++          if (done) break;
++
++          const chunk = decoder.decode(value, { stream: true });
++          buffer += chunk;
++
++          // Process complete lines for different providers
++          const lines = buffer.split('\n');
++          buffer = lines.pop() || ''; // Keep incomplete line in buffer
++
++          for (const line of lines) {
++            let content = '';
++            
++            if (llm.includes("claude")) {
++              // Anthropic streaming format
++              if (line.startsWith('data: ') && !line.includes('[DONE]')) {
++                try {
++                  const data = JSON.parse(line.slice(6));
++                  if (data.type === 'content_block_delta' && data.delta?.text) {
++                    content = data.delta.text;
++                  }
++                } catch (e) {
++                  continue;
++                }
++              }
++            } else {
++              // OpenAI/DeepSeek streaming format
++              if (line.startsWith('data: ') && !line.includes('[DONE]')) {
++                try {
++                  const data = JSON.parse(line.slice(6));
++                  if (data.choices?.[0]?.delta?.content) {
++                    content = data.choices[0].delta.content;
++                  }
++                } catch (e) {
++                  continue;
++                }
++              }
++            }
++
++            if (content) {
++              fullResponse += content;
++              
++              // Parse XML tags to detect field changes
++              for (const char of content) {
++                if (char === '<') {
++                  insideTag = true;
++                  currentValue = "";
++                } else if (char === '>' && insideTag) {
++                  insideTag = false;
++                  if (!currentValue.startsWith('/')) {
++                    currentField = currentValue;
++                    currentValue = "";
++                  }
++                } else if (insideTag) {
++                  currentValue += char;
++                } else if (currentField && char !== '\n') {
++                  currentValue += char;
++                  streamingCallback({ stage: "streaming", field: currentField, value: currentValue });
++                }
++              }
++            }
++          }
++        }
++      } finally {
++        reader.releaseLock();
++      }
++
++      return fullResponse;
++    }
+   };
+   return measureFn
+     ? await measureFn(executeCall, `LLM call to ${llm}`)
+@@ -254,7 +356,8 @@ export class Agent<I extends z.ZodObject<any>, O extends z.ZodObject<any>> {
+           stage: "response_generation",
+           message: "Generating final response...",
+         });
++        
+         try {
+           const response = await measure(
+-            async (measure) => await this.generateResponse(validatedInput, toolResults, measure),
++            async (measure) => await this.generateResponse(validatedInput, toolResults, measure, progressCallback),
+             "Generate AI response with toolResults: " + JSON.stringify(toolResults),
+           );
+           return await measure(
+@@ -409,7 +512,16 @@ export class Agent<I extends z.ZodObject<any>, O extends z.ZodObject<any>> {
+   }
+ 
+   /** Generates the final response based on input and tool results. */
+-  private async generateResponse(input: any, toolResults: Record<string, any>, measureFn: typeof measure): Promise<any> {
++  private async generateResponse(
++    input: any, 
++    toolResults: Record<string, any>, 
++    measureFn: typeof measure, 
++    progressCallback?: ProgressCallback
++  ): Promise<any> {
++    const streamingCallback: StreamingCallback | undefined = progressCallback ? 
++      (update) => progressCallback(update as ProgressUpdate) : 
++      undefined;
++      
+     return await measureFn(
+       async (measure) => {
+         const systemPrompt = this.config.systemPrompt || null;
+@@ -434,7 +546,8 @@ export class Agent<I extends z.ZodObject<any>, O extends z.ZodObject<any>> {
+         const response = await measure(() => callLLM(
+           this.config.llm,
+           messages,
+-          { temperature: this.config.temperature || 0.7, maxTokens: this.config.maxTokens || 4000 },
++          { temperature: this.config.temperature || 0.7, maxTokens: this.config.maxTokens || 4000 },
+-          measure
++          measure,
++          streamingCallback
+         ), userPrompt);
+         const parsed = await measure(
+           async () => xmlToObj(response),
+diff --git a/test/streaming.test.ts b/test/streaming.test.ts
+new file mode 100644
+index 0000000..1234567
+--- /dev/null
++++ b/test/streaming.test.ts
+@@ -0,0 +1,72 @@
++import { test, expect, it, describe } from 'bun:test';
++import { z } from 'zod';
++import { Agent, LLM, ProgressUpdate, StreamingUpdate } from '../uai';
++
++describe('UAI Streaming Tests', () => {
++  it('should emit streaming progress updates token-by-token', async () => {
++    const streamingAgent = new Agent({
++      llm: LLM['gpt-4o-mini'],
++      inputFormat: z.object({
++        question: z.string(),
++      }),
++      outputFormat: z.object({
++        analysis: z.string().describe("Step-by-step analysis of the question"),
++        answer: z.string().describe("The final answer to the question"),
++      }),
++      temperature: 0.7,
++    });
++
++    const input = {
++      question: 'What are the benefits of renewable energy?',
++    };
++
++    const streamingUpdates: StreamingUpdate[] = [];
++    const progressUpdates: ProgressUpdate[] = [];
++
++    try {
++      const result = await streamingAgent.run(input, (update) => {
++        if (update.stage === 'streaming') {
++          streamingUpdates.push(update as StreamingUpdate);
++          console.log(`Field: ${update.field}, Value: ${update.value.slice(-20)}...`);
++        } else {
++          progressUpdates.push(update);
++        }
++      });
++
++      console.log('\n--- Final Result ---');
++      console.log('Analysis:', result.analysis);
++      console.log('Answer:', result.answer);
++
++      // Verify we received streaming updates
++      expect(streamingUpdates.length).toBeGreaterThan(0);
++      
++      // Verify we have updates for both fields
++      const fieldsUpdated = new Set(streamingUpdates.map(u => u.field));
++      expect(fieldsUpdated.has('analysis')).toBe(true);
++      expect(fieldsUpdated.has('answer')).toBe(true);
++
++      // Verify the streaming updates show progressive content building
++      const analysisUpdates = streamingUpdates.filter(u => u.field === 'analysis');
++      const answerUpdates = streamingUpdates.filter(u => u.field === 'answer');
++      
++      expect(analysisUpdates.length).toBeGreaterThan(1);
++      expect(answerUpdates.length).toBeGreaterThan(1);
++
++      // Verify content is progressively building (each update should contain more text)
++      for (let i = 1; i < analysisUpdates.length; i++) {
++        expect(analysisUpdates[i].value.length).toBeGreaterThanOrEqual(analysisUpdates[i-1].value.length);
++      }
++
++      // Verify final result matches last streaming update values
++      const lastAnalysisUpdate = analysisUpdates[analysisUpdates.length - 1];
++      const lastAnswerUpdate = answerUpdates[answerUpdates.length - 1];
++      
++      expect(result.analysis.trim()).toBe(lastAnalysisUpdate.value.trim());
++      expect(result.answer.trim()).toBe(lastAnswerUpdate.value.trim());
++
++      console.log(`\n✅ Received ${streamingUpdates.length} streaming updates across ${fieldsUpdated.size} fields`);
++
++    } catch (error) {
++      console.warn('\n⚠️ Streaming test skipped (this is expected if API keys are not configured):', error.message);
++    }
++  }, { timeout: 60000 });
++});

package/test/basic.test.ts

@@ -0,0 +1,73 @@
+import { test, expect, it, describe } from 'bun:test';
+import { z } from 'zod';
+import { Agent, LLM, ProgressUpdate } from '../uai';
+
+describe('UAI Library Advanced Tests', () => {
+  it('should generate a structured response with a thinking process based on persona', async () => {
+    // 1. Define an Agent with more meaningful input and output schemas
+    const personaAgent = new Agent({
+      llm: LLM['gpt-4o-mini'],
+      // Input requires context for how the AI should behave
+      inputFormat: z.object({
+        user_query: z.string(),
+        personality: z.string(),
+        tone: z.enum(['humorous', 'formal', 'serious']),
+      }),
+      // Output is structured to separate reasoning from the final answer
+      outputFormat: z.object({
+        thinkingProcess: z.string().describe("My step-by-step reasoning for crafting the response, from the persona's point of view."),
+        finalResponse: z.string().describe("The final, crafted response for the user, delivered in character."),
+        suggestedMarkup: z.string().describe("A sample HTML block based on the response, which could be e.g. a div or a blockquote."),
+        status: z.boolean().describe("is it done or not"),
+      }),
+      temperature: 0.7,
+    });
+
+    const input = {
+      user_query: 'What is the best way to invest $100?',
+      personality: 'A cautious, old sea captain who has seen many treasures lost to recklessness.',
+      tone: 'serious' as const, // 'as const' helps TypeScript infer the most specific type
+    };
+
+    try {
+      const streamingResponse = {};
+      // 2. Run the agent and await the structured result
+      const { finalResponse, thinkingProcess, suggestedMarkup, status } = await personaAgent.run(input, (update: any) => {
+        if (update.stage === 'streaming') {
+          streamingResponse[update.field] = (streamingResponse[update.field] || '') + update.value;
+        }
+      });
+
+      // 3. Log the output for easy debugging during test runs
+      console.log('\n--- Thinking Process ---');
+      console.log(thinkingProcess);
+      console.log('\n--- Final Response ---');
+      console.log(finalResponse);
+      console.log('\n--- Suggested Markup ---');
+      console.log(suggestedMarkup);
+      console.log('\n--- Status ---');
+      console.log(status);
+
+      // check boolean type prompts
+      expect(status).toBe(true);
+
+      // 4. Verify the structure and content of the response
+      expect(thinkingProcess).toBeTypeOf('string');
+      expect(thinkingProcess.length).toBeGreaterThan(1); // Assert it's not empty
+
+      expect(finalResponse).toBeTypeOf('string');
+      expect(finalResponse.toLowerCase()).toInclude('sea');
+      expect(suggestedMarkup).toBeTypeOf('string');
+      // Assert that we received a string that contains markup, which would have failed before the fix.
+      expect(suggestedMarkup.trim()).toStartWith('<');
+      expect(suggestedMarkup.trim()).toEndWith('>');
+
+
+      console.log('\n✅ Agent generated a valid, structured response that fits the persona.');
+
+    } catch (error) {
+      // This block allows the test to pass gracefully if API keys aren't configured.
+      console.warn('\n⚠️ API call test skipped (this is expected if API keys are not configured):', error.message);
+    }
+  }, { timeout: 30000 });
+});

package/test/edge.test.ts

@@ -0,0 +1,237 @@
+import { test, expect, it, describe } from 'bun:test';
+import { z } from 'zod';
+import { Agent, LLM, ProgressUpdate } from '../uai';
+
+describe('UAI Library Tests', () => {
+  it('should process complex input validation successfully', async () => {
+    const complexAgent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        userQuery: z.string().describe('The main question or request from the user'),
+        context: z.object({
+          sessionId: z.string().describe('Unique identifier for this conversation session'),
+          previousInteraction: z.string().optional().describe('Summary of previous interaction if any'),
+          userPreferences: z.object({
+            responseStyle: z.enum(['formal', 'casual', 'technical']).describe('Preferred communication style'),
+            detailLevel: z.enum(['brief', 'moderate', 'comprehensive']).describe('Desired level of detail in responses'),
+          }),
+        }),
+        metadata: z.object({
+          timestamp: z.string().describe('ISO timestamp of the request'),
+          platform: z.string().describe('Platform or device used to make the request'),
+          urgency: z.enum(['low', 'medium', 'high']).describe('Priority level of the request'),
+        }),
+      }),
+      outputFormat: z.object({
+        primaryResponse: z.string().describe('The main answer or response to the user query'),
+        analysis: z.object({
+          confidence: z.number().describe('Confidence level from 0 to 1 in the response accuracy'),
+          reasoning: z.string().describe('Brief explanation of the reasoning process used'),
+          complexity: z.enum(['simple', 'moderate', 'complex']).describe('Assessed complexity of the query'),
+        }),
+      }),
+    });
+
+    try {
+      await complexAgent.run({
+        userQuery: 'What are the best practices for sustainable software development?',
+        context: {
+          sessionId: 'session_12345',
+          previousInteraction: 'User previously asked about green computing',
+          userPreferences: {
+            responseStyle: 'technical',
+            detailLevel: 'comprehensive',
+          },
+        },
+        metadata: {
+          timestamp: '2024-12-25T10:30:00Z',
+          platform: 'web_browser',
+          urgency: 'medium',
+        },
+      });
+      console.log('✅ Complex input validation and processing successful');
+    } catch (error) {
+      console.warn('⚠️ API call test skipped (possibly due to API keys):', error.message);
+      if (!error.message.includes('API') && !error.message.includes('401') && !error.message.includes('403')) {
+        throw error;
+      }
+    }
+  });
+
+  it('should throw error for arrays in output schema', () => {
+    expect(() => {
+      new Agent({
+        llm: LLM.gpt4o,
+        inputFormat: z.object({
+          message: z.string(),
+        }),
+        outputFormat: z.object({
+          responses: z.array(z.string()), // This should throw an error
+        }),
+      });
+    }).toThrow('Arrays are not supported in output schema. Found array at path: responses. Use individual fields like responses_1, responses_2 instead.');
+
+    console.log('✅ Array validation working correctly');
+  });
+
+  it('should throw error for nested arrays in output schema', () => {
+    expect(() => {
+      new Agent({
+        llm: LLM.gpt4o,
+        inputFormat: z.object({
+          message: z.string(),
+        }),
+        outputFormat: z.object({
+          data: z.object({
+            items: z.array(z.string()), // Nested array should also throw
+          }),
+        }),
+      });
+    }).toThrow('Arrays are not supported in output schema. Found array at path: data.items. Use individual fields like items_1, items_2 instead.');
+
+    console.log('✅ Nested array validation working correctly');
+  });
+
+  it('should validate input types correctly', async () => {
+    const agent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        message: z.string(),
+        count: z.number(),
+      }),
+      outputFormat: z.object({
+        response: z.string(),
+      }),
+    });
+
+    try {
+      await agent.run({
+        message: 123 as any, // Wrong type
+        count: 'not a number' as any, // Wrong type
+      });
+      expect(false).toBe(true); // Should not reach here
+    } catch (error) {
+      expect(error.name).toBe('ZodError');
+      console.log('✅ Input type validation working correctly');
+    }
+  });
+
+  it('should validate enum values correctly', async () => {
+    const agent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        message: z.string(),
+        priority: z.enum(['low', 'medium', 'high']),
+      }),
+      outputFormat: z.object({
+        response: z.string(),
+      }),
+    });
+
+    try {
+      await agent.run({
+        message: 'test',
+        priority: 'invalid_priority' as any, // Invalid enum value
+      });
+      expect(false).toBe(true); // Should not reach here
+    } catch (error) {
+      expect(error.name).toBe('ZodError');
+      console.log('✅ Enum validation working correctly');
+    }
+  });
+
+  it('should support all LLM model configurations', () => {
+    const models = [LLM.gpt4o, LLM.gpt4, LLM.claude, LLM.deepseek];
+    
+    for (const model of models) {
+      const agent = new Agent({
+        llm: model,
+        inputFormat: z.object({
+          query: z.string(),
+        }),
+        outputFormat: z.object({
+          result: z.string(),
+          metadata: z.object({
+            model: z.string(),
+            confidence: z.number(),
+          }),
+        }),
+      });
+
+      expect(agent).toBeDefined();
+      console.log(`✅ ${model} configuration valid`);
+    }
+  });
+
+  it('should handle optional fields correctly', async () => {
+    const agent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        required: z.string(),
+        optional: z.string().optional(),
+      }),
+      outputFormat: z.object({
+        answer: z.string(),
+        extra: z.string().optional(),
+      }),
+    });
+
+    try {
+      await agent.run({
+        required: 'test value',
+        // optional field omitted
+      });
+      console.log('✅ Optional fields handled correctly');
+    } catch (error) {
+      console.warn('⚠️ Optional fields test skipped due to API limitations');
+      if (!error.message.includes('API') && !error.message.includes('401') && !error.message.includes('403')) {
+        throw error;
+      }
+    }
+  });
+
+  it('should handle nullable fields correctly', async () => {
+    const agent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        required: z.string(),
+        nullable: z.string().nullable(),
+      }),
+      outputFormat: z.object({
+        answer: z.string(),
+        extra: z.string().nullable(),
+      }),
+    });
+
+    try {
+      await agent.run({
+        required: 'test value',
+        nullable: null,
+      });
+      console.log('✅ Nullable fields handled correctly');
+    } catch (error) {
+      console.warn('⚠️ Nullable fields test skipped due to API limitations');
+      if (!error.message.includes('API') && !error.message.includes('401') && !error.message.includes('403')) {
+        throw error;
+      }
+    }
+  });
+
+  it('should configure agent with custom temperature and maxTokens', () => {
+    const agent = new Agent({
+      llm: LLM.gpt4o,
+      inputFormat: z.object({
+        query: z.string(),
+      }),
+      outputFormat: z.object({
+        response: z.string(),
+      }),
+      temperature: 0.1,
+      maxTokens: 500,
+      systemPrompt: 'You are a precise assistant that gives brief responses.',
+    });
+
+    expect(agent).toBeDefined();
+    console.log('✅ Custom configuration parameters working correctly');
+  });
+});