@almadar/llm 2.0.1 → 2.0.3

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { R as RateLimiter, a as RateLimiterOptions, T as TokenTracker, b as Toke
 export { autoCloseJson, extractJsonFromText, isValidJson, parseJsonResponse, safeParseJson } from './json-parser.js';
 import { z } from 'zod';
 export { JsonSchema, STRUCTURED_OUTPUT_MODELS, StructuredGenerationOptions, StructuredGenerationResult, StructuredOutputClient, StructuredOutputOptions, getStructuredOutputClient, isStructuredOutputAvailable, resetStructuredOutputClient } from './structured-output.js';
+import { ServiceContract } from '@almadar/core';
 import '@langchain/openai';
 import '@langchain/anthropic';
 
@@ -64,4 +65,82 @@ declare function salvagePartialResponse<T>(rawResponse: string): T | null;
 declare function callWithContinuation<T>(options: ContinuationOptions<T>): Promise<ContinuationResult<T>>;
 declare function buildGenericContinuationPrompt(context: string, partialResponse: string, attempt: number, maxAttempts?: number): string;
 
-export { type ContinuationOptions, type ContinuationResult, LLMClient, LLMFinishReason, type TruncationReason, type TruncationResult, buildGenericContinuationPrompt, callWithContinuation, detectTruncation, findLastCompleteElement, isLikelyTruncated, mergeResponses, salvagePartialResponse };
+/**
+ * LLM Service Contract
+ *
+ * Defines the call-service-compatible actions for the LLM service.
+ * These actions can be invoked from `.orb` schemas via
+ * `["call-service", "llm", "<action>", {...}]`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * All call-service actions exposed by the LLM service.
+ */
+type LLMServiceActions = {
+    /** Generate text from a prompt. */
+    generate: {
+        params: {
+            systemPrompt?: string;
+            userPrompt: string;
+            model?: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        result: {
+            content: string;
+            usage: {
+                promptTokens: number;
+                completionTokens: number;
+                totalTokens: number;
+            };
+        };
+    };
+    /** Classify text into one of the given categories. */
+    classify: {
+        params: {
+            text: string;
+            categories: string[];
+            model?: string;
+        };
+        result: {
+            category: string;
+            confidence: number;
+            reasoning: string;
+        };
+    };
+    /** Extract structured data from text according to a JSON schema. */
+    extract: {
+        params: {
+            text: string;
+            schema: Record<string, unknown>;
+            model?: string;
+        };
+        result: {
+            data: Record<string, unknown>;
+            confidence: number;
+        };
+    };
+    /** Summarize text with optional length and style constraints. */
+    summarize: {
+        params: {
+            text: string;
+            maxLength?: number;
+            style?: string;
+            model?: string;
+        };
+        result: {
+            summary: string;
+            keyPoints: string[];
+        };
+    };
+};
+/**
+ * The full service contract for the LLM service.
+ * Implementations must provide an `execute(action, params)` method
+ * that dispatches to the correct action handler.
+ */
+type LLMServiceContract = ServiceContract<LLMServiceActions>;
+
+export { type ContinuationOptions, type ContinuationResult, LLMClient, LLMFinishReason, type LLMServiceActions, type LLMServiceContract, type TruncationReason, type TruncationResult, buildGenericContinuationPrompt, callWithContinuation, detectTruncation, findLastCompleteElement, isLikelyTruncated, mergeResponses, salvagePartialResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Multi-provider LLM client with rate limiting, token tracking, structured outputs, and continuation handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "@langchain/openai": "^1.2.6",
     "openai": "^6.18.0",
     "zod": "^3.22.0",
-    "@langchain/core": "^0.3.0"
+    "@langchain/core": "^1.1.30"
   },
   "peerDependencies": {
     "@almadar/core": ">=2.0.0"
@@ -44,9 +44,12 @@
     }
   },
   "devDependencies": {
+    "@almadar/eslint-plugin": ">=2.3.0",
+    "@typescript-eslint/parser": "8.56.0",
+    "@types/node": "^22.0.0",
+    "eslint": "10.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.3.0"
   },
   "repository": {
     "type": "git",

package/src/contracts.ts

@@ -0,0 +1,83 @@
+/**
+ * LLM Service Contract
+ *
+ * Defines the call-service-compatible actions for the LLM service.
+ * These actions can be invoked from `.orb` schemas via
+ * `["call-service", "llm", "<action>", {...}]`.
+ *
+ * @packageDocumentation
+ */
+
+import type { ServiceContract } from "@almadar/core";
+
+/**
+ * All call-service actions exposed by the LLM service.
+ */
+export type LLMServiceActions = {
+  /** Generate text from a prompt. */
+  generate: {
+    params: {
+      systemPrompt?: string;
+      userPrompt: string;
+      model?: string;
+      temperature?: number;
+      maxTokens?: number;
+    };
+    result: {
+      content: string;
+      usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+      };
+    };
+  };
+
+  /** Classify text into one of the given categories. */
+  classify: {
+    params: {
+      text: string;
+      categories: string[];
+      model?: string;
+    };
+    result: {
+      category: string;
+      confidence: number;
+      reasoning: string;
+    };
+  };
+
+  /** Extract structured data from text according to a JSON schema. */
+  extract: {
+    params: {
+      text: string;
+      schema: Record<string, unknown>;
+      model?: string;
+    };
+    result: {
+      data: Record<string, unknown>;
+      confidence: number;
+    };
+  };
+
+  /** Summarize text with optional length and style constraints. */
+  summarize: {
+    params: {
+      text: string;
+      maxLength?: number;
+      style?: string;
+      model?: string;
+    };
+    result: {
+      summary: string;
+      keyPoints: string[];
+    };
+  };
+};
+
+/**
+ * The full service contract for the LLM service.
+ * Implementations must provide an `execute(action, params)` method
+ * that dispatches to the correct action handler.
+ */
+export type LLMServiceContract = ServiceContract<LLMServiceActions>;

package/src/index.ts

@@ -87,3 +87,8 @@ export {
   type StructuredGenerationResult,
   type JsonSchema,
 } from './structured-output.js';
+
+export {
+  type LLMServiceActions,
+  type LLMServiceContract,
+} from './contracts.js';