@x12i/api-hub-models 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @x12i/api-hub-models
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosted-model submit and poll adapter for the x12i API hub
+
+ESM package for Node.js 24 or newer. Import the public name:
+
+```js
+import * as models from '@x12i/api-hub-models';
+```
+
+The whole set is also available from [`@x12i/api-hub`](https://www.npmjs.com/package/@x12i/api-hub).

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type ModelOutput, type ModelsClient } from '@x12i/api-hub-core';
+export type PredictionStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export interface Prediction {
+    id: string;
+    status: PredictionStatus;
+    output?: unknown;
+    error?: string;
+}
+/** One hosted-model provider: submit work, then poll it. */
+export interface ModelAdapter {
+    readonly name: string;
+    submit(model: string, input: Record<string, unknown>, signal?: AbortSignal): Promise<Prediction>;
+    poll(id: string, signal?: AbortSignal): Promise<Prediction>;
+}
+/** Maps provider output (strings, URL lists, objects) onto the hub's ModelOutput shape. */
+export declare function normaliseOutput(model: string, output: unknown): ModelOutput;
+export interface ModelsClientOptions {
+    adapter: ModelAdapter;
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+    defaultTimeoutMs?: number;
+}
+export declare function createModelsClient(options: ModelsClientOptions): ModelsClient;
+/** Fixture adapter for tests: each submit returns the next scripted sequence of poll states. */
+export declare function scriptedAdapter(script: Record<string, Prediction[]>): ModelAdapter & {
+    submitted: string[];
+};
+/**
+ * Hosted-model provider wiring. No provider is enabled until the owner records one in
+ * docs/CONVENTIONS.md; until then every call is `service_not_connected`.
+ */
+export declare function createModelsFromEnv(_env?: NodeJS.ProcessEnv): ModelsClient;

package/dist/index.js

@@ -0,0 +1,97 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { HubError, stubModels } from '@x12i/api-hub-core';
+const URL_LIKE = /^https:\/\/\S+$/;
+/** Maps provider output (strings, URL lists, objects) onto the hub's ModelOutput shape. */
+export function normaliseOutput(model, output) {
+    const result = { model };
+    const files = [];
+    const texts = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            if (URL_LIKE.test(value))
+                files.push({ url: value });
+            else
+                texts.push(value);
+        }
+        else if (Array.isArray(value))
+            value.forEach(visit);
+    };
+    visit(output);
+    if (files.length > 0)
+        result.files = files;
+    if (texts.length > 0)
+        result.text = texts.join('');
+    if (output !== null && typeof output === 'object' && !Array.isArray(output))
+        result.data = output;
+    else if (files.length === 0 && texts.length === 0 && output !== undefined)
+        result.data = output;
+    return result;
+}
+export function createModelsClient(options) {
+    const { adapter } = options;
+    const first = options.pollIntervalMs ?? 500;
+    const max = options.maxPollIntervalMs ?? 5_000;
+    return {
+        async run(req) {
+            const timeout = AbortSignal.timeout(req.timeoutMs ?? options.defaultTimeoutMs ?? 120_000);
+            const signal = req.signal ? AbortSignal.any([req.signal, timeout]) : timeout;
+            try {
+                let prediction = await adapter.submit(req.model, req.input, signal);
+                let wait = first;
+                while (prediction.status === 'queued' || prediction.status === 'running') {
+                    await sleep(wait, undefined, { signal });
+                    wait = Math.min(wait * 2, max);
+                    prediction = await adapter.poll(prediction.id, signal);
+                }
+                if (prediction.status === 'failed') {
+                    throw new HubError('upstream_unavailable', 'The hosted model failed to produce a result');
+                }
+                return normaliseOutput(req.model, prediction.output);
+            }
+            catch (err) {
+                if (err instanceof HubError)
+                    throw err;
+                if (timeout.aborted)
+                    throw new HubError('timeout', 'The hosted model took too long');
+                if (req.signal?.aborted)
+                    throw new HubError('timeout', 'The request was cancelled');
+                throw new HubError('upstream_unavailable', 'The hosted model is unavailable');
+            }
+        },
+    };
+}
+/** Fixture adapter for tests: each submit returns the next scripted sequence of poll states. */
+export function scriptedAdapter(script) {
+    const submitted = [];
+    const queues = new Map();
+    let n = 0;
+    return {
+        name: 'scripted',
+        submitted,
+        async submit(model) {
+            submitted.push(model);
+            const steps = script[model];
+            if (!steps || steps.length === 0)
+                throw new HubError('upstream_unavailable', `No script for ${model}`);
+            const id = `p${++n}`;
+            queues.set(id, steps.map((s) => ({ ...s, id })));
+            return queues.get(id).shift();
+        },
+        async poll(id) {
+            const queue = queues.get(id);
+            const next = queue?.shift();
+            if (!next)
+                throw new HubError('upstream_unavailable', 'Script exhausted');
+            return next;
+        },
+    };
+}
+/**
+ * Hosted-model provider wiring. No provider is enabled until the owner records one in
+ * docs/CONVENTIONS.md; until then every call is `service_not_connected`.
+ */
+// TODO(owner): pick a hosted-model provider (no training on inputs) and add its adapter here.
+export function createModelsFromEnv(_env = process.env) {
+    return stubModels;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/models/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { setTimeout as sleep } from 'node:timers/promises';\nimport { HubError, stubModels, type ModelOutput, type ModelRunRequest, type ModelsClient } from '@x12i/api-hub-core';\n\nexport type PredictionStatus = 'queued' | 'running' | 'succeeded' | 'failed';\n\nexport interface Prediction {\n  id: string;\n  status: PredictionStatus;\n  output?: unknown;\n  error?: string;\n}\n\n/** One hosted-model provider: submit work, then poll it. */\nexport interface ModelAdapter {\n  readonly name: string;\n  submit(model: string, input: Record<string, unknown>, signal?: AbortSignal): Promise<Prediction>;\n  poll(id: string, signal?: AbortSignal): Promise<Prediction>;\n}\n\nconst URL_LIKE = /^https:\\/\\/\\S+$/;\n\n/** Maps provider output (strings, URL lists, objects) onto the hub's ModelOutput shape. */\nexport function normaliseOutput(model: string, output: unknown): ModelOutput {\n  const result: ModelOutput = { model };\n  const files: { url: string }[] = [];\n  const texts: string[] = [];\n  const visit = (value: unknown) => {\n    if (typeof value === 'string') {\n      if (URL_LIKE.test(value)) files.push({ url: value });\n      else texts.push(value);\n    } else if (Array.isArray(value)) value.forEach(visit);\n  };\n  visit(output);\n  if (files.length > 0) result.files = files;\n  if (texts.length > 0) result.text = texts.join('');\n  if (output !== null && typeof output === 'object' && !Array.isArray(output)) result.data = output;\n  else if (files.length === 0 && texts.length === 0 && output !== undefined) result.data = output;\n  return result;\n}\n\nexport interface ModelsClientOptions {\n  adapter: ModelAdapter;\n  pollIntervalMs?: number;\n  maxPollIntervalMs?: number;\n  defaultTimeoutMs?: number;\n}\n\nexport function createModelsClient(options: ModelsClientOptions): ModelsClient {\n  const { adapter } = options;\n  const first = options.pollIntervalMs ?? 500;\n  const max = options.maxPollIntervalMs ?? 5_000;\n\n  return {\n    async run(req: ModelRunRequest): Promise<ModelOutput> {\n      const timeout = AbortSignal.timeout(req.timeoutMs ?? options.defaultTimeoutMs ?? 120_000);\n      const signal = req.signal ? AbortSignal.any([req.signal, timeout]) : timeout;\n      try {\n        let prediction = await adapter.submit(req.model, req.input, signal);\n        let wait = first;\n        while (prediction.status === 'queued' || prediction.status === 'running') {\n          await sleep(wait, undefined, { signal });\n          wait = Math.min(wait * 2, max);\n          prediction = await adapter.poll(prediction.id, signal);\n        }\n        if (prediction.status === 'failed') {\n          throw new HubError('upstream_unavailable', 'The hosted model failed to produce a result');\n        }\n        return normaliseOutput(req.model, prediction.output);\n      } catch (err) {\n        if (err instanceof HubError) throw err;\n        if (timeout.aborted) throw new HubError('timeout', 'The hosted model took too long');\n        if (req.signal?.aborted) throw new HubError('timeout', 'The request was cancelled');\n        throw new HubError('upstream_unavailable', 'The hosted model is unavailable');\n      }\n    },\n  };\n}\n\n/** Fixture adapter for tests: each submit returns the next scripted sequence of poll states. */\nexport function scriptedAdapter(script: Record<string, Prediction[]>): ModelAdapter & { submitted: string[] } {\n  const submitted: string[] = [];\n  const queues = new Map<string, Prediction[]>();\n  let n = 0;\n  return {\n    name: 'scripted',\n    submitted,\n    async submit(model) {\n      submitted.push(model);\n      const steps = script[model];\n      if (!steps || steps.length === 0) throw new HubError('upstream_unavailable', `No script for ${model}`);\n      const id = `p${++n}`;\n      queues.set(id, steps.map((s) => ({ ...s, id })));\n      return queues.get(id)!.shift()!;\n    },\n    async poll(id) {\n      const queue = queues.get(id);\n      const next = queue?.shift();\n      if (!next) throw new HubError('upstream_unavailable', 'Script exhausted');\n      return next;\n    },\n  };\n}\n\n/**\n * Hosted-model provider wiring. No provider is enabled until the owner records one in\n * docs/CONVENTIONS.md; until then every call is `service_not_connected`.\n */\n// TODO(owner): pick a hosted-model provider (no training on inputs) and add its adapter here.\nexport function createModelsFromEnv(_env: NodeJS.ProcessEnv = process.env): ModelsClient {\n  return stubModels;\n}\n"]}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@x12i/api-hub-models",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Hosted-model submit and poll adapter for the x12i API hub",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/apis-hub.git",
+    "directory": "packages/models"
+  },
+  "bugs": {
+    "url": "https://github.com/x12i/apis-hub/issues"
+  },
+  "homepage": "https://github.com/x12i/apis-hub",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@x12i/api-hub-core": "0.1.1"
+  }
+}