@tabbybyte/kimten 0.1.3 → 0.1.5

package/README.md

@@ -1,44 +1,38 @@
 # 🐈 kimten
+🐾 _**A tiny agent loop with paws**_ 🐾
 
-A micro-agent library: thin wrapper over the **[Agent interface in Vercel AI SDK Core v6+](https://ai-sdk.dev/docs/agents)** 
+[![build](https://github.com/tabbybyte-technologies/kimten/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tabbybyte-technologies/kimten/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/tabbybyte-technologies/kimten/branch/main/graph/badge.svg)](https://codecov.io/gh/tabbybyte-technologies/kimten)
+[![npm](https://img.shields.io/npm/v/%40tabbybyte%2Fkimten)](https://www.npmjs.com/package/@tabbybyte/kimten)
+[![last commit](https://img.shields.io/github/last-commit/tabbybyte-technologies/kimten)](https://github.com/tabbybyte-technologies/kimten/commits/main)
+[![license](https://img.shields.io/npm/l/%40tabbybyte%2Fkimten)](LICENSE)
 
-Small surface area, sharp claws, zero fluff (well… almost).
 
-Think:
+Kimten is a minimal micro-agent library: a thin wrapper over the **[Agent interface in Vercel AI SDK Core v6+](https://ai-sdk.dev/docs/agents)**.
 
-> minimal agent loop + tools + short-term memory  
-> but delivered as a smol terminal cat 🐾
+It’s meant to feel like a smart helper, not a framework.
 
-Kimten doesn’t try to be a “framework”.  
-It’s just a neat little helper that runs prompts, calls tools, remembers a little, and gets out of your way.
+## ✅ What it does
 
-No planners.  
-No graphs.  
-No magic state machines.  
-Just *play → result → nap*. 😼
+- Runs a simple agent loop (bounded by `hops`)
+- Lets the model call your tools (`toys`)
+- Keeps short-term conversation memory (in-process, per instance)
+- Supports optional structured output via Zod
 
----
-
-## ✨ Why Kimten?
+## ❌ What it does *not* do
 
-Sometimes you don’t want:
+- No planners/graphs/state machines
+- No streaming API surface
+- No persistence or long-term memory
+- No plugin system or orchestration runtime
 
-- 15 abstractions
-- 6 middlewares
-- 4 “agent runtimes”
-- 200MB of dependencies
-
-You just want:
+---
 
-✔ call an LLM  
-✔ give it tools  
-✔ keep a bit of convo memory  
-✔ maybe get structured output  
-✔ done
+## ✨ Why Kimten?
 
-Kimten = **tiny agent loop with paws** 🐾
+Use it when you just want an agent loop with tools and a little memory, without adopting a larger framework.
 
-Perfect for:
+Good fits:
 
 - CLI helpers
 - small automations
@@ -51,14 +45,10 @@ Perfect for:
 
 ## 📦 Install
 
-Feed the cat some treats:
-
 ```bash
 npm i @tabbybyte/kimten ai zod @ai-sdk/openai
 ```
 
-That’s it. No ceremony. No rituals. 🍗
-
 ### Requirements
 
 - Node `>=22`
@@ -69,8 +59,6 @@ That’s it. No ceremony. No rituals. 🍗
 
 ## 🚀 Usage
 
-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';
@@ -83,8 +71,6 @@ const cat = Kimten({
     add: async ({ a, b }) => a + b,
   },
 
-  personality: 'Helpful terminal cat',
-
   hops: 10,
 });
 
@@ -101,9 +87,6 @@ const structured = await cat.play(
 cat.forget();
 ```
 
-Done.  
-No lifecycle hooks. No config jungle. 🧘
-
 ---
 
 ## 🧠 Mental Model
@@ -119,37 +102,22 @@ loop:
 return result
 ```
 
-That’s the whole thing.
-
-Each instance keeps a **small, short-term chat memory** 🧠  
-So follow-up prompts naturally reference earlier messages:
+Each instance keeps short-term chat memory, so follow-up prompts naturally reference earlier messages:
 
 > “summarize this” → “make it shorter” → “now extract bullets”
 
-When you’re done, call `forget()` and the brain goes blank again. 🫧
-
-It’s intentionally:
-
-* tiny
-* predictable
-* hackable
-* easy to read in one sitting
-
-If you can read the source in ~5 minutes, we did it right 😺
-
 ---
 
 ## ⚙️ API
 
 ### `Kimten(config)`
 
-Create a new cat.
-
-### Required (must-haves)
+Create a new instance.
 
-* `brain` → AI SDK model instance  
+#### Required
+* `brain` → AI SDK model instance
 
-### Optional (extra whiskers)
+#### Optional
 
 * `toys` → object map of tool definitions. Each entry can be:
   * async function shorthand: `async (args) => result`
@@ -159,13 +127,13 @@ Create a new cat.
 * `hops` → max agent loop steps (default: `10`)  
   prevents infinite zoomies 🌀
 
-### Tool semantics (important)
+#### Tool 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).
 
-### Returns
+#### Returns
 
 * `play(input, schema?)`
 
@@ -179,46 +147,17 @@ Create a new cat.
 
 ---
 
-## 🧩 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
-* planners or graphs
-* middleware/plugins
-* long-term memory
-* persistence/storage
-* hidden background processes
-* TypeScript runtime/build nonsense
-* full fledged orchestration system
-
-If you need those… use something heavier.
-
-If you want **simple + fast + composable**, Kimten fits nicely.
-
----
-
 ## 🛠 Tips
 
 ### Providers & models
 
 For the `brain` part, feel free to use any compatible provider and their models.
 
-Refer to https://ai-sdk.dev/docs/foundations/providers-and-models
+Refer to the AI SDK docs: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
 
 ### Add tools freely
 
-Tools can stay simple:
+Tools can stay simple, just normal async functions:
 
 ```js
 toys: {
@@ -229,8 +168,6 @@ toys: {
 }
 ```
 
-The model decides when to use them.
-
 For stronger arg validation and better tool selection, use object form:
 
 ```js
@@ -246,27 +183,7 @@ toys: {
   },
 }
 ```
-
-### 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.  
-LLMs lie less when types exist 😼
+💡 For further details, refer to [AI SDK docs on Tools](https://ai-sdk.dev/docs/foundations/tools)
 
 ### Keep hops low
 
@@ -275,11 +192,11 @@ If you need 50+ steps, you probably want a planner, not Kimten.
 ### Reset when needed
 
 Fresh task? Call `forget()`.  
-Cats don’t hold grudges (or context). 🐾
+Cats don’t hold grudges (or context).😽
 
 ---
 
 ## License
 
-MIT  
-Pet responsibly.
+[MIT](LICENSE)  
+Pet responsibly. 🐈‍⬛

package/index.d.ts

@@ -0,0 +1,33 @@
+import type { ZodTypeAny, infer as ZodInfer } from 'zod';
+
+export type BrainModel = Record<string, unknown>;
+
+export type ToyFn = (args: any) => any | Promise<any>;
+
+export type ToyDefinition = {
+  inputSchema?: ZodTypeAny;
+  description?: string;
+  strict?: boolean;
+  execute: ToyFn;
+};
+
+export type Toys = Record<string, ToyFn | 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

@@ -5,6 +5,65 @@ 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]
+ */
+
+/**
+ * Shorthand tool form: any async/sync function.
+ *
+ * @callback ToyFn
+ * @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 {ToyFn} execute
+ */
+
+/**
+ * Tool registry map.
+ *
+ * @typedef {Record<string, ToyFn | 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 +92,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 +136,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.');
@@ -95,6 +170,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/prompt.js

@@ -1,3 +1,10 @@
+/**
+ * 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 },

package/lib/tools.js

@@ -1,6 +1,34 @@
 import { tool } from 'ai';
 import { z } from 'zod';
 
+/**
+ * @typedef {import('zod').ZodTypeAny} ZodSchema
+ */
+
+/**
+ * Shorthand tool form: any async/sync function.
+ *
+ * @callback ToyFn
+ * @param {any} args
+ * @returns {any | Promise<any>}
+ */
+
+/**
+ * Object-form tool definition.
+ *
+ * @typedef {object} ToyDefinition
+ * @property {ZodSchema} [inputSchema]
+ * @property {string} [description]
+ * @property {boolean} [strict]
+ * @property {ToyFn} execute
+ */
+
+/**
+ * Tool registry map.
+ *
+ * @typedef {Record<string, ToyFn | ToyDefinition>} Toys
+ */
+
 function isPlainObject(value) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
@@ -10,6 +38,18 @@ function isPlainObject(value) {
   return proto === Object.prototype || proto === null;
 }
 
+/**
+ * Normalize a toy registry into AI SDK tool objects.
+ *
+ * - Shorthand entry: `async (args) => result`
+ * - Object form: `{ 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 {};

package/package.json

@@ -1,21 +1,28 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=lib/**/*.js --test-coverage-include=index.js --test-coverage-exclude=test/**/*.js --test-coverage-exclude=node_modules/**",
+    "test:coverage:ci": "node --test --experimental-test-coverage --test-coverage-include=lib/**/*.js --test-coverage-include=index.js --test-coverage-exclude=test/**/*.js --test-coverage-exclude=node_modules/** --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=85"
   },
   "keywords": [
     "ai",