ringside 0.1.0__tar.gz

ringside-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build and publish
+        run: |
+          uv build
+          uv publish --token $PYPI_TOKEN
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}

ringside-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.ringside/
+data/agency-runs/
+data/agency-tasks/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+*.pyc
+.env

ringside-0.1.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# ringside — AI Agent Context
+
+> A pip-installable package that runs multi-agent debate pipelines and visualizes them as a live boxing match in the browser.
+
+## What it is
+- `ringside run` — runs the full flow: brief → debate → implement → verify (viewer opens automatically)
+- Two drafters (claude + codex) compete in round 1, reviewers pick the winner, then iterate until consensus
+- Browser at localhost:8731 shows two CSS fighters animating in real-time as the debate happens
+
+## Package layout
+```
+src/ringside/
+  agency.py        — the debate pipeline (drafter → reviewers → debate loop)
+  cli.py           — `ringside run` and `ringside watch` entry points
+  server.py        — FastAPI WebSocket server, polls run.json, streams events
+  static/
+    index.html     — single-file boxing viewer (CSS fighters, HP bars, event log)
+.ringside/           — created per-project at runtime (gitignore it)
+  tasks/           — task files (input to ringside run)
+  runs/            — output: timestamped dirs with run.json + final_plan.md
+```
+
+## run.json event types
+All events agency.py emits: `phase_start`, `agent_started`, `progress`, `draft`, `draft_competition`,
+`review`, `debate`, `round_end`, `build_gates`, `verification`, `implementation`, `summary`, `run_end`
+
+## Key design rules
+- server.py polls run.json every 200ms — do not switch to file watching (complexity not worth it)
+- index.html must remain a single self-contained file — no external CDN, no bundler
+- HP system is cosmetic/narrative — fight ends at run_end, not at 0 HP
+- Reviewer UI is slot-based per phase: plan/implementation phases can render multiple reviewers, and slots reset on phase changes
+- Replay is mixed-mode: the first hydration of a finished run may be cinematic, but reconnect/re-hydration must fast-resync from authoritative state
+- Dark theme: bg #0d0d0d, blue #00aaff (drafter), red #ff3333 (reviewer), gold #ffcc00 accents
+
+## Optional per-project config (no setup required)
+Both files are looked up in the current working directory at runtime. Without them,
+ringside works fine using built-in defaults.
+
+**.agency.toml** — override agent assignments and build gates:
+```toml
+[agents]
+drafters = ["claude", "codex"]    # competitive round 1 (default); use single for no competition
+implementer = "codex"
+plan_reviewers = ["claude", "codex"]
+impl_reviewers = ["codex"]
+verifier = "claude"
+
+[[gates.step]]
+label = "tests"
+cmd = ["pytest", "-q"]
+```
+
+**.agency-standards.md** — override the engineering standards injected into every agent
+prompt. Useful when your project has domain-specific rules (e.g. "never mutate X directly",
+"all DB queries must go through Y"). Without this file, ringside uses sensible defaults
+(no silent fallbacks, reviewer conduct rules, etc.).
+
+## Debate mechanics
+- **Competitive round 1**: two drafters (claude + codex) independently write plans in parallel.
+  Reviewers pick the stronger plan (WINNER: A/B) and review it. Losing drafter is dropped.
+- **Rounds 2+**: winning drafter iterates on reviewer feedback (same session).
+- **Approval with suggestions**: if all reviewers approve but include substantive feedback,
+  the feedback is passed back for one more drafter/implementer round before finalizing.
+- **Max rounds**: 3 per phase (plan + impl). Configurable via `--max-plan-rounds`/`--max-impl-rounds`.
+- Same mechanics apply to implementation phase (single implementer, N reviewers).
+
+## Commands
+```bash
+ringside run                                          # full flow: brief → plan → implement (viewer auto-opens)
+ringside run <task.md> [--plan-only] [--port N]       # run pipeline on existing task file
+ringside run --continue-run <run-dir>                 # chain plan → implementation
+ringside run <task.md> --no-watch                     # run without opening the viewer
+ringside brief [description] [--agent claude|codex]   # just write a task file (no run)
+ringside watch [run.json or runs-dir] [--port N]
+```

ringside-0.1.0/LICENSE

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

ringside-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: ringside
+Version: 0.1.0
+Summary: AI agent debate pipeline with live boxing visualization
+Project-URL: Homepage, https://github.com/futbolbjk/ringside
+Project-URL: Repository, https://github.com/futbolbjk/ringside
+Author: Teo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,debate,multi-agent,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: rich>=13
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: websockets>=12
+Description-Content-Type: text/markdown
+
+# ringside
+
+AI agent debate pipeline with live boxing visualization.
+
+Ringside runs multi-agent debates where a drafter proposes a plan, reviewers critique it, and they iterate until consensus — then an implementer writes code while reviewers audit. The whole thing plays out as a live boxing match in your browser.
+
+## Prerequisites
+
+Ringside dispatches to AI agent CLIs. You need at least one installed:
+
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — `claude` CLI (used as drafter and reviewer by default)
+- **[Codex](https://github.com/openai/codex)** — `codex` CLI (used as implementer and reviewer by default)
+
+Both must be on your `PATH` and authenticated.
+
+## Install
+
+```bash
+pip install ringside
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/teo/ringside.git
+cd ringside
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# Full end-to-end flow: brief → plan → implement → verify
+# (opens the boxing viewer automatically)
+ringside run
+
+# Or if you already have a task file
+ringside run .ringside/tasks/add-retry-logic.md
+
+# Plan only, then implement later
+ringside run task.md --plan-only
+ringside run --continue-run .ringside/runs/20260401-100033
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ringside run` | Full flow: interactive brief, then run the pipeline with viewer |
+| `ringside run <task.md>` | Run pipeline on an existing task file |
+| `ringside run <task.md> --plan-only` | Plan only, skip implementation |
+| `ringside run --continue-run <run-dir>` | Continue a plan-only run with implementation |
+| `ringside brief [description]` | Just write a task file (no run) |
+| `ringside watch [path]` | Reopen the boxing viewer for a run |
+
+## How it works
+
+1. **Planning phase** — A drafter (Claude) writes a plan. Reviewers (Claude + Codex) critique it. They debate until all reviewers approve or max rounds are reached.
+2. **Implementation phase** — An implementer (Codex) edits code following the approved plan. Reviewers audit the changes. Build gates (tests, linting) run between rounds.
+3. **Visualization** — A browser at `localhost:8731` shows two CSS fighters animating in real-time: punches for drafts, counter-punches for rejections, victory poses for approval.
+
+## Per-project configuration
+
+Ringside works out of the box with no configuration. Optionally, add these files to your project root:
+
+### .agency.toml
+
+Override agent assignments and build gates:
+
+```toml
+[agents]
+drafter = "claude"
+implementer = "codex"
+plan_reviewers = ["claude", "codex"]
+impl_reviewers = ["codex"]
+
+[[gates.step]]
+label = "tests"
+cmd = ["pytest", "-q"]
+```
+
+### .agency-standards.md
+
+Override the engineering standards injected into every agent prompt. Useful for domain-specific rules.
+
+### CLAUDE.md
+
+Project context (what the codebase does, key conventions) — automatically picked up and passed to all agents so they understand your project.
+
+## Output
+
+Runs are saved to `.ringside/runs/<timestamp>/` in your working directory:
+
+- `run.json` — full event log (consumed by the viewer)
+- `final_plan.md` — the approved plan
+- `followup_task.md` — auto-generated task for `--continue-run`
+
+## License
+
+MIT

ringside-0.1.0/PLAN.md

@@ -0,0 +1,81 @@
+# ringside
+
+Watch your AI agents fight it out.
+
+`ringside` is two things in one package:
+1. A multi-agent debate pipeline (drafter → reviewers → consensus loop)
+2. A live boxing visualization that turns that debate into a fight you can watch in a browser
+
+The idea: you run `ringside run my-task.md --watch`, a browser tab opens, and you watch your agents punch each other in real time as they debate your code.
+
+---
+
+## Status
+
+- [x] Package scaffold + pip installable (`ringside run`, `ringside watch`)
+- [x] `agency.py` migrated in with `agent_started` events for live tracking
+- [x] `server.py` — FastAPI WebSocket server, latest-run tracking, reset/replay semantics
+- [x] `index.html` — boxing viewer with multi-reviewer roster, timeline, replay, and live progress
+
+The fun part: `server.py` and `index.html` are going to be built *using* the debate pipeline. Agents will plan and implement the visualization that visualizes agents. First run will be terminal-only, after that you watch the fight live.
+
+---
+
+## How it works (rough)
+
+```
+ringside run task.md --watch
+  └── starts server in background thread
+  └── opens browser (shows placeholder until first event)
+  └── runs agency debate loop
+       └── writes run.json after every event (atomic)
+  server polls run.json every 200ms
+  └── broadcasts new events via WebSocket
+  browser receives events
+  └── animates fighters based on event type
+```
+
+Events already captured: `phase_start`, `agent_started`, `draft`, `review`, `debate`, `round_end`, `build_gates`, `implementation`, `verification`, `summary`, `run_end`.
+
+---
+
+## The visualization — open questions
+
+This is deliberately underspecified. Before building, research and experiment:
+
+- **Fighter visuals**: CSS-only shapes are the fast path, but pixel art sprites would look way better. Worth looking at what's available (OpenGameArt, itch.io free assets, Lottie animations). The right answer here isn't obvious — do a spike.
+- **Animation library vs raw CSS**: Raw CSS keyframes are zero-dep and fast to ship. Something like GSAP or even a lightweight sprite engine might make the animations feel much better. TBD based on what the agents produce and what looks good.
+- **Sound**: Bell dings, punch sounds, crowd noise — very doable with the Web Audio API. Probably a v2 thing but worth thinking about early so the event hooks are in place.
+- **Multiple reviewers**: Implemented as a phase-scoped tag-team roster with stable reviewer slots and per-reviewer HP.
+- **Mobile / responsive**: Probably not the first priority but the layout shouldn't be completely broken on a laptop screen at least.
+- **Replay mode**: Mixed mode is in place now — first hydration of a finished run can be cinematic, while reconnects and live re-hydration should snap back to authoritative state.
+
+---
+
+## Distribution — also open
+
+Currently `pip install -e .` from the repo. Eventually:
+- Publish to PyPI as `ringside`
+- Maybe a Homebrew formula for non-Python users
+- A `ringside init` command that sets up `.agency.toml` and the data dir in a new project
+
+The pip approach is fine for now. Don't over-engineer the distribution story until the core product works and feels good.
+
+---
+
+## Build order (next steps)
+
+1. Run `ringside run data/agency-tasks/boxing-viewer.md --plan-only` — get a reviewed plan for server.py + index.html
+2. Review and approve the plan, then run `--impl-only`
+3. First real fight: use ringside to build the next feature of ringside
+4. Iterate on visuals — this will probably go through several rounds before it looks right
+5. README + basic docs once it's working
+
+---
+
+## Principles
+
+- **Gameplay comes first** — if it isn't fun to watch, nothing else matters
+- **No external CDN** — the viewer should work offline
+- **Keep agency.py generic** — it works on any codebase, don't couple it to ringside-specific logic
+- **Ship fast** — get something working and visible, then improve the visuals incrementally

ringside-0.1.0/README.md

@@ -0,0 +1,100 @@
+# ringside
+
+AI agent debate pipeline with live boxing visualization.
+
+Ringside runs multi-agent debates where a drafter proposes a plan, reviewers critique it, and they iterate until consensus — then an implementer writes code while reviewers audit. The whole thing plays out as a live boxing match in your browser.
+
+## Prerequisites
+
+Ringside dispatches to AI agent CLIs. You need at least one installed:
+
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — `claude` CLI (used as drafter and reviewer by default)
+- **[Codex](https://github.com/openai/codex)** — `codex` CLI (used as implementer and reviewer by default)
+
+Both must be on your `PATH` and authenticated.
+
+## Install
+
+```bash
+pip install ringside
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/teo/ringside.git
+cd ringside
+pip install -e .
+```
+
+## Quick start
+
+```bash
+# Full end-to-end flow: brief → plan → implement → verify
+# (opens the boxing viewer automatically)
+ringside run
+
+# Or if you already have a task file
+ringside run .ringside/tasks/add-retry-logic.md
+
+# Plan only, then implement later
+ringside run task.md --plan-only
+ringside run --continue-run .ringside/runs/20260401-100033
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ringside run` | Full flow: interactive brief, then run the pipeline with viewer |
+| `ringside run <task.md>` | Run pipeline on an existing task file |
+| `ringside run <task.md> --plan-only` | Plan only, skip implementation |
+| `ringside run --continue-run <run-dir>` | Continue a plan-only run with implementation |
+| `ringside brief [description]` | Just write a task file (no run) |
+| `ringside watch [path]` | Reopen the boxing viewer for a run |
+
+## How it works
+
+1. **Planning phase** — A drafter (Claude) writes a plan. Reviewers (Claude + Codex) critique it. They debate until all reviewers approve or max rounds are reached.
+2. **Implementation phase** — An implementer (Codex) edits code following the approved plan. Reviewers audit the changes. Build gates (tests, linting) run between rounds.
+3. **Visualization** — A browser at `localhost:8731` shows two CSS fighters animating in real-time: punches for drafts, counter-punches for rejections, victory poses for approval.
+
+## Per-project configuration
+
+Ringside works out of the box with no configuration. Optionally, add these files to your project root:
+
+### .agency.toml
+
+Override agent assignments and build gates:
+
+```toml
+[agents]
+drafter = "claude"
+implementer = "codex"
+plan_reviewers = ["claude", "codex"]
+impl_reviewers = ["codex"]
+
+[[gates.step]]
+label = "tests"
+cmd = ["pytest", "-q"]
+```
+
+### .agency-standards.md
+
+Override the engineering standards injected into every agent prompt. Useful for domain-specific rules.
+
+### CLAUDE.md
+
+Project context (what the codebase does, key conventions) — automatically picked up and passed to all agents so they understand your project.
+
+## Output
+
+Runs are saved to `.ringside/runs/<timestamp>/` in your working directory:
+
+- `run.json` — full event log (consumed by the viewer)
+- `final_plan.md` — the approved plan
+- `followup_task.md` — auto-generated task for `--continue-run`
+
+## License
+
+MIT

ringside-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ringside"
+version = "0.1.0"
+description = "AI agent debate pipeline with live boxing visualization"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Teo" },
+]
+keywords = ["ai", "agents", "debate", "multi-agent", "visualization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "rich>=13",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "websockets>=12",
+]
+
+[project.urls]
+Homepage = "https://github.com/futbolbjk/ringside"
+Repository = "https://github.com/futbolbjk/ringside"
+
+[project.scripts]
+ringside = "ringside.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ringside"]

ringside-0.1.0/src/ringside/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"