Integrating Fikra API with Gradio

Prerequisites

• Python 3.9 or later.
• gradio and openai Python packages installed.
• A Fikra API key (fk_live_...) generated from the Fikra dashboard.
• Access to the Fikra API base URL: https://api.fikraapi.co.ke/v1.

Environment Variable Setup

Store your API key in an environment variable to avoid hardcoding secrets. For example, in your shell or .env file:

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example

Gradio does not have a native Fikra SDK, but it integrates seamlessly with the openai Python client because Fikra API is OpenAI-compatible. Below is a minimal Gradio app that calls fikra-flash.

import os
import gradio as gr
from openai import OpenAI

# Initialize the OpenAI 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")
)

def respond(message: str) -> str:
    try:
        completion = client.chat.completions.create(
            model="fikra-flash",
            messages=[
                {"role": "user", "content": message}
            ]
        )
        return completion.choices[0].message.content
    except Exception as e:
        return f"Error: {str(e)}"

# Define the Gradio interface
interface = gr.Interface(
    fn=respond,
    inputs=gr.Textbox(label="Enter your prompt"),
    outputs=gr.Textbox(label="Response"),
    title="Fikra API Gradio Demo"
)

if __name__ == "__main__":
    interface.launch()

Streaming Guidance

Fikra API supports streaming via Server-Sent Events (SSE) when stream: true is set. In Gradio, you can use a generator function to yield chunks as they arrive.

def stream_respond(message: str):
    try:
        stream = client.chat.completions.create(
            model="fikra-flash",
            messages=[
                {"role": "user", "content": message}
            ],
            stream=True
        )
        for chunk in stream:
            if chunk.choices and chunk.choices[0].delta.content:
                yield chunk.choices[0].delta.content
    except Exception as e:
        yield f"\nError: {str(e)}"

# Update the interface to use streaming
interface = gr.Interface(
    fn=stream_respond,
    inputs=gr.Textbox(label="Enter your prompt"),
    outputs=gr.Textbox(label="Response"),
    title="Fikra API Gradio Streaming Demo"
)

Common Errors

• 400 Bad Request: Malformed JSON, missing required fields, or invalid model alias. Verify that model is one of the public Fikra aliases (e.g., fikra-flash).
• 401 Unauthorized: Invalid or missing API key. Ensure Authorization: Bearer fk_live_... is correctly set via the api_key parameter.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up via the Fikra dashboard using Paystack (M-Pesa or cards).
• 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

• [ ] Use environment variables for FIKRA_API_KEY; never hardcode secrets.
• [ ] Validate model aliases against the current Fikra model registry before deployment.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard to avoid 402 errors.
• [ ] Test streaming behavior under load to ensure SSE chunks are handled correctly in Gradio.
• [ ] Restrict Gradio app access if exposing publicly (e.g., via reverse proxy or authentication).
• [ ] Log request IDs and error codes for debugging, but avoid logging sensitive user content.