@mozaik-ai/core 3.8.3 → 3.8.5

package/README.md

@@ -1,6 +1,6 @@
 # Mozaik
 
-**Mozaik** is an open-source TypeScript framework for building reactive AI agents that share an **agentic environment** instead of being orchestrated through rigid workflows.
+**Mozaik** is TypeScript framework for building reactive agents. It provides the easiest way to build collaborative, **event-driven agents** that can work together in parallel.
 
 ![npm downloads](https://img.shields.io/npm/dt/@mozaik-ai/core) ![npm downloads weekly](https://img.shields.io/npm/dw/@mozaik-ai/core) ![npm version](https://img.shields.io/npm/v/@mozaik-ai/core)
 
@@ -25,17 +25,21 @@ OPENAI_API_KEY=your-openai-key-here
 
 ## The agentic environment
 
-`AgenticEnvironment` is a broadcast bus for typed events. `Participant`s `join()` it, and anything produced by one participant is delivered to every subscriber through a **dedicated typed callback** — one per event kind, with separate handlers for items the participant emitted itself versus items emitted by someone else:
+`AgenticEnvironment` is where everything happens. `Participant`s `join()` it, and from that moment on they can **listen to messages and events** flowing through the environment by overriding any of the handlers below:
 
-| Producer call                             | Self handler           | External handler                          |
-| ----------------------------------------- | ---------------------- | ----------------------------------------- |
-| `deliverFunctionCall(source, item)`       | `onFunctionCall`       | `onExternalFunctionCall(source, …)`       |
-| `deliverFunctionCallOutput(source, item)` | `onFunctionCallOutput` | `onExternalFunctionCallOutput(source, …)` |
-| `deliverReasoning(source, item)`          | `onReasoning`          | `onExternalReasoning(source, …)`          |
-| `deliverModelMessage(source, item)`       | `onModelMessage`       | `onExternalModelMessage(source, …)`       |
-| `deliverMessage(source, message)`         | _(not delivered)_      | `onMessage(message)`                      |
+| Handler                        | Triggered when…                                        |
+| ------------------------------ | ------------------------------------------------------ |
+| `onMessage`                    | any participant sends a message                        |
+| `onFunctionCall`               | its own inference returns a function call              |
+| `onExternalFunctionCall`       | another agent's inference returns a function call      |
+| `onFunctionCallOutput`         | its own function call runner returns a result          |
+| `onExternalFunctionCallOutput` | another agent's function call runner returns a result  |
+| `onReasoning`                  | its own inference returns a reasoning item             |
+| `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 |
 
-Messages are plain `string`s exchanged between participants. Every other event flows as a typed `ContextItem` (`FunctionCallItem`, `FunctionCallOutputItem`, `ReasoningItem`, `ModelMessageItem`).
+Every handler defaults to a no-op — override only the ones you care about.
 
 ```mermaid
 flowchart LR
@@ -89,58 +93,7 @@ The environment fans every item out to every subscriber synchronously and withou
 
 ---
 
-## Intercepting events from other participants
-
-Instead of a single catch-all callback, `Participant` exposes **one typed handler per event kind**, with a clear split between events the participant emitted itself and events emitted by someone else. A participant can:
-
-- **Observe** events from other participants via the `onExternal*` family (telemetry, audit, UI streaming) and `onMessage` for plain-text messages.
-- **React** to its own outputs via the self handlers (e.g. execute a `FunctionCallItem` it just produced), or to others' outputs via the external handlers.
-- **Ignore** events it doesn't care about — every handler defaults to a no-op in the bundled participants.
-
-The typed `ContextItem`s involved are defined in [src/domain/model-context/context-item](src/domain/model-context/context-item):
-
-- Client-produced: `FunctionCallOutputItem` (and `UserMessageItem` / `DeveloperMessageItem` / `SystemMessageItem` when building a `ModelContext` directly)
-- Model-produced: `ModelMessageItem`, `FunctionCallItem`, `ReasoningItem`
-
-Plain conversational input flows as a `string` through `onMessage` — participants exchange messages without committing to a specific `ContextItem` shape on the wire.
-
-### Passive observer
-
-A passive observer subclasses `Participant` and overrides only the handlers it cares about:
-
-```ts
-import { Participant, FunctionCallItem, FunctionCallOutputItem, ReasoningItem, ModelMessageItem } from "@mozaik-ai/core"
-
-export class TranscriptLogger extends Participant {
-	async onMessage(message: string): Promise<void> {
-		console.log("[message]", message)
-	}
-
-	async onExternalFunctionCall(source: Participant, item: FunctionCallItem): Promise<void> {
-		console.log(`[${source.constructor.name}] function_call`, item.toJSON())
-	}
-
-	async onExternalFunctionCallOutput(source: Participant, item: FunctionCallOutputItem): Promise<void> {
-		console.log(`[${source.constructor.name}] function_call_output`, item.toJSON())
-	}
-
-	async onExternalReasoning(source: Participant, item: ReasoningItem): Promise<void> {
-		console.log(`[${source.constructor.name}] reasoning`, item.toJSON())
-	}
-
-	async onExternalModelMessage(source: Participant, item: ModelMessageItem): Promise<void> {
-		console.log(`[${source.constructor.name}] model_message`, item.toJSON())
-	}
-
-	// Self-emitted handlers (onFunctionCall, onReasoning, …) can be no-ops for a pure observer.
-	async onFunctionCall(): Promise<void> {}
-	async onFunctionCallOutput(): Promise<void> {}
-	async onReasoning(): Promise<void> {}
-	async onModelMessage(): Promise<void> {}
-}
-```
-
-### Reactive agent
+## 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:
 
@@ -207,6 +160,47 @@ Three things to note:
 
 ---
 
+## Reacting to external events
+
+Participants can listen to external events and react by overriding methods like `onMessage`, `onExternalFunctionCall`, `onExternalFunctionCallOutput`, `onExternalReasoning`, and `onExternalModelMessage`.
+
+## Passive observer
+
+You can create observers that don't run inference themselves but watch what's happening in the conversation and take side actions (logging, metrics, persistence, etc.). Subclass `Participant` and override only the handlers you care about:
+
+```ts
+import { Participant, FunctionCallItem, FunctionCallOutputItem, ReasoningItem, ModelMessageItem } from "@mozaik-ai/core"
+
+export class TranscriptLogger extends Participant {
+	async onMessage(message: string): Promise<void> {
+		console.log("[message]", message)
+	}
+
+	async onExternalFunctionCall(source: Participant, item: FunctionCallItem): Promise<void> {
+		console.log(`[${source.constructor.name}] function_call`, item.toJSON())
+	}
+
+	async onExternalFunctionCallOutput(source: Participant, item: FunctionCallOutputItem): Promise<void> {
+		console.log(`[${source.constructor.name}] function_call_output`, item.toJSON())
+	}
+
+	async onExternalReasoning(source: Participant, item: ReasoningItem): Promise<void> {
+		console.log(`[${source.constructor.name}] reasoning`, item.toJSON())
+	}
+
+	async onExternalModelMessage(source: Participant, item: ModelMessageItem): Promise<void> {
+		console.log(`[${source.constructor.name}] model_message`, item.toJSON())
+	}
+
+	// Self-emitted handlers (onFunctionCall, onReasoning, …) can be no-ops for a pure observer.
+	async onFunctionCall(): Promise<void> {}
+	async onFunctionCallOutput(): Promise<void> {}
+	async onReasoning(): Promise<void> {}
+	async onModelMessage(): Promise<void> {}
+}
+```
+---
+
 ## Context and models (reference)
 
 `ModelContext` is the ordered list of `ContextItem`s a `GenerativeModel` is asked to reason over. It is constructed and mutated explicitly — typically inside a participant in response to delivered items.
@@ -235,51 +229,28 @@ const response = await runtime.infer(new InferenceRequest(new Gpt54(), context))
 
 ---
 
-## Advanced: overriding generators
+## Overriding Generators
 
-`BaseAgentParticipant` and `BaseHumanParticipant` are deliberately thin shells around three generator interfaces. Swap any of them to change _how_ events are produced without touching the environment, the participants, or any consumers.
+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`
 
-An `InputStream` is the minimal text-source contract a participant uses to feed messages into the environment:
-
-```ts
-export interface InputStream {
-	stream(signal?: AbortSignal): AsyncIterable<string>
-}
-```
-
-Each yielded string is delivered to every other participant through `onMessage(message: string)`. This keeps the wire format dead simple: participants exchange text, and each one decides how to turn that text into a `ContextItem` for its own `ModelContext`.
-
 ```ts
 import { InputStream } from "@mozaik-ai/core"
 
-export class QueueInputStream implements InputStream {
-	private readonly queue: string[] = []
-	private resolveNext?: () => void
-
-	push(message: string) {
-		this.queue.push(message)
-		this.resolveNext?.()
-		this.resolveNext = undefined
-	}
-
-	async *stream(signal?: AbortSignal): AsyncIterable<string> {
-		while (!signal?.aborted) {
-			while (this.queue.length > 0) {
-				yield this.queue.shift()!
-			}
-			await new Promise<void>((resolve) => (this.resolveNext = resolve))
-		}
+export class HelloInputStream implements InputStream {
+	async *stream(): AsyncIterable<string> {
+		yield "Hello"
+		yield "World"
 	}
 }
 ```
 
-Use it for stdin, websockets, an HTTP queue, or anything that produces text over time. A reactive agent typically wraps the incoming string in a `UserMessageItem` inside `onMessage` before adding it to its `ModelContext` — see the [Reactive agent](#reactive-agent) example above.
+Each yielded string is delivered to other participants through `onMessage(message: string)`.
 
 ### Custom `InferenceRunner`
 
-Wrap any model runtime — including `OpenAIResponses` — and decide how its output becomes a stream of items. Here we expand a single `InferenceResponse` into per-item delivery:
+An `InferenceRunner` can yield `ReasoningItem`, `FunctionCallItem`, and `ModelMessageItem`.
 
 ```ts
 import {
@@ -307,11 +278,9 @@ export class OpenAIInferenceRunner implements InferenceRunner {
 }
 ```
 
-Replace the body with a streaming runtime and items will flow into the environment as soon as the model produces them.
-
 ### Custom `FunctionCallRunner`
 
-Resolve a `FunctionCallItem` against a tool registry and yield its output:
+A `FunctionCallRunner` can only produce `FunctionCallOutputItem`.
 
 ```ts
 import { FunctionCallRunner, FunctionCallItem, FunctionCallOutputItem, Tool } from "@mozaik-ai/core"
@@ -335,7 +304,7 @@ export class ToolRegistryFunctionCallRunner implements FunctionCallRunner {
 import { BaseAgentParticipant, AgenticEnvironment } from "@mozaik-ai/core"
 
 const agent = new BaseAgentParticipant(
-	new QueueInputStream(),
+	new HelloInputStream(),
 	new OpenAIInferenceRunner(),
 	new ToolRegistryFunctionCallRunner(tools),
 )
@@ -343,8 +312,6 @@ const agent = new BaseAgentParticipant(
 agent.join(new AgenticEnvironment())
 ```
 
-You now own input, inference, and tool execution end-to-end while keeping the same `Participant` contract — and any other participant in the environment can still observe and react to everything the agent emits.
-
 ---
 
 ## Made with Mozaik

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mozaik-ai/core",
-	"version": "3.8.3",
+	"version": "3.8.5",
 	"description": "A TypeScript framework for building reactive agents",
 	"main": "dist/index.js",
 	"module": "dist/index.mjs",