@harperfast/harper 5.2.0-beta.4 → 5.2.1

package/dist/resources/models/v1/errors.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * OpenAI error envelope helpers for the `/v1/*` gateway (#631).
+ *
+ * Harper's REST layer serialises uncaught errors as RFC 9457 Problem Details.
+ * Resources that need the OpenAI `{ error: { message, type, code, param } }`
+ * shape must catch errors themselves and call `toOpenAIError()` / `badRequest()`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOpenAIError = toOpenAIError;
+exports.badRequest = badRequest;
+exports.authorizeV1Request = authorizeV1Request;
+const backendRegistry_ts_1 = require("../backendRegistry.js");
+const Models_ts_1 = require("../Models.js");
+const harper_logger_ts_1 = __importDefault(require("../../../utility/logging/harper_logger.js"));
+/**
+ * Map any thrown value to an OpenAI error envelope. Uses `statusCode` when
+ * present (Harper's `ClientError` / `ServerError` convention). Falls back to
+ * `500 server_error`. `ModelBackendNotFoundError` maps to `404 model_not_found`.
+ */
+function toOpenAIError(err) {
+    let status = 500;
+    let type = 'server_error';
+    let code = null;
+    if (err instanceof backendRegistry_ts_1.ModelBackendNotFoundError) {
+        status = 404;
+        type = 'invalid_request_error';
+        code = 'model_not_found';
+    }
+    else if (err instanceof Models_ts_1.ModelCapabilityError) {
+        // Caller-driven mismatch (e.g. `tools` or streaming against a backend that
+        // doesn't support it): the request is what's wrong, not the server. It extends
+        // ServerError (statusCode 500), so this must precede the statusCode branch —
+        // falling through would report a generic sanitized 500 for a client-actionable
+        // condition. The message is safe to pass through: it names only the backend and
+        // the capability the caller asked for.
+        status = 400;
+        type = 'invalid_request_error';
+        code = 'capability_unsupported';
+    }
+    else if (err instanceof Error && typeof err.statusCode === 'number') {
+        status = err.statusCode;
+        if (status === 401) {
+            type = 'authentication_error';
+        }
+        else if (status === 403) {
+            // OpenAI semantics: 401 = bad/missing credentials, 403 = valid credentials
+            // lacking permission (matches authorizeV1Request's own 403 envelope).
+            type = 'permission_error';
+        }
+        else if (status < 500) {
+            type = 'invalid_request_error';
+        }
+        else {
+            type = 'server_error';
+        }
+    }
+    // 5xx messages stay generic: internal error strings (backend stack details, file
+    // paths) don't belong in a wire response. The real error goes to the log. 4xx
+    // messages are client-actionable and pass through.
+    let message;
+    if (status >= 500) {
+        harper_logger_ts_1.default.error('v1 gateway error', err);
+        message = 'Internal server error';
+    }
+    else {
+        message = err instanceof Error ? err.message : 'Bad request';
+    }
+    return {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+        data: { error: { message, type, code, param: null } },
+    };
+}
+/** Convenience for early request-body validation failures. */
+function badRequest(message) {
+    return {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+        data: { error: { message, type: 'invalid_request_error', code: null, param: null } },
+    };
+}
+/**
+ * Gate for the `/v1/*` handlers, since overriding the static `get`/`post` methods
+ * bypasses Resource's `transactional()` wrapper and its default `allowRead`/`allowCreate`
+ * checks (Resource.ts:685-733, 426-435) never run for these endpoints.
+ *
+ * Mirrors Resource's default gate (super_user-only) rather than introducing a new
+ * permission — see PR discussion for whether a dedicated `/v1/*` permission should
+ * replace this later.
+ *
+ * Returns an OpenAI-shape error response when access should be denied, or `null`
+ * when the request may proceed.
+ */
+function authorizeV1Request(request) {
+    const user = request?.user;
+    if (!user) {
+        return {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+            data: {
+                error: {
+                    message: 'You must provide valid credentials to access this endpoint.',
+                    type: 'authentication_error',
+                    code: null,
+                    param: null,
+                },
+            },
+        };
+    }
+    if (!user.role?.permission?.super_user) {
+        return {
+            status: 403,
+            headers: { 'Content-Type': 'application/json' },
+            data: {
+                error: {
+                    message: 'You do not have permission to access this endpoint.',
+                    type: 'permission_error',
+                    code: null,
+                    param: null,
+                },
+            },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=errors.js.map

package/dist/resources/models/v1/errors.js.map

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

package/dist/resources/models/v1/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `/v1/*` OpenAI-compatible gateway (#631).
+ *
+ * Registers three REST resources on the REST port:
+ *   POST /v1/embeddings          → V1Embeddings
+ *   POST /v1/chat/completions    → V1ChatCompletions
+ *   GET  /v1/models              → V1Models
+ *
+ * Off by default, and `defaultConfig.yaml` deliberately ships no `modelsGateway`
+ * block: with the key absent the root loader skips the component before resolving
+ * it, so none of this module graph is imported on an instance that does not use
+ * the gateway. Opt in by adding the block to `harperdb-config.yaml` with
+ * `enabled: true`, or via `set_configuration` (`modelsGateway_enabled`).
+ * `enabled: false` is honored too, for an instance that wants the block present
+ * but inert — that costs the import, which is why it is not the shipped default.
+ *
+ * Example (opt in). `rest` is required: these are REST-served resources and the
+ * gateway deliberately does not force REST to start (see `handleApplication`).
+ * Without it the resources register but every `/v1/*` path 404s.
+ *
+ * ```yaml
+ * rest: true
+ * modelsGateway:
+ *   enabled: true
+ * models:
+ *   generative:
+ *     default:
+ *       backend: ollama
+ *       model: llama3.2
+ * ```
+ *
+ * All three endpoints require `super_user` permission. Anonymous or
+ * insufficient-privilege requests receive a well-formed OpenAI error envelope.
+ */
+import type { Scope } from '../../../components/Scope.ts';
+export declare function handleApplication(scope: Scope): void;

package/dist/resources/models/v1/index.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * `/v1/*` OpenAI-compatible gateway (#631).
+ *
+ * Registers three REST resources on the REST port:
+ *   POST /v1/embeddings          → V1Embeddings
+ *   POST /v1/chat/completions    → V1ChatCompletions
+ *   GET  /v1/models              → V1Models
+ *
+ * Off by default, and `defaultConfig.yaml` deliberately ships no `modelsGateway`
+ * block: with the key absent the root loader skips the component before resolving
+ * it, so none of this module graph is imported on an instance that does not use
+ * the gateway. Opt in by adding the block to `harperdb-config.yaml` with
+ * `enabled: true`, or via `set_configuration` (`modelsGateway_enabled`).
+ * `enabled: false` is honored too, for an instance that wants the block present
+ * but inert — that costs the import, which is why it is not the shipped default.
+ *
+ * Example (opt in). `rest` is required: these are REST-served resources and the
+ * gateway deliberately does not force REST to start (see `handleApplication`).
+ * Without it the resources register but every `/v1/*` path 404s.
+ *
+ * ```yaml
+ * rest: true
+ * modelsGateway:
+ *   enabled: true
+ * models:
+ *   generative:
+ *     default:
+ *       backend: ollama
+ *       model: llama3.2
+ * ```
+ *
+ * All three endpoints require `super_user` permission. Anonymous or
+ * insufficient-privilege requests receive a well-formed OpenAI error envelope.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleApplication = handleApplication;
+const harper_logger_ts_1 = __importDefault(require("../../../utility/logging/harper_logger.js"));
+const configUtils_ts_1 = require("../../../config/configUtils.js");
+const embeddings_ts_1 = require("./embeddings.js");
+const chatCompletions_ts_1 = require("./chatCompletions.js");
+const models_ts_1 = require("./models.js");
+function handleApplication(scope) {
+    if (!scope.options.get(['enabled']))
+        return;
+    // These resources are served by REST's middleware chain, so the instance must also
+    // have a `rest`/`REST` config section — the gateway deliberately does NOT force REST
+    // to start. Doing so requires reaching into REST's module state before application
+    // configs have loaded, which silently discards an app's own `rest` options (webSocket,
+    // urlPath/host, middleware ordering). Core has no supported way yet for a component to
+    // declare "I serve REST resources"; that gap is tracked separately.
+    //
+    // Warn rather than fail: an app loaded later may still declare `rest`, so absence here
+    // is not conclusive. But defaultConfig ships no `rest` section, so enabling the gateway
+    // alone yields three registered resources and a 404 on every /v1 path — worth a line in
+    // the log instead of silence.
+    const rootConfig = (0, configUtils_ts_1.getConfigObj)();
+    if (rootConfig && !rootConfig.rest && !rootConfig.REST) {
+        harper_logger_ts_1.default.warn('modelsGateway is enabled but no `rest` section is configured; /v1/* endpoints are only served when REST is active');
+    }
+    // Explicit protocol visibility: these are REST-only wire-protocol endpoints. Without a
+    // policy, the shared registry matches them for every protocol lookup — WS dispatch could
+    // reach V1ChatCompletions.connect() and then fail iterating its non-iterable badRequest
+    // envelope, and they would surface through MQTT/GraphQL/MCP enumeration too. `sse` stays
+    // enabled for chat only: an explicit `Accept: text/event-stream` POST is dispatched via
+    // the sse lookup (REST.ts) and is a supported streaming client shape (see connect()).
+    const restOnly = { rest: true, sse: false, ws: false, mqtt: false, graphql: false, mcp: false };
+    scope.resources.set('v1/models', models_ts_1.V1Models, restOnly);
+    scope.resources.set('v1/embeddings', embeddings_ts_1.V1Embeddings, restOnly);
+    scope.resources.set('v1/chat/completions', chatCompletions_ts_1.V1ChatCompletions, { ...restOnly, sse: true });
+}
+//# sourceMappingURL=index.js.map

package/dist/resources/models/v1/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../resources/models/v1/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;;;;;AASH,8CA6BC;AAnCD,iGAAqE;AACrE,mEAA8D;AAC9D,mDAA+C;AAC/C,6DAAyD;AACzD,2CAAuC;AAEvC,SAAgB,iBAAiB,CAAC,KAAY;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;QAAE,OAAO;IAC5C,mFAAmF;IACnF,qFAAqF;IACrF,mFAAmF;IACnF,uFAAuF;IACvF,uFAAuF;IACvF,oEAAoE;IACpE,EAAE;IACF,uFAAuF;IACvF,wFAAwF;IACxF,wFAAwF;IACxF,8BAA8B;IAC9B,MAAM,UAAU,GAAG,IAAA,6BAAY,GAAyC,CAAC;IACzE,IAAI,UAAU,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACxD,0BAAY,CAAC,IAAI,CAChB,mHAAmH,CACnH,CAAC;IACH,CAAC;IACD,uFAAuF;IACvF,yFAAyF;IACzF,wFAAwF;IACxF,yFAAyF;IACzF,wFAAwF;IACxF,sFAAsF;IACtF,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAChG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,oBAAQ,EAAE,QAAQ,CAAC,CAAC;IACrD,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,EAAE,4BAAY,EAAE,QAAQ,CAAC,CAAC;IAC7D,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,qBAAqB,EAAE,sCAAiB,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/dist/resources/models/v1/models.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `GET /v1/models` — OpenAI-compatible model list endpoint (#631).
+ *
+ * Enumerates all registered embedding and generative backends from the
+ * process-wide `backendRegistry`. The response mirrors the OpenAI shape:
+ * `{ object: 'list', data: [{ id, object: 'model', created, owned_by }] }`.
+ *
+ * `logicalName` (not `backend.name`) is the `id` — it's what callers pass as
+ * `model` in subsequent requests.
+ */
+import { Resource } from '../../Resource.ts';
+import { type OpenAIErrorResponse } from './errors.ts';
+export interface OAIModelEntry {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+}
+export interface OAIModelList {
+    object: 'list';
+    data: OAIModelEntry[];
+}
+export declare class V1Models extends Resource {
+    static reservedPath: boolean;
+    static get(_target: unknown, request: unknown): OAIModelList | OpenAIErrorResponse;
+}

package/dist/resources/models/v1/models.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * `GET /v1/models` — OpenAI-compatible model list endpoint (#631).
+ *
+ * Enumerates all registered embedding and generative backends from the
+ * process-wide `backendRegistry`. The response mirrors the OpenAI shape:
+ * `{ object: 'list', data: [{ id, object: 'model', created, owned_by }] }`.
+ *
+ * `logicalName` (not `backend.name`) is the `id` — it's what callers pass as
+ * `model` in subsequent requests.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V1Models = void 0;
+const Resource_ts_1 = require("../../Resource.js");
+const backendRegistry_ts_1 = require("../backendRegistry.js");
+const errors_ts_1 = require("./errors.js");
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+class V1Models extends Resource_ts_1.Resource {
+    // Reserve this fixed route: a later app registration at the same path becomes a
+    // loud conflict (ErrorResource) instead of silently replacing the gateway and its
+    // super_user gate. See Resources.set.
+    static reservedPath = true;
+    static get(_target, request) {
+        const authError = (0, errors_ts_1.authorizeV1Request)(request);
+        if (authError)
+            return authError;
+        const created = Math.floor(Date.now() / 1000);
+        // OpenAI model ids are unique; a logical name registered for both generative and
+        // embedding (e.g. `default` in each section) is one model id to callers.
+        const ids = new Set();
+        const data = [];
+        for (const kind of ['generative', 'embedding']) {
+            for (const { logicalName } of (0, backendRegistry_ts_1.listBackends)(kind)) {
+                if (ids.has(logicalName))
+                    continue;
+                ids.add(logicalName);
+                data.push({ id: logicalName, object: 'model', created, owned_by: 'harper' });
+            }
+        }
+        return { object: 'list', data };
+    }
+}
+exports.V1Models = V1Models;
+//# sourceMappingURL=models.js.map

package/dist/resources/models/v1/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../resources/models/v1/models.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,mDAA6C;AAC7C,8DAAqD;AACrD,2CAA2E;AAc3E,8FAA8F;AAC9F,MAAa,QAAS,SAAQ,sBAAQ;IACrC,gFAAgF;IAChF,kFAAkF;IAClF,sCAAsC;IACtC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC;IAE3B,MAAM,CAAC,GAAG,CAAC,OAAgB,EAAE,OAAgB;QAC5C,MAAM,SAAS,GAAG,IAAA,8BAAkB,EAAC,OAAc,CAAC,CAAC;QACrD,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;QAEhC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC9C,iFAAiF;QACjF,yEAAyE;QACzE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,MAAM,IAAI,GAAoB,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,WAAW,CAAU,EAAE,CAAC;YACzD,KAAK,MAAM,EAAE,WAAW,EAAE,IAAI,IAAA,iCAAY,EAAC,IAAI,CAAC,EAAE,CAAC;gBAClD,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC;oBAAE,SAAS;gBACnC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;gBACrB,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC9E,CAAC;QACF,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC;;AAvBF,4BAwBC"}

package/dist/resources/models/v1/translation.d.ts

@@ -0,0 +1,133 @@
+/**
+ * OpenAI ↔ Harper internal shape mappers for the `/v1/*` gateway (#631).
+ *
+ * All functions are pure (no I/O, no side-effects) so they can be unit-tested
+ * in isolation without a running Harper instance.
+ */
+import type { EmbedOpts, GenerateInput, GenerateOpts, GenerateResult, Message, ToolDef, TokenUsage } from '../types.ts';
+export interface OAIMessageIn {
+    role: string;
+    /** May be null for assistant messages that only contain tool_calls. */
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: string;
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    /** Present on role === 'tool' messages. */
+    tool_call_id?: string;
+}
+export interface OAIToolIn {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: object;
+    };
+}
+export interface OAIChatRequest {
+    model?: string;
+    messages: OAIMessageIn[];
+    tools?: OAIToolIn[];
+    /** Subset recognised: 'none' | 'auto' | 'required' | {type:'function', function:{name}}. */
+    tool_choice?: unknown;
+    temperature?: number;
+    /** OpenAI v1 field; superseded by max_completion_tokens in v1+. */
+    max_tokens?: number;
+    /** Preferred alias; takes precedence over max_tokens when both present. */
+    max_completion_tokens?: number;
+    response_format?: {
+        type: string;
+        json_schema?: unknown;
+    };
+    stream?: boolean;
+}
+/**
+ * Map an OpenAI `messages` array to Harper `Message[]`.
+ * Normalises `tool_calls[].function.arguments` from JSON strings to parsed
+ * objects (Harper's internal contract); maps `tool_call_id` to `toolCallId`.
+ */
+export declare function translateMessages(oaiMessages: OAIMessageIn[]): Message[];
+/** Map OpenAI `tools[]` to Harper `ToolDef[]`. */
+export declare function translateTools(oaiTools: OAIToolIn[]): ToolDef[];
+/**
+ * Build Harper `GenerateInput` from translated messages and tool definitions.
+ * Uses the object form `{ messages, tools }` when tools are present, so that
+ * tool definitions travel alongside messages per Harper's type contract.
+ */
+export declare function toGenerateInput(messages: Message[], tools: ToolDef[] | undefined): GenerateInput;
+/**
+ * Validate the OpenAI wire shapes this gateway maps, returning a client-facing
+ * message for a 400 or `null` when the request is well-formed.
+ *
+ * Kept separate from the mappers so malformed nested input (`messages: [null]`,
+ * `tool_calls: [{}]`, `tools: [{}]`) becomes an OpenAI-shaped 400 instead of a
+ * TypeError escaping the handler as an RFC 9457 500.
+ */
+export declare function validateChatRequest(body: OAIChatRequest): string | null;
+/**
+ * Map an OpenAI chat-completion request body to `GenerateOpts`.
+ *
+ * `tool_choice` is honored by the caller, not here: `'none'` omits tools from the
+ * generate input entirely, and unrepresentable choices are rejected up front by
+ * `validateChatRequest`. Full in-process tool-call orchestration is #612 (out of
+ * scope for #631), so tool calls are always returned to the caller to invoke.
+ *
+ * Assumes `validateChatRequest` has already passed.
+ */
+export declare function toGenerateOpts(body: OAIChatRequest): GenerateOpts;
+/** Map an OpenAI embeddings request body to `EmbedOpts`. */
+export declare function toEmbedOpts(body: {
+    model?: string;
+}): EmbedOpts;
+interface OAIToolCallOut {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface OAIAssistantMessage {
+    role: 'assistant';
+    /** null when the message contains only tool_calls. */
+    content: string | null;
+    tool_calls?: OAIToolCallOut[];
+}
+export interface OAIChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: OAIAssistantMessage;
+        finish_reason: string;
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/** Map a Harper `GenerateResult` to an OpenAI `chat.completion` response object. */
+export declare function toChatCompletion(result: GenerateResult, model: string, id?: string): OAIChatCompletion;
+export interface OAIEmbedResponse {
+    object: 'list';
+    data: Array<{
+        embedding: number[];
+        index: number;
+        object: 'embedding';
+    }>;
+    model: string;
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+}
+/** Map `Float32Array[]` from `models.embed()` to an OpenAI embeddings response. */
+export declare function toEmbedResponse(vecs: Float32Array[], model: string, usage?: TokenUsage): OAIEmbedResponse;
+export {};