TOML configuration reference¶

# ============================================================================
# Maximal APE configuration — every section and key the loader understands.
# (Draft reference; to be revisited.)
#
# Run with:  python -m ape config.toml            (resolves paths against the
#                                                  directory containing this file)
#            python -m ape config.toml -r /proj   (resolve against /proj instead)
#            python -m ape config.toml -o /out    (redirect output files to /out)
# ============================================================================

# --- Input data --------------------------------------------------------------
[data]
path = "data.jsonl"                          # required; .csv or .jsonl, resolved vs project root
schema = "myproj.components.MyProblem"       # required; dotted path to a DataModel subclass
start_id = "problem-0042"                    # optional; resume the input slice from this id
end_id   = "problem-0100"                    # optional; stop after this id (inclusive)

# --- Instruction prompt ------------------------------------------------------
[prompt]
template = "prompts/instruction.md"          # required; mustache template, {{ field }} from the data item

# --- Main LLM ----------------------------------------------------------------
[model]
provider = "langchain_google_genai.ChatGoogleGenerativeAI"  # required; dotted path to a BaseChatModel class
name = "gemini-2.5-pro"                                      # required; passed as model=<name> to the class
# Optional cheaper helper LLM, used to summarize long tool errors.
# Both keys must be set together, or both omitted (=> no helper, fall back to main LLM).
helper_provider = "langchain_google_genai.ChatGoogleGenerativeAI"
helper_name = "gemini-2.5-flash"

# --- Solution adapter --------------------------------------------------------
[adapter]
callable = "myproj.components.parse_solution"  # required; the parsing FUNCTION itself, Callable[[str], SolutionT]

# --- Solver knobs ------------------------------------------------------------
[solver]
reformat_prompt = "That answer didn't parse. Reply with ONLY the final answer."  # required, no default
tools = ["calculator", "lmfdb"]              # optional; names of [tools.X] tables to bind to the LLM

# All optional; names match the SolverConfig fields:
user_system_prompt = "You are an expert algebraist. Be terse."
context_window_size = 256000                 # int; None/omit => best-effort detection from the model
context_compaction_threshold = 0.8           # (0, 1]; occupancy ratio that triggers compaction
max_steps = 8                                # >= 1; inferences allowed before force-finish
error_summarization_threshold = 500          # >= 0; tool-output errors at least this long get summarized
solution_adaption_attempts = 3               # >= 1; reformat retries before declaring PARSING_FAILED
rate_limit_backoff_seconds = [2, 4, 8, 16, 32]  # all > 0; seconds to wait between provider rate-limit retries

# --- Checker -----------------------------------------------------------------
[checker]
callable = "myproj.components.MyChecker"     # required; a Checker class or a zero-arg factory
expose_as_tool = true                        # optional; also expose the checker to the LLM as a tool
checker_tool = "myproj.components.make_checker_tool"  # required iff expose_as_tool; tool factory
# Any extra keys here are forwarded as **kwargs to `callable` (and to `checker_tool`).

# --- Tool definitions --------------------------------------------------------
# Each [tools.X] is instantiated as callable(**remaining_keys). If the result is a
# ToolProvider, its get_tool() output is used (a single BaseTool, or a list — both
# are handled). Only tables listed in [solver] tools are actually loaded.
[tools.lmfdb]
callable = "ape.tools.LMFDB"           # required; this is a ToolProvider -> yields a list of tools
pool_workers = 2                             # extra keys => LMFDB(pool_workers=2, query_timeout=10)
query_timeout = 10

# --- Run parameters (fields of RunParams) ------------------------------------
[run]
save_file = "output/results.jsonl"           # JSONL of OutputBatches; also used for resume
metadata_file = "output/metadata.json"       # run metadata (incl. the pickled SolverConfig)
solver_workers = 4
checker_workers = 2
runs_per_data = 3                            # solver sessions attempted per data item
load_save = true                             # on start, skip ids already completed in save_file

# --- CLI dashboard -----------------------------------------------------------
[cli]
enabled = true                               # default true; set false to run headless (no dashboard)
log_file = "output/run.log"
session_log_file = "output/sessions.log"
log_level = "INFO"                           # name or int

# --- Logging suppression -----------------------------------------------------
[logging]
suppress = ["httpx", "langchain_core", "urllib3"]   # raise these loggers to WARNING

# --- User hooks --------------------------------------------------------------
# Optional callbacks invoked at well-defined points in the run. Each value is a
# dotted path to a Callable. Exceptions raised by hooks are logged and
# swallowed so a faulty hook cannot lose results or stop the run.
[hooks]
on_batch_saved = "myproj.components.on_batch_saved"  # Callable[[OutputBatch], None];
                                                     # fires right after the built-in save handler
                                                     # persists each batch - use to mirror results
                                                     # to an external store, push a metric, etc.