agent-framework-lib 0.6.2__tar.gz → 0.6.3__tar.gz

{agent_framework_lib-0.6.2/agent_framework_lib.egg-info → agent_framework_lib-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.6.2
+Version: 0.6.3
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>
@@ -65,6 +65,8 @@ Requires-Dist: falkordb>=1.0.0
 Requires-Dist: grpcio-status>=1.71.2
 Requires-Dist: nodeenv>=1.8.0
 Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: drawpyo>=0.2.5
+Requires-Dist: openpyxl>=3.1.5
 Provides-Extra: llamaindex
 Requires-Dist: llama-index>=0.14.16; extra == "llamaindex"
 Requires-Dist: llama-index-core>=0.14.16; extra == "llamaindex"
@@ -77,6 +79,10 @@ Requires-Dist: llama-index-tools-mcp>=0.4.0; extra == "mcp"
 Provides-Extra: websearch
 Requires-Dist: ddgs>=8.0.0; extra == "websearch"
 Provides-Extra: microsoft
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.0; extra == "excel"
+Provides-Extra: drawio
+Requires-Dist: drawpyo>=0.1.0; extra == "drawio"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -133,7 +139,7 @@ Requires-Dist: traceloop-sdk>=0.30.0; extra == "observability"
 Provides-Extra: monitoring
 Requires-Dist: psutil>=5.9.0; extra == "monitoring"
 Provides-Extra: all
-Requires-Dist: agent-framework-lib[dev,elasticsearch,gcp,graphiti-all,llamaindex,mcp,memory,microsoft,minio,mongodb,monitoring,multimodal,observability,postgresql,s3,websearch]; extra == "all"
+Requires-Dist: agent-framework-lib[dev,drawio,elasticsearch,excel,gcp,graphiti-all,llamaindex,mcp,memory,microsoft,minio,mongodb,monitoring,multimodal,observability,postgresql,s3,websearch]; extra == "all"
 Dynamic: license-file
 
 # Agent Framework Library

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.3}/agent_framework/__init__.py

@@ -32,7 +32,7 @@ Example Usage:
     create_basic_agent_server(MyAgent, port=8000)
     ```
 
-Version: 0.6.2
+Version: 0.6.3
 Author: Cinco AI Team
 License: MIT
 """
@@ -88,7 +88,7 @@ def _auto_setup_dependencies() -> None:
 # Track if auto-setup has been done
 _AUTO_SETUP_DONE = False
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 __author__ = "Cinco AI Team"
 __license__ = "MIT"
 __email__ = "sebastian@cinco.ai"

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.3}/agent_framework/core/context_budget.py

@@ -107,6 +107,7 @@ class BudgetSnapshot:
     tool_definition_multiplier: float = 1.0
     raw_tool_tokens: int = 0
     estimated_tool_tokens: int = 0
+    tool_fixed_overhead: int = 0
 
 
 class ContextBudgetManager:
@@ -140,6 +141,7 @@ class ContextBudgetManager:
         self._tool_definition_tokens = 0
         self._raw_tool_tokens = 0
         self._tool_definition_multiplier = 1.0
+        self._tool_fixed_overhead = 0
 
         # Resolution order: explicit parameter > env var > class constant
         def _resolve(param, env_key, default):
@@ -248,18 +250,19 @@ class ContextBudgetManager:
             total = self._token_counter.count_tokens(message.content or "").count
         return total
 
-    # Anthropic (et d'autres providers) sérialisent les tool definitions avec un
-    # wrapping XML/JSON lourd qui multiplie le coût en tokens par rapport à ce que
-    # tiktoken estime sur le JSON brut. Empiriquement, le ratio est ~14x pour
-    # Anthropic. On utilise 15x comme marge de sécurité.
-    TOOL_DEFINITION_MULTIPLIER = 15
+    # Les providers sérialisent les tool definitions avec un wrapping qui ajoute
+    # un overhead par rapport au JSON brut. Le modèle de calibration utilise :
+    # estimated_tokens = raw_tokens * multiplier + fixed_overhead
+    # Voir provider_calibration.py pour les valeurs par provider.
+    TOOL_DEFINITION_MULTIPLIER = 1.4  # Anthropic default, overridden per-provider
 
     def set_sacred_zone(self, system_prompt: str, tool_definitions: str) -> int:
         """Compte et enregistre les tokens de la Zone Sacrée.
 
         Le system prompt est compté tel quel (tiktoken est fiable pour du texte).
-        Les tool definitions reçoivent un multiplicateur calibré par provider car
-        les providers sérialisent les définitions avec un wrapping lourd.
+        Les tool definitions reçoivent un multiplicateur calibré par provider
+        (wrapping XML/JSON) plus un overhead fixe (system prompt tool-use injecté
+        par le provider).
 
         Args:
             system_prompt: Prompt système complet (agent + skills + mémoire passive).
@@ -273,16 +276,25 @@ class ContextBudgetManager:
         self._tool_definition_multiplier = ProviderCalibrationRegistry.get_multiplier(
             self._model_name
         )
-        self._tool_definition_tokens = int(
-            self._raw_tool_tokens * self._tool_definition_multiplier
+        self._tool_fixed_overhead = ProviderCalibrationRegistry.get_fixed_overhead(
+            self._model_name
         )
+        # estimated = raw * multiplier + fixed_overhead (only if tools are present)
+        if self._raw_tool_tokens > 0:
+            self._tool_definition_tokens = (
+                int(self._raw_tool_tokens * self._tool_definition_multiplier)
+                + self._tool_fixed_overhead
+            )
+        else:
+            self._tool_definition_tokens = 0
         self._sacred_zone_tokens = self._prompt_tokens + self._tool_definition_tokens
         logger.info(
-            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %.1fx = %d)",
+            "Sacred zone: %d tokens (prompt=%d, tools=%d raw * %.1fx + %d overhead = %d)",
             self._sacred_zone_tokens,
             self._prompt_tokens,
             self._raw_tool_tokens,
             self._tool_definition_multiplier,
+            self._tool_fixed_overhead if self._raw_tool_tokens > 0 else 0,
             self._tool_definition_tokens,
         )
         if self._sacred_zone_tokens > 0.65 * self._context_window:
@@ -354,7 +366,8 @@ class ContextBudgetManager:
             model_name=self._model_name,
             tool_definition_multiplier=self._tool_definition_multiplier,
             raw_tool_tokens=self._raw_tool_tokens,
-            estimated_tool_tokens=int(self._raw_tool_tokens * self._tool_definition_multiplier),
+            estimated_tool_tokens=self._tool_definition_tokens,
+            tool_fixed_overhead=self._tool_fixed_overhead,
         )
 
     async def enforce_budget(
@@ -593,7 +606,8 @@ class ContextBudgetManager:
             model_name=self._model_name,
             tool_definition_multiplier=self._tool_definition_multiplier,
             raw_tool_tokens=self._raw_tool_tokens,
-            estimated_tool_tokens=int(self._raw_tool_tokens * self._tool_definition_multiplier),
+            estimated_tool_tokens=self._tool_definition_tokens,
+            tool_fixed_overhead=self._tool_fixed_overhead,
         )
 
     async def truncate_query_if_needed(

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.3}/agent_framework/core/provider_calibration.py

@@ -1,8 +1,16 @@
-"""Provider-specific token calibration for tool definition multipliers.
+"""Provider-specific token calibration for tool definition overhead.
 
-Provides empirically measured multipliers that account for the overhead
-each LLM provider adds when serializing tool definitions (XML wrapping,
-JSON function-calling format, etc.).
+Provides calibration factors that account for the overhead each LLM provider
+adds when serializing tool definitions. The model uses a fixed overhead
+(provider system prompt for tool-use) plus a multiplier on the raw tool
+definition tokens (XML/JSON wrapping per tool).
+
+Previous calibration (2025-01) used a single 15x multiplier for Anthropic,
+which was based on per-tool count_tokens calls that double-counted the shared
+system overhead. See: https://www.async-let.com/posts/claude-code-mcp-token-reporting
+
+Current calibration (2026-03) uses overhead + multiplier, measured against
+Anthropic's batch count_tokens endpoint and OpenAI's tiktoken validation.
 """
 
 from __future__ import annotations
@@ -19,6 +27,7 @@ class ProviderCalibration:
 
     provider_name: str
     tool_definition_multiplier: float
+    fixed_overhead_tokens: int
     source: str
     measured_date: str
     notes: str = ""
@@ -27,35 +36,46 @@ class ProviderCalibration:
 class ProviderCalibrationRegistry:
     """Registry of per-provider token calibration data.
 
-    Resolves the appropriate tool-definition multiplier for a given model
+    Resolves the appropriate tool-definition overhead for a given model
     by detecting the provider from the model name.
+
+    The total estimated tool tokens = raw_tokens * multiplier + fixed_overhead.
     """
 
     CALIBRATIONS: dict[str, ProviderCalibration] = {
         "anthropic": ProviderCalibration(
             provider_name="anthropic",
-            tool_definition_multiplier=15.0,
-            source="empirical_measurement_2025-01",
-            measured_date="2025-01",
-            notes="Heavy XML/JSON wrapping for Anthropic tool definitions",
+            tool_definition_multiplier=1.4,
+            fixed_overhead_tokens=350,
+            source="batch_count_tokens_measurement_2026-03",
+            measured_date="2026-03",
+            notes=(
+                "Anthropic injects a hidden tool-use system prompt (~350 tokens) "
+                "and wraps each tool in XML. The 1.4x multiplier accounts for "
+                "XML wrapping overhead on the raw JSON schema. Previous 15x was "
+                "based on per-tool counting that repeated the system overhead."
+            ),
         ),
         "openai": ProviderCalibration(
             provider_name="openai",
-            tool_definition_multiplier=3.0,
-            source="empirical_measurement_2025-01",
-            measured_date="2025-01",
-            notes="OpenAI function-calling format, moderate overhead",
+            tool_definition_multiplier=1.1,
+            fixed_overhead_tokens=100,
+            source="tiktoken_validation_2026-03",
+            measured_date="2026-03",
+            notes="OpenAI function-calling format, minimal overhead over JSON schema",
         ),
         "google": ProviderCalibration(
             provider_name="google",
-            tool_definition_multiplier=4.0,
-            source="empirical_measurement_2025-01",
-            measured_date="2025-01",
-            notes="Gemini tool-use format, overhead similar to OpenAI",
+            tool_definition_multiplier=1.2,
+            fixed_overhead_tokens=150,
+            source="estimated_2026-03",
+            measured_date="2026-03",
+            notes="Gemini tool-use format, similar to OpenAI with slight extra wrapping",
         ),
     }
 
-    DEFAULT_MULTIPLIER: float = 5.0
+    DEFAULT_MULTIPLIER: float = 1.5
+    DEFAULT_FIXED_OVERHEAD: int = 200
 
     # Prefix-to-provider mapping for model name detection
     _PROVIDER_PREFIXES: dict[str, str] = {
@@ -105,7 +125,7 @@ class ProviderCalibrationRegistry:
     def get_multiplier(cls, model_name: str) -> float:
         """Resolve the tool-definition multiplier for a model.
 
-        Falls back to DEFAULT_MULTIPLIER (5.0) and logs INFO when the
+        Falls back to DEFAULT_MULTIPLIER and logs INFO when the
         provider is not recognized.
 
         Args:
@@ -124,3 +144,21 @@ class ProviderCalibrationRegistry:
             cls.DEFAULT_MULTIPLIER,
         )
         return cls.DEFAULT_MULTIPLIER
+
+    @classmethod
+    def get_fixed_overhead(cls, model_name: str) -> int:
+        """Resolve the fixed tool-use overhead tokens for a model.
+
+        This accounts for the hidden system prompt that providers inject
+        when tools are present (e.g. Anthropic's tool-use preamble).
+
+        Args:
+            model_name: Name of the LLM model.
+
+        Returns:
+            Fixed overhead in tokens, or the default.
+        """
+        calibration = cls.get_calibration(model_name)
+        if calibration is not None:
+            return calibration.fixed_overhead_tokens
+        return cls.DEFAULT_FIXED_OVERHEAD

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.3}/agent_framework/skills/builtin/__init__.py

@@ -67,6 +67,10 @@ from .form_skill import create_form_skill, FORM_INSTRUCTIONS
 from .optionsblock_skill import create_optionsblock_skill, OPTIONSBLOCK_INSTRUCTIONS
 from .image_display_skill import create_image_display_skill, IMAGE_DISPLAY_INSTRUCTIONS
 
+# Excel and Draw.io skills
+from .excel_skill import create_excel_skill, EXCEL_INSTRUCTIONS
+from .drawio_skill import create_drawio_skill, DRAWIO_INSTRUCTIONS
+
 
 def get_all_builtin_skills() -> list[Skill]:
     """
@@ -102,6 +106,10 @@ def get_all_builtin_skills() -> list[Skill]:
     skills.append(create_optionsblock_skill())
     skills.append(create_image_display_skill())
 
+    # Excel and Draw.io skills
+    skills.append(create_excel_skill())
+    skills.append(create_drawio_skill())
+
     return skills
 
 
@@ -146,4 +154,10 @@ __all__ = [
     "FORM_INSTRUCTIONS",
     "OPTIONSBLOCK_INSTRUCTIONS",
     "IMAGE_DISPLAY_INSTRUCTIONS",
+    # Excel and Draw.io skill creators
+    "create_excel_skill",
+    "create_drawio_skill",
+    # Excel and Draw.io instruction constants
+    "EXCEL_INSTRUCTIONS",
+    "DRAWIO_INSTRUCTIONS",
 ]

agent_framework_lib-0.6.3/agent_framework/skills/builtin/drawio_skill.py

@@ -0,0 +1,97 @@
+"""
+Draw.io Skill - diagram generation capability.
+
+Wraps CreateDrawioTool with instructions for generating .drawio XML files.
+"""
+
+from ..base import Skill, SkillCategory, SkillMetadata
+from ...tools.drawio_tools import CreateDrawioTool
+
+
+DRAWIO_INSTRUCTIONS = """
+## Draw.io Diagram Generation
+
+Use the `create_drawio_file` tool to generate `.drawio` diagram files that open in Draw.io or diagrams.net.
+
+### Tool Parameters
+
+- `filename` (str): Target filename, e.g. `"architecture.drawio"`
+- `title` (str): Diagram page title
+- `nodes` (list): Shape/element definitions. Each node has:
+  - `id` (str): Unique identifier (used by edges)
+  - `label` (str): Display text inside the shape
+  - `shape` (str, optional): One of `rectangle`, `rounded`, `ellipse`, `diamond`, `parallelogram` (default: `rectangle`)
+  - `x` (int, optional): X position in pixels
+  - `y` (int, optional): Y position in pixels
+- `edges` (list): Connection definitions. Each edge has:
+  - `source` (str): Source node `id`
+  - `target` (str): Target node `id`
+  - `label` (str, optional): Label displayed on the edge
+
+### Supported Shapes
+
+| Shape | Description |
+|---|---|
+| `rectangle` | Standard rectangle (default) |
+| `rounded` | Rectangle with rounded corners |
+| `ellipse` | Oval / circle |
+| `diamond` | Diamond / decision shape |
+| `parallelogram` | Parallelogram (input/output) |
+
+### Example — Flowchart
+
+```json
+{
+  "filename": "order_flow.drawio",
+  "title": "Order Processing Flow",
+  "nodes": [
+    {"id": "start", "label": "Start", "shape": "ellipse", "x": 100, "y": 50},
+    {"id": "check", "label": "Check Stock?", "shape": "diamond", "x": 100, "y": 180},
+    {"id": "ship", "label": "Ship Order", "shape": "rectangle", "x": 50, "y": 320},
+    {"id": "notify", "label": "Notify Customer", "shape": "rounded", "x": 200, "y": 320},
+    {"id": "end", "label": "End", "shape": "ellipse", "x": 125, "y": 460}
+  ],
+  "edges": [
+    {"source": "start", "target": "check"},
+    {"source": "check", "target": "ship", "label": "In Stock"},
+    {"source": "check", "target": "notify", "label": "Out of Stock"},
+    {"source": "ship", "target": "end"},
+    {"source": "notify", "target": "end"}
+  ]
+}
+```
+
+### Notes
+
+- All edge `source` and `target` values must match an existing node `id`.
+- Requires `drawpyo` to be installed (`uv add drawpyo`).
+- Generated files open directly in Draw.io (https://app.diagrams.net) or diagrams.net.
+"""
+
+
+def create_drawio_skill() -> Skill:
+    """
+    Create the Draw.io diagram generation skill.
+
+    Returns:
+        Skill instance for Draw.io file generation.
+    """
+    skill = Skill(
+        metadata=SkillMetadata(
+            name="drawio",
+            description="Generate .drawio diagram files for flowcharts, architecture diagrams, and more.",
+            trigger_patterns=["drawio", "diagram", "flowchart", "architecture diagram", "draw.io"],
+            category=SkillCategory.VISUALIZATION,
+            version="1.0.0",
+        ),
+        instructions=DRAWIO_INSTRUCTIONS,
+        tools=[CreateDrawioTool()],
+        dependencies=[],
+        config={},
+    )
+    skill._display_name = "Génération de diagrammes Draw.io"
+    skill._display_icon = "🗂️"
+    return skill
+
+
+__all__ = ["create_drawio_skill", "DRAWIO_INSTRUCTIONS"]

agent_framework_lib-0.6.3/agent_framework/skills/builtin/excel_skill.py

@@ -0,0 +1,86 @@
+"""
+Excel Skill - spreadsheet generation capability.
+
+Wraps CreateExcelTool with instructions for generating .xlsx files.
+"""
+
+from ..base import Skill, SkillCategory, SkillMetadata
+from ...tools.excel_tools import CreateExcelTool
+
+
+EXCEL_INSTRUCTIONS = """
+## Excel Spreadsheet Generation
+
+Use the `create_excel_file` tool to generate `.xlsx` spreadsheet files.
+
+### Tool Parameters
+
+- `filename` (str): Target filename, e.g. `"report.xlsx"`
+- `sheets` (list): One or more sheet definitions. Each sheet has:
+  - `name` (str): Sheet tab name
+  - `headers` (list[str]): Column header labels
+  - `rows` (list[list]): Data rows — each row is a list of cell values
+  - `bold_header` (bool, optional): Apply bold formatting to the header row (default: `false`)
+
+### Example
+
+```json
+{
+  "filename": "sales_report.xlsx",
+  "sheets": [
+    {
+      "name": "Q1 Sales",
+      "headers": ["Month", "Revenue", "Units"],
+      "rows": [
+        ["January", 12500, 250],
+        ["February", 15000, 300],
+        ["March", 11000, 220]
+      ],
+      "bold_header": true
+    },
+    {
+      "name": "Summary",
+      "headers": ["Metric", "Value"],
+      "rows": [
+        ["Total Revenue", 38500],
+        ["Total Units", 770]
+      ]
+    }
+  ]
+}
+```
+
+### Notes
+
+- Multiple sheets are supported in a single call.
+- Row length does not need to match header count — short rows leave trailing cells empty.
+- Requires `openpyxl` to be installed (`uv add openpyxl`).
+"""
+
+
+def create_excel_skill() -> Skill:
+    """
+    Create the Excel spreadsheet generation skill.
+
+    Returns:
+        Skill instance for Excel file generation.
+    """
+    skill = Skill(
+        metadata=SkillMetadata(
+            name="excel",
+            description="Generate .xlsx Excel spreadsheet files with multiple sheets and formatting.",
+            trigger_patterns=["excel", "spreadsheet", "xlsx", "tableau"],
+            category=SkillCategory.DOCUMENT,
+            version="1.0.0",
+        ),
+        instructions=EXCEL_INSTRUCTIONS,
+        tools=[CreateExcelTool()],
+        dependencies=[],
+        config={},
+    )
+    skill._display_name = "Génération de fichiers Excel"
+    skill._display_icon = "📊"
+    return skill
+
+
+__all__ = ["create_excel_skill", "EXCEL_INSTRUCTIONS"]

{agent_framework_lib-0.6.2 → agent_framework_lib-0.6.3}/agent_framework/tools/__init__.py

@@ -132,6 +132,10 @@ from .unified_pdf_tool import CreateUnifiedPDFTool
 # Web search tools
 from .web_search_tools import WebSearchTool, WebNewsSearchTool
 
+# Excel and Draw.io tools (optional dependencies)
+from .excel_tools import CreateExcelTool
+from .drawio_tools import CreateDrawioTool
+
 # Adaptive image sizing components
 from .sizing_config import ImageSizingConfig, ImageDimensionCalculator
 from .pdf_image_scaler import PDFImageScaler
@@ -161,6 +165,9 @@ __all__ = [
     # Web search tools
     "WebSearchTool",
     "WebNewsSearchTool",
+    # Excel and Draw.io tools
+    "CreateExcelTool",
+    "CreateDrawioTool",
     # Adaptive image sizing
     "ImageSizingConfig",
     "ImageDimensionCalculator",

agent_framework_lib-0.6.3/agent_framework/tools/drawio_tools.py

@@ -0,0 +1,171 @@
+"""
+Draw.io diagram generation tool for creating .drawio XML files.
+"""
+
+import logging
+import os
+import tempfile
+from collections.abc import Callable
+
+from .base import AgentTool, ToolDependencyError
+
+
+try:
+    import drawpyo
+    DRAWPYO_AVAILABLE = True
+except ImportError:
+    DRAWPYO_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+# Mapping from user-facing shape names to drawpyo style attributes
+SHAPE_STYLES: dict[str, dict] = {
+    "rectangle": {},
+    "rounded": {"rounded": 1},
+    "ellipse": {"shape": "ellipse"},
+    "diamond": {"shape": "rhombus"},
+    "parallelogram": {"shape": "parallelogram"},
+}
+
+DEFAULT_SHAPE = "rectangle"
+DEFAULT_NODE_WIDTH = 120
+DEFAULT_NODE_HEIGHT = 60
+DEFAULT_X_STEP = 160
+DEFAULT_Y = 100
+
+
+class CreateDrawioTool(AgentTool):
+    """Tool for creating Draw.io .drawio diagram files."""
+
+    def get_tool_function(self) -> Callable:
+        """Return the Draw.io file creation function."""
+
+        async def create_drawio_file(
+            filename: str,
+            title: str,
+            nodes: list[dict],
+            edges: list[dict],
+        ) -> str:
+            """
+            Create a Draw.io .drawio diagram file.
+
+            Node definition fields:
+            - id (str): Unique node identifier
+            - label (str): Display text
+            - shape (str, optional): rectangle|rounded|ellipse|diamond|parallelogram (default: rectangle)
+            - x (int, optional): X position
+            - y (int, optional): Y position
+
+            Edge definition fields:
+            - source (str): Source node id
+            - target (str): Target node id
+            - label (str, optional): Edge label text
+
+            Args:
+                filename: Target filename for the .drawio file (e.g. "diagram.drawio")
+                title: Diagram title / page name
+                nodes: List of node definitions
+                edges: List of edge definitions
+
+            Returns:
+                Markdown download link on success, or an error string on failure.
+            """
+            self._ensure_initialized()
+
+            if not filename or not filename.strip():
+                return "Error: Filename cannot be empty"
+
+            if not nodes:
+                return "Error: Nodes list cannot be empty"
+
+            # Validate edge references
+            node_ids = {n["id"] for n in nodes}
+            for edge in edges:
+                for field in ("source", "target"):
+                    ref = edge.get(field)
+                    if ref not in node_ids:
+                        return f"Error: Edge references unknown node id '{ref}'"
+
+            if not DRAWPYO_AVAILABLE:
+                raise ToolDependencyError(
+                    "drawpyo is not installed. Install it with: uv add drawpyo"
+                )
+
+            if not self.file_storage:
+                raise ToolDependencyError(
+                    "File storage is not available. Ensure set_context() was called "
+                    "with a valid file_storage instance."
+                )
+
+            try:
+                with tempfile.TemporaryDirectory() as tmpdir:
+                    f = drawpyo.File()
+                    f.file_path = tmpdir
+                    f.file_name = filename
+                    page = drawpyo.Page(file=f, name=title or "Page-1")
+
+                    node_objects: dict[str, object] = {}
+                    for idx, node_def in enumerate(nodes):
+                        obj = drawpyo.diagram.Object(
+                            value=node_def.get("label", ""),
+                            page=page,
+                        )
+                        obj.geometry.width = DEFAULT_NODE_WIDTH
+                        obj.geometry.height = DEFAULT_NODE_HEIGHT
+                        obj.geometry.x = node_def.get("x", idx * DEFAULT_X_STEP)
+                        obj.geometry.y = node_def.get("y", DEFAULT_Y)
+
+                        shape = node_def.get("shape", DEFAULT_SHAPE)
+                        style_attrs = SHAPE_STYLES.get(shape, SHAPE_STYLES[DEFAULT_SHAPE])
+                        for attr, val in style_attrs.items():
+                            setattr(obj, attr, val)
+
+                        node_objects[node_def["id"]] = obj
+
+                    for edge_def in edges:
+                        src = node_objects[edge_def["source"]]
+                        tgt = node_objects[edge_def["target"]]
+                        edge_obj = drawpyo.diagram.Edge(source=src, target=tgt, page=page)
+                        label = edge_def.get("label")
+                        if label:
+                            edge_obj.label = label
+
+                    f.write()
+
+                    filepath = os.path.join(tmpdir, filename)
+                    with open(filepath, "rb") as fh:
+                        content_bytes = fh.read()
+
+                file_id = await self.file_storage.store_file(
+                    content=content_bytes,
+                    filename=filename,
+                    user_id=self.current_user_id,
+                    session_id=self.current_session_id,
+                    is_generated=True,
+                    mime_type="application/xml",
+                    tags=["agent-created"],
+                )
+
+                if hasattr(self.file_storage, "get_download_url"):
+                    try:
+                        download_url = await self.file_storage.get_download_url(file_id)
+                    except Exception as url_error:
+                        logger.warning(f"Failed to get download URL: {url_error}")
+                        download_url = f"/files/{file_id}/download"
+                else:
+                    download_url = f"/files/{file_id}/download"
+
+                logger.info(f"Created Draw.io file '{filename}' with ID: {file_id}")
+                return f"File '{filename}' created!\n\n[{filename}]({download_url})"
+
+            except ToolDependencyError:
+                raise
+            except Exception as e:
+                error_msg = f"Failed to create Draw.io file '{filename}': {e}"
+                logger.error(error_msg)
+                return f"Error: {error_msg}"
+
+        return create_drawio_file
+
+
+__all__ = ["CreateDrawioTool"]