@memorilabs/axon 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# Memori Axon - TypeScript SDK
+
+TypeScript SDK for Memori's hosted memory service.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Format existing code
+npm run format
+
+# Run type check
+npm run typecheck
+
+# Build the project
+npm run build
+```
+
+---
+
+## 📜 Available Commands
+
+### Development
+
+| Command           | Description                   |
+| ----------------- | ----------------------------- |
+| `npm run build`   | Compile TypeScript to `dist/` |
+| `npm run example` | Build and run example script  |
+
+### Testing
+
+| Command              | Description             |
+| -------------------- | ----------------------- |
+| `npm test`           | Run tests once          |
+| `npm run test:watch` | Run tests in watch mode |
+
+### Code Quality
+
+| Command                | Description                              |
+| ---------------------- | ---------------------------------------- |
+| `npm run lint`         | Check for linting issues                 |
+| `npm run lint:fix`     | Auto-fix linting issues                  |
+| `npm run format`       | Format all files with Prettier           |
+| `npm run format:check` | Check formatting without modifying files |
+| `npm run typecheck`    | Run TypeScript type checking (no build)  |
+
+---
+
+## 🔧 Git Hooks
+
+Pre-commit and pre-push hooks are configured to maintain code quality automatically.
+
+### Pre-commit Hook
+
+Runs automatically on `git commit`:
+
+- ✅ ESLint (with auto-fix)
+- ✅ Prettier (formatting)
+- ✅ Only checks staged files
+
+### Pre-push Hook
+
+Runs automatically on `git push`:
+
+- ✅ TypeScript type checking
+
+### Bypass Hooks (Use Sparingly)
+
+```bash
+git commit --no-verify   # Skip pre-commit hook
+git push --no-verify     # Skip pre-push hook
+```
+
+---
+
+## 📦 Project Structure
+
+```
+ts-sdk/
+├── src/             # Source code
+├── tests/           # Test files
+├── examples/        # Example scripts
+├── dist/            # Compiled output (generated)
+└── ...config files
+```
+
+---
+
+## 🛠️ Development Workflow
+
+1. Make your changes
+2. Run `npm run lint:fix` to auto-fix issues
+3. Run `npm run typecheck` to verify types
+4. Commit your changes (hooks run automatically)
+5. Push to remote (type check runs automatically)

package/dist/core/axon.d.ts

@@ -0,0 +1,67 @@
+import { AxonConfig } from '../types/config.js';
+import { HookRegistry } from '../hooks/registry.js';
+import { LLMRegistry } from '../llm/registry.js';
+import { CallContext, LLMRequest, LLMResponse } from '../types/index.js';
+/**
+ * Configuration options for initializing Axon.
+ */
+export interface AxonOpts {
+    /** Runtime configuration overrides. */
+    config?: AxonConfig;
+}
+/**
+ * The central hub for the Axon SDK.
+ *
+ * This class orchestrates the lifecycle of LLM calls, managing:
+ * - Provider registration (e.g., wrapping OpenAI).
+ * - Hook execution (before/after calls).
+ * - Configuration state.
+ *
+ * @example
+ * ```ts
+ * import { Axon } from 'axon';
+ * import { OpenAI } from 'openai';
+ *
+ * const axon = new Axon({ config: { failFast: true } });
+ * const client = new OpenAI();
+ *
+ * // 1. Register the client
+ * axon.llm.register(client);
+ *
+ * // 2. Add hooks
+ * axon.before.register((req) => {
+ * console.log('Sending to:', req.model);
+ * return req;
+ * });
+ *
+ * // 3. Use client as normal
+ * await client.chat.completions.create({ ... });
+ * ```
+ */
+export declare class Axon {
+    /** The active configuration for this instance. */
+    readonly config: Required<AxonConfig>;
+    /** Registry for managing third-party LLM providers. */
+    readonly llm: LLMRegistry;
+    /** Registry for hooks that run *before* the LLM call. */
+    readonly before: HookRegistry<'before'>;
+    /** Registry for hooks that run *after* the LLM call. */
+    readonly after: HookRegistry<'after'>;
+    /**
+     * Creates a new Axon instance.
+     *
+     * @param opts - Initialization options, including configuration overrides.
+     */
+    constructor(opts?: AxonOpts);
+    /**
+     * Executes the 'before' hook pipeline.
+     * @internal
+     */
+    runBefore(request: LLMRequest, ctx: CallContext): Promise<LLMRequest>;
+    /**
+     * Executes the 'after' hook pipeline.
+     * @internal
+     */
+    runAfter(request: LLMRequest, response: LLMResponse, ctx: CallContext): Promise<LLMResponse>;
+}
+//# sourceMappingURL=axon.d.ts.map

package/dist/core/axon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axon.d.ts","sourceRoot":"","sources":["../../src/core/axon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,IAAI;IACf,kDAAkD;IAClD,SAAgB,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC7C,uDAAuD;IACvD,SAAgB,GAAG,EAAE,WAAW,CAAC;IACjC,yDAAyD;IACzD,SAAgB,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/C,wDAAwD;IACxD,SAAgB,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;OAIG;gBACS,IAAI,GAAE,QAAa;IAO/B;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAI3E;;;OAGG;IACG,QAAQ,CACZ,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC;CAGxB"}

package/dist/core/axon.js

@@ -0,0 +1,68 @@
+import { defaultAxonConfig } from './config.js';
+import { HookRegistry } from '../hooks/registry.js';
+import { LLMRegistry } from '../llm/registry.js';
+/**
+ * The central hub for the Axon SDK.
+ *
+ * This class orchestrates the lifecycle of LLM calls, managing:
+ * - Provider registration (e.g., wrapping OpenAI).
+ * - Hook execution (before/after calls).
+ * - Configuration state.
+ *
+ * @example
+ * ```ts
+ * import { Axon } from 'axon';
+ * import { OpenAI } from 'openai';
+ *
+ * const axon = new Axon({ config: { failFast: true } });
+ * const client = new OpenAI();
+ *
+ * // 1. Register the client
+ * axon.llm.register(client);
+ *
+ * // 2. Add hooks
+ * axon.before.register((req) => {
+ * console.log('Sending to:', req.model);
+ * return req;
+ * });
+ *
+ * // 3. Use client as normal
+ * await client.chat.completions.create({ ... });
+ * ```
+ */
+export class Axon {
+    /** The active configuration for this instance. */
+    config;
+    /** Registry for managing third-party LLM providers. */
+    llm;
+    /** Registry for hooks that run *before* the LLM call. */
+    before;
+    /** Registry for hooks that run *after* the LLM call. */
+    after;
+    /**
+     * Creates a new Axon instance.
+     *
+     * @param opts - Initialization options, including configuration overrides.
+     */
+    constructor(opts = {}) {
+        this.config = { ...defaultAxonConfig, ...(opts.config ?? {}) };
+        this.llm = new LLMRegistry(this);
+        this.before = new HookRegistry('before');
+        this.after = new HookRegistry('after');
+    }
+    /**
+     * Executes the 'before' hook pipeline.
+     * @internal
+     */
+    async runBefore(request, ctx) {
+        return (await this.before.execute(request, ctx));
+    }
+    /**
+     * Executes the 'after' hook pipeline.
+     * @internal
+     */
+    async runAfter(request, response, ctx) {
+        return (await this.after.execute(request, response, ctx));
+    }
+}
+//# sourceMappingURL=axon.js.map

package/dist/core/axon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axon.js","sourceRoot":"","sources":["../../src/core/axon.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,IAAI;IACf,kDAAkD;IAClC,MAAM,CAAuB;IAC7C,uDAAuD;IACvC,GAAG,CAAc;IACjC,yDAAyD;IACzC,MAAM,CAAyB;IAC/C,wDAAwD;IACxC,KAAK,CAAwB;IAE7C;;;;OAIG;IACH,YAAY,OAAiB,EAAE;QAC7B,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,iBAAiB,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,OAAmB,EAAE,GAAgB;QACnD,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAe,CAAC;IACjE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CACZ,OAAmB,EACnB,QAAqB,EACrB,GAAgB;QAEhB,OAAO,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAgB,CAAC;IAC3E,CAAC;CACF"}

package/dist/core/config.d.ts

@@ -0,0 +1,6 @@
+import { AxonConfig } from '../types/config.js';
+/**
+ * The default configuration values used when no overrides are provided.
+ */
+export declare const defaultAxonConfig: Required<AxonConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,UAAU,CAIlD,CAAC"}

package/dist/core/config.js

@@ -0,0 +1,9 @@
+/**
+ * The default configuration values used when no overrides are provided.
+ */
+export const defaultAxonConfig = {
+    failFast: true,
+    postCallBackground: false,
+    collectHookTimings: false,
+};
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAyB;IACrD,QAAQ,EAAE,IAAI;IACd,kBAAkB,EAAE,KAAK;IACzB,kBAAkB,EAAE,KAAK;CAC1B,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export { Axon } from './axon.js';
+export { defaultAxonConfig } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { Axon } from './axon.js';
+export { defaultAxonConfig } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/errors/axon-error.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Base class for all Axon-related errors.
+ */
+export declare class AxonError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=axon-error.d.ts.map

package/dist/errors/axon-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axon-error.d.ts","sourceRoot":"","sources":["../../src/errors/axon-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors/axon-error.js

@@ -0,0 +1,10 @@
+/**
+ * Base class for all Axon-related errors.
+ */
+export class AxonError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AxonError';
+    }
+}
+//# sourceMappingURL=axon-error.js.map

package/dist/errors/axon-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"axon-error.js","sourceRoot":"","sources":["../../src/errors/axon-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF"}

package/dist/errors/hook-error.d.ts

@@ -0,0 +1,13 @@
+import { AxonError } from './axon-error.js';
+/**
+ * Thrown when a 'before' or 'after' hook fails execution.
+ */
+export declare class AxonHookError extends AxonError {
+    readonly hook: 'before_call' | 'after_call';
+    readonly cause: unknown;
+    constructor(opts: {
+        hook: 'before_call' | 'after_call';
+        cause: unknown;
+    });
+}
+//# sourceMappingURL=hook-error.d.ts.map

package/dist/errors/hook-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-error.d.ts","sourceRoot":"","sources":["../../src/errors/hook-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;IACnD,SAAgB,KAAK,EAAE,OAAO,CAAC;gBAEnB,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;CAMzE"}

package/dist/errors/hook-error.js

@@ -0,0 +1,15 @@
+import { AxonError } from './axon-error.js';
+/**
+ * Thrown when a 'before' or 'after' hook fails execution.
+ */
+export class AxonHookError extends AxonError {
+    hook;
+    cause;
+    constructor(opts) {
+        super(`${opts.hook} hook failed: ${String(opts.cause)}`);
+        this.name = 'AxonHookError';
+        this.hook = opts.hook;
+        this.cause = opts.cause;
+    }
+}
+//# sourceMappingURL=hook-error.js.map

package/dist/errors/hook-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-error.js","sourceRoot":"","sources":["../../src/errors/hook-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,SAAS;IAC1B,IAAI,CAA+B;IACnC,KAAK,CAAU;IAE/B,YAAY,IAA4D;QACtE,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,iBAAiB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export { AxonError } from './axon-error.js';
+export { AxonHookError } from './hook-error.js';
+export { UnsupportedLLMProviderError } from './unsupported-provider-error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export { AxonError } from './axon-error.js';
+export { AxonHookError } from './hook-error.js';
+export { UnsupportedLLMProviderError } from './unsupported-provider-error.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/errors/unsupported-provider-error.d.ts

@@ -0,0 +1,9 @@
+import { AxonError } from './axon-error.js';
+/**
+ * Thrown when attempting to register a client that Axon does not recognize.
+ */
+export declare class UnsupportedLLMProviderError extends AxonError {
+    readonly provider: string;
+    constructor(provider: string);
+}
+//# sourceMappingURL=unsupported-provider-error.d.ts.map

package/dist/errors/unsupported-provider-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-provider-error.d.ts","sourceRoot":"","sources":["../../src/errors/unsupported-provider-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,QAAQ,EAAE,MAAM;CAK7B"}

package/dist/errors/unsupported-provider-error.js

@@ -0,0 +1,13 @@
+import { AxonError } from './axon-error.js';
+/**
+ * Thrown when attempting to register a client that Axon does not recognize.
+ */
+export class UnsupportedLLMProviderError extends AxonError {
+    provider;
+    constructor(provider) {
+        super(`Unsupported LLM provider: ${provider}`);
+        this.name = 'UnsupportedLLMProviderError';
+        this.provider = provider;
+    }
+}
+//# sourceMappingURL=unsupported-provider-error.js.map

package/dist/errors/unsupported-provider-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsupported-provider-error.js","sourceRoot":"","sources":["../../src/errors/unsupported-provider-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,SAAS;IACxC,QAAQ,CAAS;IAEjC,YAAY,QAAgB;QAC1B,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/hooks/hooked.d.ts

@@ -0,0 +1,48 @@
+import { Axon } from '../core/axon.js';
+import { CallContext, LLMRequest, LLMResponse } from '../types/index.js';
+export type ArgsToRequest<TInput> = (args: TInput) => LLMRequest;
+export type RequestToArgs<TInput> = (request: LLMRequest) => TInput;
+export type RawToResponse<TOutput> = (raw: TOutput) => LLMResponse;
+export type ApplyCanonicalToRaw<TOutput> = (raw: TOutput, canonical: LLMResponse) => void;
+/**
+ * Intercepts an async iterable stream to buffer content for 'after' hooks.
+ * @internal
+ */
+export declare class HookedStream<TChunk> implements AsyncIterable<TChunk> {
+    private readonly stream;
+    private readonly request;
+    private readonly ctx;
+    private readonly axon;
+    private readonly chunkToText;
+    private readonly getFinalResponse;
+    private accumulatedContent;
+    private hasFinished;
+    constructor(stream: AsyncIterable<TChunk>, request: LLMRequest, ctx: CallContext, axon: Axon, chunkToText: (chunk: unknown) => string | undefined, getFinalResponse: () => unknown);
+    [Symbol.asyncIterator](): AsyncIterator<TChunk>;
+    private finalize;
+}
+/**
+ * A proxy handler that injects Axon logic into a provider's `create` method.
+ * @internal
+ */
+export declare class HookedCreateProxy<TInput, TOutput> {
+    private opts;
+    constructor(opts: {
+        create: (input: TInput) => Promise<TOutput>;
+        axon: Axon;
+        ctxMetadata: Record<string, unknown>;
+        argsToRequest: ArgsToRequest<TInput>;
+        requestToArgs: RequestToArgs<TInput>;
+        rawToResponse: RawToResponse<TOutput>;
+        applyCanonicalToRaw?: ApplyCanonicalToRaw<TOutput>;
+        chunkToText?: (chunk: unknown) => string | undefined;
+    });
+    executeCreate(input: TInput): Promise<TOutput>;
+}
+/**
+ * @internal
+ */
+export declare class CreateFacade {
+    static wrap<TInput, TOutput>(originalFn: (input: TInput) => Promise<TOutput>, proxy: HookedCreateProxy<TInput, TOutput>): (input: TInput) => Promise<TOutput>;
+}
+//# sourceMappingURL=hooked.d.ts.map

package/dist/hooks/hooked.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooked.d.ts","sourceRoot":"","sources":["../../src/hooks/hooked.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAqB,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE5F,MAAM,MAAM,aAAa,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,CAAC;AACjE,MAAM,MAAM,aAAa,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,CAAC;AACpE,MAAM,MAAM,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,WAAW,CAAC;AACnE,MAAM,MAAM,mBAAmB,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,KAAK,IAAI,CAAC;AAW1F;;;GAGG;AACH,qBAAa,YAAY,CAAC,MAAM,CAAE,YAAW,aAAa,CAAC,MAAM,CAAC;IAK9D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IATnC,OAAO,CAAC,kBAAkB,CAAgB;IAC1C,OAAO,CAAC,WAAW,CAAS;gBAGT,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,EACnD,gBAAgB,EAAE,MAAM,OAAO;IAG3C,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC;YAiBxC,QAAQ;CAOvB;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,MAAM,EAAE,OAAO;IAE1C,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE;QACZ,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,EAAE,IAAI,CAAC;QACX,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACrC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QACrC,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;QACtC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACnD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACtD;IAGG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAmCrD;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EACzB,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC/C,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC;CAIvC"}

package/dist/hooks/hooked.js

@@ -0,0 +1,95 @@
+import { createCallContext } from '../types/index.js';
+function isStreamArgs(args) {
+    return (typeof args === 'object' &&
+        args !== null &&
+        'stream' in args &&
+        args.stream);
+}
+/**
+ * Intercepts an async iterable stream to buffer content for 'after' hooks.
+ * @internal
+ */
+export class HookedStream {
+    stream;
+    request;
+    ctx;
+    axon;
+    chunkToText;
+    getFinalResponse;
+    accumulatedContent = [];
+    hasFinished = false;
+    constructor(stream, request, ctx, axon, chunkToText, getFinalResponse) {
+        this.stream = stream;
+        this.request = request;
+        this.ctx = ctx;
+        this.axon = axon;
+        this.chunkToText = chunkToText;
+        this.getFinalResponse = getFinalResponse;
+    }
+    async *[Symbol.asyncIterator]() {
+        try {
+            for await (const value of this.stream) {
+                const text = this.chunkToText(value);
+                if (text) {
+                    this.accumulatedContent.push(text);
+                }
+                yield value;
+            }
+        }
+        finally {
+            if (!this.hasFinished) {
+                this.hasFinished = true;
+                await this.finalize();
+            }
+        }
+    }
+    async finalize() {
+        const canonical = {
+            content: this.accumulatedContent.join(''),
+            raw: this.getFinalResponse(),
+        };
+        await this.axon.runAfter(this.request, canonical, this.ctx);
+    }
+}
+/**
+ * A proxy handler that injects Axon logic into a provider's `create` method.
+ * @internal
+ */
+export class HookedCreateProxy {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async executeCreate(input) {
+        const ctx = createCallContext({ metadata: { ...this.opts.ctxMetadata } });
+        // 1. Run Before Hooks
+        let request = this.opts.argsToRequest(input);
+        request = await this.opts.axon.runBefore(request, ctx);
+        // 2. Execute Original Method
+        const rawArgs = this.opts.requestToArgs(request);
+        const isStream = isStreamArgs(rawArgs);
+        const raw = await this.opts.create(rawArgs);
+        // 3. Handle Streams (Hooks run on completion)
+        if (isStream && this.opts.chunkToText) {
+            return new HookedStream(raw, request, ctx, this.opts.axon, this.opts.chunkToText, () => raw);
+        }
+        // 4. Handle Standard Response (Run After Hooks immediately)
+        let canonical = this.opts.rawToResponse(raw);
+        canonical = await this.opts.axon.runAfter(request, canonical, ctx);
+        // 5. Apply mutations back to the raw object
+        if (this.opts.applyCanonicalToRaw) {
+            this.opts.applyCanonicalToRaw(raw, canonical);
+        }
+        return raw;
+    }
+}
+/**
+ * @internal
+ */
+export class CreateFacade {
+    static wrap(originalFn, proxy) {
+        const wrapped = (input) => proxy.executeCreate(input);
+        return Object.assign(wrapped, originalFn);
+    }
+}
+//# sourceMappingURL=hooked.js.map

package/dist/hooks/hooked.js.map

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

package/dist/hooks/registry.d.ts

@@ -0,0 +1,28 @@
+import { CallContext, LLMRequest, LLMResponse } from '../types/index.js';
+type BeforeHook = (req: LLMRequest, ctx: CallContext) => LLMRequest | Promise<LLMRequest> | undefined | Promise<undefined>;
+type AfterHook = (req: LLMRequest, res: LLMResponse, ctx: CallContext) => LLMResponse | Promise<LLMResponse> | undefined | Promise<undefined>;
+type HookType<P> = P extends 'before' ? BeforeHook : AfterHook;
+/**
+ * Manages a list of lifecycle hooks for a specific phase.
+ *
+ * @template P - The lifecycle phase this registry manages ('before' or 'after').
+ */
+export declare class HookRegistry<P extends 'before' | 'after'> {
+    private readonly phase;
+    private hooks;
+    constructor(phase: P);
+    /**
+     * Registers a new hook function.
+     * Hooks are executed sequentially in the order they are registered.
+     *
+     * @param fn - The hook function to execute.
+     */
+    register(fn: HookType<P>): void;
+    /**
+     * Executes all registered hooks in sequence.
+     * @internal
+     */
+    execute(...args: unknown[]): Promise<unknown>;
+}
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/hooks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEzE,KAAK,UAAU,GAAG,CAChB,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,WAAW,KACb,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEvE,KAAK,SAAS,GAAG,CACf,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,WAAW,KACb,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AAEzE,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/D;;;;GAIG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,QAAQ,GAAG,OAAO;IAGxC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,KAAK,CAA0B;gBAEV,KAAK,EAAE,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAI/B;;;OAGG;IACG,OAAO,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAyBpD"}

package/dist/hooks/registry.js

@@ -0,0 +1,50 @@
+/**
+ * Manages a list of lifecycle hooks for a specific phase.
+ *
+ * @template P - The lifecycle phase this registry manages ('before' or 'after').
+ */
+export class HookRegistry {
+    phase;
+    hooks = [];
+    constructor(phase) {
+        this.phase = phase;
+    }
+    /**
+     * Registers a new hook function.
+     * Hooks are executed sequentially in the order they are registered.
+     *
+     * @param fn - The hook function to execute.
+     */
+    register(fn) {
+        this.hooks.push(fn);
+    }
+    /**
+     * Executes all registered hooks in sequence.
+     * @internal
+     */
+    async execute(...args) {
+        if (this.phase === 'before') {
+            let currentReq = args[0];
+            const ctx = args[1];
+            for (const hook of this.hooks) {
+                const result = await hook(currentReq, ctx);
+                if (result)
+                    currentReq = result;
+            }
+            return currentReq;
+        }
+        if (this.phase === 'after') {
+            const req = args[0];
+            let currentRes = args[1];
+            const ctx = args[2];
+            for (const hook of this.hooks) {
+                const result = await hook(req, currentRes, ctx);
+                if (result)
+                    currentRes = result;
+            }
+            return currentRes;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/hooks/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,OAAO,YAAY;IAGM;IAFrB,KAAK,GAAuB,EAAE,CAAC;IAEvC,YAA6B,KAAQ;QAAR,UAAK,GAAL,KAAK,CAAG;IAAG,CAAC;IAEzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAe;QACtB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,GAAG,IAAe;QAC9B,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,UAAU,GAAG,IAAI,CAAC,CAAC,CAAe,CAAC;YACvC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAgB,CAAC;YAEnC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAqB,EAAE,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;gBAC3C,IAAI,MAAM;oBAAE,UAAU,GAAG,MAAM,CAAC;YAClC,CAAC;YACD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAe,CAAC;YAClC,IAAI,UAAU,GAAG,IAAI,CAAC,CAAC,CAAgB,CAAC;YACxC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAgB,CAAC;YAEnC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAoB,EAAE,CAAC;gBAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;gBAChD,IAAI,MAAM;oBAAE,UAAU,GAAG,MAAM,CAAC;YAClC,CAAC;YACD,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}