@tabbybyte/kimten 0.1.2 → 0.1.4

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,24 +45,24 @@ Perfect for:
 
 ## 📦 Install
 
-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
 
-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
@@ -77,8 +71,6 @@ const cat = Kimten({
     add: async ({ a, b }) => a + b,
   },
 
-  personality: 'Helpful terminal cat',
-
   hops: 10,
 });
 
@@ -95,9 +87,6 @@ const structured = await cat.play(
 cat.forget();
 ```
 
-Done.  
-No lifecycle hooks. No config jungle. 🧘
-
 ---
 
 ## 🧠 Mental Model
@@ -113,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`
@@ -153,7 +127,13 @@ Create a new cat.
 * `hops` → max agent loop steps (default: `10`)  
   prevents infinite zoomies 🌀
 
-### Returns
+#### 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
 
 * `play(input, schema?)`
 
@@ -167,37 +147,17 @@ Create a new cat.
 
 ---
 
-## 🧩 Design Philosophy
-
-Kimten intentionally avoids “big agent framework energy”.
-
-No:
-
-* streaming APIs
-* planners or graphs
-* middleware/plugins
-* long-term memory
-* persistence/storage
-* hidden background processes
-* TypeScript runtime/build nonsense
-
-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: {
@@ -208,8 +168,6 @@ toys: {
 }
 ```
 
-The model decides when to use them.
-
 For stronger arg validation and better tool selection, use object form:
 
 ```js
@@ -225,11 +183,7 @@ toys: {
   },
 }
 ```
-
-### 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
 
@@ -238,33 +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). 🐾
-
----
-
-## 🐾 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. 🐈‍⬛
+Cats don’t hold grudges (or context).😽
 
 ---
 
 ## License
 
-MIT  
-Pet responsibly.
+[MIT](LICENSE)  
+Pet responsibly. 🐈‍⬛

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -15,7 +15,9 @@
     "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",