@mozaik-ai/core 3.10.2 → 3.11.0

package/README.md

@@ -78,11 +78,11 @@ flowchart LR
 
 Mozaik ships three ready-to-use participants:
 
-| Participant     | Role |
-| --------------- | ---- |
-| `BaseHuman`     | Sends messages with `sendMessage(environment, text)` |
-| `BaseAgent`     | Runs inference and function calls via `InferenceRunner` and `FunctionCallRunner` |
-| `BaseObserver`  | Listens only; no inference |
+| Participant    | Role                                                                             |
+| -------------- | -------------------------------------------------------------------------------- |
+| `BaseHuman`    | Sends messages with `sendMessage(environment, text)`                             |
+| `BaseAgent`    | Runs inference and function calls via `InferenceRunner` and `FunctionCallRunner` |
+| `BaseObserver` | Listens only; no inference                                                       |
 
 ```ts
 import {
@@ -99,18 +99,15 @@ const environment = new AgenticEnvironment()
 
 const human = new BaseHuman()
 const agent = new BaseAgent(new OpenAIInferenceRunner(), new DefaultFunctionCallRunner())
+const observer = new BaseObserver()
 
 human.join(environment)
 agent.join(environment)
+observer.join(environment)
 
 environment.start()
 
-const context = ModelContext.create("demo")
-const model = new Gpt54Mini()
-
-// Both participants produce items in parallel — neither awaits the other.
 human.sendMessage(environment, "Hello")
-agent.runInference(environment, context, model)
 ```
 
 The environment fans every item out to every subscriber synchronously and without awaiting them, so a slow listener never blocks producers or other listeners.
@@ -187,18 +184,37 @@ Three things to note:
 
 ## Streaming and semantic events
 
-Enable streaming on a model that supports it, then run inference as usual:
+When inference runs with streaming enabled (`model.setStreaming(true)` on a model that supports it), the runner does not wait for the full response. As the provider emits chunks, `OpenAIInferenceRunner` yields **`SemanticEvent`** items (`type` + `data`) and the environment delivers each one to **every** joined participant immediately — the same fan-out as messages and context items. Participants react in real time by overriding the stream handlers; no participant needs to poll or share a callback.
+
+The producing participant receives `onInternalEvent`; everyone else receives `onExternalEvent(source, event)`:
 
 ```ts
-const model = new Gpt54Mini()
-model.setStreaming(true)
+import { BaseAgent, Participant, SemanticEvent } from "@mozaik-ai/core"
+
+// Agent that runs streaming inference — can observe its own stream chunks.
+export class StreamingAgent extends BaseAgent {
+	async onInternalEvent(event: SemanticEvent<unknown>): Promise<void> {
+		if (event.type === "response.output_text.delta") {
+			// e.g. keep a local buffer of partial output
+		}
+	}
+}
 
-await agent.runInference(environment, context, model)
-```
+// Any other participant — UI, logger, second agent — reacts to another's stream.
+export class LiveTranscript extends Participant {
+	async onExternalEvent(source: Participant, event: SemanticEvent<unknown>): Promise<void> {
+		if (event.type === "response.output_text.delta") {
+			const { delta } = event.data as { delta: string }
+			process.stdout.write(delta)
+		}
+	}
 
-With streaming enabled, `OpenAIInferenceRunner` emits **`SemanticEvent`** chunks (provider `type` + `data`) into the environment. The producing agent receives `onInternalEvent`; everyone else receives `onExternalEvent(source, event)`. Use these handlers to drive a live UI—for example, print text deltas from `response.output_text.delta` events.
+	// Self-emitted stream events are unused for a pure observer.
+	async onInternalEvent(): Promise<void> {}
+}
+```
 
-`setStreaming(true)` on a model without `supportStreaming` throws before the API is called.
+Enable streaming on the model before calling `runInference` as usual. `setStreaming(true)` on a model without `supportStreaming` throws before the API is called.
 
 ---
 
@@ -319,12 +335,7 @@ Humans send text with `sendMessage(environment, message)`; other participants re
 An `InferenceRunner` can yield `ReasoningItem`, `FunctionCallItem`, `ModelMessageItem`, and `SemanticEvent` (when streaming).
 
 ```ts
-import {
-	InferenceRunner,
-	ModelContext,
-	GenerativeModel,
-	OpenAIInferenceRunner,
-} from "@mozaik-ai/core"
+import { InferenceRunner, ModelContext, GenerativeModel, OpenAIInferenceRunner } from "@mozaik-ai/core"
 
 // Use the bundled runner, or implement InferenceRunner for another provider.
 const runner: InferenceRunner = new OpenAIInferenceRunner()
@@ -350,16 +361,6 @@ export class ToolRegistryFunctionCallRunner implements FunctionCallRunner {
 }
 ```
 
-### Wiring it together
-
-```ts
-import { BaseAgent, AgenticEnvironment, OpenAIInferenceRunner } from "@mozaik-ai/core"
-
-const agent = new BaseAgent(new OpenAIInferenceRunner(), new ToolRegistryFunctionCallRunner(tools))
-
-agent.join(new AgenticEnvironment())
-```
-
 ---
 
 ## Examples

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
 
 declare abstract class ContextItem {
     abstract readonly type: string;
@@ -292,8 +293,8 @@ declare class SemanticEvent<T> {
 declare class AgenticEnvironment {
     protected subscribers: Participant[];
     private isActive;
-    subscribe(subscriber: Participant): void;
-    unsubscribe(subscriber: Participant): void;
+    subscribe(participant: Participant): void;
+    unsubscribe(participant: Participant): void;
     deliverFunctionCall(source: Participant, item: FunctionCallItem): void;
     deliverModelMessage(source: Participant, item: ModelMessageItem): void;
     deliverReasoning(source: Participant, item: ReasoningItem): void;
@@ -385,12 +386,47 @@ declare class BaseHuman extends Human {
     onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
+declare class InferenceRequest {
+    readonly model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
+    readonly context: ModelContext;
+    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext);
+}
+
+declare class InferenceResponse {
+    readonly contextItems: ContextItem[];
+    readonly tokenUsage?: TokenUsage;
+    constructor(contextItems: ContextItem[], tokenUsage: TokenUsage | undefined);
+}
+
+/**
+ * Provider-agnostic port for a single round of inference.
+ *
+ * Lives in the domain layer; concrete adapters (OpenAI Responses,
+ * Anthropic Messages, DeepSeek Chat Completions, …) live in the
+ * infrastructure layer and are injected into application-layer runners
+ * through their constructor. The application layer must depend on this
+ * interface, never on a concrete provider client.
+ */
+interface ModelRuntime {
+    infer(request: InferenceRequest): Promise<InferenceResponse>;
+}
+
 type InferenceItem = ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>;
+/**
+ * Application-layer inference runner. Provider-agnostic: it depends on
+ * the {@link ModelRuntime} domain port and receives a concrete
+ * infrastructure adapter (OpenAIResponses, AnthropicMessages, …)
+ * through its constructor. The runner never instantiates a provider
+ * client itself — wiring happens at the composition root.
+ *
+ * Name retained for backward compatibility; the runner works with any
+ * `ModelRuntime`, not just OpenAI.
+ */
 declare class OpenAIInferenceRunner implements InferenceRunner {
+    private readonly runtime;
+    constructor(runtime: ModelRuntime);
     run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<InferenceItem>;
-    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
-    mapContextToRequest(context: ModelContext): any[];
-    extractContextItems(response: any): ContextItem[];
+    private isStreamingRuntime;
 }
 
 declare class DefaultFunctionCallRunner implements FunctionCallRunner {
@@ -441,4 +477,103 @@ declare class BaseObserver extends Observer {
     onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
-export { Agent, AgenticEnvironment, BaseAgent, BaseHuman, BaseObserver, ContextItem, DefaultFunctionCallRunner, DeveloperMessageItem, FunctionCallItem, FunctionCallOutputItem, type FunctionCallRunner, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, Gpt55, Human, InMemoryModelContextRepository, type InferenceRunner, InputTokenDetails, ModelContext, type ModelContextRepository, ModelMessageItem, Observer, OpenAIInferenceRunner, OutputTokenDetails, Participant, ReasoningItem, SemanticEvent, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };
+/**
+ * Optional streaming companion to {@link ModelRuntime}. Adapters whose
+ * provider can stream a round implement this in addition to
+ * `ModelRuntime`; runners delegate to `stream` only when the model has
+ * streaming enabled and the injected runtime actually implements it.
+ */
+interface StreamingRuntime {
+    stream(request: InferenceRequest, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>>;
+}
+
+declare class OpenAIResponses implements ModelRuntime, StreamingRuntime {
+    private readonly client;
+    constructor();
+    infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
+    stream(inferenceRequest: InferenceRequest, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>>;
+    private buildRequest;
+    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
+    mapContextToRequest(context: ModelContext): any[];
+    extractContextItems(response: any): ContextItem[];
+}
+
+declare class AnthropicMessages implements ModelRuntime {
+    private readonly client;
+    constructor();
+    infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
+    extractTokenUsage(response: Anthropic.Messages.Message): TokenUsage | undefined;
+    mapContextToRequest(context: ModelContext): {
+        messages: any[];
+        system?: string;
+    };
+    extractContextItems(response: Anthropic.Messages.Message): ContextItem[];
+    private addContentBlock;
+}
+
+type AnthropicReasoningEffortType = "high" | "medium" | "low" | "none";
+
+declare class ClaudeOpus47 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+declare class ClaudeSonnet46 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+declare class ClaudeHaiku45 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+export { Agent, AgenticEnvironment, AnthropicMessages, BaseAgent, BaseHuman, BaseObserver, ClaudeHaiku45, ClaudeOpus47, ClaudeSonnet46, ContextItem, DefaultFunctionCallRunner, DeveloperMessageItem, FunctionCallItem, FunctionCallOutputItem, type FunctionCallRunner, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, Gpt55, Human, InMemoryModelContextRepository, InferenceRequest, InferenceResponse, type InferenceRunner, InputTokenDetails, ModelContext, type ModelContextRepository, ModelMessageItem, type ModelRuntime, Observer, OpenAIInferenceRunner, OpenAIResponses, OutputTokenDetails, Participant, ReasoningItem, SemanticEvent, type StreamingRuntime, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import OpenAI from 'openai';
+import Anthropic from '@anthropic-ai/sdk';
 
 declare abstract class ContextItem {
     abstract readonly type: string;
@@ -292,8 +293,8 @@ declare class SemanticEvent<T> {
 declare class AgenticEnvironment {
     protected subscribers: Participant[];
     private isActive;
-    subscribe(subscriber: Participant): void;
-    unsubscribe(subscriber: Participant): void;
+    subscribe(participant: Participant): void;
+    unsubscribe(participant: Participant): void;
     deliverFunctionCall(source: Participant, item: FunctionCallItem): void;
     deliverModelMessage(source: Participant, item: ModelMessageItem): void;
     deliverReasoning(source: Participant, item: ReasoningItem): void;
@@ -385,12 +386,47 @@ declare class BaseHuman extends Human {
     onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
+declare class InferenceRequest {
+    readonly model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
+    readonly context: ModelContext;
+    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext);
+}
+
+declare class InferenceResponse {
+    readonly contextItems: ContextItem[];
+    readonly tokenUsage?: TokenUsage;
+    constructor(contextItems: ContextItem[], tokenUsage: TokenUsage | undefined);
+}
+
+/**
+ * Provider-agnostic port for a single round of inference.
+ *
+ * Lives in the domain layer; concrete adapters (OpenAI Responses,
+ * Anthropic Messages, DeepSeek Chat Completions, …) live in the
+ * infrastructure layer and are injected into application-layer runners
+ * through their constructor. The application layer must depend on this
+ * interface, never on a concrete provider client.
+ */
+interface ModelRuntime {
+    infer(request: InferenceRequest): Promise<InferenceResponse>;
+}
+
 type InferenceItem = ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>;
+/**
+ * Application-layer inference runner. Provider-agnostic: it depends on
+ * the {@link ModelRuntime} domain port and receives a concrete
+ * infrastructure adapter (OpenAIResponses, AnthropicMessages, …)
+ * through its constructor. The runner never instantiates a provider
+ * client itself — wiring happens at the composition root.
+ *
+ * Name retained for backward compatibility; the runner works with any
+ * `ModelRuntime`, not just OpenAI.
+ */
 declare class OpenAIInferenceRunner implements InferenceRunner {
+    private readonly runtime;
+    constructor(runtime: ModelRuntime);
     run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<InferenceItem>;
-    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
-    mapContextToRequest(context: ModelContext): any[];
-    extractContextItems(response: any): ContextItem[];
+    private isStreamingRuntime;
 }
 
 declare class DefaultFunctionCallRunner implements FunctionCallRunner {
@@ -441,4 +477,103 @@ declare class BaseObserver extends Observer {
     onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
-export { Agent, AgenticEnvironment, BaseAgent, BaseHuman, BaseObserver, ContextItem, DefaultFunctionCallRunner, DeveloperMessageItem, FunctionCallItem, FunctionCallOutputItem, type FunctionCallRunner, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, Gpt55, Human, InMemoryModelContextRepository, type InferenceRunner, InputTokenDetails, ModelContext, type ModelContextRepository, ModelMessageItem, Observer, OpenAIInferenceRunner, OutputTokenDetails, Participant, ReasoningItem, SemanticEvent, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };
+/**
+ * Optional streaming companion to {@link ModelRuntime}. Adapters whose
+ * provider can stream a round implement this in addition to
+ * `ModelRuntime`; runners delegate to `stream` only when the model has
+ * streaming enabled and the injected runtime actually implements it.
+ */
+interface StreamingRuntime {
+    stream(request: InferenceRequest, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>>;
+}
+
+declare class OpenAIResponses implements ModelRuntime, StreamingRuntime {
+    private readonly client;
+    constructor();
+    infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
+    stream(inferenceRequest: InferenceRequest, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>>;
+    private buildRequest;
+    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
+    mapContextToRequest(context: ModelContext): any[];
+    extractContextItems(response: any): ContextItem[];
+}
+
+declare class AnthropicMessages implements ModelRuntime {
+    private readonly client;
+    constructor();
+    infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
+    extractTokenUsage(response: Anthropic.Messages.Message): TokenUsage | undefined;
+    mapContextToRequest(context: ModelContext): {
+        messages: any[];
+        system?: string;
+    };
+    extractContextItems(response: Anthropic.Messages.Message): ContextItem[];
+    private addContentBlock;
+}
+
+type AnthropicReasoningEffortType = "high" | "medium" | "low" | "none";
+
+declare class ClaudeOpus47 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+declare class ClaudeSonnet46 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+declare class ClaudeHaiku45 implements GenerativeModel {
+    readonly specification: {
+        name: string;
+        supportReasoningEffort: boolean;
+        defaultReasoningEffort: AnthropicReasoningEffortType;
+        supportStreaming: boolean;
+        contextWindowSize: number;
+        maxOutputTokens: number;
+        supportFunctionCalling: boolean;
+    };
+    private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+    setTools(tools: Tool[]): void;
+    getTools(): Tool[];
+    private readonly effort;
+    setReasoningEffort(effort: AnthropicReasoningEffortType): void;
+    getReasoningEffort(): AnthropicReasoningEffortType;
+}
+
+export { Agent, AgenticEnvironment, AnthropicMessages, BaseAgent, BaseHuman, BaseObserver, ClaudeHaiku45, ClaudeOpus47, ClaudeSonnet46, ContextItem, DefaultFunctionCallRunner, DeveloperMessageItem, FunctionCallItem, FunctionCallOutputItem, type FunctionCallRunner, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, Gpt55, Human, InMemoryModelContextRepository, InferenceRequest, InferenceResponse, type InferenceRunner, InputTokenDetails, ModelContext, type ModelContextRepository, ModelMessageItem, type ModelRuntime, Observer, OpenAIInferenceRunner, OpenAIResponses, OutputTokenDetails, Participant, ReasoningItem, SemanticEvent, type StreamingRuntime, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };