`yggdrasil.loki.tools`¶

tools ¶

Loki tools — the file/shell capabilities the agent acts through.

A :class:Tool is one concrete thing the agentic loop can do with its hands: list a directory, read a file, write or edit one, search the tree, run a command. The agent's engine (:mod:yggdrasil.loki.engine, the "brain") emits a JSON tool call; Loki looks the tool up in a :class:Toolbox and runs it, feeding the result back as the next observation. That reason → act → observe loop lives on :meth:yggdrasil.loki.Loki.act.

Every filesystem tool is confined to a root (the agent's working tree): a path that resolves outside the root is refused, so an autonomous agent can read and modify the project it was pointed at and nothing above it. Mutating tools record what they touched in :attr:Toolbox.changed, so a run can report exactly which files it created or edited.

Tool `dataclass` ¶

Tool(
    name: str,
    description: str,
    params: dict[str, str],
    run: Callable[..., str],
    mutates: bool = False,
)

One named capability the agent can invoke by emitting a JSON call.

run takes the decoded args as keyword arguments and returns a string observation the agent reads on its next turn. params maps each argument name to a one-line description — it's rendered into the system prompt so the model knows the tool's shape.

Toolbox `dataclass` ¶

Toolbox(tools: dict[str, Tool] = dict(), changed: list[str] = list())

A named set of tools plus the run state the loop reports on.

spec ¶

spec() -> str

The tool catalog as prompt text — one block per tool.

call ¶

call(name: str, args: dict[str, Any]) -> str

Run a tool by name; surface any error as a readable observation.

filesystem_toolbox ¶

filesystem_toolbox(
    root: str | Path = ".",
    *,
    read_only: bool = False,
    allow_shell: bool = False,
    allow_web: bool = False,
    confirm: Optional[Callable[[str], bool]] = None
) -> Toolbox

Build the default toolbox rooted at root.

The read tools (list_dir, read_file, find, grep, read_table) are always present — discovery, including parsing local tabular files (CSV/Parquet/Arrow/XLSX/JSON) through the io handlers. The write tools — write_file, edit_file, run_python (write & run Python), and run (a shell command) — are added unless read_only; the agent can code and shell out by default. allow_shell is kept for back-compat but no longer gates run. Network tools (web_*) are added only with allow_web.

confirm (fn(action) -> bool) gates destructive ops on non-temporary assets — overwriting/editing an existing file outside the system temp dir asks first; new files and scratch/temp files don't.

yggdrasil.loki.tools¶