Runtime Context

RuntimeContext lets you declare what you know about the environment before ixtract runs. It constrains the plan without polluting the learned baseline.

What it is

RuntimeContext is a set of user-declared beliefs about the current environment:

• “The source database is under heavy load right now.”
• “I only want 2 workers maximum.”
• “This extraction must finish within 30 minutes.”

These beliefs constrain the planner’s search space. They are stored with the run for history and audit, but they never feed the controller — a constrained run does not teach ixtract that “fewer workers is better.”

Worker resolution algorithm

The five-stage resolution runs in order:

Stage 1  base workers      benchmark → controller → profiler
Stage 2  hard caps         max_workers, min_workers
Stage 3  soft multipliers  source_load × network_quality
Stage 4  priority          low/normal/high priority multiplier
Stage 5  clamp             floor(result), enforce min floor

Rounding is floor() everywhere. ceil() is never used.

Real example (Run 2 from validation)

Flags: --source-load high --network-quality degraded --priority low

Worker Resolution
──────────────────────────────────────────
base          8     (controller, converged)
× network     0.75  (degraded)
× source      0.50  (high load)
→ env         3     (floor(8 × 0.75 × 0.50))
priority: low → 2
final         2

Result: 2 workers extracted 10M rows at 920K rows/sec — faster than 8 workers on this table. Over-parallelization was confirmed.

Fields reference

Hard caps

Field	Type	Effect
max_workers	int	Upper bound on workers — hard override
min_workers	int	Lower bound on workers

Hard caps are applied in Stage 2, before multipliers.

Soft multipliers

Field	Values	Multiplier
source_load	low / normal / high	1.25 / 1.0 / 0.50
network_quality	good / normal / degraded	1.10 / 1.0 / 0.75
priority	low / normal / high	floor to 2 / 1.0 / 1.25×

Multipliers stack. source_load=high + network_quality=degraded = 0.50 × 0.75 = 0.375 multiplier on base workers.

Advisories

Advisories are informational. They produce warnings in the plan output and affect the verdict, but do not block execution.

Field	Type	Advisory
target_duration_seconds	int	Warns if estimated duration exceeds target
maintenance_window_minutes	int	Warns if estimated duration approaches window
disk_budget_gb	float	Warns if estimated output size exceeds budget
egress_budget_gb	float	Warns if estimated egress exceeds budget

Verdicts

Verdict	Meaning
SAFE TO RUN	No issues
SAFE WITH WARNINGS	Advisory thresholds exceeded — review before running
NOT RECOMMENDED	Hard constraint would produce a dangerous or invalid plan

NOT RECOMMENDED does not block execution by default. Use --force to proceed anyway, or call execute(result, force=True).

Using RuntimeContext

CLI

ixtract execute orders \
  --source-load high \
  --network-quality degraded \
  --priority low \
  --max-workers 4 \
  --target-duration-seconds 60

CLI with file

ixtract execute orders --context-file ctx.json

ctx.json:

{
  "source_load": "high",
  "network_quality": "degraded",
  "priority": "low",
  "max_workers": 4
}

Python API

from ixtract import RuntimeContext, plan, execute

ctx = RuntimeContext(
    source_load="high",
    network_quality="degraded",
    priority="low",
    max_workers=4,
)

result = plan(intent, runtime_context=ctx)
print(result.verdict)

if result.is_safe:
    execution = execute(result)

Invariants

• RuntimeContext never overrides the planner — it constrains the search space.
• RuntimeContext never affects the controller — plan-time only.
• RuntimeContext never feeds learning — stored for history only.
• The system is identical without RuntimeContext — every field defaults to None.
• Order is always: base → hard caps → multipliers → priority → clamp.