FileIOToolsMixin

{
    "status": "success",
    "file_path": str,
    "content": str,
    "file_type": "python" | "markdown" | "binary" | "text",
    "line_count": int,
    "size_bytes": int,
    # Only for a file with a byte-order mark, which is read as text in that
    # encoding (PowerShell 5.1 `>` writes UTF-16): "utf-16" | "utf-32" | "utf-8-sig"
    "encoding": str,

    # Python files only
    "is_valid": bool,
    "errors": List[str],
    "symbols": [{"name": str, "type": str, "line": int}],

    # Markdown files only
    "headers": List[str],
    "code_blocks": [{"language": str, "code": str}],
    "links": [{"text": str, "url": str}],

    # Binary files only
    "is_binary": bool
}

{
    "status": "success",
    "file_path": str,
    "file_type": "docx" | "pdf" | "xlsx",
    "content": str,             # PDF text carries [Page N], Excel [Sheet: name]
    "offset": int,
    "total_chars": int,
    "next_offset": int | None,  # None once the end is reached
    "pages": int,               # PDF only
    "sheets": int,              # Excel only
    "warning": str,             # Excel formulas with no saved value, which read as blank
    "note": str,                # present while more remains: where to continue
    "hint": str,                # first part of a document over 3 reads: retrieval is cheaper
}

{
    "status": "success",
    "file_path": str,
    "bytes_written": int,
    "line_count": int
}

{
    "status": "success",
    "file_path": str,
    "diff": str,
    "backup_created": bool,
    "would_change": bool  # For dry_run
}

{
    "status": "success",
    "pattern": str,
    "directory": str,
    "files_searched": int,
    "files_with_matches": int,
    "results": [
        {
            "file": str,
            "matches": [
                # A line over 200 chars is cut to a window around the
                # match, with "..." marking each cut.
                {"line": int, "content": str}
            ]
        }
    ]
}

{
    "status": "success",
    "file_path": str,
    "diff": str,
    "additions": int,
    "deletions": int,
    "has_changes": bool
}

{
    "status": "success",
    "file_path": str,
    "size_bytes": int,
    "file_type": str
}

{
    "status": "success",
    "file_path": str,
    "old_size": int,
    "new_size": int,
    "file_type": str,
    "diff": str
}

{
    "status": "error",
    "error": str,           # names the file and says to read it
    "error_type": "not_read" | "changed_since_read",
    "file_path": str,
    "executed": False       # stopped before it ran
}

{
    "status": "error",
    "error": str,           # names the cause and the fix
    "match_count": int,     # 0 = not found, >1 = ambiguous
    "match_lines": [int],   # ambiguous only
    "matches": [dict],      # ambiguous only: line + surrounding context
    "current_content": str, # excerpt around the target region
    "current_content_start_line": int,
    "current_content_end_line": int,
    "current_content_total_lines": int
}

{
    "status": "success",
    "file_path": str,
    "function_replaced": str,
    "backup_path": str,
    "diff": str
}

{
    "status": "success",
    "file_path": str,
    "size_bytes": int,
}

{
    "status": "success",
    "file_path": str,
    "updated_sections": List[str],
}

from gaia.agents.base.agent import Agent
from gaia.agents.tools.file_io_tools import FileIOToolsMixin

class MyAgent(Agent, FileIOToolsMixin):
    def _register_tools(self):
        super()._register_tools()
        self.register_file_io_tools()

agent = MyAgent()

result = agent.read_file("calculator.py")

if result["file_type"] == "python":
    print(f"Valid Python: {result['is_valid']}")
    print(f"Symbols found:")
    for symbol in result["symbols"]:
        print(f"  {symbol['type']} {symbol['name']} at line {symbol['line']}")

code = '''
def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two integers."""
    return a + b
'''

result = agent.write_python_file(
    file_path="src/calculator.py",
    content=code,
    validate=True,
    create_dirs=True
)

if result["status"] == "success":
    print(f"Wrote {result['bytes_written']} bytes to {result['file_path']}")

result = agent.edit_python_file(
    file_path="src/calculator.py",
    old_content="return a + b",
    new_content="return int(a) + int(b)  # Ensure integers",
    backup=True
)

print("Changes:")
print(result["diff"])

result = agent.search_code(
    directory="src",
    pattern="TODO",
    file_extension=".py",
    max_results=50
)

print(f"Found {result['files_with_matches']} files with TODOs:")
for file_result in result["results"]:
    print(f"\n{file_result['file']}:")
    for match in file_result["matches"]:
        print(f"  Line {match['line']}: {match['content']}")

# Write TypeScript without validation
result = agent.write_file(
    file_path="src/components/Button.tsx",
    content=tsx_code,
    create_dirs=True
)

# Edit TypeScript file
result = agent.edit_file(
    file_path="src/components/Button.tsx",
    old_content="export default Button",
    new_content="export { Button }"
)

is_allowed, reason = self.path_validator.validate_read(file_path)
if not is_allowed:
    return {"status": "error", "error": reason}

# Typically configured when the agent is constructed
path_validator = PathValidator(
    allowed_paths=[
        "/path/to/workspace",
        "/path/to/report.pdf",
    ]
)

import ast
import difflib
import os
from typing import Any, Dict, Optional

from gaia.agents.base.tools import tool

def test_read_python_file(tmp_path):
    """Test reading Python file with analysis."""
    file_path = tmp_path / "test.py"
    file_path.write_text("def hello(): pass")

    result = read_file(str(file_path))

    assert result["status"] == "success"
    assert result["file_type"] == "python"
    assert result["is_valid"]
    assert len(result["symbols"]) == 1
    assert result["symbols"][0]["name"] == "hello"

def test_write_python_with_validation(tmp_path):
    """Test writing with syntax validation."""
    file_path = tmp_path / "test.py"

    # Valid code
    result = write_python_file(
        str(file_path),
        "x = 1 + 2",
        validate=True
    )
    assert result["status"] == "success"

    # Invalid code
    result = write_python_file(
        str(file_path),
        "x = 1 +",
        validate=True
    )
    assert result["status"] == "error"
    assert "syntax_errors" in result

def test_search_code(tmp_path):
    """Test code search."""
    # Create test files
    (tmp_path / "file1.py").write_text("# TODO: fix this\ndef func(): pass")
    (tmp_path / "file2.py").write_text("x = 1")

    result = search_code(
        str(tmp_path),
        "TODO",
        ".py"
    )

    assert result["status"] == "success"
    assert result["files_with_matches"] == 1
    assert "file1.py" in result["results"][0]["file"]