lm-deluge 0.0.80__py3-none-any.whl → 0.0.82__py3-none-any.whl

lm_deluge/tool/prefab/__init__.py

@@ -0,0 +1,29 @@
+from .filesystem import (
+    FilesystemManager,
+    FilesystemParams,
+    InMemoryWorkspaceBackend,
+    WorkspaceBackend,
+)
+from .batch_tool import BatchTool
+from .tool_search import ToolSearchTool
+from .otc import ToolComposer
+from .sandbox import DaytonaSandbox, ModalSandbox
+from .subagents import SubAgentManager
+from .todos import TodoItem, TodoManager, TodoPriority, TodoStatus
+
+__all__ = [
+    "BatchTool",
+    "ToolSearchTool",
+    "ToolComposer",
+    "TodoItem",
+    "TodoManager",
+    "TodoPriority",
+    "TodoStatus",
+    "SubAgentManager",
+    "FilesystemManager",
+    "FilesystemParams",
+    "InMemoryWorkspaceBackend",
+    "WorkspaceBackend",
+    "ModalSandbox",
+    "DaytonaSandbox",
+]

lm_deluge/tool/prefab/batch_tool.py

@@ -0,0 +1,156 @@
+"""Batch tool for issuing multiple tool calls in a single roundtrip."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .. import Tool
+
+
+class BatchTool:
+    """Expose a single tool that runs multiple other tools in one request."""
+
+    def __init__(
+        self,
+        tools: list[Tool],
+        *,
+        batch_tool_name: str = "batch",
+        include_tools_in_prompt: bool = True,
+    ):
+        self.tools = tools
+        self.batch_tool_name = batch_tool_name
+        self.include_tools_in_prompt = include_tools_in_prompt
+        self._tool_index = {tool.name: tool for tool in tools}
+
+    def _arguments_schema(self, tool: Tool) -> dict[str, Any]:
+        """Build JSON Schema for a single tool's arguments."""
+        schema: dict[str, Any] = {
+            "type": "object",
+            "properties": tool.parameters or {},
+            "required": tool.required or [],
+        }
+        if tool.additionalProperties is not None:
+            schema["additionalProperties"] = tool.additionalProperties
+        return schema
+
+    def _build_definitions(self) -> dict[str, Any]:
+        """Create $defs entries for each wrapped tool."""
+        definitions: dict[str, Any] = {}
+        for tool in self.tools:
+            definition_name = f"{tool.name}_call"
+            definitions[definition_name] = {
+                "type": "object",
+                "description": tool.description or "",
+                "properties": {
+                    "tool": {"type": "string", "enum": [tool.name]},
+                    "arguments": self._arguments_schema(tool),
+                },
+                "required": ["tool", "arguments"],
+                "additionalProperties": False,
+            }
+        return definitions
+
+    def _build_parameters(self) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Create parameters and $defs for the batch tool."""
+        definitions = self._build_definitions()
+        if definitions:
+            items_schema: dict[str, Any] = {
+                "anyOf": [
+                    {"$ref": f"#/$defs/{name}"} for name in sorted(definitions.keys())
+                ]
+            }
+        else:
+            items_schema = {
+                "type": "object",
+                "properties": {
+                    "tool": {"type": "string"},
+                    "arguments": {"type": "object"},
+                },
+                "required": ["tool", "arguments"],
+                "additionalProperties": False,
+            }
+
+        parameters: dict[str, Any] = {
+            "calls": {
+                "type": "array",
+                "description": "List of tool calls to execute in order. "
+                "Each item selects a tool and provides its arguments.",
+                "items": items_schema,
+                "minItems": 1,
+            }
+        }
+
+        return parameters, definitions
+
+    def _tool_summary(self, tool: Tool) -> str:
+        """Render a short signature for the batch tool description."""
+        params = []
+        for name, schema in (tool.parameters or {}).items():
+            json_type = schema.get("type", "any")
+            params.append(f"{name}: {json_type}")
+        signature = f"{tool.name}({', '.join(params)})" if params else f"{tool.name}()"
+        desc = tool.description or "No description provided."
+        return f"- {signature}: {desc}"
+
+    def _build_description(self) -> str:
+        header = (
+            "Submit several tool calls at once to reduce roundtrips. "
+            "Provide `calls` as an array of objects with `tool` and `arguments`. "
+            "Calls run sequentially and results are returned in order."
+        )
+        if not self.include_tools_in_prompt:
+            return header
+
+        summaries = "\n".join(self._tool_summary(tool) for tool in self.tools)
+        return f"{header}\n\nAvailable tools:\n{summaries}"
+
+    async def _run(self, calls: list[dict[str, Any]]) -> str:
+        """Execute each requested tool and return ordered results as JSON."""
+        results: list[dict[str, Any]] = []
+
+        for call in calls:
+            tool_name = call.get("tool", "")
+
+            arguments = call.get("arguments") or {}
+            tool = self._tool_index.get(tool_name)
+            if tool is None:
+                results.append(
+                    {
+                        "tool": tool_name or "",
+                        "status": "error",
+                        "error": f"Unknown tool '{tool_name}'",
+                    }
+                )
+                continue
+
+            try:
+                output = await tool.acall(**arguments)
+                results.append({"tool": tool.name, "status": "ok", "result": output})
+            except Exception as exc:  # pragma: no cover - defensive
+                results.append(
+                    {
+                        "tool": tool.name,
+                        "status": "error",
+                        "error": f"{type(exc).__name__}: {exc}",
+                    }
+                )
+
+        return json.dumps(results)
+
+    def get_tool(self) -> Tool:
+        """Return the batch tool definition."""
+        parameters, definitions = self._build_parameters()
+
+        return Tool(
+            name=self.batch_tool_name,
+            description=self._build_description(),
+            run=self._run,
+            parameters=parameters,
+            required=["calls"],
+            definitions=definitions or None,
+        )
+
+    def get_tools(self) -> list[Tool]:
+        """Convenience helper to match other prefab managers."""
+        return [self.get_tool()]

lm_deluge/{llm_tools → tool/prefab}/filesystem.py

@@ -11,7 +11,7 @@ from typing import Any, Dict, Literal, Optional, Protocol
 
 from pydantic import BaseModel, Field
 
-from ..tool import Tool
+from .. import Tool
 
 FS_DESCRIPTION = """Interact with an isolated virtual filesystem that belongs to this session.
 

lm_deluge/tool/prefab/memory.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import json
+from collections import Counter
+from typing import Any, Sequence, TypeAlias
+
+import yaml
+from pydantic import BaseModel, Field
+from typing_extensions import TypedDict
+
+# from rapidfuzz import fuzz, process
+from .. import Tool
+
+MEMORY_DESCRIPTION = """Use this tool to search, read, and update a long-term "memory" that can be used across sessions, when previous messages are cleared. Whether and when to use memory depends on the situation—for complex tasks, it can store information about work so far, what needs to be done next, why you're doing what you're doing, etc. For personal conversations, it can be used to save "memories" that can be referenced later."""
+
+MEMORY_WRITE = """
+
+"""
+
+MEMORY_READ = """
+
+"""
+
+
+class MemoryItem(BaseModel):
+    """Structured representation of a single memory."""
+
+    id: int
+    description: str = Field(
+        description='Short description ("preview") of the memory (1 sentence)'
+    )
+    content: str = Field(
+        description="Full content of the memory. May use Markdown for formatting."
+    )
+
+
+class MemoryItemDict(TypedDict):
+    id: int
+    description: str
+    content: str
+
+
+MemoryLike: TypeAlias = MemoryItem | MemoryItemDict
+
+
+class MemoryManager:
+    """Stateful todo scratchpad that exposes read/write tools."""
+
+    def __init__(
+        self,
+        memories: Sequence[MemoryLike] | dict[int, MemoryLike] | None = None,
+        *,
+        write_tool_name: str = "memwrite",
+        read_tool_name: str = "memread",
+        search_tool_name: str = "memsearch",
+        update_tool_name: str = "memupdate",
+        delete_tool_name: str = "memdelete",
+    ):
+        self.write_tool_name = write_tool_name
+        self.read_tool_name = read_tool_name
+        self.search_tool_name = search_tool_name
+        self.update_tool_name = update_tool_name
+        self.delete_tool_name = delete_tool_name
+        self._memories: dict[int, MemoryItem] = {}
+        self._tools: list[Tool] | None = None
+
+        if memories:
+            if isinstance(memories, dict):
+                self._memories = {k: self._coerce(v) for k, v in memories.items()}
+            else:
+                coerced = [self._coerce(mem) for mem in memories]
+                self._memories = {x.id: x for x in coerced}
+
+    @classmethod
+    def from_file(
+        cls,
+        file: str,
+    ) -> MemoryManager:
+        # file should be a json file
+        with open(file) as f:
+            memories = json.load(f)
+        return cls(memories)
+
+    def _coerce(self, mem: MemoryLike) -> MemoryItem:
+        if isinstance(mem, MemoryItem):
+            return mem
+        if isinstance(mem, dict):
+            return MemoryItem(**mem)
+        raise TypeError("Memories must be MemoryItem instances or dicts")
+
+    def _serialize(self) -> list[dict[str, Any]]:
+        return [mem.model_dump() for mem in self._memories.values()]
+
+    def to_file(self, file: str):
+        mems = self._serialize()
+        with open(file, "w") as f:
+            f.write(json.dumps(mems))
+
+    @staticmethod
+    def _format_memory(mem: MemoryItem, include_content: bool = True) -> str:
+        dumped = mem.model_dump()
+        if not include_content:
+            dumped.pop("content")
+        return yaml.safe_dump(dumped)
+
+    # helpers
+    def _search(self, queries: list[str], limit: int = 5) -> list[MemoryItem]:
+        hits = Counter()
+        for q in queries:
+            keywords = q.lower().split()
+            for k in keywords:
+                for mem_id, mem in self._memories.items():
+                    if k in mem.description.lower() or k in mem.content.lower():
+                        hits[mem_id] += 1
+
+        top_k = hits.most_common(limit)
+
+        return self._read([hit[0] for hit in top_k if hit[1] > 0])
+
+    def _read(self, memory_ids: list[int]) -> list[MemoryItem]:
+        return [
+            mem
+            for mem_id in memory_ids
+            if mem_id is not None and (mem := self._memories.get(mem_id)) is not None
+        ]
+
+    def _add(self, description: str, content: str):
+        new_id = max(self._memories) + 1 if self._memories else 1
+        self._memories[new_id] = self._coerce(
+            {"id": new_id, "description": description, "content": content}
+        )
+        return new_id
+
+    def _update(self, mem_id: int, description: str, content: str):
+        self._memories[mem_id].description = description
+        self._memories[mem_id].content = content
+
+    def _delete(self, mem_id: int):
+        self._memories.pop(mem_id)
+
+    def get_tools(self) -> list[Tool]:
+        """Return Tool instances bound to this manager's state."""
+        if self._tools is not None:
+            return self._tools
+
+        def search_tool(queries: list[str], limit: int = 5) -> str:
+            """Search for memories using keyword search. Use as many queries as you want, the top results will be fused into one list. Search results include just id and description."""
+            mems = self._search(queries, limit=limit)
+            return "\n---\n".join(
+                [self._format_memory(mem, include_content=False) for mem in mems]
+            )
+
+        def read_tool(mem_ids: list[int]) -> str:
+            """Read the full contents of one or more memories."""
+            mems = self._read(mem_ids)
+            return "\n---\n".join(
+                [self._format_memory(mem, include_content=True) for mem in mems]
+            )
+
+        def add_tool(description: str, content: str):
+            """Add a new memory."""
+            return self._add(description, content)
+
+        def update_tool(mem_id: int, description: str, content: str) -> str:
+            """Update a memory by ID. Must provide content and description, even if only changing one of them."""
+            self._update(mem_id, description, content)
+
+            return f"Memory {mem_id} updated successfully."
+
+        def delete_tool(mem_id: int) -> str:
+            """Delete a memory by ID."""
+            self._delete(mem_id)
+            return f"Memory {mem_id} deleted successfully."
+
+        def _rename(tool: Tool, name: str) -> Tool:
+            if tool.name == name:
+                return tool
+            return tool.model_copy(update={"name": name})
+
+        self._tools = [
+            _rename(Tool.from_function(search_tool), self.search_tool_name),
+            _rename(Tool.from_function(read_tool), self.read_tool_name),
+            _rename(Tool.from_function(add_tool), self.write_tool_name),
+            _rename(Tool.from_function(update_tool), self.update_tool_name),
+            _rename(Tool.from_function(delete_tool), self.delete_tool_name),
+        ]
+        return self._tools
+
+
+__all__ = ["MemoryManager"]

lm_deluge/tool/prefab/otc/__init__.py

@@ -0,0 +1,165 @@
+"""
+Open Tool Composition (OTC) for lm-deluge.
+
+Allows LLMs to write Python code that orchestrates multiple tool calls,
+with only the final result entering the model's context.
+"""
+
+from lm_deluge.tool import Tool
+
+from .executor import OTCExecutor
+from .parse import OTCExecutionError, OTCSecurityError
+
+OTC_PROMPT = (
+    """The "compose" tool allows you to write code"""
+    "that orchestrates multiple tool calls. "
+    "The purpose is to compose tool calls to get a "
+    "final result, without wasting network roundtrips "
+    "or input tokens on intermediate results. Use this to:\n"
+    " - Call multiple tools and combine their results\n"
+    " - Filter or aggregate data from tool results\n"
+    " - Implement conditional logic based on tool outputs\n"
+    " - Process large amounts of data without polluting your context\n"
+    "The code you write is a restricted subset of Python that runs in a "
+    "sandboxed environment, with access to each of your tools as a function. "
+    "Only the final output (via print() or a 'result' variable) will be returned to you.\n\n"
+    "IMPORTANT:\n"
+    " - Tools are called synchronously (no await needed)\n"
+    " - Use print() or set a 'result' variable for output\n"
+    " - You can use `json` and standard builtins (list, dict, sum, len, etc.) without importing anything\n"
+    " - Imports, file I/O, and network access are disabled\n\n"
+    "<<AVAILABLE_TOOLS>>\n\n"
+    "Example:\n"
+    "```python\n"
+    "# Get team members and their expenses\n"
+    'team = get_team_members(department="engineering")\n'
+    'expenses = [get_expenses(user_id=m["id"], quarter="Q3") for m in team]\n\n'
+    "# Find who exceeded budget\n"
+    "over_budget = []\n"
+    "for member, exp in zip(team, expenses):\n"
+    '\ttotal = sum(e["amount"] for e in exp)\n'
+    "\tif total > 10000:\n"
+    '\t\tover_budget.append({"name": member["name"], "total": total})\n\n'
+    "print(json.dumps(over_budget))\n"
+    "```"
+)
+
+
+class ToolComposer:
+    """Manages OTC for a set of tools, exposing a compose tool.
+
+    Similar to SubAgentManager but for tool composition instead of subagents.
+
+    Example:
+        >>> composer = ToolComposer(tools=[search_tool, fetch_tool, calculator_tool])
+        >>> all_tools = composer.get_all_tools()  # Original tools + compose tool
+        >>> # LLM can now call compose() to orchestrate the other tools
+    """
+
+    def __init__(
+        self,
+        tools: list[Tool],
+        compose_tool_name: str = "compose",
+        include_tools_in_prompt: bool = False,
+    ):
+        """Initialize the ToolComposer.
+
+        Args:
+            tools: Tools available for composition
+            compose_tool_name: Name for the composition tool
+            include_tools_in_prompt: Whether to include tool signatures in compose description
+        """
+        self.tools = tools
+        self.compose_tool_name = compose_tool_name
+        self.include_tools_in_prompt = include_tools_in_prompt
+        self.executor = OTCExecutor(tools)
+
+    def _generate_tool_signatures(self) -> str:
+        """Generate Python-style signatures for available tools."""
+        signatures = []
+        for tool in self.tools:
+            params = []
+            for name, schema in (tool.parameters or {}).items():
+                param_type = schema.get("type", "any")
+                if param_type == "string":
+                    param_type = "str"
+                elif param_type == "integer":
+                    param_type = "int"
+                elif param_type == "number":
+                    param_type = "float"
+                elif param_type == "boolean":
+                    param_type = "bool"
+                elif param_type == "array":
+                    param_type = "list"
+                elif param_type == "object":
+                    param_type = "dict"
+
+                required = tool.required and name in tool.required
+                if required:
+                    params.append(f"{name}: {param_type}")
+                else:
+                    params.append(f"{name}: {param_type} = None")
+
+            sig = f"{tool.name}({', '.join(params)})"
+            desc = tool.description or "No description"
+            # Truncate long descriptions
+            if len(desc) > 500:
+                desc = desc[:497] + "..."
+            signatures.append(f"  {sig}\n    {desc}")
+
+        return "\n".join(signatures)
+
+    def _build_compose_description(self) -> str:
+        """Build the description for the compose tool."""
+        base_desc = OTC_PROMPT
+
+        if self.include_tools_in_prompt:
+            tool_sigs = self._generate_tool_signatures()
+            base_desc = base_desc.replace(
+                "<<AVAILABLE_TOOLS>>", f"# Available Tools\n{tool_sigs}"
+            )
+        else:
+            base_desc = base_desc.replace(
+                "<<AVAILABLE_TOOLS>>",
+                "# Available Tools\nYou can use any tool available to you, but you must use it as a Python function.",
+            )
+
+        return base_desc
+
+    async def _compose(self, code: str) -> str:
+        """Execute composition code."""
+        try:
+            return await self.executor.execute(code)
+        except OTCSecurityError as e:
+            return f"Security error: {e}"
+        except OTCExecutionError as e:
+            return f"Execution error: {e}"
+        except Exception as e:
+            return f"Unexpected error: {type(e).__name__}: {e}"
+
+    def get_compose_tool(self) -> Tool:
+        """Get the composition tool."""
+        return Tool(
+            name=self.compose_tool_name,
+            description=self._build_compose_description(),
+            run=self._compose,
+            parameters={
+                "code": {
+                    "type": "string",
+                    "description": "Python code to execute. Use available tools as functions.",
+                }
+            },
+            required=["code"],
+        )
+
+    def get_all_tools(self) -> list[Tool]:
+        """Get all tools including the compose tool.
+
+        Returns tools in order: [compose_tool, ...original_tools]
+        The compose tool is first to encourage the model to consider composition.
+        """
+        return [self.get_compose_tool()] + self.tools
+
+    def get_tools_without_compose(self) -> list[Tool]:
+        """Get just the original tools without the compose tool."""
+        return self.tools