gx402 1.3.5 → 1.3.6

package/README.md

@@ -1,15 +1,179 @@
-# uaiv2
+# gx402
 
-To install dependencies:
+[![npm version](https://badge.fury.io/js/gx402.svg)](https://badge.fury.io/js/gx402)
+[![Bun](https://img.shields.io/badge/Bun-tested-blueviolet)](https://bun.sh/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+
+gx402 is a lightweight TypeScript library for building AI agents powered by large language models (LLMs). It emphasizes structured inputs and outputs using [Zod](https://zod.dev/) schemas, with built-in support for real-time streaming updates. Perfect for applications needing progressive, token-by-token responses while maintaining type safety and parseable results.
+
+Key features:
+- **Structured I/O**: Define input and output schemas with Zod for validation and type inference.
+- **Streaming Support**: Receive token-by-token updates for fields, including progressive content building.
+- **Agent Abstraction**: Simple `Agent` class to orchestrate LLM calls with customizable temperature and models.
+- **Progress Tracking**: Optional callbacks for monitoring stages like streaming or completion.
+- **Nested Schema Flattening**: Nested output fields are automatically flattened for streaming (e.g., `analysis.step1` becomes `analysis_step1`).
+
+Supports modern runtimes like Bun and Node.js.
+
+## Installation
+
+Install via npm:
 
 ```bash
-bun install
+npm install gx402
 ```
 
-To run:
+You'll also need:
+- [Zod](https://www.npmjs.com/package/zod) for schemas (`npm install zod`).
+- An LLM provider (e.g., OpenAI-compatible API). Set your API key in environment variables (e.g., `OPENAI_API_KEY`).
+
+For testing, use Bun's test runner: `bun add -d bun:test`.
+
+## Quick Start
+
+Create an agent with input/output schemas and run it with a streaming callback.
+
+```typescript
+import { z } from 'zod';
+import { Agent } from 'gx402';
+
+const agent = new Agent({
+  llm: 'o4-mini-2025-04-16', // Your LLM model (e.g., OpenAI GPT variant)
+  inputFormat: z.object({
+    question: z.string(),
+  }),
+  outputFormat: z.object({
+    analysis: z.object({
+      step1: z.string(),
+      step2: z.string(),
+      step3: z.string(),
+    }).describe('Step-by-step analysis of the question'),
+    answer: z.string().describe('The final short concise answer to the question'),
+    status: z.string().describe('just literal word OK'),
+  }),
+  temperature: 0.7, // Optional: Controls creativity (0-1)
+});
+
+const input = { question: 'What are the benefits of renewable energy?' };
+
+const result = await agent.run(input, (update) => {
+  if (update.stage === 'streaming') {
+    console.log(`Field: ${update.field}, Partial Value: ${update.value}`);
+    // Value builds progressively (e.g., "Renewable energy reduces carbon..." → "...emissions and costs.")
+  }
+});
+
+console.log('Final Analysis:', result.analysis);
+console.log('Final Answer:', result.answer);
+console.log('Status:', result.status); // e.g., "OK"
+```
+
+### Expected Output
+- **Streaming Logs** (real-time, token-by-token):
+  ```
+  Field: analysis, Partial Value: {"step1":"Renewable energy...
+  Field: analysis, Partial Value: {"step1":"Renewable energy sources like solar and wind...
+  Field: answer, Partial Value: Renewable energy offers environmental, economic...
+  ...
+  ```
+- **Final Result** (fully parsed and validated):
+  ```json
+  {
+    "analysis": {
+      "step1": "Renewable energy sources like solar and wind reduce reliance on fossil fuels.",
+      "step2": "They lower greenhouse gas emissions and combat climate change.",
+      "step3": "Economically, they create jobs and reduce long-term energy costs."
+    },
+    "answer": "Renewable energy provides environmental protection, cost savings, and energy independence.",
+    "status": "OK"
+  }
+  ```
+
+Nested fields like `analysis.step1` stream as `analysis` (full JSON object building progressively) or flattened (`analysis_step1`) based on config—check your schema descriptions for hints.
+
+## API Reference
+
+### Agent Constructor
+```typescript
+new Agent(config: AgentConfig)
+```
+
+**AgentConfig**:
+- `llm: string` (required): Model identifier (e.g., `'gpt-4o-mini'`, `'o4-mini-2025-04-16'`).
+- `inputFormat: ZodObject` (required): Schema for validating inputs.
+- `outputFormat: ZodObject` (required): Schema for parsing LLM responses. Use `.describe()` for field hints.
+- `temperature?: number` (default: 0.5): Sampling temperature.
+- `stream?: boolean` (default: true): Enable streaming.
+
+### agent.run(input: InputType, callback?: UpdateCallback): Promise<OutputType>
+- `input`: Object matching `inputFormat`.
+- `callback?: (update: ProgressUpdate | StreamingUpdate) => void`: Optional hook for real-time events.
+  - **ProgressUpdate**: `{ stage: 'starting' | 'completing' | 'error', message: string }`.
+  - **StreamingUpdate**: `{ stage: 'streaming', field: string, value: string }` – `value` grows token-by-token.
+- Returns: Parsed output matching `outputFormat`.
+
+### Types
+- `ProgressUpdate`: Non-streaming milestones (e.g., "Request sent").
+- `StreamingUpdate`: Field-specific partial values (e.g., building JSON for `analysis`).
+
+## Examples
+
+### Basic Non-Streaming
+```typescript
+const result = await agent.run(input); // No callback, blocks until complete
+```
+
+### Custom Error Handling
+```typescript
+try {
+  const result = await agent.run(input, (update) => {
+    // Handle updates...
+  });
+} catch (error) {
+  console.error('Agent failed:', error.message); // e.g., "Invalid API key"
+}
+```
+
+### Nested Streaming
+For deeply nested schemas, fields stream as flat strings (e.g., `analysis_step1: "Renewables reduce..."`). Use Zod's `.describe()` to guide the LLM on formatting.
+
+## Testing
+gx402 is tested with Bun. Run tests:
 
 ```bash
-bun run index.ts
+bun test
 ```
 
-This project was created using `bun init` in bun v1.2.13. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+Example test (from `tests/streaming.test.ts`):
+```typescript
+import { test, expect } from 'bun:test';
+import { z } from 'zod';
+import { Agent, ProgressUpdate, StreamingUpdate } from 'gx402';
+
+test('should emit streaming progress updates token-by-token', async () => {
+  // ... (see full test in repo)
+  expect(streamingUpdates.length).toBeGreaterThan(0);
+  // Verifies progressive building and final match
+}, { timeout: 60000 });
+```
+
+Note: Tests skip if API keys aren't set (e.g., for CI).
+
+## Configuration
+- **Environment Vars**: `OPENAI_API_KEY` (or provider-specific). Customize via `process.env`.
+- **Timeouts**: Set via test options or extend `Agent` for production.
+- **Providers**: Defaults to OpenAI-compatible; extend `LLM` class for others (e.g., Anthropic, Grok).
+
+## Contributing
+1. Fork and clone.
+2. Install deps: `bun install`.
+3. Run tests: `bun test`.
+4. Lint: `bun run lint`.
+5. Submit PRs to `main`.
+
+Issues? Open a ticket on GitHub.
+
+## License
+MIT. See [LICENSE](LICENSE). 
+
+Built with ❤️ for structured AI workflows. Questions? Ping `@galaxydoxyz` on X.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "gx402",
-  "module": "uai.ts",
-  "main": "./uai.ts",
-  "version": "1.3.5",
+  "module": "main.ts",
+  "main": "./main.ts",
+  "version": "1.3.6",
   "type": "module",
   "private": false,
   "devDependencies": {

package/test/streaming.test.ts

@@ -1,78 +1,78 @@
 import { test, expect, it, describe } from 'bun:test';
 import { z } from 'zod';
-import { Agent, LLM, ProgressUpdate, StreamingUpdate } from '../uai';
+import { agent, llm, progressupdate, streamingupdate } from '../uai';
 
-describe('UAI Streaming Tests', () => {
+describe('uai streaming tests', () => {
   it('should emit streaming progress updates token-by-token', async () => {
-    const streamingAgent = new Agent({
+    const streamingagent = new agent({
       llm: 'o4-mini-2025-04-16',
-      inputFormat: z.object({
+      inputformat: z.object({
         question: z.string(),
       }),
-      outputFormat: z.object({
+      outputformat: z.object({
         analysis: z.object({
           step1: z.string(), // nested fieild should be named like analysis_step1
           step2: z.string(),
           step3: z.string(),
-        }).describe("Step-by-step analysis of the question"),
-        answer: z.string().describe("The final short concise answer to the question"),
-        status: z.string().describe("just literal word OK"), // to ensure streaming single-word responses
+        }).describe("step-by-step analysis of the question"),
+        answer: z.string().describe("the final short concise answer to the question"),
+        status: z.string().describe("just literal word ok"), // to ensure streaming single-word responses
       }),
       temperature: 0.7,
     });
 
     const input = {
-      question: 'What are the benefits of renewable energy?',
+      question: 'what are the benefits of renewable energy?',
     };
 
-    const streamingUpdates: StreamingUpdate[] = [];
-    const progressUpdates: ProgressUpdate[] = [];
+    const streamingupdates: streamingupdate[] = [];
+    const progressupdates: progressupdate[] = [];
 
     try {
-      const result = await streamingAgent.run(input, (update) => {
+      const result = await streamingagent.run(input, (update) => {
         if (update.stage === 'streaming') {
-          streamingUpdates.push(update as StreamingUpdate);
-          console.log(`Field: ${update.field}, Value: ${update.value}`);
+          streamingupdates.push(update as streamingupdate);
+          console.log(`field: ${update.field}, value: ${update.value}`);
         } else {
-          progressUpdates.push(update);
+          progressupdates.push(update);
         }
       });
 
-      console.log('\n--- Final Result ---');
-      console.log('Analysis:', result.analysis);
-      console.log('Answer:', result.answer);
+      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 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 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');
+      // 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);
+      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 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];
+      // 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());
+      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`);
+      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);
+      console.warn('\n⚠️ streaming test skipped (this is expected if api keys are not configured):', error.message);
     }
   }, { timeout: 60000 });
 });

package/index.ts

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

package/patch

@@ -1,290 +0,0 @@
-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 });
-+});