Skip to content

CLI and Operator API Reference

This page documents Python operator entrypoints and support scripts.

Run CLI

run

Praxist — Unified CLI launcher.

Subcommands

run Run multi-generation research loop peer Run a single autonomous peer (for Docker/RunPod entrypoints) server Start the orchestrator dashboard

cmd_run 

cmd_run(args)

Run the full multi-generation research loop.

cmd_peer 

cmd_peer(args)

Run a single autonomous agent peer.

cmd_server 

cmd_server(args)

Start the orchestrator Flask server.

cmd_replay 

cmd_replay(args)

Inspect or verify an existing run directory.

cmd_parity 

cmd_parity(args)

Verify research_loop dogfood parity for an existing run directory.

main 

main()

CLI entrypoint for running, replaying, and inspecting Praxist research runs.

Deliverables

deliver

Praxist — Deliverables Packager.

Packages results from a completed run into a clean deliverables directory
  • Executive summary (Markdown)
  • Frontier progression report
  • Best findings with metrics
  • Code snapshots (from frontier entries)
  • Aggregated metrics tables

Usage (CLI): python -m praxist.deliver --run-dir --out-dir

Usage (library): from praxist.deliver import package_deliverables package_deliverables(run_dir, out_dir)

load_run_summary 

load_run_summary(run_dir: Path) -> dict | None

Load the finalized run summary used by deliverable packaging.

load_frontier_manifest 

load_frontier_manifest(run_dir: Path) -> dict | None

Load the frontier manifest used to select deliverable highlights.

load_all_findings 

load_all_findings(run_dir: Path) -> list[dict]

Load all findings from SQLite or filesystem.

load_all_metrics 

load_all_metrics(run_dir: Path) -> list[dict]

Load all metrics from SQLite or JSONL logs.

generate_executive_summary 

generate_executive_summary(
    run_summary: dict | None,
    manifest: dict | None,
    findings: list[dict],
    metrics: list[dict],
) -> str

Generate executive summary in Markdown.

generate_findings_report 

generate_findings_report(findings: list[dict]) -> str

Generate detailed findings report.

generate_metrics_table 

generate_metrics_table(
    metrics: list[dict], primary_metric: str = ""
) -> str

Generate aggregated metrics table.

extract_frontier_snapshots 

extract_frontier_snapshots(
    run_dir: Path, out_dir: Path
) -> int

Extract frontier workspace snapshots to deliverables/code/.

package_deliverables 

package_deliverables(
    run_dir: str,
    out_dir: str,
    name: str | None = None,
    overwrite: bool = False,
) -> Path

Package a completed run into deliverables.

Returns the output directory path.

main 

main()

CLI entrypoint for packaging a run deliverable bundle.

deliver_auto_research

CLI wrapper for Praxist deliverables packaging.

Usage

python scripts/deliver_auto_research.py --run-dir ../sam_optimizer/experiments/run_... --out-dir deliverables python scripts/deliver_auto_research.py --latest --out-dir deliverables

Current external-task runs should pass --run-dir explicitly. --latest is kept for legacy local experiments_tracking/ directories only.

find_latest_run 

find_latest_run() -> str

Find the newest legacy experiments_tracking run directory.

main 

main()

CLI entrypoint for packaging a Praxist run directory.

Task Spec Compatibility

task_spec

Task specification loader.

Reads task_spec.yaml and provides structured access to task configuration.

ComputeBudget dataclass

Task-declared compute budget and optional scheduler hints.

Missing values mean unknown and must be measured or supplied by the task. Praxist does not infer an accelerator model, memory size, utilization envelope, or CPU demand from the research domain.

EvaluationSpec dataclass

Legacy task-spec evaluation settings for benchmark and metric selection.

Baseline dataclass

Legacy baseline descriptor used by compatibility task specifications.

Toolchain dataclass

Legacy toolchain descriptor for task-local harness execution.

GenerationPolicy dataclass

Generation policy fields controlling cohort and generation counts.

Task projects should declare values measured from their unchanged baseline. The package defaults retain the established execution shape for existing task specs that predate explicit calibration fields.

RunLifecyclePolicy dataclass

Generic run-level stop policy evaluated before starting a generation.

SynthesisTriggerConfig dataclass

Event-driven generation termination via synthesis trigger.

A generation runs until ANY of these conditions is satisfied (whichever comes first):

(A) Information-density trigger: findings_in_gen >= min_findings AND minutes_since_gen_start >= min_interval_minutes AND distinct_contributing_peers >= min_contributing_peers

(B) Safety cap: minutes_since_gen_start >= max_interval_minutes

When the trigger fires, the orchestrator writes a sentinel file (/STOP_SIGNAL) that peers detect at their next safe checkpoint. Peers drain in-flight work then exit gracefully.

Defaults preserve the established event-driven behavior. Task initialization should still calibrate all density and time fields from the unchanged baseline.

AgentConfig dataclass

2026-05-07: Top-level agent runtime config.

Applies to ALL LLM agent calls in the run: peers (AutonomousAgentLoop), PIs (Multi-PI panel Round 1/2), Chair (synthesizer). Set via agent: block in task_spec.yaml.

reasoning_effort is a provider-neutral policy. Runtime adapters map it to their supported wire contract. premium_mode is retained as a compatibility alias for reasoning_effort: max when the latter is auto.

PIAgentConfig dataclass

v2026-05-04: PI / Synthesis agent configuration.

The PI agent runs ONCE between every pair of generations (so 7 times in an 8-generation run). It reads the just-completed generation's state and outputs a research_agenda_gen{N+1}.yaml that the next generation's peers receive in their prompts as explicit role contracts.

MultiPIConfig dataclass

v2026-05-05: Multi-PI panel configuration.

Default enabled: False keeps the v2026-05-04 single-PI behavior intact. See the workflow and state sections of docs/concepts/architecture.md.

ResearchMemoryConfig dataclass

v2026-05-05: Research memory (ledgers + evidence pack) configuration.

Default enabled: False keeps the v2026-05-04 raw-prompt path intact.

PromptLayoutConfig dataclass

Optional task-local prompt template overrides.

Empty fields preserve the bundled research-loop templates. Task projects may provide prompt templates when the bundled peer framing is too domain specific, while still using the same Praxist prompt-layout renderer.

GemsConfig dataclass

Opt-in periodic Gems reset mechanism.

When enabled, the research loop snapshots the current Pareto/lane frontier into durable Gems every reset_interval_generations completed logical generations, archives ordinary findings, and starts a new logical generation-0 cycle without resetting the absolute generation budget.

RuntimeEnvironmentConfig dataclass

Runtime environment fields consumed by backend-neutral helpers.

TaskSpec dataclass

Structured representation of a task_spec.yaml file.

get_prompt_base_path 

get_prompt_base_path(default_path: Path) -> Path

Return the task-local base prompt template or default_path.

prompt_layout.base_template is resolved relative to the task directory unless absolute. The file is validated here so runtime prompt rendering fails with a clear task-spec error instead of a late Jinja file-read traceback.

get_prompt_generation_path 

get_prompt_generation_path(default_path: Path) -> Path

Return the task-local generation prompt template or default_path.

Generation prompts are rendered for gen>=1. If only the base template can be overridden, task-local prompt isolation is incomplete: bundled follow-up instructions can reintroduce domain-specific contracts. This resolver mirrors get_prompt_base_path and keeps the fallback explicit.

shell_command_script_index 

shell_command_script_index(
    command: list[str],
) -> int | None

Return the command-string index for a static sh/bash argv.

declared_evaluation_entrypoint_token 

declared_evaluation_entrypoint_token(command: str) -> str

Return the static evaluator path token from a task entrypoint command.

declared_evaluation_entrypoint_chdir 

declared_evaluation_entrypoint_chdir(command: str) -> str

Return the static working-directory component of an evaluator command.

resolve_declared_evaluation_entrypoint 

resolve_declared_evaluation_entrypoint(
    command: str,
    *,
    task_dir: Path,
    runtime_cwd: object = None,
) -> Path | None

Resolve a static evaluator command to its existing task-owned file.

normalize_gems_selection_policy 

normalize_gems_selection_policy(value: Any) -> str

Normalize a task-facing generic Gems policy token.

load_task_spec 

load_task_spec(path: str | Path) -> TaskSpec

Load a TaskSpec from a YAML file.

Fake Workflow Fixture

fake_workflow_fixture

Fake workflow fixture for core-plugin conformance runs.

FakeWorkflowFixtureTaskRunner

Task runner class that exposes the fake workflow fixture to task projects.

run_fake_workflow_fixture 

run_fake_workflow_fixture(
    *,
    workspace: Path,
    task_ref: str = "task:fake_panel",
    task_project: TaskProject | None = None,
    run_dir: Path | None = None,
    runtime_ref: str = "agent_runtime:fake_runtime",
    model_provider_ref: str = "model_provider:fake_provider",
    budget_policy_ref: str = "budget_policy:fake_tiered",
    credential_profile: str | None = None,
    resolve_only: bool = False,
    run_lifecycle_observer: Any | None = None,
) -> dict[str, Any]

Run the fake workflow fixture used by conformance tests and task templates.

create_task_runner 

create_task_runner(
    task_project: TaskProject | None = None,
) -> FakeWorkflowFixtureTaskRunner

Task project entrypoint that constructs the fake workflow fixture runner.