@reminix/runtime 0.0.7 → 0.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @reminix/runtime
 
-Core runtime package for serving AI agents and tools via REST APIs. Provides the `serve()` function, `Agent` class, `tool()` factory, and `AgentAdapter` for building framework integrations.
+Core runtime package for serving AI agents and tools via REST APIs. Provides the `agent()`, `chatAgent()`, and `tool()` factory functions for building and serving AI agents.
 
 Built on [Hono](https://hono.dev) for portability across Node.js, Deno, Bun, and edge runtimes.
 
@@ -15,30 +15,27 @@ npm install @reminix/runtime
 ## Quick Start
 
 ```typescript
-import { serve, Agent } from '@reminix/runtime';
+import { agent, chatAgent, serve } from '@reminix/runtime';
 
-// Create an agent with callbacks
-const agent = new Agent('my-agent');
-
-agent.onInvoke(async (request) => {
-  const task = (request.input as Record<string, string>).task || 'unknown';
-  return { output: `Completed: ${task}` };
+// Create an agent for task-oriented operations
+const calculator = agent('calculator', {
+  description: 'Add two numbers',
+  parameters: {
+    type: 'object',
+    properties: { a: { type: 'number' }, b: { type: 'number' } },
+    required: ['a', 'b'],
+  },
+  execute: async ({ a, b }) => (a as number) + (b as number),
 });
 
-agent.onChat(async (request) => {
-  const userMsg = request.messages[request.messages.length - 1].content;
-  const response = `You said: ${userMsg}`;
-  return {
-    output: response,
-    messages: [
-      ...request.messages,
-      { role: 'assistant', content: response },
-    ],
-  };
+// Create a chat agent for conversational interactions
+const assistant = chatAgent('assistant', {
+  description: 'A helpful assistant',
+  execute: async (messages) => `You said: ${messages.at(-1)?.content}`,
 });
 
-// Serve the agent
-serve({ agents: [agent], port: 8080 });
+// Serve the agents
+serve({ agents: [calculator, assistant], port: 8080 });
 ```
 
 ## How It Works
@@ -49,8 +46,7 @@ The runtime creates a REST server (powered by [Hono](https://hono.dev)) with the
 |----------|--------|-------------|
 | `/health` | GET | Health check |
 | `/info` | GET | Runtime discovery (version, agents, tools) |
-| `/agents/{name}/invoke` | POST | Stateless invocation |
-| `/agents/{name}/chat` | POST | Conversational chat |
+| `/agents/{name}/execute` | POST | Execute an agent |
 | `/tools/{name}/execute` | POST | Execute a tool |
 
 ### Health Endpoint
@@ -73,16 +69,43 @@ Returns runtime information, available agents, and tools:
 {
   "runtime": {
     "name": "reminix-runtime",
-    "version": "0.0.7",
+    "version": "0.0.8",
     "language": "typescript",
     "framework": "hono"
   },
   "agents": [
     {
-      "name": "my-agent",
+      "name": "calculator",
       "type": "agent",
-      "invoke": { "streaming": false },
-      "chat": { "streaming": false }
+      "description": "Add two numbers",
+      "parameters": {
+        "type": "object",
+        "properties": { "a": { "type": "number" }, "b": { "type": "number" } },
+        "required": ["a", "b"]
+      },
+      "output": { "type": "number" },
+      "requestKeys": ["a", "b"],
+      "responseKeys": ["output"],
+      "streaming": false
+    },
+    {
+      "name": "assistant",
+      "type": "chat_agent",
+      "description": "A helpful assistant",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "messages": {
+            "type": "array",
+            "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } }, "required": ["role", "content"] }
+          }
+        },
+        "required": ["messages"]
+      },
+      "output": { "type": "object" },
+      "requestKeys": ["messages"],
+      "responseKeys": ["message"],
+      "streaming": false
     }
   ],
   "tools": [
@@ -97,39 +120,36 @@ Returns runtime information, available agents, and tools:
 }
 ```
 
-### Invoke Endpoint
+### Agent Execute Endpoint
+
+`POST /agents/{name}/execute` - Execute an agent.
 
-`POST /agents/{name}/invoke` - For stateless operations.
+Request keys are defined by the agent's `parameters` schema. For example, a calculator agent with `parameters: { properties: { a, b } }` expects `a` and `b` at the top level:
 
+**Task-oriented agent:**
 ```bash
-curl -X POST http://localhost:8080/agents/my-agent/invoke \
+curl -X POST http://localhost:8080/agents/calculator/execute \
   -H "Content-Type: application/json" \
-  -d '{
-    "input": {
-      "task": "summarize",
-      "text": "Lorem ipsum..."
-    }
-  }'
+  -d '{"a": 5, "b": 3}'
 ```
 
 **Response:**
 ```json
 {
-  "output": "Summary: ..."
+  "output": 8
 }
 ```
 
-### Chat Endpoint
+**Chat agent:**
 
-`POST /agents/{name}/chat` - For conversational interactions.
+Chat agents expect `messages` at the top level and return `message`:
 
 ```bash
-curl -X POST http://localhost:8080/agents/my-agent/chat \
+curl -X POST http://localhost:8080/agents/assistant/execute \
   -H "Content-Type: application/json" \
   -d '{
     "messages": [
-      {"role": "system", "content": "You are helpful"},
-      {"role": "user", "content": "What is the weather?"}
+      {"role": "user", "content": "Hello!"}
     ]
   }'
 ```
@@ -137,17 +157,13 @@ curl -X POST http://localhost:8080/agents/my-agent/chat \
 **Response:**
 ```json
 {
-  "output": "The weather is 72°F and sunny!",
-  "messages": [
-    {"role": "system", "content": "You are helpful"},
-    {"role": "user", "content": "What is the weather?"},
-    {"role": "assistant", "content": "The weather is 72°F and sunny!"}
-  ]
+  "message": {
+    "role": "assistant",
+    "content": "You said: Hello!"
+  }
 }
 ```
 
-The `output` field contains the assistant's response, while `messages` includes the full conversation history.
-
 ### Tool Execute Endpoint
 
 `POST /tools/{name}/execute` - Execute a standalone tool.
@@ -155,11 +171,7 @@ The `output` field contains the assistant's response, while `messages` includes
 ```bash
 curl -X POST http://localhost:8080/tools/get_weather/execute \
   -H "Content-Type: application/json" \
-  -d '{
-    "input": {
-      "location": "San Francisco"
-    }
-  }'
+  -d '{"location": "San Francisco"}'
 ```
 
 **Response:**
@@ -169,9 +181,119 @@ curl -X POST http://localhost:8080/tools/get_weather/execute \
 }
 ```
 
+## Agents
+
+Agents handle requests via the `/agents/{name}/execute` endpoint.
+
+### Task-Oriented Agent
+
+Use `agent()` for task-oriented agents that take structured input and return output:
+
+```typescript
+import { agent, serve } from '@reminix/runtime';
+
+const calculator = agent('calculator', {
+  description: 'Add two numbers',
+  parameters: {
+    type: 'object',
+    properties: {
+      a: { type: 'number' },
+      b: { type: 'number' },
+    },
+    required: ['a', 'b'],
+  },
+  execute: async ({ a, b }) => (a as number) + (b as number),
+});
+
+const textProcessor = agent('text-processor', {
+  description: 'Process text in various ways',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string' },
+      operation: { type: 'string', enum: ['uppercase', 'lowercase'] },
+    },
+    required: ['text'],
+  },
+  execute: async ({ text, operation }) => {
+    const t = text as string;
+    return operation === 'uppercase' ? t.toUpperCase() : t.toLowerCase();
+  },
+});
+
+serve({ agents: [calculator, textProcessor], port: 8080 });
+```
+
+### Chat Agent
+
+Use `chatAgent()` for conversational agents that handle message history:
+
+```typescript
+import { chatAgent, serve } from '@reminix/runtime';
+
+const assistant = chatAgent('assistant', {
+  description: 'A helpful assistant',
+  execute: async (messages) => {
+    const lastMsg = messages.at(-1)?.content ?? '';
+    return `You said: ${lastMsg}`;
+  },
+});
+
+// With context support
+const contextualBot = chatAgent('contextual-bot', {
+  description: 'Bot with context awareness',
+  execute: async (messages, context) => {
+    const userId = context?.user_id ?? 'unknown';
+    return `Hello user ${userId}!`;
+  },
+});
+
+serve({ agents: [assistant, contextualBot], port: 8080 });
+```
+
+### Streaming
+
+Both factories support streaming via async generators. When you use an async generator function, the agent automatically supports streaming:
+
+```typescript
+import { agent, chatAgent, serve } from '@reminix/runtime';
+
+// Streaming task agent
+const streamer = agent('streamer', {
+  description: 'Stream text word by word',
+  parameters: {
+    type: 'object',
+    properties: { text: { type: 'string' } },
+    required: ['text'],
+  },
+  execute: async function* ({ text }) {
+    for (const word of (text as string).split(' ')) {
+      yield word + ' ';
+    }
+  },
+});
+
+// Streaming chat agent
+const streamingAssistant = chatAgent('streaming-assistant', {
+  description: 'Stream responses token by token',
+  execute: async function* (messages) {
+    const response = `You said: ${messages.at(-1)?.content}`;
+    for (const char of response) {
+      yield char;
+    }
+  },
+});
+
+serve({ agents: [streamer, streamingAssistant], port: 8080 });
+```
+
+For streaming agents:
+- `stream: true` in the request → chunks are sent via SSE
+- `stream: false` in the request → chunks are collected and returned as a single response
+
 ## Tools
 
-Tools are standalone functions that can be served via the runtime. They're useful for exposing utility functions, external API integrations, or any reusable logic.
+Tools are standalone functions served via `/tools/{name}/execute`. They're useful for exposing utility functions, external API integrations, or any reusable logic.
 
 ### Creating Tools
 
@@ -190,54 +312,50 @@ const getWeather = tool('get_weather', {
     },
     required: ['location'],
   },
-  // Optional: define output schema for documentation and type inference
   output: {
     type: 'object',
     properties: {
       temp: { type: 'number' },
       condition: { type: 'string' },
-      location: { type: 'string' },
     },
   },
   execute: async (input) => {
     const location = input.location as string;
-    // Call weather API...
     return { temp: 72, condition: 'sunny', location };
   },
 });
 
-// Serve tools (with or without agents)
 serve({ tools: [getWeather], port: 8080 });
 ```
 
-The optional `output` property defines the JSON Schema for the tool's return value. This is included in the `/info` endpoint for documentation and enables better type inference for clients.
-
 ### Serving Agents and Tools Together
 
 You can serve both agents and tools from the same runtime:
 
 ```typescript
-import { Agent, tool, serve } from '@reminix/runtime';
+import { agent, tool, serve } from '@reminix/runtime';
 
-const agent = new Agent('my-agent');
-agent.onInvoke(async (req) => ({ output: 'Hello!' }));
+const summarizer = agent('summarizer', {
+  description: 'Summarize text',
+  parameters: {
+    type: 'object',
+    properties: { text: { type: 'string' } },
+    required: ['text'],
+  },
+  execute: async ({ text }) => (text as string).slice(0, 100) + '...',
+});
 
 const calculator = tool('calculate', {
   description: 'Perform basic math operations',
   parameters: {
     type: 'object',
-    properties: {
-      expression: { type: 'string', description: 'Math expression to evaluate' },
-    },
+    properties: { expression: { type: 'string' } },
     required: ['expression'],
   },
-  execute: async (input) => {
-    const expr = input.expression as string;
-    return { result: eval(expr) }; // Note: use a safe evaluator in production
-  },
+  execute: async (input) => ({ result: eval(input.expression as string) }),
 });
 
-serve({ agents: [agent], tools: [calculator], port: 8080 });
+serve({ agents: [summarizer], tools: [calculator], port: 8080 });
 ```
 
 ## Framework Adapters
@@ -278,6 +396,77 @@ const app = createApp({ agents: [myAgent], tools: [myTool] });
 // Use with any runtime: Node.js, Deno, Bun, Cloudflare Workers, etc.
 ```
 
+### `agent(name, options)`
+
+Factory function to create a task-oriented agent.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Unique identifier for the agent |
+| `options.description` | `string` | Human-readable description |
+| `options.parameters` | `object` | JSON Schema for input parameters |
+| `options.output` | `object` | Optional JSON Schema for output |
+| `options.execute` | `function` | Async function or async generator to execute |
+
+```typescript
+import { agent } from '@reminix/runtime';
+
+// Regular agent
+const myAgent = agent('my-agent', {
+  description: 'Does something useful',
+  parameters: {
+    type: 'object',
+    properties: { input: { type: 'string' } },
+    required: ['input'],
+  },
+  execute: async ({ input }) => ({ result: input }),
+});
+
+// Streaming agent
+const streamingAgent = agent('streaming-agent', {
+  description: 'Streams output',
+  parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  execute: async function* ({ text }) {
+    for (const word of (text as string).split(' ')) {
+      yield word + ' ';
+    }
+  },
+});
+```
+
+### `chatAgent(name, options)`
+
+Factory function to create a chat agent.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Unique identifier for the agent |
+| `options.description` | `string` | Human-readable description |
+| `options.execute` | `function` | Async function or async generator receiving messages |
+
+```typescript
+import { chatAgent } from '@reminix/runtime';
+
+// Regular chat agent
+const bot = chatAgent('bot', {
+  description: 'A simple bot',
+  execute: async (messages) => `You said: ${messages.at(-1)?.content}`,
+});
+
+// With context
+const contextBot = chatAgent('context-bot', {
+  execute: async (messages, context) => `Hello ${context?.user_id}!`,
+});
+
+// Streaming chat agent
+const streamingBot = chatAgent('streaming-bot', {
+  execute: async function* (messages) {
+    yield 'Hello';
+    yield ' world!';
+  },
+});
+```
+
 ### `tool(name, options)`
 
 Factory function to create a tool.
@@ -287,6 +476,7 @@ Factory function to create a tool.
 | `name` | `string` | Unique identifier for the tool |
 | `options.description` | `string` | Human-readable description |
 | `options.parameters` | `object` | JSON Schema for input parameters |
+| `options.output` | `object` | Optional JSON Schema for output |
 | `options.execute` | `function` | Async function to execute when called |
 
 ```typescript
@@ -296,150 +486,136 @@ const myTool = tool('my_tool', {
   description: 'Does something useful',
   parameters: {
     type: 'object',
-    properties: {
-      input: { type: 'string' },
-    },
+    properties: { input: { type: 'string' } },
     required: ['input'],
   },
-  execute: async (input) => {
-    return { result: input.input };
-  },
+  execute: async (input) => ({ result: input.input }),
 });
 ```
 
-### `Agent`
+### Request/Response Types
+
+```typescript
+// Request: top-level keys based on agent's requestKeys (derived from parameters)
+// For a calculator agent with parameters { a: number, b: number }:
+interface CalculatorRequest {
+  a: number;                          // Top-level key from parameters
+  b: number;                          // Top-level key from parameters
+  stream?: boolean;                   // Whether to stream the response
+  context?: Record<string, unknown>;  // Optional metadata
+}
 
-Concrete class for building agents with callbacks.
+// For a chat agent:
+interface ChatRequest {
+  messages: Message[];                // Top-level key (requestKeys: ['messages'])
+  stream?: boolean;
+  context?: Record<string, unknown>;
+}
+
+// Response: keys based on agent's responseKeys
+// Regular agent (responseKeys: ['output']):
+interface AgentResponse {
+  output: unknown;
+}
+
+// Chat agent (responseKeys: ['message']):
+interface ChatResponse {
+  message: { role: string; content: string };
+}
+```
+
+## Advanced
+
+### Agent Class
+
+For more control, you can use the `Agent` class directly:
 
 ```typescript
-import { Agent } from '@reminix/runtime';
+import { Agent, serve } from '@reminix/runtime';
 
 const agent = new Agent('my-agent', { metadata: { version: '1.0' } });
 
-agent.onInvoke(async (request) => {
+agent.onExecute(async (request) => {
   return { output: 'Hello!' };
 });
 
-agent.onChat(async (request) => {
-  return { output: 'Hi!', messages: [...] };
-});
-
-// Optional: streaming handlers
-agent.onInvokeStream(async function* (request) {
-  yield '{"chunk": "Hello"}';
-  yield '{"chunk": " world!"}';
+// Optional: streaming handler
+agent.onExecuteStream(async function* (request) {
+  yield 'Hello';
+  yield ' world!';
 });
 
-agent.onChatStream(async function* (request) {
-  yield '{"chunk": "Hi"}';
-});
+serve({ agents: [agent], port: 8080 });
 ```
 
-| Method | Description |
-|--------|-------------|
-| `onInvoke(fn)` | Register invoke handler, returns `this` for chaining |
-| `onChat(fn)` | Register chat handler, returns `this` for chaining |
-| `onInvokeStream(fn)` | Register streaming invoke handler |
-| `onChatStream(fn)` | Register streaming chat handler |
-| `toHandler()` | Returns a web-standard fetch handler for serverless |
-
-### `agent.toHandler()`
+### Tool Class
 
-Returns a web-standard `(Request) => Promise<Response>` handler for serverless deployments.
+For programmatic tool creation:
 
 ```typescript
-// Vercel Edge Function
-import { Agent } from '@reminix/runtime';
-
-const agent = new Agent('my-agent');
-agent.onInvoke(async (req) => ({ output: 'Hello!' }));
+import { Tool, serve } from '@reminix/runtime';
 
-export const POST = agent.toHandler();
-export const GET = agent.toHandler();
-
-// Cloudflare Workers
-export default { fetch: agent.toHandler() };
-
-// Deno Deploy
-Deno.serve(agent.toHandler());
+const myTool = new Tool('get_weather', {
+  description: 'Get weather for a location',
+  parameters: {
+    type: 'object',
+    properties: { location: { type: 'string' } },
+    required: ['location'],
+  },
+  execute: async (input) => ({ temp: 72, location: input.location }),
+});
 
-// Bun
-Bun.serve({ fetch: agent.toHandler() });
+serve({ tools: [myTool], port: 8080 });
 ```
 
-### `AgentAdapter`
+### AgentAdapter
 
-Abstract base class for framework adapters. Use this when wrapping an existing AI framework.
+For building framework integrations. See the [framework adapter packages](#framework-adapters) for examples.
 
 ```typescript
-import { AgentAdapter, InvokeRequest, InvokeResponse, ChatRequest, ChatResponse } from '@reminix/runtime';
+import { AgentAdapter } from '@reminix/runtime';
 
 class MyFrameworkAdapter extends AgentAdapter {
-  // Adapter name shown in /info endpoint
   static adapterName = 'my-framework';
-  
-  // AgentAdapter defaults both to true; override if your adapter doesn't support streaming
-  // override readonly invokeStreaming = false;
-  // override readonly chatStreaming = false;
-
-  private client: MyFrameworkClient;
-  private _name: string;
 
-  constructor(client: MyFrameworkClient, name = 'my-framework') {
+  constructor(private client: MyClient, private _name = 'my-framework') {
     super();
-    this.client = client;
-    this._name = name;
   }
 
-  get name(): string {
+  get name() {
     return this._name;
   }
 
-  async invoke(request: InvokeRequest): Promise<InvokeResponse> {
-    // Pass input to your framework
+  async execute(request) {
     const result = await this.client.run(request.input);
     return { output: result };
   }
-
-  async chat(request: ChatRequest): Promise<ChatResponse> {
-    // Convert messages and call your framework
-    const result = await this.client.chat(request.messages);
-    return {
-      output: result,
-      messages: [...request.messages, { role: 'assistant', content: result }],
-    };
-  }
-}
-
-// Optional: provide a wrap() factory function
-export function wrap(client: MyFrameworkClient, name = 'my-framework'): MyFrameworkAdapter {
-  return new MyFrameworkAdapter(client, name);
 }
 ```
 
-### Request/Response Types
+### Serverless Deployment
+
+Use `toHandler()` for serverless deployments:
 
 ```typescript
-interface InvokeRequest {
-  input: Record<string, unknown>;  // Arbitrary input for task execution
-  stream?: boolean;                // Whether to stream the response
-  context?: Record<string, unknown>;  // Optional metadata
-}
+import { agent } from '@reminix/runtime';
 
-interface InvokeResponse {
-  output: unknown;                 // The result (can be any type)
-}
+const myAgent = agent('my-agent', {
+  execute: async ({ task }) => `Completed: ${task}`,
+});
 
-interface ChatRequest {
-  messages: Message[];             // Conversation history
-  stream?: boolean;                // Whether to stream the response
-  context?: Record<string, unknown>;  // Optional metadata
-}
+// Vercel Edge Function
+export const POST = myAgent.toHandler();
+export const GET = myAgent.toHandler();
 
-interface ChatResponse {
-  output: string;                  // The final answer
-  messages: Message[];             // Full execution history
-}
+// Cloudflare Workers
+export default { fetch: myAgent.toHandler() };
+
+// Deno Deploy
+Deno.serve(myAgent.toHandler());
+
+// Bun
+Bun.serve({ fetch: myAgent.toHandler() });
 ```
 
 ## Deployment