noosphere 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 0xJesus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# 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
+
+```bash
+npm install noosphere
+```
+
+## Quick Start
+
+```typescript
+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:
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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:
+
+```typescript
+const ai = new Noosphere({
+  onUsage: (event) => {
+    console.log(`${event.provider}/${event.model}: $${event.cost} (${event.latencyMs}ms)`);
+  },
+});
+```
+
+### Custom Providers
+
+Register your own provider by implementing the `NoosphereProvider` interface:
+
+```typescript
+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`:
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+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