LlamaBot

https://ericmjl.github.io/llamabot/
Admin
LlamaBot is a Pythonic interface to large language models that enables easy experimentation with...
Tokens:83,527
Snippets:995
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete Example: Partitioned Document Store Setup

Source: https://ericmjl.github.io/llamabot/tutorials/querybot

This comprehensive example demonstrates setting up a partitioned LanceDBDocStore, adding documents to specific partitions ('tutorials', 'reference'), and performing targeted retrievals.

```python
from llamabot.components.docstore import LanceDBDocStore
from llamabot import QueryBot
from pathlib import Path

# Create partitioned document store
docstore = LanceDBDocStore(
    table_name="project-docs",
    enable_partitioning=True,
    default_partition="general",
)

docstore.reset()

# Organize documents by category
tutorial_files = list(Path("docs/tutorials").glob("*.md"))
reference_files = list(Path("docs/reference").glob("*.md"))

# Add tutorials
for file in tutorial_files:
    docstore.append(file.read_text(), partition="tutorials")

# Add reference docs
for file in reference_files:
    docstore.append(file.read_text(), partition="reference")

# Query specific partition directly
tutorial_results = docstore.retrieve(
    "how do I get started?",
    partitions=["tutorials"]  # Only search tutorials partition
)
print(f"Found {len(tutorial_results)} results in tutorials partition")

# Query multiple partitions
tutorial_and_ref_results = docstore.retrieve(
    "python syntax",
    partitions=["tutorials", "reference"]  # Search both partitions
)

# See what partitions exist
print(f"Available partitions: {docstore.list_partitions()}")
print(f"Tutorials count: {docstore.get_partition_count('tutorials')}")

# Create QueryBot (searches all partitions by default)
bot = QueryBot(
    system_prompt="You are a helpful documentation assistant.",
    docstore=docstore,
)

# QueryBot will search across all partitions
response = bot("How do I use the API?")

# To query only a specific partition, use docstore.retrieve() directly
# and then manually construct your prompt with those results
tutorial_only_results = docstore.retrieve(
    "getting started",
    partitions=["tutorials"]  # Only tutorials partition
)
# You can then use these results with your LLM of choice

```

--------------------------------

### Complete Example: Record QueryBot Calls

Source: https://ericmjl.github.io/llamabot/tutorials/recording_prompts

A full example demonstrating the setup, interaction, and data access for recording QueryBot calls using PromptRecorder.

```python
from llamabot.recorder import PromptRecorder, autorecord
from llamabot.bot.querybot import QueryBot

system_message = "You are a helpful assistant that can answer questions based on the provided documents."
model_name = "gpt-4"
doc_paths = ["document1.txt", "document2.txt"]

query_bot = QueryBot(system_message, model_name=model_name, document_paths=doc_paths)

with PromptRecorder() as recorder:
    query = "What is the main idea of document1?"
    response = query_bot(query)
    print(response.content)

    query = "How does document2 support the main idea?"
    response = query_bot(query)
    print(response.content)

print(recorder.dataframe())
recorder.panel().show()

```

--------------------------------

### Few-Shot Prompting with Examples

Source: https://ericmjl.github.io/llamabot/tutorials/prompts

Implement few-shot learning by including examples directly within the prompt template. This guides the model by showing desired input-output pairs.

```python
@prompt(role="user")
def classification_with_examples(text, categories):
    """Classify the following text into one of these categories:
    {% for category in categories %}
    - {{ category }}
    {% endfor %}

    Examples:
    Text: "The weather is sunny today"
    Category: Weather

    Text: "I love this new restaurant"
    Category: Food

    Text: "{{ text }}"
    Category:"""
```

--------------------------------

### Complete SimpleBot Example

Source: https://ericmjl.github.io/llamabot/tutorials/simplebot

A full example demonstrating the initialization and interaction with the SimpleBot class.

```python
from llamabot.bot.simplebot import SimpleBot

# Initialize the SimpleBot
system_prompt = "You are an AI assistant that helps users with their questions."
bot = SimpleBot(system_prompt)

# Interact with the SimpleBot
human_message = "What is the capital of France?"
response = bot(human_message)
print(response.content)
```

--------------------------------

### Install Pre-commit Globally

Source: https://ericmjl.github.io/llamabot/contributing/setup

Install the pre-commit tool globally on your system.

```bash
uv tool install pre-commit

```

--------------------------------

### LanceDBDocStore Usage Examples

Source: https://ericmjl.github.io/llamabot/reference/components/docstore

Examples demonstrating how to use the LanceDBDocStore.

```APIDOC
### Basic Usage
```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_documents")

# Add documents
docstore.append("Document 1 text")
docstore.extend(["Document 2 text", "Document 3 text"])

# Retrieve documents
results = docstore.retrieve("search query", n_results=5)
```
```

```APIDOC
### With Custom Embeddings
```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(
    table_name="my_documents",
    embedding_registry="sentence-transformers",
    embedding_model="all-MiniLM-L6-v2"
)
```
```

```APIDOC
### With Partitioning
```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(
    table_name="my_documents",
    enable_partitioning=True
)
```
```

--------------------------------

### Basic Multi-Step Workflow Example

Source: https://ericmjl.github.io/llamabot/reference/bots/agentbot

An example demonstrating how to set up and use AgentBot for a basic multi-step workflow involving web searching and user response.

```APIDOC
## Usage Examples
### Basic Multi-Step Workflow
```python
import llamabot as lmb

@lmb.tool
def get_weather(city: str) -> str:
    """Get the current weather for a city.

    :param city: The name of the city
    :return: Weather information
    """
    return f"The weather in {city} is sunny, 72°F"

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

agent = lmb.AgentBot(
    tools=[get_weather, respond_to_user],
    model_name="gpt-4o-mini"
)

result = agent("What's the weather in New York?")

```
```

--------------------------------

### Serve Documentation Locally

Source: https://ericmjl.github.io/llamabot/contributing/setup

Start a local MkDocs server to preview the documentation. The server typically runs at http://127.0.0.1:8000.

```bash
pixi run docs

```

--------------------------------

### Install LlamaBot (All Optional Dependencies)

Source: https://ericmjl.github.io/llamabot

Installs LlamaBot along with all optional dependencies for full functionality.

```bash
pip install "llamabot[all]"
```

--------------------------------

### Example: Basic QueryBot Usage

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Demonstrates how to set up a QueryBot with a LanceDBDocStore, add documents, and then query the bot for information.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_docs")
docstore.extend([doc1, doc2, doc3])

bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore
)

response = bot("What does the documentation say about authentication?")
print(response.content)


```

--------------------------------

### SimpleBot Example: Basic Usage

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Demonstrates basic usage of SimpleBot by initializing it with a system prompt and making a query.

```python
import llamabot as lmb

bot = lmb.SimpleBot(
    system_prompt="You are a helpful assistant.",
    model_name="gpt-4o-mini"
)

response = bot("What is machine learning?")
print(response.content)

```

--------------------------------

### Install Dependencies

Source: https://ericmjl.github.io/llamabot/tutorials/recording_prompts

Install pandas and panel libraries using pip. These are required for PromptRecorder functionality.

```bash
pip install pandas panel

```

--------------------------------

### Install LlamaBot (Minimum)

Source: https://ericmjl.github.io/llamabot

Installs the core LlamaBot package with essential dependencies.

```bash
pip install llamabot==0.17.11
```

--------------------------------

### Run Marimo Notebook for CLI Guide

Source: https://ericmjl.github.io/llamabot/how-to/cli-powered-by-llm

Command to open the Marimo notebook for this guide in a sandboxed environment.

```bash
uvx marimo edit --sandbox --mcp --no-token --watch https://github.com/ericmjl/llamabot/blob/main/docs/how-to/cli-powered-by-llm.py

```

--------------------------------

### Create AIMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate an AIMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import AIMessage

msg = AIMessage(content="Python is a programming language.")
```

--------------------------------

### ToolBot Example: Tool Calls

Source: https://ericmjl.github.io/llamabot/reference/bots/toolbot

Example of initializing ToolBot and making a tool call to analyze sales data.

```python
import llamabot as lmb
from llamabot.components.tools import write_and_execute_code

bot = lmb.ToolBot(
    system_prompt="You are a data analyst.",
    model_name="gpt-4o-mini",
    tools=[write_and_execute_code(globals_dict=globals())]
)

tool_calls = bot("Calculate the mean of the sales_data DataFrame")
# Returns list of tool calls to execute

```

--------------------------------

### ImageBot __call__ Example Usage

Source: https://ericmjl.github.io/llamabot/reference/bots/imagebot

Example demonstrating how to use the ImageBot's __call__ method to generate an image. It shows how to get a URL in a Jupyter notebook and save an image to a file in a script.

```python
import llamabot as lmb

bot = lmb.ImageBot()

# In a Jupyter notebook (returns URL)
url = bot("A painting of a sunset over mountains", return_url=True)

# In a Python script (saves to file)
image_path = bot("A painting of a sunset over mountains")
print(image_path)  # Path object

```

--------------------------------

### Design System Prompt for ToolBot

Source: https://ericmjl.github.io/llamabot/tutorials/toolbot

Shows an example of a system prompt that clearly defines the available tools for ToolBot, guiding the AI assistant to select and use the most appropriate tool for a given request.

```python
system_prompt = """
You are a data analysis assistant with access to the following tools:
- write_and_execute_code: Execute Python code with access to global variables
- calculate_fibonacci: Calculate Fibonacci numbers
- analyze_dataframe: Analyze pandas DataFrames

Use the most appropriate tool for each request.
"""
```

--------------------------------

### Install Dependencies with Pixi

Source: https://ericmjl.github.io/llamabot/contributing/setup

Install all project dependencies using pixi. This command sets up a dedicated environment with core, optional, and development dependencies.

```bash
pixi install

```

--------------------------------

### Using `--from-scratch` Flag

Source: https://ericmjl.github.io/llamabot/cli/docs

Use the `--from-scratch` flag to completely regenerate documentation, ignoring any existing content in the Markdown file. This is useful for a fresh start.

```bash
llamabot docs write <path_to_markdown_file> --from-scratch

```

--------------------------------

### Install Markdownlint Globally

Source: https://ericmjl.github.io/llamabot/contributing/setup

Install the markdownlint tool globally for linting markdown files.

```bash
pixi global install markdownlint

```

--------------------------------

### Install LlamaBot

Source: https://ericmjl.github.io/llamabot/cli/notebook

Install the llamabot package using pip. This is a prerequisite for using the notebook CLI.

```bash
pip install llamabot

```

--------------------------------

### Create SystemMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate a SystemMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import SystemMessage

msg = SystemMessage(content="You are a helpful assistant.")
```

--------------------------------

### Install Pre-commit Hooks

Source: https://ericmjl.github.io/llamabot/contributing/setup

Install the project's pre-commit hooks to automate code quality checks before commits.

```bash
pre-commit install

```

--------------------------------

### Example: Basic Document Q&A

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Sets up a QueryBot to answer questions based on Markdown documents found in a specified directory. It reads the documents, adds them to a LanceDBDocStore, and then queries the bot.

```python
import llamabot as lmb
from pathlib import Path

# Create a document store
docstore = lmb.LanceDBDocStore(table_name="my_documents")

# Add documents
docs_paths = Path("docs").rglob("*.md")
docs_texts = [p.read_text() for p in docs_paths]
docstore.extend(docs_texts)

# Create QueryBot
bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore
)

# Query the documents
response = bot("What is the main topic of these documents?")


```

--------------------------------

### Define a Tool with Docstrings and Examples

Source: https://ericmjl.github.io/llamabot/tutorials/toolbot

Illustrates how to define a custom tool using the `@lmb.tool` decorator, including comprehensive docstrings for parameters, return values, and usage examples. This is crucial for ToolBot's understanding and utilization of the tool.

```python
@lmb.tool
def my_tool(param1: str, param2: int) -> str:
    """Clear description of what the tool does.

    Detailed explanation of when and how to use this tool.
    Include examples and edge cases.

    Parameters
    ----------
    param1 : str
        Description of the first parameter
    param2 : int
        Description of the second parameter

    Returns
    -------
    str
        Description of what the tool returns

    Examples
    --------
    >>> my_tool("example", 42)
    "expected output"
    """
    # Tool implementation
    pass
```

--------------------------------

### ToolBot Example: Basic Tool Execution

Source: https://ericmjl.github.io/llamabot/reference/bots/toolbot

Demonstrates basic tool execution by calculating '2 + 2' using the ToolBot.

```python
import llamabot as lmb
from llamabot.components.tools import write_and_execute_code

bot = lmb.ToolBot(
    system_prompt="You are a helpful assistant that can execute Python code.",
    model_name="gpt-4o-mini",
    tools=[write_and_execute_code(globals_dict=globals())]
)

tool_calls = bot("Calculate 2 + 2")

```

--------------------------------

### Complete Markdown Source File Example

Source: https://ericmjl.github.io/llamabot/cli/docs

An example of a Markdown file with the necessary frontmatter and initial content structure. The LLM will generate content in the placeholder area.

```markdown
---
intents:
- Provide an overview of the `llamabot docs write` command.
- Explain the `--from-scratch` flag.
- Describe the frontmatter key-value pairs needed to make it work.
linked_files:
- llamabot/cli/docs.py
- pyproject.toml
---

# CLI Documentation for `llamabot docs write`

<The documentation content will be generated here.>

```

--------------------------------

### Create ToolMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate a ToolMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import ToolMessage

msg = ToolMessage(content="Tool execution result")
```

--------------------------------

### Create DeveloperMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate a DeveloperMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import DeveloperMessage

msg = DeveloperMessage(content="Add error handling to this function.")
```

--------------------------------

### SimpleBot Example: With Chat Memory

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Initializes SimpleBot with linear chat memory for fast, no-LLM-call history retention.

```python
import llamabot as lmb

# Linear memory (fast, no LLM calls)
memory = lmb.ChatMemory()

```

--------------------------------

### Run Ollama with a Model

Source: https://ericmjl.github.io/llamabot/tutorials/ollama

Use this command to start the Ollama server and load a specific model. Ensure you have adequate RAM for the model.

```bash
ollama run <model_name>
```

```bash
ollama run vicuna
```

--------------------------------

### Initialize QueryBot

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Initializes the QueryBot with a system prompt and a document store. The system prompt guides the bot's behavior, and the document store provides the knowledge base.

```python
class QueryBot(SimpleBot):
    """Initialize QueryBot.

    QueryBot is a bot that can answer questions based on a set of documents.
    It uses a document store to retrieve relevant documents for a given query.
    """


```

--------------------------------

### ToolBot Example: Using Global Variables

Source: https://ericmjl.github.io/llamabot/reference/bots/toolbot

Illustrates how to use ToolBot with global variables, often in conjunction with code execution tools.

```python
import pandas as pd
import numpy as np
import llamabot as lmb
from llamabot.components.tools import write_and_execute_code

```

--------------------------------

### Create RetrievedMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate a RetrievedMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import RetrievedMessage

msg = RetrievedMessage(content="Retrieved document content")
```

--------------------------------

### Run CLI Command

Source: https://ericmjl.github.io/llamabot/contributing/setup

Verify the command-line interface is installed and working correctly by running a basic command.

```bash
pixi run llamabot-cli

```

--------------------------------

### Create HumanMessage Instance

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Example of how to instantiate a HumanMessage with specific content. Ensure the 'content' attribute is provided.

```python
from llamabot.components.messages import HumanMessage

msg = HumanMessage(content="What is Python?")
```

--------------------------------

### Basic multi-step workflow with AgentBot

Source: https://ericmjl.github.io/llamabot/reference/bots/agentbot

Demonstrates a basic multi-step workflow using AgentBot. It includes a tool to get weather information and a terminal tool to respond to the user.

```python
import llamabot as lmb

@lmb.tool
def get_weather(city: str) -> str:
    """Get the current weather for a city.

    :param city: The name of the city
    :return: Weather information
    """
    return f"The weather in {city} is sunny, 72°F"

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

agent = lmb.AgentBot(
    tools=[get_weather, respond_to_user],
    model_name="gpt-4o-mini"
)

result = agent("What's the weather in New York?")
```

--------------------------------

### ToolBot Example: Custom Tool

Source: https://ericmjl.github.io/llamabot/reference/bots/toolbot

Shows how to use a custom tool, `calculate_fibonacci`, with ToolBot for mathematical calculations.

```python
import llamabot as lmb

@lmb.tool
def calculate_fibonacci(n: int) -> int:
    """Calculate the nth Fibonacci number.

    :param n: The position in the Fibonacci sequence
    :return: The nth Fibonacci number
    """
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b

bot = lmb.ToolBot(
    system_prompt="You are a mathematical assistant.",
    model_name="gpt-4o-mini",
    tools=[calculate_fibonacci]
)

tool_calls = bot("Calculate the 10th Fibonacci number")

```

--------------------------------

### Real-World Data Analysis Workflow with ToolBot

Source: https://ericmjl.github.io/llamabot/tutorials/toolbot

A comprehensive example demonstrating a data analysis workflow using ToolBot. It includes creating sample customer data with pandas, initializing ToolBot with a specific system prompt and the `write_and_execute_code` tool, and setting up the bot to analyze the data.

```python
import llamabot as lmb
import pandas as pd
import numpy as np
from llamabot.bots import ToolBot
from llamabot.components.tools import write_and_execute_code

# Create sample data
customer_data = pd.DataFrame({
    'customer_id': range(1, 101),
    'age': np.random.randint(18, 80, 100),
    'income': np.random.randint(20000, 150000, 100),
    'purchase_amount': np.random.randint(10, 1000, 100),
    'region': np.random.choice(['North', 'South', 'East', 'West'], 100)
})

# Create a ToolBot for data analysis
bot = ToolBot(
    system_prompt="""
    You are a data analyst assistant. You have access to customer_data DataFrame
    and can execute Python code to perform analysis. Focus on providing insights
    about customer demographics, purchasing patterns, and regional differences.
    """,
    model_name="gpt-4.1",
    tools=[write_and_execute_code(globals_dict=globals())],
)
```

--------------------------------

### AgentBot with Custom System Prompt

Source: https://ericmjl.github.io/llamabot/reference/bots/agentbot

Initialize AgentBot with a custom system prompt to guide its behavior as a specialized expert. Ensure the model name is specified.

```python
import llamabot as lmb

@lmb.tool
def analyze_data(data: str) -> str:
    """Analyze data."""
    return "Analysis complete"

agent = lmb.AgentBot(
    tools=[analyze_data],
    system_prompt="You are a data analysis expert.",
    model_name="gpt-4o-mini"
)

```

--------------------------------

### Configure ImageBot with Custom Parameters

Source: https://ericmjl.github.io/llamabot/reference/bots/imagebot

Initialize ImageBot with specific DALL-E model, size, and quality settings. This example uses DALL-E 3 with HD quality and a 1792x1024 resolution.

```python
import llamabot as lmb

bot = lmb.ImageBot(
    model="dall-e-3",
    size="1792x1024",
    quality="hd"
)

image_path = bot("A detailed landscape painting")
```

--------------------------------

### Serve Panel App via Terminal

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/simplebot-and-chatbot

Command to run the Panel application from the terminal. This command starts a local web server to host the chat interface.

```bash
panel serve chat_interface.py
```

--------------------------------

### Example: QueryBot with Threaded Memory

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Sets up QueryBot with threaded chat memory, which uses intelligent threading for better context management in conversations. This can improve the quality of contextual recall.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_docs")
docstore.extend(documents)

# Use intelligent threading for better context
memory = lmb.ChatMemory.threaded(model="gpt-4o-mini")

bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore,
    memory=memory
)


```

--------------------------------

### LanceDBDocStore Initialization with Partitioning Enabled

Source: https://ericmjl.github.io/llamabot/reference/components/docstore

Demonstrates enabling document partitioning in LanceDBDocStore for organizing documents into logical groups.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(
    table_name="my_documents",
    enable_partitioning=True
)


```

--------------------------------

### Chat Memory Initialization and Usage

Source: https://ericmjl.github.io/llamabot/design/unified_chat_memory

Demonstrates how to initialize different types of chat memory and integrate them with various bot types. Includes examples for linear, graph (threaded), and custom memory configurations.

```APIDOC
## Chat Memory Initialization and Usage

### Description
This section shows how to create and use different memory types with Llamabot bots.

### Code Examples

#### Linear Memory for Simple Conversations
```python
import llamabot as lmb

# Linear memory for simple conversations (fast)
linear_memory = lmb.ChatMemory()  # Default linear
simple_bot = lmb.SimpleBot(
    system_prompt="You are a helpful assistant.",
    memory=linear_memory
)
```

#### Graph Memory for Complex Conversations with Threading
```python
import llamabot as lmb

# Graph memory for complex conversations with threading (smart)
graph_memory = lmb.ChatMemory.threaded(model="gpt-4o-mini")
query_bot = lmb.QueryBot(
    system_prompt="You are a helpful assistant.",
    memory=graph_memory
)
```

#### Custom Memory for Specific Needs
```python
import llamabot as lmb

# Custom memory for specific needs (advanced)
custom_memory = lmb.ChatMemory(
    node_selector=lmb.LLMNodeSelector(model="gpt-4o-mini"),
    summarizer=None  # No summarization for performance
)
# Assuming StructuredBot is defined elsewhere
# structured_bot = StructuredBot(
#     system_prompt="You are a helpful assistant.",
#     pydantic_model=SomeModel,
#     memory=custom_memory
# )
```
```

--------------------------------

### Define an assistant prompt with @prompt

Source: https://ericmjl.github.io/llamabot/tutorials/prompts

Use `role="assistant"` to define prompts that represent assistant responses or few-shot examples. This is useful for guiding the AI's output format or providing examples of desired behavior.

```python
@prompt(role="assistant")
def example_response(task, solution):
    """For the task "{{ task }}", here's how I approach it:

    {{ solution }}

    This demonstrates the structured thinking process."""

```

--------------------------------

### Example: QueryBot with Chat Memory

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Configures QueryBot to use chat memory, allowing it to maintain context across multiple turns of conversation. This is useful for follow-up questions.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_docs")
docstore.extend(documents)

# Create chat memory for conversation context
memory = lmb.ChatMemory()

bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore,
    memory=memory
)

# Bot remembers previous questions
response1 = bot("What is authentication?")
response2 = bot("How does it work?")  # Bot remembers context


```

--------------------------------

### Design Tools for Specific Use Cases

Source: https://ericmjl.github.io/llamabot/tutorials/agentbot

Create focused, single-purpose tools to improve AgentBot's ability to handle specific tasks effectively. This example shows separate tools for getting and updating user profiles.

```python
def get_user_profile(user_id: str) -> dict:
    """Get user profile information.

    :param user_id: The user's unique identifier
    :return: User profile dictionary
    """
    # Implementation
    pass

def update_user_profile(user_id: str, updates: dict) -> dict:
    """Update user profile information.

    :param user_id: The user's unique identifier
    :param updates: Dictionary of fields to update
    :return: Updated user profile
    """
    # Implementation
    pass
```

--------------------------------

### Build Documentation

Source: https://ericmjl.github.io/llamabot/contributing/setup

Generate the static documentation files for the project.

```bash
pixi run build-docs

```

--------------------------------

### Initialize SimpleBot for Streaming to Panel

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Configures a SimpleBot to stream responses directly to a 'panel' target, useful for real-time display of bot output. Requires the 'panel' library to be installed.

```python
import llamabot as lmb

bot = lmb.SimpleBot(
    system_prompt="You are a helpful assistant.",
    stream_target="panel",
    model_name="gpt-4o-mini"
)

response = bot("Tell me a long story.")
```

--------------------------------

### Rendered output of a prompt

Source: https://ericmjl.github.io/llamabot/tutorials/prompts

This example shows the expected output after calling a decorated prompt function with specific arguments. It illustrates how the Jinja2 template is rendered into a complete prompt string.

```python
message = explain_concept("machine learning", "high school students")
print(message.content)
# Output:
# "Please explain machine learning to high school students in simple terms.
#
# Use examples and analogies that high school students would understand.
# Break down complex ideas into digestible pieces."

```

--------------------------------

### Initialize QueryBot with a New Docstore

Source: https://ericmjl.github.io/llamabot

Set up a QueryBot by first creating and populating a LanceDBDocStore with your documents. This is for querying a collection of documents.

```python
import llamabot as lmb
from pathlib import Path

# First, create a docstore and add your documents
docstore = lmb.LanceDBDocStore(table_name="eric_ma_blog")
docstore.add_documents([
    Path("/path/to/blog/post1.txt"),
    Path("/path/to/blog/post2.txt"),
    # ... more documents
])

# Then, create a QueryBot with the docstore
bot = lmb.QueryBot(
  system_prompt="You are an expert on Eric Ma's blog.",
  docstore=docstore,
  # Optional:
  # model_name="gpt-4.1-mini"
  # or
  # model_name="ollama_chat/mistral"
)

result = bot("Do you have any advice for me on career development?")
```

--------------------------------

### Initialize Panel Extension

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/simplebot-and-chatbot

Prepare your environment for Panel by initializing its extension. This must be called before using Panel components.

```python
pn.extension()
```

--------------------------------

### Initialize SimpleBot

Source: https://ericmjl.github.io/llamabot/tutorials/simplebot

Create an instance of SimpleBot with a system prompt. Optionally configure temperature and model name.

```python
system_prompt = "You are an AI assistant that helps users with their questions."
bot = SimpleBot(system_prompt)
```

--------------------------------

### Basic LanceDBDocStore Usage

Source: https://ericmjl.github.io/llamabot/reference/components/docstore

Demonstrates initializing LanceDBDocStore, adding documents using append and extend, and retrieving documents.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_documents")

# Add documents
docstore.append("Document 1 text")
docstore.extend(["Document 2 text", "Document 3 text"])

# Retrieve documents
results = docstore.retrieve("search query", n_results=5)


```

--------------------------------

### Install Llamabot CLI

Source: https://ericmjl.github.io/llamabot/cli/repo

Install Llamabot CLI using pip. This command ensures you have the latest version.

```bash
pip install -U llamabot

```

--------------------------------

### Initialize LanceDBDocStore and Use with QueryBot

Source: https://ericmjl.github.io/llamabot/reference/components/docstore

Demonstrates initializing a LanceDBDocStore, adding documents from markdown files, and integrating it with QueryBot for RAG. LanceDBDocStore supports semantic search and persistence.

```python
import llamabot as lmb
from pathlib import Path

docstore = lmb.LanceDBDocStore(table_name="my_docs")

docs_paths = Path("docs").rglob("*.md")
docs_texts = [p.read_text() for p in docs_paths]
docstore.extend(docs_texts)

bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore
)

response = bot("What is the main topic?")
```

--------------------------------

### Verify Editable Package Installation

Source: https://ericmjl.github.io/llamabot/contributing/setup

Check that the LlamaBot package is installed in editable mode within the pixi environment.

```bash
pixi run python -c "import llamabot; print(llamabot.__file__)"

```

--------------------------------

### Initialize QueryBot and Panel Chat Interface

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/querybot

Sets up the Panel chat interface, file input, and loading spinner. Initializes the QueryBot with a persona and document paths from an uploaded PDF.

```python
from llamabot import QueryBot
import tempfile
import panel as pn
from pathlib import Path

pn.extension()

file_input = pn.widgets.FileInput(mime_type=["application/pdf"])
spinner = pn.indicators.LoadingSpinner(value=False, width=30, height=30)
global bot
bot = None


def upload_file(event):
    spinner.value = True
    raw_contents = event.new

    with tempfile.NamedTemporaryFile(
        delete=False, suffix=".pdf", mode="wb"
    ) as temp_file:
        temp_file.write(raw_contents)
        global bot
        bot = QueryBot("You are Richard Feynman", doc_paths=[Path(temp_file.name)])

    chat_interface.send(
        "Please allow me to summarize the paper for you. One moment...",
        user="System",
        respond=False,
    )
    response = bot("Please summarize this paper for me.")
    chat_interface.send(response.content, user="System", respond=False)
    spinner.value = False


file_input.param.watch(upload_file, "value")


async def callback(contents: str, user: str, instance: pn.chat.ChatInterface):
    spinner.value = True
    global bot
    response = bot(contents)
    spinner.value = False
    yield response.content


chat_interface = pn.chat.ChatInterface(
    callback=callback,
    callback_user="QueryBot",
    show_clear=False,
)
chat_interface.send(
    "Send a message to get a reply from the bot!",
    user="System",
    respond=False,
)

app = pn.Column(pn.Row(file_input, spinner), chat_interface)
app.show()
```

--------------------------------

### Initialize QueryBot with a System Prompt

Source: https://ericmjl.github.io/llamabot/tutorials/querybot

Initialize a QueryBot instance with a specific system prompt and a pre-configured docstore. This sets the behavior for the assistant.

```python
tutorial_bot = QueryBot(
    system_prompt="You are a Python tutorial assistant.",
    docstore=docstore,  # Same docstore, but filter in your queries
)
```

--------------------------------

### Install Commit Message Hook

Source: https://ericmjl.github.io/llamabot/cli/git

Installs a Git hook to automatically generate commit messages using LlamaBot.

```bash
llamabot git hooks

```

--------------------------------

### Install Llamabot Python CLI

Source: https://ericmjl.github.io/llamabot/cli/python

Install the Llamabot Python CLI using pip. Ensure you are using the latest version with -U.

```bash
pip install -U llamabot
```

--------------------------------

### Initialize SimpleBot with Custom Models

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Shows how to initialize a SimpleBot using different custom models, including local Ollama models and cloud-based models like Anthropic Claude.

```python
import llamabot as lmb

# Using Ollama local model
bot = lmb.SimpleBot(
    system_prompt="You are a helpful assistant.",
    model_name="ollama_chat/llama2:13b"
)
```

```python
import llamabot as lmb

# Using Anthropic Claude
bot = lmb.SimpleBot(
    system_prompt="You are a helpful assistant.",
    model_name="anthropic/claude-3-5-sonnet"
)
```

--------------------------------

### Initialize QueryBot

Source: https://ericmjl.github.io/llamabot/tutorials/recording_prompts

Create an instance of QueryBot with a system message, model name, and document paths. This sets up the chatbot's behavior and knowledge base.

```python
system_message = "You are a helpful assistant that can answer questions based on the provided documents."
model_name = "gpt-4"
doc_paths = ["document1.txt", "document2.txt"]

query_bot = QueryBot(system_message, model_name=model_name, document_paths=doc_paths)

```

--------------------------------

### SimpleBot Example: Using Message Objects

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Demonstrates sending a HumanMessage object to the bot.

```python
# Using message objects
from llamabot.components.messages import HumanMessage
response = bot(HumanMessage(content="Hello!"))

```

--------------------------------

### Get All Spans with get_spans

Source: https://ericmjl.github.io/llamabot/design/observability

Retrieve all recorded spans. This is useful for a general overview of bot operations.

```python
from llamabot import get_spans

# Get all spans
all_spans = get_spans()
```

--------------------------------

### Build MCP Documentation

Source: https://ericmjl.github.io/llamabot/contributing/setup

Build the MCP documentation database.

```bash
pixi run build-mcp-docs

```

--------------------------------

### Old ChatMemory API Example

Source: https://ericmjl.github.io/llamabot/design/unified_chat_memory

Demonstrates the usage of the deprecated ChatMemory API for adding and retrieving messages.

```python
from llamabot.components.chat_memory import ChatMemory

memory = ChatMemory()
memory.add_message("user", "Hello")
messages = memory.get_messages()

```

--------------------------------

### Set Up Panel Chat Interface

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/querybot

Initializes the Panel ChatInterface with a callback function and a default system message.

```python
chat_interface = pn.chat.ChatInterface(
    callback=callback,
    callback_user="QueryBot",
    show_clear=False,
)
chat_interface.send(
    "Send a message to get a reply from the bot!",
    user="System",
    respond=False,
)
```

--------------------------------

### Run Full Test Suite

Source: https://ericmjl.github.io/llamabot/contributing/setup

Execute the entire test suite for the project.

```bash
pixi run test

```

--------------------------------

### Initialize BM25DocStore

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Instantiate a keyword-based document store using BM25. Use this for simpler document retrieval based on keyword matching. Documents can be extended to this store.

```python
import llamabot as lmb

docstore = lmb.BM25DocStore()
docstore.extend(documents)
```

--------------------------------

### SimpleBot Example: Multiple Messages

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Illustrates sending multiple string messages to the bot for a follow-up conversation.

```python
# Multiple messages
response = bot("What is Python?", "Tell me more about it.")

```

--------------------------------

### Explain a Jupyter Notebook (No Overwrite)

Source: https://ericmjl.github.io/llamabot/cli/notebook

This command explains a notebook without overwriting the original file. A new file with the '_explained' suffix will be created in the same directory.

```bash
llamabot notebook explain /path/to/notebook.ipynb

```

--------------------------------

### Initialize QueryBot with DocStore and Chat Memory

Source: https://ericmjl.github.io/llamabot/tutorials/querybot

Use this pattern to create a QueryBot with explicit document store and chat memory management. Ensure LanceDBDocStore and ChatMemory are properly configured. The loop continues until 'exit' or 'quit' is entered.

```python
from llamabot.components.docstore import LanceDBDocStore
from llamabot import QueryBot
from pyprojroot import here

# Create a document store for your knowledge base
docstore = LanceDBDocStore(
    table_name="my-documents",
    # Optional: Configure embedding model settings
    embedding_registry="sentence-transformers",  # Default registry
    embedding_model="minishlab/potion-base-8M",  # Default model
)

docstore.reset()  # Optionally clear all documents

# Add documents (e.g., all Markdown files in the docs folder)
docs_paths = (here() / "docs").rglob("*.md")
docs_texts = [p.read_text() for p in docs_paths]
docstore.extend(docs_texts)

# Create a separate store for chat memory
# For simple linear memory (fast, no LLM calls)
chat_memory = lmb.ChatMemory()

# For intelligent threading (uses LLM for smart connections)
# chat_memory = lmb.ChatMemory.threaded(model="gpt-4o-mini")

chat_memory.reset()  # Optionally clear previous chat history

# Define a system prompt (optionally using the @prompt decorator)
system_prompt = "You are a helpful assistant for my project."

# Initialize QueryBot with both docstore and chat memory
bot = QueryBot(
    system_prompt=system_prompt,
    docstore=docstore,
    memory=chat_memory,
)

# Use the bot in a conversational loop
while True:
    user_input = input("Ask a question: ")
    if user_input.lower() in {"exit", "quit"}:
        break
    response = bot(user_input)
    print(response.content)

```

--------------------------------

### Initialize QueryBot with an Existing Docstore

Source: https://ericmjl.github.io/llamabot

Create a QueryBot using a pre-existing LanceDBDocStore. This allows querying a collection of documents that have already been indexed.

```python
import llamabot as lmb

# Load an existing docstore
docstore = lmb.LanceDBDocStore(table_name="eric_ma_blog")

# Create QueryBot with the existing docstore
bot = lmb.QueryBot(
  system_prompt="You are an expert on Eric Ma's blog",
  docstore=docstore,
  # Optional:
  # model_name="gpt-4.1-mini"
  # or
  # model_name="ollama_chat/mistral"
)

result = bot("Do you have any advice for me on career development?")
```

--------------------------------

### New ChatMemory API Example

Source: https://ericmjl.github.io/llamabot/design/unified_chat_memory

Illustrates the new ChatMemory API for appending and retrieving messages, replacing older methods.

```python
from llamabot.components.chat_memory import ChatMemory

memory = ChatMemory()
memory.append("user", "Hello")
messages = memory.retrieve()

```

--------------------------------

### Basic Usage of `llamabot docs write`

Source: https://ericmjl.github.io/llamabot/cli/docs

Run this command to generate or update documentation for a specified Markdown file. Replace `<path_to_markdown_file>` with the actual file path.

```bash
llamabot docs write <path_to_markdown_file>

```

--------------------------------

### SimpleBot Example: Single String Message

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Shows how to send a single string message to the bot and print its response content.

```python
import llamabot as lmb

bot = lmb.SimpleBot("You are a helpful assistant.")

# Single string message
response = bot("Hello!")
print(response.content)

```

--------------------------------

### Set Up Widgets and Global Variables for Chat Interface

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/querybot

Configures a file input widget for PDF uploads, a loading spinner, and initializes a global variable for the QueryBot instance.

```python
file_input = pn.widgets.FileInput(mime_type=["application/pdf"])
spinner = pn.indicators.LoadingSpinner(value=False, width=30, height=30)
global bot
bot = None
```

--------------------------------

### Memory Reset and State Management

Source: https://ericmjl.github.io/llamabot/design/unified_chat_memory

Illustrates how to reset the chat memory to clear conversation history and start a new conversation.

```APIDOC
## Memory Reset and State Management

### Description
This section demonstrates how to reset the chat memory to clear conversation history and start a new conversation.

### Code Example
```python
from llamabot.bot.simplebot import SimpleBot
from llamabot.components.chat_memory import ChatMemory

# Create bot with memory
memory = ChatMemory()  # Default linear
bot = SimpleBot(
    system_prompt="You are a helpful assistant.",
    model_name="gpt-4o-mini",
    memory=memory
)

# Have a conversation
bot("Hello!")
bot("How are you?")

# Reset memory for new conversation
memory.reset()

# Bot no longer remembers previous conversation
response = bot("What did we just talk about?")  # Bot won't remember
```
```

--------------------------------

### Reset LanceDBDocStore Contents

Source: https://ericmjl.github.io/llamabot/tutorials/querybot

Use the `.reset()` method on a LanceDBDocStore instance to clear all its contents. This is useful for starting with a clean slate.

```python
docstore.reset()
```

--------------------------------

### Create Various Message Types

Source: https://ericmjl.github.io/llamabot/reference/components/messages

Demonstrates creating SystemMessage, HumanMessage, and AIMessage using helper functions and direct instantiation. Also shows the `user` and `system` helper functions.

```python
from llamabot.components.messages import (
    SystemMessage,
    HumanMessage,
    AIMessage,
    user,
    dev,
    system
)

# System prompt
sys_msg = system("You are a helpful assistant.")

# User message
user_msg = user("What is Python?")

# AI response
ai_msg = AIMessage(content="Python is a programming language.")

```

--------------------------------

### SimpleBot Constructor Parameters

Source: https://ericmjl.github.io/llamabot/reference/bots/simplebot

Initializes SimpleBot with a system prompt and optional parameters for temperature, memory, model name, streaming target, JSON mode, API key, and mock response.

```python
def __init__(
    self,
    system_prompt: str,
    temperature: float = 0.0,
    memory: Optional[AbstractDocumentStore] = None,
    model_name: str = default_language_model(),
    stream_target: str = "stdout",
    json_mode: bool = False,
    api_key: Optional[str] = None,
    mock_response: Optional[str] = None,
    **completion_kwargs,
)

```

--------------------------------

### Call SimpleBot with Text Input

Source: https://ericmjl.github.io/llamabot

Invoke the SimpleBot instance with a string of text to get a rephrased response based on the system prompt.

```python
prompt = """
Enzyme function annotation is a fundamental challenge, and numerous computational tools have been developed.
However, most of these tools cannot accurately predict functional annotations,
such as enzyme commission (EC) number,
for less-studied proteins or those with previously uncharacterized functions or multiple activities.
We present a machine learning algorithm named CLEAN (contrastive learning–enabled enzyme annotation)
to assign EC numbers to enzymes with better accuracy, reliability,
and sensitivity compared with the state-of-the-art tool BLASTp.
The contrastive learning framework empowers CLEAN to confidently (i) annotate understudied enzymes,
(ii) correct mislabeled enzymes, and (iii) identify promiscuous enzymes with two or more EC numbers—functions
that we demonstrate by systematic in silico and in vitro experiments.
We anticipate that this tool will be widely used for predicting the functions of uncharacterized enzymes,
thereby advancing many fields, such as genomics, synthetic biology, and biocatalysis.
"""
feynman(prompt)
```

--------------------------------

### AgentBot with Multiple Tools

Source: https://ericmjl.github.io/llamabot/reference/components/tools

Illustrates setting up an `AgentBot` with multiple tools, including a web search tool and a response tool. The agent orchestrates these tools to fulfill complex requests.

```python
import llamabot as lmb

@lmb.tool
def search_web(query: str) -> str:
    """Search the web."""
    return results

@lmb.tool(loopback_name=None)
def respond_to_user(response: str) -> str:
    """Respond to user."""
    return response

bot = lmb.AgentBot(
    tools=[search_web, respond_to_user],
    model_name="gpt-4o-mini"
)

result = bot("Search for AI news and summarize")


```

--------------------------------

### Generate Banner Image URL

Source: https://ericmjl.github.io/llamabot/how-to/generate-blog-banner-images

Generate a banner image from a DALL-E prompt and get its URL. Ensure the bannerbot function is imported and configured.

```python
banner_url = bannerbot(dalle_prompt.content, return_url=True)
banner_url
```

--------------------------------

### Import PromptRecorder and QueryBot

Source: https://ericmjl.github.io/llamabot/tutorials/recording_prompts

Import the necessary classes from their respective modules. PromptRecorder is used for logging, and QueryBot is the chatbot interface.

```python
from llamabot.recorder import PromptRecorder, autorecord
from llamabot.bot.querybot import QueryBot

```

--------------------------------

### BaseMessage Methods

Source: https://ericmjl.github.io/llamabot/reference/components/messages

The BaseMessage class provides several methods for interacting with message content, including getting its length, accessing slices, and concatenating strings.

```APIDOC
## BaseMessage Methods

### `__len__`
Get the length of the message content.

### `__getitem__`
Get a slice of the message content.

### `__add__` / `__radd__`
Concatenate strings with message content.
```

--------------------------------

### Send Initial System Message

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/simplebot-and-chatbot

Add a starting message to the chat interface from a 'System' user. respond=False prevents the bot from replying to this initial message.

```python
chat_interface.send(
    "Send a message to get a reply from the bot!",
    user="System",
    respond=False,
)
```

--------------------------------

### File Naming Convention for Conversations

Source: https://ericmjl.github.io/llamabot/design/unified_chat_memory

Example file naming convention for storing conversation session data. Files are organized in a 'conversations' directory with timestamps in their names.

```bash
conversations/
├── session_2024-01-15_10-30-00.json
├── session_2024-01-15_14-45-00.json
└── backup_2024-01-15_18-00-00.json


```

--------------------------------

### Run Marimo Notebook

Source: https://ericmjl.github.io/llamabot/how-to/generate-blog-banner-images

Command to open the Marimo notebook in a sandbox environment.

```bash
uvx marimo edit --sandbox --mcp --no-token --watch https://github.com/ericmjl/llamabot/blob/main/docs/how-to/generate-blog-banner-images.py

```

--------------------------------

### Integrating sse_stream with AsyncSimpleBot

Source: https://ericmjl.github.io/llamabot/reference/sse

This example shows the direct integration of `sse_stream` with `AsyncSimpleBot`. It highlights that `sse_stream` internally calls `bot.stream_async(*messages)` to generate the SSE events.

```python
from llamabot import AsyncSimpleBot
from llamabot.sse import sse_stream

bot = AsyncSimpleBot("You are helpful.", stream_target="none")

# sse_stream internally calls bot.stream_async(*messages)
async for event in sse_stream(bot, ["Hello!"]):
    print(event)
```

--------------------------------

### Launch LlamaBot Log Viewer

Source: https://ericmjl.github.io/llamabot/cli/log-viewer

Run this command in your terminal to start the local FastAPI server for the LlamaBot log viewer. Access it via your web browser at 0.0.0.0:8000.

```bash
llamabot log-viewer launch

```

--------------------------------

### Initialize BM25DocStore

Source: https://ericmjl.github.io/llamabot/reference/components/docstore

Initializes a BM25DocStore, which is a keyword-based document store using BM25 for full-text search. It requires no configuration parameters.

```python
import llamabot as lmb

docstore = lmb.BM25DocStore()
```

--------------------------------

### Define AgentBot with @tool decorated functions

Source: https://ericmjl.github.io/llamabot/reference/bots/agentbot

Instantiate AgentBot by providing a list of tools decorated with @tool. This setup is required for the bot to recognize and utilize your custom functions.

```python
from llamabot.components.tools import tool

@tool
def my_tool(arg: str) -> str:
    """Tool description."""
    return arg

bot = AgentBot(tools=[my_tool])
```

--------------------------------

### Example: QueryBot with Custom Number of Results

Source: https://ericmjl.github.io/llamabot/reference/bots/querybot

Shows how to specify a custom number of document results (`n_results`) to be used by the QueryBot when answering a query. This allows for more comprehensive or focused answers.

```python
import llamabot as lmb

docstore = lmb.LanceDBDocStore(table_name="my_docs")
docstore.extend(documents)

bot = lmb.QueryBot(
    system_prompt="You are an expert on these documents.",
    docstore=docstore
)

# Retrieve more documents for comprehensive answers
response = bot("Explain the architecture", n_results=50)


```

--------------------------------

### Serve the Panel Application

Source: https://ericmjl.github.io/llamabot/tutorials/chat-ui/querybot

Command to run the Panel application from the terminal.

```bash
panel serve chat_interface.py

```
Tokens:
Raw