Methods¶
OptPilot exposes one optimization abstraction: method.
A method proposes candidates. It can be a random search, Bayesian optimizer, RL trainer, metaheuristic, LLM workflow, or an existing agent process. OptPilot does not split methods into separate controller and engine concepts.
Methods remain user-owned. OptPilot provides the invocation protocol, candidate contract checking, trial orchestration, and evidence recording around them.
Method Config¶
This is a minimal complete method config for a schema-general parameter method. It asks OptPilot to provide the selected environment's parameter schema at runtime.
apiVersion: optpilot.io/v1
config: method
id: my-method
entrypoint:
python: user_catalog.methods.my_method.method:MyMethod
protocol: batch
settings:
batchSize: 4
accepts:
formats: [parameters]
requires:
context:
- candidate.parameters.schema
entrypoint points to the method implementation. settings is a free object passed to that implementation. accepts declares the environment surface the method needs to run.
If a method always produces a known candidate shape, add a produces field to the method config:
Method output-contract fragment:
For example, an OR-Tools job-shop method can declare that it produces a solutions parameter. A schema-general method, such as an LLM method that reads candidate.parameters.schema and directly emits whatever parameter candidate that environment asks for, should omit produces.
Compatibility Contract¶
Method and environment compatibility is intentionally explicit.
accepts answers three questions:
- which candidate formats can this method produce?
- which environment context fields does it require?
- which environment capabilities does it depend on?
produces is optional. Use it when the method has a fixed output contract or a known subset of possible outputs. Leave it unset when the method is intentionally schema-general. When present, OptPilot compares it structurally with the environment candidate contract. For parameter candidates, each produced parameter must be accepted by the environment schema with a compatible valueType, nested item/object shape, and categorical value set. This comparison is by schema shape, not by environment-specific method names or context path names.
A general parameter-producing method can be compatible with any parameter-candidate environment:
Method compatibility fragment:
In that case, compatibility says the method can run because it supports parameters and receives the schema. The runner still validates every submitted candidate against the environment contract during evaluation.
File-candidate methods use the same pattern. This is a compatibility fragment showing the accepts and produces fields inside a method config:
accepts:
formats: [files]
requires:
context:
- candidate.files.editable
- methodContext.instructions
capabilities: []
produces:
format: files
files:
editable:
- path: heuristic.py
This avoids vague domain tags. Compatibility is defined by the actual candidate contract and method-visible environment surface.
Batch Protocol¶
A batch method is passively asked to propose candidates. After evaluation, OptPilot calls observe(...) when the method implements it.
class MyMethod:
def __init__(self, definition, study_spec, rng=None):
self.definition = definition
def propose(self, n_candidates, study_state):
return [
{
"candidate_id": f"candidate-{index}",
"format": "parameters",
"spec": {"x": 1.0},
"generator": {"method_id": self.definition["id"]},
}
for index in range(n_candidates)
]
def observe(self, observations):
return None
Command methods use the same batch protocol. They receive a JSON request on stdin unless the command includes {input_file}. They write JSON to stdout unless the command includes {output_file}.
Method entrypoint fragment:
Methods That Need Reference Inputs¶
Some methods need to read the same input files that the evaluator will use before proposing a candidate. External solvers, trained policies, and coarse-grained optimization scripts commonly work this way.
Expose those files through the environment config's top-level methodContext.references:
OptPilot includes that context in study_state["candidate_context"]. A method can read the referenced files and emit candidate keys using the reference names, for example spec.solutions.ft06_small. The evaluator decides how those names map to its own settings.
Session Protocol¶
A Python session method actively interacts with an OptPilot session object. It is useful for LLM agents or workflows that naturally operate through repeated tool-like calls.
Method entrypoint fragment:
class MyAgent:
def run(self, session):
session.event({"event": "started"})
session.submit({
"candidate_id": "candidate-001",
"format": "parameters",
"spec": {"x": 1.0},
"generator": {"method_id": session.method_id},
})
Batch and session methods have the same candidate and evidence capability. The distinction is control flow: batch methods are asked to produce candidates; session methods actively submit candidates through the session.
Parallel Candidates¶
Both protocols can submit multiple candidates. settings.batchSize controls how many candidates OptPilot asks a batch method to propose at once. study.execution.parallelism controls how many candidate trials can be evaluated at the same time.
Runtime Isolation¶
Python methods run in the host process. Existing agents or optimizers that need isolated dependencies can be exposed as command methods and launched in a container.
Method runtime fragment:
entrypoint:
command: [python, my_agent.py, "{input_file}", "{output_file}"]
protocol: batch
runtime:
sandbox: container
network: disabled
container:
image: my-agent-image:latest
executable: docker
build:
context: .
dockerfile: Dockerfile.agent
tag: my-agent-image:latest
envFromHost: [OPENAI_API_KEY]
Method runtime containers are independent from environment execution containers. Use method containers for optimizer or agent dependencies. Use study execution runtime for simulator or evaluator dependencies.