@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:

npm install @pixora/pixolink

Or install separately:

npm install @pixora/pixolink-weavai

Configuration

Add to your pixo.config.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

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

// 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

// 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

// 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

// 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)

// 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)

// 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

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

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

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

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

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

Error Handling

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

// 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:

{
  "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