debatr 0.1.0__tar.gz

debatr-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# System
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.venv
+venv/
+env/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Docker
+docker-compose.override.yml
+
+# Generated audio/timeline files (backend MEDIA_ROOT)
+/backend/media/
+/media/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!frontend/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Node
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+*.tsbuildinfo
+
+# Standalone media demo (not part of the app)
+demo/
+
+# Private planning notes (public roadmap lives in README.md)
+PROGRESS.md

debatr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khoren Markosyan
+
+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.

debatr-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: debatr
+Version: 0.1.0
+Summary: Run AI debates from your terminal and give AI agents a debate tool (MCP): the command-line client for Debatr.
+Project-URL: Homepage, https://ai-debates.net
+Project-URL: Documentation, https://github.com/khoren93/debatr/tree/main/cli#readme
+Project-URL: Repository, https://github.com/khoren93/debatr
+Project-URL: Issues, https://github.com/khoren93/debatr/issues
+Project-URL: Changelog, https://github.com/khoren93/debatr/blob/main/CHANGELOG.md
+Author: Khoren Markosyan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,cli,debate,llm,mcp,openrouter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: rich>=14
+Requires-Dist: typer<1,>=0.27
+Description-Content-Type: text/markdown
+
+# debatr
+
+**Run AI debates from your terminal, and give AI agents a debate tool over MCP.**
+
+`debatr` is the command-line client for [Debatr](https://ai-debates.net), the AI debate studio:
+pick a question and the models, watch them argue live in your terminal and get the judge's
+verdict. The same package is an [MCP](https://modelcontextprotocol.io) server, so Claude, Cursor
+and other agents can stage a debate to stress-test a decision or see both sides of a question.
+
+```text
+$ debatr run "Should cities ban cars from their centres?" -d anthropic/claude-sonnet-4.5 -d openai/gpt-5
+
+● The Host  HOST · openrouter/free
+Welcome! Today two models take on car-free city centres…
+
+● Nova  PRO · anthropic/claude-sonnet-4.5
+Cities belong to people, not parked metal…
+
+● Atlas  CON · openai/gpt-5
+A ban hits the people with the fewest alternatives first…
+
+╭─ ⚖ The judge's verdict ─────────────────────────────╮
+│ Winner: Nova                                        │
+│ Nova grounded every claim in what cities measured.  │
+╰─────────────────────────────────────────────────────╯
+✓ Completed  ·  7 turns  ·  provider cost $0.0213
+```
+
+## Install
+
+```bash
+uv tool install debatr        # or: pipx install debatr
+debatr --help
+```
+
+No install needed for a one-off: `uvx debatr run "Tabs or spaces?"`. Python 3.10+ is required
+(uv fetches one if you have none).
+
+## Sign in
+
+```bash
+debatr login
+```
+
+This opens Debatr in your browser and asks you to confirm a code (like `gh auth login`). You can
+give this computer a spending limit there. The token is saved in `~/.config/debatr/config.json`
+(readable only by you) and can be revoked at any time under **Account → API tokens** on the
+website, or with `debatr logout`.
+
+For CI and scripts, create a token under **Account → API tokens** and pass it in the
+environment:
+
+```bash
+export DEBATR_TOKEN=debatr_…
+debatr whoami
+```
+
+A token acts as you for debates and spending, but can never change your password, keys or
+payments, or create other tokens.
+
+## Run a debate
+
+```bash
+debatr run "Is remote work better for juniors?"                 # two free models
+debatr run "Nuclear or renewables?" \
+  -d anthropic/claude-sonnet-4.5 -n Ada -s "A nuclear engineer" \
+  -d google/gemini-2.5-pro -n Ben -s "A grid operator who favours renewables" \
+  --rounds 3 --length medium
+debatr run "Should we rewrite it in Rust?" --context "A 40k-line Go service, team of 4" --json
+```
+
+| Option | What it does |
+|---|---|
+| `-d, --debater MODEL` | A debater's model; repeat for each (1–7). Default: `openrouter/free` twice. |
+| `-n, --name` / `-s, --stance` | Names and personas, in the order of `-d`. By default the first argues for, the second against. |
+| `--host MODEL` / `--no-host` | The host opens each round and judges (default `openrouter/free`). |
+| `-r, --rounds`, `-l, --length` | 1–10 rounds; turns `very_short`, `short`, `medium` or `long`. |
+| `--language`, `--intensity`, `--style` | Debate language, 1 calm … 10 fierce, `markdown` or `spoken`. |
+| `-c, --context TEXT` | Background the speakers should know. |
+| `--scenes`, `--fact-check` | Design charts and schemes for the web page; web fact-check of the figures (paid). |
+| `--audio`, `--voices` | Voice it when done (free `edge` voices or premium `elevenlabs`). |
+| `--public` | Publish to the gallery when finished (after an automatic content check). Private by default. |
+| `-y, --yes`, `--max-cost USD` | Start paid runs without a prompt; refuse runs estimated above a limit. |
+| `--detach`, `--json` | Print the id and return at once; or no live output, a JSON result at the end. |
+| `--config FILE`, `--print-config` | Use a full request body; print the one the options make. |
+
+Every run is estimated first. Free models cost nothing; paid models are charged to your Debatr
+credits (or to your own OpenRouter key: set `DEBATR_OPENROUTER_KEY`). Without a terminal (CI,
+agents), a paid run needs `--yes` or `--max-cost`. Press Ctrl+C to stop following a debate: you
+are asked whether to stop it on the server too.
+
+## More commands
+
+| Command | What it does |
+|---|---|
+| `debatr models [WORDS] [--free]` | Models you can cast, newest first, with prices per million tokens. |
+| `debatr watch DEBATE` | Follow a running debate live, or replay a finished one. |
+| `debatr show DEBATE [-f text\|markdown\|json] [-o FILE]` | Transcript and verdict; export as Markdown or JSON. |
+| `debatr list [WORDS] [--status S]` | Your debates. |
+| `debatr stop` / `delete` / `publish` / `unpublish DEBATE` | Manage a debate. |
+| `debatr open DEBATE` | Open it in the browser: player, audience vote, video export. |
+| `debatr audio DEBATE [--build] [-o FILE]` | Download the voiced debate as MP3 (`--build` voices it first). |
+| `debatr gallery [WORDS] [--sort trending\|new\|top]` | Browse public debates. |
+| `debatr leaderboard [--free]` | Models ranked by audience votes. |
+| `debatr whoami` / `logout` | The account, balance and token; sign out and revoke the token. |
+
+`DEBATE` is an id, a link (`…/debate/<id>`, `…/d/<slug>`) or a share slug. Commands that print
+data accept `--json`. Exit codes: `0` success, `1` an error or a debate that did not complete,
+`130` interrupted.
+
+## For AI agents (MCP)
+
+`debatr mcp` runs an MCP server on stdio. Sign in once with `debatr login` (or pass
+`DEBATR_TOKEN`), then add it to your agent:
+
+**Claude Code**
+
+```bash
+claude mcp add debatr --scope user -- uvx debatr mcp
+```
+
+**Claude Desktop, Cursor, Windsurf and other clients** (`mcpServers` in their config file):
+
+```json
+{
+  "mcpServers": {
+    "debatr": {
+      "command": "uvx",
+      "args": ["debatr", "mcp"],
+      "env": { "DEBATR_MAX_COST_USD": "0.50" }
+    }
+  }
+}
+```
+
+Desktop apps do not always see your shell's `PATH`: if `uvx` is not found, use its full path
+(`which uvx`). Add `"DEBATR_TOKEN": "debatr_…"` to `env` to use a dedicated token instead of
+your `debatr login`.
+
+| Tool | What it does |
+|---|---|
+| `start_debate` | Starts a debate and returns its id at once (a debate takes 1–5 minutes). |
+| `get_debate` | Status, progress, verdict and transcript; `wait_seconds` waits for the end and reports progress per turn. |
+| `estimate_debate` | Price and length before starting. |
+| `list_models`, `get_leaderboard` | Models to cast, and how audiences rank them. |
+| `list_my_debates`, `search_gallery` | The user's debates; public debates to read. |
+| `stop_debate`, `publish_debate`, `get_account` | Manage a debate; balance and the token's limit. |
+
+Agents spend your credits only within two limits: the token's own spending limit (set it when
+you approve `debatr login` or create the token) and `DEBATR_MAX_COST_USD`, the most one debate
+may cost through this server (default `1.00`). Debates started by agents are private unless they
+ask to publish them.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `DEBATR_URL` | Server to use (default: the one you signed in to, else `https://ai-debates.net`). Same as `--url`. |
+| `DEBATR_TOKEN` | API token; takes precedence over `debatr login`. |
+| `DEBATR_OPENROUTER_KEY` | Your OpenRouter key: models run on your account instead of your credits. Never stored by Debatr. |
+| `DEBATR_ELEVENLABS_KEY` | Your ElevenLabs key for `--voices elevenlabs`. |
+| `DEBATR_MAX_COST_USD` | MCP server: the most one debate may cost (default `1.00`). |
+| `DEBATR_CONFIG_DIR` | Where logins are saved (default `~/.config/debatr`, `%APPDATA%\debatr` on Windows). |
+
+**Self-hosted Debatr**: point the CLI at your server with `--url` (or `DEBATR_URL`), e.g.
+`debatr --url http://localhost login`. Logins are kept per server.
+
+## Development
+
+The package lives in the [`cli/`](https://github.com/khoren93/debatr/tree/main/cli) folder of the
+Debatr repository and only uses the public REST API (`/api/docs` on any Debatr server).
+
+```bash
+cd cli
+uv sync
+uv run debatr --url http://localhost --help
+uv run pytest -q && uv run ruff check . && uv run pyright
+```
+
+Releases are published to PyPI by GitHub Actions when a `cli-vX.Y.Z` tag is pushed (the version
+lives in `src/debatr/__init__.py`).
+
+## License
+
+MIT

debatr-0.1.0/README.md

@@ -0,0 +1,185 @@
+# debatr
+
+**Run AI debates from your terminal, and give AI agents a debate tool over MCP.**
+
+`debatr` is the command-line client for [Debatr](https://ai-debates.net), the AI debate studio:
+pick a question and the models, watch them argue live in your terminal and get the judge's
+verdict. The same package is an [MCP](https://modelcontextprotocol.io) server, so Claude, Cursor
+and other agents can stage a debate to stress-test a decision or see both sides of a question.
+
+```text
+$ debatr run "Should cities ban cars from their centres?" -d anthropic/claude-sonnet-4.5 -d openai/gpt-5
+
+● The Host  HOST · openrouter/free
+Welcome! Today two models take on car-free city centres…
+
+● Nova  PRO · anthropic/claude-sonnet-4.5
+Cities belong to people, not parked metal…
+
+● Atlas  CON · openai/gpt-5
+A ban hits the people with the fewest alternatives first…
+
+╭─ ⚖ The judge's verdict ─────────────────────────────╮
+│ Winner: Nova                                        │
+│ Nova grounded every claim in what cities measured.  │
+╰─────────────────────────────────────────────────────╯
+✓ Completed  ·  7 turns  ·  provider cost $0.0213
+```
+
+## Install
+
+```bash
+uv tool install debatr        # or: pipx install debatr
+debatr --help
+```
+
+No install needed for a one-off: `uvx debatr run "Tabs or spaces?"`. Python 3.10+ is required
+(uv fetches one if you have none).
+
+## Sign in
+
+```bash
+debatr login
+```
+
+This opens Debatr in your browser and asks you to confirm a code (like `gh auth login`). You can
+give this computer a spending limit there. The token is saved in `~/.config/debatr/config.json`
+(readable only by you) and can be revoked at any time under **Account → API tokens** on the
+website, or with `debatr logout`.
+
+For CI and scripts, create a token under **Account → API tokens** and pass it in the
+environment:
+
+```bash
+export DEBATR_TOKEN=debatr_…
+debatr whoami
+```
+
+A token acts as you for debates and spending, but can never change your password, keys or
+payments, or create other tokens.
+
+## Run a debate
+
+```bash
+debatr run "Is remote work better for juniors?"                 # two free models
+debatr run "Nuclear or renewables?" \
+  -d anthropic/claude-sonnet-4.5 -n Ada -s "A nuclear engineer" \
+  -d google/gemini-2.5-pro -n Ben -s "A grid operator who favours renewables" \
+  --rounds 3 --length medium
+debatr run "Should we rewrite it in Rust?" --context "A 40k-line Go service, team of 4" --json
+```
+
+| Option | What it does |
+|---|---|
+| `-d, --debater MODEL` | A debater's model; repeat for each (1–7). Default: `openrouter/free` twice. |
+| `-n, --name` / `-s, --stance` | Names and personas, in the order of `-d`. By default the first argues for, the second against. |
+| `--host MODEL` / `--no-host` | The host opens each round and judges (default `openrouter/free`). |
+| `-r, --rounds`, `-l, --length` | 1–10 rounds; turns `very_short`, `short`, `medium` or `long`. |
+| `--language`, `--intensity`, `--style` | Debate language, 1 calm … 10 fierce, `markdown` or `spoken`. |
+| `-c, --context TEXT` | Background the speakers should know. |
+| `--scenes`, `--fact-check` | Design charts and schemes for the web page; web fact-check of the figures (paid). |
+| `--audio`, `--voices` | Voice it when done (free `edge` voices or premium `elevenlabs`). |
+| `--public` | Publish to the gallery when finished (after an automatic content check). Private by default. |
+| `-y, --yes`, `--max-cost USD` | Start paid runs without a prompt; refuse runs estimated above a limit. |
+| `--detach`, `--json` | Print the id and return at once; or no live output, a JSON result at the end. |
+| `--config FILE`, `--print-config` | Use a full request body; print the one the options make. |
+
+Every run is estimated first. Free models cost nothing; paid models are charged to your Debatr
+credits (or to your own OpenRouter key: set `DEBATR_OPENROUTER_KEY`). Without a terminal (CI,
+agents), a paid run needs `--yes` or `--max-cost`. Press Ctrl+C to stop following a debate: you
+are asked whether to stop it on the server too.
+
+## More commands
+
+| Command | What it does |
+|---|---|
+| `debatr models [WORDS] [--free]` | Models you can cast, newest first, with prices per million tokens. |
+| `debatr watch DEBATE` | Follow a running debate live, or replay a finished one. |
+| `debatr show DEBATE [-f text\|markdown\|json] [-o FILE]` | Transcript and verdict; export as Markdown or JSON. |
+| `debatr list [WORDS] [--status S]` | Your debates. |
+| `debatr stop` / `delete` / `publish` / `unpublish DEBATE` | Manage a debate. |
+| `debatr open DEBATE` | Open it in the browser: player, audience vote, video export. |
+| `debatr audio DEBATE [--build] [-o FILE]` | Download the voiced debate as MP3 (`--build` voices it first). |
+| `debatr gallery [WORDS] [--sort trending\|new\|top]` | Browse public debates. |
+| `debatr leaderboard [--free]` | Models ranked by audience votes. |
+| `debatr whoami` / `logout` | The account, balance and token; sign out and revoke the token. |
+
+`DEBATE` is an id, a link (`…/debate/<id>`, `…/d/<slug>`) or a share slug. Commands that print
+data accept `--json`. Exit codes: `0` success, `1` an error or a debate that did not complete,
+`130` interrupted.
+
+## For AI agents (MCP)
+
+`debatr mcp` runs an MCP server on stdio. Sign in once with `debatr login` (or pass
+`DEBATR_TOKEN`), then add it to your agent:
+
+**Claude Code**
+
+```bash
+claude mcp add debatr --scope user -- uvx debatr mcp
+```
+
+**Claude Desktop, Cursor, Windsurf and other clients** (`mcpServers` in their config file):
+
+```json
+{
+  "mcpServers": {
+    "debatr": {
+      "command": "uvx",
+      "args": ["debatr", "mcp"],
+      "env": { "DEBATR_MAX_COST_USD": "0.50" }
+    }
+  }
+}
+```
+
+Desktop apps do not always see your shell's `PATH`: if `uvx` is not found, use its full path
+(`which uvx`). Add `"DEBATR_TOKEN": "debatr_…"` to `env` to use a dedicated token instead of
+your `debatr login`.
+
+| Tool | What it does |
+|---|---|
+| `start_debate` | Starts a debate and returns its id at once (a debate takes 1–5 minutes). |
+| `get_debate` | Status, progress, verdict and transcript; `wait_seconds` waits for the end and reports progress per turn. |
+| `estimate_debate` | Price and length before starting. |
+| `list_models`, `get_leaderboard` | Models to cast, and how audiences rank them. |
+| `list_my_debates`, `search_gallery` | The user's debates; public debates to read. |
+| `stop_debate`, `publish_debate`, `get_account` | Manage a debate; balance and the token's limit. |
+
+Agents spend your credits only within two limits: the token's own spending limit (set it when
+you approve `debatr login` or create the token) and `DEBATR_MAX_COST_USD`, the most one debate
+may cost through this server (default `1.00`). Debates started by agents are private unless they
+ask to publish them.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `DEBATR_URL` | Server to use (default: the one you signed in to, else `https://ai-debates.net`). Same as `--url`. |
+| `DEBATR_TOKEN` | API token; takes precedence over `debatr login`. |
+| `DEBATR_OPENROUTER_KEY` | Your OpenRouter key: models run on your account instead of your credits. Never stored by Debatr. |
+| `DEBATR_ELEVENLABS_KEY` | Your ElevenLabs key for `--voices elevenlabs`. |
+| `DEBATR_MAX_COST_USD` | MCP server: the most one debate may cost (default `1.00`). |
+| `DEBATR_CONFIG_DIR` | Where logins are saved (default `~/.config/debatr`, `%APPDATA%\debatr` on Windows). |
+
+**Self-hosted Debatr**: point the CLI at your server with `--url` (or `DEBATR_URL`), e.g.
+`debatr --url http://localhost login`. Logins are kept per server.
+
+## Development
+
+The package lives in the [`cli/`](https://github.com/khoren93/debatr/tree/main/cli) folder of the
+Debatr repository and only uses the public REST API (`/api/docs` on any Debatr server).
+
+```bash
+cd cli
+uv sync
+uv run debatr --url http://localhost --help
+uv run pytest -q && uv run ruff check . && uv run pyright
+```
+
+Releases are published to PyPI by GitHub Actions when a `cli-vX.Y.Z` tag is pushed (the version
+lives in `src/debatr/__init__.py`).
+
+## License
+
+MIT

debatr-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "debatr"
+dynamic = ["version"]
+description = "Run AI debates from your terminal and give AI agents a debate tool (MCP): the command-line client for Debatr."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Khoren Markosyan" }]
+keywords = ["ai", "llm", "debate", "openrouter", "mcp", "cli", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1,<1",
+    "typer>=0.27,<1",
+    "rich>=14",
+    "mcp>=2.3,<3",
+]
+
+[project.urls]
+Homepage = "https://ai-debates.net"
+Documentation = "https://github.com/khoren93/debatr/tree/main/cli#readme"
+Repository = "https://github.com/khoren93/debatr"
+Issues = "https://github.com/khoren93/debatr/issues"
+Changelog = "https://github.com/khoren93/debatr/blob/main/CHANGELOG.md"
+
+[project.scripts]
+debatr = "debatr.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/debatr/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/debatr", "tests", "README.md", "LICENSE"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.17.1",
+    "pyright>=1.1.414",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "ASYNC", "SIM", "RUF"]
+ignore = [
+    "E501", # line length handled by the formatter
+    "B008", # typer.Option() in defaults
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["debatr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

debatr-0.1.0/src/debatr/__init__.py

@@ -0,0 +1,3 @@
+"""Debatr CLI: run AI debates from the terminal and serve them to AI agents over MCP."""
+
+__version__ = "0.1.0"

debatr-0.1.0/src/debatr/__main__.py

@@ -0,0 +1,3 @@
+from debatr.cli import main
+
+main()