WickBench

Your candle burn-test spreadsheet, but reproducible.

WickBench turns repeated wick-test measurements into deterministic evidence. It reads a local CSV, calculates burn rate, melt-pool ratio, flame, temperature, and soot metrics, then evaluates every candidate against the limits in your versioned JSON test plan.

WickBench 0.1.0
result=FAIL candidates=2 passed=1 failed=1
PASS CDN-12 violations=0 rate=5.5g/h melt=0.887 flame_max=24mm temp_max=60C soot_max=1
FAIL CDN-16 violations=5 rate=10g/h melt=1 flame_max=42mm temp_max=78C soot_max=2
  mass_burn_rate_g_per_hour: observed=10 expected=3..7
  final_melt_pool_ratio: observed=1 expected=0.75..0.95
  max_flame_height_mm: observed=42 expected=<= 30
  max_jar_temperature_c: observed=78 expected=<= 65
  max_soot_score: observed=2 expected=<= 1

No account, network request, AI key, database, or runtime dependency is required.

What it does

• Validates repeated burn sessions instead of silently skipping malformed rows.
• Aggregates real session duration and mass consumption into a weighted burn rate.
• Evaluates only the limits declared by your campaign—there are no hidden “universal” wick rules.
• Orders candidates by evidence: violation count, normalized deviation, then identifier.
• Emits concise terminal output, stable JSON v1, Markdown, and a standalone SVG remaining-mass chart.
• Uses exit 0 for a passing campaign, 1 for measured plan violations, and 2 for a broken command/input boundary.

WickBench is an analysis engine, not a recipe/inventory app or a dashboard shell. See the differentiation research.

Install

Python 3.11 through 3.14 is supported.

uv tool install "wickbench @ git+https://github.com/KanadeK/wickbench.git@v0.1.0"
wickbench --version

You can also download the wheel from the v0.1.0 release and install it with python -m pip install path/to/wickbench-0.1.0-py3-none-any.whl.

Quick start

Clone the repository and run the committed fixtures:

uv sync --locked

# One passing candidate: exit 0.
uv run wickbench analyze examples/passing.csv --plan examples/plan.json

# One passing and one intentionally failing candidate: exit 1.
uv run wickbench analyze examples/campaign.csv --plan examples/plan.json

Create artifacts suitable for a test record or pull request:

uv run wickbench analyze examples/campaign.csv --plan examples/plan.json \
  --format markdown --output report.md --chart burn-curves.svg

PowerShell uses the same arguments; place them on one line or use PowerShell's backtick continuation instead of \.

Input contract

The CSV has one observation per row:

candidate,session,elapsed_minutes,remaining_mass_g,melt_pool_mm,flame_height_mm,jar_temperature_c,soot_score
CDN-12,1,0,220,0,0,22,0
CDN-12,1,240,198,70,22,58,0

Every candidate/session starts at minute 0, has at least two rows, advances strictly in time, and never increases remaining_mass_g. soot_score is the campaign's documented 0/1/2 rubric.

The JSON plan owns the acceptance limits:

{
  "schema_version": 1,
  "vessel_diameter_mm": 80,
  "limits": {
    "mass_burn_rate_g_per_hour": { "min": 3, "max": 7 },
    "final_melt_pool_ratio": { "min": 0.75, "max": 0.95 },
    "max_flame_height_mm": { "max": 30 },
    "max_jar_temperature_c": { "max": 65 },
    "max_soot_score": { "max": 1 }
  }
}

The sample numbers are synthetic test data, not recommended limits. The exact formulas and supported boundary are in the v0.1 specification.

Reports and automation

# Machine-readable report on stdout.
wickbench analyze log.csv --plan plan.json --format json

# Markdown report and standalone SVG chart.
wickbench analyze log.csv --plan plan.json --format markdown \
  --output report.md --chart burn-curves.svg

JSON consumers should check schema_version before reading fields; see the report contract. The Markdown and terminal formats round display values to three decimals, while JSON retains calculation precision.

Failure recovery

• Exit 1 means analysis succeeded and at least one configured limit was violated. Review the printed evidence; do not weaken a limit merely to make the command green.
• Exit 2 means the command, plan, CSV, or output path is invalid. WickBench names the rejected boundary and never substitutes a silent default.

Copy-ready repairs for every common error are in the failure and repair guide.

Development and acceptance

uv sync --locked
uv run python scripts/check.py

The release gate checks the lockfile, formatting, lint/security rules, strict typing, all tests with at least 90% branch coverage, both real example exit paths, JSON/SVG evidence, wheel and source-package builds, and an installed-wheel smoke test. CI runs the same command on Linux/Python 3.11 and Windows/Python 3.14.

Focused contribution rules are in CONTRIBUTING.md, changes in CHANGELOG.md, and the local-input/output threat boundary in SECURITY.md.

Safety boundary

WickBench analyzes measurements against limits supplied by the user. It does not certify a candle, prescribe a live test, control a flame, or replace applicable fire-safety, regulatory, and product-testing requirements. Never leave a burning candle unattended.

License

MIT