Skip to main content

🔧 Advanced Usage Guide

This guide covers advanced features and capabilities of OKai, including complex integrations, custom services, and specialized plugins.

Service Integration​

Video Processing Service​

OKai supports advanced video processing capabilities through the VideoService:

import { VideoService } from "@okcashpro/okai/plugin-node";

// Initialize service
const videoService = new VideoService();

// Process video content
const result = await videoService.processVideo(url, runtime);

Key features:

  • Automatic video downloading
  • Transcription support
  • Subtitle extraction
  • Cache management
  • Queue processing

Image Processing​

The ImageDescriptionService provides advanced image analysis:

import { ImageDescriptionService } from "@okcashpro/okai/plugin-node";

const imageService = new ImageDescriptionService();
const description = await imageService.describeImage(imageUrl, "gpu", runtime);

Features:

  • Local and cloud processing options
  • CUDA acceleration support
  • Automatic format handling
  • GIF frame extraction

Blockchain Integration​

Solana Integration​

The Solana plugin provides comprehensive blockchain functionality:

import { solanaPlugin } from "@okcashpro/okai/plugin-solana";

// Initialize plugin
runtime.registerPlugin(solanaPlugin);

Token Operations​

// Buy tokens
const swapResult = await swapToken(
  connection,
  walletPublicKey,
  inputTokenCA,
  outputTokenCA,
  amount,
);

// Sell tokens
const sellResult = await sellToken({
  sdk,
  seller: walletKeypair,
  mint: tokenMint,
  amount: sellAmount,
  priorityFee,
  allowOffCurve: false,
  slippage: "1",
  connection,
});

Trust Score System​

const trustScoreManager = new TrustScoreManager(tokenProvider, trustScoreDb);

// Generate trust scores
const score = await trustScoreManager.generateTrustScore(
  tokenAddress,
  recommenderId,
  recommenderWallet,
);

// Monitor trade performance
await trustScoreManager.createTradePerformance(runtime, tokenAddress, userId, {
  buy_amount: amount,
  is_simulation: false,
});

Custom Services​

Speech Generation​

Implement text-to-speech capabilities:

class SpeechService extends Service implements ISpeechService {
  async generate(runtime: IAgentRuntime, text: string): Promise<Readable> {
    if (runtime.getSetting("ELEVENLABS_XI_API_KEY")) {
      return textToSpeech(runtime, text);
    }

    const { audio } = await synthesize(text, {
      engine: "vits",
      voice: "en_US-hfc_female-medium",
    });

    return Readable.from(audio);
  }
}

PDF Processing​

Handle PDF document analysis:

class PdfService extends Service {
  async convertPdfToText(pdfBuffer: Buffer): Promise<string> {
    const pdf = await getDocument({ data: pdfBuffer }).promise;
    const numPages = pdf.numPages;
    const textPages = [];

    for (let pageNum = 1; pageNum <= numPages; pageNum++) {
      const page = await pdf.getPage(pageNum);
      const textContent = await page.getTextContent();
      const pageText = textContent.items
        .filter(isTextItem)
        .map((item) => item.str)
        .join(" ");
      textPages.push(pageText);
    }

    return textPages.join("\n");
  }
}

Advanced Memory Management​

Retrievable Memory System​

class MemoryManager {
  async getMemories({
    agentId,
    roomId,
    count,
  }: {
    agentId: string;
    roomId: string;
    count: number;
  }): Promise<Memory[]> {
    // Implement memory retrieval logic
  }

  async createMemory(
    memory: Memory,
    allowDuplicates: boolean = false,
  ): Promise<void> {
    // Implement memory storage logic
  }
}

Trust Score Database​

Implement advanced scoring systems:

class TrustScoreDatabase {
  async calculateValidationTrust(tokenAddress: string): number {
    const sql = `
      SELECT rm.trust_score
      FROM token_recommendations tr
      JOIN recommender_metrics rm ON tr.recommender_id = rm.recommender_id
      WHERE tr.token_address = ?;
    `;

    const rows = this.db.prepare(sql).all(tokenAddress);
    if (rows.length === 0) return 0;

    const totalTrust = rows.reduce((acc, row) => acc + row.trust_score, 0);
    return totalTrust / rows.length;
  }
}

Plugin Development​

Creating Custom Plugins​

const customPlugin: Plugin = {
  name: "custom-plugin",
  description: "Custom Plugin for OKai",
  actions: [
    // Custom actions
  ],
  evaluators: [
    // Custom evaluators
  ],
  providers: [
    // Custom providers
  ],
};

Advanced Action Development​

export const complexAction: Action = {
  name: "COMPLEX_ACTION",
  similes: ["ALTERNATIVE_NAME", "OTHER_NAME"],
  validate: async (runtime: IAgentRuntime, message: Memory) => {
    // Implement validation logic
    return true;
  },
  handler: async (
    runtime: IAgentRuntime,
    message: Memory,
    state: State,
    options: { [key: string]: unknown },
    callback?: HandlerCallback,
  ): Promise<boolean> => {
    // Implement complex handling logic
    return true;
  },
};

Advanced Configuration​

Custom Runtime Configuration​

const customRuntime = new AgentRuntime({
  databaseAdapter: new PostgresDatabaseAdapter(config),
  modelProvider: new OpenAIProvider(apiKey),
  plugins: [solanaPlugin, customPlugin],
  services: [
    new VideoService(),
    new ImageDescriptionService(),
    new SpeechService(),
  ],
});

Advanced Model Configuration​

const modelConfig = {
  modelClass: ModelClass.LARGE,
  temperature: 0.7,
  maxTokens: 2000,
  topP: 0.9,
  frequencyPenalty: 0.5,
  presencePenalty: 0.5,
};

const response = await generateText({
  runtime,
  context: prompt,
  ...modelConfig,
});

Performance Optimization​

Caching Strategy​

class CacheManager {
  private cache: NodeCache;
  private cacheDir: string;

  constructor() {
    this.cache = new NodeCache({ stdTTL: 300 });
    this.cacheDir = path.join(__dirname, "cache");
    this.ensureCacheDirectoryExists();
  }

  private async getCachedData<T>(key: string): Promise<T | null> {
    // Implement tiered caching strategy
  }
}

Queue Management​

class QueueManager {
  private queue: string[] = [];
  private processing: boolean = false;

  async processQueue(): Promise<void> {
    if (this.processing || this.queue.length === 0) {
      return;
    }

    this.processing = true;
    while (this.queue.length > 0) {
      const item = this.queue.shift();
      await this.processItem(item);
    }
    this.processing = false;
  }
}

Best Practices​

Error Handling​

try {
  const result = await complexOperation();
  if (!result) {
    throw new Error("Operation failed");
  }
  return result;
} catch (error) {
  console.error("Error in operation:", error);
  await errorReporting.log(error);
  throw new OperationalError("Failed to complete operation", { cause: error });
}

Resource Management​

class ResourceManager {
  private resources: Map<string, Resource> = new Map();

  async acquire(id: string): Promise<Resource> {
    // Implement resource acquisition with timeout
  }

  async release(id: string): Promise<void> {
    // Implement resource cleanup
  }
}

Troubleshooting​

Common Issues​

  1. Memory Leaks

    • Monitor memory usage
    • Implement proper cleanup
    • Use WeakMap for caching

  2. Performance Bottlenecks

    • Profile slow operations
    • Implement batching
    • Use connection pooling

  3. Integration Issues

    • Verify API credentials
    • Check network connectivity
    • Validate request formatting

Debugging​

const debug = require("debug")("okai:advanced");

debug("Detailed operation info: %O", {
  operation: "complexOperation",
  parameters: params,
  result: result,
});

Further Resources​