Reposition README as Agent-Building Framework

[ericmjl]

Reposition LlamaBot as an Agent-Building Framework

Overview

Transform the README to position LlamaBot as a powerful, composable agent-building framework. The new structure will emphasize production-ready agents with multiple tool types (RAG retrieval, web browsing, secure code execution, custom functions) and demonstrate composability patterns.

Structure Overview

The new README will follow this structure:

1. Hero Section: Position LlamaBot as "The Pythonic Agent Framework" - emphasizing composability, simplicity, and production-readiness
2. Quick Value Proposition: 3-4 bullet points highlighting key differentiators
3. Installation: Keep existing but streamline
4. Core Agent Example: Show a complete AgentBot with multiple tool types in action
5. Tool Categories: Demonstrate the 4 main tool types with working examples
6. Building Custom Agents: Show composability patterns
7. Specialized Bots: Brief overview of QueryBot, ToolBot, StructuredBot, ImageBot
8. Advanced Concepts: Memory, experimentation, CLI tools
9. Contributing: Keep existing section

Key Changes from Current README

1. New Hero Section

Replace the current intro with:

# LlamaBot: The Pythonic Agent Framework

Build production-ready AI agents with composable tools, memory, and secure execution.
LlamaBot gives you the building blocks to create agents that can retrieve knowledge, 
browse the web, execute code safely, and call custom functions - all with a clean, 
Pythonic interface.

All models supported by [LiteLLM](https://github.com/BerriAI/litellm) work with LlamaBot.

2. Add Value Proposition Section

## Why LlamaBot?

- **Composable by Design**: Build agents from reusable components - docstores, tools, memory systems
- **Tool-First Architecture**: RAG retrieval, web browsing, secure code execution, and custom functions as first-class tools
- **Production-Ready**: Docker-based sandboxing, structured outputs, memory management, and observability built-in
- **Pythonic & Simple**: Clean APIs that feel natural to Python developers, not DSL-heavy frameworks

3. Complete Agent Example

Show a working AgentBot with all 4 tool types:

import llamabot as lmb
from llamabot.components.tools import (
    search_internet_and_summarize,
    write_and_execute_script,
)

# Create a docstore for RAG
docstore = lmb.LanceDBDocStore(table_name="my_knowledge")
docstore.extend([
    "Python is a high-level programming language...",
    "Machine learning is a subset of AI...",
])

# Create a tool that retrieves from the docstore
@lmb.tool
def search_knowledge(query: str) -> str:
    """Search the knowledge base for relevant information.
    
    :param query: The search query
    :return: Retrieved knowledge
    """
    results = docstore.retrieve(query, n_results=3)
    return "\n\n".join(results)

# Build an agent with multiple tool types
agent = lmb.AgentBot(
    system_prompt="You are a helpful research assistant.",
    model_name="gpt-4o",
    tools=[
        search_knowledge,              # RAG-based retrieval
        search_internet_and_summarize, # Web browsing
        write_and_execute_script,      # Secure code execution
        # Add your custom tools here
    ]
)

# Use the agent
result = agent("What is Python and can you find the latest news about it?")
print(result.content)

4. Tool Categories

Add complete examples for each of the 4 tool types:

1. RAG-Based Retrieval Tools
2. Web Browsing Tools
3. Secure Code Execution Tools
4. Custom Function Tools

5. Building Custom Agents (Composability)

import llamabot as lmb
from pathlib import Path

class ResearchAgent:
    """Custom research agent with memory and knowledge."""
    
    def __init__(self, knowledge_base_path: Path):
        # Set up RAG retrieval
        self.docstore = lmb.LanceDBDocStore(table_name="research")
        
        # Load documents
        for doc_path in knowledge_base_path.glob("*.txt"):
            with open(doc_path) as f:
                self.docstore.append(f.read())
        
        # Create retrieval tool
        @lmb.tool
        def search_papers(query: str) -> str:
            """Search research papers."""
            results = self.docstore.retrieve(query, n_results=5)
            return "\n\n".join(results)
        
        # Build agent with memory
        self.memory = lmb.ChatMemory()
        self.agent = lmb.AgentBot(
            system_prompt="You are a research assistant specializing in AI.",
            tools=[
                search_papers,
                search_internet_and_summarize,
            ],
            memory=self.memory
        )
    
    def ask(self, question: str):
        """Ask the research agent a question."""
        return self.agent(question)

# Use your custom agent
researcher = ResearchAgent(Path("./papers"))
answer = researcher.ask("What are transformers in machine learning?")

6. Restructure Specialized Bots

Position QueryBot, ToolBot, StructuredBot, ImageBot as "pre-built specialized bots for common patterns" with when-to-use guidance.

Implementation Notes

1. Ensure all code examples are complete and runnable
2. Import statements must be explicit
3. Use consistent model names (gpt-4o for examples requiring function calling)
4. Add type hints to custom tool examples
5. Keep existing badges and contributor section
6. Maintain the Asciinema demo links

Tasks

• Rewrite hero section to position LlamaBot as 'The Pythonic Agent Framework'
• Add value proposition section with 4 key differentiators
• Create comprehensive AgentBot example showing all 4 tool types (RAG, web, code, custom)
• Add detailed tool categories section with complete working examples for each type
• Add 'Building Custom Agents' section demonstrating composability pattern
• Restructure specialized bots section as 'pre-built patterns' with when-to-use guidance
• Add concise memory section before experimentation
• Run markdownlint on the updated README.md

Target Audience

Python developers building custom AI agents, with emphasis on:

• Complete working code examples
• Composability patterns
• Clear value propositions