Semantic Kernel Custom Endpoint Integration Guide

Prerequisites

• A Fikra API key (fk_live_...) from the Fikra dashboard.
• Python 3.9+ or Node.js 18+.
• The semantic-kernel package (Python) or @microsoft/semantic-kernel (JavaScript).
• 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.

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example

Semantic Kernel supports OpenAI-compatible endpoints via the OpenAIChatCompletion service. Configure it to point to Fikra's base URL.

import os
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

# Initialize the kernel
kernel = Kernel()

# Configure the OpenAI-compatible connector for Fikra
service_id = "fikra_chat"
kernel.add_service(
    OpenAIChatCompletion(
        service_id=service_id,
        model_id="fikra-flash",
        api_key=os.environ["FIKRA_API_KEY"],
        base_url="https://api.fikraapi.co.ke/v1"
    )
)

# Use the service
prompt = "Explain the concept of semantic search in one sentence."
result = kernel.invoke_prompt(prompt, service_id=service_id)
print(result)

Streaming Guidance

Fikra supports streaming via Server-Sent Events (SSE) when stream: true is set. In Semantic Kernel, you can enable streaming by using the stream parameter in the prompt execution settings.

from semantic_kernel.contents import ChatMessageContent

# Enable streaming
streaming_result = kernel.invoke_prompt(
    prompt,
    service_id=service_id,
    execution_settings={"stream": True}
)

# Iterate over streamed chunks
for chunk in streaming_result:
    if chunk.content:
        print(chunk.content, end="", flush=True)

Common Errors

• 400 Bad Request: Malformed JSON, missing required fields, or invalid model alias. Verify that model is one of the listed Fikra aliases (e.g., fikra-flash).
• 401 Unauthorized: Missing or invalid Authorization: Bearer fk_live_... header. Ensure the API key is correctly set in the environment variable.
• 402 Payment Required: Insufficient token credits in your Fikra wallet. Top up via the Fikra dashboard using Paystack (M-Pesa or cards accepted).
• 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-side issue. Retry with backoff. Check the Fikra dashboard for status updates.

Production Checklist

• [ ] Use environment variables for API keys; never hardcode secrets.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token usage via the Fikra dashboard to avoid 402 errors.
• [ ] Validate model aliases against the current Fikra model registry before deployment.
• [ ] Test streaming behavior in staging to ensure SSE handling is robust.
• [ ] Log request IDs (if provided) for troubleshooting with Fikra support.