Chainlit OpenAI Proxy Backend Integration Guide

Prerequisites

• Python 3.9+ 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.
• Chainlit installed in your project environment.

Environment Variable Setup

Chainlit uses the openai Python package under the hood for its OpenAI-compatible backend. You must configure the environment variables to point to the Fikra API.

1. Create a .env file in your project root or export the variables in your shell.
2. Set the following variables:

OPENAI_API_KEY=your_fikra_api_key_here
OPENAI_API_BASE=https://api.fikraapi.co.ke/v1

Note: Chainlit may also respect OPENAI_BASE_URL depending on the version. Ensure the base URL ends with /v1.

Python Example: Configuring Chainlit

Chainlit’s @cl.on_message handler can be configured to use the Fikra API by setting the openai client parameters. Below is a minimal app.py example.

import chainlit as cl
import os
from openai import OpenAI

# Initialize the OpenAI client pointing to Fikra API
client = OpenAI(
    api_key=os.environ.get("FIKRA_API_KEY"),
    base_url="https://api.fikraapi.co.ke/v1"
)

@cl.on_message
async def main(message: str):
    try:
        # Use fikra-flash as the default model
        response = client.chat.completions.create(
            model="fikra-flash",
            messages=[
                {"role": "user", "content": message}
            ],
            stream=False
        )

        reply = response.choices[0].message.content
        await cl.Message(content=reply).send()
    except Exception as e:
        await cl.Message(content=f"Error: {str(e)}").send()

Note: Ensure FIKRA_API_KEY is set in your environment. The openai package is used here because Chainlit’s OpenAI backend relies on it. If you are using a newer version of Chainlit that abstracts this, check the chainlit.config or openai settings in your config.toml.

Streaming Guidance

To enable streaming, set stream=True in the request. Chainlit supports streaming responses via Server-Sent Events (SSE).

@cl.on_message
async def main_stream(message: str):
    try:
        response = client.chat.completions.create(
            model="fikra-flash",
            messages=[
                {"role": "user", "content": message}
            ],
            stream=True
        )

        msg = cl.Message(content="")
        await msg.send()

        for chunk in response:
            if chunk.choices and chunk.choices[0].delta.content:
                await msg.stream_token(chunk.choices[0].delta.content)

        await msg.update()
    except Exception as e:
        await cl.Message(content=f"Error: {str(e)}").send()

Common Errors

• 400 Bad Request: Malformed request body or invalid model alias. Verify that model is one of the listed 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.
• 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.

Production Checklist

• [ ] Use https://api.fikraapi.co.ke/v1 as the base URL.
• [ ] Store API keys in environment variables, not in code.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard.
• [ ] Test with stream=True to ensure SSE handling is correct in your frontend.
• [ ] Verify model availability in the Fikra model registry before deploying.