minion-ai 0.1.0__tar.gz

minion_ai-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install *)",
+      "Bash(python *)",
+      "Bash(.venv/Scripts/pip install *)",
+      "Bash(.venv/Scripts/python *)",
+      "WebFetch(domain:peps.python.org)"
+    ]
+  }
+}

minion_ai-0.1.0/.env

@@ -0,0 +1,2 @@
+GROQ_API_KEY_1=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
+OPENAI_API_KEY=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

minion_ai-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: minion-ai
+Version: 0.1.0
+Summary: A simple agentic framework with observability and evals baked in
+Project-URL: Repository, https://github.com/shriyansnaik/minions
+Requires-Python: >=3.10
+Requires-Dist: docstring-parser
+Requires-Dist: litellm
+Requires-Dist: openai
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# minions
+A simple agentic framework - observability, evals baked in

minion_ai-0.1.0/README.md

@@ -0,0 +1,2 @@
+# minions
+A simple agentic framework - observability, evals baked in

minion_ai-0.1.0/minions/TODO.md

@@ -0,0 +1,77 @@
+# Minions — TODO
+
+---
+
+## 1. Provider Agnostic (LiteLLM)
+
+**Problem:** Right now the code calls `client.responses.parse(...)` which is OpenAI's Responses API.
+Other providers (Anthropic, Gemini, Mistral, etc.) do not have this API, so swapping the provider is not just swapping the key — it requires changing the call itself.
+
+**Solution:** Use [LiteLLM](https://github.com/BerriAI/litellm) as an abstraction layer.
+LiteLLM wraps every major provider behind one unified interface.
+
+**What needs to change:**
+- Replace `client.responses.parse(...)` with a LiteLLM call
+- LiteLLM has structured output support via `response_format` — use that instead of `text_format`
+- `minions.init()` would accept `provider` or just let the model string carry it (LiteLLM style: `"anthropic/claude-opus-4"`, `"gemini/gemini-2.5-pro"`)
+- Drop the custom `get_client()` — LiteLLM handles the client internally
+
+**New init signature:**
+```python
+minions.init(api_key="...", model_prefix="anthropic")
+# or just pass model strings like "anthropic/claude-opus-4" to Minion directly
+```
+
+---
+
+## 2. Observability UI (minions-ui)
+
+A separate open source Docker app that shows traces from all Minion runs.
+
+### Architecture
+```
+FastAPI backend  ←  Minion posts traces here after each run
+SQLite database  ←  FastAPI stores traces as JSON
+React frontend   ←  reads from FastAPI, renders trace tree
+```
+
+### How users run it
+```bash
+git clone https://github.com/you/minions-ui
+cd minions-ui
+docker compose up
+# UI available at http://localhost:7337
+```
+
+### How users enable tracing in their code
+```python
+import minions
+minions.init(api_key="...", tracing=True, ui_url="http://localhost:7337")
+```
+
+### What the UI shows
+- List of all runs (left panel) — timestamp, model, first user message
+- Trace tree (right panel) for selected run:
+  - User input
+  - Each turn: thought → tool calls (with args) → tool outputs
+  - Sub-minion runs nested under the parent
+  - Final answer
+  - Token usage + latency per turn
+
+### What needs to be built
+- [ ] `Minion.to_trace()` — serializes conversation + raw_model_responses to a JSON blob
+- [ ] POST to `ui_url/api/traces` after `_finish` is called
+- [ ] FastAPI app with two endpoints: `POST /api/traces`, `GET /api/traces`, `GET /api/traces/{id}`
+- [ ] SQLite schema: `id`, `timestamp`, `model`, `input`, `trace_json`
+- [ ] React app (Vite + React, no UI kit) with run list + trace tree
+- [ ] Dockerfile + docker-compose.yml
+
+---
+
+## 3. Package Setup (pip installable)
+
+- [ ] Add `pyproject.toml` (or `setup.py`)
+- [ ] Decide package name (e.g. `minions-ai`)
+- [ ] Publish to PyPI
+- [ ] `minions[ui]` optional dependency group for FastAPI + uvicorn
+- [ ] `minions ui` CLI command to start the UI server locally without Docker

minion_ai-0.1.0/minions/__init__.py

@@ -0,0 +1,4 @@
+from .config import init
+from .minion import Minion
+
+__all__ = ["Minion", "init"]

minion_ai-0.1.0/minions/client.py

@@ -0,0 +1,16 @@
+from openai import OpenAI
+from .config import get_config
+
+
+def get_client() -> OpenAI:
+    config = get_config()
+
+    if not config.api_key:
+        raise RuntimeError(
+            "No API key set. Call minions.init(api_key='...') before using Minion."
+        )
+
+    return OpenAI(
+        api_key=config.api_key,
+        base_url=config.base_url,
+    )

minion_ai-0.1.0/minions/config.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class _Config:
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+    tracing: bool = False
+    ui_url: Optional[str] = None
+
+
+_config = _Config()
+
+
+def init(
+    api_key: str,
+    base_url: str = None,
+    tracing: bool = False,
+    ui_url: str = None,
+):
+    """Configure the minions library. Call once before creating any Minion.
+
+    Args:
+        api_key: Your OpenAI API key.
+        base_url: Optional custom endpoint (Azure, vLLM, any OpenAI-compatible API).
+        tracing: Enable trace collection.
+        ui_url: URL of the minions-ui server (required if tracing=True).
+    """
+    _config.api_key = api_key
+    _config.base_url = base_url
+    _config.tracing = tracing
+    _config.ui_url = ui_url
+
+
+def get_config() -> _Config:
+    return _config

minion_ai-0.1.0/minions/minion.py

@@ -0,0 +1,204 @@
+import inspect
+import docstring_parser
+from typing import Callable, Literal
+
+from .models import Tool, ToolArg, ToolCall, MinionOutput
+from .client import get_client
+
+MINION_BASE_PROMPT = """#Role
+You are Minion, a powerful AI agent. Given user input, produce the best possible output using your available tools.
+
+====================================================
+# Tools You Have
+
+{tool_schemas}
+====================================================
+
+## Sub Minions (Delegating huge tasks)
+If the above tools include `_spawn_sub_minion`, use it to delegate large tasks.
+
+**Trigger rules (apply these before starting work):**
+- Task involves reading or processing **3+ independent files/URLs/items** → delegate to sub minions
+- Split items evenly: e.g. 12 files → 3 sub minions × 4 files each
+- Each sub minion gets: the same instructions + its specific subset of items
+- You synthesize their results; you do NOT read the files yourself
+
+Only skip delegation if items are fewer than 3, or one item's output feeds another.
+
+## Thoughts
+Keep thoughts concise — enough for the human to follow your reasoning. Do not name tools directly; describe your intent instead.
+
+## Tool Arguments
+All tool args must be valid JSON. Escape double quotes where needed.
+
+## Multiple Tools
+Call independent tools simultaneously; only sequence tools when one depends on another's output.
+
+## Output Format
+Every response must include `next_thought` and `next_tools`.
+When you have sufficient information to answer, call `_finish` with your answer in `final_response`."""
+
+
+class Minion:
+
+    def __init__(
+        self,
+        model: str,
+        reasoning_effort: str = None,
+        secondary_model: str = None,
+        secondary_model_reasoning_effort: str = None,
+        system_prompt: str = None,
+        tools: list | None = [],
+        allow_sub_agents: bool = False,
+        max_turns: int = 10,
+    ):
+        self.model = model
+        self.reasoning_effort = reasoning_effort
+        self.secondary_model = secondary_model
+        self.secondary_model_reasoning_effort = secondary_model_reasoning_effort
+        self.system_prompt = system_prompt
+        self.tools = tools
+        self.parsed_tools = [self._parse_tool(tool) for tool in tools]
+        self.allow_sub_agents = allow_sub_agents
+        self.max_turns = max_turns
+
+        self.raw_model_responses = []
+
+        if allow_sub_agents:
+            if not secondary_model:
+                print("No secondary model setup, sub agents will use the main model")
+                self.secondary_model = model
+            if not secondary_model_reasoning_effort:
+                print("No secondary model reasoning settings found, sub agents will use the main models reasoning settings")
+                self.secondary_model_reasoning_effort = reasoning_effort
+            self.parsed_tools.append(self._parse_tool(self._spawn_sub_minion))
+
+        self.parsed_tools.append(self._parse_tool(self._finish))
+
+        self.conversation = []
+        self.instructions = None
+
+    def _parse_tool(self, fn: Callable) -> Tool:
+        sig = inspect.signature(fn)
+        parsed_doc = docstring_parser.parse(inspect.getdoc(fn) or "")
+        param_descriptions = {p.arg_name: p.description for p in parsed_doc.params}
+
+        parameters = {}
+        for name, param in sig.parameters.items():
+            annotation = param.annotation
+            parameters[name] = {
+                "type": annotation.__name__ if annotation != inspect.Parameter.empty else "string",
+                "description": param_descriptions.get(name, "")
+            }
+
+        return Tool(
+            schema={
+                "tool_name": fn.__name__,
+                "description": parsed_doc.short_description or "",
+                "parameters": parameters,
+            },
+            fn=fn,
+        )
+
+    def _finish(self, final_response: str) -> str:
+        """Call this when you have completed the user's request.
+
+        Args:
+            final_response: The message shown directly to the user. Must be phrased as a direct answer or summary of the completed request.
+
+        Returns:
+            The final_response string, passed through unchanged.
+        """
+        return final_response
+
+    def _spawn_sub_minion(self, input: str, tool_list: list[str] = []) -> str:
+        """Spawn an independent sub-minion to complete a task and return its answer.
+
+        Use when a task is large, separable into parallel subtasks, or requires reading many files (eg. spawn 25 sub-minions each reading 4 files rather than reading 100 yourself — too much information can confuse you if read all at once).
+
+        The sub-minion has no conversation memory, so `input` must be fully self-contained: include all context, constraints, and instructions needed to complete the task from scratch.
+
+        Args:
+            input: Self-contained task description with all required context.
+            tool_list: Restrict to specific tools by passing the names to prevent sub minion to go rogue. If tool_list is not passed, sub minion will have all tools.
+
+        Returns:
+            The sub-minion's final answer.
+        """
+        if not tool_list:
+            tools = self.tools
+        else:
+            tools = [tool.fn for tool in self.parsed_tools if tool.schema["tool_name"] in tool_list]
+
+        sub_minion = Minion(
+            model=self.secondary_model,
+            reasoning_effort=self.secondary_model_reasoning_effort,
+            tools=tools,
+            allow_sub_agents=False,
+        )
+        print("=== CREATED A SUB MINION. RUNNING IT NOW ===")
+        sub_output = sub_minion(input)
+        print("=== SUB MINION HAS ENDED ===")
+        return sub_output
+
+    def _add_to_conversation(
+        self,
+        message: MinionOutput | str,
+        message_type: Literal["system", "user", "thought", "tool", "tool_output"] = None,
+    ):
+        if isinstance(message, MinionOutput):
+            self.conversation.append({"message_type": "thought", "content": message.next_thought})
+
+            for tool in message.next_tools:
+                args = ", ".join(f"{a.key}={a.value!r}" for a in tool.args)
+                self.conversation.append({
+                    "message_type": "tool",
+                    "content": f"Tool('{tool.tool_name}' called with Args({args}))",
+                })
+        else:
+            self.conversation.append({
+                "message_type": message_type or "tool_output",
+                "content": message,
+            })
+
+    def invoke_tool(self, tool_name: str, args: dict) -> str:
+        matches = [t for t in self.parsed_tools if t.schema["tool_name"] == tool_name]
+        if not matches:
+            raise ValueError(f"Tool '{tool_name}' not found")
+        return matches[0].fn(**args)
+
+    def __call__(self, input: str) -> str:
+        self._add_to_conversation(message=input, message_type="user")
+
+        tool_schemas = "\n".join([str(tool.schema) for tool in self.parsed_tools])
+        self.instructions = MINION_BASE_PROMPT.format(tool_schemas=tool_schemas)
+        if self.system_prompt:
+            self.instructions += f"\n\n## Special Instructions from User\n{self.system_prompt}"
+
+        client = get_client()
+
+        for _ in range(self.max_turns):
+            response = client.responses.parse(
+                model=self.model,
+                instructions=self.instructions,
+                reasoning={"effort": self.reasoning_effort, "summary": "detailed"},
+                input=str(self.conversation),
+                text_format=MinionOutput,
+            )
+            self.raw_model_responses.append(response)
+
+            output = response.output_parsed
+            print(output, end="\n\n")
+            self._add_to_conversation(message=output)
+
+            for tool in output.next_tools:
+                tool_output = self.invoke_tool(
+                    tool_name=tool.tool_name,
+                    args={a.key: a.value for a in tool.args},
+                )
+                self._add_to_conversation(message=tool_output)
+
+                if tool.tool_name == "_finish":
+                    return tool_output
+
+        print(f"OOPS!! {self.max_turns} turns were not enough")

minion_ai-0.1.0/minions/models.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from typing import Callable
+from pydantic import BaseModel
+
+
+@dataclass
+class Tool:
+    fn: Callable
+    schema: dict
+
+
+class ToolArg(BaseModel):
+    key: str
+    value: str
+
+
+class ToolCall(BaseModel):
+    model_config = {"extra": "forbid"}
+    tool_name: str
+    args: list[ToolArg]
+
+
+class MinionOutput(BaseModel):
+    model_config = {"extra": "forbid"}
+    next_thought: str
+    next_tools: list[ToolCall]
+
+    def __str__(self) -> str:
+        thought = f"Thought: {self.next_thought!r}"
+        tools = "\n".join([
+            f"Tool_{i+1}: {tool.tool_name!r}\nArgs: {', '.join(f'{a.key}={a.value!r}' for a in tool.args)}"
+            for i, tool in enumerate(self.next_tools)
+        ])
+        return "\n".join([thought, tools])

minion_ai-0.1.0/minions/tools.py

@@ -0,0 +1,49 @@
+import os
+
+
+def read_file(file_path: str, encoding: str = "utf-8") -> str:
+    """Reads the contents of a file and returns them as a string.
+
+    Args:
+        file_path: Path to the file to be read.
+        encoding: Character encoding to use when decoding the file.
+            Defaults to 'utf-8'.
+
+    Returns:
+        The full contents of the file as a string.
+
+    Raises:
+        FileNotFoundError: If the file does not exist at the given path.
+        PermissionError: If the process lacks read access to the file.
+        UnicodeDecodeError: If the file cannot be decoded with the given encoding.
+    """
+    with open(file_path, "r", encoding=encoding) as f:
+        return f.read()
+
+
+def list_files(directory: str) -> list[str]:
+    """Lists all file paths within a directory, excluding hidden and private entries.
+
+    Skips files and directories whose names start with '.' or '_'.
+
+    Args:
+        directory: Path to the directory to list files from.
+
+    Returns:
+        A list of absolute file paths found in the directory.
+
+    Raises:
+        FileNotFoundError: If the directory does not exist.
+        NotADirectoryError: If the given path is not a directory.
+    """
+    if not os.path.exists(directory):
+        raise FileNotFoundError(f"Directory not found: {directory}")
+    if not os.path.isdir(directory):
+        raise NotADirectoryError(f"Path is not a directory: {directory}")
+
+    return [
+        os.path.join(directory, entry)
+        for entry in os.listdir(directory)
+        if not entry.startswith((".", "_"))
+        and os.path.isfile(os.path.join(directory, entry))
+    ]

minion_ai-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "minion-ai"
+version = "0.1.0"
+description = "A simple agentic framework with observability and evals baked in"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "openai",
+    "pydantic",
+    "docstring-parser",
+    "litellm",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["minions"]
+
+[project.urls]
+Repository = "https://github.com/shriyansnaik/minions"
+

minion_ai-0.1.0/requirements.txt

@@ -0,0 +1,4 @@
+openai
+pydantic
+docstring-parser
+litellm

minion_ai-0.1.0/test.ipynb

@@ -0,0 +1,105 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "cc0fd4f3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from minions import Minion\n",
+    "import minions as mn\n",
+    "from minions.tools import read_file, list_files"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "b64ef4e1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "OPENAI_API_KEY = \"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\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "b7e044de",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mn.init(api_key=OPENAI_API_KEY)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "c01b53a3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "minion = Minion(\n",
+    "    model=\"gpt-5.1-chat-latest\",\n",
+    "    tools=[read_file, list_files]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "233d4568",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Thought: 'List directory to find requirements.txt.'\n",
+      "Tool_1: 'list_files'\n",
+      "Args: directory='.'\n",
+      "\n",
+      "Thought: 'No requirements file exists, so respond with that.'\n",
+      "Tool_1: '_finish'\n",
+      "Args: final_response='There is no requirements.txt file in the project directory.'\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "res = minion(\"can you check requirements.txt and tell me the requirements for the project\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dda435f9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "        "
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv (3.13.3.final.0)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}