@mozaik-ai/core 3.9.5 → 3.10.1

package/README.md

@@ -56,13 +56,15 @@ OPENAI_API_KEY=your-openai-key-here
 | `onExternalReasoning`          | another agent's inference returns a reasoning item     |
 | `onModelMessage`               | its own inference returns an assistant message         |
 | `onExternalModelMessage`       | another agent's inference returns an assistant message |
+| `onInternalEvent`              | its own inference emits a semantic stream event        |
+| `onExternalEvent`              | another participant emits a semantic stream event      |
 
 Every handler defaults to a no-op — override only the ones you care about.
 
 ```mermaid
 flowchart LR
-    Human[BaseHumanParticipant] -->|streamInput| Env(("AgenticEnvironment"))
-    Agent[BaseAgentParticipant] -->|"runInference / executeFunctionCall"| Env
+    Human[BaseHuman] -->|sendMessage| Env(("AgenticEnvironment"))
+    Agent[BaseAgent] -->|"runInference / executeFunctionCall"| Env
     Observer[Custom Participant] -->|join| Env
     Env -->|"onMessage / onExternal*"| Human
     Env -->|"onFunctionCall / onReasoning / …"| Agent
@@ -74,26 +76,29 @@ flowchart LR
 
 ## Non-blocking participants
 
-Mozaik ships two ready-to-use participants:
+Mozaik ships three ready-to-use participants:
 
-| Participant            | Capabilities                                              | Pulls from                                             |
-| ---------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
-| `BaseHumanParticipant` | `InputCapable`                                            | `InputStream`                                          |
-| `BaseAgentParticipant` | `InputCapable`, `InferenceCapable`, `FunctionCallCapable` | `InputStream`, `InferenceRunner`, `FunctionCallRunner` |
+| 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 {
 	AgenticEnvironment,
-	BaseAgentParticipant,
-	BaseHumanParticipant,
+	BaseAgent,
+	BaseHuman,
+	OpenAIInferenceRunner,
+	DefaultFunctionCallRunner,
 	Gpt54Mini,
 	ModelContext,
 } from "@mozaik-ai/core"
 
 const environment = new AgenticEnvironment()
 
-const human = new BaseHumanParticipant(humanInputSource)
-const agent = new BaseAgentParticipant(agentInputSource, inferenceRunner, functionCallRunner)
+const human = new BaseHuman()
+const agent = new BaseAgent(new OpenAIInferenceRunner(), new DefaultFunctionCallRunner())
 
 human.join(environment)
 agent.join(environment)
@@ -104,7 +109,7 @@ const context = ModelContext.create("demo")
 const model = new Gpt54Mini()
 
 // Both participants produce items in parallel — neither awaits the other.
-human.streamInput(environment)
+human.sendMessage(environment, "Hello")
 agent.runInference(environment, context, model)
 ```
 
@@ -114,32 +119,33 @@ The environment fans every item out to every subscriber synchronously and withou
 
 ## Reactive agent
 
-A reactive agent extends `BaseAgentParticipant` and overrides the handlers it wants to react on. Each handler is already a no-op in the base class, so only the relevant ones need bodies:
+A reactive agent extends `BaseAgent` and overrides the handlers it wants to react on. Each handler is already a no-op in the base class, so only the relevant ones need bodies:
 
 ```ts
 import {
-	BaseAgentParticipant,
+	BaseAgent,
 	Participant,
 	UserMessageItem,
 	FunctionCallItem,
+	FunctionCallOutputItem,
+	ReasoningItem,
+	ModelMessageItem,
 	AgenticEnvironment,
 	ModelContext,
 	GenerativeModel,
-	InputStream,
 	InferenceRunner,
 	FunctionCallRunner,
 } from "@mozaik-ai/core"
 
-export class ReactiveAgent extends BaseAgentParticipant {
+export class ReactiveAgent extends BaseAgent {
 	constructor(
-		inputSource: InputStream,
 		inferenceRunner: InferenceRunner,
 		functionCallRunner: FunctionCallRunner,
 		private readonly environment: AgenticEnvironment,
 		private readonly context: ModelContext,
 		private readonly model: GenerativeModel,
 	) {
-		super(inputSource, inferenceRunner, functionCallRunner)
+		super(inferenceRunner, functionCallRunner)
 	}
 
 	// A message from a human (or any other participant) → record it and think.
@@ -179,12 +185,29 @@ Three things to note:
 
 ---
 
+## Streaming and semantic events
+
+Enable streaming on a model that supports it, then run inference as usual:
+
+```ts
+const model = new Gpt54Mini()
+model.setStreaming(true)
+
+await agent.runInference(environment, context, model)
+```
+
+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.
+
+`setStreaming(true)` on a model without `supportStreaming` throws before the API is called.
+
+---
+
 ## Lifecycle hooks
 
 Every participant receives lifecycle notifications when it or others join/leave an environment:
 
 ```ts
-export class TeamAgent extends BaseAgentParticipant {
+export class TeamAgent extends BaseAgent {
 	// Called when this participant joins an environment.
 	onJoined(environment: AgenticEnvironment): void {
 		console.log("I joined the environment")
@@ -270,64 +293,41 @@ await repo.save(context)
 
 Implement `ModelContextRepository` to plug in any storage backend.
 
-The default OpenAI provider is `OpenAIResponses`, implementing the [OpenResponses](https://www.openresponses.org/) spec. It maps `ModelContext` to the OpenAI Responses API and back into typed `ContextItem`s. Bundled models: `Gpt54`, `Gpt54Mini`, `Gpt54Nano`, `Gpt55`.
+The default inference path is `OpenAIInferenceRunner`, which maps `ModelContext` to the OpenAI Responses API and back into typed `ContextItem`s (and `SemanticEvent`s when streaming). Bundled models: `Gpt54`, `Gpt54Mini`, `Gpt54Nano`, `Gpt55`.
 
 ```ts
-import { OpenAIResponses, InferenceRequest, Gpt54 } from "@mozaik-ai/core"
+import { OpenAIInferenceRunner, DefaultFunctionCallRunner, Gpt54, ModelContext } from "@mozaik-ai/core"
+
+const runner = new OpenAIInferenceRunner()
+const context = ModelContext.create("demo")
 
-const runtime = new OpenAIResponses()
-const response = await runtime.infer(new InferenceRequest(new Gpt54(), context))
+for await (const item of runner.run(context, new Gpt54())) {
+	// ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent
+}
 ```
 
 ---
 
 ## Overriding Generators
 
-Mozaik uses generators for inference, function calls, and message streams — that's what lets the system emit events incrementally so participants can react to them as they arrive. Swap any generator to change _how_ events are produced.
-
-### Custom `InputStream`
-
-```ts
-import { InputStream } from "@mozaik-ai/core"
-
-export class HelloInputStream implements InputStream {
-	async *stream(): AsyncIterable<string> {
-		yield "Hello"
-		yield "World"
-	}
-}
-```
+Mozaik uses async generators for inference and function calls — that's what lets the system emit events incrementally so participants can react to them as they arrive. Swap any runner to change _how_ events are produced.
 
-Each yielded string is delivered to other participants through `onMessage(message: string)`.
+Humans send text with `sendMessage(environment, message)`; other participants receive it via `onMessage`.
 
 ### Custom `InferenceRunner`
 
-An `InferenceRunner` can yield `ReasoningItem`, `FunctionCallItem`, and `ModelMessageItem`.
+An `InferenceRunner` can yield `ReasoningItem`, `FunctionCallItem`, `ModelMessageItem`, and `SemanticEvent` (when streaming).
 
 ```ts
 import {
 	InferenceRunner,
-	InferenceRequest,
 	ModelContext,
 	GenerativeModel,
-	OpenAIResponses,
-	ReasoningItem,
-	FunctionCallItem,
-	ModelMessageItem,
+	OpenAIInferenceRunner,
 } from "@mozaik-ai/core"
 
-type InferenceItem = ReasoningItem | FunctionCallItem | ModelMessageItem
-
-export class OpenAIInferenceRunner implements InferenceRunner {
-	private readonly runtime = new OpenAIResponses()
-
-	async *run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<InferenceItem> {
-		const response = await this.runtime.infer(new InferenceRequest(model, context))
-		for (const item of response.contextItems) {
-			yield item as InferenceItem
-		}
-	}
-}
+// Use the bundled runner, or implement InferenceRunner for another provider.
+const runner: InferenceRunner = new OpenAIInferenceRunner()
 ```
 
 ### Custom `FunctionCallRunner`
@@ -353,13 +353,9 @@ export class ToolRegistryFunctionCallRunner implements FunctionCallRunner {
 ### Wiring it together
 
 ```ts
-import { BaseAgentParticipant, AgenticEnvironment } from "@mozaik-ai/core"
+import { BaseAgent, AgenticEnvironment, OpenAIInferenceRunner } from "@mozaik-ai/core"
 
-const agent = new BaseAgentParticipant(
-	new HelloInputStream(),
-	new OpenAIInferenceRunner(),
-	new ToolRegistryFunctionCallRunner(tools),
-)
+const agent = new BaseAgent(new OpenAIInferenceRunner(), new ToolRegistryFunctionCallRunner(tools))
 
 agent.join(new AgenticEnvironment())
 ```

package/dist/index.d.mts

@@ -127,6 +127,11 @@ interface ReasoningEffort<Effort extends string> {
     getReasoningEffort(): Effort;
 }
 
+interface StreamingCapability {
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
+}
+
 interface FunctionTool {
     type: "function";
     name: string;
@@ -151,7 +156,7 @@ type ModelSpecification = {
     maxOutputTokens: number;
     supportFunctionCalling: boolean;
 };
-interface GenerativeModel extends ReasoningEffort<string>, ToolCallingCapability {
+interface GenerativeModel extends ReasoningEffort<string>, ToolCallingCapability, StreamingCapability {
     readonly specification: ModelSpecification;
 }
 
@@ -174,51 +179,9 @@ interface ModelContextRepository {
     getByProjectId(projectId: string): Promise<ModelContext[]>;
 }
 
-declare class InferenceRequest {
-    readonly model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
-    readonly context: ModelContext;
-    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext);
-}
-
-declare class InputTokenDetails {
-    readonly cached_tokens: number;
-    constructor(cached_tokens: number);
-}
-declare class OutputTokenDetails {
-    readonly reasoning_tokens: number;
-    constructor(reasoning_tokens: number);
-}
-declare class TokenUsage {
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly totalTokens: number;
-    readonly inputTokenDetails: InputTokenDetails;
-    readonly outputTokenDetails: OutputTokenDetails;
-    constructor(inputTokens: number, outputTokens: number, totalTokens: number, inputTokenDetails: InputTokenDetails, outputTokenDetails: OutputTokenDetails);
-}
-
-declare class InferenceResponse {
-    readonly contextItems: ContextItem[];
-    readonly tokenUsage?: TokenUsage;
-    constructor(contextItems: ContextItem[], tokenUsage: TokenUsage | undefined);
-}
-
-interface ModelRuntime {
-    infer(request: InferenceRequest): Promise<InferenceResponse>;
-}
-
-declare class OpenAIResponses implements ModelRuntime {
-    private readonly client;
-    constructor();
-    infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
-    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
-    mapContextToRequest(context: ModelContext): any[];
-    extractContextItems(response: any): ContextItem[];
-}
-
 type OpenAIReasoningEffortType = "xhigh" | "high" | "medium" | "low" | "none";
 
-declare class Gpt54Nano implements GenerativeModel, ReasoningEffort<OpenAIReasoningEffortType>, ToolCallingCapability {
+declare class Gpt54Nano implements GenerativeModel {
     readonly specification: {
         name: string;
         supportReasoningEffort: boolean;
@@ -230,13 +193,16 @@ declare class Gpt54Nano implements GenerativeModel, ReasoningEffort<OpenAIReason
     };
     private tools;
     private readonly effort;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
     setTools(tools: Tool[]): void;
     getTools(): Tool[];
     setReasoningEffort(effort: OpenAIReasoningEffortType): void;
     getReasoningEffort(): OpenAIReasoningEffortType;
 }
 
-declare class Gpt54 implements GenerativeModel, ReasoningEffort<OpenAIReasoningEffortType>, ToolCallingCapability {
+declare class Gpt54 implements GenerativeModel {
     readonly specification: {
         name: string;
         supportReasoningEffort: boolean;
@@ -247,6 +213,9 @@ declare class Gpt54 implements GenerativeModel, ReasoningEffort<OpenAIReasoningE
         supportFunctionCalling: boolean;
     };
     private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
     setTools(tools: Tool[]): void;
     getTools(): Tool[];
     private readonly effort;
@@ -254,7 +223,7 @@ declare class Gpt54 implements GenerativeModel, ReasoningEffort<OpenAIReasoningE
     getReasoningEffort(): OpenAIReasoningEffortType;
 }
 
-declare class Gpt54Mini implements GenerativeModel, ReasoningEffort<OpenAIReasoningEffortType>, ToolCallingCapability {
+declare class Gpt54Mini implements GenerativeModel {
     readonly specification: {
         name: string;
         supportReasoningEffort: boolean;
@@ -266,12 +235,32 @@ declare class Gpt54Mini implements GenerativeModel, ReasoningEffort<OpenAIReason
     };
     private tools;
     private readonly effort;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
     setReasoningEffort(effort: OpenAIReasoningEffortType): void;
     getReasoningEffort(): OpenAIReasoningEffortType;
     setTools(tools: Tool[]): void;
     getTools(): Tool[];
 }
 
+declare class InputTokenDetails {
+    readonly cached_tokens: number;
+    constructor(cached_tokens: number);
+}
+declare class OutputTokenDetails {
+    readonly reasoning_tokens: number;
+    constructor(reasoning_tokens: number);
+}
+declare class TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly inputTokenDetails: InputTokenDetails;
+    readonly outputTokenDetails: OutputTokenDetails;
+    constructor(inputTokens: number, outputTokens: number, totalTokens: number, inputTokenDetails: InputTokenDetails, outputTokenDetails: OutputTokenDetails);
+}
+
 declare class InMemoryModelContextRepository implements ModelContextRepository {
     private readonly store;
     private readonly projectIndex;
@@ -293,6 +282,13 @@ declare class SystemMessageItem extends ContextItem {
     }): SystemMessageItem;
 }
 
+declare class SemanticEvent<T> {
+    readonly type: string;
+    readonly data: T;
+    constructor(type: string, data: T);
+    getType(): string;
+}
+
 declare class AgenticEnvironment {
     protected subscribers: Participant[];
     private isActive;
@@ -303,6 +299,7 @@ declare class AgenticEnvironment {
     deliverReasoning(source: Participant, item: ReasoningItem): void;
     deliverFunctionCallOutput(source: Participant, item: FunctionCallOutputItem): void;
     deliverMessage(source: Participant, message: string): void;
+    deliverSemanticEvent(source: Participant, item: SemanticEvent<unknown>): void;
     start(): Promise<void>;
     stop(): void;
 }
@@ -326,35 +323,27 @@ declare abstract class Participant {
     abstract onModelMessage(item: ModelMessageItem): Promise<void> | void;
     abstract onExternalModelMessage(source: Participant, item: ModelMessageItem): Promise<void> | void;
     abstract onMessage(message: string): Promise<void> | void;
-}
-
-interface InputCapable {
-    streamInput(environment: AgenticEnvironment): Promise<void>;
-}
-interface InferenceCapable {
-    runInference(environment: AgenticEnvironment, context: ModelContext, model: GenerativeModel, signal?: AbortSignal): Promise<void>;
-}
-interface FunctionCallCapable {
-    executeFunctionCall(environment: AgenticEnvironment, functionCallItem: FunctionCallItem, signal?: AbortSignal): Promise<void>;
+    abstract onInternalEvent(item: SemanticEvent<unknown>): Promise<void> | void;
+    abstract onExternalEvent(source: Participant, item: SemanticEvent<unknown>): Promise<void> | void;
 }
 
 interface InferenceRunner {
-    run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem>;
+    run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>>;
 }
 
 interface FunctionCallRunner {
     run(functionCallItem: FunctionCallItem, signal?: AbortSignal): AsyncIterable<FunctionCallOutputItem>;
 }
 
-interface InputStream {
-    stream(signal?: AbortSignal): AsyncIterable<string>;
+declare abstract class Agent extends Participant {
+    abstract executeFunctionCall(environment: AgenticEnvironment, functionCallItem: FunctionCallItem, signal?: AbortSignal): Promise<void>;
+    abstract runInference(environment: AgenticEnvironment, context: ModelContext, model: GenerativeModel, signal?: AbortSignal): Promise<void>;
 }
 
-declare class BaseAgentParticipant extends Participant implements InputCapable, InferenceCapable, FunctionCallCapable {
-    private inputSource;
+declare class BaseAgent extends Agent {
     private inferenceRunner;
     private functionCallRunner;
-    constructor(inputSource: InputStream, inferenceRunner: InferenceRunner, functionCallRunner: FunctionCallRunner);
+    constructor(inferenceRunner: InferenceRunner, functionCallRunner: FunctionCallRunner);
     onJoined(): void;
     onLeft(): void;
     onParticipantJoined(participant: Participant): void;
@@ -368,14 +357,17 @@ declare class BaseAgentParticipant extends Participant implements InputCapable,
     onModelMessage(item: ModelMessageItem): void;
     onExternalModelMessage(source: Participant, item: ModelMessageItem): void;
     onMessage(message: string): void;
+    onInternalEvent(item: SemanticEvent<unknown>): void;
+    onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
     executeFunctionCall(environment: AgenticEnvironment, functionCallItem: FunctionCallItem, signal?: AbortSignal): Promise<void>;
     runInference(environment: AgenticEnvironment, context: ModelContext, model: GenerativeModel, signal?: AbortSignal): Promise<void>;
-    streamInput(environment: AgenticEnvironment): Promise<void>;
 }
 
-declare class BaseHumanParticipant extends Participant implements InputCapable {
-    private inputSource;
-    constructor(inputSource: InputStream);
+declare abstract class Human extends Participant {
+    sendMessage(environment: AgenticEnvironment, message: string): void;
+}
+
+declare class BaseHuman extends Human {
     onJoined(): void;
     onLeft(): void;
     onParticipantJoined(participant: Participant): void;
@@ -389,13 +381,16 @@ declare class BaseHumanParticipant extends Participant implements InputCapable {
     onExternalFunctionCallOutput(source: Participant, item: FunctionCallOutputItem): void;
     onExternalReasoning(source: Participant, item: ReasoningItem): void;
     onExternalModelMessage(source: Participant, item: ModelMessageItem): void;
-    streamInput(environment: AgenticEnvironment): Promise<void>;
+    onInternalEvent(item: SemanticEvent<unknown>): void;
+    onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
-type InferenceItem = ReasoningItem | FunctionCallItem | ModelMessageItem;
+type InferenceItem = ReasoningItem | FunctionCallItem | ModelMessageItem | SemanticEvent<unknown>;
 declare class OpenAIInferenceRunner implements InferenceRunner {
-    private readonly runtime;
     run(context: ModelContext, model: GenerativeModel, signal?: AbortSignal): AsyncIterable<InferenceItem>;
+    extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
+    mapContextToRequest(context: ModelContext): any[];
+    extractContextItems(response: any): ContextItem[];
 }
 
 declare class DefaultFunctionCallRunner implements FunctionCallRunner {
@@ -404,7 +399,7 @@ declare class DefaultFunctionCallRunner implements FunctionCallRunner {
     run(call: FunctionCallItem, signal?: AbortSignal): AsyncIterable<FunctionCallOutputItem>;
 }
 
-declare class Gpt55 implements GenerativeModel, ReasoningEffort<OpenAIReasoningEffortType>, ToolCallingCapability {
+declare class Gpt55 implements GenerativeModel {
     readonly specification: {
         name: string;
         supportReasoningEffort: boolean;
@@ -415,6 +410,9 @@ declare class Gpt55 implements GenerativeModel, ReasoningEffort<OpenAIReasoningE
         supportFunctionCalling: boolean;
     };
     private tools;
+    private streaming;
+    setStreaming(streaming: boolean): void;
+    getStreaming(): boolean;
     setTools(tools: Tool[]): void;
     getTools(): Tool[];
     private readonly effort;
@@ -422,7 +420,10 @@ declare class Gpt55 implements GenerativeModel, ReasoningEffort<OpenAIReasoningE
     getReasoningEffort(): OpenAIReasoningEffortType;
 }
 
-declare class BaseObserverParticipant extends Participant {
+declare abstract class Observer extends Participant {
+}
+
+declare class BaseObserver extends Observer {
     onFunctionCall(item: FunctionCallItem): void;
     onExternalFunctionCall(source: Participant, item: FunctionCallItem): void;
     onFunctionCallOutput(item: FunctionCallOutputItem): void;
@@ -436,6 +437,8 @@ declare class BaseObserverParticipant extends Participant {
     onLeft(): void;
     onParticipantJoined(participant: Participant): void;
     onParticipantLeft(participant: Participant): void;
+    onInternalEvent(item: SemanticEvent<unknown>): void;
+    onExternalEvent(source: Participant, item: SemanticEvent<unknown>): void;
 }
 
-export { AgenticEnvironment, BaseAgentParticipant, BaseHumanParticipant, BaseObserverParticipant, ContextItem, DefaultFunctionCallRunner, DeveloperMessageItem, FunctionCallItem, FunctionCallOutputItem, type FunctionCallRunner, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, Gpt55, InMemoryModelContextRepository, InferenceRequest, InferenceResponse, type InferenceRunner, type InputStream, InputTokenDetails, ModelContext, type ModelContextRepository, ModelMessageItem, OpenAIInferenceRunner, OpenAIResponses, OutputTokenDetails, Participant, ReasoningItem, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };
+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, SystemMessageItem, TokenUsage, type Tool, UserMessageItem };