@tabbybyte/kimten 0.1.4 → 0.1.5

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,17 +1,22 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.4",
+  "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": {