pulse api predict

Audience: CLI users validating a request before running it.

pulse api predict validates a types.Request against a .pulse file’s schema without executing it. It reads only the header and schema — never record data — so it’s a cheap, safe iteration loop against arbitrarily large cohorts.

LLM agents using MCP: see the pulse_predict MCP tool and the debugging-with-predict skill. Predict is the LLM’s primary “would this work?” probe.

Synopsis

pulse api predict --request FILE [--json] [--strict] [--echo-request]

Flags

Structural ban

descriptor/predict.go cannot import service/ or processing/. This is enforced by TestPredictNoExecutionImports. Predict is guaranteed to never touch the executor.

Output (text mode)

Valid: true
Schema: 7 fields
Warning [PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL]: AGG_AVG on field region (categorical_u8)

Without --strict, that warning would still let the command exit 0. With --strict, the warning becomes an error and the command exits non-zero.

Output (--json)

{
  "format_version": "1.1",
  "data": {
    "valid": true,
    "schema_info": {"field_count": 7},
    "streamable": false,
    "streamable_reasons": [
      "AGG_MEDIAN on field price"
    ],
    "request": { /* the request as predict resolved it, with defaults applied */ }
  },
  "errors":  [],
  "warnings": [
    {"code": "PULSE_AGG_NOT_MEANINGFUL_FOR_CATEGORICAL", "message": "..."}
  ]
}

streamable reports whether the request will execute on the streaming Process path; streamable_reasons lists every gate that forced the buffered path. See Performance Notes for the full streaming/buffered table.

request echoes the request after defaults have been applied so you can see what would actually run. To suppress defaults, run with --no-defaults on the executing leaf (api process, api compose); predict reports defaults_applied regardless.

Smart defaults

When an aggregations[] or groups[] slot names a field but omits type, Pulse infers the operator from the named field’s schema type before running the request. Predict reports the inferred slot under data.defaults_applied so you can echo back what was filled in:

The Nullable flag on a field never changes its default operator — it only controls per-record null-bitmap participation.

Rules: defaults never override an explicit type; they never cross categories (a missing aggregator does not insert a grouper); statistical tests (tests[], post_tests[]) are not defaulted; filter expressions, features, attributes, and windows are out of scope.

--no-defaults on pulse api process / pulse api compose disables the inference pass entirely and forces every slot to be source-of-truth. Predict still reports defaults_applied so the caller can see what would have been filled in.

Exit codes

Examples

Quick validity check

pulse api predict --request req.json

Programmatic check with envelope

pulse api predict --request req.json --json | \
    jq -e '.data.valid == true' >/dev/null && echo "OK"

Strict mode for CI

pulse api predict --request req.json --strict --json

Detect that a request will buffer

pulse api predict --request req.json --json | \
    jq '.data | {streamable, streamable_reasons}'

Common warning codes

The full code-by-code recovery playbook is reachable per-code via the MCP pulse_errors_lookup tool or the pulse errors lookup CODE CLI; see also Troubleshooting.

Related

• pulse api process — executes a validated request
• Library: pulse.Predict — Go counterpart
• Debugging Predict — LLM-side iteration recipe