convert_file
Apply a registered filter to a local JSON, YAML, or TXT file and save the transformed output as UTF-8 text. Ensure the destination path is within the configured work directory.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_type | No | Optional explicit file type override for the source file. If omitted, detected from the source extension. | |
| filter_id | Yes | Identifier previously returned by register_filter. | |
| overwrite | No | If false (default), fail when destination exists. If true, overwrite the existing destination file. | |
| source_file_path | Yes | Absolute path to the source file. Must be inside an allowed --workdir if any are configured. | |
| destination_file_path | Yes | Absolute path to the destination file. Must be inside an allowed --workdir. Missing parent directories are created automatically. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_type | Yes | Effective loader type used for the source file. One of: json, yaml, txt. | |
| filter_id | Yes | Identifier of the registered filter that produced this file. | |
| expires_at | Yes | UTC timestamp in ISO 8601 format when this filter expires. | |
| overwritten | Yes | Whether an existing destination file was replaced. | |
| bytes_written | Yes | Number of UTF-8 bytes written to the destination file. | |
| source_file_path | Yes | Resolved absolute path of the processed source file. | |
| destination_file_path | Yes | Resolved absolute path where the result text was written. |