Metadata-Version: 2.4
Name: akande
Version: 0.0.10
Summary: A self-hosted, provider-agnostic voice assistant that delivers structured executive briefings via voice or text from 11 LLM providers.
Author-email: Sebastien Rousseau <sebastian.rousseau@gmail.com>
License-Expression: Apache-2.0 OR MIT
Project-URL: Homepage, https://akande.co
Project-URL: Repository, https://github.com/sebastienrousseau/akande
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Requires-Dist: openai<2,>=1.50
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: gtts>=2.5.0
Requires-Dist: reportlab>=4.1.0
Requires-Dist: speechrecognition>=3.10.1
Requires-Dist: cherrypy>=18.8.0
Requires-Dist: pydub>=0.25.1
Requires-Dist: textual<8,>=0.80
Requires-Dist: cryptography<51,>=48.0.1
Provides-Extra: mic
Requires-Dist: pyaudio>=0.2.14; extra == "mic"
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=0.40; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-generativeai<1,>=0.7; extra == "google"
Provides-Extra: mistral
Requires-Dist: mistralai<4,>=1.0; extra == "mistral"
Provides-Extra: cohere
Requires-Dist: cohere<8,>=5.13; extra == "cohere"
Provides-Extra: huggingface
Requires-Dist: huggingface_hub<3,>=0.24; extra == "huggingface"
Provides-Extra: offline-tts
Requires-Dist: pyttsx4>=3.0.0; extra == "offline-tts"
Provides-Extra: groq
Requires-Dist: groq<2,>=0.11; extra == "groq"
Provides-Extra: redis
Requires-Dist: redis<9,>=5.0; extra == "redis"
Provides-Extra: tts-local
Requires-Dist: kokoro-onnx<1,>=0.4; extra == "tts-local"
Provides-Extra: watermark
Requires-Dist: audioseal<1,>=0.1; extra == "watermark"
Requires-Dist: torch>=2.1; extra == "watermark"
Requires-Dist: torchaudio>=2.1; extra == "watermark"
Requires-Dist: numpy>=1.26; extra == "watermark"
Provides-Extra: redact
Requires-Dist: presidio-analyzer<3,>=2.2; extra == "redact"
Provides-Extra: memory
Requires-Dist: mem0ai<1,>=0.1; extra == "memory"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=0.9; extra == "mcp"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "telemetry"
Provides-Extra: all
Requires-Dist: anthropic<2,>=0.40; extra == "all"
Requires-Dist: google-generativeai<1,>=0.7; extra == "all"
Requires-Dist: mistralai<4,>=1.0; extra == "all"
Requires-Dist: cohere<8,>=5.13; extra == "all"
Requires-Dist: huggingface_hub<3,>=0.24; extra == "all"
Requires-Dist: groq<2,>=0.11; extra == "all"
Requires-Dist: pyttsx4>=3.0.0; extra == "all"
Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov<8,>=5.0; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1.0; extra == "dev"
Requires-Dist: pytest-mock<4,>=3.12; extra == "dev"
Requires-Dist: respx<1,>=0.21; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: mypy<3,>=1.10; extra == "dev"
Requires-Dist: bandit<2,>=1.7; extra == "dev"
Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: hypothesis<7,>=6.100; extra == "dev"
Requires-Dist: anthropic<2,>=0.40; extra == "dev"
Requires-Dist: google-generativeai<1,>=0.7; extra == "dev"
Requires-Dist: mistralai<4,>=1.0; extra == "dev"
Requires-Dist: cohere<8,>=5.13; extra == "dev"
Requires-Dist: huggingface_hub<3,>=0.24; extra == "dev"
Requires-Dist: groq<2,>=0.11; extra == "dev"
Requires-Dist: pyttsx4>=3.0.0; extra == "dev"
Requires-Dist: mcp<3,>=0.9; extra == "dev"
Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "dev"
Dynamic: license-file

<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
<!--
README template. Global rules: see ~/Code/AGENTS.md and ~/Code/REPO-STANDARD.md.
Releases adhere strictly to https://github.com/sebastienrousseau/passmcp/releases/tag/v0.0.5
-->

<p align="center">
  <img src="https://cloudcdn.pro/clients/akande/v1/logos/akande.svg" alt="Àkàndé logo" width="128" />
</p>

<h1 align="center">Àkàndé</h1>

<p align="center">
  A self-hosted, provider-agnostic voice assistant that delivers structured executive briefings via voice or text from 11 LLM providers.
</p>

<p align="center">
  <a href="https://github.com/sebastienrousseau/akande/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/akande/ci.yml?branch=main&style=for-the-badge&logo=github&label=Build" alt="Build" /></a>
  <a href="https://pypi.org/project/akande/"><img src="https://img.shields.io/pypi/v/akande?style=for-the-badge&color=fc8d62&logo=pypi" alt="Registry" /></a>
  <a href="docs/README.md"><img src="https://img.shields.io/badge/docs-reference-blue.svg?style=for-the-badge&labelColor=555555&logo=read-the-docs" alt="Docs" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/akande"><img src="https://img.shields.io/badge/OpenSSF%20Scorecard-Monitored-blue?style=for-the-badge&logo=openssf" alt="OpenSSF Scorecard" /></a>
  <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" /></a>
  <a href="docs/POLICIES.md"><img src="https://img.shields.io/badge/python->=3.10-93450a.svg?style=for-the-badge&logo=python" alt="Python >= 3.10" /></a>
</p>

<p align="center">
  <img src=".github/demo.gif" alt="Àkàndé Demo" width="100%" />
</p>

---

## Contents

**Getting started**

- [Install](#install) : PyPI, source, system dependencies
- [Requirements](#requirements) : toolchain floor, platforms
- [Quick Start](#quick-start) : voice briefing in ten lines

**The Àkàndé ecosystem**

- [The Àkàndé ecosystem](#the-àkàndé-ecosystem) : core CLI, web server, MCP, and TUI modules

**Library reference**

- [Capabilities at a glance](#capabilities-at-a-glance) : the current surface by theme
- [Ecosystem comparison](#ecosystem-comparison) : short matrix; full table at [`docs/COMPARISON.md`](docs/COMPARISON.md)
- [Benchmarks](#benchmarks) : headline numbers; full table at [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)
- [Features](#features) : module-level capability list
- [Configuration](#configuration) : core options
- [Examples](#examples) : runnable example index

**Operational**

- [When not to use Àkàndé](#when-not-to-use-àkàndé) : limitations
- [Development](#development) : make targets, fuzzing, CI
- [Security](#security) : guarantees and compliance
- [Documentation](#documentation) : all reference docs
- [Stability guarantees](#stability-guarantees) : SemVer axis, output stability, minimum toolchain discipline
- [License](#license)

---

## Install

### As a Python library

```toml
[dependencies]
akande = "^0.0.10"
```

```bash
# 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

```bash
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.10` (tested on 3.10, 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

```python
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`](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`](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:

```bash
# 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:

- [`examples/basic_briefing.py`](examples/basic_briefing.py) : Simple 10-line text briefing.
- [`examples/voice_interaction.py`](examples/voice_interaction.py) : Interactive microphone capture and voice synthesis.
- [`examples/mcp_server.py`](examples/mcp_server.py) : Connecting Àkàndé tools to an MCP host.

---

## 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

```bash
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`](SECURITY.md).

---

## Documentation

- [User Guide](docs/README.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Policies & Gates](docs/POLICIES.md)
- [Development Guide](DEVELOPMENT.md)

---

## 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:
- [Apache License, Version 2.0](LICENSE-APACHE)
- [MIT License](LICENSE-MIT)
