Package Exports

noosphere

Readme

noosphere

Unified AI creation engine — text, image, video, and audio generation across all providers through a single interface.

Features

Multi-modal — LLM chat, image generation, video generation, and text-to-speech
Multi-provider — OpenAI, Anthropic, Google, Groq, Mistral, xAI, OpenRouter, FAL, Hugging Face
Local-first — Auto-detects ComfyUI, Ollama, Piper, and Kokoro running on your machine
Failover & retry — Automatic retries with exponential backoff and cross-provider failover
Usage tracking — Track costs, latency, and token counts across all providers
TypeScript-first — Full type definitions with ESM and CommonJS support

Install

npm install noosphere

Quick Start

import { Noosphere } from 'noosphere';

const ai = new Noosphere();

// Chat with any LLM
const response = await ai.chat({
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.content);

// Generate an image
const image = await ai.image({
  prompt: 'A sunset over mountains',
  width: 1024,
  height: 1024,
});
console.log(image.url);

// Generate a video
const video = await ai.video({
  prompt: 'Ocean waves crashing on rocks',
  duration: 5,
});
console.log(video.url);

// Text-to-speech
const audio = await ai.speak({
  text: 'Welcome to Noosphere',
  voice: 'alloy',
  format: 'mp3',
});
// audio.buffer contains the audio data

Configuration

API keys are resolved from the constructor or environment variables:

const ai = new Noosphere({
  keys: {
    openai: 'sk-...',
    anthropic: 'sk-ant-...',
    google: 'AIza...',
    fal: 'fal-...',
    huggingface: 'hf_...',
    groq: 'gsk_...',
    mistral: '...',
    xai: '...',
    openrouter: 'sk-or-...',
  },
});

Or set environment variables:

Variable	Provider
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`GEMINI_API_KEY`	Google
`FAL_KEY`	FAL
`HUGGINGFACE_TOKEN`	Hugging Face
`GROQ_API_KEY`	Groq
`MISTRAL_API_KEY`	Mistral
`XAI_API_KEY`	xAI
`OPENROUTER_API_KEY`	OpenRouter

API

`new Noosphere(config?)`

Creates a new instance. Providers are initialized lazily on first use.

Generation

`ai.chat(options): Promise<NoosphereResult>`

Generate text with an LLM.

const result = await ai.chat({
  provider: 'anthropic',          // optional — auto-resolved if omitted
  model: 'claude-sonnet-4-20250514',  // optional
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Explain quantum computing' },
  ],
  temperature: 0.7,               // optional
  maxTokens: 1024,                // optional
  jsonMode: false,                // optional
});

console.log(result.content);     // response text
console.log(result.thinking);    // reasoning (if supported)
console.log(result.usage.cost);  // cost in USD

`ai.stream(options): NoosphereStream`

Stream LLM responses.

const stream = ai.stream({
  messages: [{ role: 'user', content: 'Write a story' }],
});

for await (const event of stream) {
  if (event.type === 'text_delta') process.stdout.write(event.delta!);
  if (event.type === 'thinking_delta') console.log('[thinking]', event.delta);
}

// Or get the full result after streaming
const result = await stream.result();

`ai.image(options): Promise<NoosphereResult>`

Generate images.

const result = await ai.image({
  prompt: 'A futuristic cityscape',
  negativePrompt: 'blurry, low quality', // optional
  width: 1024,                           // optional
  height: 768,                           // optional
  seed: 42,                              // optional
  steps: 30,                             // optional
  guidanceScale: 7.5,                    // optional
});

console.log(result.url);          // image URL
console.log(result.media?.width); // dimensions

`ai.video(options): Promise<NoosphereResult>`

Generate videos.

const result = await ai.video({
  prompt: 'A bird flying through clouds',
  imageUrl: 'https://...',  // optional — image-to-video
  duration: 5,              // optional — seconds
  fps: 24,                  // optional
  width: 1280,              // optional
  height: 720,              // optional
});

console.log(result.url);

`ai.speak(options): Promise<NoosphereResult>`

Text-to-speech synthesis.

const result = await ai.speak({
  text: 'Hello world',
  voice: 'alloy',           // optional
  language: 'en',           // optional
  speed: 1.0,               // optional
  format: 'mp3',            // optional — 'mp3' | 'wav' | 'ogg'
});

// result.buffer contains the audio data

Discovery

`ai.getProviders(modality?): Promise<ProviderInfo[]>`

List available providers, optionally filtered by modality.

const providers = await ai.getProviders('llm');
// [{ id: 'pi-ai', name: 'Pi-AI', modalities: ['llm'], local: false, status: 'online', modelCount: 42 }]

`ai.getModels(modality?): Promise<ModelInfo[]>`

List all available models.

const models = await ai.getModels('image');

`ai.getModel(provider, modelId): Promise<ModelInfo | null>`

Get details about a specific model.

`ai.syncModels(): Promise<SyncResult>`

Refresh model lists from all providers.

Usage Tracking

`ai.getUsage(options?): UsageSummary`

Get aggregated usage statistics.

const usage = ai.getUsage({ since: '2024-01-01', provider: 'openai' });
console.log(usage.totalCost);       // total USD spent
console.log(usage.totalRequests);   // number of requests
console.log(usage.byProvider);      // { openai: 2.50, anthropic: 1.20 }
console.log(usage.byModality);      // { llm: 3.00, image: 0.70 }

Real-time usage callback:

const ai = new Noosphere({
  onUsage: (event) => {
    console.log(`${event.provider}/${event.model}: $${event.cost} (${event.latencyMs}ms)`);
  },
});

Custom Providers

import type { NoosphereProvider } from 'noosphere';

const myProvider: NoosphereProvider = {
  id: 'my-provider',
  name: 'My Provider',
  modalities: ['llm'],
  isLocal: false,

  async ping() { return true; },
  async listModels() { return [/* ... */]; },

  async chat(options) {
    // your implementation
    return { content: '...', provider: 'my-provider', model: '...', modality: 'llm', latencyMs: 100, usage: { cost: 0 } };
  },
};

ai.registerProvider(myProvider);

Error Handling

All errors are instances of NoosphereError:

import { NoosphereError } from 'noosphere';

try {
  await ai.chat({ messages: [{ role: 'user', content: 'Hello' }] });
} catch (err) {
  if (err instanceof NoosphereError) {
    console.log(err.code);      // 'RATE_LIMITED' | 'TIMEOUT' | 'AUTH_FAILED' | ...
    console.log(err.provider);  // which provider failed
    console.log(err.modality);  // 'llm' | 'image' | 'video' | 'tts'
    console.log(err.isRetryable());
  }
}

Error codes: PROVIDER_UNAVAILABLE, MODEL_NOT_FOUND, AUTH_FAILED, RATE_LIMITED, TIMEOUT, GENERATION_FAILED, INVALID_INPUT, NO_PROVIDER

Retry & Failover

const ai = new Noosphere({
  retry: {
    maxRetries: 3,                // default: 2
    backoffMs: 2000,              // default: 1000
    failover: true,               // default: true — try other providers on failure
    retryableErrors: ['RATE_LIMITED', 'TIMEOUT', 'PROVIDER_UNAVAILABLE'],
  },
  timeout: {
    llm: 30000,    // 30s (default)
    image: 120000, // 2min (default)
    video: 300000, // 5min (default)
    tts: 60000,    // 1min (default)
  },
});

Local Services

Noosphere auto-detects local AI services on startup. Configure via constructor or environment variables:

const ai = new Noosphere({
  autoDetectLocal: true, // default
  local: {
    comfyui: { enabled: true, host: 'http://localhost', port: 8188 },
    piper: { enabled: true, host: 'http://localhost', port: 5500 },
    kokoro: { enabled: true, host: 'http://localhost', port: 5501 },
  },
});

Environment variables: COMFYUI_HOST, COMFYUI_PORT, PIPER_HOST, PIPER_PORT, KOKORO_HOST, KOKORO_PORT, NOOSPHERE_AUTO_DETECT_LOCAL

Cleanup

await ai.dispose();

Providers

Provider	Modalities	Type
Pi-AI (OpenAI, Anthropic, Google, Groq, Mistral, xAI, OpenRouter)	LLM	Cloud
FAL	Image, Video, TTS	Cloud
Hugging Face	LLM, Image, TTS	Cloud
ComfyUI	Image, Video	Local
Piper / Kokoro	TTS	Local

Requirements

Node.js >= 18.0.0

License

MIT