@atgs/tapeworm 0.1.7 → 0.1.9

package/dist/agent/agent.d.ts

@@ -1,20 +1,81 @@
+/**
+ * The Agent module contains all things related to Agents, including:
+ * - the Agent class
+ * - the AgentBuilder class
+ * - the default callback handler for an Agent.
+ *
+ * This module contains most of the business logic for running the main agent loop.
+ *
+ * @module
+ */
 import Conversation, { ConversationManager } from "../conversation/conversation";
 import Message from "../conversation/message";
 import { type Model } from "../model/model";
 import type Tool from "../tool/tool";
 import type ToolCall from "../tool/toolCall";
 /**
- * Coordinates a model, its tools, and the running conversation to fulfill user queries.
+ * Agents combine a model with your tools.
+ *
+ * To build an agent, use the AgentBuilder class:
+ *
+ * ```ts
+ * const agent = Agent.builder()
+ *  .name("yourAgent")
+ *  .tools([new YourTool()])
+ *  .systemPrompt("You are an agent.")
+ *  .model(yourModel)
+ *  .build();
+ * ```
+ *
  */
 export default class Agent {
+    /**
+     * The name of the agent.
+     */
     name: string;
+    /**
+     * The system prompt (if any) for the agent.
+     */
     systemPrompt?: string;
+    /**
+     * The tools this agent knows about and can run.
+     */
     tools: Tool[];
+    /**
+     * The underlying model for the agent.
+     */
     model: Model;
+    /**
+     * The conversation for the agent.
+     * You do not normally need to set this parameter unless you are building a use case
+     * where you have a persistent session with an agent.
+     */
     conversation: Conversation;
+    /**
+     * The conversation manager for the agent.
+     * Normally, a converstation manager that does nothing will be used.
+     * When SummarizingConversationManager or RAGConversationManager is implemented, these will help you avoid
+     * token overflow.
+     */
     conversationManager?: ConversationManager;
-    toolNameToIndexMap: any | undefined;
+    /**
+     * A cache for looking up tools in the Tools array.
+     * DO NOT MANUALLY SET THIS VALUE. AGENT AUTOMATICALLY TAKES CARE OF IT.
+     */
+    private toolNameToIndexMap;
+    /**
+     * The callback function, invoked for every response from the model.
+     * The default implementation just prints to std.out or your console.
+     */
     callback: (m: Message) => void;
+    /**
+     * This is the constructor for an Agent.
+     *
+     * i IMPLORE YOU not to use this method. You CAN, but you should be using the Builder instead
+     * for the best results, as this method WILL change with future updates.
+     *
+     * Builder will be a lot more stable and will always be backwards compatible.
+     */
     constructor(name: string, tools: Tool[], model: Model, conversationManager: ConversationManager, callback: (m: Message) => void);
     /**
      * Run the full agent loop for a user query: seed the conversation, invoke the model,
@@ -39,9 +100,12 @@ export default class Agent {
      * Build a lookup from tool name to index for efficient resolution of tool calls.
      */
     generateToolNameToIndexMap(): void;
+    /**
+     * Get a builder to build an Agent.
+     */
     static builder(): AgentBuilder;
 }
-declare class AgentBuilder {
+export declare class AgentBuilder {
     _name: string;
     _systemPrompt?: string;
     _tools: Tool[];
@@ -50,14 +114,45 @@ declare class AgentBuilder {
     _conversationManager: ConversationManager;
     _toolNameToIndexMap: any | undefined;
     _callback: (m: Message) => void;
+    /**
+     * Set the name of the agent.
+     */
     name(name: string): AgentBuilder;
+    /**
+     * Set the system prompt of the agent.
+     */
     systemPrompt(systemPrompt: string | undefined): AgentBuilder;
+    /**
+     * Set the tools of the agent, if you already have an array of tools.
+     */
     tools(tools: Tool[]): AgentBuilder;
+    /**
+     * Add a tool, 1 by 1, to the agent..
+     */
     addTool(tool: Tool): AgentBuilder;
+    /**
+     * Set the underlying model for the agent.
+     */
     model(model: Model): AgentBuilder;
+    /**
+     * Set the conversation manager for the agent.
+     */
     conversationManager(mgr: ConversationManager): AgentBuilder;
+    /**
+     * Set the callback for the agent.
+     */
     callback(callback: (m: Message) => void): AgentBuilder;
+    /**
+     * Build the agent.
+     */
     build(): Agent;
 }
+/**
+ * This function is Tapeworm's default callback function.
+ * If you do not specify your own callback function, then this will be called and all
+ * it will do is log output to the screen.
+ *
+ * You can override this per invocation or on the Agent itself to do other things
+ * with the LLM output.
+ */
 export declare function defaultCallback(m: Message): void;
-export {};

package/dist/conversation/conversation.d.ts

@@ -1,7 +1,20 @@
+/**
+ * The Conversation module contains the Conversation class and the ConversationManager prototypes.
+ *
+ * The Conversation is a wrapper around both a manager and an array of messages.
+ *
+ * The Conversation Manager is an object that can perform operations on only the conversation.
+ *
+ * While no Conversation Managers have been implemented yet, they will allow resilience to overflowing context windows.
+ *
+ * @module
+ */
 import type { Message } from "..";
 import type { Model } from "../model/model";
 /**
- * Maintains ordered chat messages and delegates to a conversation manager for compaction.
+ * A Conversation holds an array of messages and its associated manager.
+ *
+ * Conversations are (mostly) immutable, until the manager steps in and compacts the conversation.
  */
 export default class Conversation {
     messages: Message[];
@@ -17,7 +30,7 @@ export default class Conversation {
     append(message: Message): void;
 }
 /**
- * Strategy interface for pruning or transforming a conversation history.
+ * Interface for compacting a Conversation. Future implementations can summarize or do RAG-based compaction
  */
 export declare class ConversationManager {
     /**

package/dist/conversation/message.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The Messages module contains all the shapes that make up a single Message.
+ * - The actual Message class, which is a role + an array of MessageComponents
+ *   - And a builder, too, which you should use 99.999% of the time!
+ * - An enum called MessageComponentType
+ * - The MessageComponents
+ *   - **Content** - normal text from the LLM
+ *   - **Thinking** - chain-of-thought reasoning from the LLM
+ *   - **ToolCall** is not technically contained here, but it is a message component type
+ *   - **ToolResult** - encodes the result of a tool call.
+ * @module
+ */
 import type ToolCall from "../tool/toolCall";
 /**
  * Messages are the units of a Conversation

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The index module gathers the exports from Tapeworm.
+ *
+ * This file should be modified when new classes are introduced to Tapeworm
+ *
+ * @module
+ */
 export { default as Agent } from "./agent/agent";
 export { default as Conversation, ConversationManager, DefaultConversationManager, } from "./conversation/conversation";
 export { Model, ModelRequest, ModelRequestBuilder } from "./model/model";

package/dist/model/OllamaModel.d.ts

@@ -1,8 +1,18 @@
+/**
+ * Tapeworm's first mostly-working model is OllamaModel,
+ * which routes model requests to an Ollama endpoint on your local machine.
+ *
+ * Other Models will be housed in separate NPM packages to allow better portability
+ * and to leverage the existing NPM packages (for example, the AWS SDK in the case of Bedrock)
+ * for those models.
+ *
+ * @module
+ */
 import { Message } from "..";
 import ToolCall from "../tool/toolCall";
 import { Model, ModelRequest } from "./model";
 /**
- * Model adapter that translates between Tapeworm message/tool shapes and the Ollama chat API.
+ * The Ollama Model class. This translates between Tapeworm message/tool shapes and the Ollama chat API.
  */
 export default class OllamaModel extends Model {
     endpoint: string;

package/dist/model/model.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The Model module lays out the interface for a Tapeworm model.
+ *
+ * It contains the base Model class, which doesn't do anything other than throw errors and specify an interface,
+ * and also the ModelRequest and ModelRequestBuilder classes, which show what kind of shape a model expects to
+ * recieve upon invocation.
+ *
+ *
+ * @module
+ */
 import type Message from "../conversation/message";
 import type Tool from "../tool/tool";
 /**

package/dist/tapeworm.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class w{messages;manager;constructor(){this.messages=[],this.manager=new g}append(e){this.messages.push(e),this.messages=this.manager.compact(this.messages)}}class M{compact(e){throw new y("No implementation for conversation manager!")}configure(e){throw new y("No implementation for conversation manager!")}}class g extends M{compact(e){return e}configure(e){}}class y extends Error{constructor(e){super(e),this.name="ConversationManagerNotImplemented"}}class u{role;content;constructor(e,s){this.role=e,this.content=s}static builder(){return new b}filter(e){return this.content.filter(s=>s.getMessageComponentType()==e)}}class b{_role;_content;role(e){return this._role=e,this}init(){this._content==null&&(this._content=[])}toolCall(e){return e==null?this:(this.init(),this._content.push(e),this)}toolCalls(e){if(e==null)return this;this.init();for(const s of e)this._content.push(s);return this}toolResult(e){return e==null?this:(this.init(),this._content.push(e),this)}thinking(e){return e==null?this:(this.init(),this._content.push(C.of(e)),this)}content(e){return e==null?this:(this.init(),this._content.push(N.of(e)),this)}build(){if(this._content==null||this._content.length==0)throw new Error("Role-only messages are not supported by Tapeworm.");return new u(this._role,this._content)}}const l={Content:"content",Thinking:"thinking",ToolCall:"toolcall",ToolResult:"toolresult"};class m{getMessageComponentType(){throw new Error("Message components that do not have a message component type are not allowed.")}}class N extends m{text;constructor(e){super(),this.text=e}getMessageComponentType(){return l.Content}get(){return this.text}static of(e){return new this(e)}}class C extends m{thought;constructor(e){super(),this.thought=e}getMessageComponentType(){return l.Thinking}get(){return this.thought}static of(e){return new this(e)}}class c extends m{id;toolName;toolResult;constructor(e,s,o){super(),this.id=e,this.toolName=s,this.toolResult=o}getMessageComponentType(){return l.ToolResult}static of(e,s){return new this(e.id,e.name,s)}}class P{async invoke(e){throw new v("The invoke function for this model was not correctly implemented.")}tokenLimit(){throw new v("The tokenLimit function for this model was not correctly implemented.")}}class q{messages;tools;constructor(e,s){this.messages=e,this.tools=s}static builder(){return new f}}class f{_messages;_tools;messages(e){return this._messages=e,this}tools(e){return this._tools=e,this}build(){if(this._tools==null&&(this._tools=[]),this._messages==null)throw new j("Requests to the model should include content.");return new q(this._messages,this._tools)}}class v extends Error{constructor(e){super(e),this.name="ModelNotImplementedError"}}class j extends Error{constructor(e){super(e),this.name="MessagesNotDefinedError"}}class _ extends m{sequence;name;parameters;type;id;getMessageComponentType(){return l.ToolCall}constructor(e,s,o,n,r){super(),this.sequence=e,this.name=s,this.parameters=o,this.type=n,this.id=r}static builder(){return new x}}class x{_sequence;_name;_parameters;_type;_id;sequence(e){return this._sequence=e,this}name(e){return this._name=e,this}parameters(e){return this._parameters=e,this}type(e){return this._type=e,this}id(e){return e!=null&&(this._id=e),this}build(){return this._sequence==null&&(this._sequence=0),this._id==null&&(this._id=(Math.random()+1).toString(36).slice(2,7)),new _(this._sequence,this._name,this._parameters,this._type,this._id)}}class D extends Error{constructor(e){super(e),this.name="ToolNotFoundError"}}class k{name;systemPrompt;tools;model;conversation;conversationManager;toolNameToIndexMap;callback;constructor(e,s,o,n,r){this.name=e,this.model=o,this.conversationManager=n,this.tools=s,this.callback=r,this.conversationManager.configure(o)}async invoke(e,s=this.callback){this.conversation==null&&(this.conversation=new w,this.conversationManager!=null&&(this.conversation.manager=this.conversationManager),this.systemPrompt!=null&&this.conversation.append(u.builder().role("system").content(this.systemPrompt).build())),this.conversation.append(u.builder().role("user").content(e).build());let o=!1;for(;!o;){let n=await this._runQuery();s(n),this.conversation.append(n),o=!0;const r=n.filter(l.ToolCall);if(r!=null&&r.length!=0){o=!1,r.sort((a,i)=>(a.sequence??0)<(i.sequence??0)?-1:1);for(let a of r)await this._runTool(a)}}}async _runQuery(){return await this.model.invoke(new f().messages(this.conversation?.messages).tools(this.tools).build())}async _runTool(e){if(this.generateToolNameToIndexMap(),!(e.name in this.toolNameToIndexMap)){this.conversation.append(u.builder().role("tool").toolResult(c.of(e,new D("Agent does not have a tool with this name."))).build());return}let s=this.tools[this.toolNameToIndexMap[e.name]];try{let o=await s.execute(e.parameters);this.conversation.append(u.builder().role("tool").toolResult(c.of(e,o)).build())}catch(o){this.conversation.append(u.builder().role("tool").toolResult(c.of(e,JSON.stringify(o))).build())}}generateToolNameToIndexMap(){if(this.toolNameToIndexMap==null){this.toolNameToIndexMap={};for(let e=0;e<this.tools.length;e++)this.toolNameToIndexMap[this.tools[e].getName()]=e}}static builder(){return new A}}class A{_name;_systemPrompt;_tools;_model;_conversation;_conversationManager=new g;_toolNameToIndexMap;_callback=e=>J(e);name(e){return this._name=e,this}systemPrompt(e){return this._systemPrompt=e,this}tools(e){return this._tools=e,this}addTool(e){return this._tools==null&&(this._tools=[]),this._tools.push(e),this}model(e){return this._model=e,this}conversationManager(e){return this._conversationManager=e,this}callback(e){return this._callback=e,this}build(){let e=new k(this._name,this._tools,this._model,this._conversationManager,this._callback);return this._conversation!=null&&(e.conversation=this._conversation),this._systemPrompt!=null&&(e.systemPrompt=this._systemPrompt),e}}function J(t){for(const e of t.filter(l.Thinking))console.log("\x1B[90m"+e.get()+"\x1B[0m");for(const e of t.filter(l.Content))console.log(e.get());for(const e of t.filter(l.ToolCall))console.log("\x1B[32mCalling Tool: "+e.name+"\x1B[0m")}class d extends Error{constructor(e){super(e),this.name="ToolNotDefinedError"}}class F{name;description;tool_schema;constructor(){this.name=this.getName(),this.description=this.getDescription(),this.tool_schema=this.getToolSchema()}getName(){throw new d("Tool name not defined.")}getDescription(){throw new d("Tool description not defined.")}getToolSchema(){throw new d("Tool parameter schema not defined.")}execute(e){return null}}class p{parameters;output;constructor(e,s){this.parameters=e,this.output=s}static builder(){return new O}}class O{_parameters;_output;addParameter(e){return this._parameters==null&&(this._parameters=[]),this._parameters.push(e),this}output(e){return this._output=e,this}build(){return this._parameters==null&&(this._parameters=[]),new p(this._parameters,this._output)}}class T{name;description;type;required;constructor(e,s,o,n){this.name=e,this.description=s,this.type=o,this.required=n,this.assertValidType()}assertValidType(){}static builder(){return new S}}class S{_name;_description;_type;_required;name(e){return this._name=e,this}description(e){return this._description=e,this}type(e){return this._type=e,this}required(e){return this._required=e,this}build(){return this._required==null&&(this._required=!1),new T(this._name,this._description,this._type,this._required)}}class L extends P{endpoint;model;options;constructor(e,s,o){super(),this.endpoint=e,this.model=s,this.options=o}async invoke(e){let s={model:this.model,messages:this._formatMessages(e),tools:this._formatTools(e),...this.options},o=await fetch(this.endpoint+"/api/chat",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)});if(!o.ok)throw new Error(`HTTP error! status: ${o.status}`);let n=await o.json(),r=[];if(n.message.tool_calls)for(let a in n.message.tool_calls){const i=n.message.tool_calls[a];let h="function",R=i[h]?.name,E=i[h]?.index,B=i.id??void 0,I=typeof i[h]?.arguments=="string"?JSON.parse(i[h]?.arguments):i[h]?.arguments;r.push(_.builder().name(R).type(h).parameters(I).sequence(E).id(B).build())}return u.builder().toolCalls(r).role(n.message.role).content(n.message.content).thinking(n.message.thinking).build()}_formatTools(e){let s=[];for(let o of e.tools){let n={},r=[];for(let i of o.getToolSchema().parameters)n[i.name]={},n[i.name].type=i.type,n[i.name].description=i.description,i.required&&r.push(i.name);let a={type:"function",function:{name:o.getName(),description:o.getDescription(),parameters:{type:"object",properties:n,required:r}}};s.push(a)}return s}_formatMessages(e){let s=[];for(let o of e.messages){if(o.role=="assistant"||o.role=="system"||o.role=="user"){s.push(this._formatSingleMessage(o));continue}if(o.role=="tool"){for(const n of o.content)if(n.getMessageComponentType()==l.ToolResult){const r=n;s.push({role:o.role,name:r.toolName,content:JSON.stringify(r.toolResult)})}}}return s}_formatSingleMessage(e){let s={role:e.role},o,n,r;for(const a of e.content){if(a.getMessageComponentType()==l.Content){const i=a;o==null&&(o=""),o+=i.get()}if(a.getMessageComponentType()==l.Thinking){const i=a;r==null&&(r=""),r+=i.get()}if(a.getMessageComponentType()==l.ToolCall){const i=a;n==null&&(n=[]),n.push(this._formatToolCall(i))}}return o!=null&&(s.content=o),n!=null&&(s.tool_calls=n),r!=null&&(s.thinking=r),s}_formatToolCall(e){return{function:{name:e.name,arguments:e.parameters}}}}function Q(t){return e=>{e.prototype.getName=()=>t}}function V(t){return e=>{Object.defineProperty(e.prototype,"getDescription",{value:function(){return t},enumerable:!0,configurable:!0,writable:!0})}}function H(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParams.push(T.builder().name(t.name).description(t.description).required(t.required).type(t.type).build()),e.prototype.getToolSchema=()=>new p(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}function K(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParamsOutput=t,e.prototype.getToolSchema=()=>new p(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}exports.Agent=k;exports.Content=N;exports.Conversation=w;exports.ConversationManager=M;exports.DefaultConversationManager=g;exports.Message=u;exports.MessageBuilder=b;exports.MessageComponent=m;exports.MessageComponentType=l;exports.Model=P;exports.ModelRequest=q;exports.ModelRequestBuilder=f;exports.OllamaModel=L;exports.Parameter=T;exports.ParameterBuilder=S;exports.Thinking=C;exports.Tool=F;exports.ToolCall=_;exports.ToolCallBuilder=x;exports.ToolDescription=V;exports.ToolName=Q;exports.ToolOutput=K;exports.ToolParameter=H;exports.ToolResult=c;exports.ToolSchema=p;exports.ToolSchemaBuilder=O;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});class w{messages;manager;constructor(){this.messages=[],this.manager=new g}append(e){this.messages.push(e),this.messages=this.manager.compact(this.messages)}}class M{compact(e){throw new T("No implementation for conversation manager!")}configure(e){throw new T("No implementation for conversation manager!")}}class g extends M{compact(e){return e}configure(e){}}class T extends Error{constructor(e){super(e),this.name="ConversationManagerNotImplemented"}}class u{role;content;constructor(e,s){this.role=e,this.content=s}static builder(){return new b}filter(e){return this.content.filter(s=>s.getMessageComponentType()==e)}}class b{_role;_content;role(e){return this._role=e,this}init(){this._content==null&&(this._content=[])}toolCall(e){return e==null?this:(this.init(),this._content.push(e),this)}toolCalls(e){if(e==null)return this;this.init();for(const s of e)this._content.push(s);return this}toolResult(e){return e==null?this:(this.init(),this._content.push(e),this)}thinking(e){return e==null?this:(this.init(),this._content.push(N.of(e)),this)}content(e){return e==null?this:(this.init(),this._content.push(C.of(e)),this)}build(){if(this._content==null||this._content.length==0)throw new Error("Role-only messages are not supported by Tapeworm.");return new u(this._role,this._content)}}const l={Content:"content",Thinking:"thinking",ToolCall:"toolcall",ToolResult:"toolresult"};class m{getMessageComponentType(){throw new Error("Message components that do not have a message component type are not allowed.")}}class C extends m{text;constructor(e){super(),this.text=e}getMessageComponentType(){return l.Content}get(){return this.text}static of(e){return new this(e)}}class N extends m{thought;constructor(e){super(),this.thought=e}getMessageComponentType(){return l.Thinking}get(){return this.thought}static of(e){return new this(e)}}class c extends m{id;toolName;toolResult;constructor(e,s,o){super(),this.id=e,this.toolName=s,this.toolResult=o}getMessageComponentType(){return l.ToolResult}static of(e,s){return new this(e.id,e.name,s)}}class P{async invoke(e){throw new v("The invoke function for this model was not correctly implemented.")}tokenLimit(){throw new v("The tokenLimit function for this model was not correctly implemented.")}}class q{messages;tools;constructor(e,s){this.messages=e,this.tools=s}static builder(){return new f}}class f{_messages;_tools;messages(e){return this._messages=e,this}tools(e){return this._tools=e,this}build(){if(this._tools==null&&(this._tools=[]),this._messages==null)throw new j("Requests to the model should include content.");return new q(this._messages,this._tools)}}class v extends Error{constructor(e){super(e),this.name="ModelNotImplementedError"}}class j extends Error{constructor(e){super(e),this.name="MessagesNotDefinedError"}}class _ extends m{sequence;name;parameters;type;id;getMessageComponentType(){return l.ToolCall}constructor(e,s,o,r,n){super(),this.sequence=e,this.name=s,this.parameters=o,this.type=r,this.id=n}static builder(){return new x}}class x{_sequence;_name;_parameters;_type;_id;sequence(e){return this._sequence=e,this}name(e){return this._name=e,this}parameters(e){return this._parameters=e,this}type(e){return this._type=e,this}id(e){return e!=null&&(this._id=e),this}build(){return this._sequence==null&&(this._sequence=0),this._id==null&&(this._id=(Math.random()+1).toString(36).slice(2,7)),new _(this._sequence,this._name,this._parameters,this._type,this._id)}}class D extends Error{constructor(e){super(e),this.name="ToolNotFoundError"}}class k{name;systemPrompt;tools;model;conversation;conversationManager;toolNameToIndexMap;callback;constructor(e,s,o,r,n){this.name=e,this.model=o,this.conversationManager=r,this.tools=s,this.callback=n,this.conversationManager.configure(o)}async invoke(e,s=this.callback){this.conversation==null&&(this.conversation=new w,this.conversationManager!=null&&(this.conversation.manager=this.conversationManager),this.systemPrompt!=null&&this.conversation.append(u.builder().role("system").content(this.systemPrompt).build())),this.conversation.append(u.builder().role("user").content(e).build());let o=!1;for(;!o;){let r=await this._runQuery();s(r),this.conversation.append(r),o=!0;const n=r.filter(l.ToolCall);if(n!=null&&n.length!=0){o=!1,n.sort((a,i)=>(a.sequence??0)<(i.sequence??0)?-1:1);for(let a of n)await this._runTool(a)}}}async _runQuery(){return await this.model.invoke(new f().messages(this.conversation?.messages).tools(this.tools).build())}async _runTool(e){if(this.generateToolNameToIndexMap(),!(e.name in this.toolNameToIndexMap)){this.conversation.append(u.builder().role("tool").toolResult(c.of(e,new D("Agent does not have a tool with this name."))).build());return}let s=this.tools[this.toolNameToIndexMap[e.name]];try{let o=await s.execute(e.parameters);this.conversation.append(u.builder().role("tool").toolResult(c.of(e,o)).build())}catch(o){this.conversation.append(u.builder().role("tool").toolResult(c.of(e,JSON.stringify(o))).build())}}generateToolNameToIndexMap(){if(this.toolNameToIndexMap==null){this.toolNameToIndexMap={};for(let e=0;e<this.tools.length;e++)this.toolNameToIndexMap[this.tools[e].getName()]=e}}static builder(){return new A}}class A{_name;_systemPrompt;_tools;_model;_conversation;_conversationManager=new g;_toolNameToIndexMap;_callback=e=>J(e);name(e){return this._name=e,this}systemPrompt(e){return this._systemPrompt=e,this}tools(e){return this._tools=e,this}addTool(e){return this._tools==null&&(this._tools=[]),this._tools.push(e),this}model(e){return this._model=e,this}conversationManager(e){return this._conversationManager=e,this}callback(e){return this._callback=e,this}build(){let e=new k(this._name,this._tools,this._model,this._conversationManager,this._callback);return this._conversation!=null&&(e.conversation=this._conversation),this._systemPrompt!=null&&(e.systemPrompt=this._systemPrompt),e}}function J(t){for(const e of t.filter(l.Thinking))console.log("\x1B[90m"+e.get()+"\x1B[0m");for(const e of t.filter(l.Content))console.log(e.get());for(const e of t.filter(l.ToolCall))console.log("\x1B[32mCalling Tool: "+e.name+"\x1B[0m")}class d extends Error{constructor(e){super(e),this.name="ToolNotDefinedError"}}class F{getName(){throw new d("Tool name not defined.")}getDescription(){throw new d("Tool description not defined.")}getToolSchema(){throw new d("Tool parameter schema not defined.")}execute(e){return null}}class p{parameters;output;constructor(e,s){this.parameters=e,this.output=s}static builder(){return new O}}class O{_parameters;_output;addParameter(e){return this._parameters==null&&(this._parameters=[]),this._parameters.push(e),this}output(e){return this._output=e,this}build(){return this._parameters==null&&(this._parameters=[]),new p(this._parameters,this._output)}}class y{name;description;type;required;constructor(e,s,o,r){this.name=e,this.description=s,this.type=o,this.required=r,this.assertValidType()}assertValidType(){}static builder(){return new R}}class R{_name;_description;_type;_required;name(e){return this._name=e,this}description(e){return this._description=e,this}type(e){return this._type=e,this}required(e){return this._required=e,this}build(){return this._required==null&&(this._required=!1),new y(this._name,this._description,this._type,this._required)}}class L extends P{endpoint;model;options;constructor(e,s,o){super(),this.endpoint=e,this.model=s,this.options=o}async invoke(e){let s={model:this.model,messages:this._formatMessages(e),tools:this._formatTools(e),...this.options},o=await fetch(this.endpoint+"/api/chat",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)});if(!o.ok)throw new Error(`HTTP error! status: ${o.status}`);let r=await o.json(),n=[];if(r.message.tool_calls)for(let a in r.message.tool_calls){const i=r.message.tool_calls[a];let h="function",S=i[h]?.name,E=i[h]?.index,B=i.id??void 0,I=typeof i[h]?.arguments=="string"?JSON.parse(i[h]?.arguments):i[h]?.arguments;n.push(_.builder().name(S).type(h).parameters(I).sequence(E).id(B).build())}return u.builder().toolCalls(n).role(r.message.role).content(r.message.content).thinking(r.message.thinking).build()}_formatTools(e){let s=[];for(let o of e.tools){let r={},n=[];for(let i of o.getToolSchema().parameters)r[i.name]={},r[i.name].type=i.type,r[i.name].description=i.description,i.required&&n.push(i.name);let a={type:"function",function:{name:o.getName(),description:o.getDescription(),parameters:{type:"object",properties:r,required:n}}};s.push(a)}return s}_formatMessages(e){let s=[];for(let o of e.messages){if(o.role=="assistant"||o.role=="system"||o.role=="user"){s.push(this._formatSingleMessage(o));continue}if(o.role=="tool"){for(const r of o.content)if(r.getMessageComponentType()==l.ToolResult){const n=r;s.push({role:o.role,name:n.toolName,content:JSON.stringify(n.toolResult)})}}}return s}_formatSingleMessage(e){let s={role:e.role},o,r,n;for(const a of e.content){if(a.getMessageComponentType()==l.Content){const i=a;o==null&&(o=""),o+=i.get()}if(a.getMessageComponentType()==l.Thinking){const i=a;n==null&&(n=""),n+=i.get()}if(a.getMessageComponentType()==l.ToolCall){const i=a;r==null&&(r=[]),r.push(this._formatToolCall(i))}}return o!=null&&(s.content=o),r!=null&&(s.tool_calls=r),n!=null&&(s.thinking=n),s}_formatToolCall(e){return{function:{name:e.name,arguments:e.parameters}}}}function Q(t){return e=>{e.prototype.getName=()=>t}}function V(t){return e=>{Object.defineProperty(e.prototype,"getDescription",{value:function(){return t},enumerable:!0,configurable:!0,writable:!0})}}function H(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParams.push(y.builder().name(t.name).description(t.description).required(t.required).type(t.type).build()),e.prototype.getToolSchema=()=>new p(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}function K(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParamsOutput=t,e.prototype.getToolSchema=()=>new p(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}exports.Agent=k;exports.Content=C;exports.Conversation=w;exports.ConversationManager=M;exports.DefaultConversationManager=g;exports.Message=u;exports.MessageBuilder=b;exports.MessageComponent=m;exports.MessageComponentType=l;exports.Model=P;exports.ModelRequest=q;exports.ModelRequestBuilder=f;exports.OllamaModel=L;exports.Parameter=y;exports.ParameterBuilder=R;exports.Thinking=N;exports.Tool=F;exports.ToolCall=_;exports.ToolCallBuilder=x;exports.ToolDescription=V;exports.ToolName=Q;exports.ToolOutput=K;exports.ToolParameter=H;exports.ToolResult=c;exports.ToolSchema=p;exports.ToolSchemaBuilder=O;

package/dist/tapeworm.es.js

@@ -54,7 +54,7 @@ class g extends Error {
     super(e), this.name = "ConversationManagerNotImplemented";
   }
 }
-class h {
+class u {
   role;
   content;
   /**
@@ -148,7 +148,7 @@ class k {
   build() {
     if (this._content == null || this._content.length == 0)
       throw new Error("Role-only messages are not supported by Tapeworm.");
-    return new h(this._role, this._content);
+    return new u(this._role, this._content);
   }
 }
 const l = {
@@ -359,8 +359,8 @@ class v extends c {
    * @param type Type of tool call (e.g., function).
    * @param id Provider-generated identifier for correlating results.
    */
-  constructor(e, s, o, n, r) {
-    super(), this.sequence = e, this.name = s, this.parameters = o, this.type = n, this.id = r;
+  constructor(e, s, o, r, n) {
+    super(), this.sequence = e, this.name = s, this.parameters = o, this.type = r, this.id = n;
   }
   /**
    * Convenience factory for a ToolCallBuilder.
@@ -436,16 +436,55 @@ class I extends Error {
   }
 }
 class j {
+  /**
+   * The name of the agent.
+   */
   name;
+  /**
+   * The system prompt (if any) for the agent.
+   */
   systemPrompt;
+  /**
+   * The tools this agent knows about and can run.
+   */
   tools;
+  /**
+   * The underlying model for the agent.
+   */
   model;
+  /**
+   * The conversation for the agent.
+   * You do not normally need to set this parameter unless you are building a use case
+   * where you have a persistent session with an agent.
+   */
   conversation;
+  /**
+   * The conversation manager for the agent.
+   * Normally, a converstation manager that does nothing will be used.
+   * When SummarizingConversationManager or RAGConversationManager is implemented, these will help you avoid
+   * token overflow.
+   */
   conversationManager;
+  /**
+   * A cache for looking up tools in the Tools array.
+   * DO NOT MANUALLY SET THIS VALUE. AGENT AUTOMATICALLY TAKES CARE OF IT.
+   */
   toolNameToIndexMap;
+  /**
+   * The callback function, invoked for every response from the model.
+   * The default implementation just prints to std.out or your console.
+   */
   callback;
-  constructor(e, s, o, n, r) {
-    this.name = e, this.model = o, this.conversationManager = n, this.tools = s, this.callback = r, this.conversationManager.configure(o);
+  /**
+   * This is the constructor for an Agent.
+   *
+   * i IMPLORE YOU not to use this method. You CAN, but you should be using the Builder instead
+   * for the best results, as this method WILL change with future updates.
+   *
+   * Builder will be a lot more stable and will always be backwards compatible.
+   */
+  constructor(e, s, o, r, n) {
+    this.name = e, this.model = o, this.conversationManager = r, this.tools = s, this.callback = n, this.conversationManager.configure(o);
   }
   /**
    * Run the full agent loop for a user query: seed the conversation, invoke the model,
@@ -456,20 +495,20 @@ class j {
    */
   async invoke(e, s = this.callback) {
     this.conversation == null && (this.conversation = new x(), this.conversationManager != null && (this.conversation.manager = this.conversationManager), this.systemPrompt != null && this.conversation.append(
-      h.builder().role("system").content(this.systemPrompt).build()
+      u.builder().role("system").content(this.systemPrompt).build()
     )), this.conversation.append(
-      h.builder().role("user").content(e).build()
+      u.builder().role("user").content(e).build()
     );
     let o = !1;
     for (; !o; ) {
-      let n = await this._runQuery();
-      s(n), this.conversation.append(n), o = !0;
-      const r = n.filter(
+      let r = await this._runQuery();
+      s(r), this.conversation.append(r), o = !0;
+      const n = r.filter(
         l.ToolCall
       );
-      if (r != null && r.length != 0) {
-        o = !1, r.sort((a, i) => (a.sequence ?? 0) < (i.sequence ?? 0) ? -1 : 1);
-        for (let a of r)
+      if (n != null && n.length != 0) {
+        o = !1, n.sort((a, i) => (a.sequence ?? 0) < (i.sequence ?? 0) ? -1 : 1);
+        for (let a of n)
           await this._runTool(a);
       }
     }
@@ -491,7 +530,7 @@ class j {
   async _runTool(e) {
     if (this.generateToolNameToIndexMap(), !(e.name in this.toolNameToIndexMap)) {
       this.conversation.append(
-        h.builder().role("tool").toolResult(
+        u.builder().role("tool").toolResult(
           m.of(
             e,
             new I(
@@ -506,11 +545,11 @@ class j {
     try {
       let o = await s.execute(e.parameters);
       this.conversation.append(
-        h.builder().role("tool").toolResult(m.of(e, o)).build()
+        u.builder().role("tool").toolResult(m.of(e, o)).build()
       );
     } catch (o) {
       this.conversation.append(
-        h.builder().role("tool").toolResult(m.of(e, JSON.stringify(o))).build()
+        u.builder().role("tool").toolResult(m.of(e, JSON.stringify(o))).build()
       );
     }
   }
@@ -524,6 +563,9 @@ class j {
         this.toolNameToIndexMap[this.tools[e].getName()] = e;
     }
   }
+  /**
+   * Get a builder to build an Agent.
+   */
   static builder() {
     return new B();
   }
@@ -537,27 +579,51 @@ class B {
   _conversationManager = new _();
   _toolNameToIndexMap;
   _callback = (e) => D(e);
+  /**
+   * Set the name of the agent.
+   */
   name(e) {
     return this._name = e, this;
   }
+  /**
+   * Set the system prompt of the agent.
+   */
   systemPrompt(e) {
     return this._systemPrompt = e, this;
   }
+  /**
+   * Set the tools of the agent, if you already have an array of tools.
+   */
   tools(e) {
     return this._tools = e, this;
   }
+  /**
+   * Add a tool, 1 by 1, to the agent..
+   */
   addTool(e) {
     return this._tools == null && (this._tools = []), this._tools.push(e), this;
   }
+  /**
+   * Set the underlying model for the agent.
+   */
   model(e) {
     return this._model = e, this;
   }
+  /**
+   * Set the conversation manager for the agent.
+   */
   conversationManager(e) {
     return this._conversationManager = e, this;
   }
+  /**
+   * Set the callback for the agent.
+   */
   callback(e) {
     return this._callback = e, this;
   }
+  /**
+   * Build the agent.
+   */
   build() {
     let e = new j(
       this._name,
@@ -583,15 +649,6 @@ class p extends Error {
   }
 }
 class F {
-  name;
-  description;
-  tool_schema;
-  /**
-   * Initialize tool metadata from subclass implementations.
-   */
-  constructor() {
-    this.name = this.getName(), this.description = this.getDescription(), this.tool_schema = this.getToolSchema();
-  }
   /**
    * Name that uniquely identifies this tool.
    * @returns A short, stable identifier string.
@@ -681,8 +738,8 @@ class T {
    * @param type JSON-serializable type name (e.g., string, number).
    * @param required Whether the parameter must be provided.
    */
-  constructor(e, s, o, n) {
-    this.name = e, this.description = s, this.type = o, this.required = n, this.assertValidType();
+  constructor(e, s, o, r) {
+    this.name = e, this.description = s, this.type = o, this.required = r, this.assertValidType();
   }
   /**
    * Placeholder for validating supported parameter types.
@@ -775,16 +832,16 @@ class L extends O {
     });
     if (!o.ok)
       throw new Error(`HTTP error! status: ${o.status}`);
-    let n = await o.json(), r = [];
-    if (n.message.tool_calls)
-      for (let a in n.message.tool_calls) {
-        const i = n.message.tool_calls[a];
-        let u = "function", w = i[u]?.name, b = i[u]?.index, M = i.id ?? void 0, N = typeof i[u]?.arguments == "string" ? JSON.parse(i[u]?.arguments) : i[u]?.arguments;
-        r.push(
-          v.builder().name(w).type(u).parameters(N).sequence(b).id(M).build()
+    let r = await o.json(), n = [];
+    if (r.message.tool_calls)
+      for (let a in r.message.tool_calls) {
+        const i = r.message.tool_calls[a];
+        let h = "function", w = i[h]?.name, b = i[h]?.index, M = i.id ?? void 0, N = typeof i[h]?.arguments == "string" ? JSON.parse(i[h]?.arguments) : i[h]?.arguments;
+        n.push(
+          v.builder().name(w).type(h).parameters(N).sequence(b).id(M).build()
         );
       }
-    return h.builder().toolCalls(r).role(n.message.role).content(n.message.content).thinking(n.message.thinking).build();
+    return u.builder().toolCalls(n).role(r.message.role).content(r.message.content).thinking(r.message.thinking).build();
   }
   /**
    * Convert internal tool definitions into the JSON schema format expected by Ollama.
@@ -794,9 +851,9 @@ class L extends O {
   _formatTools(e) {
     let s = [];
     for (let o of e.tools) {
-      let n = {}, r = [];
+      let r = {}, n = [];
       for (let i of o.getToolSchema().parameters)
-        n[i.name] = {}, n[i.name].type = i.type, n[i.name].description = i.description, i.required && r.push(i.name);
+        r[i.name] = {}, r[i.name].type = i.type, r[i.name].description = i.description, i.required && n.push(i.name);
       let a = {
         type: "function",
         function: {
@@ -804,8 +861,8 @@ class L extends O {
           description: o.getDescription(),
           parameters: {
             type: "object",
-            properties: n,
-            required: r
+            properties: r,
+            required: n
           }
         }
       };
@@ -827,13 +884,13 @@ class L extends O {
         continue;
       }
       if (o.role == "tool") {
-        for (const n of o.content)
-          if (n.getMessageComponentType() == l.ToolResult) {
-            const r = n;
+        for (const r of o.content)
+          if (r.getMessageComponentType() == l.ToolResult) {
+            const n = r;
             s.push({
               role: o.role,
-              name: r.toolName,
-              content: JSON.stringify(r.toolResult)
+              name: n.toolName,
+              content: JSON.stringify(n.toolResult)
             });
           }
       }
@@ -848,7 +905,7 @@ class L extends O {
   _formatSingleMessage(e) {
     let s = {
       role: e.role
-    }, o, n, r;
+    }, o, r, n;
     for (const a of e.content) {
       if (a.getMessageComponentType() == l.Content) {
         const i = a;
@@ -856,14 +913,14 @@ class L extends O {
       }
       if (a.getMessageComponentType() == l.Thinking) {
         const i = a;
-        r == null && (r = ""), r += i.get();
+        n == null && (n = ""), n += i.get();
       }
       if (a.getMessageComponentType() == l.ToolCall) {
         const i = a;
-        n == null && (n = []), n.push(this._formatToolCall(i));
+        r == null && (r = []), r.push(this._formatToolCall(i));
       }
     }
-    return o != null && (s.content = o), n != null && (s.tool_calls = n), r != null && (s.thinking = r), s;
+    return o != null && (s.content = o), r != null && (s.tool_calls = r), n != null && (s.thinking = n), s;
   }
   /**
    * Convert a ToolCall into the structure Ollama expects.
@@ -920,7 +977,7 @@ export {
   x as Conversation,
   P as ConversationManager,
   _ as DefaultConversationManager,
-  h as Message,
+  u as Message,
   k as MessageBuilder,
   c as MessageComponent,
   l as MessageComponentType,

package/dist/tapeworm.umd.js

@@ -1 +1 @@
-(function(n,m){typeof exports=="object"&&typeof module<"u"?m(exports):typeof define=="function"&&define.amd?define(["exports"],m):(n=typeof globalThis<"u"?globalThis:n||self,m(n.Tapeworm={}))})(this,(function(n){"use strict";class m{messages;manager;constructor(){this.messages=[],this.manager=new f}append(e){this.messages.push(e),this.messages=this.manager.compact(this.messages)}}class w{compact(e){throw new M("No implementation for conversation manager!")}configure(e){throw new M("No implementation for conversation manager!")}}class f extends w{compact(e){return e}configure(e){}}class M extends Error{constructor(e){super(e),this.name="ConversationManagerNotImplemented"}}class h{role;content;constructor(e,s){this.role=e,this.content=s}static builder(){return new b}filter(e){return this.content.filter(s=>s.getMessageComponentType()==e)}}class b{_role;_content;role(e){return this._role=e,this}init(){this._content==null&&(this._content=[])}toolCall(e){return e==null?this:(this.init(),this._content.push(e),this)}toolCalls(e){if(e==null)return this;this.init();for(const s of e)this._content.push(s);return this}toolResult(e){return e==null?this:(this.init(),this._content.push(e),this)}thinking(e){return e==null?this:(this.init(),this._content.push(C.of(e)),this)}content(e){return e==null?this:(this.init(),this._content.push(N.of(e)),this)}build(){if(this._content==null||this._content.length==0)throw new Error("Role-only messages are not supported by Tapeworm.");return new h(this._role,this._content)}}const u={Content:"content",Thinking:"thinking",ToolCall:"toolcall",ToolResult:"toolresult"};class p{getMessageComponentType(){throw new Error("Message components that do not have a message component type are not allowed.")}}class N extends p{text;constructor(e){super(),this.text=e}getMessageComponentType(){return u.Content}get(){return this.text}static of(e){return new this(e)}}class C extends p{thought;constructor(e){super(),this.thought=e}getMessageComponentType(){return u.Thinking}get(){return this.thought}static of(e){return new this(e)}}class d extends p{id;toolName;toolResult;constructor(e,s,o){super(),this.id=e,this.toolName=s,this.toolResult=o}getMessageComponentType(){return u.ToolResult}static of(e,s){return new this(e.id,e.name,s)}}class P{async invoke(e){throw new k("The invoke function for this model was not correctly implemented.")}tokenLimit(){throw new k("The tokenLimit function for this model was not correctly implemented.")}}class q{messages;tools;constructor(e,s){this.messages=e,this.tools=s}static builder(){return new _}}class _{_messages;_tools;messages(e){return this._messages=e,this}tools(e){return this._tools=e,this}build(){if(this._tools==null&&(this._tools=[]),this._messages==null)throw new B("Requests to the model should include content.");return new q(this._messages,this._tools)}}class k extends Error{constructor(e){super(e),this.name="ModelNotImplementedError"}}class B extends Error{constructor(e){super(e),this.name="MessagesNotDefinedError"}}class T extends p{sequence;name;parameters;type;id;getMessageComponentType(){return u.ToolCall}constructor(e,s,o,r,i){super(),this.sequence=e,this.name=s,this.parameters=o,this.type=r,this.id=i}static builder(){return new O}}class O{_sequence;_name;_parameters;_type;_id;sequence(e){return this._sequence=e,this}name(e){return this._name=e,this}parameters(e){return this._parameters=e,this}type(e){return this._type=e,this}id(e){return e!=null&&(this._id=e),this}build(){return this._sequence==null&&(this._sequence=0),this._id==null&&(this._id=(Math.random()+1).toString(36).slice(2,7)),new T(this._sequence,this._name,this._parameters,this._type,this._id)}}class j extends Error{constructor(e){super(e),this.name="ToolNotFoundError"}}class S{name;systemPrompt;tools;model;conversation;conversationManager;toolNameToIndexMap;callback;constructor(e,s,o,r,i){this.name=e,this.model=o,this.conversationManager=r,this.tools=s,this.callback=i,this.conversationManager.configure(o)}async invoke(e,s=this.callback){this.conversation==null&&(this.conversation=new m,this.conversationManager!=null&&(this.conversation.manager=this.conversationManager),this.systemPrompt!=null&&this.conversation.append(h.builder().role("system").content(this.systemPrompt).build())),this.conversation.append(h.builder().role("user").content(e).build());let o=!1;for(;!o;){let r=await this._runQuery();s(r),this.conversation.append(r),o=!0;const i=r.filter(u.ToolCall);if(i!=null&&i.length!=0){o=!1,i.sort((l,a)=>(l.sequence??0)<(a.sequence??0)?-1:1);for(let l of i)await this._runTool(l)}}}async _runQuery(){return await this.model.invoke(new _().messages(this.conversation?.messages).tools(this.tools).build())}async _runTool(e){if(this.generateToolNameToIndexMap(),!(e.name in this.toolNameToIndexMap)){this.conversation.append(h.builder().role("tool").toolResult(d.of(e,new j("Agent does not have a tool with this name."))).build());return}let s=this.tools[this.toolNameToIndexMap[e.name]];try{let o=await s.execute(e.parameters);this.conversation.append(h.builder().role("tool").toolResult(d.of(e,o)).build())}catch(o){this.conversation.append(h.builder().role("tool").toolResult(d.of(e,JSON.stringify(o))).build())}}generateToolNameToIndexMap(){if(this.toolNameToIndexMap==null){this.toolNameToIndexMap={};for(let e=0;e<this.tools.length;e++)this.toolNameToIndexMap[this.tools[e].getName()]=e}}static builder(){return new I}}class I{_name;_systemPrompt;_tools;_model;_conversation;_conversationManager=new f;_toolNameToIndexMap;_callback=e=>D(e);name(e){return this._name=e,this}systemPrompt(e){return this._systemPrompt=e,this}tools(e){return this._tools=e,this}addTool(e){return this._tools==null&&(this._tools=[]),this._tools.push(e),this}model(e){return this._model=e,this}conversationManager(e){return this._conversationManager=e,this}callback(e){return this._callback=e,this}build(){let e=new S(this._name,this._tools,this._model,this._conversationManager,this._callback);return this._conversation!=null&&(e.conversation=this._conversation),this._systemPrompt!=null&&(e.systemPrompt=this._systemPrompt),e}}function D(t){for(const e of t.filter(u.Thinking))console.log("\x1B[90m"+e.get()+"\x1B[0m");for(const e of t.filter(u.Content))console.log(e.get());for(const e of t.filter(u.ToolCall))console.log("\x1B[32mCalling Tool: "+e.name+"\x1B[0m")}class y extends Error{constructor(e){super(e),this.name="ToolNotDefinedError"}}class x{name;description;tool_schema;constructor(){this.name=this.getName(),this.description=this.getDescription(),this.tool_schema=this.getToolSchema()}getName(){throw new y("Tool name not defined.")}getDescription(){throw new y("Tool description not defined.")}getToolSchema(){throw new y("Tool parameter schema not defined.")}execute(e){return null}}class g{parameters;output;constructor(e,s){this.parameters=e,this.output=s}static builder(){return new R}}class R{_parameters;_output;addParameter(e){return this._parameters==null&&(this._parameters=[]),this._parameters.push(e),this}output(e){return this._output=e,this}build(){return this._parameters==null&&(this._parameters=[]),new g(this._parameters,this._output)}}class v{name;description;type;required;constructor(e,s,o,r){this.name=e,this.description=s,this.type=o,this.required=r,this.assertValidType()}assertValidType(){}static builder(){return new E}}class E{_name;_description;_type;_required;name(e){return this._name=e,this}description(e){return this._description=e,this}type(e){return this._type=e,this}required(e){return this._required=e,this}build(){return this._required==null&&(this._required=!1),new v(this._name,this._description,this._type,this._required)}}class A extends P{endpoint;model;options;constructor(e,s,o){super(),this.endpoint=e,this.model=s,this.options=o}async invoke(e){let s={model:this.model,messages:this._formatMessages(e),tools:this._formatTools(e),...this.options},o=await fetch(this.endpoint+"/api/chat",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)});if(!o.ok)throw new Error(`HTTP error! status: ${o.status}`);let r=await o.json(),i=[];if(r.message.tool_calls)for(let l in r.message.tool_calls){const a=r.message.tool_calls[l];let c="function",V=a[c]?.name,H=a[c]?.index,K=a.id??void 0,W=typeof a[c]?.arguments=="string"?JSON.parse(a[c]?.arguments):a[c]?.arguments;i.push(T.builder().name(V).type(c).parameters(W).sequence(H).id(K).build())}return h.builder().toolCalls(i).role(r.message.role).content(r.message.content).thinking(r.message.thinking).build()}_formatTools(e){let s=[];for(let o of e.tools){let r={},i=[];for(let a of o.getToolSchema().parameters)r[a.name]={},r[a.name].type=a.type,r[a.name].description=a.description,a.required&&i.push(a.name);let l={type:"function",function:{name:o.getName(),description:o.getDescription(),parameters:{type:"object",properties:r,required:i}}};s.push(l)}return s}_formatMessages(e){let s=[];for(let o of e.messages){if(o.role=="assistant"||o.role=="system"||o.role=="user"){s.push(this._formatSingleMessage(o));continue}if(o.role=="tool"){for(const r of o.content)if(r.getMessageComponentType()==u.ToolResult){const i=r;s.push({role:o.role,name:i.toolName,content:JSON.stringify(i.toolResult)})}}}return s}_formatSingleMessage(e){let s={role:e.role},o,r,i;for(const l of e.content){if(l.getMessageComponentType()==u.Content){const a=l;o==null&&(o=""),o+=a.get()}if(l.getMessageComponentType()==u.Thinking){const a=l;i==null&&(i=""),i+=a.get()}if(l.getMessageComponentType()==u.ToolCall){const a=l;r==null&&(r=[]),r.push(this._formatToolCall(a))}}return o!=null&&(s.content=o),r!=null&&(s.tool_calls=r),i!=null&&(s.thinking=i),s}_formatToolCall(e){return{function:{name:e.name,arguments:e.parameters}}}}function J(t){return e=>{e.prototype.getName=()=>t}}function F(t){return e=>{Object.defineProperty(e.prototype,"getDescription",{value:function(){return t},enumerable:!0,configurable:!0,writable:!0})}}function L(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParams.push(v.builder().name(t.name).description(t.description).required(t.required).type(t.type).build()),e.prototype.getToolSchema=()=>new g(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}function Q(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParamsOutput=t,e.prototype.getToolSchema=()=>new g(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}n.Agent=S,n.Content=N,n.Conversation=m,n.ConversationManager=w,n.DefaultConversationManager=f,n.Message=h,n.MessageBuilder=b,n.MessageComponent=p,n.MessageComponentType=u,n.Model=P,n.ModelRequest=q,n.ModelRequestBuilder=_,n.OllamaModel=A,n.Parameter=v,n.ParameterBuilder=E,n.Thinking=C,n.Tool=x,n.ToolCall=T,n.ToolCallBuilder=O,n.ToolDescription=F,n.ToolName=J,n.ToolOutput=Q,n.ToolParameter=L,n.ToolResult=d,n.ToolSchema=g,n.ToolSchemaBuilder=R,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));
+(function(n,m){typeof exports=="object"&&typeof module<"u"?m(exports):typeof define=="function"&&define.amd?define(["exports"],m):(n=typeof globalThis<"u"?globalThis:n||self,m(n.Tapeworm={}))})(this,(function(n){"use strict";class m{messages;manager;constructor(){this.messages=[],this.manager=new f}append(e){this.messages.push(e),this.messages=this.manager.compact(this.messages)}}class w{compact(e){throw new M("No implementation for conversation manager!")}configure(e){throw new M("No implementation for conversation manager!")}}class f extends w{compact(e){return e}configure(e){}}class M extends Error{constructor(e){super(e),this.name="ConversationManagerNotImplemented"}}class h{role;content;constructor(e,s){this.role=e,this.content=s}static builder(){return new b}filter(e){return this.content.filter(s=>s.getMessageComponentType()==e)}}class b{_role;_content;role(e){return this._role=e,this}init(){this._content==null&&(this._content=[])}toolCall(e){return e==null?this:(this.init(),this._content.push(e),this)}toolCalls(e){if(e==null)return this;this.init();for(const s of e)this._content.push(s);return this}toolResult(e){return e==null?this:(this.init(),this._content.push(e),this)}thinking(e){return e==null?this:(this.init(),this._content.push(N.of(e)),this)}content(e){return e==null?this:(this.init(),this._content.push(C.of(e)),this)}build(){if(this._content==null||this._content.length==0)throw new Error("Role-only messages are not supported by Tapeworm.");return new h(this._role,this._content)}}const u={Content:"content",Thinking:"thinking",ToolCall:"toolcall",ToolResult:"toolresult"};class p{getMessageComponentType(){throw new Error("Message components that do not have a message component type are not allowed.")}}class C extends p{text;constructor(e){super(),this.text=e}getMessageComponentType(){return u.Content}get(){return this.text}static of(e){return new this(e)}}class N extends p{thought;constructor(e){super(),this.thought=e}getMessageComponentType(){return u.Thinking}get(){return this.thought}static of(e){return new this(e)}}class d extends p{id;toolName;toolResult;constructor(e,s,o){super(),this.id=e,this.toolName=s,this.toolResult=o}getMessageComponentType(){return u.ToolResult}static of(e,s){return new this(e.id,e.name,s)}}class P{async invoke(e){throw new k("The invoke function for this model was not correctly implemented.")}tokenLimit(){throw new k("The tokenLimit function for this model was not correctly implemented.")}}class q{messages;tools;constructor(e,s){this.messages=e,this.tools=s}static builder(){return new _}}class _{_messages;_tools;messages(e){return this._messages=e,this}tools(e){return this._tools=e,this}build(){if(this._tools==null&&(this._tools=[]),this._messages==null)throw new B("Requests to the model should include content.");return new q(this._messages,this._tools)}}class k extends Error{constructor(e){super(e),this.name="ModelNotImplementedError"}}class B extends Error{constructor(e){super(e),this.name="MessagesNotDefinedError"}}class T extends p{sequence;name;parameters;type;id;getMessageComponentType(){return u.ToolCall}constructor(e,s,o,r,i){super(),this.sequence=e,this.name=s,this.parameters=o,this.type=r,this.id=i}static builder(){return new O}}class O{_sequence;_name;_parameters;_type;_id;sequence(e){return this._sequence=e,this}name(e){return this._name=e,this}parameters(e){return this._parameters=e,this}type(e){return this._type=e,this}id(e){return e!=null&&(this._id=e),this}build(){return this._sequence==null&&(this._sequence=0),this._id==null&&(this._id=(Math.random()+1).toString(36).slice(2,7)),new T(this._sequence,this._name,this._parameters,this._type,this._id)}}class j extends Error{constructor(e){super(e),this.name="ToolNotFoundError"}}class R{name;systemPrompt;tools;model;conversation;conversationManager;toolNameToIndexMap;callback;constructor(e,s,o,r,i){this.name=e,this.model=o,this.conversationManager=r,this.tools=s,this.callback=i,this.conversationManager.configure(o)}async invoke(e,s=this.callback){this.conversation==null&&(this.conversation=new m,this.conversationManager!=null&&(this.conversation.manager=this.conversationManager),this.systemPrompt!=null&&this.conversation.append(h.builder().role("system").content(this.systemPrompt).build())),this.conversation.append(h.builder().role("user").content(e).build());let o=!1;for(;!o;){let r=await this._runQuery();s(r),this.conversation.append(r),o=!0;const i=r.filter(u.ToolCall);if(i!=null&&i.length!=0){o=!1,i.sort((l,a)=>(l.sequence??0)<(a.sequence??0)?-1:1);for(let l of i)await this._runTool(l)}}}async _runQuery(){return await this.model.invoke(new _().messages(this.conversation?.messages).tools(this.tools).build())}async _runTool(e){if(this.generateToolNameToIndexMap(),!(e.name in this.toolNameToIndexMap)){this.conversation.append(h.builder().role("tool").toolResult(d.of(e,new j("Agent does not have a tool with this name."))).build());return}let s=this.tools[this.toolNameToIndexMap[e.name]];try{let o=await s.execute(e.parameters);this.conversation.append(h.builder().role("tool").toolResult(d.of(e,o)).build())}catch(o){this.conversation.append(h.builder().role("tool").toolResult(d.of(e,JSON.stringify(o))).build())}}generateToolNameToIndexMap(){if(this.toolNameToIndexMap==null){this.toolNameToIndexMap={};for(let e=0;e<this.tools.length;e++)this.toolNameToIndexMap[this.tools[e].getName()]=e}}static builder(){return new I}}class I{_name;_systemPrompt;_tools;_model;_conversation;_conversationManager=new f;_toolNameToIndexMap;_callback=e=>D(e);name(e){return this._name=e,this}systemPrompt(e){return this._systemPrompt=e,this}tools(e){return this._tools=e,this}addTool(e){return this._tools==null&&(this._tools=[]),this._tools.push(e),this}model(e){return this._model=e,this}conversationManager(e){return this._conversationManager=e,this}callback(e){return this._callback=e,this}build(){let e=new R(this._name,this._tools,this._model,this._conversationManager,this._callback);return this._conversation!=null&&(e.conversation=this._conversation),this._systemPrompt!=null&&(e.systemPrompt=this._systemPrompt),e}}function D(t){for(const e of t.filter(u.Thinking))console.log("\x1B[90m"+e.get()+"\x1B[0m");for(const e of t.filter(u.Content))console.log(e.get());for(const e of t.filter(u.ToolCall))console.log("\x1B[32mCalling Tool: "+e.name+"\x1B[0m")}class y extends Error{constructor(e){super(e),this.name="ToolNotDefinedError"}}class x{getName(){throw new y("Tool name not defined.")}getDescription(){throw new y("Tool description not defined.")}getToolSchema(){throw new y("Tool parameter schema not defined.")}execute(e){return null}}class g{parameters;output;constructor(e,s){this.parameters=e,this.output=s}static builder(){return new S}}class S{_parameters;_output;addParameter(e){return this._parameters==null&&(this._parameters=[]),this._parameters.push(e),this}output(e){return this._output=e,this}build(){return this._parameters==null&&(this._parameters=[]),new g(this._parameters,this._output)}}class v{name;description;type;required;constructor(e,s,o,r){this.name=e,this.description=s,this.type=o,this.required=r,this.assertValidType()}assertValidType(){}static builder(){return new E}}class E{_name;_description;_type;_required;name(e){return this._name=e,this}description(e){return this._description=e,this}type(e){return this._type=e,this}required(e){return this._required=e,this}build(){return this._required==null&&(this._required=!1),new v(this._name,this._description,this._type,this._required)}}class A extends P{endpoint;model;options;constructor(e,s,o){super(),this.endpoint=e,this.model=s,this.options=o}async invoke(e){let s={model:this.model,messages:this._formatMessages(e),tools:this._formatTools(e),...this.options},o=await fetch(this.endpoint+"/api/chat",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)});if(!o.ok)throw new Error(`HTTP error! status: ${o.status}`);let r=await o.json(),i=[];if(r.message.tool_calls)for(let l in r.message.tool_calls){const a=r.message.tool_calls[l];let c="function",V=a[c]?.name,H=a[c]?.index,K=a.id??void 0,W=typeof a[c]?.arguments=="string"?JSON.parse(a[c]?.arguments):a[c]?.arguments;i.push(T.builder().name(V).type(c).parameters(W).sequence(H).id(K).build())}return h.builder().toolCalls(i).role(r.message.role).content(r.message.content).thinking(r.message.thinking).build()}_formatTools(e){let s=[];for(let o of e.tools){let r={},i=[];for(let a of o.getToolSchema().parameters)r[a.name]={},r[a.name].type=a.type,r[a.name].description=a.description,a.required&&i.push(a.name);let l={type:"function",function:{name:o.getName(),description:o.getDescription(),parameters:{type:"object",properties:r,required:i}}};s.push(l)}return s}_formatMessages(e){let s=[];for(let o of e.messages){if(o.role=="assistant"||o.role=="system"||o.role=="user"){s.push(this._formatSingleMessage(o));continue}if(o.role=="tool"){for(const r of o.content)if(r.getMessageComponentType()==u.ToolResult){const i=r;s.push({role:o.role,name:i.toolName,content:JSON.stringify(i.toolResult)})}}}return s}_formatSingleMessage(e){let s={role:e.role},o,r,i;for(const l of e.content){if(l.getMessageComponentType()==u.Content){const a=l;o==null&&(o=""),o+=a.get()}if(l.getMessageComponentType()==u.Thinking){const a=l;i==null&&(i=""),i+=a.get()}if(l.getMessageComponentType()==u.ToolCall){const a=l;r==null&&(r=[]),r.push(this._formatToolCall(a))}}return o!=null&&(s.content=o),r!=null&&(s.tool_calls=r),i!=null&&(s.thinking=i),s}_formatToolCall(e){return{function:{name:e.name,arguments:e.parameters}}}}function J(t){return e=>{e.prototype.getName=()=>t}}function F(t){return e=>{Object.defineProperty(e.prototype,"getDescription",{value:function(){return t},enumerable:!0,configurable:!0,writable:!0})}}function L(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParams.push(v.builder().name(t.name).description(t.description).required(t.required).type(t.type).build()),e.prototype.getToolSchema=()=>new g(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}function Q(t){return e=>{e.prototype.tapewormParams==null&&(e.prototype.tapewormParams=[]),e.prototype.tapewormParamsOutput==null&&(e.prototype.tapewormParamsOutput=""),e.prototype.tapewormParamsOutput=t,e.prototype.getToolSchema=()=>new g(e.prototype.tapewormParams,e.prototype.tapewormParamsOutput)}}n.Agent=R,n.Content=C,n.Conversation=m,n.ConversationManager=w,n.DefaultConversationManager=f,n.Message=h,n.MessageBuilder=b,n.MessageComponent=p,n.MessageComponentType=u,n.Model=P,n.ModelRequest=q,n.ModelRequestBuilder=_,n.OllamaModel=A,n.Parameter=v,n.ParameterBuilder=E,n.Thinking=N,n.Tool=x,n.ToolCall=T,n.ToolCallBuilder=O,n.ToolDescription=F,n.ToolName=J,n.ToolOutput=Q,n.ToolParameter=L,n.ToolResult=d,n.ToolSchema=g,n.ToolSchemaBuilder=S,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));

package/dist/tool/tool.d.ts

@@ -1,16 +1,13 @@
+/**
+ * The Tool module contains the Tool class, which shows
+ * what properties are required by a class to be invocable by Tapeworm.
+ */
 import type ToolSchema from "./toolschema";
 /**
  * The Tool class represents a tool that a Tapeworm agent can use.
  *
  */
 export default class Tool {
-    private name;
-    private description;
-    private tool_schema;
-    /**
-     * Initialize tool metadata from subclass implementations.
-     */
-    constructor();
     /**
      * Name that uniquely identifies this tool.
      * @returns A short, stable identifier string.

package/dist/tool/toolCall.d.ts

@@ -1,3 +1,11 @@
+/**
+ * This module is dedicated to just the ToolCall MessageComponent.
+ *
+ * The reason is that it's the most complicated MessageComponent and deserves to have its own file,
+ * as this class contains more ways to instantiate than normal MessageComponents.
+ *
+ * @module
+ */
 import { MessageComponent, MessageComponentType } from "../conversation/message";
 /**
  * Represents a single tool invocation returned by a model, including the target

package/dist/tool/toolDecorators.d.ts

@@ -3,7 +3,7 @@
  *
  * They are different from the Babel decorators in @atgs/babel-plugin-tapeworm-decorator, but they achieve the same functionality.
  *
- *
+ * @module
  */
 export declare function ToolName(name: String): (toolClass: Function) => void;
 export declare function ToolDescription(description: String): (toolClass: Function) => void;

package/dist/tool/toolschema.d.ts

@@ -1,5 +1,17 @@
 /**
- * Tool schemas specify the input and output of a tool.
+ * This module contains everything related to tool schemas.
+ *
+ * Enclosed are the ToolSchema (and builder) and Parameter (and builder) classes.
+ *
+ * @module
+ */
+/**
+ * ToolSchemas define the input and output of a tool.
+ *
+ * They consist of a list of parameters and a description of the output of the tool.
+ *
+ * You can build these using ToolSchemaBuilder, but it can be more pragmatic to use
+ * the Typescript or Babel decorators instead, as they will automatically generate a ToolSchema for you.
  */
 export default class ToolSchema {
     parameters: Parameter[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atgs/tapeworm",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "main": "dist/tapeworm.cjs.js",
   "module": "dist/tapeworm.es.js",
@@ -15,7 +15,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "npm run format && npm run test && vite build && npm run build:types",
+    "build": "npm run format && npm run test && vite build && npm run build:types && npm run docs",
+    "docs": "typedoc --options typedoc.json",
     "build:types": "tsc -p tsconfig.types.json",
     "test": "jest",
     "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,css,md}\""
@@ -27,6 +28,8 @@
     "jest": "^30.2.0",
     "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.15",
+    "typedoc-plugin-rename-defaults": "^0.7.3",
     "typescript": "^5.9.3",
     "vite": "^7.2.7"
   }