Timeout Configurations and Limits for Theorem Proving Attempts in LeanAgent

LeanAgent enforces a default 600-second wall-clock timeout per theorem, with optional expansion limits and a 1-second tolerance buffer to prevent premature termination.

The lean-dojo/leanagent repository implements strict runtime controls to balance thoroughness against computational budget. Understanding these timeout configurations and limits for theorem proving attempts is essential for optimizing proof search strategies and resource allocation.

Core Timeout Settings in LeanAgent

LeanAgent employs a dual-control mechanism that terminates proof searches based on either elapsed time or node expansions.

Wall-Clock Timeout (timeout)

The primary limit is a wall-clock timeout measured in seconds. By default, this is set to 600 seconds (10 minutes) in leanagent.py and prover/evaluate.py.

In prover/proof_search.py, the BestFirstSearchProver class stores this value and checks it after every search step:

self.total_time = time.monotonic() - time_start + tolerance
if self.total_time > self.timeout:
    # Search terminates

The check occurs at line 175-180, where self.total_time is compared against self.timeout.

Expansion Limits (max_expansions)

Optionally, you can constrain the search space using max_expansions, which limits the number of tree node expansions. By default, this is None (unlimited).

The termination logic checks both conditions:

if self.total_time > self.timeout or (
    self.max_expansions is not None
    and self.num_expansions > self.max_expansions
):
    # Stop search

This allows you to set a hard ceiling on computational effort regardless of time elapsed.

Tolerance Constants

To prevent premature termination due to floating-point rounding errors, LeanAgent adds a tolerance of 1 second to the measured time. This fixed constant is defined in proof_search.py and added to total_time before comparison with the timeout limit.

Where Timeout Configurations Are Defined

The timeout configurations flow through three critical files in the repository:

• prover/proof_search.py: Core implementation of BestFirstSearchProver containing the timeout checking logic (lines 175-180) and the tolerance constant
• leanagent.py: High-level driver that instantiates DistributedProver with the default timeout=600 (around line 1332)
• prover/evaluate.py: CLI wrapper exposing --timeout and --max_expansions arguments with defaults of 600 and None respectively (around line 172)

The values propagate from the CLI or main driver down through DistributedProver.__init__ to BestFirstSearchProver.__init__, where they are stored as instance variables.

Configuring Timeouts via Command Line

When running evaluation scripts, you can override the default 600-second limit using the --timeout flag:

python -m prover.evaluate \
    --data_path data/lean4 \
    --timeout 300 \
    --max_expansions 5000

This configuration passes the 300-second limit and 5,000 expansion cap to the underlying BestFirstSearchProver.

Programmatic Configuration in Python

For custom integrations, instantiate DistributedProver directly with your desired limits:

from prover.proof_search import DistributedProver

prover = DistributedProver(
    use_vllm=False,
    ckpt_path="path/to/checkpoint.ckpt",
    indexed_corpus_path=None,
    tactic=None,
    module=None,
    num_workers=4,
    num_gpus=4,
    timeout=1200,              # 20 minutes

    max_expansions=50_000,     # Stop after 50k expansions

    num_sampled_tactics=64,
    raid_dir="/raid",
    checkpoint_dir="checkpoints",
    debug=False,
)

During a search, you can inspect the current limits and progress through the prover's attributes:

# Inside a proof search callback or debug context

print(f"Timeout limit: {prover.timeout}s")
print(f"Max expansions: {prover.max_expansions}")
print(f"Current expansions: {prover.num_expansions}")
print(f"Elapsed time: {prover.total_time}s")

Summary

• Default timeout: 600 seconds (10 minutes) defined in leanagent.py and prover/evaluate.py
• Optional expansion limit: max_expansions defaults to None but can cap node expansions
• Tolerance buffer: 1-second constant in proof_search.py prevents rounding errors
• Termination logic: Located in prover/proof_search.py lines 175-180, checks both time and expansion limits
• Configuration: Pass via CLI (--timeout, --max_expansions) or programmatically to DistributedProver

Frequently Asked Questions

What happens when a theorem proving attempt reaches the timeout limit?

When the elapsed wall-clock time exceeds the configured timeout value (default 600 seconds), the BestFirstSearchProver immediately terminates the search loop and returns the best partial result found so far. The check occurs after every search step in prover/proof_search.py, ensuring responsive termination even during deep searches.

Can I set different timeout configurations for different theorems?

Yes, since the timeout and max_expansions parameters are passed per DistributedProver instance, you can create separate prover instances with different limits for different theorem batches. However, within a single DistributedProver instance, all worker processes share the same timeout configuration, so you would need to instantiate multiple provers to vary limits across individual theorems.

What is the difference between timeout and max_expansions in LeanAgent?

The timeout parameter limits the wall-clock time in seconds, protecting against infinite loops or computationally expensive proof branches regardless of search depth. The max_expansions parameter limits the number of tree nodes expanded, providing a deterministic ceiling on computational effort independent of hardware speed. Use timeout for time-budget constraints and max_expansions for reproducible resource limits across different machines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}