Berghain Bouncer Challenge Solver

Overview

Berghain Bouncer Challenge Solver is a helper-only agent for Scenario 1 of the Listen Labs Berghain Bouncer Challenge. The agent connects to the public API, monitors the active attribute constraints, and selects admissions that keep the venue on track to meet its quotas while staying within rate limits. The codebase is purpose-built for reproducibility and long-term maintainability with a focus on clear configuration, deterministic behaviour, and transparent logging.

Key Features and Use Cases

• Constraint-aware admission logic that prioritises attributes still needed to satisfy the scenario requirements.
• Robust HTTP session handling with retries, exponential backoff, jitter, and early exit on interruption.
• Command-line interface for supplying the challenge base URL and player identifier without editing the source.
• Progress logging that reports throughput, remaining quotas, and acceptance reasoning at regular intervals.
• Ready-to-package Python project structure that supports virtual environments, CI workflows, and auditing.

Repository Layout

BerghainChallenge
├── docs/                         Supporting documents and artefacts
│   └── Berghain Bouncer Challenge.pdf
├── src/
│   └── berghain_challenge/
│       ├── __init__.py
│       └── BerghainSolver.py     Scenario 1 helper agent implementation
├── .github/workflows/            Continuous integration and auditing workflows
├── CHANGELOG.md                  Revision history
├── LICENSE                       MIT License text
├── README.md                     Project documentation
├── ROADMAP.md                    Planned improvements and audit findings
├── requirements.txt              Runtime dependencies
└── pyproject.toml                Packaging metadata and build configuration

Dependency Overview

Berghain Bouncer Challenge Solver
├── berghain_challenge/BerghainSolver.py   → Core CLI and HTTP interaction logic
├── berghain_challenge/__init__.py         → Package export for `run_scenario1`
└── docs/                                  → Reference material for the challenge rules

Requirements

• Python 3.9 – 3.13
• pip 23 or newer
• Network access to https://berghain.challenges.listenlabs.ai/

The solver depends on the requests HTTP client. All dependencies are listed in requirements.txt and declared in pyproject.toml.

Installation

python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

To install the package in editable mode for development:

pip install -e .

Quick Start

1. Export the base URL (without a trailing slash) and your player identifier supplied by Listen Labs:

   export BERGHAIN_BASE_URL="https://berghain.challenges.listenlabs.ai"
   export BERGHAIN_PLAYER_ID="00000000-0000-0000-0000-000000000000"

2. Run the helper agent module:

   python -m berghain_challenge.BerghainSolver --base-url "$BERGHAIN_BASE_URL" --player-id "$BERGHAIN_PLAYER_ID"

3. Monitor the console logs for efficiency metrics, outstanding quota counts, and retry activity.

Command Reference

usage: BerghainSolver.py --player-id PLAYER_ID --base-url BASE_URL

Scenario 1 Agent — helper-only version

options:
  --player-id PLAYER_ID   UUID assigned by the challenge website
  --base-url BASE_URL     Base URL of the challenge instance (e.g. https://berghain.challenges.listenlabs.ai)

Example Output Snippet

[100] admit=84/1000 eff=0.84 slots_left=916
  Needs: {'local': 40, 'black': 180} Reasons: {'helps_constraints': 77, 'neutral_block': 23}

Configuration Highlights

Parameter	Default	Description
REQUEST_TIMEOUT	(5, 30)	Tuple of connect/read timeouts for HTTP requests.
USER_AGENT	"HelperOnlyAgent-S1"	Custom header applied to all requests.
LOG_EVERY	100	Frequency of progress log statements.
BASE_THROTTLE	0.01	Minimum pause between decisions in seconds.
MAX_RETRIES	5	Maximum number of HTTP retries before failing.
BACKOFF_BASE	0.2	Base multiplier for exponential backoff on throttling responses.
MAX_BACKOFF	1.0	Maximum delay applied during backoff.

For advanced tuning, fork the repository and wrap these constants in os.getenv lookups or a configuration loader to externalise per-environment settings without modifying the core logic.

Troubleshooting and Support

• HTTP 429 / rate limiting – Increase BASE_THROTTLE or reduce logging frequency to remain under the API's rate limits.
• Invalid player identifier – Verify the UUID from the Listen Labs dashboard and ensure it is passed verbatim to the CLI.
• Network errors – Confirm outbound HTTPS traffic to the challenge host is allowed by your firewall or VPN configuration.
• Interrupted runs – Use Ctrl+C to stop the agent safely; the script exits with status code 1 and logs "Interrupted.".

For additional support, open an issue describing your environment, exact command invocation, and relevant console output.

Development Notes

• Static analysis can be run locally with bandit -r src and pip-audit to review security posture.
• Continuous integration executes linting, static analysis, dependency audits, and bytecode compilation checks on every push.
• The repository intentionally avoids automatic formatting to respect the original solver implementation.

License

Distributed under the MIT License. See LICENSE for details.