@hardlydifficult/ai 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/ai
 
-Unified AI client with chainable structured output, required usage tracking, and response parsing utilities.
+Unified AI client with chainable structured output, callback-based streaming, tool-calling agent, required usage tracking, and response parsing utilities.
 
 ## Installation
 
@@ -10,16 +10,20 @@ npm install @hardlydifficult/ai
 
 ## AI Client
 
-### `createAI(model, tracker, options?)`
+### `createAI(model, tracker, logger, options?)`
 
-Creates an AI client. Usage tracking is **required** — every call automatically fires `tracker.record()`.
+Creates an AI client. Usage tracking and logging are **required** — every call automatically fires `tracker.record()` and logs via `logger`.
 
 ```typescript
-import { createAI, claude } from "@hardlydifficult/ai";
+import { createAI, claude, ollama } from "@hardlydifficult/ai";
+import { Logger, ConsolePlugin } from "@hardlydifficult/logger";
 
-const ai = createAI(claude("sonnet"), tracker);
+const logger = new Logger().use(new ConsolePlugin());
+const ai = createAI(claude("sonnet"), tracker, logger);
 ```
 
+Options: `{ maxTokens?: number, temperature?: number }`. Per-request AI instances are free — `createAI()` is a closure factory with zero async overhead.
+
 ### `chat(prompt, systemPrompt?)`
 
 Send a prompt and get a rich response with usage info and conversation support.
@@ -33,6 +37,12 @@ msg.usage; // { inputTokens: 50, outputTokens: 200, durationMs: 1200 }
 const msg = await ai.chat("Explain closures", "You are a TypeScript tutor");
 ```
 
+### `.text()` — String Shorthand
+
+```typescript
+const text = await ai.chat("Summarize this").text(); // → string
+```
+
 ### `.zod(schema)` — Structured Output
 
 Chain `.zod(schema)` to constrain the model's output format AND validate the result. The schema does triple duty: constrains output, validates response, provides TypeScript types.
@@ -45,8 +55,8 @@ const TaskSchema = z.object({
   priority: z.enum(["high", "medium", "low"]),
 });
 
-const msg = await ai.chat("Create a task for fixing the login bug").zod(TaskSchema);
-msg.data; // { title: "Fix login bug", priority: "high" } — typed as z.infer<typeof TaskSchema>
+const data = await ai.chat("Create a task for fixing the login bug").zod(TaskSchema);
+// { title: "Fix login bug", priority: "high" } — typed as z.infer<typeof TaskSchema>
 ```
 
 ### `.reply(prompt)` — Conversation
@@ -59,6 +69,46 @@ const msg2 = await msg1.reply("Give me a TypeScript example");
 const msg3 = await msg2.reply("Now formalize it").zod(DefinitionSchema);
 ```
 
+### `stream(messages, onText)` — Callback-Based Streaming
+
+Stream text deltas via callback. Returns accumulated text + usage when done.
+
+```typescript
+const result = await ai.stream(messages, (text) => process.stdout.write(text));
+result.text;  // full accumulated text
+result.usage; // { inputTokens, outputTokens, durationMs }
+```
+
+### `agent(tools, options?)` — Tool-Calling Agent
+
+Create a tool-calling agent. Tools are plain objects — no SDK imports needed. Tool calls and results are auto-logged via Logger.
+
+```typescript
+import type { ToolMap } from "@hardlydifficult/ai";
+
+const tools: ToolMap = {
+  read_file: {
+    description: "Read a file",
+    inputSchema: z.object({ path: z.string() }),
+    execute: async ({ path }) => fs.readFileSync(path, "utf-8"),
+  },
+};
+
+// Non-streaming
+const result = await ai.agent(tools).run(messages);
+
+// Streaming — function shorthand
+await ai.agent(tools).stream(messages, (text) => process.stdout.write(text));
+
+// Streaming — with tool call markers
+await ai.agent(tools, { maxSteps: 20 }).stream(messages, {
+  onText: (text) => process.stdout.write(text),
+  onToolCall: (name) => console.log(`Using tool: ${name}`),
+});
+```
+
+Agent options: `{ maxSteps?: number (default 10), temperature?: number (default 0.7), maxTokens?: number (default 4096) }`.
+
 ## Model Helpers
 
 ### `claude(variant)`
@@ -86,7 +136,7 @@ ollama("llama3.3");
 
 ## Usage Tracking
 
-`createAI` requires an `AITracker` — no AI without tracking. The tracker fires for every call (`chat`, `reply`, `zod`).
+`createAI` requires an `AITracker` — no AI without tracking. The tracker fires for every call (`chat`, `reply`, `zod`, `stream`, `agent`).
 
 ```typescript
 import type { AITracker } from "@hardlydifficult/ai";
@@ -98,7 +148,7 @@ const tracker: AITracker = {
   },
 };
 
-const ai = createAI(claude("sonnet"), tracker);
+const ai = createAI(claude("sonnet"), tracker, logger);
 ```
 
 ## Response Parsing

package/dist/createAI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createAI.d.ts","sourceRoot":"","sources":["../src/createAI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAgB,KAAK,aAAa,EAAU,MAAM,IAAI,CAAC;AAG9D,OAAO,KAAK,EACV,EAAE,EACF,SAAS,EACT,SAAS,EAIV,MAAM,YAAY,CAAC;AA6IpB,qEAAqE;AACrE,wBAAgB,QAAQ,CACtB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,SAAS,GAClB,EAAE,CAoBJ"}
+{"version":3,"file":"createAI.d.ts","sourceRoot":"","sources":["../src/createAI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAgB,KAAK,aAAa,EAAU,MAAM,IAAI,CAAC;AAK9D,OAAO,KAAK,EAIV,EAAE,EACF,SAAS,EACT,SAAS,EAMV,MAAM,YAAY,CAAC;AA6IpB,qEAAqE;AACrE,wBAAgB,QAAQ,CACtB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,SAAS,GAClB,EAAE,CA4CJ"}

package/dist/createAI.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAI = createAI;
 const ai_1 = require("ai");
+const createAgent_js_1 = require("./createAgent.js");
+const createStream_js_1 = require("./createStream.js");
 const DEFAULT_MAX_TOKENS = 4096;
 function createChatCall(model, tracker, logger, maxTokens, messages, systemPrompt) {
     let zodSchema;
@@ -91,10 +93,21 @@ function createAI(model, tracker, logger, options) {
         throw new Error("AITracker is required — all AI usage must be tracked");
     }
     const maxTokens = options?.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const temperature = options?.temperature;
     return {
         chat(prompt, systemPrompt) {
             return createChatCall(model, tracker, logger, maxTokens, [{ role: "user", content: prompt }], systemPrompt);
         },
+        stream(messages, onText) {
+            return (0, createStream_js_1.runStream)(model, tracker, logger, messages, onText, maxTokens, temperature);
+        },
+        agent(tools, agentOptions) {
+            return (0, createAgent_js_1.createAgent)(model, tools, tracker, logger, {
+                maxSteps: agentOptions?.maxSteps,
+                maxTokens: agentOptions?.maxTokens ?? maxTokens,
+                temperature: agentOptions?.temperature ?? temperature,
+            });
+        },
     };
 }
 //# sourceMappingURL=createAI.js.map

package/dist/createAI.js.map

@@ -1 +1 @@
-{"version":3,"file":"createAI.js","sourceRoot":"","sources":["../src/createAI.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"createAI.js","sourceRoot":"","sources":["../src/createAI.ts"],"names":[],"mappings":"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"}

package/dist/createAgent.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from "@hardlydifficult/logger";
+import { type LanguageModel } from "ai";
+import type { Agent, AgentOptions, AITracker, ToolMap } from "./types.js";
+/** Create a tool-calling Agent bound to a model, tools, and tracker. */
+export declare function createAgent(model: LanguageModel, tools: ToolMap, tracker: AITracker, logger: Logger, options?: AgentOptions): Agent;
+//# sourceMappingURL=createAgent.d.ts.map

package/dist/createAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAgent.d.ts","sourceRoot":"","sources":["../src/createAgent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,IAAI,CAAC;AAEZ,OAAO,KAAK,EACV,KAAK,EAEL,YAAY,EAEZ,SAAS,EAET,OAAO,EAER,MAAM,YAAY,CAAC;AAiDpB,wEAAwE;AACxE,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,YAAY,GACrB,KAAK,CAiGP"}

package/dist/createAgent.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgent = createAgent;
+const ai_1 = require("ai");
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_TEMPERATURE = 0.7;
+/** Normalize the handler arg into AgentCallbacks. */
+function toCallbacks(handler) {
+    return typeof handler === "function" ? { onText: handler } : handler;
+}
+/** Convert ToolMap entries to AI SDK tool() calls, wrapping execute with logging + callbacks. */
+function convertTools(tools, logger, callbacks) {
+    const result = {};
+    for (const [name, def] of Object.entries(tools)) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK tool() requires explicit generic params for heterogeneous ToolMap
+        result[name] = (0, ai_1.tool)({
+            description: def.description,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- ToolMap uses any to support heterogeneous schemas
+            inputSchema: def.inputSchema,
+            execute: async (args) => {
+                logger.debug("Tool call", { tool: name, input: args });
+                callbacks?.onToolCall?.(name, args);
+                const output = await def.execute(args);
+                logger.debug("Tool result", {
+                    tool: name,
+                    outputLength: output.length,
+                });
+                callbacks?.onToolResult?.(name, output);
+                return output;
+            },
+        });
+    }
+    return result;
+}
+/** Create a tool-calling Agent bound to a model, tools, and tracker. */
+function createAgent(model, tools, tracker, logger, options) {
+    const maxSteps = options?.maxSteps ?? DEFAULT_MAX_STEPS;
+    const maxTokens = options?.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const temperature = options?.temperature ?? DEFAULT_TEMPERATURE;
+    return {
+        async run(messages) {
+            const startMs = Date.now();
+            const sdkTools = convertTools(tools, logger);
+            logger.debug("Agent run start", {
+                messageCount: messages.length,
+                toolCount: Object.keys(tools).length,
+                maxSteps,
+            });
+            const result = await (0, ai_1.generateText)({
+                model,
+                messages,
+                tools: sdkTools,
+                stopWhen: (0, ai_1.stepCountIs)(maxSteps),
+                maxOutputTokens: maxTokens,
+                temperature,
+            });
+            const durationMs = Date.now() - startMs;
+            const resultUsage = result.usage;
+            const usage = {
+                inputTokens: resultUsage.inputTokens ?? 0,
+                outputTokens: resultUsage.outputTokens ?? 0,
+                durationMs,
+            };
+            tracker.record(usage);
+            logger.debug("Agent run complete", {
+                responseLength: result.text.length,
+                durationMs,
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+            });
+            return { text: result.text, usage };
+        },
+        async stream(messages, handler) {
+            const callbacks = toCallbacks(handler);
+            const startMs = Date.now();
+            const sdkTools = convertTools(tools, logger, callbacks);
+            logger.debug("Agent stream start", {
+                messageCount: messages.length,
+                toolCount: Object.keys(tools).length,
+                maxSteps,
+            });
+            const result = (0, ai_1.streamText)({
+                model,
+                messages,
+                tools: sdkTools,
+                stopWhen: (0, ai_1.stepCountIs)(maxSteps),
+                maxOutputTokens: maxTokens,
+                temperature,
+            });
+            let accumulated = "";
+            for await (const part of result.fullStream) {
+                if (part.type === "text-delta") {
+                    accumulated += part.text;
+                    callbacks.onText(part.text);
+                }
+            }
+            const resultUsage = await result.usage;
+            const durationMs = Date.now() - startMs;
+            const usage = {
+                inputTokens: resultUsage.inputTokens ?? 0,
+                outputTokens: resultUsage.outputTokens ?? 0,
+                durationMs,
+            };
+            tracker.record(usage);
+            logger.debug("Agent stream complete", {
+                responseLength: accumulated.length,
+                durationMs,
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+            });
+            return { text: accumulated, usage };
+        },
+    };
+}
+//# sourceMappingURL=createAgent.js.map

package/dist/createAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAgent.js","sourceRoot":"","sources":["../src/createAgent.ts"],"names":[],"mappings":"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"}

package/dist/createStream.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from "@hardlydifficult/logger";
+import { type LanguageModel } from "ai";
+import type { AgentResult, AITracker, Message } from "./types.js";
+/** Stream a response, calling onText for each text delta. */
+export declare function runStream(model: LanguageModel, tracker: AITracker, logger: Logger, messages: Message[], onText: (text: string) => void, maxTokens?: number, temperature?: number): Promise<AgentResult>;
+//# sourceMappingURL=createStream.d.ts.map

package/dist/createStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStream.d.ts","sourceRoot":"","sources":["../src/createStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,KAAK,aAAa,EAAc,MAAM,IAAI,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAS,MAAM,YAAY,CAAC;AAIzE,6DAA6D;AAC7D,wBAAsB,SAAS,CAC7B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC9B,SAAS,GAAE,MAA2B,EACtC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CAwCtB"}

package/dist/createStream.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStream = runStream;
+const ai_1 = require("ai");
+const DEFAULT_MAX_TOKENS = 4096;
+/** Stream a response, calling onText for each text delta. */
+async function runStream(model, tracker, logger, messages, onText, maxTokens = DEFAULT_MAX_TOKENS, temperature) {
+    const startMs = Date.now();
+    logger.debug("AI stream start", {
+        messageCount: messages.length,
+    });
+    const result = (0, ai_1.streamText)({
+        model,
+        messages,
+        maxOutputTokens: maxTokens,
+        ...(temperature !== undefined && { temperature }),
+    });
+    let accumulated = "";
+    for await (const chunk of result.textStream) {
+        accumulated += chunk;
+        onText(chunk);
+    }
+    const resultUsage = await result.usage;
+    const durationMs = Date.now() - startMs;
+    const usage = {
+        inputTokens: resultUsage.inputTokens ?? 0,
+        outputTokens: resultUsage.outputTokens ?? 0,
+        durationMs,
+    };
+    tracker.record(usage);
+    logger.debug("AI stream complete", {
+        responseLength: accumulated.length,
+        durationMs,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+    });
+    return { text: accumulated, usage };
+}
+//# sourceMappingURL=createStream.js.map

package/dist/createStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStream.js","sourceRoot":"","sources":["../src/createStream.ts"],"names":[],"mappings":";;AAQA,8BAgDC;AAvDD,2BAAoD;AAIpD,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,6DAA6D;AACtD,KAAK,UAAU,SAAS,CAC7B,KAAoB,EACpB,OAAkB,EAClB,MAAc,EACd,QAAmB,EACnB,MAA8B,EAC9B,YAAoB,kBAAkB,EACtC,WAAoB;IAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE3B,MAAM,CAAC,KAAK,CAAC,iBAAiB,EAAE;QAC9B,YAAY,EAAE,QAAQ,CAAC,MAAM;KAC9B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAA,eAAU,EAAC;QACxB,KAAK;QACL,QAAQ;QACR,eAAe,EAAE,SAAS;QAC1B,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC;KAClD,CAAC,CAAC;IAEH,IAAI,WAAW,GAAG,EAAE,CAAC;IAErB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC5C,WAAW,IAAI,KAAK,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;IAExC,MAAM,KAAK,GAAU;QACnB,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,CAAC;QACzC,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,CAAC;QAC3C,UAAU;KACX,CAAC;IAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtB,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE;QACjC,cAAc,EAAE,WAAW,CAAC,MAAM;QAClC,UAAU;QACV,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createAI } from "./createAI.js";
 export { claude } from "./claude.js";
 export { ollama } from "./ollama.js";
-export type { AI, AIOptions, AITracker, ChatCall, ChatMessage, Usage, } from "./types.js";
+export type { Agent, AgentCallbacks, AgentOptions, AgentResult, AI, AIOptions, AITracker, ChatCall, ChatMessage, Message, ToolDefinition, ToolMap, Usage, } from "./types.js";
 export { extractCodeBlock } from "./extractCodeBlock.js";
 export { extractJson } from "./extractJson.js";
 export { extractTyped, type SchemaLike } from "./extractTyped.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,EAAE,EACF,SAAS,EACT,SAAS,EACT,QAAQ,EACR,WAAW,EACX,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EACV,KAAK,EACL,cAAc,EACd,YAAY,EACZ,WAAW,EACX,EAAE,EACF,SAAS,EACT,SAAS,EACT,QAAQ,EACR,WAAW,EACX,OAAO,EACP,cAAc,EACd,OAAO,EACP,KAAK,GACN,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AACf,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AASf,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,qDAAkE;AAAzD,+GAAA,YAAY,OAAA;AACrB,iDAIyB;AAHvB,mHAAA,kBAAkB,OAAA;AAClB,oHAAA,mBAAmB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AACf,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AAgBf,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,qDAAkE;AAAzD,+GAAA,YAAY,OAAA;AACrB,iDAIyB;AAHvB,mHAAA,kBAAkB,OAAA;AAClB,oHAAA,mBAAmB,OAAA"}

package/dist/types.d.ts

@@ -9,6 +9,7 @@ export interface AITracker {
 }
 export interface AIOptions {
     maxTokens?: number;
+    temperature?: number;
 }
 export interface ChatMessage {
     text: string;
@@ -19,7 +20,44 @@ export interface ChatCall extends PromiseLike<ChatMessage> {
     text(): PromiseLike<string>;
     zod<TSchema extends z.ZodType>(schema: TSchema): PromiseLike<z.infer<TSchema>>;
 }
+/** A conversation message. */
+export interface Message {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+/** Tool definition — consumers define tools as plain objects, no SDK import needed. */
+export interface ToolDefinition<TInput extends z.ZodType = z.ZodType> {
+    description: string;
+    inputSchema: TInput;
+    execute: (input: z.infer<TInput>) => Promise<string>;
+}
+/** Named set of tools. Each tool may have a different input schema. */
+export type ToolMap = Record<string, ToolDefinition<any>>;
+/** Callbacks for agent streaming. Tool calls are auto-logged via Logger. */
+export interface AgentCallbacks {
+    onText: (text: string) => void;
+    onToolCall?: (name: string, input: Record<string, unknown>) => void;
+    onToolResult?: (name: string, result: string) => void;
+}
+/** Options for creating an agent. */
+export interface AgentOptions {
+    maxSteps?: number;
+    temperature?: number;
+    maxTokens?: number;
+}
+/** Result of a stream or agent run. */
+export interface AgentResult {
+    text: string;
+    usage: Usage;
+}
+/** Tool-calling agent bound to a model and tool set. */
+export interface Agent {
+    run(messages: Message[]): Promise<AgentResult>;
+    stream(messages: Message[], handler: ((text: string) => void) | AgentCallbacks): Promise<AgentResult>;
+}
 export interface AI {
     chat(prompt: string, systemPrompt?: string): ChatCall;
+    stream(messages: Message[], onText: (text: string) => void): Promise<AgentResult>;
+    agent(tools: ToolMap, options?: AgentOptions): Agent;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,WAAW,KAAK;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;CACjC;AAED,MAAM,WAAW,QAAS,SAAQ,WAAW,CAAC,WAAW,CAAC;IACxD,IAAI,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,EAC3B,MAAM,EAAE,OAAO,GACd,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,EAAE;IACjB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CACvD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/ai",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [