ToyAIKit

https://pypi.org/project/toyaikit/
Admin
ToyAIKit is a minimalistic Python library for building AI assistants powered by Large Language...
Tokens:5,998
Snippets:50
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install ToyAIKit

Source: https://pypi.org/project/toyaikit

Install the ToyAIKit library using pip.

```bash
pip install toyaikit

```

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

### Django Coding Agent Tools and Setup

Source: https://pypi.org/project/toyaikit

This Python script defines the tools and setup for a Django coding agent. It includes methods for reading/writing files, executing bash commands (with a safeguard against 'runserver'), and a function to start a new Django project by copying a template. The agent is configured with a developer prompt and uses an OpenAI client for responses.

```python
import os
import shutil
import subprocess
from pathlib import Path

class AgentTools:
    def __init__(self, project_path: Path):
        self.project_path = project_path

    def read_file(self, file_path: str) -> str:
        """Read the contents of a file."""
        try:
            full_path = self.project_path / file_path
            with open(full_path, 'r', encoding='utf-8') as f:
                return f.read()
        except Exception as e:
            return f"Error reading file: {str(e)}"

    def write_file(self, file_path: str, content: str) -> str:
        """Write content to a file."""
        try:
            full_path = self.project_path / file_path
            full_path.parent.mkdir(parents=True, exist_ok=True)
            with open(full_path, 'w', encoding='utf-8') as f:
                f.write(content)
            return f"File {file_path} written successfully"
        except Exception as e:
            return f"Error writing file: {str(e)}"

    def execute_bash_command(self, command: str) -> str:
        """Execute a bash command in the project directory."""
        if "runserver" in command:
            return "runserver command blocked in agent mode"
        try:
            result = subprocess.run(
                command.split(), 
                cwd=self.project_path, 
                capture_output=True, 
                text=True, 
                timeout=30
            )
            return f"Exit code: {result.returncode}\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
        except Exception as e:
            return f"Error executing command: {str(e)}"

# Copy Django template
def start_project():
    project_name = input("Enter the new Django project name: ").strip()
    if not project_name:
        print("Project name cannot be empty.")
        return
    
    if os.path.exists(project_name):
        print(f"Directory '{project_name}' already exists.")
        return
    
    shutil.copytree('django_template', project_name)
    print(f"Django template copied to '{project_name}' directory.")
    return project_name

# Setup coding agent
project_name = start_project()
if project_name:
    project_path = Path(project_name)
    agent_tools = AgentTools(project_path)
    
    tools = Tools()
    tools.add_tools(agent_tools)
    
    developer_prompt = """
    You are a coding agent. Your task is to modify the provided Django project template
    according to user instructions. You don't tell the user what to do; you do it yourself 
    using the available tools.
    
    Always ensure changes are consistent with Django best practices and the project's structure.
    Use TailwindCSS for styling and make the results look beautiful.
    """
    
    runner = OpenAIResponsesRunner(
        tools=tools,
        developer_prompt=developer_prompt,
        chat_interface=IPythonChatInterface(),
        llm_client=OpenAIClient()
    )
    
    runner.run()

```

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

### Basic Usage with OpenAI

Source: https://pypi.org/project/toyaikit

Demonstrates basic usage of ToyAIKit with OpenAI for a weather assistant. Requires the OpenAI Python client and defines a simple tool for getting weather information.

```python
from openai import OpenAI

from toyaikit.llm import OpenAIClient
from toyaikit.tools import Tools
from toyaikit.chat import IPythonChatInterface
from toyaikit.chat.runners import OpenAIResponsesRunner

# Create tools
tools = Tools()

# Add a simple function as a tool
def get_weather(city: str):
    """Get weather information for a city."""
    return f"Weather in {city}: Sunny, 25°C"

tools.add_tool(get_weather)

# Create chat interface and client
chat_interface = IPythonChatInterface()
openai_client = OpenAIClient(
    model="gpt-4o-mini",
    client=OpenAI()
)

# Create and run chat assistant
runner = OpenAIResponsesRunner(
    tools=tools,
    developer_prompt="You are a helpful weather assistant.",
    chat_interface=chat_interface,
    llm_client=openai_client
)

runner.run()

```

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

### Initialize and Use IPython Chat Interface

Source: https://pypi.org/project/toyaikit

Set up and interact with the IPython-based chat interface for an AI assistant. This includes getting user input, displaying messages, AI responses, and function calls.

```Python
from toyaikit.chat import IPythonChatInterface

chat_interface = IPythonChatInterface()

# Get user input
user_input = chat_interface.input()

# Display message
chat_interface.display("Hello!")

# Display AI response
chat_interface.display_response("AI response")

# Display function call
chat_interface.display_function_call("function_name", '{"arg1": "value1"}', "result")
```

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

### PydanticAI Agent with OpenAI

Source: https://pypi.org/project/toyaikit

Set up a PydanticAI agent using OpenAI's GPT-4o-mini model. Ensure necessary tools are imported and available. This snippet demonstrates the initial setup for a coding agent.

```python
from pydantic_ai import Agent

from toyaikit.tools import get_instance_methods
from toyaikit.chat import IPythonChatInterface
from toyaikit.chat.runners import PydanticAIRunner

# Get tools from your object with functions
coding_agent_tools_list = get_instance_methods(agent_tools)

# Create Pydantic AI agent with OpenAI
coding_agent = Agent(
    'openai:gpt-4o-mini',
    instructions="You are a coding agent that can modify Django projects.",
    tools=coding_agent_tools_list
)

# Setup and run with ToyAIKit
chat_interface = IPythonChatInterface()
runner = PydanticAIRunner(
    chat_interface=chat_interface,
    agent=coding_agent
)

# Run asynchronously
await runner.run()

```

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

### OpenAI Chat Completions API Runner

Source: https://pypi.org/project/toyaikit

Uses the OpenAIChatCompletionsRunner for interacting with the chat.completions API. Requires OpenAI client and tools setup.

```python
from openai import OpenAI

from toyaikit.tools import Tools
from toyaikit.llm import OpenAIChatCompletionsClient
from toyaikit.chat.runners import OpenAIChatCompletionsRunner
from toyaikit.chat import IPythonChatInterface

# Setup tools and client
agent_tools = ... # class with some functions to be called

tools = Tools()
tools.add_tools(agent_tools)

chat_interface = IPythonChatInterface()

llm_client = OpenAIChatCompletionsClient(
    model="gpt-4o-mini",
    client=OpenAI()
)

# Create and run the chat completions runner
runner = OpenAIChatCompletionsRunner(
    tools=tools,
    developer_prompt="You are a coding agent that can modify Django projects.",
    chat_interface=chat_interface,
    llm_client=llm_client
)
runner.run()

```

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

### OpenAIResponsesRunner with Structured Output

Source: https://pypi.org/project/toyaikit

Use this snippet to get structured responses from OpenAI using Pydantic models with OpenAIResponsesRunner. Ensure you have defined your Pydantic model and initialized the OpenAIClient.

```python
from pydantic import BaseModel
from toyaikit.llm import OpenAIClient
from toyaikit.chat.runners import OpenAIResponsesRunner

# Define your response structure
class TestResponse(BaseModel):
    hello: bool
    world: str

# Create the runner
runner = OpenAIResponsesRunner(llm_client=OpenAIClient())

# Use structured output
result = runner.loop(prompt='how are you', output_format=TestResponse)
print(result.last_message)
# Output: TestResponse(hello=True, world="I'm doing well, thank you! How can I assist you today?")

# Or use without structured output for free-form text
result = runner.loop(prompt='how are you')
print(result.last_message)
# Output: "I'm just a program, but I'm here and ready to help you! How can I assist you today?"
```

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

### FAQ Search Agent Implementation

Source: https://pypi.org/project/toyaikit

This snippet demonstrates how to build a course teaching assistant that can search FAQ documents and add new entries. It includes setting up the search index, defining search tools, and running an agent with a developer prompt.

```python
import requests
from minsearch import AppendableIndex
from typing import List, Dict, Any

# Load FAQ data
docs_url = 'https://github.com/alexeygrigorev/llm-rag-workshop/raw/main/notebooks/documents.json'
docs_response = requests.get(docs_url)
documents_raw = docs_response.json()

# Prepare documents
documents = []
for course in documents_raw:
    course_name = course['course']
    for doc in course['documents']:
        doc['course'] = course_name
        documents.append(doc)

# Create search index
index = AppendableIndex(
    text_fields=["question", "text", "section"],
    keyword_fields=["course"]
)
index.fit(documents)

# Define search tools
class SearchTools:
    def __init__(self, index):
        self.index = index

    def search(self, query: str) -> List[Dict[str, Any]]:
        """
        Search the FAQ database for entries matching the given query.
        
        Args:
            query (str): Search query text to look up in the course FAQ. 
        
        Returns:
            List[Dict[str, Any]]: A list of search result entries.
        """
        boost = {'question': 3.0, 'section': 0.5}
        results = self.index.search(
            query=query,
            filter_dict={'course': 'data-engineering-zoomcamp'},
            boost_dict=boost,
            num_results=5,
        )
        return results

    def add_entry(self, question: str, answer: str) -> None:
        """
        Add a new entry to the FAQ database.
        
        Args:
            question (str): The question to be added to the FAQ database.
            answer (str): The corresponding answer to the question.
        """
        doc = {
            'question': question,
            'text': answer,
            'section': 'user added',
            'course': 'data-engineering-zoomcamp'
        }
        self.index.append(doc)

# Create and run FAQ agent
search_tools = SearchTools(index)

tools = Tools()
tools.add_tools(search_tools)

developer_prompt = """
You're a course teaching assistant. 
You're given a question from a course student and your task is to answer it.

If you want to look up the answer, explain why before making the call. Use as many 
keywords from the user question as possible when making first requests.

Make multiple searches. Try to expand your search by using new keywords based on the results you
get from the search.

At the end, make a clarifying question based on what you presented and ask if there are 
other areas that the user wants to explore.
"""

runner = OpenAIResponsesRunner(
    tools=tools,
    developer_prompt=developer_prompt,
    chat_interface=IPythonChatInterface(),
    llm_client=OpenAIClient()
)

runner.run()

```

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

### Run Tests

Source: https://pypi.org/project/toyaikit

Execute the test suite for the project. Ensure all tests pass before proceeding with other development tasks.

```shell
make test

```

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

### MCP Server Creation with FastMCP

Source: https://pypi.org/project/toyaikit

Creates an MCP server using FastMCP and adds tools to it. Supports STDIO and HTTP SSE transports.

```python
from fastmcp import FastMCP
from toyaikit.tools import wrap_instance_methods

# Create MCP server
mcp = FastMCP("FAQ Server")

# Add tools to server
search_tools = SearchTools(index)
wrap_instance_methods(mcp.tool, search_tools)

# Run server
if __name__ == "__main__":
    mcp.run()  # STDIO transport
    # or
    mcp.run(transport="sse")  # HTTP SSE transport

```

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

### Build Package

Source: https://pypi.org/project/toyaikit

Build the distributable package for the ToyAIKit project. This command generates the necessary files for distribution.

```shell
uv run hatch build

```

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

### OpenAIChatCompletionsRunner with Structured Output

Source: https://pypi.org/project/toyaikit

This snippet demonstrates how to achieve structured output with OpenAIChatCompletionsRunner by defining a Pydantic model and passing it to the `output_format` parameter. Requires initialization of OpenAIChatCompletionsClient.

```python
from pydantic import BaseModel
from toyaikit.llm import OpenAIChatCompletionsClient
from toyaikit.chat.runners import OpenAIChatCompletionsRunner

# Define your response structure
class TestResponse(BaseModel):
    hello: bool
    world: str

# Create the runner
runner = OpenAIChatCompletionsRunner(llm_client=OpenAIChatCompletionsClient())

# Use structured output
result = runner.loop(prompt='how are you', output_format=TestResponse)
print(result.last_message)
# Output: TestResponse(hello=True, world="I'm doing well, thank you! How can I assist you today?")

# Or use without structured output for free-form text
result = runner.loop(prompt='how are you')
print(result.last_message)
# Output: "I'm just a program, but I'm here and ready to help you! How can I assist you today?"
```

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

### Publish to PyPI

Source: https://pypi.org/project/toyaikit

Publish the built package to the official PyPI repository. Ensure the package is built and tested before publishing.

```shell
uv run hatch publish

```

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

### Publish to Test PyPI

Source: https://pypi.org/project/toyaikit

Publish the built package to the Test PyPI repository. This is useful for testing the publishing process without affecting the main PyPI index.

```shell
uv run hatch publish --repo test

```

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

### OpenAI Agents SDK Runner Integration

Source: https://pypi.org/project/toyaikit

Integrates the OpenAI Agents SDK with ToyAIKit. Requires tools to be wrapped with the function_tool decorator.

```python
from agents import Agent, function_tool

from toyaikit.tools import wrap_instance_methods
from toyaikit.chat import IPythonChatInterface
from toyaikit.chat.runners import OpenAIAgentsSDKRunner

# Wrap tools with function_tool decorator
agent_tools = ... # your tools class instance
coding_agent_tools_list = wrap_instance_methods(function_tool, agent_tools)

# Create the Agent
coding_agent = Agent(
    name="CodingAgent",
    instructions="You are a coding agent that can modify Django projects.",
    tools=coding_agent_tools_list,
    model='gpt-4o-mini'
)

# Setup and run with ToyAIKit
chat_interface = IPythonChatInterface()
runner = OpenAIAgentsSDKRunner(
    chat_interface=chat_interface,
    agent=coding_agent
)

# In Jupyter, run asynchronously
await runner.run()

```

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

### Clean Build Artifacts

Source: https://pypi.org/project/toyaikit

Remove the distribution directory to clean up build artifacts. This ensures a fresh build on the next attempt.

```shell
rm -r dist/

```

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

### Add Individual Functions to Tools

Source: https://pypi.org/project/toyaikit

Integrate individual Python functions into the ToyAIKit tools system for LLM function calling. Ensure functions are defined with type hints and docstrings.

```Python
from toyaikit.tools import Tools

tools = Tools()

# Add individual functions
def calculate_area(length: float, width: float):
    """Calculate the area of a rectangle."""
    return length * width

tools.add_tool(calculate_area)
```

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

### Z.ai GLM-4.5 Integration with OpenAI Client

Source: https://pypi.org/project/toyaikit

Integrates Z.ai's GLM-4.5 model using the OpenAI client with a custom base URL. Requires ZAI_API_KEY environment variable.

```python
import os
from openai import OpenAI

from toyaikit.tools import Tools
from toyaikit.chat import IPythonChatInterface
from toyaikit.chat.runners import OpenAIChatCompletionsRunner
from toyaikit.llm import OpenAIChatCompletionsClient

# Setup z.ai client
zai_client = OpenAI(
    api_key=os.getenv('ZAI_API_KEY'),
    base_url='https://api.z.ai/api/paas/v4/'
)

# Define the model to use
llm_client = OpenAIChatCompletionsClient(
    model='glm-4.5',
    client=zai_client
)

# Setup tools and run
agent_tools = ...

tools = Tools()
tools.add_tools(agent_tools)

runner = OpenAIChatCompletionsRunner(
    tools=tools,
    developer_prompt="You are a coding agent that can modify Django projects.",
    chat_interface=IPythonChatInterface(),
    llm_client=llm_client
)

runner.run()

```

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

### Add Class Methods to Tools

Source: https://pypi.org/project/toyaikit

Integrate all methods from a Python class instance into the ToyAIKit tools system. This allows multiple related functions to be added efficiently.

```Python
# Add all methods from a class instance
class MathTools:
    def add(self, a: float, b: float):
        """Add two numbers."""
        return a + b
    
    def multiply(self, a: float, b: float):
        """Multiply two numbers."""
        return a * b

math_tools = MathTools()
tools.add_tools(math_tools)
```

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

### Switching PydanticAI Agent to Claude

Source: https://pypi.org/project/toyaikit

Reconfigure an existing PydanticAI agent to use Anthropic's Claude model. This is useful for comparing model performance or utilizing specific Claude features.

```python
coding_agent = Agent(
    'anthropic:claude-3-5-sonnet-latest',
    instructions="You are a coding agent that can modify Django projects.",
    tools=coding_agent_tools_list
)


```

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

### MCP Client Usage with Subprocess Transport

Source: https://pypi.org/project/toyaikit

Connects to an MCP server using a subprocess transport. Requires the server command and working directory to be specified.

```python
from toyaikit.mcp import MCPClient, SubprocessMCPTransport

# Connect to an MCP server
client = MCPClient(
    transport=SubprocessMCPTransport(
        server_command=["uv", "run", "python", "main.py"],
        workdir="faq-mcp"
    )
)

# Initialize connection
client.full_initialize()

# Use MCP tools with ToyAIKit
from toyaikit.mcp import MCPTools

mcp_tools = MCPTools(client)

runner = OpenAIResponsesRunner(
    tools=mcp_tools,
    developer_prompt="You are an assistant with access to MCP tools.",
    chat_interface=IPythonChatInterface(),
    llm_client=OpenAIClient()
)

runner.run()

```

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

### PydanticAI Agent with MCP Server

Source: https://pypi.org/project/toyaikit

Integrate PydanticAI with a Multi-Chat Protocol (MCP) server using `MCPServerStdio`. This allows agents to communicate through a standardized protocol, useful for distributed or complex chat applications.

```python
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

from toyaikit.chat.interface import StdOutputInterface
from toyaikit.chat.runners import PydanticAIRunner

# Connect to MCP server
mcp_client = MCPServerStdio(
    command="uv",
    args=["run", "python", "main.py"],
    cwd="faq-mcp"
)

# Create agent with MCP tools
agent = Agent(
    name="faq_agent",
    instructions="You're a course teaching assistant.",
    toolsets=[mcp_client],
    model='gpt-4o-mini'
)

# Run agent
runner = PydanticAIRunner(
    chat_interface=StdOutputInterface(),
    agent=agent
)

import asyncio
asyncio.run(runner.run())


```

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

### Anthropic Messages API Integration

Source: https://pypi.org/project/toyaikit

Integrates Anthropic's Claude models using the Messages API. Supports default ANTHROPIC_API_KEY or custom base URL for z.ai compatibility.

```python
import os

from toyaikit import AnthropicClient, AnthropicMessagesRunner
from toyaikit.tools import Tools
from toyaikit.chat import IPythonChatInterface

# Setup Anthropic client
# Uses ANTHROPIC_API_KEY from environment automatically
llm_client = AnthropicClient(
    model="claude-sonnet-4-5-20250514",
)

# Or with custom base URL (e.g., for z.ai compatibility)
llm_client = AnthropicClient(
    api_key=os.environ.get("ZAI_AUTH_TOKEN"),
    base_url="https://api.z.ai/api/anthropic",
    model="claude-sonnet-4-5-20250929",
)

# Setup tools and run
agent_tools = ... # class with some functions to be called

tools = Tools()
tools.add_tools(agent_tools)

runner = AnthropicMessagesRunner(
    tools=tools,
    developer_prompt="You are a helpful assistant.",
    chat_interface=IPythonChatInterface(),
    llm_client=llm_client
)

runner.run()

```
Tokens:
Raw