@harny/vercel-ai-provider 0.0.0-stage → 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/** The memory API answered with an error, or the call never reached it. */
+export declare class HarnyAPIError extends Error {
+    /** The API's error code, for example `content-required`, or `network-error` / `rate-limited` / `timeout` from this package. */
+    readonly code: string;
+    /** HTTP status, or 0 when no answer came back. */
+    readonly status: number;
+    /** The API's plain-words explanation. */
+    readonly debugMessage: string;
+    /** Extra data the API attached (for example the ids a delete could not find). */
+    readonly data: unknown;
+    /** Seconds to wait before retrying, when the API said so (a per-minute limit). */
+    readonly retryAfter: number | undefined;
+    /** The `X-Request-Id` of the call, to quote when you ask for help. */
+    readonly requestId: string | undefined;
+    constructor(init: {
+        code: string;
+        status: number;
+        debugMessage: string;
+        data?: unknown;
+        retryAfter?: number;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+/** The package was set up in a way that cannot work (no key, no user, a plain-http address). Nothing was sent. */
+export declare class HarnyConfigError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,32 @@
+/** The memory API answered with an error, or the call never reached it. */
+export class HarnyAPIError extends Error {
+    /** The API's error code, for example `content-required`, or `network-error` / `rate-limited` / `timeout` from this package. */
+    code;
+    /** HTTP status, or 0 when no answer came back. */
+    status;
+    /** The API's plain-words explanation. */
+    debugMessage;
+    /** Extra data the API attached (for example the ids a delete could not find). */
+    data;
+    /** Seconds to wait before retrying, when the API said so (a per-minute limit). */
+    retryAfter;
+    /** The `X-Request-Id` of the call, to quote when you ask for help. */
+    requestId;
+    constructor(init) {
+        super(`Harny ${init.status || 'network'} ${init.code}: ${init.debugMessage}`, { cause: init.cause });
+        this.name = 'HarnyAPIError';
+        this.code = init.code;
+        this.status = init.status;
+        this.debugMessage = init.debugMessage;
+        this.data = init.data;
+        this.retryAfter = init.retryAfter;
+        this.requestId = init.requestId;
+    }
+}
+/** The package was set up in a way that cannot work (no key, no user, a plain-http address). Nothing was sent. */
+export class HarnyConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HarnyConfigError';
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+import type { RecallResult } from './types.js';
+export declare const DEFAULT_HEADING = "What you remember about this person from earlier conversations, most relevant first. Use it when it helps; do not mention it unless asked:";
+/** The recalled evidence as a short block for a system prompt. Empty string when there is none. */
+export declare function formatMemories(results: readonly RecallResult[], heading?: string): string;

package/dist/format.js

@@ -0,0 +1,11 @@
+export const DEFAULT_HEADING = 'What you remember about this person from earlier conversations, most relevant first. Use it when it helps; do not mention it unless asked:';
+/** The recalled evidence as a short block for a system prompt. Empty string when there is none. */
+export function formatMemories(results, heading = DEFAULT_HEADING) {
+    const lines = results
+        .filter((result) => result.content && result.content.trim())
+        .map((result) => {
+        const when = result.occurredAt ? ` (${result.occurredAt.slice(0, 10)})` : '';
+        return `- ${result.content.trim()}${when}`;
+    });
+    return lines.length ? `${heading}\n${lines.join('\n')}` : '';
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createHarny, harny, type HarnyProvider } from './provider.js';
+export { createMemoryMiddleware, type MemorySettings } from './middleware.js';
+export { createTools, type ToolSettings } from './tools.js';
+export { addMemories, getMemories, retrieveMemories, type MemoryCallOptions } from './standalone.js';
+export { HarnyClient, resolveBaseURL } from './client.js';
+export { HarnyAPIError, HarnyConfigError } from './errors.js';
+export { formatMemories, DEFAULT_HEADING } from './format.js';
+export { VERSION } from './version.js';
+export type { PromptMessage } from './messages.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createHarny, harny } from './provider.js';
+export { createMemoryMiddleware } from './middleware.js';
+export { createTools } from './tools.js';
+export { addMemories, getMemories, retrieveMemories } from './standalone.js';
+export { HarnyClient, resolveBaseURL } from './client.js';
+export { HarnyAPIError, HarnyConfigError } from './errors.js';
+export { formatMemories, DEFAULT_HEADING } from './format.js';
+export { VERSION } from './version.js';

package/dist/messages.d.ts

@@ -0,0 +1,19 @@
+/** A prompt message in the AI SDK's shape (`LanguageModelV4Prompt` entries and `ModelMessage` both fit). */
+export interface PromptMessage {
+    role: string;
+    content: unknown;
+}
+/** The text of one message: its text parts joined by a newline. Files, tool calls and reasoning are left out. */
+export declare function textOf(message: PromptMessage): string;
+/** The text of the last user message, which is what the person just asked. */
+export declare function lastUserQuery(prompt: readonly PromptMessage[]): string | undefined;
+/**
+ * The user turns that are new in this call: the user messages after the last assistant or tool message.
+ * Assistant text is never returned (user turns only).
+ */
+export declare function newUserTurns(prompt: readonly PromptMessage[]): string[];
+export declare function sha256Hex(text: string): Promise<string>;
+/** The id of a stored user turn: a hash of the conversation key and the text, so a repeat replaces itself. */
+export declare function turnId(conversationKey: string, text: string): Promise<string>;
+/** The conversation key when none is set: a hash of the first user message, which stays fixed as the chat grows. */
+export declare function defaultConversationKey(prompt: readonly PromptMessage[]): Promise<string>;

package/dist/messages.js

@@ -0,0 +1,57 @@
+/** The text of one message: its text parts joined by a newline. Files, tool calls and reasoning are left out. */
+export function textOf(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((part) => !!part && part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text)
+        .join('\n')
+        .trim();
+}
+/** The text of the last user message, which is what the person just asked. */
+export function lastUserQuery(prompt) {
+    for (let i = prompt.length - 1; i >= 0; i--) {
+        const message = prompt[i];
+        if (message?.role === 'user') {
+            const text = textOf(message);
+            if (text)
+                return text;
+        }
+    }
+    return undefined;
+}
+/**
+ * The user turns that are new in this call: the user messages after the last assistant or tool message.
+ * Assistant text is never returned (user turns only).
+ */
+export function newUserTurns(prompt) {
+    let start = 0;
+    for (let i = prompt.length - 1; i >= 0; i--) {
+        const role = prompt[i]?.role;
+        if (role === 'assistant' || role === 'tool') {
+            start = i + 1;
+            break;
+        }
+    }
+    return prompt
+        .slice(start)
+        .filter((message) => message.role === 'user')
+        .map(textOf)
+        .filter((text) => text.length > 0);
+}
+export async function sha256Hex(text) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** The id of a stored user turn: a hash of the conversation key and the text, so a repeat replaces itself. */
+export async function turnId(conversationKey, text) {
+    return `turn-${await sha256Hex(`${conversationKey}\n${text}`)}`;
+}
+/** The conversation key when none is set: a hash of the first user message, which stays fixed as the chat grows. */
+export async function defaultConversationKey(prompt) {
+    const first = prompt.find((message) => message.role === 'user');
+    return sha256Hex(first ? textOf(first) : '');
+}

package/dist/middleware.d.ts

@@ -0,0 +1,41 @@
+import type { LanguageModelMiddleware } from 'ai';
+import type { HarnyClient } from './client.js';
+import { type PromptMessage } from './messages.js';
+import type { RecallLevel, RecallPending, RecallResult } from './types.js';
+export interface MemorySettings {
+    /** The end user. Defaults to the `user` given to createHarny. */
+    user?: string;
+    /** Recall before each turn. Default true. */
+    recall?: boolean;
+    /** Evidence size for recall. Default 'low'. Not with `maxTokens`. */
+    level?: RecallLevel;
+    /** Evidence budget in tokens. Not with `level`. */
+    maxTokens?: number;
+    /** Most memories to inject. Default 20. */
+    limit?: number;
+    /** Store the person's messages after a successful call. User turns only: assistant text is never stored. Default false: saving conversation messages is opt-in (`saveUserMessages: true`). */
+    saveUserMessages?: boolean;
+    /** Names the conversation for the ids of stored messages. Default: a hash of the first user message. */
+    conversationId?: string | ((prompt: readonly PromptMessage[]) => string | Promise<string>);
+    /** The line above the injected memories. */
+    heading?: string;
+    /** Replace the whole injected block. Return '' to inject nothing. */
+    formatMemories?: (results: readonly RecallResult[]) => string;
+    /** Extra metadata on every stored message. */
+    metadata?: Record<string, unknown>;
+    /** Memory trouble never fails the model call; it comes here. */
+    onError?: (error: unknown, context: {
+        stage: 'recall' | 'ingest';
+    }) => void;
+    /** Called when recall reports sends still being processed, so the answer may miss the newest facts. */
+    onPending?: (pending: RecallPending) => void;
+    /**
+     * Hand the store to the host so the response is not held back (for example Vercel's waitUntil).
+     * Without it the call waits for the store to finish.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** How long a recall answer is reused for the same person and question (tool loops ask again). Default 30000 ms. */
+    cacheTtlMs?: number;
+}
+/** The memory middleware: recall into the system prompt before the call, store the person's message after it. */
+export declare function createMemoryMiddleware(client: HarnyClient, settings?: MemorySettings): LanguageModelMiddleware;

package/dist/middleware.js

@@ -0,0 +1,136 @@
+import { DEFAULT_HEADING, formatMemories } from './format.js';
+import { defaultConversationKey, lastUserQuery, newUserTurns, turnId } from './messages.js';
+const DEFAULT_LIMIT = 20;
+/** The memory middleware: recall into the system prompt before the call, store the person's message after it. */
+export function createMemoryMiddleware(client, settings = {}) {
+    const cache = new Map();
+    const stored = new Set();
+    const ttl = settings.cacheTtlMs ?? 30_000;
+    const report = (error, stage) => {
+        try {
+            settings.onError?.(error, { stage });
+        }
+        catch {
+            // A failing error handler must not fail the call either.
+        }
+    };
+    async function recallBlock(prompt) {
+        if (settings.recall === false)
+            return '';
+        const query = lastUserQuery(prompt);
+        if (!query)
+            return '';
+        const user = client.actingUser(settings.user);
+        if (!user)
+            throw new Error("Name the end user: pass user to createHarny or to the call's settings.");
+        const cacheKey = `${user}\n${query}`;
+        const hit = cache.get(cacheKey);
+        if (hit && hit.expires > Date.now())
+            return hit.block;
+        const answer = await client.recall({
+            query,
+            user,
+            limit: settings.limit ?? DEFAULT_LIMIT,
+            ...(settings.maxTokens !== undefined ? { maxTokens: settings.maxTokens } : { level: settings.level ?? 'low' }),
+        });
+        if (answer.pending) {
+            try {
+                settings.onPending?.(answer.pending);
+            }
+            catch {
+                // see report()
+            }
+        }
+        const block = settings.formatMemories
+            ? settings.formatMemories(answer.results)
+            : formatMemories(answer.results, settings.heading ?? DEFAULT_HEADING);
+        cache.set(cacheKey, { block, expires: Date.now() + ttl });
+        return block;
+    }
+    async function saveTurns(prompt) {
+        if (settings.saveUserMessages !== true)
+            return;
+        const turns = newUserTurns(prompt);
+        if (!turns.length)
+            return;
+        const user = client.actingUser(settings.user);
+        if (!user)
+            throw new Error("Name the end user: pass user to createHarny or to the call's settings.");
+        const conversation = typeof settings.conversationId === 'function'
+            ? await settings.conversationId(prompt)
+            : (settings.conversationId ?? (await defaultConversationKey(prompt)));
+        for (const text of turns) {
+            const id = await turnId(conversation, text);
+            const memoKey = `${user}\n${id}`;
+            if (stored.has(memoKey))
+                continue;
+            await client.ingest({
+                content: text,
+                id,
+                label: 'User message',
+                timestamp: new Date(),
+                user,
+                ...(settings.metadata ? { metadata: settings.metadata } : {}),
+            });
+            stored.add(memoKey);
+        }
+    }
+    function store(prompt) {
+        const work = saveTurns(prompt).catch((error) => report(error, 'ingest'));
+        if (settings.waitUntil) {
+            try {
+                settings.waitUntil(work);
+            }
+            catch (error) {
+                report(error, 'ingest');
+            }
+            return undefined;
+        }
+        return work;
+    }
+    return {
+        transformParams: async ({ params }) => {
+            const prompt = params.prompt;
+            let block = '';
+            try {
+                block = await recallBlock(prompt);
+            }
+            catch (error) {
+                report(error, 'recall');
+            }
+            if (!block)
+                return params;
+            const messages = [...params.prompt];
+            const first = messages[0];
+            if (first && first.role === 'system') {
+                messages[0] = { ...first, content: `${first.content}\n\n${block}` };
+            }
+            else {
+                messages.unshift({ role: 'system', content: block });
+            }
+            return { ...params, prompt: messages };
+        },
+        wrapGenerate: async ({ doGenerate, params }) => {
+            const result = await doGenerate();
+            await store(params.prompt);
+            return result;
+        },
+        wrapStream: async ({ doStream, params }) => {
+            const result = await doStream();
+            let failed = false;
+            const prompt = params.prompt;
+            const stream = result.stream.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    if (chunk.type === 'error')
+                        failed = true;
+                    controller.enqueue(chunk);
+                },
+                async flush() {
+                    if (!failed)
+                        await store(prompt);
+                },
+            }));
+            return { ...result, stream };
+        },
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,32 @@
+import { wrapLanguageModel, type LanguageModel } from 'ai';
+import { HarnyClient } from './client.js';
+import { createMemoryMiddleware, type MemorySettings } from './middleware.js';
+import { createTools, type ToolSettings } from './tools.js';
+import type { HarnyClientOptions } from './types.js';
+export interface HarnyProvider {
+    /** Wrap a model so it remembers the person. Accepts a model object, or a gateway model id such as 'openai/gpt-5'. */
+    <M extends LanguageModel>(model: M, settings?: MemorySettings): ReturnType<typeof wrapLanguageModel>;
+    /** The same as calling the provider. */
+    languageModel(model: LanguageModel, settings?: MemorySettings): ReturnType<typeof wrapLanguageModel>;
+    /** The memory middleware alone, for `wrapLanguageModel({ model, middleware })`. */
+    middleware(settings?: MemorySettings): ReturnType<typeof createMemoryMiddleware>;
+    /** `{ harny_remember, harny_recall }` for a tool set. */
+    tools(settings?: ToolSettings): ReturnType<typeof createTools>;
+    /** The memory API client behind it. */
+    client: HarnyClient;
+    ingest: HarnyClient['ingest'];
+    ingestBatch: HarnyClient['ingestBatch'];
+    getIngestion: HarnyClient['getIngestion'];
+    waitForIngestion: HarnyClient['waitForIngestion'];
+    deleteIngestion: HarnyClient['deleteIngestion'];
+    deleteDataPoints: HarnyClient['deleteDataPoints'];
+    recall: HarnyClient['recall'];
+    usage: HarnyClient['usage'];
+}
+/**
+ * Create the provider. Nothing is read or sent until the first call, so it is safe to create at import time.
+ * `apiKey` defaults to HARNY_API_KEY, `baseURL` to HARNY_API_URL, else https://api.harny.ai.
+ */
+export declare function createHarny(options?: HarnyClientOptions): HarnyProvider;
+/** A ready provider that reads HARNY_API_KEY and HARNY_API_URL. Name the person per call: harny(model, { user }). */
+export declare const harny: HarnyProvider;

package/dist/provider.js

@@ -0,0 +1,34 @@
+import { gateway, wrapLanguageModel } from 'ai';
+import { HarnyClient } from './client.js';
+import { createMemoryMiddleware } from './middleware.js';
+import { createTools } from './tools.js';
+/**
+ * Create the provider. Nothing is read or sent until the first call, so it is safe to create at import time.
+ * `apiKey` defaults to HARNY_API_KEY, `baseURL` to HARNY_API_URL, else https://api.harny.ai.
+ */
+export function createHarny(options = {}) {
+    const client = new HarnyClient(options);
+    const wrap = (model, settings = {}) => {
+        const resolved = typeof model === 'string' ? gateway(model) : model;
+        return wrapLanguageModel({
+            model: resolved,
+            middleware: createMemoryMiddleware(client, settings),
+        });
+    };
+    const provider = ((model, settings) => wrap(model, settings));
+    provider.languageModel = wrap;
+    provider.middleware = (settings) => createMemoryMiddleware(client, settings);
+    provider.tools = (settings) => createTools(client, { user: options.user, ...settings });
+    provider.client = client;
+    provider.ingest = client.ingest.bind(client);
+    provider.ingestBatch = client.ingestBatch.bind(client);
+    provider.getIngestion = client.getIngestion.bind(client);
+    provider.waitForIngestion = client.waitForIngestion.bind(client);
+    provider.deleteIngestion = client.deleteIngestion.bind(client);
+    provider.deleteDataPoints = client.deleteDataPoints.bind(client);
+    provider.recall = client.recall.bind(client);
+    provider.usage = client.usage.bind(client);
+    return provider;
+}
+/** A ready provider that reads HARNY_API_KEY and HARNY_API_URL. Name the person per call: harny(model, { user }). */
+export const harny = createHarny();

package/dist/standalone.d.ts

@@ -0,0 +1,22 @@
+import { type PromptMessage } from './messages.js';
+import type { HarnyClientOptions, IngestReceipt, RecallLevel, RecallResult } from './types.js';
+export interface MemoryCallOptions extends HarnyClientOptions {
+    level?: RecallLevel;
+    maxTokens?: number;
+    limit?: number;
+    /** For `addMemories`: names the conversation for the ids. Default 'default'. */
+    conversationId?: string;
+    /** For `addMemories`: extra metadata on every stored message. */
+    metadata?: Record<string, unknown>;
+    /** For `retrieveMemories`: the line above the memories. */
+    heading?: string;
+}
+/**
+ * Store the user messages of a prompt-shaped array. Assistant and system messages are skipped: only what the
+ * person said is kept. Returns one receipt per stored message.
+ */
+export declare function addMemories(messages: readonly PromptMessage[], options?: MemoryCallOptions): Promise<IngestReceipt[]>;
+/** The raw recalled results for the last user message of a prompt (or for a plain string). */
+export declare function getMemories(prompt: string | readonly PromptMessage[], options?: MemoryCallOptions): Promise<RecallResult[]>;
+/** A system-prompt block with the recalled memories, or '' when there are none. */
+export declare function retrieveMemories(prompt: string | readonly PromptMessage[], options?: MemoryCallOptions): Promise<string>;

package/dist/standalone.js

@@ -0,0 +1,47 @@
+import { HarnyClient } from './client.js';
+import { DEFAULT_HEADING, formatMemories } from './format.js';
+import { lastUserQuery, textOf, turnId } from './messages.js';
+function asPrompt(prompt) {
+    return typeof prompt === 'string' ? [{ role: 'user', content: prompt }] : [...prompt];
+}
+/**
+ * Store the user messages of a prompt-shaped array. Assistant and system messages are skipped: only what the
+ * person said is kept. Returns one receipt per stored message.
+ */
+export async function addMemories(messages, options = {}) {
+    const client = new HarnyClient(options);
+    const conversation = options.conversationId ?? 'default';
+    const receipts = [];
+    for (const message of messages) {
+        if (message.role !== 'user')
+            continue;
+        const text = textOf(message);
+        if (!text)
+            continue;
+        receipts.push(await client.ingest({
+            content: text,
+            id: await turnId(conversation, text),
+            label: 'User message',
+            timestamp: new Date(),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+        }));
+    }
+    return receipts;
+}
+/** The raw recalled results for the last user message of a prompt (or for a plain string). */
+export async function getMemories(prompt, options = {}) {
+    const query = lastUserQuery(asPrompt(prompt));
+    if (!query)
+        return [];
+    const client = new HarnyClient(options);
+    const answer = await client.recall({
+        query,
+        limit: options.limit ?? 20,
+        ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : { level: options.level ?? 'low' }),
+    });
+    return answer.results;
+}
+/** A system-prompt block with the recalled memories, or '' when there are none. */
+export async function retrieveMemories(prompt, options = {}) {
+    return formatMemories(await getMemories(prompt, options), options.heading ?? DEFAULT_HEADING);
+}