Integrating Fikra API with Llama.cpp

Prerequisites

• A Fikra API key (fk_live_...) generated from the Fikra dashboard.
• Python 3.8+ or Node.js 18+.
• The openai Python package or axios/fetch for JavaScript.
• Access to the Fikra API base URL: https://api.fikraapi.co.ke/v1.

Important Note on Llama.cpp Compatibility

Llama.cpp is a local inference engine and does not natively support OpenAI-compatible remote API endpoints via its standard CLI or server configuration. It is designed to run models locally. Therefore, you cannot simply point Llama.cpp to Fikra API as a "replacement" in the sense of configuring Llama.cpp to proxy requests to Fikra.

Instead, this guide demonstrates how to use the OpenAI-compatible interface of Fikra API directly in your application code, which is the standard way to integrate with Fikra. If you are currently using Llama.cpp for local inference and wish to switch to Fikra's hosted models, you should replace your local inference calls with direct HTTP calls to the Fikra API using an OpenAI-compatible client.

Environment Variable Setup

Store your Fikra API key in an environment variable to avoid hardcoding secrets.

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example

Use the openai Python package, which is compatible with Fikra's OpenAI-style interface.

import os
from openai import OpenAI

# Initialize the client with Fikra's base URL and API key
client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

# Make a chat completion request
response = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, Fikra!"}
    ]
)

print(response.choices[0].message.content)

Streaming Guidance

Fikra supports streaming via Server-Sent Events (SSE) when stream: true is set. This is useful for real-time UI updates.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

# Enable streaming
stream = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Common Errors

• 400 Bad Request: Malformed request body, invalid model alias, or missing required fields. Check the model registry for valid aliases.
• 401 Unauthorized: Invalid or missing API key. Ensure Authorization: Bearer fk_live_... is correctly set.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up via Paystack (M-Pesa or cards) in the dashboard.
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM. Implement exponential backoff.
• 503 Service Unavailable: Temporary server issue. Retry with backoff. Check the Fikra dashboard for status updates.

Production Checklist

1. Use Environment Variables: Never hardcode API keys in source code.
2. Implement Retry Logic: Handle 429 and 503 errors with exponential backoff.
3. Monitor Token Usage: Track credit consumption in the Fikra dashboard to avoid 402 errors.
4. Validate Model Aliases: Use only listed Fikra aliases (e.g., fikra-flash, fikra-pro-20b). Check the model registry for availability.
5. Secure Endpoints: Ensure your application does not expose the Fikra API key to client-side code.
6. Test Streaming: Verify SSE handling in your frontend or backend to ensure smooth user experience.
7. Rate Limit Awareness: Design your application to respect the 30 RPM (unverified) or 100 RPM (trusted) limits.
8. Billing Integration: Ensure your users can top up their wallets via Paystack to maintain service continuity.