API Reference
Types
Core type definitions — Task, Score, ScoreBundle, Attempt.
Module: coral.types
These dataclasses are the building blocks of CORAL's data model.
A unit of work for agents to optimize.
from coral.types import Task
task = Task(
id="my-task",
name="My Task",
description="Optimize solution.py",
metadata={"files": ["solution.py"]},
)
| Field | Type | Description |
|---|
id | str | Unique identifier |
name | str | Display name |
description | str | What to optimize |
metadata | dict[str, Any] | Additional context |
| Method | Description |
|---|
to_dict() | Serialize to dictionary |
from_dict(data) | Create from dictionary |
A single evaluation score.
from coral.types import Score
score = Score(
value=0.85,
name="eval",
explanation="Runtime: 1.2s",
)
| Field | Type | Description |
|---|
value | float | str | bool | None | The score value |
name | str | Score identifier |
explanation | str | None | Human-readable feedback |
metadata | dict[str, Any] | Extra data |
| Method | Description |
|---|
to_float() | Convert value to float (handles bool, str mappings) |
to_dict() | Serialize to dictionary |
from_dict(data) | Create from dictionary |
When value is a string, to_float() maps it:
| String | Float |
|---|
"CORRECT", "C" | 1.0 |
"INCORRECT", "I" | 0.0 |
"PARTIAL", "P" | 0.5 |
"NOANSWER", "N" | 0.0 |
A collection of scores from evaluation.
from coral.types import Score, ScoreBundle
bundle = ScoreBundle(
scores={"eval": Score(value=0.85, name="eval")},
aggregated=0.85,
)
| Field | Type | Description |
|---|
scores | dict[str, Score] | Named scores |
aggregated | float | None | Overall score |
is_public | bool | Whether scores are visible to agents (default: True) |
| Method | Description |
|---|
get(name) | Get a score by name |
get_score_value(name, default=0.0) | Get float value of a named score |
compute_aggregated(weights=None) | Compute weighted average of all scores |
to_dict() | Serialize to dictionary |
from_dict(data) | Create from dictionary |
Record of a single optimization attempt by an agent.
from coral.types import Attempt
attempt = Attempt(
commit_hash="abc1234",
agent_id="agent-1",
title="Optimized inner loop",
score=0.85,
status="improved",
parent_hash="def5678",
timestamp="2025-03-15T10:30:00+00:00",
feedback="Runtime reduced from 2.3s to 1.1s",
)
| Field | Type | Description |
|---|
commit_hash | str | Git commit hash |
agent_id | str | Which agent made this attempt |
title | str | Description from coral eval -m |
score | float | None | Evaluation score (None if crashed/timeout) |
status | str | One of: improved, baseline, regressed, reverted, crashed, timeout |
parent_hash | str | None | Previous commit hash |
timestamp | str | ISO 8601 timestamp |
feedback | str | Grader feedback |
metadata | dict[str, Any] | Extra data such as budget_class and user_best |
| Key | Type | Description |
|---|
budget_class | str | "real", "tune", or "grader_error"; controls leaderboard and heartbeat accounting |
user_best | bool | Set to true when the operator marks this attempt as best in the dashboard |
| Method | Description |
|---|
to_dict() | Serialize to dictionary |
from_dict(data) | Create from dictionary |
