Saplings

Saplings provides several agent implementations, each balancing speed, cost, and effectiveness differently:

• GreedyAgent: Implements greedy best-first search. It is the fastest and cheapest but cannot backtrack, making it the least effective.
• MonteCarloAgent: Implements Monte Carlo Tree Search (MCTS). It is the most effective as it balances exploration and exploitation, but it is the slowest and most expensive.
• AStarAgent: Implements a variation of the A* pathfinding algorithm. It is a middle-ground option that can backtrack and recover from mistakes but does not update its strategy based on past trajectories.
• COTAgent: A standard Chain-of-Thought agent. It does not implement any search; it simply calls tools sequentially. Use this as a baseline for comparison.

Saplings provides several agent implementations depending on the desired reasoning strategy:

• MonteCarloAgent: Implements Monte Carlo Tree Search (MCTS).
• AStarAgent: Implements A* search.
• GreedyAgent: Implements greedy best-first search.
• COTAgent: Implements standard Chain-of-Thought (no tree search).

This example demonstrates the minimum setup required to create a search-enabled agent using a multiplication tool and the MonteCarloAgent algorithm. Saplings uses Model (a LiteLLM wrapper) and an Evaluator to guide the search process.

from saplings.examples import MultiplicationTool
from saplings import MonteCarloAgent, Evaluator, Model

model = Model(model="openai/gpt-4o") # Wraps LiteLLM
evaluator = Evaluator(model)
tools = [MultiplicationTool()]

agent = MonteCarloAgent(tools, model, evaluator)
messages, _, _ = agent.run("Let x = 9418.343 * 8.11 and y = 2x. Calculate (xy)(x^2).")

Install the Saplings library using pip to add tree search capabilities to your agents.

$ pip install saplings

Messages are the core data structure in Saplings, representing a search trajectory (a list of messages). They are compatible with OpenAI message formats (user input, tool calls, tool responses, assistant responses).

Key features:

• OpenAI Compatibility: Use .to_openai_message() (or .to_openai_response()) to convert Saplings messages to OpenAI-style dictionaries.
• Raw Output: For tool responses, the raw_output property contains the original tool output, which may differ from the content property (the version shown to the model).

When an agent runs, it returns a list of messages representing the best trajectory found.

```python
# Running an agent and converting the trajectory to OpenAI format
messages, _, _ = agent.run("This is my prompt!")
openai_messages = [message.to_openai_response() for message in messages]

print(openai_messages)
# [{

An Evaluator guides the search process by scoring trajectories. It takes a list of messages (a trajectory) and returns a score between 0 and 1. A score of 1.0 typically indicates the problem is solved.

By default, Evaluator(model) uses the provided LLM to score trajectories. You can customize the system prompt and sampling rate via the Evaluator parameters, or implement a custom evaluator class.

from saplings import Evaluator

evaluator = Evaluator(model)

Saplings uses the Model class to wrap LiteLLM, providing access to over 100 LLMs. You specify the model using a provider/model string (e.g., openai/gpt-4o). Any additional keyword arguments (kwargs) passed to the Model constructor are passed down to all LiteLLM completion calls.

from saplings import Model

model = Model("openai/gpt-4o")

Once an agent is initialized with tools, a model, and an evaluator, you can execute it using .run() (synchronous) or .run_async() (asynchronous).

Return Values

The .run() method returns a tuple containing:

1. messages: A list of Message objects representing the best tool-use trajectory.
2. score: The final score of the trajectory as determined by the evaluator.
3. is_solution: A boolean indicating if the search terminated because the evaluator deemed the trajectory a solution.

# Synchronous
messages, score, is_solution = agent.run("What's 2 * 2?")

# Asynchronous
# messages, score, is_solution = await agent.run_async("What's 2 * 2?")