Installation

Pick the surface you need. All three talk to the same API.

Hosted API — nothing to install

export VENKAI_API_KEY="vk_live_…"
curl -s https://api.venkai.fr/api/health

Any HTTP client works. See REST API.

Python SDK

Beta

The SDK is not published on PyPI. There is no pip install venkai today — install it from the repository:

git clone <your-venkai-checkout> venkai-src
cd venkai-src
pip install -r venkai/requirements.txt

Then make the package importable (add the checkout root to PYTHONPATH, or run from it):

from venkai.sdk.client import VenkaiClient

client = VenkaiClient(
    api_key="vk_live_…",
    base_url="https://api.venkai.fr",   # required: the default is localhost
    project="billing-service",
)

base_url defaults to http://127.0.0.1:8000

The SDK's default targets a local development server. Against the hosted API you must pass base_url="https://api.venkai.fr" explicitly, or every call fails with a connection error.

Full surface: Python SDK.

MCP server

Beta

Runs as a stdio MCP server and talks to the API over HTTP. Requires the same checkout plus the mcp package (already in venkai/requirements.txt).

.mcp.json

{
  "mcpServers": {
    "venkai": {
      "command": "python",
      "args": ["venkai/mcp/server.py"],
      "env": {
        "VENKAI_API_KEY": "vk_live_…",
        "VENKAI_BASE_URL": "https://api.venkai.fr"
      }
    }
  }
}

Full tool list: MCP.

Self-hosted API

Beta

cd venkai
cp .env.example .env      # then fill in the required secrets
docker compose up -d --build

See Docker for the compose topology, and Self-hosting for the full procedure including the external-network prerequisite.

Run the API directly (development)

cd venkai
pip install -r requirements.txt
export VENKAI_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
uvicorn venkai.api.main:app --port 8000

With no VENKAI_DATABASE_URL set, the API uses a local SQLite file — zero setup, and the right choice for trying things out. See Configuration.

Requirements

Python	3.13 (the production image is python:3.13-slim)
Database	SQLite for development, PostgreSQL for production
Optional	sentence-transformers + CPU torch, only for the semantic embedding provider (~80 MB model)