Kwola is an autonomous browser-testing and learning system for web applications. Kwola 1.1 uses the learning schema version 3 and intentionally rejects older runs and checkpoints; initialize a fresh run after upgrading. It requires Python 3.12 and targets Linux for production. It supports Playwright Chromium and Firefox, mitmproxy-based JavaScript branch instrumentation, local LMDB runs, and PyTorch/NCCL training.
uv sync --locked --python 3.12
npm ci
uv run playwright install chromium firefox
uv run kwola doctorNode dependencies are repository-local and pinned. The JavaScript instrumentation service never depends on a globally installed Babel executable.
When browser.prevent_offsite_navigation is enabled, Kwola confines document navigation to the
target's exact origin. OAuth and other required document origins must be listed in
browser.allowed_navigation_origins; cross-origin API and static-resource requests remain allowed.
Set prevent_offsite_navigation to false to retain unrestricted 1.0 behavior.
kwola init URL --profile testing --run-dir RUN_DIR
kwola init URL --run-dir RUN_DIR # defaults to the throughput-tuned rig profile
kwola run RUN_DIR
kwola test-step RUN_DIR --browser chromium --random
kwola train-step RUN_DIR --gpu 0
kwola report RUN_DIR
kwola doctor --require-gpus 2
kwola benchmark RUN_DIR
kwola status RUN_DIR
kwola proxy install-certThe built-in profiles are testing, standard, and rig. rig is the default and continuously
feeds both GPUs from ten parallel browser environments. It budgets two CPU threads per browser and
four per training rank on the 32-thread reference host, uses a measured batch of 32 per GPU, and
amortizes replay preparation over 900-iteration training steps. Each fresh trace funds sixteen replay
samples so browser production keeps the trainers continuously supplied. It caches decoded screenshots
in RAM, page-locks prefetched batches, and overlaps their preparation with GPU optimization.
standard preserves the lower-throughput two-rank reference configuration. Pass --gpu INDEX for
an explicit single-GPU step.
TraceNet predicts separate immediate-reward and discounted-future-reward maps over the valid spatial action catalog. Their sum drives inference. Training uses masked Double DQN, with the online network selecting the next valid action and the target network evaluating it. Terminal transitions and next states with no valid action receive no bootstrap value.
Automatic training requires at least one configured global batch
(training.batch_size * training.world_size) in the replay buffer. Each fresh trace earns
training.replay_samples_per_new_trace sample credits (eight by default); complete global batches
consume those credits while sampling the entire frozen replay snapshot. Partial-batch credit and
work deferred by the adaptive iteration cap persist for later training steps instead of being
discarded. After startup, retained credit may continue training an unchanged replay snapshot until
that earned work is exhausted.
Current-state crops remain action-centred with configured jitter. Double-DQN targets reconstruct the
complete next viewport from the same overlapping, blended tiles used by inference, so action selection
and target evaluation cover the complete valid action space. Global coordinates, current action masks,
and action-map availability are model inputs. TraceNet uses mode-independent spatial GroupNorm.
The default conservative-Q term (training.losses.conservative_q = 0.1, margin 0.1) penalizes the
highest valid action outside the demonstrated region when it exceeds the demonstrated Q value minus
the margin; set its weight to 0 to disable it.
Exploration uses two independent decisions. random is the probability of bypassing the model for
action-catalog-weighted random behavior. Otherwise the model runs, and weighted_random is the
conditional probability of sampling from its valid Q map instead of taking the greedy maximum.
Forced-random steps and runs without a checkpoint use action-catalog-weighted random behavior.
Pass --greedy to bypass both exploration stages while retaining checkpoint-backed inference;
--greedy and --random are mutually exclusive.
Every run contains strictly validated kwola.json and manifest.json files, an LMDB database,
content-addressed blobs, disposable prepared-sample cache records, reports, logs, and atomically
published PyTorch checkpoints. Unknown configuration fields are rejected.
Credentials are referenced by environment-variable name and are never written into new run
configuration files. For example, set browser.autologin.email_environment and
browser.autologin.password_environment in kwola.json, then export those named variables before
running Kwola. The equivalent fixed-action fields are policy.actions.email_environment and
policy.actions.password_environment. Kwola refuses to write new configuration files containing
inline secrets.
See Architecture for component and process ownership, storage layout, hook ordering, and failure behavior. See Acceptance evidence for the recorded baseline and final rig results.
uv run ruff format --check kwola tests
uv run ruff check kwola tests
uv run mypy --strict kwola
uv run pytest
uv run pip-audit --format json --output pip-audit.json
npm audit --json > npm-audit.json
uv run python scripts/audit_dependencies.py --python-json pip-audit.json \
--npm-json npm-audit.json --exceptions security/advisory-exceptions.jsonEvery high or critical advisory fails this policy unless it has an owned, justified, unexpired exception, regardless of whether an upstream fix is currently available.
Release acceptance additionally passes --require-no-exceptions to the dependency policy and runs
the complete gate from a fresh schema-v3 run on the Linux two-GPU host:
uv run python scripts/run_rig_acceptance.py \
--evidence-dir /path/to/new-empty-evidence-directory \
--kros1-url http://127.0.0.1:3001/ \
--kros3-url http://127.0.0.1:3003/The runner records command logs, environment versions, metrics, and artifact hashes; verifies both browsers, instrumentation, checkpoint compatibility/publication, single-GPU and concurrent two-rank training; enforces the benchmark and zero-exception gates; and rejects leaked runtime processes. Only update the acceptance evidence document after this complete command passes.
The architecture tests enforce limits of 500 lines per module, 300 lines per class, and 80 lines per ordinary method. Domain modules cannot import browser, tensor, storage, process, or reporting infrastructure.
Kwola is licensed under the MIT License. See LICENSE.