chore: open-source readiness pass

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing
+
+Thanks for your interest in `live-streamer`. This is a working demo project — the
+bar for contributions is "keep it running and keep the sync tight."
+
+## Repository layout
+
+The repo is four independent Python packages, each with its own `uv`-managed
+virtualenv and its own `pytest` suite:
+
+| Package | What it does |
+|---|---|
+| `stream_orchestrator/` | M1 — HeyGen Avatar Realtime session lifecycle + HTTP/SSE contract + OBS browser sources |
+| `showrunner/` | The content brain — LLM scene planner, Playwright browser executor, cue scheduler |
+| `chat_ingester/` | Twitch chat reader → URL filter → SQLite queue the showrunner consumes |
+| `script_producer/` | Minimal library slice imported by the showrunner (`word_tracker`, `markers`, `cues`, …) |
+
+## Prerequisites
+
+- **Python 3.11** (every package pins `requires-python = ">=3.11"`)
+- **[uv](https://github.com/astral-sh/uv)** for dependency and venv management
+- **Playwright + Chromium** (for the showrunner): `uv run playwright install chromium`
+- **OBS Studio** with the obs-websocket plugin (for the streaming/egress path)
+- A **HeyGen** API key (Avatar Realtime) and an **Anthropic** API key
+
+## Setup
+
+```bash
+# 1. Copy the env template and fill in your keys
+cp .env.example .env && $EDITOR .env      # HEYGEN_API_KEY + ANTHROPIC_API_KEY at minimum
+
+# 2. Create each package's venv (run inside each package directory)
+cd stream_orchestrator && uv sync && cd ..
+cd showrunner          && uv sync && uv run playwright install chromium && cd ..
+cd chat_ingester       && uv sync && cd ..
+cd script_producer     && uv sync && cd ..
+```
+
+## Running the tests
+
+Each package has its own suite. Run from inside the package directory:
+
+```bash
+cd stream_orchestrator && uv run pytest -q
+cd showrunner          && uv run pytest -q
+cd chat_ingester       && uv run pytest -q
+cd script_producer     && uv run pytest -q
+```
+
+The `showrunner/` suite carries opt-in live tests (real Anthropic + real Chromium)
+behind the `live` marker; they are deselected by default. Run them explicitly with:
+
+```bash
+cd showrunner && uv run pytest -m live -q     # requires ANTHROPIC_API_KEY
+```
+
+## Pull request expectations
+
+- Keep changes scoped and describe what you changed and why.
+- Run the affected package's `pytest` suite before opening a PR; add or update tests
+  for behavior you change.
+- The sync/pacing logic (word-timestamp scheduling, runway/buffer policy) is
+  load-bearing and easy to break subtly — call out any change that touches it, and
+  prefer a live smoke run when you do.
+- Don't commit a real `.env` or any API keys.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HeyGen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.