autourgos-toolbox 3.0.0__tar.gz

autourgos_toolbox-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jitin Kumar Sengar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autourgos_toolbox-3.0.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: autourgos-toolbox
+Version: 3.0.0
+Summary: Dynamic lazy-loading toolbox middleware for Autourgos agents — keeps context windows clean by loading tools only when needed.
+Author-email: Jitin Kumar Sengar <devxjitin@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/devxjitin/autourgos-toolbox
+Project-URL: Repository, https://github.com/devxjitin/autourgos-toolbox
+Project-URL: Issues, https://github.com/devxjitin/autourgos-toolbox/issues
+Keywords: autourgos,agent,middleware,toolbox,llm,tools,lazy-loading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: autourgos-react-agent>=1.6.0
+Dynamic: license-file
+
+# autourgos-toolbox
+
+Dynamic lazy-loading toolbox middleware for [Autourgos](https://github.com/devxjitin) agents.
+
+Keeps the agent's context window clean by only showing toolbox names and descriptions upfront. The agent loads the tools it actually needs at runtime by calling `expose_toolbox(name)`.
+
+---
+
+## Why use this?
+
+Real-world agents often need dozens of tools — GitHub, databases, web search, file system, APIs. Dumping all of them into the prompt at once:
+
+- Wastes tokens on tools the agent will never use for a given task
+- Confuses the LLM with too many choices
+- Can hit the context window limit before the task even starts
+
+`ToolboxMiddleware` solves this by grouping tools into named **toolboxes** and only showing the catalog upfront. The agent picks what it needs and loads it on demand.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-toolbox
+```
+
+Depends on `autourgos-react-agent`. Works with any Autourgos agent.
+
+---
+
+## Quick Start
+
+```python
+from autourgos_toolbox import Toolbox, ToolboxMiddleware
+from autourgos_react_agent import ReactAgent
+
+# Define toolboxes
+web_box = Toolbox(
+    name="web",
+    description="Web search and page scraping tools.",
+    tools=[web_search, scrape_url],
+)
+db_box = Toolbox(
+    name="database",
+    description="SQL query tools for the production database.",
+    tools=[run_query, list_tables, describe_table],
+)
+
+# Attach middleware
+middleware = ToolboxMiddleware(toolboxes=[web_box, db_box])
+agent = ReactAgent(llm=my_llm, middleware=[middleware])
+
+result = agent.invoke("Find the latest Python release and log it to the database")
+print(result)
+```
+
+When used with a verbose `ReactAgent` (`ReactAgent(..., verbose=True)`), this
+middleware narrates its own actions into the same trace as the agent's
+Thought/Action/Observation output, for example:
+
+```
+[Toolbox] Exposed toolbox 'web' to agent.
+```
+
+The agent sees this in its prompt at the start:
+
+```
+## Dynamic Toolboxes
+Available Toolboxes:
+- **web**: Web search and page scraping tools.
+- **database**: SQL query tools for the production database.
+```
+
+When it needs the web tools, it calls:
+```json
+{"action": "expose_toolbox", "action_input": {"toolbox_name": "web"}}
+```
+
+And immediately all web tools are registered and their schemas injected into the prompt.
+
+---
+
+## How it works
+
+1. **on_agent_start** — middleware injects `expose_toolbox` and `expose_tool` meta-tools plus a toolbox catalog into the agent's system prompt. No actual tools are loaded yet.
+2. **Agent calls expose_toolbox** — all tools in that toolbox are registered on the agent and their schemas are appended to the prompt.
+3. **Agent uses the tools** — now fully loaded and callable.
+4. **on_agent_end / on_agent_error** — agent is fully restored to its original state (tools + prompt) so the next run starts clean.
+
+---
+
+## Define toolboxes
+
+### As a list of Toolbox objects
+
+```python
+from autourgos_toolbox import Toolbox, ToolboxMiddleware
+
+github_box = Toolbox(
+    name="github",
+    description="Tools for reading and writing GitHub issues and PRs.",
+    tools=[search_issues, create_pr, list_repos],
+)
+
+middleware = ToolboxMiddleware(toolboxes=[github_box])
+```
+
+### As a dict
+
+```python
+middleware = ToolboxMiddleware(toolboxes={
+    "github": {
+        "description": "Tools for reading and writing GitHub issues and PRs.",
+        "tools": [search_issues, create_pr, list_repos],
+    },
+    "slack": {
+        "description": "Tools for sending and reading Slack messages.",
+        "tools": [send_message, read_channel],
+    },
+})
+```
+
+### Add toolboxes dynamically
+
+```python
+middleware = ToolboxMiddleware()
+middleware.add_toolbox("github", "GitHub tools.", [search_issues, create_pr])
+middleware.add_toolbox("slack", "Slack tools.", [send_message, read_channel])
+```
+
+---
+
+## Using StructuredTool
+
+Tools can be plain callables or `StructuredTool` instances. `StructuredTool` auto-infers the JSON schema from type annotations and docstrings:
+
+```python
+from autourgos_toolbox import StructuredTool
+
+def search_issues(query: str, repo: str) -> str:
+    """Search GitHub issues.
+
+    Args:
+        query: Search keywords.
+        repo: Repository name in owner/repo format.
+    """
+    ...
+
+tool = StructuredTool.from_function(search_issues)
+```
+
+---
+
+## Combine with other middleware
+
+```python
+from autourgos_toolbox import ToolboxMiddleware, Toolbox
+from autourgos_history import AgentHistoryMiddleware
+from autourgos_summarizer import AutoSummarizeMiddleware
+
+middleware = [
+    ToolboxMiddleware(toolboxes=[web_box, db_box]),
+    AutoSummarizeMiddleware(summarize_every=5),
+    AgentHistoryMiddleware(),
+]
+agent = ReactAgent(llm=my_llm, middleware=middleware)
+```
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Any Autourgos agent with `add_tools()`, `agent.tools`, and `agent.system_prompt` / `agent.prompt_template`
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_toolbox-3.0.0/README.md

@@ -0,0 +1,180 @@
+# autourgos-toolbox
+
+Dynamic lazy-loading toolbox middleware for [Autourgos](https://github.com/devxjitin) agents.
+
+Keeps the agent's context window clean by only showing toolbox names and descriptions upfront. The agent loads the tools it actually needs at runtime by calling `expose_toolbox(name)`.
+
+---
+
+## Why use this?
+
+Real-world agents often need dozens of tools — GitHub, databases, web search, file system, APIs. Dumping all of them into the prompt at once:
+
+- Wastes tokens on tools the agent will never use for a given task
+- Confuses the LLM with too many choices
+- Can hit the context window limit before the task even starts
+
+`ToolboxMiddleware` solves this by grouping tools into named **toolboxes** and only showing the catalog upfront. The agent picks what it needs and loads it on demand.
+
+---
+
+## Install
+
+```bash
+pip install autourgos-toolbox
+```
+
+Depends on `autourgos-react-agent`. Works with any Autourgos agent.
+
+---
+
+## Quick Start
+
+```python
+from autourgos_toolbox import Toolbox, ToolboxMiddleware
+from autourgos_react_agent import ReactAgent
+
+# Define toolboxes
+web_box = Toolbox(
+    name="web",
+    description="Web search and page scraping tools.",
+    tools=[web_search, scrape_url],
+)
+db_box = Toolbox(
+    name="database",
+    description="SQL query tools for the production database.",
+    tools=[run_query, list_tables, describe_table],
+)
+
+# Attach middleware
+middleware = ToolboxMiddleware(toolboxes=[web_box, db_box])
+agent = ReactAgent(llm=my_llm, middleware=[middleware])
+
+result = agent.invoke("Find the latest Python release and log it to the database")
+print(result)
+```
+
+When used with a verbose `ReactAgent` (`ReactAgent(..., verbose=True)`), this
+middleware narrates its own actions into the same trace as the agent's
+Thought/Action/Observation output, for example:
+
+```
+[Toolbox] Exposed toolbox 'web' to agent.
+```
+
+The agent sees this in its prompt at the start:
+
+```
+## Dynamic Toolboxes
+Available Toolboxes:
+- **web**: Web search and page scraping tools.
+- **database**: SQL query tools for the production database.
+```
+
+When it needs the web tools, it calls:
+```json
+{"action": "expose_toolbox", "action_input": {"toolbox_name": "web"}}
+```
+
+And immediately all web tools are registered and their schemas injected into the prompt.
+
+---
+
+## How it works
+
+1. **on_agent_start** — middleware injects `expose_toolbox` and `expose_tool` meta-tools plus a toolbox catalog into the agent's system prompt. No actual tools are loaded yet.
+2. **Agent calls expose_toolbox** — all tools in that toolbox are registered on the agent and their schemas are appended to the prompt.
+3. **Agent uses the tools** — now fully loaded and callable.
+4. **on_agent_end / on_agent_error** — agent is fully restored to its original state (tools + prompt) so the next run starts clean.
+
+---
+
+## Define toolboxes
+
+### As a list of Toolbox objects
+
+```python
+from autourgos_toolbox import Toolbox, ToolboxMiddleware
+
+github_box = Toolbox(
+    name="github",
+    description="Tools for reading and writing GitHub issues and PRs.",
+    tools=[search_issues, create_pr, list_repos],
+)
+
+middleware = ToolboxMiddleware(toolboxes=[github_box])
+```
+
+### As a dict
+
+```python
+middleware = ToolboxMiddleware(toolboxes={
+    "github": {
+        "description": "Tools for reading and writing GitHub issues and PRs.",
+        "tools": [search_issues, create_pr, list_repos],
+    },
+    "slack": {
+        "description": "Tools for sending and reading Slack messages.",
+        "tools": [send_message, read_channel],
+    },
+})
+```
+
+### Add toolboxes dynamically
+
+```python
+middleware = ToolboxMiddleware()
+middleware.add_toolbox("github", "GitHub tools.", [search_issues, create_pr])
+middleware.add_toolbox("slack", "Slack tools.", [send_message, read_channel])
+```
+
+---
+
+## Using StructuredTool
+
+Tools can be plain callables or `StructuredTool` instances. `StructuredTool` auto-infers the JSON schema from type annotations and docstrings:
+
+```python
+from autourgos_toolbox import StructuredTool
+
+def search_issues(query: str, repo: str) -> str:
+    """Search GitHub issues.
+
+    Args:
+        query: Search keywords.
+        repo: Repository name in owner/repo format.
+    """
+    ...
+
+tool = StructuredTool.from_function(search_issues)
+```
+
+---
+
+## Combine with other middleware
+
+```python
+from autourgos_toolbox import ToolboxMiddleware, Toolbox
+from autourgos_history import AgentHistoryMiddleware
+from autourgos_summarizer import AutoSummarizeMiddleware
+
+middleware = [
+    ToolboxMiddleware(toolboxes=[web_box, db_box]),
+    AutoSummarizeMiddleware(summarize_every=5),
+    AgentHistoryMiddleware(),
+]
+agent = ReactAgent(llm=my_llm, middleware=middleware)
+```
+
+---
+
+## Requirements
+
+- Python 3.9+
+- Any Autourgos agent with `add_tools()`, `agent.tools`, and `agent.system_prompt` / `agent.prompt_template`
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

autourgos_toolbox-3.0.0/autourgos_toolbox/__init__.py

@@ -0,0 +1,34 @@
+"""
+autourgos-toolbox — Dynamic lazy-loading toolbox middleware for Autourgos agents.
+
+Keeps context windows clean by only showing toolbox names upfront.
+The agent calls `expose_toolbox(name)` at runtime to load the tools it needs.
+
+Quick start::
+
+    from autourgos_toolbox import Toolbox, ToolboxMiddleware
+
+    web_box = Toolbox("web", "Web search tools.", [search, scrape])
+    db_box  = Toolbox("database", "SQL tools.", [run_query, list_tables])
+
+    middleware = ToolboxMiddleware(toolboxes=[web_box, db_box])
+    agent = ReactAgent(llm=my_llm, middleware=[middleware])
+"""
+
+from .base import CallbackHandler, StructuredTool, build_tool_list, register_tool
+from .middleware import Toolbox, ToolboxMiddleware
+
+try:
+    from importlib.metadata import version as _meta_version
+    __version__ = _meta_version("autourgos-toolbox")
+except Exception:
+    __version__ = "2.1.0"
+
+__all__ = [
+    "Toolbox",
+    "ToolboxMiddleware",
+    "StructuredTool",
+    "CallbackHandler",
+    "build_tool_list",
+    "register_tool",
+]

autourgos_toolbox-3.0.0/autourgos_toolbox/base.py

@@ -0,0 +1,130 @@
+"""
+base.py — Base classes for autourgos-toolbox.
+
+CallbackHandler is re-exported from autourgos-react-agent, the package that
+owns this interface, to avoid divergent duplicate copies. StructuredTool,
+register_tool, and build_tool_list are toolbox-specific (they operate on a
+dict-based tool registry, unlike react-agent's own build_tool_list which
+operates on a plain list of tool dicts) and remain defined locally here.
+"""
+from __future__ import annotations
+
+import inspect
+import json
+from typing import Any, Callable, Dict, List, Optional
+
+from autourgos_react_agent import CallbackHandler
+
+__all__ = ["CallbackHandler", "StructuredTool", "register_tool", "build_tool_list"]
+
+
+# ── StructuredTool ─────────────────────────────────────────────────────────────
+
+class StructuredTool:
+    """
+    A callable tool with a name, description, and auto-inferred JSON schema
+    built from the function's type annotations and docstring.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        func: Callable,
+        args_schema: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.name        = name
+        self.description = description
+        self.func        = func
+        self.args_schema = args_schema or self._infer_schema(func)
+
+    @classmethod
+    def from_function(
+        cls,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> "StructuredTool":
+        tool_name = name or func.__name__
+        tool_desc = description or (inspect.getdoc(func) or "")
+        return cls(name=tool_name, description=tool_desc, func=func)
+
+    @staticmethod
+    def _infer_schema(func: Callable) -> Dict[str, Any]:
+        sig    = inspect.signature(func)
+        hints  = {}
+        try:
+            hints = func.__annotations__
+        except Exception:
+            pass
+
+        _PY_TO_JSON = {
+            "str": "string", "int": "integer", "float": "number",
+            "bool": "boolean", "list": "array", "dict": "object",
+        }
+
+        properties: Dict[str, Any] = {}
+        required:   List[str]      = []
+
+        for param_name, param in sig.parameters.items():
+            if param_name in ("self", "return"):
+                continue
+            hint = hints.get(param_name)
+            type_name = "string"
+            if hint is not None:
+                raw = getattr(hint, "__name__", str(hint))
+                type_name = _PY_TO_JSON.get(raw, "string")
+
+            # parse inline description from docstring "param: description" lines
+            doc   = inspect.getdoc(func) or ""
+            pdesc = ""
+            for line in doc.splitlines():
+                line = line.strip()
+                if line.startswith(f"{param_name}:") or line.startswith(f"{param_name} :"):
+                    pdesc = line.split(":", 1)[-1].strip()
+                    break
+
+            properties[param_name] = {"type": type_name, "description": pdesc}
+            if param.default is inspect.Parameter.empty:
+                required.append(param_name)
+
+        return {
+            "type": "object",
+            "properties": properties,
+            "required": required,
+        }
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.func(*args, **kwargs)
+
+
+# ── runtime helpers ────────────────────────────────────────────────────────────
+
+def register_tool(registry: Dict[str, Dict[str, Any]], tool: Any) -> None:
+    """Register a tool (StructuredTool or plain callable) into a dict registry."""
+    if isinstance(tool, StructuredTool):
+        registry[tool.name] = {
+            "description": tool.description,
+            "parameters":  tool.args_schema,
+            "func":        tool.func,
+        }
+    elif callable(tool):
+        name = getattr(tool, "__name__", str(tool))
+        doc  = inspect.getdoc(tool) or ""
+        registry[name] = {
+            "description": doc,
+            "parameters":  StructuredTool._infer_schema(tool),
+            "func":        tool,
+        }
+    elif isinstance(tool, dict) and "name" in tool:
+        registry[tool["name"]] = tool
+
+
+def build_tool_list(tools: Dict[str, Dict[str, Any]]) -> str:
+    """Format a tool registry into a prompt-ready string."""
+    lines: List[str] = []
+    for name, info in tools.items():
+        desc   = info.get("description", "")
+        params = info.get("parameters", {})
+        lines.append(f"Tool: {name}\nDescription: {desc}\nParameters: {json.dumps(params, indent=2)}\n")
+    return "\n".join(lines)