OptPilot

OptPilot is an orchestration layer for iterative optimization studies. It lets you connect a user-owned method to a user-owned environment, run candidate solutions, collect objective metrics, and keep the evidence needed to inspect, compare, and reproduce a study.

OptPilot does not replace your simulator, solver, benchmark, RL trainer, LLM workflow, or metaheuristic. Those pieces stay in your code. OptPilot supplies the public contract, runtime loop, and evidence model around them.

The Core Idea

Every run follows the same loop:

The three public config roles map onto that loop:

Config role	Question it answers
environment	What can be evaluated, what candidate shape is valid, and how are metrics returned?
method	How are candidates proposed, and which environment contracts can the method use?
study	Which environment and method should run together, with which objective, budget, and execution policy?

Environment and method configs are reusable. Study configs are concrete run plans.

flowchart LR
  Method["method\nproposes candidates"]
  Runner["OptPilot Core\nvalidates + materializes"]
  Env["environment\nevaluates candidates"]
  Evidence["evidence\nmetrics + artifacts + history"]

  Method --> Runner
  Runner --> Env
  Runner --> Evidence
  Env --> Evidence
  Evidence -. "optional feedback" .-> Method

Two Ways To Use OptPilot

OptPilot has two installation modes:

• Core CLI/SDK: install from PyPI when you want to validate packages and run studies in your own project without the GUI.
• Source checkout for tutorial and Studio: clone the repository when you want the local Studio UI, workspace management, assistant integration, and bundled tutorial package.

Start with Installation to choose the right mode.

flowchart TB
  Configs["public configs\nenvironment + method + study"]
  Core["Core CLI/SDK\nPyPI package"]
  Studio["Full Studio\nsource checkout"]
  Runs["OptPilot Realm\ncanonical Run evidence"]
  Workspaces["Workspaces\ndurable editable projects"]

  Configs --> Core
  Configs --> Studio
  Core --> Runs
  Studio --> Runs
  Studio --> Workspaces

Supported Today

OptPilot currently provides:

• JSON Schema validation for public environment, method, and study configs, plus optional catalog resource manifests
• package validation for folders containing OptPilot configs
• parameter, file, and opaque candidate contracts
• Python and command evaluators
• Python and command methods, including batch-style and session-style method protocols
• local process and Docker/Podman-compatible runtime execution where configs declare it
• local evidence stores with summaries, observations, candidates, trial records, method calls, scheduler events, and retained output files
• a full source-checkout Studio for browsing packages, launching studies, managing editable workspace copies, inspecting runs, and optionally using an assistant

OptPilot intentionally does not provide a production optimizer, remote cluster backend, hosted multi-user service, automatic dependency inference, or a generic replacement for domain-specific solvers and simulators.

Documentation Map

Read the docs in this order if you are new:

1. Installation: choose Core CLI/SDK or full Studio.
2. Your First Run: complete one small run and inspect its evidence.
3. OptPilot Core: learn environments, methods, studies, candidates, runtime workspaces, and evidence.
4. Packages and Catalogs: understand how reusable environments, methods, resources, and studies are organized.
5. Research Packages: browse the three paper companion packages and see how their public contracts compose.
6. OptPilot Studio: use the local GUI, workspace manager, and assistant.
7. Build Your First Package: copy the small tutorial package and replace one building block at a time.

Use Configuration Reference when you need the allowed YAML fields and How a Run Works when you need the runtime sequence.

Research Packages

OptPilot's release catalog contains one companion package for each research paper, plus one deliberately small tutorial. Package implementations remain general: Methods and Environments compose through declared Candidate, metric, trace, and capability contracts rather than package-specific imports.

Package	What it demonstrates	Runs without an API key?
DEVS-Gen (catalog/devs_gallery)	Generate and evaluate discrete-event world models from natural-language specifications.	Gallery studies yes; generation needs a key
LLM-Guided Heuristic Design (catalog/production_agv_scheduling)	Improve executable policies using simulation metrics and event-level traces; production/AGV scheduling is the reference case.	Baselines yes; LLM search needs a key
COOPA (catalog/or_solving)	Formulate and solve a natural-language OR problem with provenance and solver routing.	Needs a key and the pruned runtime dependencies
Build Your First Package (catalog/optpilot_tutorial)	Learn Environment, Method, Run setup, and Resource configuration from one tiny runnable package.	Yes

Generate and Optimize joins the first two ideas: generate a simulator from a text specification, then optimize the policy it declares.

What Ships Where?

The PyPI core package contains the CLI, SDK, schemas, runner, runtime helpers, evidence store, and package validation command.

The source checkout also contains the four catalog packages above:

• catalog/devs_gallery/, catalog/production_agv_scheduling/, and catalog/or_solving/: the three research packages
• catalog/optpilot_tutorial/: the small teaching/template package
• studio/: the OptPilot Studio UI package
• docs, tests, and contributor tooling

Catalog packages are released separately from the core Python wheel. Third-party code inside a package carries its license text and a third-party notice in that package. Code that cannot be redistributed is not bundled at all: COOPA is bundled under Apache-2.0; only its native solver backends are installed by you.

A package that works with the core CLI can be dropped into a Studio catalog root later. That is the intended path: integrate with the schema first, then use Studio for browsing, editing copies, launching studies, and inspecting runs.