@mozaik-ai/core 0.7.0

package/README.md

@@ -0,0 +1,275 @@
+# Mozaik
+
+Mozaik is a TypeScript library for orchestrating AI agents, supporting both manually defined and AI-generated workflows.
+
+![Mosaic](https://www.rockform.co.uk/wp-content/uploads/2018/06/Picture6-1.jpg)
+
+---
+
+## 📦 Installation
+
+```bash
+yarn add @jigjoy-ai/mosaic
+```
+
+## API Key Configuration
+
+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 Agents
+
+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 { Agent, Command } from '@jigjoy-ai/mosaic'
+
+const command: Command = {
+    model: 'claude-sonnet-4.5'
+}
+
+const agent = new Agent(command)
+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 { Agent, Command } from '@jigjoy-ai/mosaic'
+
+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 command: Command = {
+    model: 'gpt-5-mini',
+    task: 'Create a 1-day vegetarian meal plan with breakfast, lunch, and dinner.',
+    structuredOutput: mealPlanSchema
+}
+
+const agent = new Agent(command)
+const response = await agent.act()
+```
+
+### Multi-turn Conversation
+
+Multi-turn conversation allows developers to provide chat history so the AI agent can maintain context and generate more relevant, continuous responses.
+
+```typescript
+import { Agent, Command } from '@jigjoy-ai/mosaic'
+
+const command: Command = {
+    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 Agent(command)
+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 { Agent, Command, Tool } from '@jigjoy-ai/mosaic'
+
+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 command: Command = {
+    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 Agent(command)
+await agent.act()
+```
+
+### Vision
+
+Vision support allows AI agents to interpret images alongside text, enabling richer understanding and multimodal interactions.
+
+```typescript
+import { Agent, Command } from '@jigjoy-ai/mosaic'
+
+const command: Command = {
+    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 Agent(command)
+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 { Agent, Command } from '@jigjoy-ai/mosaic'
+
+const openaiCommand: Command = {
+    model: 'gpt-5'
+}
+
+const anthropicCommand: Command = {
+    model: 'claude-sonnet-4.5'
+}
+
+const openaiAgent = new Agent(openaiCommand)
+const anthropicAgent = new Agent(anthropicCommand)
+
+const task = 'What are the key differences between TypeScript and JavaScript?'
+
+// Execute both agents in parallel using Promise.all()
+const [openaiResponse, anthropicResponse] = await Promise.all([
+    openaiAgent.act(task),
+    anthropicAgent.act(task)
+])
+```
+
+### Workflow
+
+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.
+
+```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")
+])
+
+await workflow.execute()
+```
+
+### AI Autonomy
+
+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.
+
+For example, given the goal `"Implement login functionality"`, the planner can generate the following workflow:
+
+```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
+
+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.
+
+---
+
+Working examples are available on the [GitHub repo](https://github.com/jigjoy-ai/mosaic-examples).
+
+---
+
+### 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()`.
+
+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.
+
+#### Extending the default hooks
+
+You can add your own hooks by creating a new cluster or extending the default one:
+
+```ts
+import { ClusterHook } from "@core/workflow/hooks/cluster"
+import { DEFAULT_CLUSTER_HOOK } from "@core/workflow/hooks"
+import { MetricsHook } from "./metrics-hook"
+
+const extendedHook = new ClusterHook([
+  DEFAULT_CLUSTER_HOOK,
+  new MetricsHook()
+])
+
+await workflow.execute(extendedHook)
+```
+
+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.
+
+---
+
+## Author & License
+
+Created by [JigJoy](https://jigjoy.io) team  
+Licensed under the MIT License.

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+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 class Task extends WorkUnit {
+    private task;
+    private model;
+    constructor(task: string, model: Model);
+    getTask(): string;
+    getModel(): Model;
+    execute(hook?: ExecutionHook): Promise<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 WorkUnit {
+    constructor();
+    abstract execute(hook: ExecutionHook): Promise<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 const OPENAI_MODELS: readonly ["gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5.1"];
+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>;
+}
+
+type Command = {
+    model: Model;
+    messages?: Message[];
+    task?: string;
+    structuredOutput?: ZodObject<any>;
+    tools?: Tool[];
+};
+
+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;
+    build(): any;
+}
+
+declare abstract class Endpoint {
+    abstract requestBuilder: RequestBuilder;
+    command: Command | null;
+    buildRequest(command: Command): any;
+    abstract sendRequest(providerRequest: any): any;
+}
+
+declare abstract class EndpointResolver {
+    abstract resolve(model: string): Endpoint;
+}
+
+declare class RequestGateway {
+    readonly endpointResolver: EndpointResolver;
+    endpoint: Endpoint;
+    constructor(endpointResolver: EndpointResolver);
+    invoke(command: Command): Promise<any>;
+}
+
+declare class Agent {
+    private command;
+    gateway: RequestGateway;
+    constructor(command: Command);
+    setModel(model: Model): void;
+    setMessages(messages: Message[]): void;
+    setTask(task: string): void;
+    setStructuredOutput(schema: ZodObject<any>): void;
+    act(task?: string): Promise<any>;
+}
+
+declare class PlanningAgent extends Agent {
+    constructor(command: Command);
+    planFromGoal(goal: string): Promise<Workflow>;
+}
+
+export { Agent, type Command, type Message, type Model, PlanningAgent, Task, type Tool, WorkUnit, Workflow };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+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 class Task extends WorkUnit {
+    private task;
+    private model;
+    constructor(task: string, model: Model);
+    getTask(): string;
+    getModel(): Model;
+    execute(hook?: ExecutionHook): Promise<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 WorkUnit {
+    constructor();
+    abstract execute(hook: ExecutionHook): Promise<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 const OPENAI_MODELS: readonly ["gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5.1"];
+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>;
+}
+
+type Command = {
+    model: Model;
+    messages?: Message[];
+    task?: string;
+    structuredOutput?: ZodObject<any>;
+    tools?: Tool[];
+};
+
+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;
+    build(): any;
+}
+
+declare abstract class Endpoint {
+    abstract requestBuilder: RequestBuilder;
+    command: Command | null;
+    buildRequest(command: Command): any;
+    abstract sendRequest(providerRequest: any): any;
+}
+
+declare abstract class EndpointResolver {
+    abstract resolve(model: string): Endpoint;
+}
+
+declare class RequestGateway {
+    readonly endpointResolver: EndpointResolver;
+    endpoint: Endpoint;
+    constructor(endpointResolver: EndpointResolver);
+    invoke(command: Command): Promise<any>;
+}
+
+declare class Agent {
+    private command;
+    gateway: RequestGateway;
+    constructor(command: Command);
+    setModel(model: Model): void;
+    setMessages(messages: Message[]): void;
+    setTask(task: string): void;
+    setStructuredOutput(schema: ZodObject<any>): void;
+    act(task?: string): Promise<any>;
+}
+
+declare class PlanningAgent extends Agent {
+    constructor(command: Command);
+    planFromGoal(goal: string): Promise<Workflow>;
+}
+
+export { Agent, type Command, type Message, type Model, PlanningAgent, Task, type Tool, WorkUnit, Workflow };