KelvinK · v1
Install

Doc · 02 / Usage

How a developer uses it

One command. Two before it. Everything visible on disk. No hosted service.

Workflow · 04 steps

Install, init, check, read

01

Install

Pure Python. No services, no account.

02

Init

30-second interactive setup. Asks four questions and writes kelvin.yaml.

03

Check

Runs perturbations, invokes your pipeline once per perturbation, prints the report.

04

Read

Self-contained HTML for per-case drill-down. Commit it to a PR.

Flag — --only <case> runs on a single case. No other flags.

kelvin init · 04 questions

The four-question setup

Everything Kelvin needs to understand your pipeline.

  1. Q1

    Shell command

    Shell command to invoke your pipeline (with {input} and {output} placeholders).

  2. Q2

    Cases location

    Where your cases live.

  3. Q3

    Decision field

    Name of the decision field in your pipeline's output JSON.

  4. Q4

    Governing types

    Which unit types are governing (used for swap perturbations).

Contract

kelvin.yaml

Four keys. Written by kelvin init. Edit by hand if needed.

kelvin.yaml
run: python -m envelop.assess --input {input} --output {output}  # how Kelvin invokes your pipeline
cases: ./ventures                                                # where your markdown case files live
decision_field: recommendation                                   # the JSON field Kelvin compares
governing_types: [gate_rule]                                     # types that should change the answer when swapped
seed: 0                                                          # deterministic perturbation choices

Pipeline contract

Language-agnostic. Framework-agnostic.

Works for any pipeline invocable as a command. Kelvin invokes it once per perturbation.

Inputs · placeholders

  • {input} — path to a perturbed markdown file Kelvin writes before the call.
  • {output} — path where the pipeline must write a JSON file before exiting.

Failure semantics

  • Output JSON must contain the field named in decision_field.
  • Non-zero exit code or missing output file = perturbation fails. Logged and shown in the report; scoring continues with remaining perturbations.

Input format

One markdown file per case

## Section headers declare typed units. The header text becomes the unit type, normalized (lowercased, whitespace → underscore). Content before the first header is treated as untyped preamble and never perturbed.

ventures/acme.md
Preamble text. Optional. Never perturbed.

## Interview
First customer interview content...

## Interview
Second customer interview content...

## Gate Rule
Stage-gate criterion content...

## Budget Assumption
Budget figures and reasoning...

Filename

ventures/acme.md → case name acme.

Repeated headers

Two ## Interview headers produce two units of type interview.

Normalization

## interview, ## INTERVIEW, ## Interview all collapse to interview. Use consistent header text for units of the same type.