@almadar/llm 2.56.0 → 2.58.0

package/src/contracts.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 
-import type { ServiceContract, ServiceParams, ServiceParamsValue } from "@almadar/core";
+import type { ServiceContract, ServiceParams, ServiceParamsValue, TraceActivity } from "@almadar/core";
 
 /**
  * JSON Schema definition for structured extraction.
@@ -37,6 +37,30 @@ interface JsonSchemaDefinition extends ServiceParams {
 type ExtractedValue = string | number | boolean | null | ExtractedValue[] | { [key: string]: ExtractedValue };
 type ExtractedData = Record<string, ExtractedValue>;
 
+/** One turn of the conversation `call-tools` continues. */
+export interface AgentChatMessage extends ServiceParams {
+  role: "user" | "assistant";
+  content: string;
+}
+
+/**
+ * What the model may use in `call-tools`. Exactly one of:
+ * `event` — a declared external input, addressed like a `listens` source
+ * (`EVENT`, `Trait.EVENT`, `Orbital.Trait.EVENT`), fired as the caller;
+ * `read` — an entity whose rows the caller may read.
+ */
+export interface AgentTool extends ServiceParams {
+  event?: string;
+  read?: string;
+}
+
+/**
+ * One thing a `call-tools` run did, in order: each model call (`llm_response`),
+ * each tool the model used (`tool_call`) and what the app answered
+ * (`tool_result`). The `@almadar/core` trace shape the activity feed renders.
+ */
+export type AgentActivity = Extract<TraceActivity, { type: "llm_response" | "tool_call" | "tool_result" }>;
+
 /**
  * All call-service actions exposed by the LLM service.
  */
@@ -121,6 +145,38 @@ export type LLMServiceActions = {
     };
   };
 
+  /**
+   * Answer a request by operating the running app as the caller: the model may
+   * fire the declared inputs and read the entities named in `tools`, through the
+   * host's ordinary dispatch (guards, policies and listens all apply), until it
+   * replies. Hitting `maxSteps` is a failure.
+   * @synonyms agent, assistant, tool use, act
+   */
+  "call-tools": {
+    params: {
+      /** The conversation so far, oldest first; the last turn is the request. */
+      messages: AgentChatMessage[];
+      /** The inputs and entities the model may use. */
+      tools: AgentTool[];
+      /** Standing instructions for the model. */
+      instructions?: string;
+      /** Model round-trips allowed before the call fails (default 8). */
+      maxSteps?: number;
+      /** Model id override. */
+      model?: string;
+    };
+    result: {
+      reply: string;
+      steps: AgentActivity[];
+      usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        modelCalls: number;
+      };
+    };
+  };
+
   /** Generate embeddings for an array of texts. */
   embed: {
     params: {

package/src/index.ts

@@ -143,8 +143,20 @@ export {
 export {
   type LLMServiceActions,
   type LLMServiceContract,
+  type MLServiceActions,
+  type MLServiceContract,
+  type AgentChatMessage,
+  type AgentTool,
+  type AgentActivity,
 } from './contracts.js';
 
+export {
+  createScriptedToolClient,
+  type ToolCallingClient,
+  type ScriptedTurn,
+  type ScriptedToolClient,
+} from './scripted-tool-client.js';
+
 export {
   MasarProvider,
   MasarError,

package/src/scripted-tool-client.ts

@@ -0,0 +1,49 @@
+/**
+ * The tool-calling seam a tool loop needs, and a scripted model for it.
+ *
+ * `ToolCallingClient` is the one `LLMClient` capability a tool loop uses: one
+ * `callWithTools` round-trip. `createScriptedToolClient` replays scripted
+ * assistant turns in order, so a loop runs deterministically with no network
+ * (unit tests, the verifiers' agent checks). It records every request it gets.
+ *
+ * @packageDocumentation
+ */
+
+import type { LLMClient, LLMUsage } from './client.js';
+import type { ChatCompletionMessage, ChatCompletionToolDef } from './tool-call-types.js';
+
+export type ToolCallingClient = Pick<LLMClient, 'callWithTools'>;
+
+export interface ScriptedTurn {
+  message: ChatCompletionMessage;
+  usage?: LLMUsage;
+}
+
+export interface ScriptedToolClient extends ToolCallingClient {
+  readonly requests: ReadonlyArray<{
+    messages: ReadonlyArray<ChatCompletionMessage>;
+    tools: ReadonlyArray<ChatCompletionToolDef>;
+  }>;
+}
+
+export function createScriptedToolClient(turns: readonly ScriptedTurn[]): ScriptedToolClient {
+  const requests: Array<{
+    messages: ReadonlyArray<ChatCompletionMessage>;
+    tools: ReadonlyArray<ChatCompletionToolDef>;
+  }> = [];
+  return {
+    requests,
+    async callWithTools(options) {
+      const turn = turns[requests.length];
+      requests.push({ messages: [...options.messages], tools: [...options.tools] });
+      if (turn === undefined) {
+        throw new Error(`scripted tool client: no scripted turn ${requests.length} (script has ${turns.length})`);
+      }
+      return {
+        message: turn.message,
+        finishReason: turn.message.tool_calls && turn.message.tool_calls.length > 0 ? 'tool_calls' : 'stop',
+        usage: turn.usage ?? null,
+      };
+    },
+  };
+}