npm package: @mamdouh-aboammar/pixolink-weavai
Description: WeavAi module for PixoLink — Intelligent AI orchestration with multi-provider support and advanced features
Author: PrePilot Labs & PixoRA Team
Latest version: 1.0.0

# @pixora/pixolink-weavai

WeavAi module for PixoLink SDK — Intelligent AI orchestration with multi-provider support, automatic fallback, caching, and advanced features.

## Features

- 🤖 **Multi-Provider Support** — Gemini, OpenAI, Anthropic, DeepSeek, OpenRouter
- 🔄 **Automatic Fallback** — Seamless provider switching on failure
- 💾 **Smart Caching** — Response caching with configurable TTL
- 🛡️ **Ethics & Safety** — Built-in content policy enforcement
- 🧠 **PIE (Prompt Intelligence Engine)** — Intelligent prompt preprocessing
- 📦 **ACCE (Context Compression)** — Adaptive context window management
- 🎯 **Cognitive Alignment** — Semantic validation and alignment
- 📊 **Telemetry & Metrics** — Request tracking and performance monitoring
- 🌊 **Streaming Support** — Real-time text generation
- 🔌 **Contextual Plugin** — Conversation history management

## Installation

This module is included with PixoLink SDK:

```bash
npm install @pixora/pixolink
```

Or install separately:

```bash
npm install @pixora/pixolink-weavai
```

## Configuration

Add to your `pixo.config.json`:

```json
{
  "connectors": {
    "ai": {
      "provider": "gemini",
      "apiKey": "${GEMINI_API_KEY}",
      "models": ["gemini-2.0-flash-exp"],
      "fallbackProviders": [
        {
          "provider": "openai",
          "apiKey": "${OPENAI_API_KEY}",
          "model": "gpt-4"
        },
        {
          "provider": "anthropic",
          "apiKey": "${ANTHROPIC_API_KEY}",
          "model": "claude-3-5-sonnet-20241022"
        }
      ]
    }
  },
  "modules": {
    "weavai": {
      "enabled": true,
      "config": {
        "defaultProvider": "gemini",
        "enableFallback": true,
        "fallbackOrder": ["gemini", "openai", "anthropic"],
        "enableCache": true,
        "cacheTTL": 3600000,
        "maxCacheSize": 52428800,
        "enableEthics": true,
        "enableTelemetry": true,
        "enablePIE": true,
        "enableACCE": true,
        "enableCognitivePipeline": false,
        "contextual": {
          "enabled": true,
          "maxHistory": 100
        }
      }
    }
  }
}
```

## Usage

### Basic Text Generation

```typescript
import { usePlugin } from '@pixora/pixolink';

const weavai = usePlugin('weavai');

// Simple generation
const result = await weavai.generate('Explain quantum computing in simple terms');
console.log(result.response.text);

// With options
const result = await weavai.generate('Write a creative story', {
  maxTokens: 1000,
  temperature: 0.9,
  topP: 0.95
});
```

### Automatic Fallback

```typescript
// Automatically tries multiple providers
const result = await weavai.generateWithFallback(
  'Generate product description',
  {
    maxTokens: 500,
    temperature: 0.7
  }
);

console.log(`Generated by: ${result.trace.connector}`);
console.log(`Cached: ${result.trace.cached}`);
console.log(`Latency: ${result.trace.latency}ms`);
```

### Streaming Generation

```typescript
// Stream text as it's generated
for await (const chunk of weavai.stream('Tell me a long story about AI')) {
  process.stdout.write(chunk);
}

// With callback
await weavai.stream('Generate code example', {
  maxTokens: 2000,
  onChunk: (chunk) => {
    // Process each chunk
    console.log(chunk);
  }
});
```

### Provider Management

```typescript
// Get available providers
const providers = weavai.getProviders();
console.log('Available providers:', providers);

// Check specific provider
if (weavai.isProviderAvailable('openai')) {
  const result = await weavai.generate('Hello', {
    connector: 'openai'
  });
}

// Get status
const status = weavai.getStatus();
console.log('Ready:', status.ready);
console.log('Connectors:', status.connectorCount);
```

### Metrics & Monitoring

```typescript
// Get generation metrics
const metrics = weavai.getMetrics();

console.log('Total requests:', metrics.totalRequests);
console.log('Success rate:', 
  (metrics.successfulRequests / metrics.totalRequests * 100).toFixed(2) + '%'
);
console.log('Average latency:', metrics.averageLatency.toFixed(0) + 'ms');
console.log('Cache hit rate:',
  (metrics.cacheHits / metrics.totalRequests * 100).toFixed(2) + '%'
);

// Per-provider metrics
for (const [provider, stats] of Object.entries(metrics.byProvider)) {
  console.log(`${provider}:`, {
    requests: stats.requests,
    successRate: (stats.successes / stats.requests * 100).toFixed(2) + '%',
    avgLatency: stats.averageLatency.toFixed(0) + 'ms'
  });
}
```

### Advanced Features

#### PIE (Prompt Intelligence Engine)

```typescript
// Enable PIE for intelligent prompt preprocessing
const result = await weavai.generate(prompt, {
  metadata: {
    enablePIE: true,
    pieBudget: 2048  // Token budget for preprocessing
  }
});
```

#### ACCE (Adaptive Context Compression)

```typescript
// Enable context compression for long prompts
const result = await weavai.generate(longPrompt, {
  metadata: {
    enableACCE: true,
    tokenBudget: 4000  // Compress to fit within budget
  }
});
```

#### Cognitive Alignment Pipeline

```typescript
import { z } from 'zod';

// Define expected output schema
const productSchema = z.object({
  name: z.string(),
  description: z.string(),
  price: z.number().positive(),
  category: z.string()
});

// Generate with semantic validation
const result = await weavai.generate('Create a product listing', {
  metadata: {
    enableCognitivePipeline: true,
    pipelineSchema: productSchema,
    expectedKeywords: ['product', 'price', 'description'],
    semanticThreshold: 0.7
  }
});
```

### Event-Driven Integration

```typescript
import { PixoLink } from '@pixora/pixolink';

const pixo = PixoLink.getInstance();

// Subscribe to WeavAi events
pixo.eventBus.on('weavai:generation:complete', (data) => {
  console.log('Generation completed:', {
    provider: data.trace.connector,
    latency: data.trace.latency,
    cached: data.trace.cached
  });
});

pixo.eventBus.on('weavai:generation:error', (data) => {
  console.error('Generation failed:', data.error);
});

pixo.eventBus.on('weavai:telemetry', (event) => {
  // Process telemetry events
  console.log('Telemetry:', event);
});
```

### Complete Example: AI-Powered Chat

```typescript
import { PixoLink, usePlugin } from '@pixora/pixolink';

await PixoLink.init('./pixo.config.json');

const weavai = usePlugin('weavai');

async function chat(userMessage: string): Promise<string> {
  try {
    // Generate with fallback and caching
    const result = await weavai.generateWithFallback(userMessage, {
      maxTokens: 500,
      temperature: 0.7,
      metadata: {
        enablePIE: true,
        enableACCE: true
      }
    });

    // Log metrics
    console.log(`Provider: ${result.trace.connector}`);
    console.log(`Latency: ${result.trace.latency}ms`);
    console.log(`Cached: ${result.trace.cached}`);

    return result.response.text;
  } catch (error) {
    console.error('Chat failed:', error);
    throw error;
  }
}

// Use the chat function
const response = await chat('Hello! How can AI help businesses?');
console.log('AI:', response);

// Get performance metrics
const metrics = weavai.getMetrics();
console.log('\nPerformance Metrics:');
console.log(`Total requests: ${metrics.totalRequests}`);
console.log(`Success rate: ${(metrics.successfulRequests / metrics.totalRequests * 100).toFixed(1)}%`);
console.log(`Avg latency: ${metrics.averageLatency.toFixed(0)}ms`);
console.log(`Cache hits: ${metrics.cacheHits} (${(metrics.cacheHits / metrics.totalRequests * 100).toFixed(1)}%)`);
```

### Complete Example: Content Generation Pipeline

```typescript
import { PixoLink, usePlugin } from '@pixora/pixolink';
import { z } from 'zod';

await PixoLink.init();

const weavai = usePlugin('weavai');

// Define content schema
const blogPostSchema = z.object({
  title: z.string(),
  excerpt: z.string().max(200),
  content: z.string().min(500),
  tags: z.array(z.string()).min(3).max(10),
  category: z.enum(['Tech', 'Business', 'Lifestyle', 'Education'])
});

async function generateBlogPost(topic: string) {
  const prompt = `Write a comprehensive blog post about: ${topic}
  
  Include:
  - Engaging title
  - Short excerpt (under 200 chars)
  - Well-structured content (at least 500 words)
  - 3-10 relevant tags
  - Appropriate category
  
  Format as JSON matching the schema.`;

  const result = await weavai.generate(prompt, {
    maxTokens: 2000,
    temperature: 0.8,
    metadata: {
      enablePIE: true,
      enableCognitivePipeline: true,
      pipelineSchema: blogPostSchema
    }
  });

  // Parse and validate response
  const blogPost = blogPostSchema.parse(JSON.parse(result.response.text));
  
  return blogPost;
}

// Generate content
const post = await generateBlogPost('The Future of Artificial Intelligence');
console.log('Generated Blog Post:');
console.log('Title:', post.title);
console.log('Category:', post.category);
console.log('Tags:', post.tags.join(', '));
console.log('\nExcerpt:', post.excerpt);
console.log('\nContent:', post.content.substring(0, 200) + '...');
```

## API Reference

### WeavAiAPI Methods

#### `generate(prompt, options?)`
Generate text using AI.

**Parameters:**
- `prompt: string` — Input text
- `options?: GenerateOptions` — Generation options
  - `maxTokens?: number` — Maximum output tokens
  - `temperature?: number` — Randomness (0-2)
  - `topP?: number` — Nucleus sampling (0-1)
  - `stopSequences?: string[]` — Stop generation at these
  - `connector?: string` — Force specific provider
  - `cache?: boolean` — Enable/disable caching
  - `metadata?: object` — Advanced options

**Returns:** `Promise<WeavAIGeneration>`

#### `generateWithFallback(prompt, options?)`
Generate with automatic provider fallback on failure.

**Parameters:** Same as `generate()`

**Returns:** `Promise<WeavAIGeneration>`

#### `stream(prompt, options?)`
Stream text generation in real-time.

**Parameters:**
- `prompt: string` — Input text
- `options?: StreamOptions` — Streaming options
  - All `GenerateOptions` fields
  - `onChunk?: (chunk: string) => void` — Callback for each chunk

**Returns:** `AsyncGenerator<string, void, unknown>`

#### `getStatus()`
Get WeavAi system status.

**Returns:** `WeavAIStatus`
- `ready: boolean` — System ready
- `connectorCount: number` — Active providers
- `connectors: string[]` — Provider names
- `metrics: object` — Performance metrics

#### `getProviders()`
Get list of available providers.

**Returns:** `string[]`

#### `isProviderAvailable(provider)`
Check if specific provider is available.

**Parameters:**
- `provider: string` — Provider name

**Returns:** `boolean`

#### `getMetrics()`
Get generation metrics and statistics.

**Returns:** `object`
- `totalRequests: number`
- `successfulRequests: number`
- `failedRequests: number`
- `cacheHits: number`
- `averageLatency: number`
- `byProvider: Record<string, object>` — Per-provider stats

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultProvider` | string | `'gemini'` | Default AI provider |
| `enableFallback` | boolean | `true` | Enable automatic fallback |
| `fallbackOrder` | string[] | `['gemini', 'openai', 'anthropic']` | Provider fallback order |
| `enableCache` | boolean | `true` | Enable response caching |
| `cacheTTL` | number | `3600000` | Cache TTL (ms) |
| `maxCacheSize` | number | `52428800` | Max cache size (bytes) |
| `enableEthics` | boolean | `true` | Enable ethics checking |
| `enableTelemetry` | boolean | `true` | Enable telemetry |
| `enablePIE` | boolean | `false` | Enable PIE preprocessing |
| `enableACCE` | boolean | `false` | Enable context compression |
| `enableCognitivePipeline` | boolean | `false` | Enable cognitive alignment |
| `contextual.enabled` | boolean | `false` | Enable contextual plugin |
| `contextual.maxHistory` | number | `100` | Max conversation history |

## Supported Providers

| Provider | Status | Models |
|----------|--------|--------|
| **Gemini** | ✅ Full | gemini-2.0-flash-exp, gemini-pro |
| **OpenAI** | ✅ Full | gpt-4, gpt-4-turbo, gpt-3.5-turbo |
| **Anthropic** | ✅ Full | claude-3-5-sonnet, claude-3-opus |
| **DeepSeek** | ✅ Full | deepseek-chat, deepseek-coder |
| **OpenRouter** | ✅ Full | Multiple models via gateway |

## Advanced Topics

### Custom Provider Configuration

```json
{
  "connectors": {
    "ai": {
      "provider": "openrouter",
      "apiKey": "${OPENROUTER_API_KEY}",
      "fallbackProviders": [
        {
          "provider": "gemini",
          "apiKey": "${GEMINI_API_KEY}",
          "model": "gemini-2.0-flash-exp"
        }
      ]
    }
  }
}
```

### Error Handling

```typescript
try {
  const result = await weavai.generate(prompt);
} catch (error) {
  if (error.type === 'RATE_LIMIT') {
    // Handle rate limit
    await sleep(error.retryAfter);
  } else if (error.type === 'CONTENT_POLICY') {
    // Handle content policy violation
    console.error('Content violated policy:', error.message);
  } else {
    // Handle other errors
    console.error('Generation failed:', error);
  }
}
```

### Performance Optimization

```typescript
// Use caching for repeated queries
const result = await weavai.generate(commonPrompt, {
  cache: true  // Enable cache lookup
});

// Batch generation
const prompts = ['prompt1', 'prompt2', 'prompt3'];
const results = await Promise.all(
  prompts.map(p => weavai.generate(p))
);

// Stream for long responses
for await (const chunk of weavai.stream(longPrompt)) {
  // Process chunks incrementally
  displayChunk(chunk);
}
```

## Troubleshooting

### No Providers Available

```
Error: No LLM connectors registered
```

**Solution:** Ensure at least one API key is configured in `pixo.config.json`:

```json
{
  "connectors": {
    "ai": {
      "provider": "gemini",
      "apiKey": "${GEMINI_API_KEY}"
    }
  }
}
```

### All Providers Failing

```
Error: All providers failed
```

**Solution:** Check:
1. API keys are valid
2. Network connectivity
3. Provider rate limits
4. Error logs for specific failures

### High Latency

**Solution:**
- Enable caching: `enableCache: true`
- Use faster models (e.g., gemini-flash)
- Enable ACCE for context compression
- Check metrics: `weavai.getMetrics()`

## License

MIT