Installation¶

Prerequisites¶

uv
libopus for Discord voice (brew install opus, apt install libopus0, dnf install opus, or pacman -S opus)
A Discord application + bot token (portal) with the message_content, messages, and voice_states intents enabled
An OpenRouter API key
(optional, voice only) One of: Azure Cognitive Services key + region, a Cartesia API key, or a Google Gemini API key
(optional, voice only) A Deepgram API key for speech transcription

Environment variables¶

Create a .env in the repo root (loaded on startup). Only install-wide secrets and the active-familiar selector live here; everything tunable about the familiar — LLM model, TTS voice — lives in data/familiars/<id>/character.toml.

# required
DISCORD_BOT=<discord bot token>
OPENROUTER_API_KEY=<openrouter key>

# pick the familiar to load (or pass --familiar on the CLI)
FAMILIAR_ID=aria

# TTS credentials — set the one matching [tts].provider in character.toml

# Azure Speech (default provider):
AZURE_SPEECH_KEY=<azure cognitive services key>
AZURE_SPEECH_REGION=<azure region, e.g. eastus>

# Cartesia (provider="cartesia"):
CARTESIA_API_KEY=<cartesia key>

# Google Gemini TTS (provider="gemini"):
GOOGLE_API_KEY=<google ai studio key>

# optional — Deepgram speech transcription (voice channels only)
DEEPGRAM_API_KEY=<deepgram key>

Per-familiar model choice¶

LLM model selection is per-call-site, in the familiar's character.toml under [llm.<slot>] tables. Three tiered slots ship today: fast (voice), prose (text replies), and background (summaries / fact extraction / dossiers). See Tuning — LLM slots for the schema.

The reference profile at data/familiars/_default/character.toml fills each slot with a sensible default. A user's own character.toml only overrides the fields it wants to change. Copy the default to start a new familiar:

cp -r data/familiars/_default data/familiars/my-familiar
# then edit data/familiars/my-familiar/character.toml

Start¶

uv sync --dev
uv run familiar-connect run
uv run familiar-connect run --familiar aria
uv run familiar-connect -vv run --familiar aria

run resolves the active familiar via --familiar first, then FAMILIAR_ID. -v / -vv / -vvv tune logging verbosity.

CLI reference¶

Help text below is generated at build time from the argparse parser in src/familiar_connect/cli.py. Run uv run familiar-connect --help locally for the same output.

usage: familiar-connect [-h] [--version] [-v] {run,diagnose,version} ...

familiar-connect CLI tool

positional arguments:
  {run,diagnose,version}
                        Available commands
    run                 Start the Discord bot
    diagnose            Aggregate span timings from log files
    version             Display package version

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v, --verbose         Increase verbosity (can be repeated: -v, -vv, -vvv)

usage: familiar-connect run [-h] [--familiar ID]

Start the familiar and connect to Discord

options:
  -h, --help     show this help message and exit
  --familiar ID  Folder name of the character to run (under data/familiars/).
                 Overrides FAMILIAR_ID.

Once the bot is online, see Slash commands for the subscription surface.