tools

agentic_ml.research.tools

Strands tools exposed to the research agent.

Each tool is a thin wrapper over an LLM-agnostic action in :mod:agentic_ml.core.engine. Tools are built by factory functions that close over the :class:~agentic_ml.core.engine.ResearchContext, plus any task-specific tools.

make_finish_research

make_finish_research(ctx: ResearchContext)

Build a finish_research tool bound to ctx.

Source code in src/agentic_ml/research/tools/control.py

def make_finish_research(ctx: ResearchContext):
    """Build a ``finish_research`` tool bound to ``ctx``."""

    @tool
    def finish_research(reason: str = "") -> str:
        """Signal that the research loop is complete.

        Call this when the iteration budget is spent or no further improvement seems likely.
        """
        return f"Research finished. {reason}".strip()

    return finish_research

make_profile_dataset

make_profile_dataset(ctx: ResearchContext)

Build a profile_dataset tool bound to ctx.

Source code in src/agentic_ml/research/tools/data.py

def make_profile_dataset(ctx: ResearchContext):
    """Build a ``profile_dataset`` tool bound to ``ctx``."""

    @tool
    def profile_dataset() -> str:
        """Return an aggregate description of the dataset (schema, dtypes, missing values).

        Only summary statistics are exposed; the raw rows are never revealed.
        """
        return ctx.profile_text

    return profile_dataset

make_create_trial

make_create_trial(ctx: ResearchContext)

Build a create_trial tool bound to ctx.

Source code in src/agentic_ml/research/tools/experiment.py

def make_create_trial(ctx: ResearchContext):
    """Build a ``create_trial`` tool bound to ``ctx``."""

    @tool
    def create_trial(description: str, model_py: str, helpers_py: str = "") -> dict:
        """Create and evaluate a new trial.

        Args:
            description: A short natural-language summary of the idea being tested.
            model_py: Source of a `model.py` defining a `Model` class per the contract.
            helpers_py: Optional source of a `helpers.py` module imported by `model.py`.

        Returns:
            A dict with the trial id, status ("ok"/"failed"/"budget_exhausted"), the metrics,
            the evaluation runtime, whether the save/load roundtrip passed, any error message,
            and how many trials remain (``iterations_remaining``) — with a ``budget_note``
            telling you to call `finish_research` once that reaches 0.
        """
        return create_trial_action(ctx, description, model_py, helpers_py)

    return create_trial

make_read_trial

make_read_trial(ctx: ResearchContext)

Build a read_trial tool bound to ctx.

Source code in src/agentic_ml/research/tools/experiment.py

def make_read_trial(ctx: ResearchContext):
    """Build a ``read_trial`` tool bound to ``ctx``."""

    @tool
    def read_trial(trial_id: str) -> dict:
        """Read the `model.py` and `helpers.py`. This is useful for the agent to refresh
        the code for several scenarios:
            - Read the code of a previous trial to reuse it as a starting point if the
                new proposal is based on it.
            - Refresh the code of a previous trial to fix a bug.
            - Any other reason.
        Args:
            trial_id: The id of the trial to read.

        Returns:
            A dict with keys "model.py" and "helpers.py" containing the source code of
            each file ("helpers.py" is optional).
        """
        return ctx.workspace.read_trial_code(trial_id)

    return read_trial

make_read_leaderboard

make_read_leaderboard(ctx: ResearchContext)

Build a read_leaderboard tool bound to ctx.

Source code in src/agentic_ml/research/tools/leaderboard.py

def make_read_leaderboard(ctx: ResearchContext):
    """Build a ``read_leaderboard`` tool bound to ``ctx``."""

    @tool
    def read_leaderboard() -> str:
        """Return the current leaderboard as CSV text.

        Columns: ID, Status, one column per tracked metric, runtime and description.
        Use it to decide what to try next and to avoid repeating failed ideas. If you
        only want to inspect a specific trial, use `read_leaderboard_row(trial_id)`.
        """
        return read_leaderboard_action(ctx)

    return read_leaderboard

make_read_leaderboard_row

make_read_leaderboard_row(ctx: ResearchContext)

Build a read_leaderboard_row tool bound to ctx.

Source code in src/agentic_ml/research/tools/leaderboard.py

def make_read_leaderboard_row(ctx: ResearchContext):
    """Build a ``read_leaderboard_row`` tool bound to ``ctx``."""

    @tool
    def read_leaderboard_row(trial_id: str) -> str:
        """Return the leaderboard row for a given trial ID as CSV text.

        Columns: ID, Status, one column per tracked metric, runtime and description.
        Use it to inspect the results of a specific trial.
        """
        return read_leaderboard_action(ctx, trial_id=trial_id)

    return read_leaderboard_row

build_tools

build_tools(ctx: ResearchContext) -> list

Compose the base tools with the task's extra tools.

Source code in src/agentic_ml/research/tools/__init__.py

def build_tools(ctx: ResearchContext) -> list:
    """Compose the base tools with the task's extra tools."""
    tools = [
        make_profile_dataset(ctx),
        make_create_trial(ctx),
        make_read_trial(ctx),
        make_read_leaderboard(ctx),
        make_read_leaderboard_row(ctx),
        make_finish_research(ctx),
    ]
    tools.extend(ctx.task.extra_tools(ctx))
    return tools