minions-py 0.2.0

minions

Providers · Installation · Minions · Native Tools · User Guide · Development

Provider-native AI agents organized as reusable workflow-specific Minion classes.

Minions keeps each workflow inside one provider pathway. Tool schemas and tool functions are never translated or mixed between providers.

Supported Providers

Installation

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install git+https://github.com/is-leeroy-jenkins/minions.git

Editable installation for development:

git clone https://github.com/is-leeroy-jenkins/minions.git
Set-Location minions
python -m pip install -e .

Authentication

Set only the key required by the selected provider.

Concrete Minions

The same concrete class family is exported from every provider module.

Quick Start

OpenAI

from fonky.gpt import tools
from guro import instructions
from minions.gpt import DataMinion


minion = DataMinion(
    model='gpt-5.6-sol',
    instructions=instructions.get( 'DATA_SCIENTIST' ),
    tools=[ tools.fetch_wikipedia, tools.load_csv ],
)
result = minion.run( 'Analyze the available evidence.' )

Gemini

from fonky.gemini import tools
from guro import instructions
from minions.gemini import ResearchMinion


minion = ResearchMinion(
    model='gemini-2.5-flash',
    instructions=instructions.get( 'DEEP_RESEARCH_AGENT' ),
    tools=[ tools.fetch_wikipedia ],
)
result = minion.run( 'Research the requested topic.' )

Grok

Grok requires matching provider schemas and local callables only for client-executed function tools. xAI-hosted tools do not require entries in functions.

from fonky.grok import tools
from guro import instructions
from minions.grok import DataMinion


minion = DataMinion(
    model='grok-4.5',
    instructions=instructions.get( 'DATA_SCIENTIST' ),
    tools=[ tools.wikipedia_fetch_tool, tools.csv_tool ],
    functions=[ tools.fetch_wikipedia, tools.load_csv ],
)
result = minion.run( 'Analyze the available evidence.' )

Claude

from fonky.claude import tools
from guro import instructions
from minions.claude import ComplianceMinion


minion = ComplianceMinion(
    model='claude-sonnet-4-6',
    instructions=instructions.get( 'COMPLIANCE_ANALYST' ),
    tools=[ tools.load_pdf, tools.fetch_web_page ],
)
result = minion.run( 'Evaluate the supplied material.' )

Mistral

Mistral requires matching provider schemas and local callables for local function tools. Provider-hosted tools do not require a local callable.

from fonky.mistral import tools
from guro import instructions
from minions.mistral import CodingMinion


minion = CodingMinion(
    model='mistral-medium-latest',
    instructions=instructions.get( 'SENIOR_ENGINEER' ),
    tools=[ tools.github_tool ],
    functions=[ tools.load_github ],
)
result = minion.run( 'Review the repository.' )

Tool-Free Execution

Tools are optional for every provider.

from guro import instructions
from minions.gpt import WritingMinion


minion = WritingMinion(
    model='gpt-5.6-sol',
    instructions=instructions.get( 'TECHNICAL_WRITER' ),
)
result = minion.run( 'Draft the requested documentation.' )

Constructor Reference

Common arguments

Provider-specific arguments

Execution Reference

Asynchronous execution:

result = await minion.run_async( 'Complete the workflow.' )

Streaming execution:

stream = minion.stream( 'Complete the workflow.' )

OpenAI and Claude return provider-managed streaming objects. Gemini and Grok return asynchronous iterators. Mistral returns a synchronous iterator. Each pathway continues its tool loop through the final provider response.

Tool Contracts

Grok and Mistral reject duplicate, missing, or extra local function names before execution. Provider-hosted tools execute on the provider and therefore do not require local callables.

Native Provider Tools

Native tools remain optional and provider-specific. Do not pass a native tool from one provider to another provider's Minion.

OpenAI native tools

from minions.gpt import FileSearchTool, ResearchMinion, WebSearchTool


minion = ResearchMinion(
    model='gpt-5.6-sol',
    instructions='Research the question using current and indexed sources.',
    tools=[
        WebSearchTool( ),
        FileSearchTool( vector_store_ids=[ 'vs_...' ] ),
    ],
)

CodeInterpreterTool and ImageGenerationTool accept their native OpenAI tool configuration objects. Minions passes those configurations to the OpenAI Agents SDK unchanged.

Gemini native tools

from minions.gemini import ResearchMinion, VertexAiSearchTool


minion = ResearchMinion(
    model='gemini-2.5-flash',
    instructions='Research the configured enterprise data store.',
    tools=[
        VertexAiSearchTool(
            data_store_id=(
                'projects/project/locations/global/collections/default_collection/'
                'dataStores/store'
            ),
        ),
    ],
)

google_search and url_context are native ADK tool objects and can be imported directly from minions.gemini. Supported tool combinations depend on the selected Gemini model and ADK rules.

Grok native tools

from minions.grok import DataMinion, code_execution, collections_search, web_search


minion = DataMinion(
    model='grok-4.5',
    instructions='Research and analyze the requested subject.',
    tools=[
        web_search( ),
        code_execution( ),
        collections_search( collection_ids=[ 'collection-id' ] ),
    ],
)

The image_generation constructor is also exported from minions.grok. xAI executes these tools on its servers; functions remains reserved for client-executed function schemas.

Claude native tools

from minions.claude import ResearchMinion


minion = ResearchMinion(
    model='claude-sonnet-4-6',
    instructions='Research and analyze the requested subject.',
    tools=[
        { 'type': 'web_search_20260318', 'name': 'web_search' },
        { 'type': 'web_fetch_20260318', 'name': 'web_fetch' },
        { 'type': 'code_execution_20260521', 'name': 'code_execution' },
    ],
)

Anthropic executes these server tools. Local tools decorated with anthropic.beta_tool can appear in the same tools sequence and are executed by Anthropic's native tool runner.

Mistral native tools

from minions.mistral import (
    CodeInterpreterTool,
    DataMinion,
    DocumentLibraryTool,
    WebSearchTool,
)


minion = DataMinion(
    model='mistral-medium-latest',
    instructions='Research and analyze the requested subject.',
    tools=[
        WebSearchTool( ),
        CodeInterpreterTool( ),
        DocumentLibraryTool( library_ids=[ 'library-id' ] ),
    ],
)

ImageGenerationTool is also exported from minions.mistral. Mistral executes native tools; functions remains reserved for client-executed function schemas.

Category Templates

Concrete Minions are subclass templates. Guro prompts plug into a category through the instructions argument without a factory or registry.

from guro import instructions
from minions.gpt import GovernanceMinion


governor = GovernanceMinion(
    model='gpt-5.6-sol',
    instructions=instructions.get( 'AI_GOVENANCE_AGENT' ),
)

Provider-specific customization uses ordinary inheritance:

from minions.gpt import ComplianceMinion


class BudgetMinion( ComplianceMinion ):
    """OpenAI Minion specialized for federal budget compliance."""

    minion_name: str = 'Budget Minion'

Development

python -m pip install -e .
python -m pip install pytest pytest-asyncio build
python -m pytest
python -m build

Documentation:

python -m pip install -r requirements-docs.txt
python -m mkdocs build --strict
python -m mkdocs serve

Tests mock provider network boundaries and validate provider inheritance, optional tools, concrete class exports, synchronous execution, asynchronous execution, streaming, and local tool loops.

Project Structure

minions/
├── __init__.py
├── config.py
├── gpt.py
├── gemini.py
├── grok.py
├── claude.py
├── mistral.py
└── tests/