LlamaBot

StructuredBot is a specialized bot class designed for scenarios requiring guaranteed structured outputs from LLMs. Unlike SimpleBot, which returns raw text, StructuredBot provides:

• Pydantic schema validation: Enforces the structure defined by your Pydantic models.
• Automatic retries: Automatically attempts to fix the output if the LLM produces invalid data.
• Validated objects: Returns actual Pydantic model instances instead of strings.
• Error reporting: Provides clear error messages when validation fails after all retry attempts.

AgentBot is a graph-based agent that uses PocketFlow to orchestrate tool execution. Instead of using simple loops, it builds a flow graph consisting of:

1. A decision node (DecideNode): Analyzes the conversation and selects which tool to execute.
2. Tool nodes: Execute the selected tools.
3. Loopback: Tools can loop back to the decision node (except terminal tools).
4. Terminal nodes: The flow continues until a terminal node is reached.

This approach allows for visual flow representation, flexible orchestration, and automatic tool wrapping where you provide plain callables.

ToolBot is a specialized bot class designed for tool selection and execution rather than multi-turn conversation. It analyzes user requests, selects the most appropriate tool from a provided toolkit, extracts necessary arguments, and returns a single function call with the proper arguments.

Use ToolBot for:

• Automation workflows: Executing specific functions based on intent.
• Data analysis: Running custom code or analysis tools.
• API integrations: Calling external services via function calling.
• Single-turn scenarios: When you need a direct action rather than a chat.

Comparison with other bots:

• SimpleBot: Focuses on conversation and text generation.
• AgentBot: Multi-turn planning and execution with multiple tools.
• QueryBot: Document retrieval and question answering.

Since @prompt uses Jinja2, you can use complex logic within your docstrings to create dynamic prompts:

• Loops: Iterate over lists or complex data structures.
• Conditionals: Include or exclude content based on function arguments.
• Variables: Inject any function argument into the template.

Note: The decorator automatically validates that every {{ variable }} in the docstring has a corresponding parameter in the function signature.

@prompt(role="user")
def complex_prompt(items, include_details=False):
    """Review the following items:
    {% for item in items %}
    - {{ item }}
    {% if include_details %}
      (Details included)
    {% endif %}
    {% endfor %}
    """

By default, tools loop back to a decision node (controlled by loopback_name="decide"). If you want a tool to signal the end of a bot's execution (e.g., sending a final response to a user), set loopback_name=None.

This is required for tools like respond_to_user or return_object_to_user to prevent the bot from attempting to make further decisions after the final output is generated.

from llamabot.components.tools import tool

@tool(loopback_name=None)
def respond_to_user(response: str) -> str:
    """Respond to the user with a message.

    :param response: The message to send
    :return: The response message
    """
    return response

The behavior of ChatMemory during append and retrieve operations is determined by the node_selector provided during initialization.

• LinearNodeSelector (Default): Messages are appended in a simple chronological sequence. append always connects the new message to the most recent assistant message. retrieve simply returns the $N$ most recent messages.
• LLMNodeSelector: Uses an LLM to analyze the content of a new message and determine which existing conversation thread it belongs to. This allows for non-linear, branching conversation histories. retrieve uses semantic search to find relevant nodes and then traverses their parent paths to provide full context.

LlamaBot uses PocketFlow (Flow / AsyncFlow) for agent graph orchestration.

Specifically, the AgentBot serves as a reference implementation of a PocketFlow graph that follows a decide $\rightarrow$ tool $\rightarrow$ loopback topology. While AgentBot provides a standard pattern, the library is designed to allow users to fork or replace components like DecideNode and edges to implement their own custom orchestration graphs.

LlamaBot's Git CLI commands (llamabot git hooks and llamabot git compose) are designed to work from any subdirectory within a Git worktree. The system automatically resolves the enclosing repository's Git directories, so you do not need to be at the repository root to run commands.

Error Handling: If you attempt to run these commands outside of a Git worktree, the system will raise a RuntimeError with instructions to run the command inside a Git repository.

LlamaBot is a Python library designed for interacting with Large Language Models (LLMs) using a composable API. It leverages LiteLLM under the hood, allowing you to switch between different LLM providers and models without changing your core application logic.

The library is built around three primary abstractions:

1. Bots: Callable objects that encapsulate specific prompts and model interaction logic.
2. Messages: The structured content used in conversations, categorized as system, human, or assistant content.
3. Components: Optional extensions used to enhance bot capabilities, such as document stores for Retrieval-Augmented Generation (RAG).