Python API

from scientist.config import ScientistConfig

config = ScientistConfig.from_yaml("task.yaml")

@dataclass
class TaskConfig:
    name: str              # Task identifier
    description: str       # What agents should do
    files: list[str]       # Key files to focus on
    tips: str              # Additional hints for agents
    seed: list[str]        # Files/dirs copied into workspace

@dataclass
class GraderConfig:
    entrypoint: str        # "module.path:ClassName", required, resolved inside the grader venv
    setup: list[str]       # Shell commands run in .scientist/private/grader_venv/ at start time
    timeout: int           # Eval timeout in seconds (default: 300)
    args: dict[str, Any]   # Extra grader arguments
    private: list[str]     # Files hidden from agents
    direction: str         # "maximize" or "minimize"

@dataclass
class AgentConfig:
    count: int             # Number of worker agents (default: 1)
    runtime: str           # "claude_code", "codex", "opencode"
    model: str             # Model name or ID (default: "sonnet")
    max_turns: int         # Max conversation turns (default: 0 = unlimited)
    timeout: int           # Stall watchdog in seconds (default: 1200)
    research: bool         # Enable web search (default: True)
    cadence: list[CadenceActionConfig]  # Periodic actions

@dataclass
class CoordinationConfig:
    enabled: bool
    mode: str                    # "auto", "advisory", or "managed"
    coordinator_threshold: int   # default: 8 workers
    workers_per_coordinator: int # default: 4
    auto_personas: bool
    seed: str                    # optional YAML/JSON DAG seed

@dataclass
class LabsConfig:
    count: int                 # default: 1
    rotation: RotationConfig

@dataclass
class RotationConfig:
    enabled: bool
    every: int
    rank_window: int
    min_evals: int
    dest_weighting: str
    max_per_cycle: int
    rotation_cooldown: int

@dataclass
class CadenceActionConfig:
    name: str              # Action name (e.g. "reflect")
    every: int             # Trigger every N evals
    is_global: bool        # Use global eval count (default: False)
    trigger: str           # "interval" or "plateau"
    options: dict          # trigger-specific options such as epsilon

@dataclass
class SharingConfig:
    attempts: bool            # Share experiment scores (default: True)
    notes: bool            # Enable shared notes (default: True)
    skills: bool           # Enable shared skills (default: True)

@dataclass
class WorkspaceConfig:
    results_dir: str       # Where to store results (default: "./results")
    repo_path: str         # Git repository root (default: ".")

@dataclass
class RunConfig:
    verbose: bool          # Print verbose manager output (default: False)
    ui: bool               # Start the web dashboard (default: False)
    session: str           # "local", "tmux", or "docker"
    docker_image: str      # Docker image override
    stop: RunStopConfig    # Optional run-level auto-stop conditions

@dataclass
class RunStopConfig:
    score_threshold: float | None     # Stop when best real score reaches this threshold
    max_real_attempts: int | None     # Stop after this many finalized real experiments

scientist launch -c task.yaml run.stop.score_threshold=0.8
scientist launch -c task.yaml run.stop.max_real_attempts=30

from scientist.types import Task

task = Task(
    id="my-task",
    name="My Task",
    description="Optimize solution.py",
    metadata={"files": ["solution.py"]},
)

from scientist.types import Score

score = Score(
    value=0.85,
    name="eval",
    explanation="Runtime: 1.2s",
)

from scientist.types import Score, ScoreBundle

bundle = ScoreBundle(
    scores={"eval": Score(value=0.85, name="eval")},
    aggregated=0.85,
)

from scientist.types import Attempt

experiment = 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",
)

from typing import Protocol, runtime_checkable
from scientist.types import ScoreBundle, Task

@runtime_checkable
class GraderInterface(Protocol):
    async def grade(
        self,
        codebase_path: str,
        tasks: list[Task],
        **kwargs,
    ) -> ScoreBundle: ...

from scientist.grader.base import BaseGrader
from scientist.types import Task, ScoreBundle

class MyGrader(BaseGrader):
    async def grade(self, codebase_path: str, tasks: list[Task]) -> ScoreBundle:
        score = self._make_score(0.85, explanation="Good result")
        return self._make_bundle(score, aggregated=0.85)

BaseGrader(name: str, description: str = "", is_public: bool = True, **kwargs)

from scientist.grader import TaskGrader
from scientist.types import ScoreBundle

class Grader(TaskGrader):
    def evaluate(self) -> float | ScoreBundle:
        result = self.run_program("solution.py")
        return float(result.stdout.strip())

from scientist.commons.attempts import read_attempts, write_attempt
from scientist.types import Attempt

# Read all experiments
experiments = read_attempts("/path/to/.scientist")
for a in experiments:
    print(f"{a.agent_id}: {a.score} ({a.status})")

# Write an experiment
experiment = Attempt(
    commit_hash="abc123",
    agent_id="agent-1",
    title="Improved performance",
    score=0.85,
    status="improved",
    parent_hash="def456",
    timestamp="2025-03-15T10:30:00+00:00",
)
write_attempt("/path/to/.scientist", experiment)

---
creator: agent-1
created: 2026-03-15T10:30:00+00:00
---

# Vectorization insights

Content goes here...

skills/
└── profiler/
    ├── SKILL.md       # Description and usage
    └── profile.py     # Implementation