Shared tools

This toolkit supplies building blocks for the sample environments rather than a benchmark task of its own. It represents documents as source files and sections, exposes list, grep, and read operations, and provides a Python calculation tool.

What you supply

Build a Corpus from your task’s documents and choose the tools to expose through your environment. Configure result lengths, permitted calculation imports, and execution limits to suit the task. The toolkit does not define a question, reward, or completion rule; those belong to your environment.

What to adapt

Reuse the corpus tools when your agent works with read-only evidence. Replace document parsing or tool output formatting when your sources need a different structure. PythonTool runs calculations in a restricted subprocess with resource limits; it is not a container or a security boundary for arbitrary untrusted code.

The reference below covers the document model and individual tools.

Corpus

Expose a read-only collection of source files and addressable sections to task tools.

from focus.environments.toolkit import Corpus

Definition

@dataclass(frozen=True)
class Corpus

Fields

files: tuple[SourceFile, ...] = ()

Corpus.paths

def paths(self) -> tuple[str, ...]

Corpus.resolve

def resolve(self, path: str) -> SourceFile | None

A file from what the model typed: an exact path, else a unique suffix.

The suffix has to start at a path-component boundary — a whole tail of the path, never a tail of one name. Bare endswith made "ax.txt" resolve "a/tax.txt" uniquely and confidently, which is worse than not resolving: the model gets a file it did not ask for and cites it.

No basename tier: basename equality implies a boundary-aligned suffix, so it could only ever fire where the suffix pass already found nothing.

Corpus.manifest

def manifest(self, *, label: str='sections') -> str

The file list that goes in the prompt — the discovery affordance.

label is the word this task calls its sections by (“provisions” for a statute, “headings” for a manual): the manifest is prompt text a model reads, so it should use the task’s own vocabulary rather than this module’s.

DEFAULT_IMPORTS

List the imports allowed by the Python calculation tool’s default code policy.

from focus.environments.toolkit import DEFAULT_IMPORTS

Definition

DEFAULT_IMPORTS = frozenset({'math', 'decimal', 'fractions', 'itertools', 'datetime', 'statistics', 'json', 're', 'collections'})

GrepTool

Search the task corpus with a regular expression and report matching paths, lines, and sections.

from focus.environments.toolkit import GrepTool

Definition

class GrepTool(BaseTool)

GrepTool.init

def __init__(self, corpus: Corpus, *, description: str=DEFAULT_DESCRIPTION, max_hits: int=40, max_chars: int=4000, search_timeout: float=1.0, max_pattern_chars: int=512)

GrepTool.call

def call(self, params: str | dict[str, Any], *, workspace: object=None, **kwargs: object) -> str

ListTool

List the files available in the task corpus.

from focus.environments.toolkit import ListTool

Definition

class ListTool(BaseTool)

ListTool.init

def __init__(self, corpus: Corpus, *, description: str | None=None, section_arg: str='section')

ListTool.call

def call(self, params: str | dict[str, Any], **kwargs: Any) -> str

PythonTool

Run a calculation in a subprocess with configured execution limits and an import policy.

from focus.environments.toolkit import PythonTool

Definition

class PythonTool(BaseTool)

PythonTool.init

def __init__(self, *, timeout: float=10.0, max_chars: int=3000, allowed_imports: Iterable[str]=DEFAULT_IMPORTS, description: str | None=None)

PythonTool.call

async def call(self, params: str | dict[str, Any], **kwargs: object) -> str

ReadTool

Read a file or named section from the task corpus with line numbers for citation.

from focus.environments.toolkit import ReadTool

Definition

class ReadTool(BaseTool)

ReadTool.init

def __init__(self, corpus: Corpus, *, description: str | None=None, section_arg: str='section', section_help: str=DEFAULT_SECTION_HELP, max_line_chars: int=500, max_chars: int=0)

ReadTool.call

def call(self, params: str | dict[str, Any], *, workspace: object=None, **kwargs: object) -> str

Section

Identify a labeled range of lines within a source file.

from focus.environments.toolkit import Section

Definition

@dataclass(frozen=True)
class Section

Fields

label: str
start: int
end: int

Sectioner

Define a callable that splits source text into addressable sections for corpus tools.

from focus.environments.toolkit import Sectioner

Definition

Sectioner = Callable[[str], Sequence['Section']]

SourceFile

Hold a mounted file’s content and the sections available for inspection.

from focus.environments.toolkit import SourceFile

Definition

@dataclass(frozen=True)
class SourceFile

Fields

path: str
text: str
sections: tuple[Section, ...] = ()
_lines: tuple[str, ...] = field(init=False, repr=False, compare=False)

SourceFile.sectioned

@classmethod
def sectioned(cls, path: str, text: str, sectioner: Sectioner) -> SourceFile

Build a file, running sectioner over its text for the section index.

SourceFile.lines

def lines(self) -> tuple[str, ...]

SourceFile.section_at

def section_at(self, line: int) -> str

The most specific section containing a 1-based line.

Spans nest, so a line inside (c)(1) is also inside (c). The narrowest one is the citation worth printing: “§63(c)” points at sixty lines, while “§63(c)(1)” points at the rule.

SourceFile.find

def find(self, label: str) -> Section | None

focus.environments.toolkit.grep.DEFAULT_DESCRIPTION

Supply the default model-facing description of the corpus search tool.

from focus.environments.toolkit.grep import DEFAULT_DESCRIPTION

Definition

DEFAULT_DESCRIPTION = 'Search the files with a regular expression. Returns matching lines as ' + '`path:line: text`, naming the section each hit fell in, which is how you cite ' + 'what you relied on. Search for the distinctive words the passage itself would ' + 'use, not a sentence copied from the question.'

focus.environments.toolkit.read.DEFAULT_DESCRIPTION

Supply the default model-facing description of the corpus reading tool.

from focus.environments.toolkit.read import DEFAULT_DESCRIPTION

Definition

DEFAULT_DESCRIPTION = 'Read a file by path, with 1-based line numbers you can cite. Pass `{section}` to ' + 'read just one section of it (the file list names them); otherwise you get the ' + 'whole file from `offset`. Read the whole section, not just the line grep ' + 'matched -- the sentence that changes the answer is usually a line or two ' + 'below it.'

DEFAULT_SECTION_HELP

Supply the default explanation of how to select a named file section.

from focus.environments.toolkit.read import DEFAULT_SECTION_HELP

Definition

DEFAULT_SECTION_HELP = "one section of that file, e.g. '(c)(1)'"

screen_code

Parse Python code and reject operations disallowed by the calculation tool’s code policy.

from focus.environments.toolkit import screen_code

Definition

def screen_code(code: str, *, allowed_imports: Iterable[str]=DEFAULT_IMPORTS) -> ast.Module