Configuration

Research settings belong to the selected engine adapter. C3 execution choices and hard limits are separate. Each submission pins an engine version; the service records the adapter version and resolves defaults before starting paid work.

Engine settings and C3 execution

Use engine_config for the engine's native configuration and c3 for execution:

run = client.research.run(
    initial_program=Path("candidate.py"),
    evaluator=Path("evaluate.py"),
    engine="openevolve",
    engine_version="0.2.26",
    engine_config={
        "max_iterations": 4,
        "random_seed": 42,
        "llm": {
            "models": [{"name": "openai/gpt-4.1-mini", "weight": 1.0}],
            "temperature": 0.7,
            "max_tokens": 1024,
        },
        "database": {"population_size": 40, "archive_size": 10},
    },
    c3={"hardware_profile": "l40", "provider": "nextgen"},
)

This snippet assumes client is a C3 client and Path is imported from pathlib. File inputs must be Path objects; strings are interpreted as source code.

Namespace	Examples	Responsibility
engine_config	Search iterations, model ensemble, sampling, prompts, population, early stopping	Research algorithm
c3	Hardware, compute provider, inference connection, execution concurrency	Managed execution
limits	Total duration, evaluation timeout/count, optional spending cap	Hard admission and execution bounds
inputs	Adapter-specific experiment material; OpenEvolve accepts initial program and evaluator source	Experiment material

Only OpenEvolve 0.2.26 is currently available. Each additional engine requires a separate tested adapter; sharing the submission envelope does not imply support for another framework. An adapter's settings use that engine's vocabulary.

The SDK also accepts an inputs dictionary with the selected adapter's input shape. For OpenEvolve, use inputs={"initial_program": source, "evaluator": evaluator_source} with source strings, or the Path convenience arguments shown above. Do not mix inputs with initial_program/evaluator. Other engines will define their own input shapes when their adapters are implemented.

Discover supported settings

GET /v2/research/engines returns the authenticated engine catalogue. Each entry provides its engine and adapter versions, configuration schemas, defaults, managed settings, capabilities and workflow. The schema for the selected adapter is the supported contract, even if a newer upstream OpenEvolve release exposes additional fields.

The OpenEvolve adapter exposes native controls for iterations and random seed; weighted model selection and sampling; prompt context counts; population, archive and islands; diff-based evolution; and bounded early stopping. Its schema supplies exact ranges and defaults. The model pool contains between one and four declared OpenRouter model IDs with positive weights. Each actual model request uses the selected model and C3's normal admission and settlement.

Cascade evaluation, LLM feedback, embedding/novelty models, custom Python LLM clients, custom prompt-template files and checkpoint resume remain unsupported. Service endpoints, API keys, workspace paths, evaluator retries and managed parallelism belong to C3. The current service supports one evaluation at a time. Unknown, unsupported or managed native fields fail explicitly; they are not silently ignored. All fields must be serializable configuration data.

The existing model, iterations and config SDK arguments remain compatible through an explicit translation for OpenEvolve. Use either that legacy form or engine_config/c3; mixing them is rejected. For example, legacy config.objective maps to engine_config.prompt.system_message, and config.provider maps to c3.provider.

Inspect requested and effective settings

Open Run settings on the private run page, or call run.configuration() from Python. Requested settings show what was submitted; effective settings include resolved defaults. The record also identifies the engine and adapter version. Existing historical runs remain readable, but cannot retrospectively recover which values were explicitly supplied if that distinction was never stored.

Select c3={"hardware_profile": "l40", "provider": "nextgen"} for NextGen L40 compute. Omit provider to let C3 choose. c3.inference_connection is currently openrouter, and c3.max_concurrent_evaluations is fixed at 1. Selecting a GPU does not make CPU-only Python use CUDA; the candidate or evaluator must implement GPU work.

Candidate and evaluator

The evaluator must define evaluate(program_path), load the candidate at that path, and return finite numeric metrics including combined_score. OpenEvolve maximizes that score. If your natural metric is loss or latency, convert it to a score where higher is better and retain the original metric for interpretation.

The pilot accepts small inline Python sources, up to 256,000 UTF-8 bytes per source. Dependency installation, custom evaluation images and large dataset configuration are not exposed by this research interface yet. The supplied quickstart uses the Python standard library and the GPU's CUDA driver.

Time and evaluation limits

Limit	Default	Pilot range
max_runtime_seconds	21,600 seconds, 6 hours	30 seconds to 24 hours
evaluation_timeout_seconds	3,600 seconds, 1 hour	10 seconds to 1 hour
max_evaluations	OpenEvolve max_iterations + 1	Up to 21, including the baseline
budget_microcredits	No explicit campaign cap	Optional positive amount, subject to available account credits

The campaign clock includes provisioning and queue time. The evaluation timeout bounds compute execution after the script starts. A cold GPU can wait before that execution begins. A local SDK wait timeout affects neither limit.

Choose limits for your actual experiment. The defaults allow room for provisioning and substantive evaluations; a known ten-minute evaluator can request evaluation_timeout_seconds=600. Short deliberate failure tests use smaller limits, but those are not recommended research defaults. The campaign also stops when its requested search finishes, even if time remains. Early stopping can complete successfully with fewer evaluations than the maximum. An iteration that fails to produce an evaluable candidate need not create a compute job.

With native engine_config submissions, max_evaluations can be lower than max_iterations + 1. This is a hard C3 admission limit: reaching it can stop the run before the engine finishes, rather than count as successful early stopping. The legacy submission form continues to require enough slots for the baseline and every requested iteration.

Override only the limits you need:

limits = {
    "max_runtime_seconds": 43_200,      # 12-hour campaign
    "evaluation_timeout_seconds": 3600, # up to one hour per evaluation
    "max_evaluations": 11,             # baseline plus ten candidates
}
# Pass engine_config={"max_iterations": 10} and limits=limits to the SDK.

An idempotency key applies to the entire request. Retry the same request with the same key after a lost response; changing its model, inputs or limits requires a new key for a new campaign.

Credits and reservations

Currency fields use GBP microcredits: 1,000,000 microcredits = £1. A campaign budget is optional; available account credits still apply.

C3 reserves compute credit using the evaluation timeout before admitting a job, then settles its actual charge. A one-hour timeout therefore requires a larger temporary reservation than a three-minute timeout. Campaign admission considers both spent and committed credits. A small explicit budget can stop the next step while a previous reservation is still settling, even when completed work was brief. Choose an appropriate known runtime or sufficient credit; increasing a time limit does not increase your configured budget automatically.

Inference also reserves credit before calling OpenRouter and settles the reported cost. Uncertain outcomes remain committed for verified reconciliation; the system does not assume a lost response was free or automatically repeat a paid call.

GPU billing reuses C3's existing accounting without charging compute twice. The staging pilot uses an explicit 1 USD to 1 GBP inference test tariff, not a market exchange rate or production price. It currently adds no customer controller fee; the operator's controller and provider hosting costs are separate.