Familiar-Connect

An AI "familiar" that joins Discord voice channels, listens to users, understands speech, and talks back using real AI voices.

Full documentation lives at docs/ — or browse the rendered site via uv run mkdocs serve.

Quickstart

uv sync --dev
cp .env.example .env                           # fill in your tokens
FAMILIAR_ID=aria uv run familiar-connect run

See Installation for the full prerequisites (libopus, Discord bot token, OpenRouter key, optional Cartesia key), env var reference, and side-model picking advice. See On-disk layout for the minimum data/familiars/<id>/ shape and character.toml examples.

Where things are

• Getting started — install, run, smoke-test, troubleshoot.
• Architecture — the context pipeline, memory directory, configuration model, security, design decisions.
• Guides — bootstrapping from SillyTavern character cards and lorebooks, Twitch integration.
• Roadmap — planned features (chattiness, voice input, session logging, web search, …).
• Contributing — dev workflow, TDD expectations, the ruff banned-api bootstrap-to-runtime rule, docs build.

Development commands

uv sync --dev                 # install + dev deps
uv run ruff check             # lint
uv run ruff format            # format
uv run ty check               # type-check
uv run pytest                 # run tests
uv run mkdocs serve           # preview the docs site