Integrating Fikra API with Flowise Custom LLM Node

Prerequisites

• A Fikra API key (fk_live_...) generated from the Fikra dashboard.
• Flowise installed and running locally or in your deployment environment.
• Node.js environment compatible with Flowise.
• Access to the Fikra API base URL: https://api.fikraapi.co.ke/v1.

Environment Variable Setup

Flowise supports custom environment variables. Set the following in your .env file or Flowise environment configuration:

FIKRA_API_KEY=fk_live_your_key_here
FIKRA_BASE_URL=https://api.fikraapi.co.ke/v1

Custom LLM Node Configuration

Flowise is not natively OpenAI-compatible in its default LLM nodes, but it supports Custom LLM nodes that allow you to define arbitrary HTTP requests. Since Fikra API uses an OpenAI-style chat-completions interface, you can configure a custom node to call Fikra directly.

JavaScript Example (Flowise Custom LLM Node)

Create a custom LLM node in Flowise with the following logic. This example uses fetch (Node.js 18+) to call the Fikra API:

import { ICommonObject } from '@flowiseai/flowise';

export class FikraLLM extends ICommonObject {
  name: string = 'FikraLLM';
  displayName: string = 'Fikra LLM';
  description: string = 'Custom LLM node for Fikra API';
  baseClasses: string[] = ['FikraLLM'];

  constructor(private options: ICommonObject) {
    super();
  }

  async call(input: string): Promise<string> {
    const apiKey = process.env.FIKRA_API_KEY;
    const baseUrl = process.env.FIKRA_BASE_URL || 'https://api.fikraapi.co.ke/v1';

    const response = await fetch(`${baseUrl}/chat/completions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'fikra-flash',
        messages: [
          { role: 'user', content: input }
        ],
        stream: false
      })
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Fikra API error: ${response.status} - ${errorText}`);
    }

    const data = await response.json();
    return data.choices[0].message.content;
  }
}

Register this node in your Flowise custom nodes directory and select it in your workflow.

Streaming Guidance

Fikra API supports streaming via stream: true and Server-Sent Events (SSE). In a custom Flowise node, you can handle streaming by reading the response body as a stream:

async callStream(input: string): Promise<AsyncGenerator<string>> {
  const apiKey = process.env.FIKRA_API_KEY;
  const baseUrl = process.env.FIKRA_BASE_URL || 'https://api.fikraapi.co.ke/v1';

  const response = await fetch(`${baseUrl}/chat/completions`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'fikra-flash',
      messages: [
        { role: 'user', content: input }
      ],
      stream: true
    })
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Fikra API error: ${response.status} - ${errorText}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const chunk = decoder.decode(value);
    // Parse SSE lines: lines starting with 'data: ' contain JSON chunks
    for (const line of chunk.split('\n')) {
      if (line.startsWith('data: ')) {
        const jsonStr = line.slice(6).trim();
        if (jsonStr === '[DONE]') return;
        try {
          const parsed = JSON.parse(jsonStr);
          const delta = parsed.choices[0]?.delta?.content;
          if (delta) yield delta;
        } catch (e) {
          // Ignore malformed chunks
        }
      }
    }
  }
}

Note: Flowise’s built-in streaming support may require additional configuration depending on your version. Test streaming in a minimal Flowise workflow before integrating into production.

Common Errors

Production Checklist

• [ ] Store FIKRA_API_KEY in a secure environment variable, not in code.
• [ ] Use fikra-flash for low-latency tasks; check the model registry for other aliases if needed.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard to avoid 402 errors.
• [ ] Test streaming in a staging environment before enabling in production.
• [ ] Validate that your Flowise version supports custom LLM nodes and SSE streaming.
• [ ] Log request IDs (if provided in responses) for debugging.
• [ ] Do not hardcode API keys or base URLs in version-controlled code.