rossum-agent 1.0.0rc0__py3-none-any.whl

rossum_agent/tools/dynamic_tools.py

@@ -0,0 +1,365 @@
+"""Dynamic tool loading for the Rossum Agent.
+
+Provides functionality to load MCP tool categories on-demand to reduce context usage.
+Catalog metadata is fetched from MCP server (single source of truth) and cached.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from rossum_agent.rossum_mcp_integration import mcp_tools_to_anthropic_format
+from rossum_agent.tools.core import get_mcp_connection, get_mcp_event_loop
+
+if TYPE_CHECKING:
+    from anthropic.types import ToolParam
+    from mcp.types import Tool as MCPTool
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CatalogData:
+    """Cached catalog data from MCP server."""
+
+    catalog: dict[str, set[str]] = field(default_factory=dict)
+    keywords: dict[str, list[str]] = field(default_factory=dict)
+    destructive_tools: set[str] = field(default_factory=set)
+
+
+# Cached catalog from MCP (fetched once per process)
+_catalog_cache: CatalogData | None = None
+
+# Discovery tool that's always loaded
+DISCOVERY_TOOL_NAME = "list_tool_categories"
+
+
+@dataclass
+class DynamicToolsState:
+    """Mutable state container for dynamically loaded tools.
+
+    Stored on RossumAgent instance and passed to functions that need to modify
+    tool state. Using a class allows modifications in thread pool executors to
+    be visible in the main context (unlike context variables which are copied).
+    """
+
+    loaded_categories: set[str] = field(default_factory=set)
+    tools: list[ToolParam] = field(default_factory=list)
+
+    def reset(self) -> None:
+        """Reset state for a new conversation."""
+        self.loaded_categories.clear()
+        self.tools.clear()
+
+
+# Global state for backwards compatibility (used when agent instance not available)
+_global_state: DynamicToolsState | None = None
+
+
+def get_global_state() -> DynamicToolsState:
+    """Get or create global state for backwards compatibility."""
+    global _global_state
+    if _global_state is None:
+        _global_state = DynamicToolsState()
+    return _global_state
+
+
+def reset_dynamic_tools() -> None:
+    """Reset dynamic tool state for a new conversation (global state)."""
+    get_global_state().reset()
+
+
+def get_loaded_categories() -> set[str]:
+    """Get the set of currently loaded categories (global state)."""
+    return get_global_state().loaded_categories
+
+
+def get_dynamic_tools() -> list[ToolParam]:
+    """Get the list of dynamically loaded tools (global state)."""
+    return get_global_state().tools
+
+
+def _fetch_catalog_from_mcp() -> CatalogData:
+    """Fetch tool catalog from MCP server."""
+    global _catalog_cache
+
+    if _catalog_cache is not None:
+        return _catalog_cache
+
+    mcp_connection = get_mcp_connection()
+    loop = get_mcp_event_loop()
+
+    if mcp_connection is None or loop is None:
+        logger.warning("MCP connection not available, returning empty catalog")
+        return CatalogData()
+
+    # Call list_tool_categories MCP tool to get catalog
+    try:
+        result = asyncio.run_coroutine_threadsafe(mcp_connection.call_tool("list_tool_categories", {}), loop).result(
+            timeout=10
+        )
+
+        # Handle various result formats from MCP
+        # 1. String (JSON) - parse it
+        if isinstance(result, str):
+            result = json.loads(result)
+
+        # 2. FastMCP wraps list returns in {"result": [...]}
+        if isinstance(result, dict) and "result" in result:
+            result = result["result"]
+
+        # 3. The unwrapped result might also be a JSON string
+        if isinstance(result, str):
+            result = json.loads(result)
+
+        catalog: dict[str, set[str]] = {}
+        keywords: dict[str, list[str]] = {}
+        destructive_tools: set[str] = set()
+
+        for category in result:
+            name = category["name"]
+            catalog[name] = {tool["name"] for tool in category["tools"]}
+            keywords[name] = category.get("keywords", [])
+            for tool in category["tools"]:
+                if tool.get("destructive", False):
+                    destructive_tools.add(tool["name"])
+
+        _catalog_cache = CatalogData(catalog=catalog, keywords=keywords, destructive_tools=destructive_tools)
+        logger.info(f"Fetched catalog with {len(catalog)} categories from MCP")
+        return _catalog_cache
+
+    except Exception as e:
+        logger.error(f"Failed to fetch catalog from MCP: {e}")
+        return CatalogData()
+
+
+def get_category_tool_names() -> dict[str, set[str]]:
+    """Get mapping of category names to tool names (fetched from MCP)."""
+    return _fetch_catalog_from_mcp().catalog
+
+
+def get_category_keywords() -> dict[str, list[str]]:
+    """Get mapping of category names to keywords (fetched from MCP)."""
+    return _fetch_catalog_from_mcp().keywords
+
+
+def get_destructive_tools() -> set[str]:
+    """Get set of destructive tool names (fetched from MCP)."""
+    return _fetch_catalog_from_mcp().destructive_tools
+
+
+def suggest_categories_for_request(request_text: str) -> list[str]:
+    """Suggest tool categories based on keywords in the request.
+
+    Uses word boundary matching to avoid false positives (e.g., "credit" matching "edit").
+    """
+    keywords = get_category_keywords()
+    if not keywords:
+        return []
+
+    request_lower = request_text.lower()
+    suggestions: list[str] = []
+
+    for category, category_keywords in keywords.items():
+        for keyword in category_keywords:
+            pattern = rf"\b{re.escape(keyword)}\b"
+            if re.search(pattern, request_lower):
+                suggestions.append(category)
+                break
+
+    return suggestions
+
+
+def _filter_mcp_tools_by_names(mcp_tools: list[MCPTool], tool_names: set[str]) -> list[MCPTool]:
+    """Filter MCP tools to only those with names in the given set."""
+    return [tool for tool in mcp_tools if tool.name in tool_names]
+
+
+def _filter_discovery_tools(mcp_tools: list[MCPTool]) -> list[MCPTool]:
+    """Filter MCP tools to only discovery tools."""
+    return [tool for tool in mcp_tools if tool.name == DISCOVERY_TOOL_NAME]
+
+
+def _load_categories_impl(
+    categories: list[str],
+    state: DynamicToolsState | None = None,
+    exclude_destructive: bool = True,
+) -> str:
+    """Load multiple tool categories at once.
+
+    Args:
+        categories: List of category names to load
+        state: Optional state container. Uses global state if not provided.
+        exclude_destructive: If True (default), skip destructive tools (delete operations).
+            Destructive tools can only be loaded via explicit load_tool call.
+
+    Returns:
+        Message indicating which tools were loaded or an error message.
+    """
+    if state is None:
+        state = get_global_state()
+
+    catalog = get_category_tool_names()
+    if not catalog:
+        return "Error: Could not fetch tool catalog from MCP"
+
+    valid_categories = set(catalog.keys())
+    invalid = [c for c in categories if c not in valid_categories]
+    if invalid:
+        return f"Error: Unknown categories {invalid}. Valid: {sorted(valid_categories)}"
+
+    to_load = [c for c in categories if c not in state.loaded_categories]
+
+    if not to_load:
+        return f"Categories already loaded: {categories}"
+
+    mcp_connection, loop = get_mcp_connection(), get_mcp_event_loop()
+    if mcp_connection is None or loop is None:
+        return "Error: MCP connection not available"
+
+    # Collect all tool names to load
+    tool_names_to_load: set[str] = set()
+    for category in to_load:
+        tool_names_to_load.update(catalog[category])
+
+    # Exclude destructive tools if requested (e.g., during automatic pre-loading)
+    if exclude_destructive:
+        destructive_tools = get_destructive_tools()
+        tool_names_to_load -= destructive_tools
+
+    # Get all MCP tools and filter
+    mcp_tools = asyncio.run_coroutine_threadsafe(mcp_connection.get_tools(), loop).result()
+    tools_to_add = _filter_mcp_tools_by_names(mcp_tools, tool_names_to_load)
+
+    if not tools_to_add:
+        return f"No tools found for categories: {to_load}"
+
+    # Convert to Anthropic format and add to dynamic tools
+    anthropic_tools = mcp_tools_to_anthropic_format(tools_to_add)
+    state.tools.extend(anthropic_tools)
+
+    # Mark categories as loaded
+    for category in to_load:
+        state.loaded_categories.add(category)
+
+    tool_names = [t.name for t in tools_to_add]
+    logger.info(f"Loaded {len(tool_names)} tools from categories {to_load}: {tool_names}")
+
+    return f"Loaded {len(tool_names)} tools from {to_load}: {', '.join(sorted(tool_names))}"
+
+
+def preload_categories_for_request(request_text: str) -> str | None:
+    """Pre-load tool categories based on keywords in the user's request.
+
+    Called automatically on first user message to reduce tool discovery friction.
+    Destructive tools (delete operations) are excluded - they can only be loaded
+    via explicit load_tool call.
+
+    Returns:
+        Message about loaded categories, or None if nothing was loaded.
+    """
+    suggestions = suggest_categories_for_request(request_text)
+    if not suggestions:
+        return None
+
+    result = _load_categories_impl(suggestions)
+    if result.startswith("Error") or result.startswith("Categories already"):
+        return None
+
+    logger.info(f"Pre-loaded categories based on request keywords: {suggestions}")
+    return result
+
+
+def get_load_tool_category_definition() -> ToolParam:
+    """Get the tool definition for load_tool_category."""
+    return {
+        "name": "load_tool_category",
+        "description": (
+            "Load MCP tools from one or more categories. Once loaded, the tools become "
+            "available for use. Use list_tool_categories first to see available categories.\n"
+            "Categories: annotations, queues, schemas, engines, hooks, email_templates, "
+            "document_relations, relations, rules, users, workspaces"
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "categories": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Category names to load (e.g., ['queues', 'schemas'])",
+                }
+            },
+            "required": ["categories"],
+        },
+    }
+
+
+def load_tool_category(categories: list[str]) -> str:
+    """Load MCP tools from specified categories."""
+    return _load_categories_impl(categories)
+
+
+def get_load_tool_definition() -> ToolParam:
+    """Get the tool definition for load_tool."""
+    return {
+        "name": "load_tool",
+        "description": (
+            "Load specific MCP tools by name. Use this to load destructive tools "
+            "(delete operations) which are excluded from load_tool_category. "
+            "Example: load_tool(['delete_hook']) to enable hook deletion."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "tool_names": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Tool names to load (e.g., ['delete_hook', 'delete_queue'])",
+                }
+            },
+            "required": ["tool_names"],
+        },
+    }
+
+
+def load_tool(tool_names: list[str], state: DynamicToolsState | None = None) -> str:
+    """Load specific MCP tools by name.
+
+    Use this to load destructive tools (delete operations) that are excluded
+    from category loading for safety.
+    """
+    if state is None:
+        state = get_global_state()
+
+    mcp_connection, loop = get_mcp_connection(), get_mcp_event_loop()
+    if mcp_connection is None or loop is None:
+        return "Error: MCP connection not available"
+
+    # Get all MCP tools
+    mcp_tools = asyncio.run_coroutine_threadsafe(mcp_connection.get_tools(), loop).result()
+    available_tool_names = {t.name for t in mcp_tools}
+
+    # Validate requested tool names
+    invalid = [name for name in tool_names if name not in available_tool_names]
+    if invalid:
+        return f"Error: Unknown tools {invalid}"
+
+    # Filter to already-loaded tools
+    already_loaded = {t["name"] for t in state.tools}
+    to_load = [name for name in tool_names if name not in already_loaded]
+
+    if not to_load:
+        return f"Tools already loaded: {tool_names}"
+
+    # Filter MCP tools and convert to Anthropic format
+    tools_to_add = _filter_mcp_tools_by_names(mcp_tools, set(to_load))
+    anthropic_tools = mcp_tools_to_anthropic_format(tools_to_add)
+    state.tools.extend(anthropic_tools)
+
+    logger.info(f"Loaded {len(to_load)} tools by name: {to_load}")
+    return f"Loaded tools: {', '.join(sorted(to_load))}"

rossum_agent/tools/file_tools.py

@@ -0,0 +1,62 @@
+"""File system tools for the Rossum Agent.
+
+We use these tools to write into a specific output location.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from anthropic import beta_tool
+
+from rossum_agent.tools.core import get_output_dir
+
+logger = logging.getLogger(__name__)
+
+
+@beta_tool
+def write_file(filename: str, content: str | dict | list) -> str:
+    """Write content to a file in the agent's output directory.
+
+    Use this tool to save analysis results, export data, or create reports.
+    Files are saved to a session-specific directory that can be shared with the user.
+
+    Args:
+        filename: The name of the file to write (e.g., 'report.md', 'analysis.json').
+        content: The content to write to the file. Can be a string, dict, or list.
+
+    Returns:
+        JSON with status, message, and file path.
+    """
+    if not filename or not filename.strip():
+        return json.dumps({"status": "error", "message": "Error: filename is required"})
+
+    if not content:
+        return json.dumps({"status": "error", "message": "Error: content is required"})
+
+    # Convert dict/list to JSON string
+    if isinstance(content, dict | list):
+        content = json.dumps(content, indent=2, ensure_ascii=False)
+
+    try:
+        output_dir = get_output_dir()
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        safe_filename = Path(filename).name
+        file_path = output_dir / safe_filename
+
+        file_path.write_text(content, encoding="utf-8")
+
+        logger.info(f"write_file: wrote {len(content)} chars to {file_path}")
+        return json.dumps(
+            {
+                "status": "success",
+                "message": f"Successfully wrote {len(content)} characters to {safe_filename}",
+                "path": str(file_path),
+            }
+        )
+    except Exception as e:
+        logger.exception("Error in write_file")
+        return json.dumps({"status": "error", "message": f"Error writing file: {e}"})

rossum_agent/tools/formula.py

@@ -0,0 +1,187 @@
+"""Formula field suggestion tool for the Rossum Agent.
+
+This module provides a tool to get formula suggestions from Rossum's internal API
+for formula fields based on natural language descriptions.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+import re
+
+import httpx
+from anthropic import beta_tool
+
+from rossum_agent.tools.core import require_rossum_credentials
+
+logger = logging.getLogger(__name__)
+
+_SUGGEST_FORMULA_TIMEOUT = 60
+
+
+def _build_suggest_formula_url(api_base_url: str) -> str:
+    """Build the suggest_formula endpoint URL.
+
+    Uses the base URL directly (e.g., https://elis.rossum.ai/api/v1)
+    and appends the internal endpoint path.
+    """
+    return f"{api_base_url.rstrip('/')}/internal/schemas/suggest_formula"
+
+
+def _fetch_schema_content(api_base_url: str, token: str, schema_id: int) -> list[dict]:
+    """Fetch schema content from Rossum API."""
+    url = f"{api_base_url.rstrip('/')}/schemas/{schema_id}"
+    with httpx.Client(timeout=30) as client:
+        response = client.get(url, headers={"Authorization": f"Bearer {token}"})
+        response.raise_for_status()
+        return response.json()["content"]
+
+
+def _create_formula_field_definition(label: str, field_schema_id: str | None = None) -> dict:
+    """Create a properly structured formula field definition."""
+    if not field_schema_id:
+        field_schema_id = label.lower().replace(" ", "_")
+    return {
+        "id": field_schema_id,
+        "label": label,
+        "type": "string",
+        "category": "datapoint",
+        "can_export": True,
+        "constraints": {"required": False},
+        "disable_prediction": False,
+        "formula": "",
+        "hidden": False,
+        "rir_field_names": [],
+        "score_threshold": 0,
+        "suggest": True,
+        "ui_configuration": {"type": "formula", "edit": "disabled"},
+    }
+
+
+def _find_field_in_schema(nodes: list[dict], field_id: str) -> bool:
+    """Recursively search for a field ID in schema content."""
+    for node in nodes:
+        if node.get("id") == field_id:
+            return True
+        if "children" in node:
+            children = node["children"]
+            if isinstance(children, list) and _find_field_in_schema(children, field_id):
+                return True
+            if isinstance(children, dict) and _find_field_in_schema([children], field_id):
+                return True
+    return False
+
+
+def _inject_formula_field(
+    schema_content: list[dict], label: str, section_id: str, field_schema_id: str | None = None
+) -> list[dict]:
+    """Inject a formula field into the specified section of schema_content.
+
+    The suggest_formula API requires the target field to exist in schema_content.
+    """
+    if not field_schema_id:
+        field_schema_id = label.lower().replace(" ", "_")
+
+    if _find_field_in_schema(schema_content, field_schema_id):
+        return schema_content
+
+    modified = copy.deepcopy(schema_content)
+    formula_field = _create_formula_field_definition(label, field_schema_id)
+
+    for section in modified:
+        if section.get("id") == section_id and section.get("category") == "section":
+            section.setdefault("children", []).append(formula_field)
+            return modified
+
+    if modified and modified[0].get("category") == "section":
+        modified[0].setdefault("children", []).append(formula_field)
+    else:
+        modified.append(formula_field)
+
+    return modified
+
+
+@beta_tool
+def suggest_formula_field(
+    label: str, hint: str, schema_id: int, section_id: str, field_schema_id: str | None = None
+) -> str:
+    """Get AI-generated formula suggestions for a new formula field.
+
+    Args:
+        label: Display label for the field (e.g., 'Net Terms').
+        hint: Natural language description of the formula logic.
+        schema_id: The numeric schema ID (e.g., 9389721). Get this from get_schema or list_queues.
+        section_id: Section ID where the field belongs. Ask the user if not specified.
+        field_schema_id: Optional ID for the formula field. Defaults to label.lower().replace(" ", "_").
+
+    Returns:
+        JSON with formula suggestion and field_definition for use with patch_schema.
+    """
+    field_schema_id = field_schema_id or label.lower().replace(" ", "_")
+    logger.info(f"suggest_formula_field: {field_schema_id=}, {schema_id=}, {section_id=}, hint={hint[:100]}...")
+
+    try:
+        api_base_url, token = require_rossum_credentials()
+        url = _build_suggest_formula_url(api_base_url)
+
+        schema_content = _fetch_schema_content(api_base_url, token, schema_id)
+        enriched_schema = _inject_formula_field(schema_content, label, section_id, field_schema_id)
+
+        payload = {"field_schema_id": field_schema_id, "hint": hint, "schema_content": enriched_schema}
+
+        logger.debug(f"Calling suggest_formula API: {url}")
+        logger.debug(f"suggest_formula payload: {json.dumps(payload, indent=2)}")
+
+        with httpx.Client(timeout=_SUGGEST_FORMULA_TIMEOUT) as client:
+            response = client.post(
+                url,
+                json=payload,
+                headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            result = response.json()
+
+        suggestions = result.get("results", [])
+        if not suggestions:
+            return json.dumps(
+                {"status": "no_suggestions", "message": "No formula suggestions returned. Try rephrasing the hint."}
+            )
+
+        top_suggestion = suggestions[0]
+        formula = top_suggestion.get("formula", "")
+        summary = top_suggestion.get("summary", "")
+        if summary:
+            summary = _clean_html(summary)
+
+        field_definition = _create_formula_field_definition(label, field_schema_id)
+        field_definition["formula"] = formula
+
+        return json.dumps(
+            {
+                "status": "success",
+                "formula": formula,
+                "field_definition": field_definition,
+                "section_id": section_id,
+                "summary": summary,
+                "description": _clean_html(top_suggestion.get("description", "")),
+            }
+        )
+
+    except httpx.HTTPStatusError as e:
+        logger.exception("HTTP error in suggest_formula_field")
+        return json.dumps(
+            {
+                "status": "error",
+                "error": f"HTTP {e.response.status_code}: {e.response.text[:500]}",
+            }
+        )
+    except Exception as e:
+        logger.exception("Error in suggest_formula_field")
+        return json.dumps({"status": "error", "error": str(e)})
+
+
+def _clean_html(text: str) -> str:
+    """Remove HTML tags from text (simple cleanup for display)."""
+    return re.sub(r"<[^>]+>", "", text)

rossum_agent/tools/skills.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+import logging
+
+from anthropic import beta_tool
+
+from rossum_agent.agent.skills import get_skill, get_skill_registry
+
+logger = logging.getLogger(__name__)
+
+
+@beta_tool
+def load_skill(name: str) -> str:
+    """Load a specialized skill that provides domain-specific instructions and workflows.
+
+    Use this tool when you recognize that a task matches one of the available skills.
+    The skill will provide detailed instructions, workflows, and context for the task.
+
+    Args:
+        name: The name of the skill to load (e.g., "rossum-deployment").
+
+    Returns:
+        JSON with skill instructions, or error with available skills if not found.
+    """
+    if (skill := get_skill(name)) is None:
+        available = get_skill_registry().get_skill_names()
+        logger.error(f"Skill '{name}' not found. Available skills: {available}")
+        return json.dumps({"status": "error", "message": f"Skill '{name}' not found.", "available_skills": available})
+    logger.info(f"Loaded skill '{skill.name}'")
+    return json.dumps({"status": "success", "skill_name": skill.name, "instructions": skill.content})