@tabbybyte/kimten 0.1.4 → 0.2.0

package/README.md

@@ -14,8 +14,8 @@ It’s meant to feel like a smart helper, not a framework.
 
 ## ✅ What it does
 
-- Runs a simple agent loop (bounded by `hops`)
-- Lets the model call your tools (`toys`)
+- Runs a simple, single-agent loop (bounded by `hops`)
+- Lets the LLM model (the brain) call your tool functions (the toys)
 - Keeps short-term conversation memory (in-process, per instance)
 - Supports optional structured output via Zod
 
@@ -24,19 +24,19 @@ It’s meant to feel like a smart helper, not a framework.
 - No planners/graphs/state machines
 - No streaming API surface
 - No persistence or long-term memory
-- No plugin system or orchestration runtime
+- No plugin system or multi-agent orchestration
 
 ---
 
 ## ✨ Why Kimten?
 
-Use it when you just want an agent loop with tools and a little memory, without adopting a larger framework.
+Use it when you just want an agent loop with toys and a little memory, without adopting a larger framework.
 
 Good fits:
 
 - CLI helpers
 - small automations
-- local tools
+- local toys
 - scripting
 - quick AI utilities
 - “just let the model call a function” use cases
@@ -68,9 +68,19 @@ const cat = Kimten({
   brain: openai('gpt-4o-mini'), // or, any other available model
 
   toys: {
-    add: async ({ a, b }) => a + b,
+    randomNumber: {
+      description: 'Generate a random integer between min and max (inclusive).',
+      inputSchema: z.object({ min: z.number().int(), max: z.number().int() }),
+      async execute({ min, max }) {
+        const low = Math.min(min, max);
+        const high = Math.max(min, max);
+        return Math.floor(Math.random() * (high - low + 1)) + low;
+      },
+    },
   },
 
+  personality: 'You are a helpful assistant.',
+
   hops: 10,
 });
 
@@ -119,19 +129,18 @@ Create a new instance.
 
 #### Optional
 
-* `toys` → object map of tool definitions. Each entry can be:
-  * async function shorthand: `async (args) => result`
+* `toys` → object map of toy (tool) definitions. Each entry is:
   * object form: `{ inputSchema?, description?, strict?, execute }`
   default: `{}`
-* `personality` → system prompt / behavior description (default: `"You are a helpful assistant."`)
-* `hops` → max agent loop steps (default: `10`)  
-  prevents infinite zoomies 🌀
+* `personality` → system instructions / prompt for overall behavior description (default: `'You are a helpful assistant.'`)
+* `hops` → max agent loop steps (default: `10`) - prevents infinite zoomies 🌀
 
-#### Tool semantics
+#### Toy semantics
 
-- Tool inputs are validated only if you provide `inputSchema` (shorthand tools accept anything).
-- Tool results should be JSON-serializable; `undefined` becomes `null`.
-- If a tool throws, Kimten returns `{ error, toolName }` as the tool result (it does not re-throw).
+- Toy inputs are validated only if you provide `inputSchema`.
+- Toy results should be JSON-serializable; `undefined` becomes `null`.
+- If a toy function throws, Kimten returns `{ error, toolName }` as the toy result (it does not re-throw).
+- Under the hood, each toy is implemented as an AI SDK tool.
 
 #### Returns
 
@@ -153,32 +162,25 @@ Create a new instance.
 
 For the `brain` part, feel free to use any compatible provider and their models.
 
-Refer to the AI SDK docs: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
+❗ Note that not all providers (and models) may work out the box with Kimten, particularly for structured output.
 
-### Add tools freely
+💡 Refer to the AI SDK docs: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
 
-Tools can stay simple, just normal async functions:
-
-```js
-toys: {
-  readFile,
-  writeFile,
-  fetchJson,
-  runCommand,
-}
-```
+### Add toys freely
 
-For stronger arg validation and better tool selection, use object form:
+Define `toys` in object form for strong arg validation and proper selection by the LLM:
 
 ```js
 import { z } from 'zod';
 
 toys: {
-  add: {
-    description: 'Add two numbers.',
-    inputSchema: z.object({ a: z.number(), b: z.number() }),
-    async execute({ a, b }) {
-      return a + b;
+  randomNumber: {
+    description: 'Generate a random integer between min and max (inclusive).',
+    inputSchema: z.object({ min: z.number().int(), max: z.number().int() }),
+    async execute({ min, max }) {
+      const low = Math.min(min, max);
+      const high = Math.max(min, max);
+      return Math.floor(Math.random() * (high - low + 1)) + low;
     },
   },
 }

package/index.d.ts

@@ -0,0 +1,32 @@
+import type { ZodTypeAny, infer as ZodInfer } from 'zod';
+
+export type BrainModel = Record<string, unknown>;
+
+export type ToolExecute = (args: any) => any | Promise<any>;
+
+export type ToyDefinition = {
+  inputSchema?: ZodTypeAny;
+  description?: string;
+  strict?: boolean;
+  execute: ToolExecute;
+};
+
+export type Toys = Record<string, ToyDefinition>;
+
+export type KimtenConfig = {
+  brain: BrainModel;
+  toys?: Toys;
+  personality?: string;
+  hops?: number;
+};
+
+export type KimtenAgent = {
+  play(input: string): Promise<string>;
+  play<S extends ZodTypeAny>(input: string, schema: S): Promise<ZodInfer<S>>;
+  forget(): void;
+};
+
+export declare function Kimten(config: KimtenConfig): KimtenAgent;
+
+declare const _default: typeof Kimten;
+export default _default;

package/index.js

@@ -1,3 +1,8 @@
+/**
+ * @module @tabbybyte/kimten
+ *
+ * Public entrypoint for Kimten.
+ */
 import { Kimten } from './lib/kimten.js';
 
 export { Kimten };

package/lib/kimten.js

@@ -1,10 +1,68 @@
 import { ToolLoopAgent, stepCountIs, Output } from 'ai';
 import { createMemory } from './memory.js';
-import { buildMessages } from './prompt.js';
 import { normalizeToys } from './tools.js';
 
 const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
 
+/**
+ * @typedef {import('zod').ZodTypeAny} ZodSchema
+ */
+
+/**
+ * A minimal AI SDK model-like object accepted by Kimten.
+ *
+ * This is intentionally loose to avoid coupling Kimten to AI SDK internal types,
+ * while still providing useful IDE hints.
+ *
+ * @typedef {object} BrainModel
+ * @property {string} [specificationVersion]
+ * @property {string} [provider]
+ * @property {string} [modelId]
+ * @property {Record<string, unknown>} [supportedUrls]
+ */
+
+/**
+ * Tool execute function.
+ *
+ * @callback ToolExecute
+ * @param {any} args
+ * @returns {any | Promise<any>}
+ */
+
+/**
+ * Object-form tool definition.
+ *
+ * @typedef {object} ToyDefinition
+ * @property {import('zod').ZodTypeAny} [inputSchema]
+ * @property {string} [description]
+ * @property {boolean} [strict]
+ * @property {ToolExecute} execute
+ */
+
+/**
+ * Tool registry map.
+ *
+ * @typedef {Record<string, ToyDefinition>} Toys
+ */
+
+/**
+ * Kimten factory config.
+ *
+ * @typedef {object} KimtenConfig
+ * @property {BrainModel} brain AI SDK model instance.
+ * @property {Toys} [toys] Tool registry.
+ * @property {string} [personality] System prompt / instructions.
+ * @property {number} [hops] Max loop steps (prevents infinite loops).
+ */
+
+/**
+ * Returned Kimten instance.
+ *
+ * @typedef {object} KimtenAgent
+ * @property {(input: string, schema?: ZodSchema | null) => Promise<any>} play Run the agent loop.
+ * @property {() => void} forget Clear short-term memory.
+ */
+
 function validateConfig(config) {
   if (config === null || typeof config !== 'object' || Array.isArray(config)) {
     throw new TypeError('Kimten requires a config object.');
@@ -33,6 +91,12 @@ function validateConfig(config) {
   };
 }
 
+/**
+ * Create a tiny tool-using agent with short-term memory.
+ *
+ * @param {KimtenConfig} config
+ * @returns {KimtenAgent}
+ */
 export function Kimten(config) {
   const { brain, toys, personality, hops } = validateConfig(config);
   const memory = createMemory();
@@ -71,6 +135,16 @@ export function Kimten(config) {
     return createStructuredAgent(schema);
   }
 
+  /**
+   * Run the agent loop.
+   *
+   * - Stores the conversation in short-term memory (in-process, per instance).
+   * - If `schema` is provided, returns structured output (via AI SDK output mode).
+   *
+   * @param {string} input
+   * @param {ZodSchema | null} [schema]
+   * @returns {Promise<any>}
+   */
   async function play(input, schema = null) {
     if (typeof input !== 'string') {
       throw new TypeError('Kimten play(input) expects input to be a string.');
@@ -80,7 +154,7 @@ export function Kimten(config) {
 
     const agent = schema ? getStructuredAgent(schema) : textAgent;
     const result = await agent.generate({
-      messages: buildMessages(personality, memory.list()),
+      messages: memory.list(),
     });
 
     const assistantContent =
@@ -95,6 +169,11 @@ export function Kimten(config) {
     return schema ? result.output : assistantContent;
   }
 
+  /**
+   * Clear short-term memory for this instance.
+   *
+   * @returns {void}
+   */
   function forget() {
     memory.clear();
   }

package/lib/memory.js

@@ -1,8 +1,32 @@
 export const MEMORY_LIMIT = 10;
 
+/**
+ * A single chat message stored in short-term memory.
+ *
+ * @typedef {object} MemoryMessage
+ * @property {'system' | 'user' | 'assistant' | 'tool'} role
+ * @property {any} content
+ */
+
+/**
+ * Short-term FIFO memory store (sliding window).
+ *
+ * @typedef {object} MemoryStore
+ * @property {(message: MemoryMessage) => void} add
+ * @property {() => MemoryMessage[]} list
+ * @property {() => void} clear
+ */
+
+/**
+ * Create a short-term FIFO memory store.
+ *
+ * @param {number} [limit=MEMORY_LIMIT] Max number of messages to keep.
+ * @returns {MemoryStore}
+ */
 export function createMemory(limit = MEMORY_LIMIT) {
   const history = [];
 
+  /** @param {MemoryMessage} message */
   function add(message) {
     history.push(message);
     if (history.length > limit) {

package/lib/tools.js

@@ -1,6 +1,34 @@
 import { tool } from 'ai';
 import { z } from 'zod';
 
+/**
+ * @typedef {import('zod').ZodTypeAny} ZodSchema
+ */
+
+/**
+ * Tool execute function.
+ *
+ * @callback ToolExecute
+ * @param {any} args
+ * @returns {any | Promise<any>}
+ */
+
+/**
+ * Object-form tool definition.
+ *
+ * @typedef {object} ToyDefinition
+ * @property {ZodSchema} [inputSchema]
+ * @property {string} [description]
+ * @property {boolean} [strict]
+ * @property {ToolExecute} execute
+ */
+
+/**
+ * Tool registry map.
+ *
+ * @typedef {Record<string, ToyDefinition>} Toys
+ */
+
 function isPlainObject(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
@@ -10,13 +38,24 @@ function isPlainObject(value) {
   return proto === Object.prototype || proto === null;
 }
 
+/**
+ * Normalize a toy registry into AI SDK tool objects.
+ *
+ * - Object form only: `{ inputSchema?, description?, strict?, execute }`
+ *
+ * Tool execution is wrapped so thrown errors become JSON-safe results:
+ * `{ error, toolName }` (Kimten does not re-throw tool errors).
+ *
+ * @param {Toys | null | undefined} toys
+ * @returns {Record<string, ReturnType<typeof tool>>}
+ */
 export function normalizeToys(toys) {
   if (toys === undefined || toys === null) {
     return {};
   }
 
   if (!isPlainObject(toys)) {
-    throw new TypeError('Kimten config "toys" must be an object map of functions or tool definitions.');
+    throw new TypeError('Kimten config "toys" must be an object map of tool definitions.');
   }
 
   const wrapped = {};
@@ -46,16 +85,9 @@ export function normalizeToys(toys) {
 }
 
 function normalizeToyDefinition(name, entry) {
-  if (typeof entry === 'function') {
-    return {
-      inputSchema: z.any(),
-      execute: entry,
-    };
-  }
-
   if (!isPlainObject(entry)) {
     throw new TypeError(
-      `Kimten tool "${name}" must be a function or an object with execute(args).`
+      `Kimten tool "${name}" must be an object with execute(args).`
     );
   }
 

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
   "description": "A micro-agent library: thin wrapper over the Agent interface from Vercel's AI SDK Core v6+",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "lib"
   ],
   "scripts": {

package/lib/prompt.js

@@ -1,6 +0,0 @@
-export function buildMessages(personality, history) {
-  return [
-    { role: 'system', content: personality },
-    ...history,
-  ];
-}