Extend

Contributing

Set up the repository, run the tests for the part you change, and open a small pull request against main.

Set up the Python package

Install Python 3.11+ and uv. The repository root is the package.

Package development

git clone https://github.com/sleeptalklabs/sleeptalk.git
cd sleeptalk
uv sync --dev --all-extras
uv run pytest

The terminal extra needs PortAudio (brew install portaudio or sudo apt install libportaudio2). Discord voice needs libopus (brew install opus or sudo apt install libopus0).

Run sleeptalk trust once in your checkout so its config/profiles/ is used instead of ~/.sleeptalk. Keep operator profiles under config/profiles/ local; never commit them.

Work on browser pages and the hosted service

With Node.js 22+:

Call pages and hosted relay

cd rendezvous
npm ci
npm test
npm run build

Directory	What it holds
`rendezvous/web/`	The browser call page, and the shell that loads the settings page on a phone
`rendezvous/src/`	The hosted relay, a Cloudflare Worker
`remote-entry-web/`	The page for paired remote setup (`host remote`)
`sleeptalk/_settings/`	The settings page, on the host, on a phone, and for agent key requests
`sleeptalk/_setup/`	`providers.json`, the free-usage and card facts the settings page shows

The browser builds land in the Python package (sleeptalk/_web/ and sleeptalk/_remote_entry/), and those built files are tracked.

To walk an agent's key request on the settings page in your own browser, against a throwaway host that accepts any key and fakes Discord:

Preview a key request

uv run python scripts/preview_setup_page.py --mode open

Other modes are preferred, fixed, reuse, and discord. Add --page local for the page as the host's own browser serves it.

Run the checks

Test suites

uv run pytest
uv run pytest scripts/test_audit_release_contents.py
(cd rendezvous && npm test && npm run build)

For packaging changes, bash scripts/prove_release_wheel.sh builds the wheel and source archive, checks every file against tracked inputs, installs into a blank environment, and runs package-only web and host checks.

sleeptalk eval contract runs the public contract tests. sleeptalk eval health --log PATH checks a session trace. Conformance verifies what an adapter advertises; a real voice trial verifies what the caller hears. Keep those results separate.

Where things live

Conversation turn ownership: RealtimeSession in sleeptalk/session.py.
Cascade speech behavior: VoicePolicyRuntime in sleeptalk/voice_policy_runtime.py.
A new agent: the adapter contract and component registration. For your own agent outside the repository, see Custom agents.

Open a pull request

Branch from main.
Make the smallest change that proves the fix or feature.
Run the suites that cover what you touched, and say what you ran in the pull request.
Use an imperative commit subject, for example fix(call): reject a reused ticket.

Live microphone, Discord speech, and sleeptalk run checks stay with a person; automated output does not replace them. Read the contributing guide for the full rules and report security problems through the security policy.