servants 0.2.0

A simple library for prototyping and learning agent-based reasoning with tools.

servants

A simple Python library for prototyping and learning agent-based reasoning with tools.

This package helps you quickly prototype agent architectures that use tools (functions) and step-by-step reasoning. It is designed for educational and experimental purposes, not for production use.

Installation

pip install servants

Usage

# Example: Using Servants for Tool-Driven Agent Reasoning

import time
import sys
import os
from openai import OpenAI

# Import the main classes for tool, agent, and orchestration
from servants import Tool, Servant, Master

# --- Tool Definitions ---
def get_weather(city: str) -> str:
    """
    Gets the current weather for a given city.
    Args:
        city (str): The city to get the weather for.
    Returns:
        str: The weather conditions (e.g., "Sunny", "Rainy", "Cloudy").
    """
    if "london" in city.lower():
        return "Rainy"
    elif "paris" in city.lower():
        return "Sunny"
    else:
        return "Cloudy"

def suggest_activity(weather: str) -> str:
    """
    Suggests an activity based on the weather.
    Args:
        weather (str): The current weather (e.g., "Sunny", "Rainy", "Cloudy").
    Returns:
        str: A suggested activity.
    """
    if weather == "Sunny":
        return "Go for a walk in the park."
    elif weather == "Rainy":
        return "Visit a museum or watch a movie."
    else:
        return "It's a good day to read a book indoors."

# --- LLM Client Setup ---
# Set up OpenAI client (replace with your API key)
client = OpenAI(api_key="sk-...YOUR-API-KEY...")

# --- Tool Wrapping ---
weather_tool = Tool(get_weather, "get_weather", "Gets the current weather for a given city.")
activity_tool = Tool(suggest_activity, "suggest_activity", "Suggests an activity based on the weather.")

# --- LLM Chat Completion Function ---
def chat_completion_func(messages):
    """
    Calls the OpenAI chat completion API with the given messages.
    Args:
        messages (list): List of message dicts for the LLM.
    Returns:
        str: The LLM's response content.
    """
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        temperature=0.7
    )
    return response.choices[0].message.content

# --- Agent and Orchestration ---
servant = Servant(tools=[weather_tool, activity_tool])
manager = Master([servant])
problem = "I'm in London today. What do you suggest I do?"
system_message = (
    "You are a helpful assistant. You can use tools to find information and make suggestions. "
    "Reason step-by-step to solve the user's problem."
)

print("Starting the orchestrator...")
manager.run(
    problem=problem,
    chat_completion_func=chat_completion_func,
    system_message=system_message,
    max_iterations=4,
    tools=[weather_tool, activity_tool]
)

# --- Monitoring and Control ---
for _ in range(10):
    print(f"Manager statuses: {manager.get_status()}")
    time.sleep(1)
print("Pausing all servants...")
manager.pause()
time.sleep(3)
print("Resuming all servants...")
manager.resume()
time.sleep(10)
results = manager.get_results()
print("\nResults from Manager:")
for idx, result in results:
    print(f"Servant {idx}: {result}")
manager.stop()
print("All servants stopped")

# --- Entrypoint ---
if __name__ == "__main__":
    # Run the example usage if this script is executed directly
    example_usage()

What does it do?

• Lets you quickly prototype agent-based architectures that use tools (functions) and step-by-step reasoning.
• Provides a simple API for defining tools, agents (servants), and orchestrators (masters).
• Automatically generates a JSON schema for any Python function's parameters and types.
• Makes it easy to describe agent tools and methods for LLMs or other automation systems.
• Minimal, easy-to-use API for experimentation and learning.

Note

This library is intended for prototyping and learning. For production-grade agent frameworks, see LangChain or similar projects.