Integrating Fikra API with Streamlit

Prerequisites

• Python 3.9 or later.
• streamlit 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 local development, you can use a .env file or export it in your shell:

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example

Streamlit applications can use the openai Python SDK directly because Fikra API implements an OpenAI-compatible chat-completions interface. Configure the client with the Fikra base URL and API key.

import os
import streamlit as st
from openai import OpenAI

# Initialize the client with Fikra API settings
client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

st.title("Fikra API Chat")

# Initialize chat history
if "messages" not in st.session_state:
    st.session_state.messages = []

# Display existing messages
for message in st.session_state.messages:
    with st.chat_message(message["role"]):
        st.markdown(message["content"])

# User input
if prompt := st.chat_input("Type a message..."):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    # Call Fikra API
    with st.chat_message("assistant"):
        response = client.chat.completions.create(
            model="fikra-flash",
            messages=st.session_state.messages
        )
        response_text = response.choices[0].message.content
        st.markdown(response_text)
        st.session_state.messages.append({"role": "assistant", "content": response_text})

Streaming Guidance

Fikra API supports streaming via Server-Sent Events (SSE) when stream: true is set. In the openai Python SDK, use the stream=True parameter and iterate over the response chunks.

# Replace the non-streaming call with:
with st.chat_message("assistant"):
    stream = client.chat.completions.create(
        model="fikra-flash",
        messages=st.session_state.messages,
        stream=True
    )

    full_response = ""
    for chunk in stream:
        if chunk.choices and chunk.choices[0].delta.content:
            token = chunk.choices[0].delta.content
            full_response += token
            st.write(token)

    st.session_state.messages.append({"role": "assistant", "content": full_response})

Common Errors

• 400 Bad Request: Malformed request body or invalid parameters. Verify that model is a valid Fikra alias (e.g., fikra-flash) and that the messages array is correctly formatted.
• 401 Unauthorized: Missing or invalid API key. Ensure the Authorization: Bearer fk_live_... header is correctly set using the FIKRA_API_KEY environment variable.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up your account 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 in your application.
• 503 Service Unavailable: Temporary server-side issue. Retry the request with backoff. Check the Fikra dashboard for any service announcements.

Production Checklist

• [ ] Store FIKRA_API_KEY in a secure environment variable or secret manager; never hardcode it.
• [ ] Use fikra-flash for low-latency tasks; check the model registry for other aliases like fikra-pro-20b if higher quality is needed.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard to avoid 402 errors.
• [ ] Validate user input to prevent prompt injection or malformed requests.
• [ ] Test streaming behavior in production to ensure SSE connections are handled correctly by your web server.