refactor utilities

utils/doc_editor_tools.py

@@ -1,276 +0,0 @@
-#!/usr/bin/env python3
-"""
-Document editor tools for HTML modification
-Implements Cline-like text-based editing with exact match + BeautifulSoup validation for HTML
-"""
-
-import logging
-from typing import Literal, Dict, Any
-from bs4 import BeautifulSoup
-from langchain_core.tools import tool
-
-logger = logging.getLogger(__name__)
-
-async def _validate_html(html: str) -> tuple[bool, str]:
-    """
-    Validate HTML structure using BeautifulSoup.
-    
-    BeautifulSoup is very tolerant and will parse even malformed HTML.
-    We use it to ensure the HTML is at least parseable and contains some content.
-    
-    Args:
-        html: The HTML string to validate
-    
-    Returns:
-        tuple[bool, str]: (is_valid, error_message)
-    """
-    if not html or not html.strip():
-        return False, "HTML document is empty"
-    
-    try:
-        # Parse the HTML (html.parser is included in stdlib)
-        soup = BeautifulSoup(html, 'html.parser')
-        
-        # Get the normalized HTML
-        normalized = str(soup)
-        
-        # Check if there's any content
-        if not normalized.strip():
-            return False, "HTML document is empty after parsing"
-        
-        # Check if there are any HTML tags
-        if len(soup.find_all()) == 0:
-            return False, "HTML document contains no HTML tags"
-        
-        # Check for obvious structural issues
-        # BeautifulSoup will have already failed if the HTML is completely unparsable
-        # So at this point we know it's at least somewhat valid
-        
-        return True, "OK"
-        
-    except Exception as e:
-        return False, f"HTML parsing failed: {str(e)}"
-
-
-@tool
-async def replace_html(doc_text: str, search: str, replace: str, expected_matches: int = 1) -> Dict[str, Any]:
-    """
-    Replace an exact block of HTML text in the document.
-    
-    This tool performs exact string matching on the HTML content.
-    It's critical that the 'search' parameter matches exactly (including whitespace, tags, and attributes).
-    
-    Args:
-        doc_text: The HTML document content
-        search: The exact HTML block to replace (must match exactly, including whitespace)
-        replace: The exact HTML block to insert
-        expected_matches: Expected number of occurrences (default: 1)
-    
-    Returns:
-        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
-        and optionally 'error' (str) if something went wrong
-    
-    Example:
-        search = "<p>12 mois</p>"
-        replace = "<p>24 mois</p>"
-    """
-    logger.info(f"  🔧 replace_html | search:{len(search)}b | replace:{len(replace)}b | expect:{expected_matches}")
-    
-    # Count exact matches
-    m = doc_text.count(search) if search else 0
-    
-    if m != expected_matches:
-        error = f"Search not found. Expected {expected_matches}, found {m}"
-        logger.warning(f"  ❌ {error}")
-        return {
-            "ok": False,
-            "error": error,
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nHTML must match EXACTLY and your search pattern has unexpected number of matches"
-        }
-    
-    # Perform replacement
-    new_text = doc_text.replace(search, replace, expected_matches)
-    
-    # Validate result with BeautifulSoup
-    is_valid, validation_error = await _validate_html(new_text)
-    if not is_valid:
-        logger.warning(f"  ❌ Validation failed: {validation_error}")
-        return {
-            "ok": False,
-            "error": f"Invalid HTML: {validation_error}",
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
-        }
-    
-    logger.info(f"  ✅ Success | +{len(new_text)-len(doc_text)}b")
-    return {
-        "ok": True,
-        "doc_text": new_text,
-        "matches": m
-    }
-
-
-@tool
-async def add_html(doc_text: str, anchor_search: str, insert: str,
-                   position: Literal["before", "after"] = "after", 
-                   expected_matches: int = 1) -> Dict[str, Any]:
-    """
-    Add HTML content before or after an anchor block in the document.
-    
-    This tool finds an exact anchor block and inserts new content adjacent to it.
-    Useful for adding new paragraphs, sections, or elements.
-    
-    Args:
-        doc_text: The HTML document content
-        anchor_search: The exact HTML block to find (must match exactly)
-        insert: The exact HTML block to insert
-        position: "before" or "after" (default: "after")
-        expected_matches: Expected number of anchor occurrences (default: 1)
-    
-    Returns:
-        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
-        and optionally 'error' (str) if something went wrong
-    
-    Example:
-        anchor_search = "<h2>Article 2 - Durée</h2>"
-        insert = "<h3>Article 3 - Prix</h3>"
-        position = "after"
-    """
-    logger.info(f"  🔧 add_html | anchor:{len(anchor_search)}b | insert:{len(insert)}b | pos:{position} | expect:{expected_matches}")
-    
-    # Count exact matches of anchor
-    m = doc_text.count(anchor_search) if anchor_search else 0
-    
-    if m != expected_matches:
-        error = f"Anchor not found. Expected {expected_matches}, found {m}"
-        logger.warning(f"  ❌ {error}")
-        return {
-            "ok": False,
-            "error": error,
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nAnchor must match EXACTLY, and your search pattern has unexpected number of matches"
-        }
-    
-    # Insert before or after anchor
-    if position == "before":
-        new_text = doc_text.replace(anchor_search, insert + anchor_search, 1)
-    else:  # after
-        new_text = doc_text.replace(anchor_search, anchor_search + insert, 1)
-    
-    # Validate result with BeautifulSoup
-    is_valid, validation_error = await _validate_html(new_text)
-    if not is_valid:
-        logger.warning(f"  ❌ Validation failed: {validation_error}")
-        return {
-            "ok": False,
-            "error": f"Invalid HTML: {validation_error}",
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
-        }
-    
-    logger.info(f"  ✅ Success | +{len(new_text)-len(doc_text)}b")
-    return {
-        "ok": True,
-        "doc_text": new_text,
-        "matches": m
-    }
-
-
-@tool
-async def delete_html(doc_text: str, search: str, expected_matches: int = 1) -> Dict[str, Any]:
-    """
-    Delete an exact block of HTML from document.
-    
-    This is a convenience wrapper around replace_html with an empty replacement.
-    Useful for removing unwanted sections, clauses, or content.
-    
-    Args:
-        doc_text: The HTML document content
-        search: The exact HTML block to delete (must match exactly)
-        expected_matches: Expected number of occurrences (default: 1)
-    
-    Returns:
-        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
-        and optionally 'error' (str) if something went wrong
-    
-    Example:
-        search = "<p>This paragraph should be deleted</p>"
-    """
-    logger.info(f"  🔧 delete_html | search:{len(search)}b | expect:{expected_matches}")
-    
-    # Count exact matches
-    m = doc_text.count(search) if search else 0
-    
-    if m != expected_matches:
-        error = f"Search not found. Expected {expected_matches}, found {m}"
-        logger.warning(f"  ❌ {error}")
-        return {
-            "ok": False,
-            "error": error,
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nHTML must match EXACTLY and your search pattern has unexpected number of matches"
-        }
-    
-    # Perform replacement with empty string
-    new_text = doc_text.replace(search, "", expected_matches)
-    
-    # Validate result with BeautifulSoup
-    is_valid, validation_error = await _validate_html(new_text)
-    if not is_valid:
-        logger.warning(f"  ❌ Validation failed: {validation_error}")
-        return {
-            "ok": False,
-            "error": f"Invalid HTML: {validation_error}",
-            "matches": m,
-            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
-        }
-    
-    logger.info(f"  ✅ Success | -{len(doc_text)-len(new_text)}b")
-    return {
-        "ok": True,
-        "doc_text": new_text,
-        "matches": m
-    }
-
-
-@tool
-async def view_current_document() -> Dict[str, Any]:
-    """
-    View the current state of the document being edited.
-    
-    Use this tool to see the current document content after modifications.
-    This helps you verify previous edits and understand the current structure.
-    
-    The document content is automatically provided by the workflow state.
-    
-    Returns:
-        Dict with 'ok' (bool) and 'content' (str) containing the HTML document
-    """
-    # doc_text is injected by _tools_node in doc_editor.py
-    logger.info(f"  🔍 view_current_document")
-    return {
-        "ok": True,
-        "content": ""
-    }
-
-
-@tool
-async def attempt_completion(message: str) -> Dict[str, Any]:
-    """
-    Signal that document editing is complete and provide a summary message.
-    
-    This tool should be called when all requested modifications have been
-    successfully applied to document.
-    
-    Args:
-        message: A summary message describing what was changed in document
-    
-    Returns:
-        Dict with 'ok' (bool) and 'message' (str)
-    """
-    logger.info(f"  ✅ attempt_completion | {message}")
-    return {
-        "ok": True,
-        "message": message
-    }

utils/tools.py

@@ -5,14 +5,18 @@ Tools for the CyberLegal Agent
 
 import os
 import json
-from typing import List, Dict, Any, Optional
+from typing import List, Dict, Any, Optional, Literal
 from langchain_core.tools import tool
 from langchain_tavily import TavilySearch
-from subagents.lawyer_selector import LawyerSelectorAgent
-from subagents.lawyer_messenger import LawyerMessengerAgent
-from subagents.doc_editor import DocumentEditorAgent
+from agents.lawyer_selector import LawyerSelectorAgent
+from agents.lawyer_messenger import LawyerMessengerAgent
+from agents.doc_editor import DocumentEditorAgent
 from utils.lightrag_client import LightRAGClient, get_lightrag_client, validate_jurisdiction, get_available_jurisdictions
 import resend
+import logging
+from bs4 import BeautifulSoup
+
+logger = logging.getLogger(__name__)
 
 # Global instances - will be initialized in agent_api.py
 lawyer_selector_agent: Optional[LawyerSelectorAgent] = None
@@ -276,7 +280,6 @@ async def retrieve_lawyer_document(file_path: str) -> str:
     except Exception as e:
         return f"Error retrieving document: {str(e)}"
 
-
 @tool
 async def _retrieve_lawyer_document(
     user_id: str,
@@ -357,6 +360,123 @@ async def _retrieve_lawyer_document(
         return f"Error retrieving document: {str(e)}"
 
 
+# ============ DRAFT DOCUMENT TOOL ============
+
+@tool
+async def create_draft_document(
+    title: str,
+    content: str,
+    path: str
+) -> str:
+    """
+    Create a new document draft and save it to "My documents" via Supabase.
+    
+    This tool saves an HTML document as a PDF draft in the user's document storage.
+    The document will be stored in the specified folder path within "My Documents".
+    
+    Use this tool when the user wants to:
+    - Create a new document draft
+    - Save a generated document
+    - Store a document in their document library
+    
+    Args:
+        title: Document title (e.g., "Contract de bail", "Note juridique")
+        content: Document content in HTML format (e.g., "<h1>Title</h1><p>Content...</p>")
+        path: Folder path where to save the document
+               - Empty string "" → root folder of My Documents
+               - "Contracts/" → ./Contracts/title.pdf
+               - "Drafts/Legal/" → ./Drafts/Legal/title.pdf
+    
+    Returns:
+        Confirmation message with document path and success status
+    
+    Example:
+        create_draft_document(
+            title="Contract de bail",
+            content="<h1>Contrat de bail</h1><p>Ce contrat est conclu entre...</p>",
+            path="Contracts/"
+        )
+        → Saves as "./Contracts/Contract de bail.pdf" and returns confirmation
+    """
+    return
+
+@tool
+async def _create_draft_document(
+    user_id: str,
+    title: str,
+    content: str,
+    path: str
+) -> str:
+    """
+    Real implementation of create_draft_document - calls Supabase endpoint.
+    Args:
+        user_id: User UUID (injected by the agent)
+        title: Document title
+        content: Document HTML content
+        path: Folder path
+    
+    Returns:
+        Success/failure message with document path
+    """
+    try:
+        import httpx
+        
+        # Check configuration from environment
+        base_url = os.getenv("SUPABASE_BASE_URL")
+        cyberlgl_api_key = os.getenv("CYBERLGL_API_KEY")
+
+        if path:
+            # Remove leading ./ if present
+            if path.startswith('./'):
+                path = path[2:]
+            # Ensure trailing /
+            if not path.endswith('/'):
+                path += '/'
+        else:
+            path = ''
+            
+        full_path = f"./{path}{title}.pdf"
+        
+        endpoint_url = f"{base_url}/create-document-from-html"
+        
+        request_body = {
+            "userId": user_id,
+            "html": content,
+            "path": full_path
+        }
+        
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                endpoint_url,
+                json=request_body,
+                headers={
+                    "x-api-key": cyberlgl_api_key
+                },
+                timeout=30.0
+            )
+            
+            if response.status_code == 200:
+                return f"✅ Document successfully saved to: {full_path}"
+            elif response.status_code == 400:
+                error_data = response.json() if response.headers.get('content-type', '').startswith('application/json') else {}
+                return f"❌ Bad request: {error_data.get('error', 'Unknown error')}"
+            elif response.status_code == 401:
+                return "❌ Authentication failed: Invalid API key"
+            elif response.status_code == 403:
+                return "❌ Access denied: You do not have permission to save documents"
+            elif response.status_code == 500:
+                return "❌ Server error: Failed to save document"
+            else:
+                return f"❌ Error: HTTP {response.status_code} - {response.text}"
+                
+    except httpx.TimeoutError:
+        return "❌ Error: Timeout while saving document"
+    except httpx.RequestError as e:
+        return f"❌ Error: Failed to connect to document server: {str(e)}"
+    except Exception as e:
+        return f"❌ Error saving document: {str(e)}"
+
+
 # ============ DOC ASSISTANT TOOLS ============
 
 @tool
@@ -379,7 +499,6 @@ async def edit_document(plan: str) -> str:
     """
     return
 
-
 @tool
 async def _edit_document(
     doc_text: str,
@@ -442,14 +561,399 @@ async def _edit_document(
         }
 
 
+async def _validate_html(html: str) -> tuple[bool, str]:
+    """
+    Validate HTML structure using BeautifulSoup.
+    
+    BeautifulSoup is very tolerant and will parse even malformed HTML.
+    We use it to ensure the HTML is at least parseable and contains some content.
+    
+    Args:
+        html: The HTML string to validate
+    
+    Returns:
+        tuple[bool, str]: (is_valid, error_message)
+    """
+    if not html or not html.strip():
+        return False, "HTML document is empty"
+    
+    try:
+        # Parse the HTML (html.parser is included in stdlib)
+        soup = BeautifulSoup(html, 'html.parser')
+        
+        # Get the normalized HTML
+        normalized = str(soup)
+        
+        # Check if there's any content
+        if not normalized.strip():
+            return False, "HTML document is empty after parsing"
+        
+        # Check if there are any HTML tags
+        if len(soup.find_all()) == 0:
+            return False, "HTML document contains no HTML tags"
+        
+        # Check for obvious structural issues
+        # BeautifulSoup will have already failed if the HTML is completely unparsable
+        # So at this point we know it's at least somewhat valid
+        
+        return True, "OK"
+        
+    except Exception as e:
+        return False, f"HTML parsing failed: {str(e)}"
+
+# ============ FACADES (Public Interface) ============
+
+@tool
+async def replace_html(
+    search: str,
+    replace: str,
+    expected_matches: int = 1
+) -> str:
+    """
+    Replace an exact block of HTML text in the document.
+    
+    This tool performs exact string matching on the HTML content.
+    It's critical that the 'search' parameter matches exactly (including whitespace, tags, and attributes).
+    
+    Args:
+        doc_text: The HTML document content (injected automatically)
+        search: The exact HTML block to replace (must match exactly, including whitespace)
+        replace: The exact HTML block to insert
+        expected_matches: Expected number of occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    
+    Example:
+        search = "<p>12 mois</p>"
+        replace = "<p>24 mois</p>"
+    """
+    return
+
+
+@tool
+async def add_html(
+    anchor_search: str,
+    insert: str,
+    position: Literal["before", "after"] = "after",
+    expected_matches: int = 1
+) -> str:
+    """
+    Add HTML content before or after an anchor block in the document.
+    
+    This tool finds an exact anchor block and inserts new content adjacent to it.
+    Useful for adding new paragraphs, sections, or elements.
+    
+    Args:
+        doc_text: The HTML document content (injected automatically)
+        anchor_search: The exact HTML block to find (must match exactly)
+        insert: The exact HTML block to insert
+        position: "before" or "after" (default: "after")
+        expected_matches: Expected number of anchor occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    
+    Example:
+        anchor_search = "<h2>Article 2 - Durée</h2>"
+        insert = "<h3>Article 3 - Prix</h3>"
+        position = "after"
+    """
+    return
+
+
+@tool
+async def delete_html(
+    search: str,
+    expected_matches: int = 1
+) -> str:
+    """
+    Delete an exact block of HTML from document.
+    
+    This is a convenience wrapper around replace_html with an empty replacement.
+    Useful for removing unwanted sections, clauses, or content.
+    
+    Args:
+        doc_text: The HTML document content (injected automatically)
+        search: The exact HTML block to delete (must match exactly)
+        expected_matches: Expected number of occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    
+    Example:
+        search = "<p>This paragraph should be deleted</p>"
+    """
+    return
+
+
+@tool
+async def view_current_document() -> str:
+    """
+    View the current state of the document being edited.
+    
+    Use this tool to see the current document content after modifications.
+    This helps you verify previous edits and understand the current structure.
+    
+    The document content is automatically provided by the workflow state.
+    
+    Returns:
+        Dict with 'ok' (bool) and 'content' (str) containing the HTML document
+    """
+    return
+
+
+@tool
+async def attempt_completion(message: str) -> Dict[str, Any]:
+    """
+    Signal that document editing is complete and provide a summary message (real implementation).
+    
+    This tool should be called when all requested modifications have been
+    successfully applied to document.
+    
+    Args:
+        message: A summary message describing what was changed in document
+    
+    Returns:
+        Dict with 'ok' (bool) and 'message' (str)
+    """
+    logger.info(f"  ✅ attempt_completion | {message}")
+    return {
+        "ok": True,
+        "message": message
+    }
+
+
+# ============ REAL IMPLEMENTATIONS ============
+
+@tool
+async def _replace_html(doc_text: str, search: str, replace: str, expected_matches: int = 1) -> Dict[str, Any]:
+    """
+    Replace an exact block of HTML text in the document (real implementation).
+    
+    This tool performs exact string matching on the HTML content.
+    It's critical that the 'search' parameter matches exactly (including whitespace, tags, and attributes).
+    
+    Args:
+        doc_text: The HTML document content
+        search: The exact HTML block to replace (must match exactly, including whitespace)
+        replace: The exact HTML block to insert
+        expected_matches: Expected number of occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    """
+    logger.info(f"  🔧 replace_html | search:{len(search)}b | replace:{len(replace)}b | expect:{expected_matches}")
+    
+    # Count exact matches
+    m = doc_text.count(search) if search else 0
+    
+    if m != expected_matches:
+        error = f"Search not found. Expected {expected_matches}, found {m}"
+        logger.warning(f"  ❌ {error}")
+        return {
+            "ok": False,
+            "error": error,
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nHTML must match EXACTLY and your search pattern has unexpected number of matches"
+        }
+    
+    # Perform replacement
+    new_text = doc_text.replace(search, replace, expected_matches)
+    
+    # Validate result with BeautifulSoup
+    is_valid, validation_error = await _validate_html(new_text)
+    if not is_valid:
+        logger.warning(f"  ❌ Validation failed: {validation_error}")
+        return {
+            "ok": False,
+            "error": f"Invalid HTML: {validation_error}",
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
+        }
+    
+    logger.info(f"  ✅ Success | +{len(new_text)-len(doc_text)}b")
+    return {
+        "ok": True,
+        "doc_text": new_text,
+        "matches": m
+    }
+
+
+@tool
+async def _add_html(doc_text: str, anchor_search: str, insert: str,
+                   position: Literal["before", "after"] = "after", 
+                   expected_matches: int = 1) -> Dict[str, Any]:
+    """
+    Add HTML content before or after an anchor block in the document (real implementation).
+    
+    This tool finds an exact anchor block and inserts new content adjacent to it.
+    Useful for adding new paragraphs, sections, or elements.
+    
+    Args:
+        doc_text: The HTML document content
+        anchor_search: The exact HTML block to find (must match exactly)
+        insert: The exact HTML block to insert
+        position: "before" or "after" (default: "after")
+        expected_matches: Expected number of anchor occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    """
+    logger.info(f"  🔧 add_html | anchor:{len(anchor_search)}b | insert:{len(insert)}b | pos:{position} | expect:{expected_matches}")
+    
+    # Count exact matches of anchor
+    m = doc_text.count(anchor_search) if anchor_search else 0
+    
+    if m != expected_matches:
+        error = f"Anchor not found. Expected {expected_matches}, found {m}"
+        logger.warning(f"  ❌ {error}")
+        return {
+            "ok": False,
+            "error": error,
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nAnchor must match EXACTLY, and your search pattern has unexpected number of matches"
+        }
+    
+    # Insert before or after anchor
+    if position == "before":
+        new_text = doc_text.replace(anchor_search, insert + anchor_search, 1)
+    else:  # after
+        new_text = doc_text.replace(anchor_search, anchor_search + insert, 1)
+    
+    # Validate result with BeautifulSoup
+    is_valid, validation_error = await _validate_html(new_text)
+    if not is_valid:
+        logger.warning(f"  ❌ Validation failed: {validation_error}")
+        return {
+            "ok": False,
+            "error": f"Invalid HTML: {validation_error}",
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
+        }
+    
+    logger.info(f"  ✅ Success | +{len(new_text)-len(doc_text)}b")
+    return {
+        "ok": True,
+        "doc_text": new_text,
+        "matches": m
+    }
+
+
+@tool
+async def _delete_html(doc_text: str, search: str, expected_matches: int = 1) -> Dict[str, Any]:
+    """
+    Delete an exact block of HTML from document (real implementation).
+    
+    This is a convenience wrapper around replace_html with an empty replacement.
+    Useful for removing unwanted sections, clauses, or content.
+    
+    Args:
+        doc_text: The HTML document content
+        search: The exact HTML block to delete (must match exactly)
+        expected_matches: Expected number of occurrences (default: 1)
+    
+    Returns:
+        Dict with 'ok' (bool), 'doc_text' (updated HTML), 'matches' (int),
+        and optionally 'error' (str) if something went wrong
+    """
+    logger.info(f"  🔧 delete_html | search:{len(search)}b | expect:{expected_matches}")
+    
+    # Count exact matches
+    m = doc_text.count(search) if search else 0
+    
+    if m != expected_matches:
+        error = f"Search not found. Expected {expected_matches}, found {m}"
+        logger.warning(f"  ❌ {error}")
+        return {
+            "ok": False,
+            "error": error,
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{error}\nHTML must match EXACTLY and your search pattern has unexpected number of matches"
+        }
+    
+    # Perform replacement with empty string
+    new_text = doc_text.replace(search, "", expected_matches)
+    
+    # Validate result with BeautifulSoup
+    is_valid, validation_error = await _validate_html(new_text)
+    if not is_valid:
+        logger.warning(f"  ❌ Validation failed: {validation_error}")
+        return {
+            "ok": False,
+            "error": f"Invalid HTML: {validation_error}",
+            "matches": m,
+            "DANGER_PANEL": f"⚠️⚠️⚠️ MODIFICATION FAILED ⚠️⚠️⚠️\n{validation_error}"
+        }
+    
+    logger.info(f"  ✅ Success | -{len(doc_text)-len(new_text)}b")
+    return {
+        "ok": True,
+        "doc_text": new_text,
+        "matches": m
+    }
+
+
+@tool
+async def _view_current_document(doc_text: str) -> Dict[str, Any]:
+    """
+    View the current state of the document being edited (real implementation).
+    
+    Use this tool to see the current document content after modifications.
+    This helps you verify previous edits and understand the current structure.
+    
+    Args:
+        doc_text: The HTML document content (injected from state)
+    
+    Returns:
+        Dict with 'ok' (bool) and 'content' (str) containing the HTML document
+    """
+    logger.info(f"  🔍 view_current_document ({len(doc_text)}b)")
+    return {
+        "ok": True,
+        "content": doc_text
+    }
+
+
+@tool
+async def _attempt_completion(message: str) -> Dict[str, Any]:
+    """
+    Signal that document editing is complete and provide a summary message (real implementation).
+    
+    This tool should be called when all requested modifications have been
+    successfully applied to document.
+    
+    Args:
+        message: A summary message describing what was changed in document
+    
+    Returns:
+        Dict with 'ok' (bool) and 'message' (str)
+    """
+    logger.info(f"  ✅ attempt_completion | {message}")
+    return {
+        "ok": True,
+        "message": message
+    }
+
+
+
+
 # Export tool sets for different user types
-tools_for_client_facade = [query_knowledge_graph, find_lawyers, message_lawyer, search_web]
-tools_for_client = [_query_knowledge_graph, _find_lawyers, _message_lawyer, search_web ]
-tools_for_lawyer_facade = [query_knowledge_graph, search_web, retrieve_lawyer_document]
-tools_for_lawyer = [_query_knowledge_graph, search_web, _retrieve_lawyer_document]
+tools_for_client_facade = [query_knowledge_graph, find_lawyers, message_lawyer, search_web, create_draft_document]
+tools_for_client = [_query_knowledge_graph, _find_lawyers, _message_lawyer, search_web, _create_draft_document]
+tools_for_lawyer_facade = [query_knowledge_graph, search_web, retrieve_lawyer_document, create_draft_document]
+tools_for_lawyer = [_query_knowledge_graph, search_web, _retrieve_lawyer_document, _create_draft_document]
 
 # Tools for DocAssistant (document router)
-tools_for_doc_facade = [query_knowledge_graph, retrieve_lawyer_document, edit_document]
-tools_for_doc = [_query_knowledge_graph, _retrieve_lawyer_document, _edit_document]
+tools_for_doc_assistant_facade = [query_knowledge_graph, retrieve_lawyer_document, edit_document]
+tools_for_doc_assistant = [_query_knowledge_graph, _retrieve_lawyer_document, _edit_document]
+
+tools_for_doc_editor_facade = [replace_html, add_html, delete_html, view_current_document, attempt_completion]
+tools_for_doc_editor = [_replace_html, _add_html, _delete_html, _view_current_document, _attempt_completion]
 
 tools = tools_for_client

utils/utils.py

@@ -1,92 +0,0 @@
-#!/usr/bin/env python3
-"""
-Utility functions for agent operations
-"""
-
-import time
-from typing import Tuple
-import logging
-
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-class PerformanceMonitor:
-    """
-    Monitor agent performance and timing
-    """
-    
-    def __init__(self):
-        self.metrics = {}
-    
-    def start_timer(self, operation: str) -> None:
-        """
-        Start timing an operation
-        """
-        self.metrics[f"{operation}_start"] = time.time()
-    
-    def end_timer(self, operation: str) -> float:
-        """
-        End timing an operation and return duration
-        """
-        start_time = self.metrics.get(f"{operation}_start")
-        if start_time:
-            duration = time.time() - start_time
-            self.metrics[f"{operation}_duration"] = duration
-            return duration
-        return 0.0
-    
-    def get_metrics(self) -> dict:
-        """
-        Get all collected metrics
-        """
-        return self.metrics.copy()
-    
-    def reset(self) -> None:
-        """
-        Reset all metrics
-        """
-        self.metrics.clear()
-
-
-def validate_query(query: str) -> Tuple[bool, str]:
-    """
-    Validate user query
-    """
-    if not query or not query.strip():
-        return False, "Query cannot be empty."
-    
-    if len(query) > 2500:
-        return False, "Query is too long. Please keep it under 1000 characters."
-    
-    return True, None
-
-
-def format_error_message(error: str) -> str:
-    """
-    Format error messages for user display
-    """
-    error_map = {
-        "Server unreachable": "❌ The legal database is currently unavailable. Please try again in a moment.",
-        "timeout": "❌ The request timed out. Please try again.",
-        "invalid json": "❌ There was an issue processing the response. Please try again.",
-        "health check failed": "❌ The system is initializing. Please wait a moment and try again."
-    }
-    
-    for key, message in error_map.items():
-        if key.lower() in error.lower():
-            return message
-    
-    return f"❌ An error occurred: {error}"
-
-
-def create_safe_filename(query: str, timestamp: str) -> str:
-    """
-    Create a safe filename for logging purposes
-    """
-    # Remove problematic characters
-    safe_query = "".join(c for c in query if c.isalnum() or c in (' ', '-', '_')).strip()
-    safe_query = safe_query[:50]  # Limit length
-    
-    return f"{timestamp}_{safe_query}.log"

utils/{update_notifier.py → utils_fn.py}

@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
 """
-Utility for pushing document updates to the external endpoint
+Utility functions for agent operations
 """
 
-import os
+import time
+from typing import Tuple, Optional
 import logging
-from typing import Optional
+import os
 import httpx
-
+# Configure logging
+logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
@@ -103,4 +105,54 @@ async def push_document_update(
         
     except Exception as e:
         logger.error(f"❌ Unexpected error pushing document update for {document_id}: {str(e)}")
-        return False
+        return False
+
+class PerformanceMonitor:
+    """
+    Monitor agent performance and timing
+    """
+    
+    def __init__(self):
+        self.metrics = {}
+    
+    def start_timer(self, operation: str) -> None:
+        """
+        Start timing an operation
+        """
+        self.metrics[f"{operation}_start"] = time.time()
+    
+    def end_timer(self, operation: str) -> float:
+        """
+        End timing an operation and return duration
+        """
+        start_time = self.metrics.get(f"{operation}_start")
+        if start_time:
+            duration = time.time() - start_time
+            self.metrics[f"{operation}_duration"] = duration
+            return duration
+        return 0.0
+    
+    def get_metrics(self) -> dict:
+        """
+        Get all collected metrics
+        """
+        return self.metrics.copy()
+    
+    def reset(self) -> None:
+        """
+        Reset all metrics
+        """
+        self.metrics.clear()
+
+
+def validate_query(query: str) -> Tuple[bool, str]:
+    """
+    Validate user query
+    """
+    if not query or not query.strip():
+        return False, "Query cannot be empty."
+    
+    if len(query) > 2500:
+        return False, "Query is too long. Please keep it under 1000 characters."
+    
+    return True, None