Build
← Relifold documentation

Planner

Turn a desired result and available Spaces into an editable pipeline draft.

The Planner proposes a pipeline; it does not declare or run one. It can use semantic, deterministic, reshape, and control operations, including ordinary Python predicates when an exact condition belongs outside a semantic prompt.

For practical guidance on deterministic cost reduction, semantic review, and confidence rubrics, read Cost, semantic review, and confidence.

Give it useful context

Review the draft

Start with proposal-only advice when you want the DAG shape and resource envelope without registering a version or launching empirical rule research:

advice = workspace.planner_advice(
    pipeline_id="event-recommendations",
    instruction=instruction,
    sources=["behaviors", "news"],
    output_columns=["user_id", "event_interests", "recommended_news_ids"],
    provider="openai",
    model="gpt-5",
    target_execution_cost_usd=1.00,
    max_execution_cost_usd=2.00,
    max_authoring_cost_usd=1.00,
)
print(advice["plan"])
print(advice["forecast"])
assert advice["status"] in {"ready_to_author", "needs_engineering"}

Advice first asks the Central Planner for the natural DAG under an infinite-budget assumption. Deterministic operator-specific estimators then price every semantic task and calculate its maximum affordable input frontier. The same Planner performs one finite-budget refinement and, only while observed diagnostics remain, up to eight bounded executable or estimate-correction turns. Every returned DAG is recompiled and repriced; one attempted correction is never presumed successful. If the authoring cap blocks a later correction, the latest complete proposal and its exact diagnostics are returned instead of discarding already-settled work. No additional model agent or Prompt Writer runs on this path. The caller may inspect the proposal and diagnostics, edit the executable proposal, or submit it through ordinary authoring. Without compatible execution evidence, expected cost remains unknown unless a sufficient representative deterministic-gate hand supports a statistical interval; tiny model-visible display samples never discount cost. The host may safely project row-local deterministic Transform fields over that bounded estimator hand, but never executes semantic work. The Central Planner grounds lexical, similarity, category, regex, embedding, and threshold rules in representative sampled data and console analysis before authoring them. The first-shot compiler validates their syntax, fields, executable contract, and cost effects; it does not independently certify, remove, or relabel them. Soft cost-target misses stay visible in the forecast but do not trigger repeated correctness turns after hard constraints pass. Paid semantic evidence includes a supporting field only when it adds sampled, non-redundant meaning that exact logic and deterministic gates cannot settle.

The host reprices the exact candidate after every Planner turn. A changed semantic task receives a new estimate, so stale task economics cannot authorize the final DAG. Forward estimates report expected spend, an interval, and a conservative attempt ceiling; inverse estimates report the maximum affordable input hand and fraction. The Planner also prefers the cleanest meaningful topology: when less than one percent of a task's expected hand can enter, it normally removes that task unless cited evidence establishes disproportionate downstream value. At or above one percent, the hand is size-significant and remains by default; dropping it requires cited semantic/downstream evidence that it is unnecessary, harmful, or an evidence-supported deterministic alternative is at least as good. While quality is unmet or unknown and budget remains, the Planner retains the highest-value feasible improvement; it never spends merely to spend. These are Planner judgments rather than deterministic compiler gates.

Clean deterministic composition uses native positive forms: normalize inside one modest Cluster unless a reusable/indexed field is needed; use one grouped multi-input Apply for exact-key enrichment; and use one grouped multi-input Apply for exact-key expansion or terminal assembly. Generated restricted Python uses named functions, including named nested sort-key functions—never lambdas.

The full planning response includes one architecture rationale and execution forecast. The rationale explains why tasks and deterministic reductions exist, their expected hand sizes and costs, and which assumptions still require evidence. Retrieve it through the same public workspace client when another researcher or process needs to inspect the draft:

draft = workspace.plan(
    pipeline_id="event-recommendations",
    version_id="v1",
    instruction=instruction,
    sources=["behaviors", "news"],
    output_columns=["user_id", "event_interests", "recommended_news_ids"],
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    target_execution_cost_usd=1.00,
    max_execution_cost_usd=2.00,
    max_authoring_cost_usd=1.00,
)
planning_evidence = workspace.planner("event-recommendations", "v1")
print(planning_evidence["forecast"])

# Recompute economics from the current draft after any manual edit.
preflight = workspace.version_forecast("event-recommendations", "v1")
print(preflight["cost_estimate"])

# A reviewed hard limit is separate from the estimate. Blank/null means unbounded.
workspace.update_task_max_cost(
    "event-recommendations", "v1", node_index=2, max_cost_usd=30.0,
)

The two execution-cost fields are optional. The target guides physical planning; the maximum is an admission ceiling for bounded forecasts and persists as the version's hard default cost envelope. They are session-level cost limits rather than task-level cost/call caps. Expected cost uses the selected model's token rates, operator batch shape and the current full dataset. After Prompt Writers finish, the Planner rechecks a requested maximum before version registration, including when the shape already exists. If a target and maximum are both present, the hard maximum takes precedence and cannot be masked by an unknown soft-target estimate. The retry-safe dollar ceiling is a conservative planning projection while row size is profiled; Maximum Execution Cost remains the hard charge boundary. An unknown model price or unbounded connector remains unknown rather than zero. The Planner prefers exact deterministic candidate reduction, shared semantic computation, and compact semantic hands, and rejects a bounded projection that still exceeds max_execution_cost_usd after correction attempts. Runtime is observed after execution and is never forecast.

workspace.planner_advice(...) is the fast architecture surface. It never mutates a version and does not dispatch Prompt Writers. Deep threshold, regex, gate, and prompt certification belongs to explicit research executions, optimization workflows, human researchers, or external coding agents. Successor advice may read research outputs and return a proposed DAG diff, but the caller separately decides whether to register it.

The Planner profiles a bounded, spread sample of each attached source rather than reasoning from column names alone. It uses values, types, cardinality, and compact vocabulary evidence to apply two supporting-key tests: a field must add non-redundant decision information, and that contribution must not be completely decidable through arithmetic, exact comparison, or a deterministic gate. A redundant or deterministically settled field is excluded from the semantic hand even when it is useful to a predicate or candidate gate.

For every semantic task, the central Planner privately traces its downstream consumers to name the task's ultimate local purpose. When a semantic producer has one downstream purpose, accepted deterministic contraction, extraction, or exclusion may move before that producer; the Planner repeats the analysis after every schema or representation change. This private lineage analysis is never copied into Prompt Writer, judge, verifier, or reviewer instructions, which remain task-local.

Native semantic topology operators are authoritative: use SemCluster for semantic equivalence, deduplication, grouping, and partitioning; SemTaxonomy (or the tree/forest convenience form SemHierarchy) for broader/narrower DAGs; and SemSort for semantic ranking and chains. A repeated pairwise SemTransform, custom graph reconstruction, or hand-written semantic ordering is not a cheaper substitute. Deterministic operations may still settle accepted regions before the native operator evaluates the remaining unresolved relationships.

Without a hard resource maximum, the Planner optimizes semantic fidelity first. With a hard maximum, it forms and prices the highest-fidelity plausible DAG, skips specialist research when even the best-case safe reduction bound cannot make a hotspot fit, and otherwise reprices accepted task-local rule evidence before one localized topology correction. The maximum is the constraint; quality is optimized within it. A stopped partial task never counts as evidence that its prompt or complete-result quality failed.

If a successor retains an obsolete diagnostic branch beside one explicit requested-output Select, the compiler removes only nodes that cannot reach that sink. Multiple selected sinks, duplicate producers, and branches that must be joined remain explicit validation failures; the compiler never guesses between them.

After every Central Planner response, deterministic compilation validates the complete node-and-edge contract, schemas, callable identities, candidate-index declarations, and terminal projection. Diagnostics with no unique mechanical repair return to the same Central Planner in a bounded correction turn. No second planning agent is introduced.

Planner goals and generated worker prompts obey the same task-local evidence boundary. If a goal instructs the judge to use, inspect, compare, or consider a declared input field—even a simple name such as category—that field must be the primary key or supporting evidence before prompt writing begins. The compiler repairs the evidence declaration or rejects the goal; a Prompt Writer is never asked to use a hidden input.

For equivalence decisions, a merge and a certified split both require positive task-local evidence. If neither side is supported, the confidence guidance reflects that uncertainty instead of presenting a confident separation. The task's acceptance setting determines whether the evidence is sufficient. The generated rules cannot invent a minimum count of matching anchors, written as digits or words. This prevents negative closure from amplifying conservative prompt wording into false independence.

An observed-output successor preserves an unchanged normal task locally even when the overall pipeline instruction is refined. If that task's type, spaces, identity, emitted fields, goal, constraints, and output contracts are unchanged but its proposed callable cannot read its own input, the compiler restores the last registered evidence/function ABI. A changed task-local goal or output contract disables this repair and remains a Planner decision.

This continuity proof applies equally to Planner-authored and manually registered base versions; a manual draft does not need a synthetic Planner artifact for its registered callable ABI to remain authoritative. Structural fields still match exactly. Planner-only goal, decision-constraint, and output-contract metadata are compared when the base recorded them; missing manual metadata is not an explicit contract change. The compiler still rechecks the restored callable and complete graph.

max_authoring_cost_usd is a separate hard limit over the calls that create the draft: Central Planner and Prompt Writers. Deterministic compilation, estimation, and parameter profiling make no model call. All agent calls share one atomic allowance. A value of zero permits exact cache replays but no new paid call. Reaching the limit fails the authoring job without publishing a partial draft; it never changes the execution budget proposed inside that draft.

A failed hosted authoring job includes a human-readable failure object with a title, summary, last active phase, concrete next action, and support code. Private model responses and exception chains remain server-only. The two Planner execution fields are target_execution_cost_usd and max_execution_cost_usd. These exact names are shared by the Python client, HTTP API, saved version, and response.

Every executable task also has a task_preflight estimate. Semantic tasks show a structural cost estimate before execution; deterministic tasks show model spend of $0.00. Runtime is recorded only after execution as observability and is never a preflight field. A task's authored max_cost_usd is displayed separately. When an empirical recommendation exists, the draft UI prefills it for review but does not apply it automatically; blank means unbounded, and declared versions remain immutable.

Preflight keeps expectation, structural ceiling, and hard stop separate. Its evidence order is compatible complete production history, then an exact-execution-shape research projection, then the structural token forecast. A sampled indexed relationship task may project its measured candidate density to the full bounded input, but the estimate labels that assumption and never presents it as a guarantee. Changing the prompt, model, predicate, candidate index, batch shape, verifier share, reasoning-evidence choice, or task contract invalidates the estimate. Research and preflight compare the same typed task identity, so constructor defaults cannot hide a compatible completed hand. An unchanged successor gives the compact economics to the Central Planner. Prompt Writers receive no pricing information.

For inference-dependent SemCluster, SemTaxonomy, and SemSort tasks, completed executions emit a small model-free structure estimate. The independent estimator—not the Planner prompt—projects final cluster growth and quotient density, taxonomy cover and incomparability, or sort information efficiency, then recalculates calls for the current hand. Updating this estimator automatically updates version_forecast(), Planner economics, preflight, and UI observability. Completed task wall time remains observability and is never projected. The selected model's token contract prices the same call interval. A compatible completed hand yields one expected cost range on every surface; an uncalibrated mathematical floor remains an explicitly priced scenario and never masquerades as that range.

The pipeline forecast sums compatible per-task expected costs and evidence intervals into an aggregate expected value and aggregate lower/upper range. That range is a planning interval, not a claim that cross-task dependence was measured. Structural floors, scenario projections, empirical expectations, and retry-safe ceilings remain separately labelled; a user-authored task or pipeline budget remains a separate hard stop.

A stopped relational task remains ineligible for checkpoint scoring, but its real oracle work is still inspectable with workspace.session_task_evidence(session_id, task_id). That bounded view contains direct judge/verifier evaluations, applies the authored confidence threshold by default, and explicitly excludes repair placeholders. For SemCluster, callers may request a seeded random sample from the monotone equivalence closure of certified facts; contradictory components and relationships whose sparse owned-pair mask is unavailable are excluded. It is a valid manual-diagnostic sampling frame, not a declaration that the incomplete output structure passed quality.

For a small known SemCluster hand, use workspace.session_task_evidence_pairs(session_id, task_id, pairs). One bounded request resolves at most 500 caller-named primary-value pairs from certified direct relationships and their equivalence closure, without paging the complete relationship history. Unknown pairs stay unknown; repaired output never enters the result.

workspace.plan(...) waits for the completed draft for compatibility with scripts. Interactive clients can return immediately and reconnect to durable progress:

job = workspace.start_plan(
    pipeline_id="event-recommendations",
    version_id="v2",
    base_version="v1",
    instruction="Improve the event recommendations from the reviewed results.",
    sources=["behaviors", "news"],
    observed_outputs=["event-signatures", "reviewed-event-pairs"],
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    max_authoring_cost_usd=1.00,
)
progress = workspace.authoring_job("event-recommendations", job["job_id"])
# Optional:
# workspace.cancel_authoring_job("event-recommendations", job["job_id"])

Progress is queued, running, or repairing until it becomes completed, failed, or cancelled. A completed job contains the same Planner result returned by plan(...). For any intelligible human-language goal, the Planner returns a complete DAG: omitted product choices use disclosed, conservative defaults instead of blocking authoring. For example, an unspecified recommendation fanout may default to top 20 or top 50. Semantic and eligibility thresholds still require user authority or reviewed data evidence.

Quality goals may be written naturally in instruction, such as “at least 50% event-assignment accuracy.” Relifold routes an explicit goal to the Central Planner, which includes only relevant task-local criteria in isolated Prompt Writer briefs. No separate quality-objective JSON field is required.

base_version and observed_outputs remain backward-compatible, proposal-only primitives for experimental successor planning. They never add research rows to production lineage or mutate a draft. They are not part of the first-shot Planner quality promise; researchers and coding agents ordinarily inspect virtual task outputs and make evidence-grounded draft edits themselves.

A registered normal-function parameter or semantic-gate parameter is profiled by a deterministic finite grid over reviewed cases. The rule structure is immutable: Jaccard remains Jaccard and a regular expression remains that regular expression. Insufficient or one-sided evidence yields no proposal; it never causes the compiler to delete or suppress the Planner-authored rule.

A semantic candidate gate and a deterministic replacement are different review contracts. A candidate gate may only exclude relationships proved impossible; every admitted relationship still goes to the semantic judge. A replacement predicts the task's complete final relation or output and must match reviewed conformance, calibration, and hidden-holdout cases exactly. Relifold exposes both only as review candidates. It never converts a semantic task merely because a budget is tight. After independent acceptance, the compiler can install the exact normal-operator mirror while preserving the task's identity, goal, keys, inputs, outputs, evidence, and reviewed provenance.

Parameter profiles keep calibration and holdout evidence separate and install nothing automatically. A proposed value must improve the reviewed objective without regressing the protected holdout contract. Researchers explicitly accept any change after inspecting its evidence.

forecast estimates one pipeline execution. authoring separately reports elapsed time, paid calls, and actual cost for creating this draft. Detailed phase timing, token accounting, cache behavior, correction rounds, and prompt-reuse bookkeeping remain internal diagnostics rather than a second public authoring model.

A cost estimate appears only when the full input is bounded and compatible evidence supports the current configuration. Hard execution limits remain separate. Runtime is recorded after execution and is not forecast.

Before declaring, inspect:

Good planning instruction. “Using headlines only, group articles within each category into specific developing event threads. Give each thread a short name. For every user, map the 20 most recent resolvable clicks to those threads and output a normalized list of {event, weight}, preserving every user.”