@almadar/llm 2.36.0 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "description": "Multi-provider LLM client with rate limiting, token tracking, structured outputs, and continuation handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,10 +46,10 @@
     "@almadar/logger": "^1.10.0"
   },
   "peerDependencies": {
-    "@almadar/core": "^10.34.0"
+    "@almadar/core": "^10.35.0"
   },
   "devDependencies": {
-    "@almadar/core": "^10.34.0",
+    "@almadar/core": "^10.35.0",
     "@almadar/eslint-plugin": "^2.15.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/parser": "8.56.0",

package/src/contracts.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 
-import type { ServiceContract, ServiceParams } from "@almadar/core";
+import type { ServiceContract, ServiceParams, ServiceParamsValue } from "@almadar/core";
 
 /**
  * JSON Schema definition for structured extraction.
@@ -105,3 +105,34 @@ export type LLMServiceActions = {
  * that dispatches to the correct action handler.
  */
 export type LLMServiceContract = ServiceContract<LLMServiceActions>;
+
+/**
+ * All call-service actions exposed by the ML service — model inference on a
+ * trained or off-the-shelf checkpoint. Reached via a deployed serving
+ * orbital (see `@almadar/integrations`' `ml` integration).
+ */
+export type MLServiceActions = {
+  /** Run inference against a deployed model checkpoint. */
+  infer: {
+    params: {
+      /** `hf:<id>` for off-the-shelf weights, or a masar checkpoint id. */
+      model: string;
+      /** JSON-safe model input (tensor-shaped payload from `contract/entity-to-tensor`). */
+      input: ServiceParamsValue;
+    };
+    result: {
+      /** JSON-safe model output, before contract clamp/validation by the caller. */
+      output: ServiceParamsValue;
+      confidence: number;
+      /** Contract violations reported by the model service, if any (see `contract/violations`). */
+      violations: ServiceParamsValue[];
+    };
+  };
+};
+
+/**
+ * The full service contract for the ML service.
+ * Implementations must provide an `execute(action, params)` method
+ * that dispatches to the correct action handler.
+ */
+export type MLServiceContract = ServiceContract<MLServiceActions>;