writeragent_api.py

"""Auto-generated WriterAgent tool proxy API.

Generated by scripts/generate_tool_proxies.py — DO NOT EDIT.
Provides Python-native access to WriterAgent tools from venv subprocess scripts.
"""
import os
import sys
import threading
import uuid
from plugin.scripting.ipc import read_pickle_frame, write_pickle_frame


# Detect if running in-process (LibreOffice host) or out-of-process (Venv worker)
IS_WORKER = os.environ.get("WRITERAGENT_IS_WORKER") == "1"

# ── RPC transport ──────────────────────────────────────────────
_lock = threading.Lock()


def _rpc_call(tool_name: str, **kwargs) -> dict:
    """Send a tool call to the LibreOffice host and block for the result."""
    if not IS_WORKER:
        try:
            from plugin.framework.uno_context import get_ctx, get_active_document
            from plugin.doc.document_helpers import is_calc, is_writer, is_draw
            from plugin.main import get_tools
            from plugin.framework.tool import ToolContext

            uno_ctx = get_ctx()
            doc = get_active_document(uno_ctx)
            if not doc:
                raise RuntimeError("No active document found to run tool")

            if is_calc(doc):
                doc_type = "calc"
            elif is_writer(doc):
                doc_type = "writer"
            elif is_draw(doc):
                doc_type = "draw"
            else:
                doc_type = ""

            registry = get_tools()
            tctx = ToolContext(
                doc=doc,
                ctx=uno_ctx,
                doc_type=doc_type,
                services=registry._services,
                caller="script"
            )
            return registry.execute(tool_name, tctx, **kwargs)
        except Exception as e:
            raise RuntimeError(f"Failed to execute tool in-process: {e}")

    call_id = str(uuid.uuid4())
    request = {"type": "tool_call", "id": call_id, "tool": tool_name, "args": kwargs}
    with _lock:
        write_pickle_frame(sys.stdout.buffer, request)
        # Block and read the response frame from the host on stdin
        response = read_pickle_frame(sys.stdin.buffer, require_dict=True)
        if response is None:
            raise ConnectionError("Lost connection to LibreOffice host during tool call")

    if response.get("status") == "error":
        raise RuntimeError(response.get("message", response.get("error", "Unknown error")))
    return response.get("result", {})


def get_active_document_type() -> str:
    """Return the active document's type ('writer', 'calc', 'draw', or 'unknown')."""
    try:
        res = _rpc_call("list_open_documents")
        for doc in res.get("documents", []):
            if doc.get("is_active"):
                return doc.get("doc_type", "unknown")
    except Exception:
        pass
    return "unknown"


DOMAIN_TOOLS = {   'analysi': [   'analyze_data',
                   'calc_goal_seek',
                   'calc_solver',
                   'forecast_data',
                   'optimize_data',
                   'plot_data',
                   'query_folder_sql'],
    'bookmark': [   'cleanup_bookmarks',
                    'create_bookmark',
                    'delete_bookmark',
                    'get_bookmark',
                    'list_bookmarks',
                    'rename_bookmark',
                    'resolve_bookmark'],
    'brainstorming': ['brainstorm_research_web', 'save_design_spec'],
    'calc': [   'delegate_to_specialized_calc_toolset',
                'delete_structure',
                'get_sheet_summary',
                'insert_cell_html',
                'list_calc_functions',
                'merge_cells',
                'read_cell_range',
                'set_style',
                'write_formula_range'],
    'chart': ['delete_chart', 'get_chart_info', 'list_charts', 'manage_charts', 'upsert_chart'],
    'comment': [   'add_cell_comment',
                   'delete_cell_comment',
                   'delete_comment',
                   'list_cell_comments',
                   'list_comments',
                   'resolve_comment',
                   'workflow'],
    'conditional_formatting': ['add_conditional_format', 'list_conditional_formats', 'remove_conditional_formats'],
    'core': [   'find_tools',
                'get_guidance',
                'list_open_documents',
                'redo',
                'report_bug',
                'specialized_workflow_finished',
                'undo',
                'upsert_memory',
                'web_research'],
    'deep_research': ['deep_research_web'],
    'document_research': ['delegate_read_document', 'grep_nearby_files', 'list_nearby_files', 'search_nearby_files'],
    'draw': [   'add_slide',
                'delegate_to_specialized_draw_toolset',
                'delete_slide',
                'get_draw_tree',
                'get_placeholder_text',
                'get_presentation_info',
                'list_pages',
                'list_placeholders',
                'read_slide_text',
                'set_active_page',
                'set_placeholder_text'],
    'embedded': ['embedded_edit', 'embedded_insert'],
    'error': ['detect_and_explain_errors', 'evaluate_formula'],
    'field': ['fields_delete', 'fields_insert', 'fields_list', 'fields_update_all', 'update_fields'],
    'footnote': [   'footnotes_delete',
                    'footnotes_edit',
                    'footnotes_insert',
                    'footnotes_list',
                    'footnotes_settings_get',
                    'footnotes_settings_update'],
    'forms': [   'create_form',
                 'create_form_control',
                 'delete_form_control',
                 'edit_form_control',
                 'generate_form',
                 'list_form_controls'],
    'headers_footer': ['get_headers_footers', 'set_headers_footers'],
    'images': [   'delete_image',
                  'download_image',
                  'generate_image',
                  'get_image_info',
                  'insert_image',
                  'list_images',
                  'list_nearby_image_files',
                  'replace_image',
                  'set_image_properties'],
    'indexe': ['indexes_add_mark', 'indexes_create', 'indexes_list', 'indexes_update_all', 'refresh_indexes'],
    'math': ['insert_math'],
    'page': [   'get_header_footer_text',
                'get_page_columns',
                'get_page_style_properties',
                'insert_page_break',
                'set_header_footer_text',
                'set_page_columns',
                'set_page_style_properties'],
    'pivot_table': ['create_pivot_table', 'list_pivot_tables', 'refresh_pivot_table'],
    'ppt-master': [   'apply_ppt_master_native_enhance',
                      'apply_ppt_master_template_fill',
                      'export_presentation_project',
                      'validate_ppt_master_project'],
    'python': ['run_venv_python_script', 'symbolic_math'],
    'range': ['add_named_range', 'delete_named_range', 'list_named_ranges', 'sort_range'],
    'search': ['replace_in_spreadsheet', 'search_in_spreadsheet'],
    'shape': [   'delete_shape',
                 'get_draw_summary',
                 'list_writer_images',
                 'shapes_connect',
                 'shapes_group',
                 'upsert_shape'],
    'sheet': [   'apply_sheet_filter',
                 'clear_sheet_filter',
                 'create_sheet',
                 'delete_sheet',
                 'get_sheet_filter',
                 'list_sheets',
                 'protect_sheet',
                 'rename_sheet',
                 'switch_sheet'],
    'slide_master': ['get_slide_master', 'list_master_slides', 'set_slide_master'],
    'slide_transition': ['get_slide_layout', 'get_slide_transition', 'set_slide_layout', 'set_slide_transition'],
    'speaker_note': ['get_speaker_notes', 'set_speaker_notes'],
    'structural': [   'get_heading_children',
                      'get_surroundings',
                      'goto_page',
                      'list_sections',
                      'navigate_heading',
                      'read_section'],
    'styles': ['create_style', 'get_style_info', 'import_styles', 'list_styles', 'update_style'],
    'table': [   'delete_table_column',
                 'delete_table_row',
                 'get_table_cells',
                 'insert_table_column',
                 'insert_table_row',
                 'list_tables',
                 'set_table_cell'],
    'textframe': ['get_text_frame_info', 'list_text_frames', 'set_text_frame_properties'],
    'tracking': [   'track_changes_accept',
                    'track_changes_accept_all',
                    'track_changes_comment_delete',
                    'track_changes_comment_insert',
                    'track_changes_comment_list',
                    'track_changes_list',
                    'track_changes_reject',
                    'track_changes_reject_all',
                    'track_changes_show',
                    'track_changes_start',
                    'track_changes_stop'],
    'vision': ['extract_text_from_image'],
    'writer': [   'add_comment',
                  'apply_document_content',
                  'apply_style',
                  'delegate_to_specialized_writer_toolset',
                  'get_document_content',
                  'get_document_tree',
                  'get_image',
                  'get_page_objects',
                  'search_in_document',
                  'set_selection'],
    'writing_plan': ['write_document_section', 'writing_research_web']}


class _AnalysiProxy:
    """Proxy for analysi tools."""

    def analyze_data(self, helper: str, *, params: dict = {}, data_range: str = "", output_range: str = "", headers: bool = True, task_hint: str = "", auto_plot: bool = True) -> dict:
        """Run a trusted numpy/pandas analysis helper on spreadsheet data."""
        return _rpc_call("analyze_data", helper=helper, params=params, data_range=data_range, output_range=output_range, headers=headers, task_hint=task_hint, auto_plot=auto_plot)

    def calc_goal_seek(self, formula_cell: str, variable_cell: str, target_value: float, *, apply_result: bool = True) -> dict:
        """Finds the value for a variable cell that makes a formula cell reach a target value.."""
        return _rpc_call("calc_goal_seek", formula_cell=formula_cell, variable_cell=variable_cell, target_value=target_value, apply_result=apply_result)

    def calc_solver(self, objective_cell: str, variables: list, *, maximize: bool = True, constraints: list = [], engine: str = "") -> dict:
        """Solves an optimization problem to maximize, minimize, or reach a value for an objective cell by changing multiple variable cells subject to constraints.."""
        return _rpc_call("calc_solver", objective_cell=objective_cell, variables=variables, maximize=maximize, constraints=constraints, engine=engine)

    def forecast_data(self, helper: str, *, params: dict = {}, data_range: str = "", output_range: str = "", headers: bool = True, task_hint: str = "") -> dict:
        """Run a trusted time-series forecasting helper on spreadsheet data."""
        return _rpc_call("forecast_data", helper=helper, params=params, data_range=data_range, output_range=output_range, headers=headers, task_hint=task_hint)

    def optimize_data(self, helper: str, *, params: dict = {}, data_range: str = "", output_range: str = "", headers: bool = True, task_hint: str = "") -> dict:
        """Run a trusted optimization helper on spreadsheet data."""
        return _rpc_call("optimize_data", helper=helper, params=params, data_range=data_range, output_range=output_range, headers=headers, task_hint=task_hint)

    def plot_data(self, helper: str, *, params: dict = {}, data_range: str = "", headers: bool = True, task_hint: str = "") -> dict:
        """Run a trusted visualization helper on spreadsheet data."""
        return _rpc_call("plot_data", helper=helper, params=params, data_range=data_range, headers=headers, task_hint=task_hint)

    def query_folder_sql(self, sql: str, *, files: list = [], data_range: str = "", headers: bool = True, tables: dict = {}, task_hint: str = "") -> dict:
        """Run read-only SQL (via DuckDB) against folder files and/or live Calc ranges (Phase C multi-table)."""
        return _rpc_call("query_folder_sql", sql=sql, files=files, data_range=data_range, headers=headers, tables=tables, task_hint=task_hint)

analysi = _AnalysiProxy()


class _BookmarkProxy:
    """Proxy for bookmark tools."""

    def cleanup_bookmarks(self) -> dict:
        """Remove all _mcp_* bookmarks from the document."""
        return _rpc_call("cleanup_bookmarks")

    def create_bookmark(self, name: str) -> dict:
        """Create a new bookmark at the current cursor or selection in Writer."""
        return _rpc_call("create_bookmark", name=name)

    def delete_bookmark(self, name: str) -> dict:
        """Delete an existing bookmark by its name.."""
        return _rpc_call("delete_bookmark", name=name)

    def get_bookmark(self, name: str) -> dict:
        """Get details about a specific bookmark, including the text it spans.."""
        return _rpc_call("get_bookmark", name=name)

    def list_bookmarks(self) -> dict:
        """List all bookmarks in the document with their anchor text preview."""
        return _rpc_call("list_bookmarks")

    def rename_bookmark(self, old_name: str, new_name: str) -> dict:
        """Rename an existing bookmark.."""
        return _rpc_call("rename_bookmark", old_name=old_name, new_name=new_name)

    def resolve_bookmark(self, bookmark_name: str) -> dict:
        """Resolve a bookmark to its current paragraph index and text."""
        return _rpc_call("resolve_bookmark", bookmark_name=bookmark_name)

bookmark = _BookmarkProxy()


class _BrainstormingProxy:
    """Proxy for brainstorming tools."""

    def brainstorm_research_web(self, query: str) -> dict:
        """Search the public web for context during brainstorming."""
        return _rpc_call("brainstorm_research_web", query=query)

    def save_design_spec(self, content: list, *, target: str = "") -> dict:
        """Save the approved design spec to the active Writer document."""
        return _rpc_call("save_design_spec", content=content, target=target)

brainstorming = _BrainstormingProxy()


class _CalcProxy:
    """Proxy for calc tools."""

    def delegate_to_specialized_calc_toolset(self, domain: str, task: str) -> dict:
        """Delegates a specialized Calc task."""
        return _rpc_call("delegate_to_specialized_calc_toolset", domain=domain, task=task)

    def delete_structure(self, structure_type: str, start: str, *, count: int = 0) -> dict:
        """Deletes rows or columns."""
        return _rpc_call("delete_structure", structure_type=structure_type, start=start, count=count)

    def get_sheet_summary(self, *, sheet_name: str = "") -> dict:
        """Returns a comprehensive summary of the active or specified sheet: used area, column headers, charts, merged cells, annotations, and shapes.."""
        return _rpc_call("get_sheet_summary", sheet_name=sheet_name)

    def insert_cell_html(self, cell_address: str, html: str) -> dict:
        """Parses HTML with the same filter as Writer and pastes rich text into one cell on the active sheet (e.g."""
        return _rpc_call("insert_cell_html", cell_address=cell_address, html=html)

    def list_calc_functions(self, *, filter: str = "") -> dict:
        """Lists available Calc spreadsheet functions."""
        return _rpc_call("list_calc_functions", filter=filter)

    def merge_cells(self, range_name: list, *, center: bool = True) -> dict:
        """Merges the specified cell range(s)."""
        return _rpc_call("merge_cells", range_name=range_name, center=center)

    def read_cell_range(self, range_name: list) -> dict:
        """Reads values from the specified cell range(s)."""
        return _rpc_call("read_cell_range", range_name=range_name)

    def set_style(self, range_name: list, *, bold: bool = True, italic: bool = True, font_size: float = 0.0, bg_color: str = "", font_color: str = "", h_align: str = "", v_align: str = "", wrap_text: bool = True, border_color: str = "", number_format: str = "") -> dict:
        """Applies style and formatting to the specified cell(s) or range(s)."""
        return _rpc_call("set_style", range_name=range_name, bold=bold, italic=italic, font_size=font_size, bg_color=bg_color, font_color=font_color, h_align=h_align, v_align=v_align, wrap_text=wrap_text, border_color=border_color, number_format=number_format)

    def write_formula_range(self, range_name: list, formula_or_values: str) -> dict:
        """Writes formulas or values to a cell range(s) efficiently."""
        return _rpc_call("write_formula_range", range_name=range_name, formula_or_values=formula_or_values)

calc = _CalcProxy()


class _ChartProxy:
    """Proxy for chart tools."""

    def delete_chart(self, chart_name: str) -> dict:
        """Delete a chart by name.."""
        return _rpc_call("delete_chart", chart_name=chart_name)

    def get_chart_info(self, chart_name: str) -> dict:
        """Get detailed info about a chart: type, title, ranges (if Calc), axis titles, and legend properties.."""
        return _rpc_call("get_chart_info", chart_name=chart_name)

    def list_charts(self) -> dict:
        """List all charts in the current context (active sheet, document, or slide) with name, title, and type.."""
        return _rpc_call("list_charts")

    def manage_charts(self, action: str, *, chart_name: str = "", data_range: str = "", headers: list = [], rows: list = [], chart_type: str = "", title: str = "", subtitle: str = "", is_3d: bool = True, stacked: bool = True, percent: bool = True, x_axis_title: str = "", y_axis_title: str = "", legend_position: str = "", has_legend: bool = True, position: str = "", bg_color: str = "", colors: list = []) -> dict:
        """Manage charts: list, get_info, create, edit, or delete a chart in the current context (active sheet, document, or slide).."""
        return _rpc_call("manage_charts", action=action, chart_name=chart_name, data_range=data_range, headers=headers, rows=rows, chart_type=chart_type, title=title, subtitle=subtitle, is_3d=is_3d, stacked=stacked, percent=percent, x_axis_title=x_axis_title, y_axis_title=y_axis_title, legend_position=legend_position, has_legend=has_legend, position=position, bg_color=bg_color, colors=colors)

    def upsert_chart(self, action: str, *, chart_name: str = "", data_range: str = "", headers: list = [], rows: list = [], chart_type: str = "", title: str = "", is_3d: bool = True, stacked: bool = True, percent: bool = True, x_axis_title: str = "", y_axis_title: str = "", legend_position: str = "", has_legend: bool = True, subtitle: str = "", position: str = "", bg_color: str = "", colors: list = []) -> dict:
        """Creates a new chart or modifies an existing chart on a sheet, document, or slide.."""
        return _rpc_call("upsert_chart", action=action, chart_name=chart_name, data_range=data_range, headers=headers, rows=rows, chart_type=chart_type, title=title, is_3d=is_3d, stacked=stacked, percent=percent, x_axis_title=x_axis_title, y_axis_title=y_axis_title, legend_position=legend_position, has_legend=has_legend, subtitle=subtitle, position=position, bg_color=bg_color, colors=colors)

chart = _ChartProxy()


class _CommentProxy:
    """Proxy for comment tools."""

    def add_cell_comment(self, cell: str, text: str, *, sheet_name: str = "") -> dict:
        """Add a comment (annotation) to a specific cell in a Calc sheet.."""
        return _rpc_call("add_cell_comment", cell=cell, text=text, sheet_name=sheet_name)

    def delete_cell_comment(self, cell: str, *, sheet_name: str = "") -> dict:
        """Delete the comment (annotation) from a specific cell.."""
        return _rpc_call("delete_cell_comment", cell=cell, sheet_name=sheet_name)

    def delete_comment(self, *, comment_name: str = "", author: str = "") -> dict:
        """Delete comments by name or author."""
        return _rpc_call("delete_comment", comment_name=comment_name, author=author)

    def list_cell_comments(self, *, sheet_name: str = "") -> dict:
        """List all cell comments (annotations) in a Calc sheet."""
        return _rpc_call("list_cell_comments", sheet_name=sheet_name)

    def list_comments(self, *, author_filter: str = "") -> dict:
        """List all comments/annotations in the document, including author, content, date, resolved status, and anchor preview."""
        return _rpc_call("list_comments", author_filter=author_filter)

    def resolve_comment(self, comment_name: str, *, resolution: str = "", author: str = "") -> dict:
        """Resolve a comment with an optional reason."""
        return _rpc_call("resolve_comment", comment_name=comment_name, resolution=resolution, author=author)

    def workflow(self, action: str, *, unresolved_only: bool = True, prefix_filter: str = "", content: str = "") -> dict:
        """Workflow and task operations."""
        return _rpc_call("workflow", action=action, unresolved_only=unresolved_only, prefix_filter=prefix_filter, content=content)

comment = _CommentProxy()


class _ConditionalFormattingProxy:
    """Proxy for conditional_formatting tools."""

    def add_conditional_format(self, range_name: str, operator: str, style_name: str, *, formula1: str = "", formula2: str = "") -> dict:
        """Add a conditional formatting rule to a Calc cell range."""
        return _rpc_call("add_conditional_format", range_name=range_name, operator=operator, formula1=formula1, formula2=formula2, style_name=style_name)

    def list_conditional_formats(self, *, range_name: str = "") -> dict:
        """List conditional formatting rules on a Calc cell range."""
        return _rpc_call("list_conditional_formats", range_name=range_name)

    def remove_conditional_formats(self, range_name: str, *, rule_index: int = 0) -> dict:
        """Remove a conditional formatting rule from a Calc cell range by index, or clear all rules if no index is provided."""
        return _rpc_call("remove_conditional_formats", range_name=range_name, rule_index=rule_index)

conditional_formatting = _ConditionalFormattingProxy()


class _CoreProxy:
    """Proxy for core tools."""

    def find_tools(self, *, domain: str = "") -> dict:
        """Discover additional tools that are available but not listed here."""
        return _rpc_call("find_tools", domain=domain)

    def get_guidance(self, *, topic: str = "") -> dict:
        """Read WriterAgent's how-to-use manual on demand."""
        return _rpc_call("get_guidance", topic=topic)

    def list_open_documents(self) -> dict:
        """List all currently open documents in LibreOffice."""
        return _rpc_call("list_open_documents")

    def redo(self, *, steps: int = 0) -> dict:
        """Redo the last undone change(s) in the document (all document types)."""
        return _rpc_call("redo", steps=steps)

    def report_bug(self, summary: str, *, details: str = "", category: str = "") -> dict:
        """Report a WriterAgent bug or bad experience — the agent itself may call this when a tool misbehaves, returns a confusing result, or the workflow felt wrong."""
        return _rpc_call("report_bug", summary=summary, details=details, category=category)

    def specialized_workflow_finished(self, answer: str) -> dict:
        """Provides a final answer to the given task and exits the specialized toolset mode.."""
        return _rpc_call("specialized_workflow_finished", answer=answer)

    def undo(self, *, steps: int = 0) -> dict:
        """Undo the last change(s) in the document (all document types)."""
        return _rpc_call("undo", steps=steps)

    def upsert_memory(self, key: str, content: str) -> dict:
        """Persistent memory for the agent."""
        return _rpc_call("upsert_memory", key=key, content=content)

    def web_research(self, query: str, *, history_text: str = "") -> dict:
        """Perform deep web research to answer complex questions."""
        return _rpc_call("web_research", query=query, history_text=history_text)

core = _CoreProxy()


class _DeepResearchProxy:
    """Proxy for deep_research tools."""

    def web(self, query: str) -> dict:
        """Run breadth/depth public web research on a topic."""
        return _rpc_call("deep_research_web", query=query)

deep_research = _DeepResearchProxy()


class _DocumentResearchProxy:
    """Proxy for document_research tools."""

    def delegate_read_document(self, path_or_name: str, task: str) -> dict:
        """Open a nearby file by path or basename (read-only, hidden) and run a read-only sub-agent with production read tools for that file type."""
        return _rpc_call("delegate_read_document", path_or_name=path_or_name, task=task)

    def grep_nearby_files(self, pattern: str, *, file_subset: str = "", regex: bool = True, case_sensitive: bool = True) -> dict:
        """Search nearby LibreOffice files for text and return snippet previews per matching file."""
        return _rpc_call("grep_nearby_files", pattern=pattern, file_subset=file_subset, regex=regex, case_sensitive=case_sensitive)

    def list_nearby_files(self, *, filter: str = "", file_kind: str = "") -> dict:
        """List files in the same folder as the active document (newest first)."""
        return _rpc_call("list_nearby_files", filter=filter, file_kind=file_kind)

    def search_nearby_files(self, query: str, *, k: int = 0, near_slop: int = 0, file_subset: str = "") -> dict:
        """Search the active folder index (keyword BM25/NEAR + semantic embeddings, fused ranking)."""
        return _rpc_call("search_nearby_files", query=query, k=k, near_slop=near_slop, file_subset=file_subset)

document_research = _DocumentResearchProxy()


class _DrawProxy:
    """Proxy for draw tools."""

    def add_slide(self, *, page_index: int = 0, switch_to_new_slide: bool = True) -> dict:
        """Inserts a new slide (page) at the specified index.."""
        return _rpc_call("add_slide", page_index=page_index, switch_to_new_slide=switch_to_new_slide)

    def delegate_to_specialized_draw_toolset(self, domain: str, task: str) -> dict:
        """Delegates a specialized Draw task."""
        return _rpc_call("delegate_to_specialized_draw_toolset", domain=domain, task=task)

    def delete_slide(self, page_index: int) -> dict:
        """Deletes the slide (page) at the specified index.."""
        return _rpc_call("delete_slide", page_index=page_index)

    def get_draw_tree(self, *, page_index: int = 0) -> dict:
        """Returns a semantic tree (DOM) of the shapes on the active or specified draw page."""
        return _rpc_call("get_draw_tree", page_index=page_index)

    def get_placeholder_text(self, *, role: str = "", shape_index: int = 0, page_index: int = 0) -> dict:
        """Get text from a slide placeholder."""
        return _rpc_call("get_placeholder_text", role=role, shape_index=shape_index, page_index=page_index)

    def get_presentation_info(self) -> dict:
        """Get presentation metadata: slide count, dimensions, master slide names, and whether it is an Impress document.."""
        return _rpc_call("get_presentation_info")

    def list_pages(self) -> dict:
        """Lists all pages (slides) in the document.."""
        return _rpc_call("list_pages")

    def list_placeholders(self, *, page_index: int = 0) -> dict:
        """List all text placeholders on a slide with their role (title, subtitle, body), text content, and shape index.."""
        return _rpc_call("list_placeholders", page_index=page_index)

    def read_slide_text(self, *, page_index: int = 0) -> dict:
        """Read all text content from a slide (shapes text) and speaker notes."""
        return _rpc_call("read_slide_text", page_index=page_index)

    def set_active_page(self, page_index: int) -> dict:
        """Changes the currently active slide (page) in Draw/Impress.."""
        return _rpc_call("set_active_page", page_index=page_index)

    def set_placeholder_text(self, text: str, *, role: str = "", shape_index: int = 0, page_index: int = 0) -> dict:
        """Set text on a slide placeholder."""
        return _rpc_call("set_placeholder_text", text=text, role=role, shape_index=shape_index, page_index=page_index)

draw = _DrawProxy()


class _EmbeddedProxy:
    """Proxy for embedded tools."""

    def edit(self, *, name: str = "") -> dict:
        """Activate or edit an embedded OLE object (planned).."""
        return _rpc_call("embedded_edit", name=name)

    def insert(self, *, object_type: str = "", target: str = "", old_content: str = "") -> dict:
        """Insert an embedded object (e.g."""
        return _rpc_call("embedded_insert", object_type=object_type, target=target, old_content=old_content)

embedded = _EmbeddedProxy()


class _ErrorProxy:
    """Proxy for error tools."""

    def detect_and_explain_errors(self, *, range_name: list = []) -> dict:
        """Detects formula errors in the specified range(s) and provides an explanation and fix suggestion."""
        return _rpc_call("detect_and_explain_errors", range_name=range_name)

    def evaluate_formula(self, formula: str, *, cell: str = "") -> dict:
        """Evaluates a Calc formula on a temporary duplicate sheet and returns the result or error, without modifying the active sheets.."""
        return _rpc_call("evaluate_formula", formula=formula, cell=cell)

error = _ErrorProxy()


class _FieldProxy:
    """Proxy for field tools."""

    def delete(self, ids: list) -> dict:
        """Deletes one or more text fields from the document by their 1-based ID."""
        return _rpc_call("fields_delete", ids=ids)

    def insert(self, field_type: str, *, properties: dict = {}, target: str = "", old_content: str = "") -> dict:
        """Insert a text field at the specified target position."""
        return _rpc_call("fields_insert", field_type=field_type, properties=properties, target=target, old_content=old_content)

    def list(self) -> dict:
        """List all text fields in the document."""
        return _rpc_call("fields_list")

    def update_all(self) -> dict:
        """Refresh all text fields (dates, page numbers, cross-references)."""
        return _rpc_call("fields_update_all")

    def update_fields(self) -> dict:
        """Refresh all text fields."""
        return _rpc_call("update_fields")

field = _FieldProxy()


class _FootnoteProxy:
    """Proxy for footnote tools."""

    def delete(self, note_type: str, index: int) -> dict:
        """Deletes an existing footnote or endnote based on its index (from footnotes_list).."""
        return _rpc_call("footnotes_delete", note_type=note_type, index=index)

    def edit(self, note_type: str, index: int, *, text: str = "", label: str = "") -> dict:
        """Edits an existing footnote or endnote."""
        return _rpc_call("footnotes_edit", note_type=note_type, index=index, text=text, label=label)

    def insert(self, note_type: str, text: str, *, label: str = "", insert_after_text: str = "", occurrence: int = 0, case_sensitive: bool = True) -> dict:
        """Inserts a new footnote or endnote."""
        return _rpc_call("footnotes_insert", note_type=note_type, text=text, label=label, insert_after_text=insert_after_text, occurrence=occurrence, case_sensitive=case_sensitive)

    def list(self, note_type: str) -> dict:
        """Lists all existing footnotes or endnotes in the document, including their indices, labels (if custom), and text content."""
        return _rpc_call("footnotes_list", note_type=note_type)

    def settings_get(self, note_type: str) -> dict:
        """Gets the current formatting and numbering settings for footnotes or endnotes."""
        return _rpc_call("footnotes_settings_get", note_type=note_type)

    def settings_update(self, note_type: str, properties: dict) -> dict:
        """Updates the formatting and numbering settings for footnotes or endnotes."""
        return _rpc_call("footnotes_settings_update", note_type=note_type, properties=properties)

footnote = _FootnoteProxy()


class _FormsProxy:
    """Proxy for forms tools."""

    def create_form(self, fields: list) -> dict:
        """Creates multiple form controls at once from a list of field definitions."""
        return _rpc_call("create_form", fields=fields)

    def create_form_control(self, type: str, name: str, *, label: str = "", group_name: str = "", items: list = [], placeholder: str = "", default_value: str = "", width: int = 0, height: int = 0) -> dict:
        """Creates a single interactive form control (checkbox, text field, radio button, date field, combobox, or button)."""
        return _rpc_call("create_form_control", type=type, label=label, name=name, group_name=group_name, items=items, placeholder=placeholder, default_value=default_value, width=width, height=height)

    def delete_form_control(self, shape_index: int) -> dict:
        """Deletes a form control by shape index (Calc: active sheet draw page).."""
        return _rpc_call("delete_form_control", shape_index=shape_index)

    def edit_form_control(self, shape_index: int, *, name: str = "", label: str = "", text: str = "", items: list = [], x: int = 0, y: int = 0, width: int = 0, height: int = 0) -> dict:
        """Modifies an existing form control by index (from list_form_controls)."""
        return _rpc_call("edit_form_control", shape_index=shape_index, name=name, label=label, text=text, items=items, x=x, y=y, width=width, height=height)

    def generate_form(self, description: str) -> dict:
        """Generates a document or sheet layout with interactive form fields from a description."""
        return _rpc_call("generate_form", description=description)

    def list_form_controls(self) -> dict:
        """Lists interactive form controls (checkboxes, text fields, etc.) with indices and values."""
        return _rpc_call("list_form_controls")

forms = _FormsProxy()


class _HeadersFooterProxy:
    """Proxy for headers_footer tools."""

    def get_headers_footers(self, page_index: int, *, is_master_page: bool = True) -> dict:
        """Retrieves header, footer, date/time, and slide number configuration for a specific slide or master page in a presentation.."""
        return _rpc_call("get_headers_footers", page_index=page_index, is_master_page=is_master_page)

    def set_headers_footers(self, page_index: int, *, is_master_page: bool = True, header_text: str = "", footer_text: str = "", date_time_text: str = "", is_header_visible: bool = True, is_footer_visible: bool = True, is_page_number_visible: bool = True, is_date_time_visible: bool = True, is_date_time_fixed: bool = True) -> dict:
        """Updates header, footer, date/time, and slide number configuration for a specific slide or master page in a presentation.."""
        return _rpc_call("set_headers_footers", page_index=page_index, is_master_page=is_master_page, header_text=header_text, footer_text=footer_text, date_time_text=date_time_text, is_header_visible=is_header_visible, is_footer_visible=is_footer_visible, is_page_number_visible=is_page_number_visible, is_date_time_visible=is_date_time_visible, is_date_time_fixed=is_date_time_fixed)

headers_footer = _HeadersFooterProxy()


class _ImagesProxy:
    """Proxy for images tools."""

    def delete_image(self, image_name: str, *, remove_frame: bool = True) -> dict:
        """Delete an image from the document.."""
        return _rpc_call("delete_image", image_name=image_name, remove_frame=remove_frame)

    def download_image(self, url: str, *, verify_ssl: bool = True, force: bool = True) -> dict:
        """Download an image from URL to local cache."""
        return _rpc_call("download_image", url=url, verify_ssl=verify_ssl, force=force)

    def generate_image(self, prompt: str, *, source_image: str = "", strength: float = 0.75, aspect_ratio: str = 'square', base_size: int = 512, width: int = 0, height: int = 0, provider: str = "", image_model: str = "") -> dict:
        """Generate an image from a text prompt and insert it."""
        return _rpc_call("generate_image", prompt=prompt, source_image=source_image, strength=strength, aspect_ratio=aspect_ratio, base_size=base_size, width=width, height=height, provider=provider, image_model=image_model)

    def get_image_info(self, image_name: str) -> dict:
        """Get detailed info about a specific image: URL, dimensions, anchor type, orientation, crop (crop_mm, mm trimmed per edge), and paragraph index.."""
        return _rpc_call("get_image_info", image_name=image_name)

    def insert_image(self, image_path: str, *, locator: str = "", paragraph_index: int = 0, width_mm: int = 0, height_mm: int = 0) -> dict:
        """Insert an image from local path or URL into the document."""
        return _rpc_call("insert_image", image_path=image_path, locator=locator, paragraph_index=paragraph_index, width_mm=width_mm, height_mm=height_mm)

    def list_images(self) -> dict:
        """List all images/graphic objects in the document with name, dimensions, title, and description.."""
        return _rpc_call("list_images")

    def list_nearby_image_files(self, *, filter: str = "") -> dict:
        """List image files (.png, .jpg, .jpeg, .gif, .webp, .bmp, .svg) in the same folder as the active document (newest first)."""
        return _rpc_call("list_nearby_image_files", filter=filter)

    def replace_image(self, image_name: str, new_image_path: str, *, width_mm: float = 0.0, height_mm: float = 0.0) -> dict:
        """Replace an image's source file keeping position and frame.."""
        return _rpc_call("replace_image", image_name=image_name, new_image_path=new_image_path, width_mm=width_mm, height_mm=height_mm)

    def set_image_properties(self, image_name: str, *, width_mm: float = 0.0, height_mm: float = 0.0, title: str = "", description: str = "", anchor_type: int = 0, hori_orient: str = "", vert_orient: str = "", crop_top_mm: float = 0.0, crop_bottom_mm: float = 0.0, crop_left_mm: float = 0.0, crop_right_mm: float = 0.0) -> dict:
        """Resize, reposition, crop, or update caption/alt-text for an image."""
        return _rpc_call("set_image_properties", image_name=image_name, width_mm=width_mm, height_mm=height_mm, title=title, description=description, anchor_type=anchor_type, hori_orient=hori_orient, vert_orient=vert_orient, crop_top_mm=crop_top_mm, crop_bottom_mm=crop_bottom_mm, crop_left_mm=crop_left_mm, crop_right_mm=crop_right_mm)

images = _ImagesProxy()


class _IndexeProxy:
    """Proxy for indexe tools."""

    def add_mark(self, mark_text: str, *, index_kind: str = "", primary_key: str = "", secondary_key: str = "", target: str = "", old_content: str = "") -> dict:
        """Add an index mark (e.g."""
        return _rpc_call("indexes_add_mark", mark_text=mark_text, index_kind=index_kind, primary_key=primary_key, secondary_key=secondary_key, target=target, old_content=old_content)

    def create(self, index_kind: str, *, title: str = "", create_from_outline: bool = True, target: str = "", old_content: str = "") -> dict:
        """Create a new document index (e.g."""
        return _rpc_call("indexes_create", index_kind=index_kind, title=title, create_from_outline=create_from_outline, target=target, old_content=old_content)

    def list(self) -> dict:
        """List all document indexes (table of contents, alphabetical index, bibliography, etc.).."""
        return _rpc_call("indexes_list")

    def refresh_indexes(self) -> dict:
        """Refresh all document indexes (TOC, bibliography, etc.)."""
        return _rpc_call("refresh_indexes")

    def update_all(self) -> dict:
        """Refresh/update all document indexes (table of contents, bibliography, etc.).."""
        return _rpc_call("indexes_update_all")

indexe = _IndexeProxy()


class _MathProxy:
    """Proxy for math tools."""

    def insert_math(self, formula_type: str, formula: str, page_index: int, x: int, y: int) -> dict:
        """Inserts an editable LibreOffice Math formula on a Draw or Impress page."""
        return _rpc_call("insert_math", formula_type=formula_type, formula=formula, page_index=page_index, x=x, y=y)

math = _MathProxy()


class _PageProxy:
    """Proxy for page tools."""

    def get_header_footer_text(self, region: str, *, style_name: str = "") -> dict:
        """Retrieve the text content of a page style's header or footer.."""
        return _rpc_call("get_header_footer_text", style_name=style_name, region=region)

    def get_page_columns(self, *, style_name: str = "") -> dict:
        """Get the column layout for a page style.."""
        return _rpc_call("get_page_columns", style_name=style_name)

    def get_page_style_properties(self, *, style_name: str = "") -> dict:
        """Get dimensions, margins, and header/footer states of a page style.."""
        return _rpc_call("get_page_style_properties", style_name=style_name)

    def insert_page_break(self, *, before_text: str = "", after_text: str = "", occurrence: int = 0, case_sensitive: bool = True) -> dict:
        """Start a new page."""
        return _rpc_call("insert_page_break", before_text=before_text, after_text=after_text, occurrence=occurrence, case_sensitive=case_sensitive)

    def set_header_footer_text(self, region: str, content: str, *, style_name: str = "") -> dict:
        """Set the text content of a page style's header or footer."""
        return _rpc_call("set_header_footer_text", style_name=style_name, region=region, content=content)

    def set_page_columns(self, column_count: int, *, style_name: str = "", spacing_mm: float = 0.0) -> dict:
        """Set the number of columns and spacing for a page style.."""
        return _rpc_call("set_page_columns", style_name=style_name, column_count=column_count, spacing_mm=spacing_mm)

    def set_page_style_properties(self, *, style_name: str = "", width_mm: float = 0.0, height_mm: float = 0.0, is_landscape: bool = True, left_margin_mm: float = 0.0, right_margin_mm: float = 0.0, top_margin_mm: float = 0.0, bottom_margin_mm: float = 0.0, gutter_margin_mm: float = 0.0, header_is_on: bool = True, footer_is_on: bool = True, header_is_shared: bool = True, footer_is_shared: bool = True, header_height_mm: float = 0.0, footer_height_mm: float = 0.0, header_body_distance_mm: float = 0.0, footer_body_distance_mm: float = 0.0, back_color: int = 0, back_transparent: bool = True, numbering_type: int = 0, footnote_height_mm: float = 0.0, register_paragraph_style: str = "", page_style_layout: int = 0) -> dict:
        """Modify dimensions, margins, and header/footer toggles of a page style.."""
        return _rpc_call("set_page_style_properties", style_name=style_name, width_mm=width_mm, height_mm=height_mm, is_landscape=is_landscape, left_margin_mm=left_margin_mm, right_margin_mm=right_margin_mm, top_margin_mm=top_margin_mm, bottom_margin_mm=bottom_margin_mm, gutter_margin_mm=gutter_margin_mm, header_is_on=header_is_on, footer_is_on=footer_is_on, header_is_shared=header_is_shared, footer_is_shared=footer_is_shared, header_height_mm=header_height_mm, footer_height_mm=footer_height_mm, header_body_distance_mm=header_body_distance_mm, footer_body_distance_mm=footer_body_distance_mm, back_color=back_color, back_transparent=back_transparent, numbering_type=numbering_type, footnote_height_mm=footnote_height_mm, register_paragraph_style=register_paragraph_style, page_style_layout=page_style_layout)

page = _PageProxy()


class _PivotTableProxy:
    """Proxy for pivot_table tools."""

    def create_pivot_table(self, pivot_table_name: str, source_range: str, destination_cell: str, data_fields: list, *, source_sheet_name: str = "", destination_sheet_name: str = "", row_fields: list = [], column_fields: list = [], page_fields: list = []) -> dict:
        """Create a pivot table (DataPilot) from a source data range."""
        return _rpc_call("create_pivot_table", pivot_table_name=pivot_table_name, source_range=source_range, source_sheet_name=source_sheet_name, destination_cell=destination_cell, destination_sheet_name=destination_sheet_name, row_fields=row_fields, column_fields=column_fields, data_fields=data_fields, page_fields=page_fields)

    def list_pivot_tables(self, *, sheet_name: str = "") -> dict:
        """List pivot tables in the spreadsheet, optionally limited to one sheet.."""
        return _rpc_call("list_pivot_tables", sheet_name=sheet_name)

    def refresh_pivot_table(self, pivot_table_name: str, *, sheet_name: str = "") -> dict:
        """Reload pivot table data from the source range."""
        return _rpc_call("refresh_pivot_table", pivot_table_name=pivot_table_name, sheet_name=sheet_name)

pivot_table = _PivotTableProxy()


class _PptMasterProxy:
    """Proxy for ppt-master tools."""

    def apply_ppt_master_native_enhance(self, project_path: str) -> dict:
        """Apply ppt-master native enhancement (notes, transitions) from a project folder.."""
        return _rpc_call("apply_ppt_master_native_enhance", project_path=project_path)

    def apply_ppt_master_template_fill(self, fill_plan_path: str) -> dict:
        """Apply a ppt-master fill_plan.json to the active presentation (template-fill route).."""
        return _rpc_call("apply_ppt_master_template_fill", fill_plan_path=fill_plan_path)

    def export_presentation_project(self, project_path: str) -> dict:
        """Export a ppt-master project folder into the active Impress/Draw document by building or loading exports/*.pptx and importing via LibreOffice's native PPTX filter.."""
        return _rpc_call("export_presentation_project", project_path=project_path)

    def validate_ppt_master_project(self, project_path: str) -> dict:
        """Check that a ppt-master project folder has expected artifacts (SVG slides, design spec).."""
        return _rpc_call("validate_ppt_master_project", project_path=project_path)

ppt_master = _PptMasterProxy()


class _PythonProxy:
    """Proxy for python tools."""

    def run_venv_python_script(self, code: str, *, data_range: str = "", data: list = []) -> dict:
        """Run Python code."""
        return _rpc_call("run_venv_python_script", code=code, data_range=data_range, data=data)

    def symbolic_math(self, helper: str, *, params: dict = {}, task_hint: str = "", display_block: bool = True) -> dict:
        """Run a trusted SymPy symbolic math helper."""
        return _rpc_call("symbolic_math", helper=helper, params=params, task_hint=task_hint, display_block=display_block)

python = _PythonProxy()


class _RangeProxy:
    """Proxy for range tools."""

    def add_named_range(self, name: str, content: str) -> dict:
        """Defines a new named range in the workbook.."""
        return _rpc_call("add_named_range", name=name, content=content)

    def delete_named_range(self, name: str) -> dict:
        """Deletes an existing named range by name.."""
        return _rpc_call("delete_named_range", name=name)

    def list_named_ranges(self) -> dict:
        """Lists all named ranges in the workbook and their reference contents.."""
        return _rpc_call("list_named_ranges")

    def sort_range(self, range_name: list, *, sort_column: int = 0, ascending: bool = True, has_header: bool = True) -> dict:
        """Sorts the specified range(s) by a column."""
        return _rpc_call("sort_range", range_name=range_name, sort_column=sort_column, ascending=ascending, has_header=has_header)

range = _RangeProxy()


class _SearchProxy:
    """Proxy for search tools."""

    def in_spreadsheet(self, pattern: str, *, regex: bool = True, case_sensitive: bool = True, max_results: int = 0, sheet_name: str = "", all_sheets: bool = True) -> dict:
        """Search for text or values in a Calc spreadsheet."""
        return _rpc_call("search_in_spreadsheet", pattern=pattern, regex=regex, case_sensitive=case_sensitive, max_results=max_results, sheet_name=sheet_name, all_sheets=all_sheets)

    def replace_in_spreadsheet(self, search: str, replace: str, *, regex: bool = True, case_sensitive: bool = True, sheet_name: str = "", all_sheets: bool = True) -> dict:
        """Find and replace text or values in a Calc spreadsheet."""
        return _rpc_call("replace_in_spreadsheet", search=search, replace=replace, regex=regex, case_sensitive=case_sensitive, sheet_name=sheet_name, all_sheets=all_sheets)

search = _SearchProxy()


class _ShapeProxy:
    """Proxy for shape tools."""

    def connect(self, start_shape_index: int, end_shape_index: int, *, page_index: int = 0, line_color: str = "", line_width: int = 0) -> dict:
        """Connect two shapes on the same page with a connector.."""
        return _rpc_call("shapes_connect", start_shape_index=start_shape_index, end_shape_index=end_shape_index, page_index=page_index, line_color=line_color, line_width=line_width)

    def delete_shape(self, shape_index: int, *, page_index: int = 0) -> dict:
        """Deletes a shape by index.."""
        return _rpc_call("delete_shape", shape_index=shape_index, page_index=page_index)

    def get_draw_summary(self, *, page_index: int = 0) -> dict:
        """Returns a summary of shapes on the active or specified page.."""
        return _rpc_call("get_draw_summary", page_index=page_index)

    def group(self, shape_indices: list, *, page_index: int = 0) -> dict:
        """Groups multiple shapes together on the same page.."""
        return _rpc_call("shapes_group", shape_indices=shape_indices, page_index=page_index)

    def list_writer_images(self) -> dict:
        """List images and graphic objects in the Writer document (names, sizes, titles)."""
        return _rpc_call("list_writer_images")

    def upsert_shape(self, action: str, *, shape_index: int = 0, page_index: int = 0, shape_type: str = "", x: int = 0, y: int = 0, width: int = 0, height: int = 0, text: str = "", bg_color: str = "", fill_color: str = "", fill_style: str = "", line_color: str = "", line_width: int = 0, text_color: str = "", font_size: float = 0.0, font_name: str = "", rotation_angle: float = 0.0) -> dict:
        """Creates a new shape or modifies an existing shape on a page.."""
        return _rpc_call("upsert_shape", action=action, shape_index=shape_index, page_index=page_index, shape_type=shape_type, x=x, y=y, width=width, height=height, text=text, bg_color=bg_color, fill_color=fill_color, fill_style=fill_style, line_color=line_color, line_width=line_width, text_color=text_color, font_size=font_size, font_name=font_name, rotation_angle=rotation_angle)

shape = _ShapeProxy()


class _SheetProxy:
    """Proxy for sheet tools."""

    def apply_sheet_filter(self, range_name: str, criteria: list, *, contains_header: bool = True) -> dict:
        """Hide rows that do not match a standard Calc filter (not conditional formatting)."""
        return _rpc_call("apply_sheet_filter", range_name=range_name, contains_header=contains_header, criteria=criteria)

    def clear_sheet_filter(self, range_name: str, *, contains_header: bool = True) -> dict:
        """Remove the active standard sheet filter on a range so all rows show again."""
        return _rpc_call("clear_sheet_filter", range_name=range_name, contains_header=contains_header)

    def create_sheet(self, sheet_name: str, *, position: int = 0) -> dict:
        """Creates a new sheet.."""
        return _rpc_call("create_sheet", sheet_name=sheet_name, position=position)

    def delete_sheet(self, sheet_name: str) -> dict:
        """Deletes an existing sheet by name.."""
        return _rpc_call("delete_sheet", sheet_name=sheet_name)

    def get_sheet_filter(self, range_name: str) -> dict:
        """Return active filter criteria and contains_header for a range, or empty if none."""
        return _rpc_call("get_sheet_filter", range_name=range_name)

    def list_sheets(self) -> dict:
        """Lists all sheet names in the workbook.."""
        return _rpc_call("list_sheets")

    def protect_sheet(self, *, sheet_name: str = "", protect: bool = True) -> dict:
        """Protects or unprotects a sheet."""
        return _rpc_call("protect_sheet", sheet_name=sheet_name, protect=protect)

    def rename_sheet(self, old_name: str, new_name: str) -> dict:
        """Renames an existing sheet.."""
        return _rpc_call("rename_sheet", old_name=old_name, new_name=new_name)

    def switch_sheet(self, sheet_name: str) -> dict:
        """Switches to the specified sheet (makes it active).."""
        return _rpc_call("switch_sheet", sheet_name=sheet_name)

sheet = _SheetProxy()


class _SlideMasterProxy:
    """Proxy for slide_master tools."""

    def get_slide_master(self, *, page_index: int = 0) -> dict:
        """Get the master slide assigned to a specific slide."""
        return _rpc_call("get_slide_master", page_index=page_index)

    def list_master_slides(self) -> dict:
        """List all master slides (master pages) in the document with name and dimensions.."""
        return _rpc_call("list_master_slides")

    def set_slide_master(self, master_name: str, *, page_index: int = 0) -> dict:
        """Assign a master slide to a specific slide by master name."""
        return _rpc_call("set_slide_master", page_index=page_index, master_name=master_name)

slide_master = _SlideMasterProxy()


class _SlideTransitionProxy:
    """Proxy for slide_transition tools."""

    def get_slide_layout(self, *, page_index: int = 0) -> dict:
        """Get the layout type of an Impress slide."""
        return _rpc_call("get_slide_layout", page_index=page_index)

    def get_slide_transition(self, *, page_index: int = 0) -> dict:
        """Get the transition effect, speed, duration, and advance mode for an Impress slide.."""
        return _rpc_call("get_slide_transition", page_index=page_index)

    def set_slide_layout(self, layout: str, *, page_index: int = 0) -> dict:
        """Set the layout of an Impress slide."""
        return _rpc_call("set_slide_layout", page_index=page_index, layout=layout)

    def set_slide_transition(self, *, page_index: int = 0, effect: str = "", speed: str = "", duration: int = 0, transition_duration: float = 0.0, advance: str = "") -> dict:
        """Set the transition effect on an Impress slide."""
        return _rpc_call("set_slide_transition", page_index=page_index, effect=effect, speed=speed, duration=duration, transition_duration=transition_duration, advance=advance)

slide_transition = _SlideTransitionProxy()


class _SpeakerNoteProxy:
    """Proxy for speaker_note tools."""

    def get_speaker_notes(self, *, page_index: int = 0) -> dict:
        """Read speaker notes from an Impress slide."""
        return _rpc_call("get_speaker_notes", page_index=page_index)

    def set_speaker_notes(self, text: str, *, page_index: int = 0, append: bool = True) -> dict:
        """Set or replace speaker notes on an Impress slide.."""
        return _rpc_call("set_speaker_notes", text=text, page_index=page_index, append=append)

speaker_note = _SpeakerNoteProxy()


class _StructuralProxy:
    """Proxy for structural tools."""

    def get_heading_children(self, *, locator: str = "", heading_para_index: int = 0, heading_bookmark: str = "", content_strategy: str = "", depth: int = 0) -> dict:
        """Drill into a heading's children — body paragraphs and sub-headings."""
        return _rpc_call("get_heading_children", locator=locator, heading_para_index=heading_para_index, heading_bookmark=heading_bookmark, content_strategy=content_strategy, depth=depth)

    def get_surroundings(self, locator: str, *, radius: int = 0, include: list = []) -> dict:
        """Discover objects within a radius of paragraphs around a locator."""
        return _rpc_call("get_surroundings", locator=locator, radius=radius, include=include)

    def goto_page(self, page: int) -> dict:
        """Navigate the view cursor to a specific page.."""
        return _rpc_call("goto_page", page=page)

    def list_sections(self) -> dict:
        """List all named sections in the document.."""
        return _rpc_call("list_sections")

    def navigate_heading(self, locator: str, direction: str) -> dict:
        """Navigate from a locator to a related heading."""
        return _rpc_call("navigate_heading", locator=locator, direction=direction)

    def read_section(self, section_name: str) -> dict:
        """Read the text content of a named section."""
        return _rpc_call("read_section", section_name=section_name)

structural = _StructuralProxy()


class _StylesProxy:
    """Proxy for styles tools."""

    def create_style(self, style_name: str, *, family: str = "", parent_style: str = "", property_updates: dict = {}, conditional_rules: list = []) -> dict:
        """Create a new paragraph or character style with optional inheritance and property settings."""
        return _rpc_call("create_style", style_name=style_name, family=family, parent_style=parent_style, property_updates=property_updates, conditional_rules=conditional_rules)

    def get_style_info(self, style_name: str, *, family: str = "") -> dict:
        """Get detailed properties of a specific style (font, size, margins, etc.).."""
        return _rpc_call("get_style_info", style_name=style_name, family=family)

    def import_styles(self, file_path: str, *, overwrite: bool = True, load_paragraph_styles: bool = True, load_page_styles: bool = False, load_frame_styles: bool = False, load_numbering_styles: bool = False) -> dict:
        """Import styles from an external document or template (.odt, .ott)."""
        return _rpc_call("import_styles", file_path=file_path, overwrite=overwrite, load_paragraph_styles=load_paragraph_styles, load_page_styles=load_page_styles, load_frame_styles=load_frame_styles, load_numbering_styles=load_numbering_styles)

    def list_styles(self, *, family: str = "") -> dict:
        """List available styles in the document."""
        return _rpc_call("list_styles", family=family)

    def update_style(self, style_name: str, *, family: str = "", parent_style: str = "", property_updates: dict = {}) -> dict:
        """Update the properties of an existing style."""
        return _rpc_call("update_style", style_name=style_name, family=family, parent_style=parent_style, property_updates=property_updates)

styles = _StylesProxy()


class _TableProxy:
    """Proxy for table tools."""

    def delete_table_column(self, table_name: str, col_index: int) -> dict:
        """Delete one column from a table by 0-based col_index."""
        return _rpc_call("delete_table_column", table_name=table_name, col_index=col_index)

    def delete_table_row(self, table_name: str, row_index: int) -> dict:
        """Delete one row from a table by 0-based row_index."""
        return _rpc_call("delete_table_row", table_name=table_name, row_index=row_index)

    def get_table_cells(self, table_name: str) -> dict:
        """Return a table's cell text as a row-major matrix (matrix[row][col]) by position — not by cell name."""
        return _rpc_call("get_table_cells", table_name=table_name)

    def insert_table_column(self, table_name: str, col_index: int) -> dict:
        """Insert one empty column into a table."""
        return _rpc_call("insert_table_column", table_name=table_name, col_index=col_index)

    def insert_table_row(self, table_name: str, row_index: int) -> dict:
        """Insert one empty row into a table."""
        return _rpc_call("insert_table_row", table_name=table_name, row_index=row_index)

    def list_tables(self) -> dict:
        """List the text tables in the document with their name and dimensions (rows x columns)."""
        return _rpc_call("list_tables")

    def set_table_cell(self, table_name: str, cell: str, text: str) -> dict:
        """Set the plain-text content of ONE table cell, addressed A1-style (e.g."""
        return _rpc_call("set_table_cell", table_name=table_name, cell=cell, text=text)

table = _TableProxy()


class _TextframeProxy:
    """Proxy for textframe tools."""

    def get_text_frame_info(self, frame_name: str) -> dict:
        """Get detailed info about a text frame.."""
        return _rpc_call("get_text_frame_info", frame_name=frame_name)

    def list_text_frames(self) -> dict:
        """List all text frames in the document.."""
        return _rpc_call("list_text_frames")

    def set_text_frame_properties(self, frame_name: str, *, width_mm: float = 0.0, height_mm: float = 0.0, anchor_type: int = 0, hori_orient: int = 0, vert_orient: int = 0) -> dict:
        """Resize or reposition a text frame.."""
        return _rpc_call("set_text_frame_properties", frame_name=frame_name, width_mm=width_mm, height_mm=height_mm, anchor_type=anchor_type, hori_orient=hori_orient, vert_orient=vert_orient)

textframe = _TextframeProxy()


class _TrackingProxy:
    """Proxy for tracking tools."""

    def track_changes_accept(self, index: int) -> dict:
        """Accept a specific tracked change by its index (from track_changes_list).."""
        return _rpc_call("track_changes_accept", index=index)

    def track_changes_accept_all(self) -> dict:
        """Accept all tracked changes in the document.."""
        return _rpc_call("track_changes_accept_all")

    def track_changes_comment_delete(self, index: int) -> dict:
        """Delete a specific comment (annotation) by its index (from track_changes_comment_list).."""
        return _rpc_call("track_changes_comment_delete", index=index)

    def track_changes_comment_insert(self, content: str, author: str) -> dict:
        """Insert a comment (annotation) at the current cursor selection.."""
        return _rpc_call("track_changes_comment_insert", content=content, author=author)

    def track_changes_comment_list(self) -> dict:
        """List all comments (annotations) currently in the document.."""
        return _rpc_call("track_changes_comment_list")

    def track_changes_list(self) -> dict:
        """List all tracked changes (redlines) in the document, including type, author, date, text and location."""
        return _rpc_call("track_changes_list")

    def track_changes_reject(self, index: int) -> dict:
        """Reject a specific tracked change by its index (from track_changes_list).."""
        return _rpc_call("track_changes_reject", index=index)

    def track_changes_reject_all(self) -> dict:
        """Reject all tracked changes in the document.."""
        return _rpc_call("track_changes_reject_all")

    def track_changes_show(self, show: bool) -> dict:
        """Show or hide tracked changes markup in the document view (Writer)."""
        return _rpc_call("track_changes_show", show=show)

    def track_changes_start(self) -> dict:
        """Start recording changes (track changes) in the document.."""
        return _rpc_call("track_changes_start")

    def track_changes_stop(self) -> dict:
        """Stop recording changes (track changes) in the document.."""
        return _rpc_call("track_changes_stop")

tracking = _TrackingProxy()


class _VisionProxy:
    """Proxy for vision tools."""

    def extract_text_from_image(self, *, image_name: str = "", insert_into_document: bool = True, params: dict = {}) -> dict:
        """OCR text from an embedded document image using local Docling/Paddle (Settings → Python venv)."""
        return _rpc_call("extract_text_from_image", image_name=image_name, insert_into_document=insert_into_document, params=params)

vision = _VisionProxy()


class _WriterProxy:
    """Proxy for writer tools."""

    def add_comment(self, content: str, search_text: str, *, occurrence: int = 0, author: str = "") -> dict:
        """Add a comment/annotation anchored to text matching search_text."""
        return _rpc_call("add_comment", content=content, search_text=search_text, occurrence=occurrence, author=author)

    def apply_document_content(self, content: list, *, target: str = "", old_content: str = "", all_matches: bool = True, position: str = "", dry_run: bool = True, regex: bool = True, case_sensitive: bool = True) -> dict:
        """Insert or replace content."""
        return _rpc_call("apply_document_content", content=content, target=target, old_content=old_content, all_matches=all_matches, position=position, dry_run=dry_run, regex=regex, case_sensitive=case_sensitive)

    def apply_style(self, style_name: str, *, family: str = "", target: str = "", old_content: str = "", all_matches: bool = True, occurrence: int = 0) -> dict:
        """Apply a style to a target."""
        return _rpc_call("apply_style", style_name=style_name, family=family, target=target, old_content=old_content, all_matches=all_matches, occurrence=occurrence)

    def delegate_to_specialized_writer_toolset(self, domain: str, task: str) -> dict:
        """Delegates a specialized task with a focused toolset."""
        return _rpc_call("delegate_to_specialized_writer_toolset", domain=domain, task=task)

    def get_document_content(self, *, scope: str = "", max_chars: int = 0, start: int = 0, end: int = 0, include_images: bool = True) -> dict:
        """Get document (or selection/range) content."""
        return _rpc_call("get_document_content", scope=scope, max_chars=max_chars, start=start, end=end, include_images=include_images)

    def get_document_tree(self, *, content_strategy: str = "", depth: int = 0) -> dict:
        """Get the document heading tree with bookmarks and content previews, plus document statistics."""
        return _rpc_call("get_document_tree", content_strategy=content_strategy, depth=depth)

    def get_image(self, *, image: str = "", selection: bool = True, page: int = 0) -> dict:
        """Return an image so you can SEE it (vision-capable models)."""
        return _rpc_call("get_image", image=image, selection=selection, page=page)

    def get_page_objects(self, *, page: int = 0, locator: str = "", paragraph_index: int = 0) -> dict:
        """Get images, tables, frames, and Draw shapes visible on a specific physical page."""
        return _rpc_call("get_page_objects", page=page, locator=locator, paragraph_index=paragraph_index)

    def search_in_document(self, pattern: str, *, regex: bool = True, case_sensitive: bool = True, max_results: int = 0, return_offsets: bool = True) -> dict:
        """Search for text ANYWHERE in the document using LibreOffice native search — body paragraphs and headings, table cells, text boxes / frames, floating drawing shapes, page headers/footers, AND comments (annotations) are all covered."""
        return _rpc_call("search_in_document", pattern=pattern, regex=regex, case_sensitive=case_sensitive, max_results=max_results, return_offsets=return_offsets)

    def set_selection(self, *, search_text: str = "", occurrence: int = 0, case_sensitive: bool = True, char_start: int = 0, char_end: int = 0) -> dict:
        """Select a passage in the document (highlights it for the user and lets a following apply_document_content/apply_style with target='selection' act on it)."""
        return _rpc_call("set_selection", search_text=search_text, occurrence=occurrence, case_sensitive=case_sensitive, char_start=char_start, char_end=char_end)

writer = _WriterProxy()


class _WritingPlanProxy:
    """Proxy for writing_plan tools."""

    def write_document_section(self, content: list, *, target: str = "") -> dict:
        """Write/append a specific section's content to the document."""
        return _rpc_call("write_document_section", content=content, target=target)

    def writing_research_web(self, query: str) -> dict:
        """Search the public web for context during document writing."""
        return _rpc_call("writing_research_web", query=query)

writing_plan = _WritingPlanProxy()