@_vrsen/openswarm 0.1.0

package/docs_agent/tools/ListDocuments.py

@@ -0,0 +1,134 @@
+"""List all documents in a project."""
+
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+
+from .utils.doc_file_utils import get_project_dir, get_mnt_dir
+
+
+
+class ListDocuments(BaseTool):
+    """
+    List all documents in a project folder.
+    
+    Shows all .source.html files (the canonical source) along with their
+    associated .docx files and any converted formats (PDF, MD, TXT).
+    
+    Use this tool to:
+    - See what documents exist in a project
+    - Check file sizes and formats
+    - Verify document creation
+    - Browse available documents before reading/editing
+    """
+    
+    project_name: str = Field(
+        ...,
+        description="Name of the project folder to list documents from"
+    )
+
+    def run(self):
+        """List all documents in the project."""
+        try:
+            project_dir = get_project_dir(self.project_name)
+
+            if not project_dir.exists():
+                mnt_dir = get_mnt_dir()
+                if mnt_dir.exists():
+                    projects = [d.name for d in mnt_dir.iterdir() if d.is_dir() and (d / "documents").exists()]
+                    if projects:
+                        projects_list = "\n  - ".join(projects)
+                        return f"""Error: Project '{self.project_name}' not found.
+
+Available projects:
+  - {projects_list}"""
+                    else:
+                        return f"""Error: Project '{self.project_name}' not found.
+
+No projects exist yet. Create a document first using CreateDocument tool."""
+                else:
+                    return f"""Error: Project '{self.project_name}' not found.
+
+No projects directory exists yet. Create a document first using CreateDocument tool."""
+            
+            source_files = list(project_dir.glob("*.source.html"))
+            
+            if not source_files:
+                return f"""Project: {self.project_name}
+Path: {project_dir}
+
+No documents found in this project.
+
+Use CreateDocument tool to create a new document."""
+            
+            documents = []
+
+            for source_file in sorted(source_files):
+                doc_name = source_file.name.replace(".source.html", "")
+                lines = [f"  {len(documents) + 1}. {doc_name}"]
+                lines.append(f"    Source: {source_file.name} ({source_file.stat().st_size:,} bytes)")
+
+                # All DOCX exports: base + versioned (_v2, _v3, …), skip Word lock files (~$…)
+                docx_exports = sorted(
+                    f for f in project_dir.glob(f"{doc_name}*.docx")
+                    if not f.name.startswith("~$")
+                )
+                if docx_exports:
+                    lines.append("    Exports:")
+                    for docx in docx_exports:
+                        snapshot = project_dir / f"{docx.name}.snapshot.html"
+                        snapshot_flag = " [snapshot]" if snapshot.exists() else ""
+                        lines.append(
+                            f"      - {docx.name} ({docx.stat().st_size:,} bytes){snapshot_flag}"
+                        )
+                else:
+                    lines.append("    Exports: none (use ConvertDocument to generate)")
+
+                # Other converted formats (PDF, MD, TXT)
+                others = []
+                for ext, label in [(".pdf", "PDF"), (".md", "Markdown"), (".txt", "TXT")]:
+                    f = project_dir / f"{doc_name}{ext}"
+                    if f.exists():
+                        others.append(f"{label} ({f.stat().st_size:,} bytes)")
+                if others:
+                    lines.append(f"    Other formats: {', '.join(others)}")
+
+                documents.append("\n".join(lines))
+
+            return (
+                f"Project: {self.project_name}\n"
+                f"Path: {project_dir}\n\n"
+                f"Documents ({len(documents)}):\n\n"
+                + "\n\n".join(documents)
+            )
+            
+        except Exception as e:
+            return f"Error listing documents: {str(e)}"
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("TEST: ListDocuments Tool")
+    print("=" * 70)
+    print()
+    
+    print("Setup: Creating test documents...")
+    
+    # Test 1: List documents in project
+    print("Test 1: Listing documents in test_list project...")
+    tool = ListDocuments(project_name="test_list")
+    print(tool.run())
+    print()
+    
+    # Test 2: List documents in non-existent project
+    print("Test 2: Attempting to list non-existent project...")
+    tool = ListDocuments(project_name="nonexistent_project")
+    print(tool.run())
+    print()
+    
+    # Test 3: List documents in empty project
+    print("Test 3: Listing documents in empty project...")
+    empty_dir = get_project_dir("empty_project")
+    empty_dir.mkdir(parents=True, exist_ok=True)
+    
+    tool = ListDocuments(project_name="empty_project")
+    print(tool.run())

package/docs_agent/tools/ModifyDocument.py

@@ -0,0 +1,247 @@
+"""Multi-purpose document editing tool supporting targeted search-and-replace and line operations."""
+
+import traceback
+from pathlib import Path
+from typing import Any, Literal, Optional
+
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+
+from .utils.doc_file_utils import get_project_dir
+from .utils.html_validation import build_unsupported_error, find_unsupported_html
+
+
+class ModifyDocument(BaseTool):
+    """
+    Edit a document's HTML source.
+
+    Supports two modes:
+
+    **search_and_replace** (preferred for targeted edits):
+    Provide a list of {old_content, new_content} pairs. Each old_content is matched
+    exactly against the file — like StrReplace. Use a snippet that is unique enough to
+    identify the target (can be short or long). Replacements apply sequentially; if one
+    fails, the rest are skipped and the file is not modified.
+
+    **Line operations** (for structural additions/deletions):
+    - replace: replace a line range with new content
+    - insert: insert content before/after a line
+    - delete: remove a line range
+
+    Always call ViewDocument first to see the current content and line numbers.
+    The DOCX is not regenerated on edit — call ConvertDocument when ready to export.
+    """
+
+    project_name: str = Field(
+        ...,
+        description="Name of the project folder containing the document.",
+    )
+
+    document_name: str = Field(
+        ...,
+        description="Name of the document to edit (without extension).",
+    )
+
+    operation: Literal["search_and_replace", "replace", "insert", "delete"] = Field(
+        ...,
+        description=(
+            "Edit mode:\n"
+            "- 'search_and_replace': batch exact-match replacements (preferred)\n"
+            "- 'replace': replace lines start_line–end_line with new_content\n"
+            "- 'insert': insert new_content before/after start_line\n"
+            "- 'delete': delete lines start_line–end_line"
+        ),
+    )
+
+    # --- search_and_replace fields ---
+    replacements: Optional[list[dict[str, Any]]] = Field(
+        default=None,
+        description=(
+            "Required for 'search_and_replace'. List of {old_content, new_content} dicts.\n"
+            "Each old_content is matched exactly against the file (like StrReplace).\n"
+            "Use a snippet that uniquely identifies the target — any length is fine.\n"
+            "Replacements apply in order; the first failure stops the batch.\n\n"
+            "Example:\n"
+            '  [{"old_content": "#C8102E", "new_content": "#DA291C"},\n'
+            '   {"old_content": "<h1>Old Title</h1>", "new_content": "<h1>New Title</h1>"}]'
+        ),
+    )
+
+    # --- line operation fields ---
+    start_line: Optional[int] = Field(
+        default=None,
+        description="Starting line number (1-based). Required for line operations.",
+    )
+
+    end_line: Optional[int] = Field(
+        default=None,
+        description="Ending line number (inclusive). Required for 'replace' and 'delete'.",
+    )
+
+    new_content: Optional[str] = Field(
+        default=None,
+        description="New HTML content. Required for 'replace' and 'insert'.",
+    )
+
+    after: bool = Field(
+        default=False,
+        description="For 'insert' only: insert AFTER start_line instead of before.",
+    )
+
+    def run(self) -> str:
+        try:
+            project_dir = get_project_dir(self.project_name)
+            if not project_dir.exists():
+                return f"Error: Project '{self.project_name}' not found."
+
+            doc_name = (
+                self.document_name.replace(".html", "").replace(".docx", "").replace(".md", "")
+            )
+            source_path = project_dir / f"{doc_name}.source.html"
+            md_path = project_dir / f"{doc_name}.md"
+
+            if not source_path.exists() and not md_path.exists():
+                return f"Error: Document '{doc_name}' not found in project '{self.project_name}'."
+
+            editing_markdown = not source_path.exists()
+            current_content = (
+                md_path.read_text(encoding="utf-8")
+                if editing_markdown
+                else source_path.read_text(encoding="utf-8")
+            )
+
+            if self.operation == "search_and_replace":
+                return self._search_and_replace(current_content, source_path, md_path, editing_markdown)
+
+            lines = current_content.split("\n")
+            total_lines = len(lines)
+
+            if self.operation == "replace":
+                return self._replace_lines(lines, total_lines, doc_name, source_path, md_path, editing_markdown)
+            if self.operation == "insert":
+                return self._insert_lines(lines, total_lines, doc_name, source_path, md_path, editing_markdown)
+            if self.operation == "delete":
+                return self._delete_lines(lines, total_lines, doc_name, source_path, md_path, editing_markdown)
+
+            return f"Error: Unknown operation '{self.operation}'."
+
+        except Exception as e:
+            return f"Error modifying document: {type(e).__name__}: {e}\n{traceback.format_exc()}"
+
+    # ── search_and_replace ────────────────────────────────────────────────────
+
+    def _search_and_replace(self, content: str, source_path: Path, md_path: Path, editing_markdown: bool) -> str:
+        if not self.replacements:
+            return "Error: 'replacements' is required for search_and_replace operation."
+
+        updated = content
+        for i, item in enumerate(self.replacements, start=1):
+            old = item.get("old_content", "")
+            new = item.get("new_content", "")
+            if old not in updated:
+                snippet = old[:80].replace("\n", "↵")
+                return (
+                    f"Error: replacement #{i} — 'old_content' not found in document.\n"
+                    f"Snippet: '{snippet}'\n"
+                    f"Tip: copy a shorter or more unique fragment directly from ViewDocument output and retry."
+                )
+            updated = updated.replace(old, new, 1)
+
+        error = self._validate_and_save(updated, source_path, md_path, editing_markdown)
+        if error:
+            return error
+
+        count = len(self.replacements)
+        return f"Applied {count} replacement{'s' if count != 1 else ''} to '{source_path.name}'."
+
+    # ── line operations ───────────────────────────────────────────────────────
+
+    def _replace_lines(self, lines, total_lines, doc_name, source_path, md_path, editing_markdown):
+        if not self.new_content:
+            return "Error: 'new_content' is required for replace operation."
+        if not self.end_line:
+            return "Error: 'end_line' is required for replace operation."
+        if not self.start_line:
+            return "Error: 'start_line' is required for replace operation."
+
+        if self.start_line < 1 or self.start_line > total_lines:
+            return f"Error: Invalid start_line {self.start_line}. Document has {total_lines} lines."
+        if self.end_line < self.start_line or self.end_line > total_lines:
+            return f"Error: Invalid end_line {self.end_line}. Must be >= start_line and <= {total_lines}."
+
+        start_idx, end_idx = self.start_line - 1, self.end_line
+        lines_removed = end_idx - start_idx
+        del lines[start_idx:end_idx]
+        lines.insert(start_idx, self.new_content)
+
+        error = self._validate_and_save("\n".join(lines), source_path, md_path, editing_markdown)
+        if error:
+            return error
+
+        net = len(lines) - total_lines
+        return (
+            f"Replaced lines {self.start_line}–{self.end_line} in '{doc_name}'.\n"
+            f"Removed {lines_removed} lines, added {len(self.new_content.splitlines())}. "
+            f"Net: {'+' if net >= 0 else ''}{net}. Total: {len(lines)} lines."
+        )
+
+    def _insert_lines(self, lines, total_lines, doc_name, source_path, md_path, editing_markdown):
+        if not self.new_content:
+            return "Error: 'new_content' is required for insert operation."
+        if not self.start_line:
+            return "Error: 'start_line' is required for insert operation."
+
+        if self.start_line < 1 or self.start_line > total_lines + 1:
+            return f"Error: Invalid start_line {self.start_line}. Valid range: 1–{total_lines + 1}."
+
+        insert_idx = self.start_line if self.after else self.start_line - 1
+        lines.insert(insert_idx, self.new_content)
+
+        error = self._validate_and_save("\n".join(lines), source_path, md_path, editing_markdown)
+        if error:
+            return error
+
+        position = f"after line {self.start_line}" if self.after else f"before line {self.start_line}"
+        return (
+            f"Inserted content {position} in '{doc_name}'. "
+            f"Added {len(self.new_content.splitlines())} line(s). Total: {len(lines)} lines."
+        )
+
+    def _delete_lines(self, lines, total_lines, doc_name, source_path, md_path, editing_markdown):
+        if not self.end_line:
+            return "Error: 'end_line' is required for delete operation."
+        if not self.start_line:
+            return "Error: 'start_line' is required for delete operation."
+
+        if self.start_line < 1 or self.start_line > total_lines:
+            return f"Error: Invalid start_line {self.start_line}. Document has {total_lines} lines."
+        if self.end_line < self.start_line or self.end_line > total_lines:
+            return f"Error: Invalid end_line {self.end_line}. Must be >= start_line and <= {total_lines}."
+
+        start_idx, end_idx = self.start_line - 1, self.end_line
+        deleted = end_idx - start_idx
+        del lines[start_idx:end_idx]
+
+        error = self._validate_and_save("\n".join(lines), source_path, md_path, editing_markdown)
+        if error:
+            return error
+
+        return (
+            f"Deleted lines {self.start_line}–{self.end_line} from '{doc_name}'. "
+            f"Removed {deleted} line(s). Total: {len(lines)} lines."
+        )
+
+    # ── shared save ──────────────────────────────────────────────────────────
+
+    def _validate_and_save(self, content: str, source_path: Path, md_path: Path, editing_markdown: bool) -> str | None:
+        """Write content to disk. Returns an error string on failure, None on success."""
+        if editing_markdown:
+            md_path.write_text(content, encoding="utf-8")
+            return None
+
+        issues = find_unsupported_html(content)
+        if issues:
+            return build_unsupported_error(issues)
+
+        source_path.write_text(content, encoding="utf-8")
+        return None

package/docs_agent/tools/RestoreDocument.py

@@ -0,0 +1,79 @@
+"""Restore an HTML document source from a previous DOCX export snapshot."""
+
+from pathlib import Path
+
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+
+from .utils.doc_file_utils import get_project_dir
+
+
+class RestoreDocument(BaseTool):
+    """
+    Restore the working HTML source of a document to the state it was in at
+    a previous DOCX export.
+
+    Every time ConvertDocument produces a .docx it automatically saves a
+    companion snapshot alongside it:
+
+        report.docx
+        report.docx.snapshot.html   ← HTML source at time of that export
+        report_v2.docx
+        report_v2.docx.snapshot.html
+
+    This tool reads the snapshot for the requested DOCX version and writes
+    it back as the canonical <document>.source.html, ready for further edits
+    or re-conversion.
+
+    To list available versions use ListDocuments — each .docx file in the
+    project is one export.
+    """
+
+    project_name: str = Field(
+        ...,
+        description="Name of the project folder containing the document.",
+    )
+    docx_filename: str = Field(
+        ...,
+        description=(
+            "Filename of the DOCX export to restore from, e.g. 'report.docx' "
+            "or 'report_v2.docx'. The file must exist in the project folder."
+        ),
+    )
+
+    def run(self) -> str:
+        project_dir = get_project_dir(self.project_name)
+        docx_name = (
+            self.docx_filename
+            if self.docx_filename.endswith(".docx")
+            else f"{self.docx_filename}.docx"
+        )
+        snapshot_path = project_dir / f"{docx_name}.snapshot.html"
+
+        if not snapshot_path.exists():
+            available = sorted(
+                p.name for p in project_dir.glob("*.docx.snapshot.html")
+            )
+            hint = (
+                "\nAvailable snapshots:\n" + "\n".join(f"  {s}" for s in available)
+                if available
+                else "\nNo snapshots found in this project."
+            )
+            return f"Error: No snapshot found for '{docx_name}'.{hint}"
+
+        doc_name = Path(docx_name).stem
+        doc_name = _strip_version(doc_name)
+        source_path = project_dir / f"{doc_name}.source.html"
+
+        source_path.write_text(snapshot_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+        return (
+            f"Restored '{doc_name}' to the version captured in '{docx_name}'.\n"
+            f"Working source: {source_path}"
+        )
+
+
+def _strip_version(stem: str) -> str:
+    """Remove trailing _vN suffix so report_v2 → report."""
+    import re
+    return re.sub(r"_v\d+$", "", stem)

package/docs_agent/tools/ViewDocument.py

@@ -0,0 +1,153 @@
+"""View document content from HTML source."""
+
+from typing import Optional, List
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+
+from .utils.doc_file_utils import get_project_dir
+
+
+class ViewDocument(BaseTool):
+    """
+    View the content of an existing document (reads from .source.html file).
+    
+    This tool reads the HTML source file which is the canonical source of truth.
+    Optionally specify a line range to view only part of the document.
+    
+    Use this tool to:
+    - Read existing document content before editing
+    - Check document structure and formatting
+    - Verify specific sections of a document
+    """
+    
+    project_name: str = Field(
+        ...,
+        description="Name of the project folder containing the document"
+    )
+    
+    document_name: str = Field(
+        ...,
+        description="Name of the document to view (without extension)"
+    )
+    
+    view_range: Optional[List[int]] = Field(
+        default=None,
+        description="Optional line range [start_line, end_line] (1-based, inclusive). If not provided, shows entire document. Example: [1, 50] shows first 50 lines."
+    )
+
+    def run(self):
+        """View document content."""
+        try:
+            project_dir = get_project_dir(self.project_name)
+
+            if not project_dir.exists():
+                return f"Error: Project '{self.project_name}' not found."
+
+            doc_name = (
+                self.document_name.replace(".html", "")
+                .replace(".docx", "")
+                .replace(".md", "")
+            )
+            source_path = project_dir / f"{doc_name}.source.html"
+            docx_path = project_dir / f"{doc_name}.docx"
+            md_path = project_dir / f"{doc_name}.md"
+            
+            if not source_path.exists() and not md_path.exists():
+                return f"Error: Document '{doc_name}' not found in project '{self.project_name}'."
+            
+            if source_path.exists():
+                content = source_path.read_text(encoding="utf-8")
+            else:
+                content = md_path.read_text(encoding="utf-8")
+            lines = content.split('\n')
+            total_lines = len(lines)
+
+            if self.view_range:
+                if len(self.view_range) != 2:
+                    return "❌ Error: view_range must be a list of exactly 2 integers [start_line, end_line]"
+
+                start_line, end_line = self.view_range
+
+                if start_line < 1 or end_line < start_line or start_line > total_lines:
+                    return f"Error: Invalid line range [{start_line}, {end_line}]. Document has {total_lines} lines."
+
+                start_idx = start_line - 1  # 1-based → 0-based
+                end_idx = min(end_line, total_lines)
+                
+                selected_lines = lines[start_idx:end_idx]
+                content_to_show = '\n'.join(selected_lines)
+                
+                range_info = f"Lines {start_line}-{end_idx} of {total_lines}"
+            else:
+                content_to_show = content
+                range_info = f"All {total_lines} lines"
+            
+            source_size = source_path.stat().st_size if source_path.exists() else md_path.stat().st_size
+            docx_exists = docx_path.exists()
+            docx_info = (
+                f"\n  - {docx_path.name} exists"
+                if docx_exists
+                else f"\n  - {docx_path.name} NOT FOUND (needs regeneration)"
+            )
+            
+            return f"""# Document: {doc_name}
+Project: {self.project_name}
+Source: {(source_path.name if source_path.exists() else md_path.name)} ({source_size:,} bytes){docx_info}
+Viewing: {range_info}
+
+---
+
+{content_to_show}"""
+            
+        except Exception as e:
+            return f"Error viewing document: {str(e)}"
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("TEST: ViewDocument Tool")
+    print("=" * 70)
+    print()
+    
+    # First, create a test document to view
+    from CreateDocument import CreateDocument
+    
+    print("Setup: Creating test document...")
+    html_content = """<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Test Document</title>
+</head>
+<body>
+    <h1>Test Document Title</h1>
+    <p>This is line 1 of content.</p>
+    <p>This is line 2 of content.</p>
+    <p>This is line 3 of content.</p>
+    <p>This is line 4 of content.</p>
+    <p>This is line 5 of content.</p>
+    <h2>Section 2</h2>
+    <p>More content here in section 2.</p>
+    <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+        <li>Item 3</li>
+    </ul>
+</body>
+</html>"""
+    
+    create_tool = CreateDocument(
+        project_name="test_view",
+        document_name="sample_doc",
+        content={"type": "html", "value": html_content},
+        overwrite=True
+    )
+    print(create_tool.run())
+    print()
+
+    tool = ViewDocument(
+        project_name="test_view",
+        document_name="sample_doc",
+        view_range=[1, 10]
+    )
+    print(tool.run())

package/docs_agent/tools/__init__.py

@@ -0,0 +1 @@
+"""Tools for the agent."""

package/docs_agent/tools/utils/__init__.py

@@ -0,0 +1 @@
+