llmist 0.1.1

package/dist/testing/index.d.cts

@@ -0,0 +1,274 @@
+import { B as BaseGadget } from '../mock-stream-D4erlo7B.cjs';
+export { a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-D4erlo7B.cjs';
+import { ZodType } from 'zod';
+import 'tslog';
+
+/**
+ * Testing utilities for gadgets.
+ *
+ * Provides helpers for testing gadgets with schema validation without
+ * requiring full executor setup.
+ *
+ * @module testing/gadget-testing
+ */
+
+/**
+ * Result of testing a gadget.
+ */
+interface TestGadgetResult {
+    /** Result string if execution succeeded */
+    result?: string;
+    /** Error message if validation or execution failed */
+    error?: string;
+    /** Parameters after validation and default application */
+    validatedParams?: Record<string, unknown>;
+}
+/**
+ * Options for testGadget.
+ */
+interface TestGadgetOptions {
+    /**
+     * If true, skip schema validation.
+     * Useful for testing gadget behavior with invalid parameters.
+     */
+    skipValidation?: boolean;
+}
+/**
+ * Test a gadget with schema validation and default application.
+ *
+ * This helper replicates the validation behavior from GadgetExecutor.execute(),
+ * making it easy to test gadgets in isolation without setting up a full
+ * registry and executor.
+ *
+ * @param gadget - Gadget instance to test
+ * @param params - Raw parameters (before validation)
+ * @param options - Test options
+ * @returns Promise resolving to test result
+ *
+ * @example
+ * ```typescript
+ * import { testGadget } from 'llmist/testing';
+ * import { createGadget } from 'llmist';
+ * import { z } from 'zod';
+ *
+ * const calculator = createGadget({
+ *   description: 'Add numbers',
+ *   schema: z.object({
+ *     a: z.number(),
+ *     b: z.number().default(0),
+ *   }),
+ *   execute: ({ a, b }) => String(a + b),
+ * });
+ *
+ * // Test with defaults applied
+ * const result = await testGadget(calculator, { a: 5 });
+ * expect(result.result).toBe('5');
+ * expect(result.validatedParams).toEqual({ a: 5, b: 0 });
+ *
+ * // Test validation errors
+ * const invalid = await testGadget(calculator, { a: 'not a number' });
+ * expect(invalid.error).toContain('Invalid parameters');
+ *
+ * // Test with validation skipped
+ * const skipped = await testGadget(calculator, { a: 5 }, { skipValidation: true });
+ * expect(skipped.validatedParams).toEqual({ a: 5 }); // No defaults applied
+ * ```
+ */
+declare function testGadget(gadget: BaseGadget, params: Record<string, unknown>, options?: TestGadgetOptions): Promise<TestGadgetResult>;
+/**
+ * Test multiple parameter sets against a gadget.
+ *
+ * Convenience helper for running the same gadget with different inputs.
+ *
+ * @param gadget - Gadget instance to test
+ * @param paramSets - Array of parameter sets to test
+ * @param options - Test options applied to all tests
+ * @returns Promise resolving to array of test results
+ *
+ * @example
+ * ```typescript
+ * const results = await testGadgetBatch(calculator, [
+ *   { a: 1, b: 2 },
+ *   { a: 5 },
+ *   { a: 'invalid' },
+ * ]);
+ *
+ * expect(results[0].result).toBe('3');
+ * expect(results[1].result).toBe('5');
+ * expect(results[2].error).toBeDefined();
+ * ```
+ */
+declare function testGadgetBatch(gadget: BaseGadget, paramSets: Record<string, unknown>[], options?: TestGadgetOptions): Promise<TestGadgetResult[]>;
+
+/**
+ * Mock gadget utilities for testing.
+ *
+ * Provides helpers for creating mock gadgets with configurable behavior
+ * and call tracking.
+ *
+ * @module testing/mock-gadget
+ */
+
+/**
+ * Recorded gadget call for tracking.
+ */
+interface RecordedCall {
+    /** Parameters passed to execute() */
+    params: Record<string, unknown>;
+    /** When the call was made */
+    timestamp: number;
+}
+/**
+ * Mock gadget with call tracking capabilities.
+ */
+interface MockGadget extends BaseGadget {
+    /** Get all recorded calls */
+    getCalls(): RecordedCall[];
+    /** Get number of times the gadget was executed */
+    getCallCount(): number;
+    /** Reset call history */
+    resetCalls(): void;
+    /** Check if gadget was called with specific params (partial match) */
+    wasCalledWith(params: Partial<Record<string, unknown>>): boolean;
+    /** Get the last call's parameters */
+    getLastCall(): RecordedCall | undefined;
+}
+/**
+ * Configuration for creating a mock gadget.
+ */
+interface MockGadgetConfig<TSchema extends ZodType = ZodType> {
+    /** Gadget name (required) */
+    name: string;
+    /** Gadget description */
+    description?: string;
+    /** Parameter schema */
+    schema?: TSchema;
+    /** Static result to return */
+    result?: string;
+    /** Dynamic result based on parameters */
+    resultFn?: (params: Record<string, unknown>) => string | Promise<string>;
+    /** Error to throw on execution */
+    error?: Error | string;
+    /** Enable call tracking (default: true) */
+    trackCalls?: boolean;
+    /** Execution delay in ms */
+    delayMs?: number;
+    /** Gadget timeout setting */
+    timeoutMs?: number;
+}
+/**
+ * Create a mock gadget for testing.
+ *
+ * @param config - Mock gadget configuration
+ * @returns MockGadget instance with call tracking
+ *
+ * @example
+ * ```typescript
+ * import { createMockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const calculator = createMockGadget({
+ *   name: 'Calculator',
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   resultFn: ({ a, b }) => String(Number(a) + Number(b)),
+ * });
+ *
+ * // Use in tests
+ * const registry = new GadgetRegistry();
+ * registry.registerByClass(calculator);
+ *
+ * // After running agent...
+ * expect(calculator.getCallCount()).toBe(1);
+ * expect(calculator.wasCalledWith({ a: 5 })).toBe(true);
+ * ```
+ */
+declare function createMockGadget<TSchema extends ZodType>(config: MockGadgetConfig<TSchema>): MockGadget;
+/**
+ * Fluent builder for creating mock gadgets.
+ *
+ * @example
+ * ```typescript
+ * import { mockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const mock = mockGadget()
+ *   .withName('Weather')
+ *   .withDescription('Get weather for a city')
+ *   .withSchema(z.object({ city: z.string() }))
+ *   .returns('Sunny, 72F')
+ *   .trackCalls()
+ *   .build();
+ *
+ * // Or for error testing
+ * const errorMock = mockGadget()
+ *   .withName('Unstable')
+ *   .throws('Service unavailable')
+ *   .build();
+ * ```
+ */
+declare class MockGadgetBuilder {
+    private config;
+    /**
+     * Set the gadget name.
+     */
+    withName(name: string): this;
+    /**
+     * Set the gadget description.
+     */
+    withDescription(description: string): this;
+    /**
+     * Set the parameter schema.
+     */
+    withSchema<T extends ZodType>(schema: T): MockGadgetBuilder;
+    /**
+     * Set a static result to return.
+     */
+    returns(result: string): this;
+    /**
+     * Set a dynamic result function.
+     */
+    returnsAsync(resultFn: (params: Record<string, unknown>) => string | Promise<string>): this;
+    /**
+     * Make the gadget throw an error on execution.
+     */
+    throws(error: Error | string): this;
+    /**
+     * Add execution delay.
+     */
+    withDelay(ms: number): this;
+    /**
+     * Set timeout for the gadget.
+     */
+    withTimeout(ms: number): this;
+    /**
+     * Enable call tracking (enabled by default).
+     */
+    trackCalls(): this;
+    /**
+     * Disable call tracking.
+     */
+    noTracking(): this;
+    /**
+     * Build the mock gadget.
+     */
+    build(): MockGadget;
+}
+/**
+ * Create a fluent builder for mock gadgets.
+ *
+ * @returns New MockGadgetBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const mock = mockGadget()
+ *   .withName('Search')
+ *   .withSchema(z.object({ query: z.string() }))
+ *   .returnsAsync(async ({ query }) => {
+ *     return `Results for: ${query}`;
+ *   })
+ *   .build();
+ * ```
+ */
+declare function mockGadget(): MockGadgetBuilder;
+
+export { type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type RecordedCall, type TestGadgetOptions, type TestGadgetResult, createMockGadget, mockGadget, testGadget, testGadgetBatch };

package/dist/testing/index.d.ts

@@ -0,0 +1,274 @@
+import { B as BaseGadget } from '../mock-stream-D4erlo7B.js';
+export { a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM } from '../mock-stream-D4erlo7B.js';
+import { ZodType } from 'zod';
+import 'tslog';
+
+/**
+ * Testing utilities for gadgets.
+ *
+ * Provides helpers for testing gadgets with schema validation without
+ * requiring full executor setup.
+ *
+ * @module testing/gadget-testing
+ */
+
+/**
+ * Result of testing a gadget.
+ */
+interface TestGadgetResult {
+    /** Result string if execution succeeded */
+    result?: string;
+    /** Error message if validation or execution failed */
+    error?: string;
+    /** Parameters after validation and default application */
+    validatedParams?: Record<string, unknown>;
+}
+/**
+ * Options for testGadget.
+ */
+interface TestGadgetOptions {
+    /**
+     * If true, skip schema validation.
+     * Useful for testing gadget behavior with invalid parameters.
+     */
+    skipValidation?: boolean;
+}
+/**
+ * Test a gadget with schema validation and default application.
+ *
+ * This helper replicates the validation behavior from GadgetExecutor.execute(),
+ * making it easy to test gadgets in isolation without setting up a full
+ * registry and executor.
+ *
+ * @param gadget - Gadget instance to test
+ * @param params - Raw parameters (before validation)
+ * @param options - Test options
+ * @returns Promise resolving to test result
+ *
+ * @example
+ * ```typescript
+ * import { testGadget } from 'llmist/testing';
+ * import { createGadget } from 'llmist';
+ * import { z } from 'zod';
+ *
+ * const calculator = createGadget({
+ *   description: 'Add numbers',
+ *   schema: z.object({
+ *     a: z.number(),
+ *     b: z.number().default(0),
+ *   }),
+ *   execute: ({ a, b }) => String(a + b),
+ * });
+ *
+ * // Test with defaults applied
+ * const result = await testGadget(calculator, { a: 5 });
+ * expect(result.result).toBe('5');
+ * expect(result.validatedParams).toEqual({ a: 5, b: 0 });
+ *
+ * // Test validation errors
+ * const invalid = await testGadget(calculator, { a: 'not a number' });
+ * expect(invalid.error).toContain('Invalid parameters');
+ *
+ * // Test with validation skipped
+ * const skipped = await testGadget(calculator, { a: 5 }, { skipValidation: true });
+ * expect(skipped.validatedParams).toEqual({ a: 5 }); // No defaults applied
+ * ```
+ */
+declare function testGadget(gadget: BaseGadget, params: Record<string, unknown>, options?: TestGadgetOptions): Promise<TestGadgetResult>;
+/**
+ * Test multiple parameter sets against a gadget.
+ *
+ * Convenience helper for running the same gadget with different inputs.
+ *
+ * @param gadget - Gadget instance to test
+ * @param paramSets - Array of parameter sets to test
+ * @param options - Test options applied to all tests
+ * @returns Promise resolving to array of test results
+ *
+ * @example
+ * ```typescript
+ * const results = await testGadgetBatch(calculator, [
+ *   { a: 1, b: 2 },
+ *   { a: 5 },
+ *   { a: 'invalid' },
+ * ]);
+ *
+ * expect(results[0].result).toBe('3');
+ * expect(results[1].result).toBe('5');
+ * expect(results[2].error).toBeDefined();
+ * ```
+ */
+declare function testGadgetBatch(gadget: BaseGadget, paramSets: Record<string, unknown>[], options?: TestGadgetOptions): Promise<TestGadgetResult[]>;
+
+/**
+ * Mock gadget utilities for testing.
+ *
+ * Provides helpers for creating mock gadgets with configurable behavior
+ * and call tracking.
+ *
+ * @module testing/mock-gadget
+ */
+
+/**
+ * Recorded gadget call for tracking.
+ */
+interface RecordedCall {
+    /** Parameters passed to execute() */
+    params: Record<string, unknown>;
+    /** When the call was made */
+    timestamp: number;
+}
+/**
+ * Mock gadget with call tracking capabilities.
+ */
+interface MockGadget extends BaseGadget {
+    /** Get all recorded calls */
+    getCalls(): RecordedCall[];
+    /** Get number of times the gadget was executed */
+    getCallCount(): number;
+    /** Reset call history */
+    resetCalls(): void;
+    /** Check if gadget was called with specific params (partial match) */
+    wasCalledWith(params: Partial<Record<string, unknown>>): boolean;
+    /** Get the last call's parameters */
+    getLastCall(): RecordedCall | undefined;
+}
+/**
+ * Configuration for creating a mock gadget.
+ */
+interface MockGadgetConfig<TSchema extends ZodType = ZodType> {
+    /** Gadget name (required) */
+    name: string;
+    /** Gadget description */
+    description?: string;
+    /** Parameter schema */
+    schema?: TSchema;
+    /** Static result to return */
+    result?: string;
+    /** Dynamic result based on parameters */
+    resultFn?: (params: Record<string, unknown>) => string | Promise<string>;
+    /** Error to throw on execution */
+    error?: Error | string;
+    /** Enable call tracking (default: true) */
+    trackCalls?: boolean;
+    /** Execution delay in ms */
+    delayMs?: number;
+    /** Gadget timeout setting */
+    timeoutMs?: number;
+}
+/**
+ * Create a mock gadget for testing.
+ *
+ * @param config - Mock gadget configuration
+ * @returns MockGadget instance with call tracking
+ *
+ * @example
+ * ```typescript
+ * import { createMockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const calculator = createMockGadget({
+ *   name: 'Calculator',
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   resultFn: ({ a, b }) => String(Number(a) + Number(b)),
+ * });
+ *
+ * // Use in tests
+ * const registry = new GadgetRegistry();
+ * registry.registerByClass(calculator);
+ *
+ * // After running agent...
+ * expect(calculator.getCallCount()).toBe(1);
+ * expect(calculator.wasCalledWith({ a: 5 })).toBe(true);
+ * ```
+ */
+declare function createMockGadget<TSchema extends ZodType>(config: MockGadgetConfig<TSchema>): MockGadget;
+/**
+ * Fluent builder for creating mock gadgets.
+ *
+ * @example
+ * ```typescript
+ * import { mockGadget } from 'llmist/testing';
+ * import { z } from 'zod';
+ *
+ * const mock = mockGadget()
+ *   .withName('Weather')
+ *   .withDescription('Get weather for a city')
+ *   .withSchema(z.object({ city: z.string() }))
+ *   .returns('Sunny, 72F')
+ *   .trackCalls()
+ *   .build();
+ *
+ * // Or for error testing
+ * const errorMock = mockGadget()
+ *   .withName('Unstable')
+ *   .throws('Service unavailable')
+ *   .build();
+ * ```
+ */
+declare class MockGadgetBuilder {
+    private config;
+    /**
+     * Set the gadget name.
+     */
+    withName(name: string): this;
+    /**
+     * Set the gadget description.
+     */
+    withDescription(description: string): this;
+    /**
+     * Set the parameter schema.
+     */
+    withSchema<T extends ZodType>(schema: T): MockGadgetBuilder;
+    /**
+     * Set a static result to return.
+     */
+    returns(result: string): this;
+    /**
+     * Set a dynamic result function.
+     */
+    returnsAsync(resultFn: (params: Record<string, unknown>) => string | Promise<string>): this;
+    /**
+     * Make the gadget throw an error on execution.
+     */
+    throws(error: Error | string): this;
+    /**
+     * Add execution delay.
+     */
+    withDelay(ms: number): this;
+    /**
+     * Set timeout for the gadget.
+     */
+    withTimeout(ms: number): this;
+    /**
+     * Enable call tracking (enabled by default).
+     */
+    trackCalls(): this;
+    /**
+     * Disable call tracking.
+     */
+    noTracking(): this;
+    /**
+     * Build the mock gadget.
+     */
+    build(): MockGadget;
+}
+/**
+ * Create a fluent builder for mock gadgets.
+ *
+ * @returns New MockGadgetBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const mock = mockGadget()
+ *   .withName('Search')
+ *   .withSchema(z.object({ query: z.string() }))
+ *   .returnsAsync(async ({ query }) => {
+ *     return `Results for: ${query}`;
+ *   })
+ *   .build();
+ * ```
+ */
+declare function mockGadget(): MockGadgetBuilder;
+
+export { type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type RecordedCall, type TestGadgetOptions, type TestGadgetResult, createMockGadget, mockGadget, testGadget, testGadgetBatch };

package/dist/testing/index.js

@@ -0,0 +1,34 @@
+import {
+  MockBuilder,
+  MockGadgetBuilder,
+  MockManager,
+  MockProviderAdapter,
+  createMockAdapter,
+  createMockClient,
+  createMockGadget,
+  createMockStream,
+  createTextMockStream,
+  getMockManager,
+  mockGadget,
+  mockLLM,
+  testGadget,
+  testGadgetBatch
+} from "../chunk-DCW33WV7.js";
+import "../chunk-TP7HE3MN.js";
+export {
+  MockBuilder,
+  MockGadgetBuilder,
+  MockManager,
+  MockProviderAdapter,
+  createMockAdapter,
+  createMockClient,
+  createMockGadget,
+  createMockStream,
+  createTextMockStream,
+  getMockManager,
+  mockGadget,
+  mockLLM,
+  testGadget,
+  testGadgetBatch
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "llmist",
+  "version": "0.1.1",
+  "description": "Universal TypeScript LLM client with streaming-first agent framework. Works with any model - no structured outputs or native tool calling required. Implements its own flexible grammar for function calling.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing/index.d.ts",
+        "default": "./dist/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/testing/index.d.cts",
+        "default": "./dist/testing/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "cli": "bun run scripts/cli-runner.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check --write .",
+    "test": "bun test",
+    "test:unit": "bun test src/agent src/core src/gadgets src/providers src/testing",
+    "test:watch": "bun test --watch",
+    "test:e2e": "bun test src/e2e --timeout 60000 --bail 1",
+    "test:e2e:watch": "bun test src/e2e --watch --timeout 60000",
+    "test:all": "bun run test && bun run test:e2e",
+    "clean": "rimraf dist",
+    "postinstall": "node scripts/install-hooks.js"
+  },
+  "bin": {
+    "llmist": "dist/cli.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zbigniewsobiecki/llmist.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "llm",
+    "ai",
+    "agent",
+    "agents",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "gpt",
+    "streaming",
+    "function-calling",
+    "tool-calling",
+    "typescript",
+    "universal-client",
+    "multi-provider",
+    "hooks",
+    "gadgets"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.69.0",
+    "@google/genai": "^1.27.0",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "openai": "^4.0.0",
+    "tiktoken": "^1.0.22",
+    "tslog": "^4.10.2",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.12.7",
+    "bun-types": "^1.3.2",
+    "dotenv": "^17.2.3",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.4.5"
+  }
+}