@mozaik-ai/core 3.1.3 → 3.2.0

package/README.md

@@ -154,9 +154,9 @@ Use `InferenceVisitor` for concerns that should stay separate from agent logic:
 
 ---
 
-### Context Model
+### Model Context
 
-`Context` is the structured input passed to the model. It is composed of ordered **`ContextItem`** objects — each representing a single unit of context.
+`ModelContext` is the structured input passed to the model. It is composed of ordered **`ContextItem`** objects — each representing a single unit of context.
 
 **Client-provided items** (you add these):
 
@@ -171,26 +171,26 @@ Use `InferenceVisitor` for concerns that should stay separate from agent logic:
 - `Reasoning` — the model's internal reasoning trace
 
 ```ts
-import { Context, DeveloperMessage, UserMessage, InMemoryContextRepository } from "@mozaik-ai/core"
+import { ModelContext, DeveloperMessage, UserMessage, InMemoryContextRepository } from "@mozaik-ai/core"
 
-const context = Context.create("project-id")
+const context = ModelContext.create("project-id")
 	.addItem(DeveloperMessage.create("You are a helpful assistant."))
 	.addItem(UserMessage.create("What is the capital of France?"))
 
-const repo = new InMemoryContextRepository()
+const repo = new InMemoryModelContextRepository()
 await repo.save(context)
 
 // later...
 const restored = await repo.getByProjectId("project-id")
 ```
 
-Context can be persisted and restored via `ContextRepository`. The built-in `InMemoryContextRepository` is suitable for development; implement `ContextRepository` to connect any storage backend.
+ModelContext can be persisted and restored via `ModelContextRepository`. The built-in `InMemoryModelContextRepository` is suitable for development; implement `ModelContextRepository` to connect any storage backend.
 
 ---
 
 ### OpenResponses
 
-`OpenAIResponses` is the framework's inference provider. It implements the **OpenResponses** specification ([openresponses.org](https://www.openresponses.org/)), mapping Mozaik's typed `Context` to the OpenAI Responses API and back.
+`OpenAIResponses` is the framework's inference provider. It implements the **OpenResponses** specification ([openresponses.org](https://www.openresponses.org/)), mapping Mozaik's typed `ModelContext` to the OpenAI Responses API and back.
 
 It is the default provider used by `AgentRuntime` and handles:
 
@@ -239,7 +239,7 @@ society.enter("Analyze the impact of AI on software development", model, context
 society.stop()
 ```
 
-All agents receive the same `Context`, enabling **collaborative context building** — each agent's output is visible to others through the shared context as the execution progresses.
+All agents receive the same `ModelContext`, enabling **collaborative context building** — each agent's output is visible to others through the shared context as the execution progresses.
 
 > **Experimental:** `AgentSociety` is in active development. The API is stable enough to build on, but expect refinements — particularly around context isolation, coordination primitives, and agent-to-agent messaging. Feedback and contributions are welcome.
 
@@ -254,10 +254,10 @@ import {
 	Agent,
 	AgentRuntime,
 	HookId,
-	Context,
+	ModelContext,
 	DeveloperMessage,
 	Gpt54Mini,
-	InMemoryContextRepository,
+	InMemoryModelContextRepository,
 	Tool,
 } from "@mozaik-ai/core"
 
@@ -289,9 +289,9 @@ const agent = new Agent(runtime)
 
 // Set up model and context
 const model = new Gpt54Mini([weatherTool])
-const context = Context.create("demo").addItem(DeveloperMessage.create("You are a weather assistant."))
+const context = ModelContext.create("demo").addItem(DeveloperMessage.create("You are a weather assistant."))
 
-const repo = new InMemoryContextRepository()
+const repo = new InMemoryModelContextRepository()
 await repo.save(context)
 
 // Run

package/dist/index.d.mts

@@ -6,20 +6,21 @@ declare abstract class ContextItem {
     abstract toJSON(): any;
 }
 
-declare class Context {
+declare class ModelContext {
     readonly id: string;
     readonly projectId: string;
     readonly items: ContextItem[];
     constructor(id: string, projectId: string, items: ContextItem[]);
-    addItem(item: ContextItem): Context;
-    applyModelOutput(items: ContextItem[]): Context;
+    addItem(item: ContextItem): ModelContext;
+    applyModelOutput(items: ContextItem[]): ModelContext;
     getItems(): ContextItem[];
-    static create(projectId: string): Context;
+    getLastItem(): ContextItem;
+    static create(projectId: string): ModelContext;
     static rehydrate(data: {
         id: string;
         projectId: string;
         items: ContextItem[];
-    }): Context;
+    }): ModelContext;
     toJSON(): any;
 }
 
@@ -147,10 +148,10 @@ declare class FunctionCallOutput extends ContextItem {
     toJSON(): any;
 }
 
-interface ContextRepository {
-    save(context: Context): Promise<void>;
-    get(id: string): Promise<Context>;
-    getByProjectId(projectId: string): Promise<Context[]>;
+interface ModelContextRepository {
+    save(context: ModelContext): Promise<void>;
+    get(id: string): Promise<ModelContext>;
+    getByProjectId(projectId: string): Promise<ModelContext[]>;
 }
 
 interface ReasoningEffort<Effort extends string> {
@@ -175,8 +176,8 @@ interface ToolCallingCapability {
 
 declare class InferenceRequest {
     readonly model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
-    readonly context: Context;
-    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context);
+    readonly context: ModelContext;
+    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext);
 }
 
 declare class InputTokenDetails {
@@ -211,7 +212,7 @@ declare class OpenAIResponses implements ModelRuntime {
     constructor();
     infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
     extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
-    mapContextToRequest(context: Context): any[];
+    mapContextToRequest(context: ModelContext): any[];
     extractContextItems(response: any): ContextItem[];
 }
 
@@ -271,17 +272,17 @@ declare class Gpt54Mini implements GenerativeModel, ReasoningEffort<OpenAIReason
     getTools(): Tool[];
 }
 
-interface Condition<T> {
+interface Specification<T> {
     isSatisfiedBy(candidate: T): boolean;
-    and(other: Condition<T>): Condition<T>;
-    or(other: Condition<T>): Condition<T>;
-    not(): Condition<T>;
+    and(other: Specification<T>): Specification<T>;
+    or(other: Specification<T>): Specification<T>;
+    not(): Specification<T>;
 }
-declare abstract class BaseCondition<T> implements Condition<T> {
+declare abstract class BaseSpecification<T> implements Specification<T> {
     abstract isSatisfiedBy(candidate: T): boolean;
-    and(other: Condition<T>): Condition<T>;
-    or(other: Condition<T>): Condition<T>;
-    not(): Condition<T>;
+    and(other: Specification<T>): Specification<T>;
+    or(other: Specification<T>): Specification<T>;
+    not(): Specification<T>;
 }
 
 interface Action<T> {
@@ -291,35 +292,35 @@ interface AsyncAction<T> {
     apply(candidate: T): Promise<T>;
 }
 interface AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
     apply(candidate: T): Promise<T>;
 }
 declare class If<T> implements AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
-    constructor({ condition, action }: {
-        condition: Condition<T>;
+    constructor({ specification, action }: {
+        specification: Specification<T>;
         action: AsyncAction<T>;
     });
     apply(candidate: T): Promise<T>;
 }
 declare class Loop<T> implements AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
-    constructor({ condition, action }: {
-        condition: Condition<T>;
+    constructor({ specification, action }: {
+        specification: Specification<T>;
         action: AsyncAction<T>;
     });
     apply(candidate: T): Promise<T>;
 }
 
-declare class InMemoryContextRepository implements ContextRepository {
+declare class InMemoryModelContextRepository implements ModelContextRepository {
     private readonly store;
     private readonly projectIndex;
-    save(context: Context): Promise<void>;
-    get(id: string): Promise<Context>;
-    getByProjectId(projectId: string): Promise<Context[]>;
+    save(context: ModelContext): Promise<void>;
+    get(id: string): Promise<ModelContext>;
+    getByProjectId(projectId: string): Promise<ModelContext[]>;
     private clone;
 }
 
@@ -370,10 +371,8 @@ interface RuntimeContext {
     userMessage: UserMessage;
     inferenceRequest?: InferenceRequest;
     model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
-    context: Context;
+    context: ModelContext;
     inferenceResponse?: InferenceResponse;
-    functionCallOutput?: FunctionCallOutput;
-    modelMessage?: ModelMessage;
     error?: Error;
 }
 
@@ -381,12 +380,12 @@ declare class AgentRuntime {
     private hooksRegistry;
     private stateHandlerRegistry;
     constructor();
-    onInferencePending(context: RuntimeContext): Promise<void>;
-    onFunctionCallPending(context: RuntimeContext): Promise<void>;
+    onInferencePending(runtimeContext: RuntimeContext): Promise<void>;
+    onFunctionCallPending(runtimeContext: RuntimeContext): Promise<void>;
     onError(context: RuntimeContext): Promise<void>;
     onModelMessageReceived(context: RuntimeContext): Promise<void>;
     on(hookId: HookId, callback: (data: any) => Promise<void>): Promise<void>;
-    start(userMessage: UserMessage, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): Promise<void>;
+    start(userMessage: UserMessage, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): Promise<void>;
 }
 
 interface InferenceVisitor {
@@ -394,9 +393,15 @@ interface InferenceVisitor {
     afterInference(inferenceResponse: InferenceResponse): Promise<void>;
 }
 
+interface FunctionCallVisitor {
+    beforeFunctionCall(context: RuntimeContext): Promise<void>;
+    afterFunctionCall(context: RuntimeContext): Promise<void>;
+}
+
 declare class Agent {
     private readonly runtime;
     private visitor;
+    private functionCallVisitor;
     constructor(runtime: AgentRuntime);
     beforeInference(context: RuntimeContext): Promise<void>;
     afterInference(context: RuntimeContext): Promise<void>;
@@ -407,7 +412,8 @@ declare class Agent {
     onError(context: RuntimeContext): Promise<void>;
     onStart(context: RuntimeContext): Promise<void>;
     setInferenceVisitor(visitor: InferenceVisitor): void;
-    run(userMessage: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): Promise<void>;
+    setFunctionCallVisitor(visitor: FunctionCallVisitor): void;
+    run(userMessage: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): Promise<void>;
 }
 
 declare class AgentSociety {
@@ -416,9 +422,9 @@ declare class AgentSociety {
     private isActive;
     constructor(name: string);
     join(agent: Agent): void;
-    enter(messageText: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): void;
+    enter(messageText: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): void;
     start(): Promise<void>;
     stop(): void;
 }
 
-export { type Action, Agent, AgentRuntime, AgentSociety, type AsyncAction, type AsyncRule, BaseCondition, type Condition, Context, ContextItem, type ContextRepository, DeveloperMessage, FunctionCall, FunctionCallOutput, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, If, InMemoryContextRepository, InferenceRequest, InferenceResponse, type InferenceVisitor, InputTokenDetails, Loop, ModelMessage, OpenAIResponses, OutputTokenDetails, Reasoning, TokenUsage, type Tool, UserMessage };
+export { type Action, Agent, AgentRuntime, AgentSociety, type AsyncAction, type AsyncRule, BaseSpecification, ContextItem, DeveloperMessage, FunctionCall, FunctionCallOutput, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, If, InMemoryModelContextRepository, InferenceRequest, InferenceResponse, type InferenceVisitor, InputTokenDetails, Loop, ModelContext, type ModelContextRepository, ModelMessage, OpenAIResponses, OutputTokenDetails, Reasoning, type Specification, TokenUsage, type Tool, UserMessage };

package/dist/index.d.ts

@@ -6,20 +6,21 @@ declare abstract class ContextItem {
     abstract toJSON(): any;
 }
 
-declare class Context {
+declare class ModelContext {
     readonly id: string;
     readonly projectId: string;
     readonly items: ContextItem[];
     constructor(id: string, projectId: string, items: ContextItem[]);
-    addItem(item: ContextItem): Context;
-    applyModelOutput(items: ContextItem[]): Context;
+    addItem(item: ContextItem): ModelContext;
+    applyModelOutput(items: ContextItem[]): ModelContext;
     getItems(): ContextItem[];
-    static create(projectId: string): Context;
+    getLastItem(): ContextItem;
+    static create(projectId: string): ModelContext;
     static rehydrate(data: {
         id: string;
         projectId: string;
         items: ContextItem[];
-    }): Context;
+    }): ModelContext;
     toJSON(): any;
 }
 
@@ -147,10 +148,10 @@ declare class FunctionCallOutput extends ContextItem {
     toJSON(): any;
 }
 
-interface ContextRepository {
-    save(context: Context): Promise<void>;
-    get(id: string): Promise<Context>;
-    getByProjectId(projectId: string): Promise<Context[]>;
+interface ModelContextRepository {
+    save(context: ModelContext): Promise<void>;
+    get(id: string): Promise<ModelContext>;
+    getByProjectId(projectId: string): Promise<ModelContext[]>;
 }
 
 interface ReasoningEffort<Effort extends string> {
@@ -175,8 +176,8 @@ interface ToolCallingCapability {
 
 declare class InferenceRequest {
     readonly model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
-    readonly context: Context;
-    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context);
+    readonly context: ModelContext;
+    constructor(model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext);
 }
 
 declare class InputTokenDetails {
@@ -211,7 +212,7 @@ declare class OpenAIResponses implements ModelRuntime {
     constructor();
     infer(inferenceRequest: InferenceRequest): Promise<InferenceResponse>;
     extractTokenUsage(response: OpenAI.Responses.Response): TokenUsage | undefined;
-    mapContextToRequest(context: Context): any[];
+    mapContextToRequest(context: ModelContext): any[];
     extractContextItems(response: any): ContextItem[];
 }
 
@@ -271,17 +272,17 @@ declare class Gpt54Mini implements GenerativeModel, ReasoningEffort<OpenAIReason
     getTools(): Tool[];
 }
 
-interface Condition<T> {
+interface Specification<T> {
     isSatisfiedBy(candidate: T): boolean;
-    and(other: Condition<T>): Condition<T>;
-    or(other: Condition<T>): Condition<T>;
-    not(): Condition<T>;
+    and(other: Specification<T>): Specification<T>;
+    or(other: Specification<T>): Specification<T>;
+    not(): Specification<T>;
 }
-declare abstract class BaseCondition<T> implements Condition<T> {
+declare abstract class BaseSpecification<T> implements Specification<T> {
     abstract isSatisfiedBy(candidate: T): boolean;
-    and(other: Condition<T>): Condition<T>;
-    or(other: Condition<T>): Condition<T>;
-    not(): Condition<T>;
+    and(other: Specification<T>): Specification<T>;
+    or(other: Specification<T>): Specification<T>;
+    not(): Specification<T>;
 }
 
 interface Action<T> {
@@ -291,35 +292,35 @@ interface AsyncAction<T> {
     apply(candidate: T): Promise<T>;
 }
 interface AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
     apply(candidate: T): Promise<T>;
 }
 declare class If<T> implements AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
-    constructor({ condition, action }: {
-        condition: Condition<T>;
+    constructor({ specification, action }: {
+        specification: Specification<T>;
         action: AsyncAction<T>;
     });
     apply(candidate: T): Promise<T>;
 }
 declare class Loop<T> implements AsyncRule<T> {
-    condition: Condition<T>;
+    specification: Specification<T>;
     action: AsyncAction<T>;
-    constructor({ condition, action }: {
-        condition: Condition<T>;
+    constructor({ specification, action }: {
+        specification: Specification<T>;
         action: AsyncAction<T>;
     });
     apply(candidate: T): Promise<T>;
 }
 
-declare class InMemoryContextRepository implements ContextRepository {
+declare class InMemoryModelContextRepository implements ModelContextRepository {
     private readonly store;
     private readonly projectIndex;
-    save(context: Context): Promise<void>;
-    get(id: string): Promise<Context>;
-    getByProjectId(projectId: string): Promise<Context[]>;
+    save(context: ModelContext): Promise<void>;
+    get(id: string): Promise<ModelContext>;
+    getByProjectId(projectId: string): Promise<ModelContext[]>;
     private clone;
 }
 
@@ -370,10 +371,8 @@ interface RuntimeContext {
     userMessage: UserMessage;
     inferenceRequest?: InferenceRequest;
     model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability;
-    context: Context;
+    context: ModelContext;
     inferenceResponse?: InferenceResponse;
-    functionCallOutput?: FunctionCallOutput;
-    modelMessage?: ModelMessage;
     error?: Error;
 }
 
@@ -381,12 +380,12 @@ declare class AgentRuntime {
     private hooksRegistry;
     private stateHandlerRegistry;
     constructor();
-    onInferencePending(context: RuntimeContext): Promise<void>;
-    onFunctionCallPending(context: RuntimeContext): Promise<void>;
+    onInferencePending(runtimeContext: RuntimeContext): Promise<void>;
+    onFunctionCallPending(runtimeContext: RuntimeContext): Promise<void>;
     onError(context: RuntimeContext): Promise<void>;
     onModelMessageReceived(context: RuntimeContext): Promise<void>;
     on(hookId: HookId, callback: (data: any) => Promise<void>): Promise<void>;
-    start(userMessage: UserMessage, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): Promise<void>;
+    start(userMessage: UserMessage, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): Promise<void>;
 }
 
 interface InferenceVisitor {
@@ -394,9 +393,15 @@ interface InferenceVisitor {
     afterInference(inferenceResponse: InferenceResponse): Promise<void>;
 }
 
+interface FunctionCallVisitor {
+    beforeFunctionCall(context: RuntimeContext): Promise<void>;
+    afterFunctionCall(context: RuntimeContext): Promise<void>;
+}
+
 declare class Agent {
     private readonly runtime;
     private visitor;
+    private functionCallVisitor;
     constructor(runtime: AgentRuntime);
     beforeInference(context: RuntimeContext): Promise<void>;
     afterInference(context: RuntimeContext): Promise<void>;
@@ -407,7 +412,8 @@ declare class Agent {
     onError(context: RuntimeContext): Promise<void>;
     onStart(context: RuntimeContext): Promise<void>;
     setInferenceVisitor(visitor: InferenceVisitor): void;
-    run(userMessage: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): Promise<void>;
+    setFunctionCallVisitor(visitor: FunctionCallVisitor): void;
+    run(userMessage: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): Promise<void>;
 }
 
 declare class AgentSociety {
@@ -416,9 +422,9 @@ declare class AgentSociety {
     private isActive;
     constructor(name: string);
     join(agent: Agent): void;
-    enter(messageText: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: Context): void;
+    enter(messageText: string, model: GenerativeModel & ReasoningEffort<string> & ToolCallingCapability, context: ModelContext): void;
     start(): Promise<void>;
     stop(): void;
 }
 
-export { type Action, Agent, AgentRuntime, AgentSociety, type AsyncAction, type AsyncRule, BaseCondition, type Condition, Context, ContextItem, type ContextRepository, DeveloperMessage, FunctionCall, FunctionCallOutput, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, If, InMemoryContextRepository, InferenceRequest, InferenceResponse, type InferenceVisitor, InputTokenDetails, Loop, ModelMessage, OpenAIResponses, OutputTokenDetails, Reasoning, TokenUsage, type Tool, UserMessage };
+export { type Action, Agent, AgentRuntime, AgentSociety, type AsyncAction, type AsyncRule, BaseSpecification, ContextItem, DeveloperMessage, FunctionCall, FunctionCallOutput, type GenerativeModel, Gpt54, Gpt54Mini, Gpt54Nano, If, InMemoryModelContextRepository, InferenceRequest, InferenceResponse, type InferenceVisitor, InputTokenDetails, Loop, ModelContext, type ModelContextRepository, ModelMessage, OpenAIResponses, OutputTokenDetails, Reasoning, type Specification, TokenUsage, type Tool, UserMessage };