minions-py 0.2.0__tar.gz

minions_py-0.2.0/PKG-INFO

@@ -0,0 +1,464 @@
+Metadata-Version: 2.4
+Name: minions-py
+Version: 0.2.0
+Summary: Reusable provider-specific AI workflow agents.
+Project-URL: Repository, https://github.com/is-leeroy-jenkins/minions
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic<2,>=1.4
+Requires-Dist: google-adk<3,>=2.8
+Requires-Dist: mistralai[agents]<3,>=2.9
+Requires-Dist: openai-agents<1,>=0.22
+Requires-Dist: xai-sdk<2,>=1.19
+
+###### minions
+
+<p align="center">
+  <img src="resources/images/minions-project.png" alt="Minions" width="900">
+</p>
+
+<p align="center">
+  <a href="#supported-providers">Providers</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#concrete-minions">Minions</a> ·
+  <a href="#native-provider-tools">Native Tools</a> ·
+  <a href="https://github.com/is-leeroy-jenkins/minions/blob/main/resources/user-guide.md">User Guide</a> ·
+  <a href="#development">Development</a>
+</p>
+
+___
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-0078FC?style=for-the-badge&logo=github)](https://is-leeroy-jenkins.github.io/minions/)
+
+
+Provider-native AI agents organized as reusable workflow-specific `Minion` classes.
+
+![](https://github.com/is-leeroy-jenkins/minions/blob/main/resources/images/minions-workflow.png)
+
+___
+
+Minions keeps each workflow inside one provider pathway. Tool schemas and tool functions are never
+translated or mixed between providers.
+
+## Supported Providers
+
+| Module            | Provider SDK                 | `Minion` implementation                  | Execution methods            |
+|-------------------|------------------------------|------------------------------------------|------------------------------|
+| `minions.gpt`     | OpenAI Agents SDK            | Inherits `agents.Agent`                  | `run`, `run_async`, `stream` |
+| `minions.gemini`  | Google Agent Development Kit | Inherits `google.adk.Agent`              | `run`, `run_async`, `stream` |
+| `minions.grok`    | xAI SDK                      | Wraps synchronous and asynchronous chats | `run`, `run_async`, `stream` |
+| `minions.claude`  | Anthropic SDK                | Wraps native tool runners                | `run`, `run_async`, `stream` |
+| `minions.mistral` | Mistral SDK                  | Wraps a native remote agent              | `run`, `run_async`, `stream` |
+
+## Installation
+
+```powershell
+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:
+
+```powershell
+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.
+
+| Provider | Environment variable |
+|----------|----------------------|
+| OpenAI   | `OPENAI_API_KEY`     |
+| Gemini   | `GOOGLE_API_KEY`     |
+| Grok     | `XAI_API_KEY`        |
+| Claude   | `ANTHROPIC_API_KEY`  |
+| Mistral  | `MISTRAL_API_KEY`    |
+
+
+
+![](https://github.com/is-leeroy-jenkins/minions/blob/main/resources/images/minions-architecture.png)
+
+___
+
+## Concrete Minions
+
+The same concrete class family is exported from every provider module.
+
+| Guro workflow category                   | Minion class            |
+|------------------------------------------|-------------------------|
+| Research / Academic                      | `ResearchMinion`        |
+| Writing / Administrative                 | `WritingMinion`         |
+| Compliance / Legal / Budget              | `ComplianceMinion`      |
+| Business / Finance / Marketing           | `BusinessMinion`        |
+| Software Engineering / Software Engineer | `CodingMinion`          |
+| Data Analytics                           | `DataMinion`            |
+| Data Governance                          | `GovernanceMinion`      |
+| Instruction / Training / Planning        | `PlanningMinion`        |
+| Image Generation                         | `ImageGenerationMinion` |
+| Image Analysis                           | `ImageAnalysisMinion`   |
+| Image Editing                            | `ImageEditingMinion`    |
+| Translation API                          | `TranslationMinion`     |
+| Transcription API                        | `TranscriptionMinion`   |
+| Speech API                               | `SpeechMinion`          |
+
+
+
+## Quick Start
+
+### OpenAI
+
+```python
+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
+
+```python
+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`.
+
+```python
+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
+
+```python
+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.
+
+```python
+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.
+
+```python
+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
+
+| Argument | Type | Default | Description |
+|---|---|---:|---|
+| `model` | `str` | Required | Provider model identifier |
+| `instructions` | `str` | Required | System instructions, including Guro instruction text |
+| `tools` | Provider-specific sequence or `None` | `None` | Optional provider-native tools |
+| `max_turns` | `int` | `10` | Maximum model turns for one execution |
+| `name` | `str` or `None` | `None` | Overrides the concrete class display name |
+
+### Provider-specific arguments
+
+| Provider | Argument | Type | Default | Description |
+|---|---|---|---:|---|
+| Grok | `functions` | `Sequence[ToolFunction]` or `None` | `None` | Local callables matching Grok tool schemas |
+| Grok | `api_key` | `str` or `None` | `None` | Overrides `XAI_API_KEY` |
+| Claude | `max_tokens` | `int` | `4096` | Maximum generated tokens |
+| Claude | `api_key` | `str` or `None` | `None` | Overrides `ANTHROPIC_API_KEY` |
+| Mistral | `functions` | `Sequence[ToolFunction]` or `None` | `None` | Local callables matching function-tool schemas |
+| Mistral | `api_key` | `str` or `None` | `None` | Overrides `MISTRAL_API_KEY` |
+
+## Execution Reference
+
+| Provider | `run` return | `run_async` return | `stream` return |
+|---|---|---|---|
+| OpenAI | `RunResult` | `RunResult` | `RunResultStreaming` |
+| Gemini | Final `Event` | Final `Event` | `AsyncIterator[Event]` |
+| Grok | `Response` | `Response` | `AsyncIterator[tuple[Response, Chunk]]` |
+| Claude | `BetaMessage` | `BetaMessage` | `BetaAsyncStreamingToolRunner[object]` |
+| Mistral | `ChatCompletionResponse` | `ChatCompletionResponse` | `Iterator[CompletionEvent]` |
+
+Asynchronous execution:
+
+```python
+result = await minion.run_async( 'Complete the workflow.' )
+```
+
+Streaming execution:
+
+```python
+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
+
+| Provider | Accepted tool contract |
+|---|---|
+| OpenAI | OpenAI Agents SDK `Tool` objects |
+| Gemini | Callable, `BaseTool`, or `BaseToolset` |
+| Grok | xAI `chat_pb2.Tool`; local function schemas require identically named callables |
+| Claude | `ClaudeTool`: Anthropic `BetaFunctionTool` or `BetaToolUnionParam` |
+| Mistral | `CreateAgentRequestTool` schemas; local function tools require identically named callables |
+
+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
+
+| Provider | Native tools exported by the provider module |
+|---|---|
+| OpenAI | `WebSearchTool`, `FileSearchTool`, `CodeInterpreterTool`, `ImageGenerationTool` |
+| Gemini | `google_search`, `url_context`, `VertexAiSearchTool` |
+| Grok | `web_search`, `code_execution`, `collections_search`, `image_generation` |
+| Claude | Web search, web fetch, and code execution through `BetaToolUnionParam` definitions |
+| Mistral | `WebSearchTool`, `CodeInterpreterTool`, `ImageGenerationTool`, `DocumentLibraryTool` |
+
+Native tools remain optional and provider-specific. Do not pass a native tool from one provider to
+another provider's Minion.
+
+### OpenAI native tools
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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.
+
+```python
+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:
+
+```python
+from minions.gpt import ComplianceMinion
+
+
+class BudgetMinion( ComplianceMinion ):
+    """OpenAI Minion specialized for federal budget compliance."""
+
+    minion_name: str = 'Budget Minion'
+```
+
+## Development
+
+```powershell
+python -m pip install -e .
+python -m pip install pytest pytest-asyncio build
+python -m pytest
+python -m build
+```
+
+Documentation:
+
+```powershell
+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
+
+```text
+minions/
+├── __init__.py
+├── config.py
+├── gpt.py
+├── gemini.py
+├── grok.py
+├── claude.py
+├── mistral.py
+└── tests/
+```
+<p align="center">
+  <a href="https://github.com/is-leeroy-jenkins/minions/actions/workflows/tests.yml"><img src="https://github.com/is-leeroy-jenkins/minions/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/version-0.2.0-6f42c1" alt="Version 0.2.0">
+</p>