krill-collector 0.1.2

Record browser workflow sessions into krill recordings

krill-collector

A krill feeds by filtering everything that drifts past it — this package filters a live browser session, straining out the HTTP exchanges and user events that make up a workflow.

Record a browser workflow session, including server-side request capture, into a krill WorkflowRecording.

Install

Requires Python 3.10+ and uv. Playwright needs a browser binary the first time:

uv add krill-collector
uv run playwright install chromium

Usage

Record from the command line — drive the browser by hand, then close the tab to finish:

uv run krill-collect http://target-app.local -o logicflow.json

Or from Python:

from krill_collector import WorkflowCollector, save_recording

collector = WorkflowCollector("http://target-app.local")
recording = collector.collect()  # opens a browser; records until the tab closes
save_recording(recording, "logicflow.json")

The recording is consumed by the companion krill-fuzzer package.

API

browser session ──▶ intercept ──▶ record ──▶ WorkflowRecording ──▶ JSON
                     ├── network (RequestInterceptor)
                     ├── DOM events (EventRecorder)
                     └── server-side (ServerRequestRecorder)

krill_collector

Symbol	Type	Description
WorkflowCollector(target_url, server_project_roots)	class	Orchestrates a recording session: collect() (sync), async_collect()
ServerRequestRecorder(project_root, output_dir)	class	Standalone server-side PHP request capture: instrument(), deinstrument(), collect()
CollectorError	Exception	Browser launch failure or zero exchanges captured; subclass of KrillError
WorkflowRecording	dataclass	The recording output: exchanges, events, target, timings (from krill-core)
RecordedEvent / EventType	recorded interaction + its kind (from krill-core)
save_recording	function	Write a recording to JSON (from krill-core)

krill-collect

Command-line recorder. krill-collect TARGET_URL [-o OUTPUT] [-s SERVER_ROOT ...] — records a browser session against TARGET_URL, writing JSON to OUTPUT (default logicflow.json). Repeat -s DIR to capture server-side requests from each project root.

Documentation

• Docs index — collect module design and implementation notes.

Citation

If you use this project in academic work, please cite our paper. BibTeX (placeholder until the paper is released):

@misc{beluga_placeholder,
  title  = {{TODO: paper title — not yet released}},
  author = {{TODO: authors}},
  year   = {{TODO}},
  note   = {Paper not yet released. Citation entry will be updated on publication.}
}

License

GPL-2.0 — see LICENSE.