squadria 0.1.5

A multi-agent orchestration framework for Python develpoed by Sajib Hossain

Squadria

squadria is a lightweight Python framework for orchestrating role-based AI agents. It gives you simple building blocks to define an assistant persona, assign tasks, and run multi-step workflows where one step can feed context into the next.

Features

• Persona-driven agents (Actor) powered by LiteLLM
• Structured task objects (Job) with expected output guidance
• Sequential, parallel, and hierarchical orchestration (Squad)
• Plugin abstraction (Plugin) with automatic parameter schema generation
• Small, readable core focused on extensibility

Installation

pip install squadria

Quick Start

Set your provider API key first (example for OpenAI):

export OPENAI_API_KEY="your_api_key_here"

Create and run a simple two-step workflow:

from squadria import Actor, Job, Squad

researcher = Actor(
    title="Senior Tech Researcher",
    objective="Find practical trends in AI tooling.",
    expertise="You analyze current AI engineering practices.",
    tone=["concise", "analytical"],
    language="English",
    model="gpt-4o-mini",
    verbose=True,
    trace_level="minimal",
    guardrails=["personal_info", "medicine"],
)

writer = Actor(
    title="Technical Writer",
    objective="Turn research into a clear summary.",
    expertise="You explain technical topics for developers.",
    tone=["clear", "engaging"],
    language="English",
    model="gpt-4o-mini",
    verbose=True,
)

research_job = Job(
    description="List 3 current trends in AI agent frameworks.",
    expected_output="Three bullet points with one sentence each.",
    actor=researcher,
    max_retries=10,
)

writing_job = Job(
    description="Write a short 2-paragraph overview from the research context.",
    expected_output="Two short paragraphs.",
    actor=writer,
)

squad = Squad(
    actors=[researcher, writer],
    jobs=[research_job, writing_job],
    process="sequential",
    trace_level="minimal",
)

final_result = squad.kickoff()
print(final_result)

Hierarchical Execution

Use a manager actor to plan subtasks, delegate them to workers, and synthesize final output.

from squadria import Actor, Job, Squad

manager = Actor(
    title="Engineering Manager",
    objective="Break goals into tasks and synthesize final output.",
    expertise="You are strong at decomposition and delegation.",
    tone=["structured", "decisive"],
    language="English",
    model="gpt-4o-mini",
)

researcher = Actor(
    title="Research Analyst",
    objective="Collect evidence quickly.",
    expertise="You summarize findings with references.",
    tone=["concise"],
    language="English",
    model="gpt-4o-mini",
)

writer = Actor(
    title="Technical Writer",
    objective="Write clear final prose.",
    expertise="You communicate complex ideas simply.",
    tone=["clear"],
    language="English",
    model="gpt-4o-mini",
)

top_level_job = Job(
    description="Create a short brief on modern AI agent orchestration patterns.",
    expected_output="A concise, structured brief.",
    actor=manager,
    max_retries=10,
)

squad = Squad(
    actors=[manager, researcher, writer],
    jobs=[top_level_job],
    process="hierarchical",
    manager=manager,
)

result = squad.kickoff()
print(result)

Core Concepts

Persona Configuration

Defines the personality and constraints for an agent:

• title: role name
• objective: what the agent tries to achieve
• expertise: domain background for grounding
• tone: list of style adjectives
• language: response language (default: English)

Actor accepts these fields directly as constructor parameters.

Actor

Wraps LLM execution. It:

• auto-generates a unique id (UUID string)
• accepts persona fields directly: title, objective, expertise, optional tone, optional language
• accepts optional guardrails (built-in and custom)
• when verbose=True, prints step-by-step console traces
• accepts optional trace_level (minimal or detailed, default: minimal)
• builds a system prompt from persona data
• optionally includes plugin descriptions
• sends messages through litellm.completion(...)
• returns the model output text

Guardrails

Guardrails are optional Actor-level safety constraints.

Built-in guardrail keys:

• personal_info
• medicine
• self_harm
• violence
• illegal_activities
• financial_advice

You can configure them with:

• built-ins as strings: guardrails=["medicine", "personal_info"]
• object-style custom rules: guardrails=["medicine", {"name": "no_legal_advice", "rule": "Do not provide legal advice.", "severity": "high"}]

For custom rules, only rule is required. name and severity are optional metadata.

Job

Represents a single task with:

• description
• expected_output
• actor
• optional context
• optional max_retries (default: 10)
• auto-generated id (UUID string)

Squad

Supports three process modes:

• sequential: chains context from one job to the next
• parallel: executes all jobs concurrently and returns combined ordered output
• hierarchical: manager plans worker tasks (JSON plan), workers execute, manager synthesizes final output
• auto-generated id (UUID string)
• optional trace_level (minimal or detailed, default: minimal)

Plugin

Wraps a Python function into a reusable capability object and generates a JSON schema for function arguments using Pydantic.

Plugin Example

from squadria.plugins.base import Plugin

def add(a: int, b: int) -> int:
    return a + b

math_plugin = Plugin(
    name="adder",
    description="Adds two numbers",
    func=add,
)

print(math_plugin.execute(a=2, b=3))  # 5
print(math_plugin.get_description())   # includes auto-generated schema

API Surface

Top-level imports available from squadria:

• Actor
• Job
• Plugin
• Squad

Persona schema classes are internal implementation details and are not part of the top-level public interface.

Notes

• Current orchestration modes are sequential, parallel, and hierarchical.
• Hierarchical mode requires manager=... and at least one worker actor.
• Ensure your API key is set for the model provider you choose.
• This framework is intentionally minimal and designed to be extended.