Contents
Getting started
The Àkàndé ecosystem
Library reference
Operational
Install
As a Python library
[dependencies]
akande = "^0.0.11"
# Core install : provider SDKs and mic capture are optional extras
pip install akande
# Full kit : every provider + microphone + MCP
pip install "akande[all,mic,mcp]"
From source
git clone https://github.com/sebastienrousseau/akande
cd akande
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
Requirements
| Requirement | Supported Version | Details |
|---|
| Python | >= 3.11 (tested on 3.11, 3.12, 3.13, 3.14) | Core runtime environment |
| PortAudio | >= 19 (optional) | Required for microphone audio input (akande[mic]) |
| FFmpeg | Any modern release (optional) | Required for MP3 / non-WAV audio transcoding |
| Platforms | Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), Windows | Platform-agnostic Python package |
Quick Start
import asyncio
import os
from akande.akande import Akande
from akande.providers.registry import get_provider
os.environ["LLM_PROVIDER"] = (
"ollama" # or openai, anthropic, google, claude_cli, etc.
)
async def main() -> None:
provider = get_provider()
assistant = Akande(openai_service=provider)
response = await assistant.generate_response(
"Provide a morning executive briefing on market trends."
)
print(response)
asyncio.run(main())
This runs the end-to-end Àkàndé pipeline: intent classification, safety wrapping, provider execution, and optional speech synthesis.
The Àkàndé ecosystem
Àkàndé provides a complete voice-first executive briefing stack across command-line, graphical terminal, REST, and protocol interfaces:
| Component | Purpose | Use case |
|---|
akande.pipeline | Core orchestration pipeline | Intent classification, safety envelopes, tool dispatch |
akande.server | REST and SSE streaming server | Web-based clients and HTTP streaming integrations |
akande.tui | Bubble Tea interactive terminal UI | Full-screen interactive terminal workflow |
akande.mcp | Model Context Protocol client and server | Exposing Àkàndé tools to Claude Desktop, Cursor, Continue |
Capabilities at a glance
| Area | Capability | Status |
|---|
| Providers | 11 LLM providers (OpenAI, Anthropic, Google, Claude CLI, Mistral, Cohere, etc.) | Production |
| Speech-to-Text | SpeechRecognition and Faster-Whisper backends | Production |
| Text-to-Speech | gTTS and local Kokoro-82M ONNX offline synthesis | Production |
| Safety & Audit | Input sanitization, safety envelopes, cryptographically verifiable PDF audits | Production |
| Compliance | EU AI Act Article 50 transparency and AudioSeal audio watermarking | Production |
Ecosystem comparison
| Project | Self-Hosted | Multi-Provider | Voice STT/TTS | Article 50 Audit |
|---|
| Àkàndé | Yes | 11 providers | Yes (Native) | Yes (Cryptographic) |
| Open-WebUI | Yes | Yes | Partial | No |
| LocalAI | Yes | Local only | Yes | No |
See docs/COMPARISON.md for the evidence and complete matrix.
Benchmarks
| Scenario | Result | Environment |
|---|
| Pipeline dispatch overhead | < 1.2 ms | Apple Silicon M3 / Python 3.13 |
| Watermark verification latency | < 18 ms | Apple Silicon M3 / 1s audio |
| Audio sanitization & safety wrapping | < 0.3 ms | Ubuntu 24.04 / Python 3.12 |
See docs/BENCHMARKS.md for methodology and full results.
Features
- 11 LLM Providers : Switch between OpenAI, Anthropic, Google Gemini, Claude Code CLI, Mistral, Cohere, Groq, Ollama, LM Studio, Azure, and Codex CLI.
- Safety Envelope : Strict transcript sanitization, control character stripping, length clamping, and
<user_input> boundary envelopes.
- SSRF Prevention : Built-in host validation restricting loopbacks, private RFC 1918 subnets, link-local addresses, and cloud metadata services.
- Regulatory Transparency : Full EU AI Act Article 50 compliance with machine-readable audit manifests and AudioSeal watermarking.
Configuration
Set configuration through environment variables or .env files:
# Provider selection
export LLM_PROVIDER=openai # anthropic, google, ollama, claude_cli, etc.
# Operational profile
export AKANDE_PROFILE=eu # eu (strict compliance) or default
# Audio configuration
export AKANDE_TTS=kokoro # gtts or kokoro
export AKANDE_STT=sr # sr or faster_whisper
Examples
Runnable examples demonstrating features:
When not to use Àkàndé
- Raw conversational chatbot : Àkàndé is optimized for structured, factual executive briefings and action synthesis rather than open-ended chit-chat.
- Ultra-low-latency telephony : Real-time sub-100ms voice agents require specialized WebRTC infrastructure; Àkàndé targets structured turn-taking.
Development
uv venv
uv pip install -e ".[all,dev]" mcp
uv run --extra dev pytest
uv run --extra dev ruff check .
All contributions must pass the verification gates (pytest with >= 95% coverage, ruff, mypy, bandit, pip-audit).
Security
Àkàndé enforces security best practices across input validation, network tools, and credential handling:
- Private IP and SSRF rejection on external fetch tools.
- Strict input sanitization and delimiter escaping on speech transcripts.
- Cryptographically signed audit manifests with SHA-256 sidecars.
Report vulnerabilities according to SECURITY.md.
Documentation
Stability guarantees
Àkàndé adheres to strict Semantic Versioning:
- Patch releases (0.0.x -> 0.0.y) : Backwards-compatible bug fixes and security patches.
- Breaking changes : Never introduced in patch releases. Deprecations documented at least one minor iteration in advance.
License
Dual-licensed under Apache-2.0 OR MIT at your option:
