@tabbybyte/kimten 0.1.5 → 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

@@ -2,16 +2,16 @@ import type { ZodTypeAny, infer as ZodInfer } from 'zod';
 
 export type BrainModel = Record<string, unknown>;
 
-export type ToyFn = (args: any) => any | Promise<any>;
+export type ToolExecute = (args: any) => any | Promise<any>;
 
 export type ToyDefinition = {
   inputSchema?: ZodTypeAny;
   description?: string;
   strict?: boolean;
-  execute: ToyFn;
+  execute: ToolExecute;
 };
 
-export type Toys = Record<string, ToyFn | ToyDefinition>;
+export type Toys = Record<string, ToyDefinition>;
 
 export type KimtenConfig = {
   brain: BrainModel;
@@ -30,4 +30,3 @@ export declare function Kimten(config: KimtenConfig): KimtenAgent;
 
 declare const _default: typeof Kimten;
 export default _default;
-

package/lib/kimten.js

@@ -1,6 +1,5 @@
 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.';
@@ -23,9 +22,9 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  */
 
 /**
- * Shorthand tool form: any async/sync function.
+ * Tool execute function.
  *
- * @callback ToyFn
+ * @callback ToolExecute
  * @param {any} args
  * @returns {any | Promise<any>}
  */
@@ -37,13 +36,13 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  * @property {import('zod').ZodTypeAny} [inputSchema]
  * @property {string} [description]
  * @property {boolean} [strict]
- * @property {ToyFn} execute
+ * @property {ToolExecute} execute
  */
 
 /**
  * Tool registry map.
  *
- * @typedef {Record<string, ToyFn | ToyDefinition>} Toys
+ * @typedef {Record<string, ToyDefinition>} Toys
  */
 
 /**
@@ -155,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 =

package/lib/tools.js

@@ -6,9 +6,9 @@ import { z } from 'zod';
  */
 
 /**
- * Shorthand tool form: any async/sync function.
+ * Tool execute function.
  *
- * @callback ToyFn
+ * @callback ToolExecute
  * @param {any} args
  * @returns {any | Promise<any>}
  */
@@ -20,13 +20,13 @@ import { z } from 'zod';
  * @property {ZodSchema} [inputSchema]
  * @property {string} [description]
  * @property {boolean} [strict]
- * @property {ToyFn} execute
+ * @property {ToolExecute} execute
  */
 
 /**
  * Tool registry map.
  *
- * @typedef {Record<string, ToyFn | ToyDefinition>} Toys
+ * @typedef {Record<string, ToyDefinition>} Toys
  */
 
 function isPlainObject(value) {
@@ -41,8 +41,7 @@ function isPlainObject(value) {
 /**
  * Normalize a toy registry into AI SDK tool objects.
  *
- * - Shorthand entry: `async (args) => result`
- * - Object form: `{ inputSchema?, description?, strict?, execute }`
+ * - 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).
@@ -56,7 +55,7 @@ export function normalizeToys(toys) {
   }
 
   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 = {};
@@ -86,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,6 +1,6 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },

package/lib/prompt.js

@@ -1,13 +0,0 @@
-/**
- * Build AI SDK messages for a generation call.
- *
- * @param {string} personality System prompt / instructions.
- * @param {Array<{ role: string, content: any }>} history Prior conversation messages.
- * @returns {Array<{ role: string, content: any }>}
- */
-export function buildMessages(personality, history) {
-  return [
-    { role: 'system', content: personality },
-    ...history,
-  ];
-}