@tabbybyte/kimten 0.1.1 → 0.1.3

package/README.md

@@ -54,11 +54,17 @@ Perfect for:
 Feed the cat some treats:
 
 ```bash
-npm i kimten ai zod @ai-sdk/openai
+npm i @tabbybyte/kimten ai zod @ai-sdk/openai
 ```
 
 That’s it. No ceremony. No rituals. 🍗
 
+### Requirements
+
+- Node `>=22`
+- AI SDK Core `>=6`
+- Zod `>=3`
+
 ---
 
 ## 🚀 Usage
@@ -68,7 +74,7 @@ Summon your little helper (with or without `toys`) and let it `play`.
 ```js
 import { openai } from '@ai-sdk/openai'; // or, any other provider
 import { z } from 'zod';
-import Kimten from 'kimten';
+import Kimten from '@tabbybyte/kimten';
 
 const cat = Kimten({
   brain: openai('gpt-4o-mini'), // or, any other available model
@@ -145,11 +151,20 @@ Create a new cat.
 
 ### Optional (extra whiskers)
 
-* `toys` → object map of async functions (tools the model may call), default: `{}`
+* `toys` → object map of tool definitions. Each entry can be:
+  * async function shorthand: `async (args) => result`
+  * 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 🌀
 
+### Tool semantics (important)
+
+- 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).
+
 ### Returns
 
 * `play(input, schema?)`
@@ -164,10 +179,18 @@ Create a new cat.
 
 ---
 
-## 🧩 Design Philosophy
+## 🧩 Design Philosophy & Vibes
 
 Kimten intentionally avoids “big agent framework energy”.
 
+It’s meant to be:
+
+* small
+* opinionated
+* dependency-light
+* short-term memory by design
+* easy to embed anywhere
+
 No:
 
 * streaming APIs
@@ -177,6 +200,7 @@ No:
 * persistence/storage
 * hidden background processes
 * TypeScript runtime/build nonsense
+* full fledged orchestration system
 
 If you need those… use something heavier.
 
@@ -194,7 +218,7 @@ Refer to https://ai-sdk.dev/docs/foundations/providers-and-models
 
 ### Add tools freely
 
-Tools are just async functions:
+Tools can stay simple:
 
 ```js
 toys: {
@@ -207,6 +231,38 @@ toys: {
 
 The model decides when to use them.
 
+For stronger arg validation and better tool selection, use object form:
+
+```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;
+    },
+  },
+}
+```
+
+### Small “real” example
+
+```js
+toys: {
+  fetchJson: {
+    description: 'Fetch JSON from a URL (GET).',
+    inputSchema: z.object({ url: z.string().url() }),
+    async execute({ url }) {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    },
+  },
+}
+```
+
 ### Structured output = sanity
 
 Use Zod schemas whenever possible.  
@@ -223,28 +279,6 @@ Cats don’t hold grudges (or context). 🐾
 
 ---
 
-## 🐾 Vibes
-
-Kimten is:
-
-* small
-* opinionated
-* dependency-light
-* short-memory by design
-* easy to embed anywhere
-
-It’s not trying to be LangChain or a full orchestration system.
-
-It’s just a cat.
-
-A helpful one.
-
-In your terminal.
-
-Typing. 🐈‍⬛
-
----
-
 ## License
 
 MIT  

package/lib/tools.js

@@ -16,21 +16,21 @@ export function normalizeToys(toys) {
   }
 
   if (!isPlainObject(toys)) {
-    throw new TypeError('Kimten config "toys" must be an object map of functions.');
+    throw new TypeError('Kimten config "toys" must be an object map of functions or tool definitions.');
   }
 
   const wrapped = {};
 
-  for (const [name, fn] of Object.entries(toys)) {
-    if (typeof fn !== 'function') {
-      throw new TypeError(`Kimten tool "${name}" must be a function.`);
-    }
+  for (const [name, entry] of Object.entries(toys)) {
+    const definition = normalizeToyDefinition(name, entry);
 
     wrapped[name] = tool({
-      inputSchema: z.any(),
+      inputSchema: definition.inputSchema,
+      ...(definition.description ? { description: definition.description } : {}),
+      ...(definition.strict !== undefined ? { strict: definition.strict } : {}),
       async execute(args) {
         try {
-          const result = await fn(args);
+          const result = await definition.execute(args);
           return toJsonSafe(result);
         } catch (error) {
           return {
@@ -45,6 +45,40 @@ export function normalizeToys(toys) {
   return wrapped;
 }
 
+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).`
+    );
+  }
+
+  if (typeof entry.execute !== 'function') {
+    throw new TypeError(`Kimten tool "${name}" object form must include execute(args).`);
+  }
+
+  if (entry.description !== undefined && typeof entry.description !== 'string') {
+    throw new TypeError(`Kimten tool "${name}" description must be a string when provided.`);
+  }
+
+  if (entry.strict !== undefined && typeof entry.strict !== 'boolean') {
+    throw new TypeError(`Kimten tool "${name}" strict must be a boolean when provided.`);
+  }
+
+  return {
+    inputSchema: entry.inputSchema ?? z.any(),
+    execute: entry.execute,
+    description: entry.description,
+    strict: entry.strict,
+  };
+}
+
 function toJsonSafe(value) {
   if (value === undefined) {
     return null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.1",
-    "publishConfig": {
+  "version": "0.1.3",
+  "publishConfig": {
     "access": "public"
   },
   "description": "A micro-agent library: thin wrapper over the Agent interface from Vercel's AI SDK Core v6+",