# 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[​](#engine-settings-and-c3-execution "Direct link to 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[​](#discover-supported-settings "Direct link to 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[​](#inspect-requested-and-effective-settings "Direct link to 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[​](#candidate-and-evaluator "Direct link to 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[​](#time-and-evaluation-limits "Direct link to 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[​](#credits-and-reservations "Direct link to 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.