Validate and register a restricted Python filter for later execution on a local file.

Use this tool first when you want to run custom filtering or transformation logic against a local document. The submitted source code must define exactly one top-level function with this exact signature:

def filter_item(data):

The server loads the target file before execution and passes the loaded document into filter_item(data).

Input document types:

• JSON files -> parsed JSON value such as dict, list, string, number, boolean, or null

• YAML files -> parsed YAML value such as dict, list, string, number, boolean, or null

• TXT files -> list of text lines

The function must return a text result (str). The returned text may contain any format you want, such as plain text, YAML, CSV-like text, or a custom report.

Preloaded standard-library modules (don't try to import them in your functions):

• json, yaml, re

• math, statistics, datetime, decimal

• collections, itertools, functools, operator

• textwrap, html, base64, hashlib, ipaddress, unicodedata, difflib

Safety rules:

• The code is validated against a restricted Python subset

• Imports, network access, dynamic execution, and unsafe attribute access are rejected

• Registered filters are stored in memory only and expire automatically after a server-side TTL

Forbidden:

• Using non-standard libraries or modules

• Accessing the filesystem, network, or environment variables

• Defining multiple top-level functions, classes, or module-level code

• Using dynamic features like eval, exec, or import

Args: code: Python source code that defines exactly one function named filter_item(data).

Returns: A structured object containing the new filter identifier, expiration timestamp, TTL in seconds, and validation policy version.

Raises: ValueError: If the code is invalid, unsafe, or does not match the required function signature.

Run a previously registered filter on a local file and return its text output.

Use this tool after register_filter. The server resolves the registered filter, loads the file from the local filesystem, converts it into an in-memory document, calls filter_item(data), and returns the exact text produced by the filter.

Supported file types:

• json

• yaml

• txt

If file_type is omitted, the server tries to detect the type from the file extension.

File loading behavior:

• json -> parsed JSON value

• yaml -> parsed YAML value

• txt -> list of lines

Args: filter_id: Identifier returned earlier by register_filter. file_path: Path to the local file that should be loaded and passed into the filter. file_type: Optional explicit file type override. Use this when extension-based detection is missing or ambiguous.

Returns: A structured object containing the filter identifier, resolved file path, effective file type, filter expiration time, and result_text.

Raises: ValueError: If the filter does not exist, has expired, returns a non-string result, or the file type is unsupported. FileNotFoundError: If the file does not exist.

Apply a registered filter to a source file and save the text output.

Use this tool after register_filter when you want to transform a local json, yaml, or txt file and persist the returned string as UTF-8 text. The destination path must be inside a configured --workdir; unlike run_filter, convert_file refuses to write when no --workdir is configured.

Missing destination parent directories are created automatically. Existing destination files are rejected unless overwrite is true.

Args: filter_id: Identifier returned earlier by register_filter. source_file_path: Absolute path to the source file to load. destination_file_path: Absolute path where result text is saved. file_type: Optional explicit source file type override. overwrite: Whether to replace an existing destination file.

Returns: A structured object describing the written file and filter metadata.

Raises: ValueError: If paths are invalid, workdir is missing, the filter is unknown or expired, destination exists without overwrite, or the filter returns a non-string result. FileNotFoundError: If the source file does not exist.