@mappies/miniwat-agent 0.5.0 → 0.8.0

package/README.md

@@ -1 +1,914 @@
-# miniwat-agent
+# Miniwat Agent
+
+> Build conversational AI applications with OpenAI or AWS Bedrock in
+> just a few lines of code.
+
+The `Agent` class is the main entry point to miniwat. It combines a
+language model, optional system instructions, an optional planner, conversation history, and
+streaming into a simple API.
+
+``` ts
+const model = new OpenAiModel({
+  modelId: "gpt-4.1-mini",
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+const agent = new Agent({ model });
+const session = new Session();
+
+const response = await agent.invoke("Hello!", session);
+
+console.log(response.message.content);
+```
+
+------------------------------------------------------------------------
+
+# Why miniwat?
+
+Most LLM libraries require you to manually:
+
+-   Track conversation history
+-   Send the entire message list every request
+-   Configure streaming
+-   Manage model-specific APIs
+
+With miniwat you work with only three objects:
+
+``` text
+Model
+   ↓
+Agent
+   ↓
+Session
+```
+
+Everything else happens automatically.
+
+------------------------------------------------------------------------
+
+# Installation
+
+``` bash
+npm install @mappies/miniwat-agent
+```
+
+Choose one model implementation.
+
+``` bash
+npm install @mappies/miniwat-provider-openai
+```
+
+or
+
+``` bash
+npm install @mappies/miniwat-provider-bedrock
+```
+
+------------------------------------------------------------------------
+
+# Quick Start
+
+The following example creates an AI assistant using OpenAI. It can be copied directly into a project and run as-is.
+
+```ts
+import { Agent, Session } from "@mappies/miniwat-agent";
+import { OpenAiModel } from "@mappies/miniwat-provider-openai";
+
+async function main() {
+  const model = new OpenAiModel({
+    modelId: "gpt-4.1-mini",
+    apiKey: process.env.OPENAI_API_KEY
+  });
+
+  const agent = new Agent({
+    model,
+    instruction: {
+      system: {
+        value: "You are a helpful assistant."
+      }
+    }
+  });
+
+  const session = new Session();
+
+  const response = await agent.invoke(
+    "Explain what TypeScript is in one paragraph.",
+    session
+  );
+
+  console.log(response.message.content);
+}
+
+main().catch(console.error);
+```
+
+Run the example after setting your OpenAI API key.
+
+**Linux / macOS**
+
+```bash
+export OPENAI_API_KEY=your_api_key
+node app.js
+```
+
+**Windows PowerShell**
+
+```powershell
+$env:OPENAI_API_KEY="your_api_key"
+node app.js
+```
+
+Congratulations! You've built your first miniwat application.
+
+The rest of this guide explains each part of the example in more detail.
+
+------------------------------------------------------------------------
+
+# Your First Agent
+
+## Step 1 --- Create a model
+
+### OpenAI
+
+``` ts
+import { OpenAiModel } from "@mappies/miniwat-provider-openai";
+
+const model = new OpenAiModel({
+  modelId: "gpt-4.1-mini",
+  apiKey: process.env.OPENAI_API_KEY
+});
+```
+
+### AWS Bedrock
+
+``` ts
+import { BedrockModel } from "@mappies/miniwat-provider-bedrock";
+
+const model = new BedrockModel({
+  region: "us-east-1",
+  modelId: "anthropic.claude-3-5-sonnet-20240620-v1:0"
+});
+```
+
+------------------------------------------------------------------------
+
+## Step 2 --- Create an Agent
+
+``` ts
+const agent = new Agent({
+  model
+});
+```
+
+At this point the agent is ready to answer prompts.
+
+Planning is optional. When no planner is configured, the agent sends prompts directly to the model. To enable multi-step planning, provide a planner when creating the agent.
+
+``` ts
+import { DefaultPlanner } from "@mappies/miniwat-agent";
+
+const planner = new DefaultPlanner(model);
+
+const agent = new Agent({
+  model,
+  planner
+});
+```
+
+------------------------------------------------------------------------
+
+## Step 3 --- Create a Session
+
+``` ts
+const session = new Session();
+```
+
+A `Session` stores the conversation history.
+
+Think of it as a chat thread.
+
+Reuse the same session if you want the model to remember previous
+messages.
+
+------------------------------------------------------------------------
+
+## Step 4 --- Ask a question
+
+``` ts
+const response = await agent.invoke(
+  "Explain TypeScript generics.",
+  session
+);
+
+console.log(response.message.content);
+```
+
+That's all you need to build a basic chatbot.
+
+------------------------------------------------------------------------
+
+# Conversation Memory
+
+Every call automatically appends:
+
+1.  your prompt
+2.  the assistant response
+
+to the session.
+
+``` ts
+await agent.invoke("My name is Alice.", session);
+
+await agent.invoke(
+  "What's my name?",
+  session
+);
+```
+
+Because both requests share the same session, the model remembers the
+earlier conversation.
+
+To start over:
+
+``` ts
+const newSession = new Session();
+```
+
+------------------------------------------------------------------------
+
+# Customizing the Assistant
+
+Add a system instruction.
+
+``` ts
+const agent = new Agent({
+  model,
+  instruction: {
+    system: {
+      value: "You are a friendly programming tutor."
+    }
+  }
+});
+```
+
+This instruction is applied automatically to every request.
+
+------------------------------------------------------------------------
+
+# Streaming Responses
+
+For chat applications, streaming provides a better user experience.
+
+``` ts
+const stream = await agent.stream(
+  "Write a short story.",
+  session
+);
+
+stream.on("data", chunk => {
+  process.stdout.write(chunk);
+});
+
+await (stream as any).promise;
+```
+
+The stream promise ensures the completed response is written back into
+the session.
+
+------------------------------------------------------------------------
+
+# Model Options
+
+Pass inference settings per request.
+
+``` ts
+await agent.invoke(prompt, session, {
+  inference: {
+    temperature: 0.2,
+    maxTokens: 800,
+    topP: 0.9
+  }
+});
+```
+
+A temperature of **0.2** is recommended for most assistants.
+
+------------------------------------------------------------------------
+
+# Events
+
+Applications often need progress updates.
+
+``` ts
+await agent.invoke(prompt, session, {
+  event: {
+    onThinking: async text => {
+      console.log(text);
+    },
+
+    onTooling: async message => {
+      console.log(message);
+    },
+
+    onResponse: async message => {
+      console.log(message.content);
+    },
+
+    onPlanUpdated: async plan => {
+      console.log(plan);
+    }
+  }
+});
+```
+
+`onPlanUpdated` is called when a configured planner's plan changes during execution.
+
+Typical uses include:
+
+-   updating a status indicator
+-   logging tool execution
+-   displaying plan execution progress
+-   saving completed responses
+
+------------------------------------------------------------------------
+
+# Building a Chat Loop
+
+``` ts
+while (true) {
+  const response = await agent.invoke(userInput, session);
+
+  console.log(response.message.content);
+}
+```
+
+Notice there is no manual message management.
+
+The session grows automatically.
+
+------------------------------------------------------------------------
+
+# Using MCP Tools
+
+One of miniwat's primary design goals is to make AI agents **safe to use in production**.
+
+Unlike many agent frameworks that allow language models to connect to arbitrary MCP servers, **miniwat takes a security-first approach**. Only **miniwat-approved MCP packages** can be used by an application. MCP packages are **not** downloaded or installed automatically—they must be explicitly installed with `npm` before they can be configured and used.
+
+This explicit opt-in model helps reduce risks such as:
+
+- Executing untrusted code
+- Loading unexpected third-party MCP servers
+- Accessing unauthorized local or network resources
+- Accidentally exposing secrets
+- Server-Side Request Forgery (SSRF)
+- Prompt injection through unsafe tools
+- Data exfiltration
+
+The philosophy is simple:
+
+> **Powerful AI agents require trustworthy tools.**
+
+By requiring applications to explicitly install and configure approved MCP packages, miniwat gives developers complete control over the capabilities exposed to their agents while maintaining a strong security posture.
+
+## Serverless MCP Architecture
+
+miniwat is also designed around a **serverless MCP architecture**.
+
+Rather than communicating with long-running MCP servers over stdio, HTTP, or WebSockets, miniwat executes **functions exported by locally installed npm packages**. This eliminates the need to deploy, monitor, and secure separate MCP server processes, making miniwat a natural fit for modern serverless platforms.
+
+This design provides several advantages:
+
+- **Lower latency** – Tool functions execute directly within your application process.
+- **Simpler deployment** – No MCP servers need to be started or managed.
+- **Reduced operational overhead** – Deploy a single application instead of multiple services.
+- **Improved security** – Only explicitly installed and approved MCP packages can be executed.
+- **Serverless friendly** – Works naturally in environments such as AWS Lambda, Azure Functions, and Google Cloud Functions, where long-running MCP servers are impractical.
+
+Because miniwat executes functions instead of connecting to external MCP servers, it uses its own `mcp.json` format. Rather than describing how to connect to remote servers, the configuration describes:
+
+- which npm package provides the MCP implementation
+- which tool definitions from that package are exposed to the language model
+- which environment variables are required as secrets
+
+This approach keeps MCP configuration simple while making deployments portable, secure, and well suited for serverless applications.
+
+---
+
+## Available MCP Servers
+
+The following MCP servers are currently approved for use with miniwat.
+
+| MCP | npm Package | Description | Repository |
+|-----|-------------|-------------|------------|
+| **Weather** | `@mappies/miniwat-mcp-weather` | Provides weather tools, including current weather and daily forecast lookup. | `https://gitlab.com/mappies/miniwat/mcp/weather` |
+| **Web** | `@mappies/miniwat-mcp-web` | Provides web tools, including web search and safe URL fetching. | `https://gitlab.com/mappies/miniwat/mcp/web` |
+| **Trello** | `@mappies/miniwat-mcp-trello` | Provides Trello tools for boards, lists, cards, labels, members, and workspaces. | `https://gitlab.com/mappies/miniwat/mcp/trello` |
+
+> **Important**
+>
+> miniwat does not download MCP packages automatically. You must install the MCP packages yourself.
+
+```bash
+npm install @mappies/miniwat-mcp-weather
+npm install @mappies/miniwat-mcp-web
+npm install @mappies/miniwat-mcp-trello
+```
+
+---
+
+## miniwat MCP Config Format
+
+miniwat uses its own MCP configuration format.
+
+It does **not** use the standard MCP `mcp.json` format.
+
+A miniwat MCP config uses a top-level `mcpServers` object. Each MCP server entry defines:
+
+- the npm package that provides the MCP implementation
+- the tool definitions to expose to the language model
+- optional `secrets` required by that MCP
+
+Each MCP package may provide many tool definitions. The `tools` array allows you to explicitly choose which tool definitions are exposed to your agent. This follows the principle of least privilege—only the capabilities your application requires are made available to the language model.
+
+For example, the Weather MCP provides both current weather and weather forecast tools. If your application only needs current weather, simply omit the forecast tool from the configuration.
+
+Example `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Weather": {
+      "package": "@mappies/miniwat-mcp-weather",
+      "tools": [
+        {
+          "import": "GET_CURRENT_WEATHER_DEFINITION"
+        },
+        {
+          "import": "GET_WEATHER_FORECAST_DEFINITION"
+        }
+      ]
+    },
+    "Web": {
+      "package": "@mappies/miniwat-mcp-web",
+      "tools": [
+        {
+          "import": "SEARCH_WEB_DEFINITION"
+        },
+        {
+          "import": "FETCH_URL_DEFINITION"
+        }
+      ]
+    },
+    "Trello": {
+      "package": "@mappies/miniwat-mcp-trello",
+      "secrets": [
+        "TRELLO_API_KEY",
+        "TRELLO_TOKEN"
+      ],
+      "tools": [
+        {
+          "import": "LIST_TRELLO_BOARDS_DEFINITION"
+        },
+        {
+          "import": "CREATE_TRELLO_BOARD_DEFINITION"
+        },
+        {
+          "import": "GET_TRELLO_BOARD_DEFINITION"
+        },
+        {
+          "import": "LIST_TRELLO_LISTS_DEFINITION"
+        },
+        {
+          "import": "MOVE_TRELLO_LIST_DEFINITION"
+        },
+        {
+          "import": "GET_TRELLO_CARD_DEFINITION"
+        },
+        {
+          "import": "LIST_TRELLO_LABELS_DEFINITION"
+        },
+        {
+          "import": "UPDATE_CARD_TITLE_DEFINITION"
+        },
+        {
+          "import": "REMOVE_CARD_LABEL_DEFINITION"
+        },
+        {
+          "import": "ADD_CARD_LABEL_DEFINITION"
+        },
+        {
+          "import": "ADD_MEMBER_TO_BOARD_DEFINITION"
+        },
+        {
+          "import": "LIST_TRELLO_CARDS_DEFINITION"
+        },
+        {
+          "import": "LIST_TRELLO_WORKSPACES_DEFINITION"
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Configuring a Model with MCP Tools
+
+In miniwat, MCP tools are passed to the model through the `mcpConfig` option.
+
+For example, import your `mcp.json` file:
+
+```ts
+import mcpConfig from "./mcp.json";
+```
+
+Then pass it to the model provider.
+
+### OpenAI
+
+```ts
+import { OpenAiModel } from "@mappies/miniwat-provider-openai";
+import mcpConfig from "./mcp.json";
+
+const model = new OpenAiModel({
+  modelId: "gpt-4.1-mini",
+  apiKey: process.env.OPENAI_API_KEY,
+  mcpConfig
+});
+```
+
+### AWS Bedrock
+
+```ts
+import { BedrockModel } from "@mappies/miniwat-provider-bedrock";
+import mcpConfig from "./mcp.json";
+
+const model = new BedrockModel({
+  region: "us-east-1",
+  modelId: "your-bedrock-model-id-or-arn",
+  mcpConfig
+});
+```
+
+The provider creates a `ToolDispatcher` internally from the given `mcpConfig`.
+
+---
+
+## Using MCP Tools with Agent
+
+After the model is configured with `mcpConfig`, create an `Agent` normally.
+
+```ts
+import { Agent, Session } from "@mappies/miniwat-agent";
+
+const agent = new Agent({
+  model,
+  instruction: {
+    system: {
+      value: "You are a helpful assistant."
+    }
+  }
+});
+
+const session = new Session();
+
+const response = await agent.invoke(
+  "What's the weather in Blacksburg tomorrow?",
+  session
+);
+
+console.log(response.message.content);
+```
+
+The model can now discover the configured miniwat-approved tools and call them when needed.
+
+---
+
+## Passing Secrets to MCP Servers
+
+Some MCP servers require credentials.
+
+For example, the Trello MCP requires:
+
+```json
+"secrets": [
+  "TRELLO_API_KEY",
+  "TRELLO_TOKEN"
+]
+```
+
+The `secrets` array tells miniwat which environment variables are required by that MCP server.
+
+Do **not** put secret values directly inside `mcp.json`.
+
+Instead, define them as environment variables before starting your application.
+
+### Linux / macOS
+
+```bash
+export TRELLO_API_KEY=your_trello_api_key
+export TRELLO_TOKEN=your_trello_token
+```
+
+### Windows PowerShell
+
+```powershell
+$env:TRELLO_API_KEY="your_trello_api_key"
+$env:TRELLO_TOKEN="your_trello_token"
+```
+
+Your `mcp.json` should only contain the names of the required secrets:
+
+```json
+{
+  "mcpServers": {
+    "Trello": {
+      "package": "@mappies/miniwat-mcp-trello",
+      "secrets": [
+        "TRELLO_API_KEY",
+        "TRELLO_TOKEN"
+      ],
+      "tools": [
+        {
+          "import": "LIST_TRELLO_BOARDS_DEFINITION"
+        }
+      ]
+    }
+  }
+}
+```
+
+This keeps sensitive values out of source control.
+
+---
+
+## Building a Custom MCP Package
+
+A miniwat MCP is simply an **npm package** that exports tool definitions and their corresponding implementation functions.
+
+Unlike traditional MCP implementations, there is no server to run. miniwat loads your package directly and executes the exported functions.
+
+### Package Structure
+
+A simple MCP package might look like this:
+
+```text
+my-mcp/
+├── package.json
+└── src/
+    ├── index.ts
+    └── getRandomNumber.ts
+```
+
+### Export a Tool Definition
+
+Every tool begins with a definition that describes the tool to the language model.
+
+```ts
+export const GET_RANDOM_NUMBER_DEFINITION = {
+  name: "getRandomNumber",
+  description: "Generate a random number between two values.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      min: { type: "number" },
+      max: { type: "number" }
+    },
+    required: ["min", "max"]
+  }
+} as const;
+```
+
+### Export the Tool Function
+
+Each tool definition must have a corresponding exported function whose name exactly matches the definition's `name` property.
+
+The function accepts a **single object parameter**, with properties that match the tool's `inputSchema`. When the language model invokes the tool, miniwat automatically maps the generated JSON arguments to this object and calls your function.
+
+
+```ts
+export async function getRandomNumber({ min, max }: { min: number; max: number; }) {
+  return {
+    value: Math.floor(Math.random() * (max - min + 1)) + min
+  };
+}
+```
+
+### Optional: Input Text Helper
+
+If you want the UI to display status updates while the tool is running, export an input text helper.
+
+```ts
+export function getRandomNumberInputText({ min, max }: { min: number; max: number; }) {
+  return `Generating a random number between ${min} and ${max}.`;
+}
+```
+
+### Export Everything
+
+Export the definitions and functions from your package.
+
+```ts
+export * from "./getRandomNumber";
+```
+
+### Use the Package
+
+Install the package into your application.
+
+```bash
+npm install @your-org/my-mcp
+```
+
+Then expose the desired tool definitions in `mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "Example": {
+      "package": "@your-org/my-mcp",
+      "tools": [
+        {
+          "import": "GET_RANDOM_NUMBER_DEFINITION"
+        }
+      ]
+    }
+  }
+}
+```
+
+Only the tool definitions listed in `mcp.json` are exposed to the language model, allowing you to choose exactly which actions your agent can perform.
+
+---
+
+## Example: Model Provider Factory
+
+A common pattern is to create a model factory that always loads the MCP config.
+
+```ts
+import { Model } from "@mappies/miniwat-agent-core";
+import { BedrockModel } from "@mappies/miniwat-provider-bedrock";
+import { OpenAiModel } from "@mappies/miniwat-provider-openai";
+import mcpConfig from "../mcp.json";
+
+export class ModelProviderFactory {
+  static create(): Model {
+    const options = {
+      mcpConfig
+    };
+
+    if (process.env.OPENAI_API_KEY) {
+      return new OpenAiModel({
+        ...options,
+        modelId: process.env.DEFAULT_OPENAI_MODEL || "gpt-4.1-mini",
+        apiKey: process.env.OPENAI_API_KEY,
+        baseURL: process.env.OPENAI_BASE_URL
+      });
+    }
+
+    return new BedrockModel({
+      ...options,
+      region: process.env.AWS_REGION,
+      modelId: process.env.DEFAULT_BEDROCK_MODEL_ARN || ""
+    });
+  }
+}
+```
+
+Then use the factory when creating your agent.
+
+```ts
+const model = ModelProviderFactory.create();
+
+const agent = new Agent({
+  model,
+  instruction: {
+    system: {
+      value: "You are a helpful assistant."
+    }
+  }
+});
+```
+
+---
+
+## Automatic Tool Execution
+
+Once the model is configured with `mcpConfig`, tool execution is automatic.
+
+For example, if the user asks:
+
+> What's the weather in Blacksburg tomorrow?
+
+The model may invoke the **Weather** MCP.
+
+If the user asks:
+
+> Search the web for the latest TypeScript release notes.
+
+The model may invoke the **Web** MCP.
+
+If the user asks:
+
+> Summarize https://example.com/report.pdf
+
+The model may invoke the **Web** MCP's `fetchUrl` tool.
+
+If the user asks:
+
+> Create a Trello board named Sprint Planning.
+
+The model may invoke the **Trello** MCP.
+
+From your application's perspective, there is nothing special to do.
+
+```ts
+const response = await agent.invoke(prompt, session);
+```
+
+The model provider and `ToolDispatcher` handle the tool workflow:
+
+1. List configured tools from `mcpConfig`.
+2. Send tool definitions to the model.
+3. Let the model choose a tool when needed.
+4. Execute the selected tool.
+5. Send the tool result back to the model.
+6. Continue the conversation.
+7. Return the final response.
+
+---
+
+## Observing Tool Activity
+
+You can observe tool activity with `onTooling`.
+
+```ts
+const response = await agent.invoke(prompt, session, {
+  event: {
+    onThinking: async text => {
+      console.log("Thinking:", text);
+    },
+    onTooling: async message => {
+      console.log("Tool activity:", message);
+    },
+    onResponse: async message => {
+      console.log("Response:", message.content);
+    }
+  }
+});
+```
+
+This is useful for:
+
+- logging tool calls
+- displaying status updates in a UI
+- saving tool call history
+- debugging MCP behavior
+
+------------------------------------------------------------------------
+
+# Which API should I use?
+
+## invoke()
+
+Use when you want the complete response.
+
+``` ts
+await agent.invoke(prompt, session);
+```
+
+## stream()
+
+Use when building chat interfaces.
+
+``` ts
+await agent.stream(prompt, session);
+```
+
+------------------------------------------------------------------------
+
+# Best Practices
+
+-   Create one `Session` per conversation.
+-   Reuse that session until the conversation ends.
+-   Use `stream()` for interactive UIs.
+-   Keep system instructions short and focused.
+-   Use low temperatures for factual assistants.
+
+------------------------------------------------------------------------
+
+# Next Steps
+
+You now know how to:
+
+-   create a model
+-   create an agent
+-   maintain conversations with sessions
+-   customize behavior with instructions
+-   stream responses
+-   receive events
+-   build a chatbot
+
+From here you can integrate miniwat into a CLI, web server, desktop
+application, or WebSocket chat service.