Package Exports

@jigjoy-io/mosaic
@jigjoy-io/mosaic/dist/index.js
@jigjoy-io/mosaic/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jigjoy-io/mosaic) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Mosaic

A TypeScript library that provides a unified, provider-agnostic API for interacting with AI language models. Currently supports OpenAI and Anthropic Claude endpoints.

📦 Installation

yarn add @jigjoy-io/mosaic

Key Purpose

Creates an abstraction layer between your application and AI model providers, allowing you to switch providers or models without changing your code.

Architecture

Core Components

RequestGateway - Main entry point that orchestrates requests
ProviderResolver - Determines which provider to use based on the model
ModelProvider - Abstract base for provider implementations (OpenAI, Anthropic)
RequestBuilder - Constructs provider-specific requests using chain-of-responsibility pattern
Capability Handlers - Modular handlers (messages, task, model) that build requests step-by-step

How It Works

You create a Mosaic object with messages and model
You instantiate a MosaicAgent with the Mosaic object
You call agent.act(task) to send a request
Gateway resolves the appropriate provider (OpenAI or Anthropic)
Provider builds the request through a chain of handlers
Request is sent to the AI provider's API
Response is returned as a simple string

Design Patterns

Strategy Pattern - Swappable providers
Chain of Responsibility - Sequential request building through handlers
Builder Pattern - Constructs complex request objects
Facade Pattern - Single entry point for all AI interactions

Extensibility

The architecture supports adding new providers (Google, etc.) by:

Implementing ModelProvider abstract class
Creating provider-specific RequestBuilder and mapper
Registering in ProviderResolver

API Key Configuration

Make sure to set your API keys in a .env file at the root of your project:

# For OpenAI
OPENAI_API_KEY=your-openai-key-here

# For Anthropic Claude
ANTHROPIC_API_KEY=your-anthropic-key-here

Supported Models

The following models are supported out of the box.

OpenAI

gpt-5
gpt-5-mini
gpt-5-nano

Anthropic Claude

claude-sonnet-4-5-20250929
claude-haiku-4-5-20251001
claude-opus-4-1-20250805

Quick Start

OpenAI Example

import 'dotenv/config'
import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

const request: Mosaic = {
    messages: [{
        role: 'system', 
        content: 'You are a helpful weather assistant'
    }],
    model: 'gpt-5'
}

const agent = new MosaicAgent(request)
const response = await agent.act('What is the weather in Serbia?')
console.log(response)

Anthropic Claude Example

import 'dotenv/config'
import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

// Using Claude Sonnet 4.5 (latest, best for coding/vision)
const request: Mosaic = {
    messages: [],
    model: 'claude-sonnet-4-5-20250929'
}

const agent = new MosaicAgent(request)
const codingResponse = await agent.act('Write a React component for a todo list')

Usage Examples

Simple Chat Completion

import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

const request: Mosaic = {
    messages: [],
    model: 'gpt-5-nano'
}

const agent = new MosaicAgent(request)
const response = await agent.act('Explain quantum computing in simple terms')

Multi-turn Conversation

import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

const request: Mosaic = {
    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-20251001'
}

const agent = new MosaicAgent(request)
const response = await agent.act('Can you show me an example?')

Using Different Models

import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

// OpenAI GPT-5
const gptRequest: Mosaic = {
    messages: [],
    model: 'gpt-5'
}
const gptAgent = new MosaicAgent(gptRequest)
const gptResponse = await gptAgent.act('Write a haiku about coding')

// Anthropic Claude Opus 4
const opusRequest: Mosaic = {
    messages: [],
    model: 'claude-opus-4-1-20250805'
}
const opusAgent = new MosaicAgent(opusRequest)
const opusResponse = await opusAgent.act('Analyze this complex problem...')

Parallel Task Execution

import 'dotenv/config'
import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

const openaiRequest: Mosaic = {
    model: 'gpt-5'
}

const anthropicRequest: Mosaic = {
    model: 'claude-sonnet-4-5-20250929'
}

const openaiAgent = new MosaicAgent(openaiRequest)
const anthropicAgent = new MosaicAgent(anthropicRequest)

const task = 'What are the key differences between TypeScript and JavaScript? Provide a concise answer.'

// Execute both agents in parallel using Promise.all()
const [openaiResponse, anthropicResponse] = await Promise.all([
    openaiAgent.act(task),
    anthropicAgent.act(task)
])

Important Notes

Anthropic Image Support

When using Anthropic Claude models with images, note that:

Images must be provided as base64-encoded data URLs
Format: data:image/[type];base64,[encoded-data]
Supported formats: JPEG, PNG, GIF, WebP
Maximum size: 30MB per image, up to 20 images per request

Example:

import { MosaicAgent, Mosaic } from '@jigjoy-io/mosaic'

const request: Mosaic = {
    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-1-20250805'
}

const agent = new MosaicAgent(request)
const response = await agent.act()

Working examples are available on the GitHub repo.

Author & License

Created by JigJoy team
Licensed under the MIT License.