@tabbybyte/kimten 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Project Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# 🐈 kimten
+
+A micro-agent library: thin wrapper over the **[Agent interface in Vercel AI SDK Core v6+](https://ai-sdk.dev/docs/agents)** 
+
+Small surface area, sharp claws, zero fluff (well… almost).
+
+Think:
+
+> minimal agent loop + tools + short-term memory  
+> but delivered as a smol terminal cat 🐾
+
+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.
+
+No planners.  
+No graphs.  
+No magic state machines.  
+Just *play → result → nap*. 😼
+
+---
+
+## ✨ Why Kimten?
+
+Sometimes you don’t want:
+
+- 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
+
+Kimten = **tiny agent loop with paws** 🐾
+
+Perfect for:
+
+- CLI helpers
+- small automations
+- local tools
+- scripting
+- quick AI utilities
+- “just let the model call a function” use cases
+
+---
+
+## 📦 Install
+
+Feed the cat some treats:
+
+```bash
+npm i kimten ai zod @ai-sdk/openai
+```
+
+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';
+import Kimten from 'kimten';
+
+const cat = Kimten({
+  brain: openai('gpt-4o-mini'), // or, any other available model
+
+  toys: {
+    add: async ({ a, b }) => a + b,
+  },
+
+  personality: 'Helpful terminal cat',
+
+  hops: 10,
+});
+
+// free-form text
+const text = await cat.play('summarize this repo');
+
+// structured output
+const structured = await cat.play(
+  'extract the name',
+  z.object({ name: z.string() })
+);
+
+// wipe short-term memory
+cat.forget();
+```
+
+Done.  
+No lifecycle hooks. No config jungle. 🧘
+
+---
+
+## 🧠 Mental Model
+
+Kimten is basically:
+
+```
+loop:
+  include short-term conversation memory
+  prompt LLM
+  maybe call a tool
+  repeat (max hops)
+return result
+```
+
+That’s the whole thing.
+
+Each instance keeps a **small, 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)
+
+* `brain` → AI SDK model instance  
+
+### Optional (extra whiskers)
+
+* `toys` → object map of async functions (tools the model may call), default: `{}`
+* `personality` → system prompt / behavior description (default: `"You are a helpful assistant."`)
+* `hops` → max agent loop steps (default: `10`)  
+  prevents infinite zoomies 🌀
+
+### Returns
+
+* `play(input, schema?)`
+
+  * runs the agent  
+  * uses short-term memory automatically  
+  * optional Zod schema for structured output
+
+* `forget()`
+
+  * clears short-term memory/context
+
+---
+
+## 🧩 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
+
+### Add tools freely
+
+Tools are just async functions:
+
+```js
+toys: {
+  readFile,
+  writeFile,
+  fetchJson,
+  runCommand,
+}
+```
+
+The model decides when to use them.
+
+### Structured output = sanity
+
+Use Zod schemas whenever possible.  
+LLMs lie less when types exist 😼
+
+### Keep hops low
+
+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. 🐈‍⬛
+
+---
+
+## License
+
+MIT  
+Pet responsibly.

package/index.js

@@ -0,0 +1,4 @@
+import { Kimten } from './lib/kimten.js';
+
+export { Kimten };
+export default Kimten;

package/lib/kimten.js

@@ -0,0 +1,106 @@
+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.';
+
+function validateConfig(config) {
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError('Kimten requires a config object.');
+  }
+
+  const { brain, toys = {}, personality = null, hops = 10 } = config;
+
+  if (!brain || typeof brain !== 'object') {
+    throw new TypeError('Kimten config "brain" is required and must be an AI SDK model instance.');
+  }
+
+  const resolvedPersonality = personality ?? DEFAULT_PERSONALITY;
+  if (typeof resolvedPersonality !== 'string' || resolvedPersonality.trim() === '') {
+    throw new TypeError('Kimten config "personality" must be a non-empty string when provided.');
+  }
+
+  if (!Number.isInteger(hops) || hops <= 0) {
+    throw new TypeError('Kimten config "hops" must be a positive integer.');
+  }
+
+  return {
+    brain,
+    toys,
+    personality: resolvedPersonality,
+    hops,
+  };
+}
+
+export function Kimten(config) {
+  const { brain, toys, personality, hops } = validateConfig(config);
+  const memory = createMemory();
+  const tools = normalizeToys(toys);
+  const structuredAgents = new WeakMap(); // Cache for agents based on output schema
+
+  const textAgent = new ToolLoopAgent({
+    model: brain,
+    instructions: personality,
+    tools,
+    stopWhen: stepCountIs(hops),
+  });
+
+  function createStructuredAgent(schema) {
+    return new ToolLoopAgent({
+      model: brain,
+      instructions: personality,
+      tools,
+      stopWhen: stepCountIs(hops),
+      output: Output.object({ schema }),
+    });
+  }
+
+  function getStructuredAgent(schema) {
+    if (schema !== null && (typeof schema === 'object' || typeof schema === 'function')) {
+      const cached = structuredAgents.get(schema);
+      if (cached) {
+        return cached;
+      }
+
+      const created = createStructuredAgent(schema);
+      structuredAgents.set(schema, created);
+      return created;
+    }
+
+    return createStructuredAgent(schema);
+  }
+
+  async function play(input, schema = null) {
+    if (typeof input !== 'string') {
+      throw new TypeError('Kimten play(input) expects input to be a string.');
+    }
+
+    memory.add({ role: 'user', content: input });
+
+    const agent = schema ? getStructuredAgent(schema) : textAgent;
+    const result = await agent.generate({
+      messages: buildMessages(personality, memory.list()),
+    });
+
+    const assistantContent =
+      schema
+        ? (typeof result.text === 'string' && result.text.trim() !== ''
+            ? result.text
+            : JSON.stringify(result.output ?? null))
+        : (typeof result.text === 'string' ? result.text : '');
+
+    memory.add({ role: 'assistant', content: assistantContent });
+
+    return schema ? result.output : assistantContent;
+  }
+
+  function forget() {
+    memory.clear();
+  }
+
+  return {
+    play,
+    forget,
+  };
+}

package/lib/memory.js

@@ -0,0 +1,26 @@
+export const MEMORY_LIMIT = 10;
+
+export function createMemory(limit = MEMORY_LIMIT) {
+  const history = [];
+
+  function add(message) {
+    history.push(message);
+    if (history.length > limit) {
+      history.shift();
+    }
+  }
+
+  function list() {
+    return history.slice();
+  }
+
+  function clear() {
+    history.length = 0;
+  }
+
+  return {
+    add,
+    list,
+    clear,
+  };
+}

package/lib/prompt.js

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

package/lib/tools.js

@@ -0,0 +1,58 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+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.');
+  }
+
+  const wrapped = {};
+
+  for (const [name, fn] of Object.entries(toys)) {
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Kimten tool "${name}" must be a function.`);
+    }
+
+    wrapped[name] = tool({
+      inputSchema: z.any(),
+      async execute(args) {
+        try {
+          const result = await fn(args);
+          return toJsonSafe(result);
+        } catch (error) {
+          return {
+            error: error instanceof Error ? error.message : String(error),
+            toolName: name,
+          };
+        }
+      },
+    });
+  }
+
+  return wrapped;
+}
+
+function toJsonSafe(value) {
+  if (value === undefined) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return { value: String(value) };
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tabbybyte/kimten",
+  "version": "0.1.1",
+    "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",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "tools",
+    "vercel-ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tabbybyte-technologies/kimten.git"
+  },
+  "peerDependencies": {
+    "ai": ">=6",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "ai": "^6.0.0-beta.89",
+    "zod": "^3.25.76"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}