@mozaik-ai/core 0.9.4 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Mozaik
 
-Mozaik is a TypeScript library for orchestrating AI agents, supporting both manually defined and AI-generated workflows.
+Mozaik is a TypeScript library for orchestrating AI agents.
 
 ![mozaik](https://github.com/user-attachments/assets/0fdc15a8-3778-4d0e-bd13-143d04090b9e)
 
@@ -19,252 +19,89 @@ Make sure to set your API keys in a `.env` file at the root of your project:
 ```env
 # For OpenAI
 OPENAI_API_KEY=your-openai-key-here
-
-# For Anthropic Claude
-ANTHROPIC_API_KEY=your-anthropic-key-here
-```
-
-## Supported Models
-
-The system supports OpenAI models (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.1) and Anthropic Claude models (Claude Sonnet, Haiku, and Opus 4.5) out of the box.
-
----
-
-## Features
-
-### AI MozaikAgents
-
-This feature lets developers create AI agents through a single unified request definition, making it easy to compose tasks and leverage multiple models. You can mix providers, choose the best model for each task, and build agents that work across different capabilities.
-
-```typescript
-import "dotenv/config"
-import { MozaikAgent, MozaikRequest } from "@mozaik-ai/core"
-
-const request: MozaikRequest = {
-	model: "claude-sonnet-4.5",
-}
-
-const agent = new MozaikAgent(request)
-const codingResponse = await agent.act("Write a React component for a todo list")
-```
-
-### Structured Output
-
-Structured output lets you enforce exact response formats—using schemas like Zod—so AI returns predictable, validated data every time.
-
-```typescript
-import { z } from "zod"
-import { MozaikAgent, MozaikRequest } from "@mozaik-ai/core"
-
-const mealPlanSchema = z.object({
-	calories: z.number(),
-	meals: z
-		.array(
-			z.object({
-				name: z.string(),
-				description: z.string(),
-				ingredients: z.array(z.string()).min(3),
-			}),
-		)
-		.length(3),
-	shoppingList: z.array(z.string()),
-})
-
-const request: MozaikRequest = {
-	model: "gpt-5-mini",
-	task: "Create a 1-day vegetarian meal plan with breakfast, lunch, and dinner.",
-	structuredOutput: mealPlanSchema,
-}
-
-const agent = new MozaikAgent(request)
-const response = await agent.act()
 ```
 
-### Multi-turn Conversation
+## Context Runtime (Overview)
 
-Multi-turn conversation allows developers to provide chat history so the AI agent can maintain context and generate more relevant, continuous responses.
+The **Context Runtime** models the core behavior of a language model:
 
-```typescript
-import { MozaikAgent, MozaikRequest } from "@mozaik-ai/core"
+> Given a structured **context**, produce a **response**.
 
-const request: MozaikRequest = {
-	messages: [
-		{ role: "system", content: "You are a coding assistant" },
-		{ role: "user", content: "How do I sort an array in TypeScript?" },
-		{ role: "assistant", content: "You can use the .sort() method..." },
-	],
-	model: "claude-haiku-4.5",
-}
-
-const agent = new MozaikAgent(request)
-const response = await agent.act("Can you show me an example?")
-```
-
-### Tool Calling
-
-Tool calling allows the agent to invoke real functions in your environment—letting it perform actual actions (like writing files, calling APIs, or modifying state) instead of merely generating text.
-
-```typescript
-import { promises as fs } from "fs"
-import { MozaikAgent, MozaikRequest, Tool } from "@mozaik-ai/core"
-
-const tools: Tool[] = [
-	{
-		name: "write_file",
-		description: "Write text to a file.",
-		schema: {
-			type: "object",
-			properties: {
-				filename: { type: "string" },
-				content: { type: "string" },
-			},
-			required: ["filename", "content"],
-		},
-		async invoke({ filename, content }) {
-			await fs.writeFile(filename, content, "utf8")
-			return { ok: true }
-		},
-	},
-]
-
-const request: MozaikRequest = {
-	model: "gpt-5.1",
-	tools,
-	messages: [
-		{
-			role: "system",
-			content: "Save notes to disk using the tool, then confirm where the file was written.",
-		},
-	],
-	task: "Create a two-bullet trip prep checklist for Belgrade and save it as trip-checklist.txt.",
-}
-
-const agent = new MozaikAgent(request)
-await agent.act()
-```
+It abstracts away vendor-specific APIs (e.g. OpenAI) and provides a domain-centric interface for working with LLMs.
 
-### Vision
-
-Vision support allows AI agents to interpret images alongside text, enabling richer understanding and multimodal interactions.
-
-```typescript
-import { MozaikAgent, MozaikRequest } from "@mozaik-ai/core"
-
-const request: MozaikRequest = {
-	messages: [
-		{
-			role: "user",
-			content: [
-				{
-					type: "image_url",
-					url: "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
-				},
-				{
-					type: "text",
-					text: "What is in this image?",
-				},
-			],
-		},
-	],
-	model: "claude-opus-4.5",
-}
-
-const agent = new MozaikAgent(request)
-const response = await agent.act()
-```
-
-### Parallel Task Execution
-
-This example demonstrates how to use standard JavaScript/TypeScript concurrency (Promise.all) to run multiple AI agents in parallel and compare or combine their responses.
-
-```typescript
-import "dotenv/config"
-import { MozaikAgent, MozaikRequest } from "@mozaik-ai/core"
-
-const openaiRequest: MozaikRequest = {
-	model: "gpt-5",
-}
-
-const anthropicRequest: MozaikRequest = {
-	model: "claude-sonnet-4.5",
-}
+---
 
-const openaiAgent = new MozaikAgent(openaiRequest)
-const anthropicAgent = new MozaikAgent(anthropicRequest)
+## Compatibility
 
-const task = "What are the key differences between TypeScript and JavaScript?"
+This domain model is fully compatible with the **Open Responses** specification for multi-provider LLM interfaces ([openresponses.org](https://www.openresponses.org/)).
 
-// Execute both agents in parallel using Promise.all()
-const [openaiResponse, anthropicResponse] = await Promise.all([openaiAgent.act(task), anthropicAgent.act(task)])
-```
+![OpenResponses overview](public/openresponses-overview.png)
 
-### Workflow
+The core idea of OpenResponses is a **unified specification across LLM providers**: while vendors differ in details, most models follow the same interaction architecture and principles. OpenResponses standardizes that shared shape using **typed context items** (and clarifies that any item type can be streamed).
 
-A workflow defines how tasks are executed together, either sequentially (one after another) or in parallel. Each task or workflow is a `WorkUnit`, which allows workflows to be composed and nested to build more complex execution pipelines.
+- **Input (context)**: client-provided context items such as **user_message**, **developer_message**, and **function_call_output**
+- **Output (response)**: model-produced context items such as **reasoning**, **function_call**, and **model_message**
+- **Streaming (optional)**: items may be delivered incrementally as **semantic events** (meaningful events at the item level, not just raw token streams)
 
-```typescript
-const workflow = new Workflow("sequential", [
-	new Task("Analyze requirements", "gpt-5"),
-	new Workflow("parallel", [
-		new Task("Generate API schema", "gpt-5-mini"),
-		new Task("Draft documentation", "gpt-5-nano"),
-	]),
-	new Task("Review and finalize", "gpt-5"),
-])
+## Mozaik Core Concepts
 
-await workflow.execute()
-```
+Mozaik turns the OpenResponses specification into a practical **object model** so developers can manipulate LLM context in different ways (compose it, append model outputs, **persist it**, and **restore it** from a database/repository, etc.). This is a starting point—our main goal is to address core **context engineering** problems like **context bloating**, **context window overflow**, and **sequential agent collaboration**.
 
-### AI Autonomy
+### Context
 
-Developers can create autonomous agents using an AI planner agent. The planner works as a meta-agent: it breaks a high-level goal into smaller tasks, assigns each task to a specialized agent, and coordinates their execution through a workflow.
+Represents everything the model needs to generate a response.
 
-For example, given the goal `"Implement login functionality"`, the planner can generate the following workflow:
+A context is composed of ordered **context items**.
 
-```typescript
-Workflow(sequential, [
-	Task("Design login form UI", "gpt-5"),
-	Task("Implement authentication logic", "claude-sonnet-4.5"),
-	Workflow(parallel, [Task("Add input validation", "gpt-5-mini"), Task("Style the login form", "gpt-5-nano")]),
-	Task("Write unit tests", "gpt-5"),
-])
-```
+---
 
-### Autonomy Slider
+### ContextItem
 
-By combining manually created workflows with the AI Planner, you can build hybrid workflows and control the level of autonomy, deciding which steps are fixed and which are planned automatically.
+A single unit of context.
 
----
+Examples:
 
-Working examples are available on the [GitHub repo](https://github.com/jigjoy-ai/mosaic-examples).
+- Client-specific
+    - User message
+    - Developer message (System instruction)
+    - Function call output (added after a model function call and fed back so the model can continue reasoning or finish the job)
+- Model-specific
+    - Function call
+    - Model message
+    - Reasoning
 
 ---
 
-### Execution Hooks
-
-Execution hooks allow you to attach custom behavior to workflow and task execution without changing the workflow logic itself. Hooks are invoked at key lifecycle moments (before/after task or workflow execution) and are passed into `execute()`.
+## Example (Context + OpenAI Responses)
 
-A default hook cluster is provided out of the box, but you can extend or replace it to add logging, metrics, tracing, or other instrumentation.
+This is a minimal end-to-end example that:
 
-#### Extending the default hooks
-
-You can add your own hooks by creating a new cluster or extending the default one:
+- builds a `Context` from a developer message + user message
+- calls a model (OpenAI Responses API)
+- stores/restores the context using a repository
 
 ```ts
-import { ClusterHook } from "@core/workflow/hooks/cluster"
-import { DEFAULT_CLUSTER_HOOK } from "@core/workflow/hooks"
-import { MetricsHook } from "./metrics-hook"
+const contextRepository = new InMemoryContextRepository()
 
-const extendedHook = new ClusterHook([DEFAULT_CLUSTER_HOOK, new MetricsHook()])
+const message = UserMessage.create("Tell me a joke about birds")
+const developerMessage = DeveloperMessage.create(
+	"You are a joke teller. You will be given a joke and you will need to tell it to the user.",
+)
+const projectId = `pr-${crypto.randomUUID()}`
+const context = Context.create(projectId).addItem(developerMessage).addItem(message)
 
-await workflow.execute(extendedHook)
-```
+await contextRepository.save(context)
 
-If you’re building agentic systems and want to learn or connect with like-minded developers, join [our Discord](https://discord.gg/33uMhcerDU) where we share ideas and knowledge.
+const model = new GPT54Model()
+const newContextItems = await model.call(context)
+context.addItems(newContextItems)
 
----
+await contextRepository.save(context)
+const restoredContexts = await contextRepository.getByProjectId(projectId)
+console.log(restoredContexts)
+```
 
 ## Author & License
 
-Created by [JigJoy](https://jigjoy.io) team  
+Created by [JigJoy](https://jigjoy.io) team
 Licensed under the MIT License.

package/dist/index.d.mts

@@ -1,132 +1,148 @@
-import { ZodObject } from 'zod';
-
-declare class Workflow extends WorkUnit {
-    readonly mode: "parallel" | "sequential";
-    readonly units: WorkUnit[];
-    constructor(mode: "parallel" | "sequential", units: WorkUnit[]);
-    execute(hook?: ExecutionHook): Promise<any>;
+declare abstract class ContextItem {
+    abstract readonly type: string;
+    getType(): string;
+    abstract toJSON(): any;
 }
 
-declare class Task extends WorkUnit {
-    private task;
-    private model;
-    constructor(task: string, model: Model);
-    getTask(): string;
-    getModel(): Model;
-    execute(hook?: ExecutionHook): Promise<any>;
+declare class Context {
+    readonly id: string;
+    readonly projectId: string;
+    readonly items: ContextItem[];
+    constructor(id: string, projectId: string, items: ContextItem[]);
+    addItem(item: ContextItem): Context;
+    addItems(items: ContextItem[]): Context;
+    getItems(): ContextItem[];
+    static create(projectId: string): Context;
+    static rehydrate(data: {
+        id: string;
+        projectId: string;
+        items: ContextItem[];
+    }): Context;
+    toJSON(): any;
 }
 
-interface ExecutionHook {
-    beforeWorkflow(wf: Workflow): void;
-    afterWorkflow(wf: Workflow, result: any): void;
-    beforeTask(task: Task): void;
-    afterTask(task: Task, result: any): void;
+declare abstract class Content {
+    abstract readonly type: string;
 }
 
-declare abstract class WorkUnit {
-    constructor();
-    abstract execute(hook: ExecutionHook): Promise<any>;
+declare class InputText extends Content {
+    readonly text: string;
+    readonly type = "input_text";
+    private constructor();
+    static create(text: string): InputText;
+    static rehydrate(data: {
+        text: string;
+    }): InputText;
+    toJSON(): any[];
 }
 
-interface TextPart {
-    type: "text";
-    text: string;
-}
-interface ImagePart {
-    type: "image_url";
-    url: string;
-}
-interface Message {
-    role: "system" | "user" | "assistant" | "tool";
-    content: string | Array<TextPart | ImagePart>;
+declare class UserMessage extends ContextItem {
+    readonly type = "message";
+    readonly role = "user";
+    readonly content: InputText;
+    private constructor();
+    static create(text: string): UserMessage;
+    static rehydrate(data: {
+        text: string;
+    }): UserMessage;
+    toJSON(): any;
 }
 
-declare const OPENAI_MODELS: readonly ["gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5.1", "gpt-5.2", "gpt-5.4"];
-type OpenAIModel = (typeof OPENAI_MODELS)[number];
-declare const ANTHROPIC_MODELS: readonly ["claude-sonnet-4.5", "claude-haiku-4.5", "claude-opus-4.5"];
-type AnthropicModel = (typeof ANTHROPIC_MODELS)[number];
-type Model = OpenAIModel | AnthropicModel;
-
-interface Tool {
-    name: string;
-    description: string;
-    schema: Record<string, any>;
-    invoke: (args: any) => Promise<any>;
+declare class DeveloperMessage extends ContextItem {
+    readonly type = "message";
+    readonly role = "developer";
+    readonly content: InputText;
+    private constructor();
+    toJSON(): any;
+    static create(text: string): DeveloperMessage;
+    static rehydrate(data: {
+        text: string;
+    }): DeveloperMessage;
 }
 
-type MozaikRequest = {
-    model: Model;
-    messages?: Message[];
-    task?: string;
-    structuredOutput?: ZodObject<any>;
-    tools?: Tool[];
-    reasoningEffort?: ReasoningEffort;
-};
-declare enum ReasoningEffort {
-    NONE = "none",
-    LOW = "low",
-    MEDIUM = "medium",
-    HIGH = "high",
-    MAX = "max"
+declare class OutputText extends Content {
+    readonly text: string;
+    readonly type = "output_text";
+    private constructor();
+    static rehydrate(data: {
+        text: string;
+    }): OutputText;
+    toJSON(): any[];
 }
 
-declare abstract class RequestBuilder {
-    request: any;
-    initialize(): void;
-    abstract addModel(model: string): RequestBuilder;
-    abstract addTask(task: string): RequestBuilder;
-    abstract addMessages(messages: Message[]): RequestBuilder;
-    abstract addStructuredOutput(schema: ZodObject<any>): RequestBuilder;
-    abstract addTools(tools: Tool[]): RequestBuilder;
-    abstract addReasoningEffort(effort: ReasoningEffort): RequestBuilder;
-    build(): any;
+declare class ModelMessage extends ContextItem {
+    readonly type = "message";
+    readonly role = "assistant";
+    readonly content: OutputText;
+    private constructor();
+    static rehydrate(data: {
+        text: string;
+    }): ModelMessage;
+    toJSON(): any;
 }
 
-declare abstract class Endpoint {
-    abstract requestBuilder: RequestBuilder;
-    request: MozaikRequest | null;
-    buildRequest(request: MozaikRequest): any;
-    abstract sendRequest(providerRequest: any): any;
+declare class FunctionCall extends ContextItem {
+    readonly type = "function_call";
+    readonly callId: string;
+    readonly name: string;
+    readonly args: string;
+    private constructor();
+    static rehydrate(data: {
+        callId: string;
+        name: string;
+        args: string;
+    }): FunctionCall;
+    toJSON(): any;
 }
 
-declare abstract class EndpointResolver {
-    abstract resolve(model: string): Endpoint;
+declare class SummaryText extends Content {
+    readonly text: string;
+    readonly type = "summary_text";
+    private constructor();
+    static rehydrate(data: {
+        text: string;
+    }): SummaryText;
+    toJSON(): Record<string, any>;
 }
 
-declare class RequestGateway {
-    readonly endpointResolver: EndpointResolver;
-    endpoint: Endpoint;
-    constructor(endpointResolver: EndpointResolver);
-    invoke(request: MozaikRequest): Promise<any>;
+declare class Reasoning extends ContextItem {
+    readonly type = "reasoning";
+    readonly content: InputText | undefined;
+    readonly encryptedContent: string | undefined;
+    readonly summary: SummaryText[];
+    private constructor();
+    static rehydrate(data: {
+        content: InputText | undefined;
+        encryptedContent: string | undefined;
+        summary: SummaryText[];
+    }): Reasoning;
+    toJSON(): any;
 }
 
-declare class MozaikAgent {
-    private request;
-    gateway: RequestGateway;
-    constructor(request: MozaikRequest);
-    setModel(model: Model): void;
-    setMessages(messages: Message[]): void;
-    setTask(task: string): void;
-    setStructuredOutput(schema: ZodObject<any>): void;
-    act(task?: string): Promise<any>;
+declare abstract class GenerativeModel {
+    abstract mapContextToRequest(context: Context): any[];
+    abstract extractContextItems(response: any): ContextItem[];
+    abstract infer(request: any): Promise<any>;
+    call(context: Context): Promise<ContextItem[]>;
 }
 
-declare class PlanningAgent extends MozaikAgent {
-    constructor(request: MozaikRequest);
-    planFromGoal(goal: string): Promise<Workflow>;
+declare class FunctionCallOutput extends ContextItem {
+    readonly type = "function_call_output";
+    readonly callId: string;
+    readonly output: InputText[];
+    private constructor();
+    static create(callId: string, output: InputText[]): FunctionCallOutput;
+    static rehydrate(data: {
+        callId: string;
+        output: InputText[];
+    }): FunctionCallOutput;
+    toJSON(): any;
 }
 
-type UsageEntry = {
-    inputTokens: number;
-    outputTokens: number;
-    model: string;
-};
-type MozaikResponse = {
-    data: any;
-    usage: {
-        entries: UsageEntry[];
-        totalUsdCost: number;
-    };
-};
+interface ContextRepository {
+    save(context: Context): Promise<void>;
+    get(id: string): Promise<Context>;
+    getByProjectId(projectId: string): Promise<Context[]>;
+}
 
-export { type Message, type Model, MozaikAgent, type MozaikRequest, type MozaikResponse, PlanningAgent, ReasoningEffort, Task, type Tool, WorkUnit, Workflow };
+export { Context, ContextItem, type ContextRepository, DeveloperMessage, FunctionCall, FunctionCallOutput, GenerativeModel, ModelMessage, Reasoning, UserMessage };