@tabbybyte/kimten 0.1.5 → 0.3.0

package/README.md

@@ -14,8 +14,8 @@ It’s meant to feel like a smart helper, not a framework.
 
 ## ✅ What it does
 
-- Runs a simple agent loop (bounded by `hops`)
-- Lets the model call your tools (`toys`)
+- Runs a simple, single-agent loop (bounded by `hops`)
+- Lets the LLM model (the brain) call your tool functions (the toys)
 - Keeps short-term conversation memory (in-process, per instance)
 - Supports optional structured output via Zod
 
@@ -24,19 +24,19 @@ It’s meant to feel like a smart helper, not a framework.
 - No planners/graphs/state machines
 - No streaming API surface
 - No persistence or long-term memory
-- No plugin system or orchestration runtime
+- No plugin system or multi-agent orchestration
 
 ---
 
 ## ✨ Why Kimten?
 
-Use it when you just want an agent loop with tools and a little memory, without adopting a larger framework.
+Use it when you just want an agent loop with toys and a little memory, without adopting a larger framework.
 
 Good fits:
 
 - CLI helpers
 - small automations
-- local tools
+- local toys
 - scripting
 - quick AI utilities
 - “just let the model call a function” use cases
@@ -68,9 +68,19 @@ const cat = Kimten({
   brain: openai('gpt-4o-mini'), // or, any other available model
 
   toys: {
-    add: async ({ a, b }) => a + b,
+    randomNumber: {
+      description: 'Generate a random integer between min and max (inclusive).',
+      inputSchema: z.object({ min: z.number().int(), max: z.number().int() }),
+      async execute({ min, max }) {
+        const low = Math.min(min, max);
+        const high = Math.max(min, max);
+        return Math.floor(Math.random() * (high - low + 1)) + low;
+      },
+    },
   },
 
+  personality: 'You are a helpful assistant.',
+
   hops: 10,
 });
 
@@ -89,7 +99,7 @@ cat.forget();
 
 ---
 
-## 🧠 Mental Model
+## 💭 Mental Model
 
 Kimten is basically:
 
@@ -115,35 +125,36 @@ Each instance keeps short-term chat memory, so follow-up prompts naturally refer
 Create a new instance.
 
 #### Required
-* `brain` → AI SDK model instance
+* 🧠 `brain` → AI SDK model instance
 
 #### Optional
 
-* `toys` → object map of tool definitions. Each entry can be:
-  * async function shorthand: `async (args) => result`
+* 🎱 `toys` → object map of toy (tool) definitions. Each entry is:
   * 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 🌀
+* 🕵️‍♂️ `personality` → system instructions / prompt for overall behavior description (default: `'You are a helpful assistant.'`)
+* 🌀 `hops` → max agent loop steps (default: `10`) - prevents infinite zoomies
 
-#### Tool semantics
+#### Toy 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).
+- Toy inputs are validated only if you provide `inputSchema`.
+- Toy results should be JSON-serializable; `undefined` becomes `null`.
+- If a toy function throws, Kimten returns `{ error, toolName }` as the toy result (it does not re-throw).
+- Under the hood, each toy is implemented as an AI SDK tool.
 
 #### Returns
 
-* `play(input, schema?)`
+* `play(input, schema?, context?)`
 
   * runs the agent  
   * uses short-term memory automatically  
   * optional Zod schema for structured output
+  * optional plain object context injected into the current call prompt as JSON (with basic redaction/truncation guards)
+  * context is ephemeral per `play()` call and is not persisted in memory
 
 * `forget()`
 
-  * clears short-term memory/context
+  * clears short-term memory
 
 ---
 
@@ -153,32 +164,25 @@ Create a new instance.
 
 For the `brain` part, feel free to use any compatible provider and their models.
 
-Refer to the AI SDK docs: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
+❗ Note that not all providers (and models) may work out the box with Kimten, particularly for structured output.
 
-### Add tools freely
+💡 Refer to the AI SDK docs for details: **[providers and models](https://ai-sdk.dev/docs/foundations/providers-and-models)**.
 
-Tools can stay simple, just normal async functions:
-
-```js
-toys: {
-  readFile,
-  writeFile,
-  fetchJson,
-  runCommand,
-}
-```
+### Add toys freely
 
-For stronger arg validation and better tool selection, use object form:
+Define `toys` in object form for strong arg validation and proper selection by the LLM:
 
 ```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;
+  randomNumber: {
+    description: 'Generate a random integer between min and max (inclusive).',
+    inputSchema: z.object({ min: z.number().int(), max: z.number().int() }),
+    async execute({ min, max }) {
+      const low = Math.min(min, max);
+      const high = Math.max(min, max);
+      return Math.floor(Math.random() * (high - low + 1)) + low;
     },
   },
 }

package/index.d.ts

@@ -2,16 +2,16 @@ import type { ZodTypeAny, infer as ZodInfer } from 'zod';
 
 export type BrainModel = Record<string, unknown>;
 
-export type ToyFn = (args: any) => any | Promise<any>;
+export type ToolExecute = (args: any) => any | Promise<any>;
 
 export type ToyDefinition = {
   inputSchema?: ZodTypeAny;
   description?: string;
   strict?: boolean;
-  execute: ToyFn;
+  execute: ToolExecute;
 };
 
-export type Toys = Record<string, ToyFn | ToyDefinition>;
+export type Toys = Record<string, ToyDefinition>;
 
 export type KimtenConfig = {
   brain: BrainModel;
@@ -21,8 +21,12 @@ export type KimtenConfig = {
 };
 
 export type KimtenAgent = {
-  play(input: string): Promise<string>;
-  play<S extends ZodTypeAny>(input: string, schema: S): Promise<ZodInfer<S>>;
+  play(input: string, schema?: null, context?: Record<string, unknown> | null): Promise<string>;
+  play<S extends ZodTypeAny>(
+    input: string,
+    schema: S,
+    context?: Record<string, unknown> | null
+  ): Promise<ZodInfer<S>>;
   forget(): void;
 };
 
@@ -30,4 +34,3 @@ export declare function Kimten(config: KimtenConfig): KimtenAgent;
 
 declare const _default: typeof Kimten;
 export default _default;
-

package/lib/kimten.js

@@ -1,9 +1,9 @@
 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.';
+const CONTEXT_CHAR_LIMIT = 4000;
 
 /**
  * @typedef {import('zod').ZodTypeAny} ZodSchema
@@ -23,9 +23,9 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  */
 
 /**
- * Shorthand tool form: any async/sync function.
+ * Tool execute function.
  *
- * @callback ToyFn
+ * @callback ToolExecute
  * @param {any} args
  * @returns {any | Promise<any>}
  */
@@ -37,13 +37,13 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  * @property {import('zod').ZodTypeAny} [inputSchema]
  * @property {string} [description]
  * @property {boolean} [strict]
- * @property {ToyFn} execute
+ * @property {ToolExecute} execute
  */
 
 /**
  * Tool registry map.
  *
- * @typedef {Record<string, ToyFn | ToyDefinition>} Toys
+ * @typedef {Record<string, ToyDefinition>} Toys
  */
 
 /**
@@ -60,7 +60,7 @@ const DEFAULT_PERSONALITY = 'You are a helpful assistant.';
  * Returned Kimten instance.
  *
  * @typedef {object} KimtenAgent
- * @property {(input: string, schema?: ZodSchema | null) => Promise<any>} play Run the agent loop.
+ * @property {(input: string, schema?: ZodSchema | null, context?: Record<string, unknown> | null) => Promise<any>} play Run the agent loop.
  * @property {() => void} forget Clear short-term memory.
  */
 
@@ -92,6 +92,45 @@ function validateConfig(config) {
   };
 }
 
+function serializeContext(context) {
+  if (context === null || context === undefined) {
+    return '';
+  }
+
+  if (typeof context !== 'object' || Array.isArray(context)) {
+    throw new TypeError('Kimten play(input, schema, context) expects context to be a plain object when provided.');
+  }
+
+  const redacted = JSON.stringify(
+    context,
+    (key, value) => {
+      const lowered = String(key).toLowerCase();
+      if (
+        lowered.includes('password') ||
+        lowered.includes('token') ||
+        lowered.includes('secret') ||
+        lowered.includes('apikey') ||
+        lowered.includes('api_key')
+      ) {
+        return '[REDACTED]';
+      }
+
+      return value;
+    },
+    2
+  );
+
+  if (typeof redacted !== 'string') {
+    return '';
+  }
+
+  if (redacted.length <= CONTEXT_CHAR_LIMIT) {
+    return redacted;
+  }
+
+  return `${redacted.slice(0, CONTEXT_CHAR_LIMIT)}\n...(truncated)`;
+}
+
 /**
  * Create a tiny tool-using agent with short-term memory.
  *
@@ -144,19 +183,41 @@ export function Kimten(config) {
    *
    * @param {string} input
    * @param {ZodSchema | null} [schema]
+   * @param {Record<string, unknown> | null} [context]
    * @returns {Promise<any>}
    */
-  async function play(input, schema = null) {
+  async function play(input, schema = null, context = null) {
     if (typeof input !== 'string') {
       throw new TypeError('Kimten play(input) expects input to be a string.');
     }
 
+    // Serialize provided context (redacts sensitive keys and truncates if too long).
+    const serializedContext = serializeContext(context);
+
+    // If we have context, embed it before the user's message so the agent sees both.
+    const effectiveInput = serializedContext
+      ? `Context (JSON):\n${serializedContext}\n\nUser message:\n${input}`
+      : input;
+
+    // Store the raw user message (no context) in short-term memory.
     memory.add({ role: 'user', content: input });
 
+    // Retrieve conversation so far from memory.
+    const fetchedMessages = memory.list();
+
+    // If the last message is the user message we just added, we may need to replace it with
+    // a version that includes the serialized context, so the agent can see that information.
+    // This way we keep the raw user message in memory, but provide the agent with the enriched version.
+    const lastMessage = fetchedMessages[fetchedMessages.length - 1];
+    const messages = serializedContext && lastMessage?.role === 'user'
+      ? [...fetchedMessages.slice(0, -1), { ...lastMessage, content: effectiveInput }]
+      : fetchedMessages;
+
+    // Choose a structured agent when a schema is provided, otherwise use the text agent.
     const agent = schema ? getStructuredAgent(schema) : textAgent;
-    const result = await agent.generate({
-      messages: buildMessages(personality, memory.list()),
-    });
+
+    // Run the agent loop with the prepared messages.
+    const result = await agent.generate({ messages });
 
     const assistantContent =
       schema

package/lib/tools.js

@@ -6,9 +6,9 @@ import { z } from 'zod';
  */
 
 /**
- * Shorthand tool form: any async/sync function.
+ * Tool execute function.
  *
- * @callback ToyFn
+ * @callback ToolExecute
  * @param {any} args
  * @returns {any | Promise<any>}
  */
@@ -20,13 +20,13 @@ import { z } from 'zod';
  * @property {ZodSchema} [inputSchema]
  * @property {string} [description]
  * @property {boolean} [strict]
- * @property {ToyFn} execute
+ * @property {ToolExecute} execute
  */
 
 /**
  * Tool registry map.
  *
- * @typedef {Record<string, ToyFn | ToyDefinition>} Toys
+ * @typedef {Record<string, ToyDefinition>} Toys
  */
 
 function isPlainObject(value) {
@@ -41,8 +41,7 @@ function isPlainObject(value) {
 /**
  * Normalize a toy registry into AI SDK tool objects.
  *
- * - Shorthand entry: `async (args) => result`
- * - Object form: `{ inputSchema?, description?, strict?, execute }`
+ * - Object form only: `{ inputSchema?, description?, strict?, execute }`
  *
  * Tool execution is wrapped so thrown errors become JSON-safe results:
  * `{ error, toolName }` (Kimten does not re-throw tool errors).
@@ -56,7 +55,7 @@ export function normalizeToys(toys) {
   }
 
   if (!isPlainObject(toys)) {
-    throw new TypeError('Kimten config "toys" must be an object map of functions or tool definitions.');
+    throw new TypeError('Kimten config "toys" must be an object map of tool definitions.');
   }
 
   const wrapped = {};
@@ -86,16 +85,9 @@ export function normalizeToys(toys) {
 }
 
 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).`
+      `Kimten tool "${name}" must be an object with execute(args).`
     );
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbybyte/kimten",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },

package/lib/prompt.js

@@ -1,13 +0,0 @@
-/**
- * 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 },
-    ...history,
-  ];
-}