satif-ai 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

satif_ai/standardizers/ai_xlsx.py

@@ -0,0 +1,372 @@
+import logging
+import shutil
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+try:
+    from xlsx_to_sdif.graph import graph as xlsx_graph
+    from xlsx_to_sdif.state import State as XLSXState
+except ImportError:
+    xlsx_graph = None  # type: ignore
+    XLSXState = None  # type: ignore
+    logging.getLogger(__name__).warning(
+        "Failed to import xlsx_to_sdif. AIXLSXStandardizer will not be functional."
+    )
+
+
+from satif_core.standardizers.base import AsyncStandardizer
+from satif_core.types import Datasource, SDIFPath, StandardizationResult
+
+from satif_ai.utils.merge_sdif import merge_sdif_files
+
+logger = logging.getLogger(__name__)
+
+
+class AIXLSXStandardizer(AsyncStandardizer):
+    """
+    An asynchronous standardizer for XLSX files that leverages the `xlsx-to-sdif` library.
+
+    This standardizer processes one or more XLSX files, converts each to an
+    intermediate SDIF (Standardized Data Interchange Format) file using the
+    `xlsx-to-sdif` processing graph, and then consolidates these intermediate
+    files into a single final SDIF file.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        """
+        Initializes the AIXLSXStandardizer.
+
+        Args:
+            ...
+        """
+
+    async def _invoke_xlsx_graph(
+        self, input_file_path: Path, graph_config: Dict[str, Any]
+    ) -> Path:
+        """
+        Invokes the `xlsx-to-sdif` graph for a single XLSX file.
+
+        Args:
+            input_file_path: Path to the input XLSX file.
+            graph_config: Configuration for the `xlsx-to-sdif` graph invocation,
+                          including a unique `thread_id`.
+
+        Returns:
+            Path to the SDIF file produced by the graph.
+
+        Raises:
+            RuntimeError: If the `xlsx-to-sdif` graph is not available, fails to
+                          return a final state, or does not produce an output path.
+            FileNotFoundError: If the graph reports an output file that doesn't exist.
+        """
+        if not xlsx_graph or not XLSXState:
+            raise RuntimeError(
+                "xlsx_to_sdif is not available. "
+                "Please ensure 'xlsx-to-sdif' library is installed correctly."
+            )
+
+        initial_state: XLSXState = {"spreadsheet_path": str(input_file_path)}  # type: ignore
+
+        thread_id = graph_config.get("configurable", {}).get(
+            "thread_id", "unknown_thread"
+        )
+        logger.info(
+            f"Invoking xlsx_to_sdif graph for: {input_file_path.name} with thread_id: {thread_id}"
+        )
+
+        # Stream events for logging or potential progress updates
+        async for event in xlsx_graph.astream_events(
+            initial_state, graph_config, version="v1"
+        ):
+            event_type = event["event"]
+            event_name = event.get("name", "")
+            if event_type in ["on_tool_start", "on_chain_start"]:
+                logger.debug(
+                    f"Graph event for {input_file_path.name} (Thread: {thread_id}): {event_type} - {event_name}"
+                )
+            elif event_type in ["on_tool_error", "on_chain_error", "on_llm_error"]:
+                logger.warning(
+                    f"Graph error event for {input_file_path.name} (Thread: {thread_id}): {event_type} - {event_name}. Data: {event.get('data')}"
+                )
+
+        final_snapshot = await xlsx_graph.aget_state(graph_config)
+        if not final_snapshot or not final_snapshot.values:
+            raise RuntimeError(
+                f"xlsx_to_sdif graph did not return a final state for {input_file_path.name} (Thread: {thread_id})."
+            )
+
+        output_sdif_path_str = final_snapshot.values.get("output_sdif_path")
+        if not output_sdif_path_str:
+            raise RuntimeError(
+                f"xlsx_to_sdif graph for {input_file_path.name} (Thread: {thread_id}) "
+                f"did not produce an 'output_sdif_path' in its final state. State: {final_snapshot.values}"
+            )
+
+        output_sdif_path = Path(output_sdif_path_str)
+        if not output_sdif_path.is_file():
+            raise FileNotFoundError(
+                f"xlsx_to_sdif graph for {input_file_path.name} (Thread: {thread_id}) "
+                f"reported output file '{output_sdif_path}', but it does not exist or is not a file."
+            )
+
+        logger.info(
+            f"xlsx_to_sdif graph successfully processed {input_file_path.name} (Thread: {thread_id}). Output at {output_sdif_path}"
+        )
+        return output_sdif_path
+
+    async def _resolve_and_filter_input_files(
+        self, datasource: Datasource
+    ) -> List[Path]:
+        """Resolves and validates datasource, returning a list of XLSX file paths."""
+        input_files: List[Path]
+        if isinstance(datasource, (str, Path)):
+            input_files = [Path(datasource)]
+        elif isinstance(datasource, list) and all(
+            isinstance(p, (str, Path)) for p in datasource
+        ):
+            input_files = [Path(p) for p in datasource]
+        else:
+            raise ValueError(
+                "Datasource must be a file path (str or Path) or a list of such paths."
+            )
+
+        if not input_files:
+            raise ValueError("No input XLSX files provided in the datasource.")
+
+        xlsx_input_files = []
+        for f_path in input_files:
+            if not f_path.is_file():
+                raise FileNotFoundError(f"Input file not found: {f_path}")
+            if f_path.suffix.lower() not in (
+                ".xlsx",
+                ".xlsm",
+                ".xlsb",
+                ".xls",
+            ):  # Common Excel extensions
+                logger.warning(
+                    f"File {f_path.name} is not a typical XLSX file extension, but will be attempted."
+                )
+            xlsx_input_files.append(f_path)
+
+        if not xlsx_input_files:
+            raise ValueError(
+                "No processable XLSX files found in the datasource after filtering."
+            )
+        return xlsx_input_files
+
+    def _prepare_final_output_path(
+        self, output_path: SDIFPath, overwrite: bool
+    ) -> Path:
+        """Prepares the final output path, handling overwrites and directory creation."""
+        final_output_path = Path(output_path)
+        if final_output_path.exists() and not overwrite:
+            raise FileExistsError(
+                f"Output file {final_output_path} already exists and overwrite is False."
+            )
+        elif final_output_path.exists() and overwrite:
+            logger.info(
+                f"Overwrite active: Deleting existing output file {final_output_path}"
+            )
+            try:
+                if (
+                    final_output_path.is_dir()
+                ):  # Should not happen if SDIFPath is file path
+                    raise IsADirectoryError(
+                        f"Output path {final_output_path} is a directory."
+                    )
+                final_output_path.unlink()
+            except OSError as e:
+                raise RuntimeError(
+                    f"Failed to delete existing output file {final_output_path}: {e}"
+                ) from e
+
+        final_output_path.parent.mkdir(parents=True, exist_ok=True)
+        return final_output_path
+
+    def _setup_temp_directories(self) -> Tuple[Path, Path, Path]:
+        """Creates and returns paths for temporary working directories."""
+        run_temp_dir = Path(tempfile.mkdtemp(prefix="satif_aixlsx_run_"))
+        intermediate_sdif_dir = run_temp_dir / "intermediate_sdifs"
+        intermediate_sdif_dir.mkdir()
+        temp_input_copies_dir = (
+            run_temp_dir / "temp_input_copies"
+        )  # Directory for temporary input copies
+        temp_input_copies_dir.mkdir()
+        return run_temp_dir, intermediate_sdif_dir, temp_input_copies_dir
+
+    async def _process_single_file_to_intermediate_sdif(
+        self,
+        input_xlsx_file: Path,
+        final_output_path_stem: str,
+        temp_input_copies_dir: Path,
+        intermediate_sdif_dir: Path,
+    ) -> Path:
+        """Processes a single XLSX file to an intermediate SDIF in a controlled location."""
+        logger.info(f"Processing file: {input_xlsx_file.name}")
+        graph_thread_id = f"satif_aixlsx_{final_output_path_stem}_{input_xlsx_file.stem}_{uuid.uuid4().hex[:8]}"
+
+        temp_input_file_for_graph = (
+            temp_input_copies_dir
+            / f"{input_xlsx_file.stem}_{graph_thread_id}{input_xlsx_file.suffix}"
+        )
+        shutil.copy2(input_xlsx_file, temp_input_file_for_graph)
+        logger.debug(
+            f"Created temporary copy of {input_xlsx_file.name} at {temp_input_file_for_graph}"
+        )
+
+        graph_config_for_file = {
+            "configurable": {"thread_id": graph_thread_id},
+            "recursion_limit": 50,  # Default, make configurable if needed
+        }
+
+        try:
+            graph_produced_sdif_path = await self._invoke_xlsx_graph(
+                temp_input_file_for_graph, graph_config_for_file
+            )
+
+            target_intermediate_sdif_path = (
+                intermediate_sdif_dir
+                / f"intermediate_{input_xlsx_file.stem}_{graph_thread_id}.sdif"
+            )
+            shutil.move(
+                str(graph_produced_sdif_path),
+                str(target_intermediate_sdif_path),
+            )
+            logger.info(
+                f"Moved graph output for {input_xlsx_file.name} to {target_intermediate_sdif_path}"
+            )
+            return target_intermediate_sdif_path
+        except Exception as e:
+            error_msg = f"Failed to process file {input_xlsx_file.name} (using copy {temp_input_file_for_graph.name}) with xlsx-to-sdif graph: {e}"
+            logger.error(error_msg, exc_info=True)
+            # Re-raise to be caught by the main standardize method's loop or error handling
+            raise RuntimeError(
+                f"Error processing {input_xlsx_file.name}. Halting batch."
+            ) from e
+
+    async def _consolidate_intermediate_sdifs(
+        self, intermediate_sdif_paths: List[Path], final_output_path: Path
+    ) -> None:
+        """Consolidates intermediate SDIF files into the final output path."""
+        if not intermediate_sdif_paths:
+            # This case should ideally be handled before calling, but as a safeguard:
+            raise RuntimeError(
+                "No intermediate SDIF files were provided for consolidation."
+            )
+
+        if len(intermediate_sdif_paths) == 1:
+            logger.info(
+                f"Only one intermediate SDIF generated. Moving {intermediate_sdif_paths[0]} to {final_output_path}"
+            )
+            shutil.move(str(intermediate_sdif_paths[0]), str(final_output_path))
+        else:
+            logger.info(
+                f"Merging {len(intermediate_sdif_paths)} intermediate SDIF files into {final_output_path}"
+            )
+            merge_sdif_files(
+                source_db_paths=intermediate_sdif_paths,
+                target_db_path=final_output_path,
+            )
+
+    async def standardize(
+        self,
+        datasource: Datasource,
+        output_path: SDIFPath,
+        *,
+        overwrite: bool = False,
+        config: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> StandardizationResult:
+        """
+        Standardizes one or more XLSX files into a single SDIF file.
+
+        Args:
+            datasource: A single file path (str or Path) or a list of file paths
+                        to XLSX files.
+            output_path: The path where the final consolidated SDIF file will be saved.
+            overwrite: If True, overwrite the output_path if it already exists.
+                       Defaults to False.
+            config: General configuration options (currently not used by this standardizer
+                    for graph interaction but preserved for API consistency).
+            **kwargs: Additional keyword arguments (currently ignored).
+
+        Returns:
+            A StandardizationResult object containing the path to the final SDIF file.
+
+        Raises:
+            ValueError: If the datasource is invalid or no XLSX files are found.
+            RuntimeError: If critical errors occur during processing, such as the
+                          `xlsx-to-sdif` graph not being available or failing.
+            FileNotFoundError: If input files are not found or graph outputs are invalid.
+            FileExistsError: If output_path exists and overwrite is False.
+        """
+        if not xlsx_graph or not XLSXState:
+            raise RuntimeError(
+                "AIXLSXStandardizer cannot operate because `xlsx_to_sdif.graph` or `xlsx_to_sdif.state` is not available. "
+                "Please ensure the 'xlsx-to-sdif' library is installed and accessible."
+            )
+
+        xlsx_input_files = await self._resolve_and_filter_input_files(datasource)
+        final_output_path = self._prepare_final_output_path(output_path, overwrite)
+        run_temp_dir, intermediate_sdif_dir, temp_input_copies_dir = (
+            self._setup_temp_directories()
+        )
+
+        intermediate_sdif_paths: List[Path] = []
+        processing_errors: List[str] = []
+
+        try:
+            # Process each file sequentially. Consider asyncio.gather for parallel if graph supports it well for many files.
+            for i, input_xlsx_file in enumerate(xlsx_input_files):
+                try:
+                    logger.info(
+                        f"Starting processing for file {i + 1}/{len(xlsx_input_files)}: {input_xlsx_file.name}"
+                    )
+                    intermediate_sdif_path = (
+                        await self._process_single_file_to_intermediate_sdif(
+                            input_xlsx_file,
+                            final_output_path.stem,  # Pass stem for unique naming
+                            temp_input_copies_dir,
+                            intermediate_sdif_dir,
+                        )
+                    )
+                    intermediate_sdif_paths.append(intermediate_sdif_path)
+                except Exception:
+                    logger.error(
+                        f"Halting standardization due to error processing {input_xlsx_file.name}."
+                    )
+                    raise  # Re-raise the exception to be caught by the outer try/finally
+
+            if not intermediate_sdif_paths:
+                # This condition might be redundant if _process_single_file_to_intermediate_sdif always raises on failure
+                # and we re-raise immediately.
+                if processing_errors:  # This list would be empty if we fail fast
+                    raise RuntimeError(
+                        f"No XLSX files were successfully processed. Errors: {'; '.join(processing_errors)}"
+                    )
+                else:
+                    raise RuntimeError(
+                        "No intermediate SDIF files were generated, though no specific errors were caught."
+                    )
+
+            await self._consolidate_intermediate_sdifs(
+                intermediate_sdif_paths, final_output_path
+            )
+
+            logger.info(f"Successfully created final SDIF: {final_output_path}")
+            return StandardizationResult(
+                output_path=final_output_path, file_configs=None
+            )  # file_configs not available from this process
+
+        finally:
+            if run_temp_dir.exists():
+                try:
+                    shutil.rmtree(run_temp_dir)
+                    logger.debug(f"Cleaned up temporary directory: {run_temp_dir}")
+                except Exception as e_clean:
+                    logger.error(
+                        f"Error cleaning up temporary directory {run_temp_dir}: {e_clean}",
+                        exc_info=True,
+                    )

satif_ai/transform.py

@@ -0,0 +1,155 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import FastMCPTransport
+from satif_core.code_executors.base import CodeExecutor
+from satif_core.transformation_builders.base import AsyncTransformationBuilder
+from satif_core.types import (
+    FilePath,
+    SDIFPath,
+    TransformationResult,
+)
+from satif_sdk.code_executors.local_executor import LocalCodeExecutor
+from satif_sdk.transformers.code import CodeTransformer
+from sdif_mcp.server import mcp
+
+from satif_ai.transformation_builders.syncpulse import SyncpulseTransformationBuilder
+from satif_ai.utils.openai_mcp import OpenAICompatibleMCP
+
+
+async def atransform(
+    sdif: SDIFPath,
+    output_target_files: Dict[FilePath, str] | List[FilePath] | FilePath,
+    instructions: Optional[str] = None,
+    output_path: FilePath = Path("."),
+    *,
+    transformation_code: Optional[str] = None,
+    transformation_builder: Optional[AsyncTransformationBuilder] = None,
+    code_executor: Optional[CodeExecutor] = None,
+    mcp_server: Optional[FastMCP] = None,
+    mcp_client: Optional[Client] = None,
+    llm_model: str = "o4-mini",
+    schema_only: bool = False,
+    representer_kwargs: Optional[Dict[str, Any]] = None,
+) -> TransformationResult:
+    """
+    Asynchronously transforms an SDIF (Standard Data Interchange Format) input using
+    an AI-generated or provided transformation code.
+
+    This function orchestrates the process of:
+    1. Optionally generating transformation code using an AI model via a `TransformationBuilder`
+       if `transformation_code` is not provided.
+       explicitly passed.
+    2. Executing the transformation code using a `CodeTransformer` and a `CodeExecutor`.
+    3. Exporting the results to the specified output.
+
+    Args:
+        sdif: Path to the input SDIF file or an `SDIFDatabase` object.
+        output_target_files: A dictionary mapping original example file paths (or string identifiers)
+                             to their desired agent-facing filenames, or a list of output example
+                             file paths, or a single output file path. These are used by the AI to understand the target
+                             format and structure, and also by the `CodeTransformer` to determine
+                             output filenames if the transformation result keys match.
+        instructions: Optional. Natural language instructions for the AI to generate
+                      the transformation code. Used if `transformation_code` is None.
+        output_path: Path to the directory where transformation outputs will be saved.
+        transformation_code: Optional. Pre-existing Python code for the transformation.
+                             If None, code will be generated by the `transformation_builder`.
+        transformation_builder: Optional. An `AsyncTransformationBuilder` instance responsible for generating
+                      the transformation code if `transformation_code` is not provided.
+                      If None, a `SyncpulseTransformationBuilder` is instantiated.
+        code_executor: Optional. A `CodeExecutor` instance for running the transformation
+                       code. If None, a `LocalCodeExecutor` is used.
+        mcp_server: Optional. A `FastMCP` server instance for the AI code builder.
+                    Defaults to the global `mcp` instance if `transformation_builder` is None and
+                    a new `SyncpulseTransformationBuilder` is being created.
+        mcp_client: Optional. A user-provided `Client` instance. If provided when
+                    `transformation_builder` is None, it will be used by the internally
+                    created `SyncpulseTransformationBuilder`. The caller is responsible for
+                    managing the lifecycle of a provided client.
+        llm_model: The language model to use for code generation (e.g., "o4-mini").
+                   Used if `transformation_builder` is None.
+        schema_only: If True, the transformation aims to match only the schema (headers)
+                     of the `output_target_files`, and input samples may be omitted or marked
+                     as empty for the AI. This is useful for structural transformations
+                     without processing actual data rows.
+        representer_kwargs: Optional dictionary of keyword arguments to pass to the
+                            representer when analyzing `output_target_files`.
+
+    Returns:
+        A `TransformationResult` object containing the path to the output
+        and the transformation code used.
+    """
+    current_transformation_code: Optional[str] = transformation_code
+    active_builder: Optional[AsyncTransformationBuilder] = transformation_builder
+
+    _openai_mcp_instance: Optional[OpenAICompatibleMCP] = None
+    openai_mcp_managed_locally = False
+
+    # If code isn't provided, we need a builder. If a builder isn't provided, we create one.
+    if current_transformation_code is None:
+        if active_builder is None:
+            # Create SyncpulseTransformationBuilder
+            _effective_mcp_server = mcp_server if mcp_server is not None else mcp
+
+            _openai_mcp_instance = OpenAICompatibleMCP(mcp=_effective_mcp_server)
+            await _openai_mcp_instance.connect()
+            openai_mcp_managed_locally = True
+
+            if mcp_client is None:  # No user-provided client, create and manage one
+                mcp_transport = FastMCPTransport(mcp=_effective_mcp_server)
+                async with Client(mcp_transport) as new_client:
+                    active_builder = SyncpulseTransformationBuilder(
+                        mcp_server=_openai_mcp_instance,
+                        mcp_session=new_client.session,
+                        llm_model=llm_model,
+                    )
+                    current_transformation_code = await active_builder.build(
+                        sdif=sdif,
+                        output_target_files=output_target_files,
+                        instructions=instructions,
+                        schema_only=schema_only,
+                        representer_kwargs=representer_kwargs,
+                    )
+            else:
+                active_builder = SyncpulseTransformationBuilder(
+                    mcp_server=_openai_mcp_instance,
+                    mcp_session=mcp_client,  # Use the provided client
+                    llm_model=llm_model,
+                )
+                current_transformation_code = await active_builder.build(
+                    sdif=sdif,
+                    output_target_files=output_target_files,
+                    instructions=instructions,
+                    schema_only=schema_only,
+                    representer_kwargs=representer_kwargs,
+                )
+
+    # Disconnect OpenAICompatibleMCP if it was created and connected locally
+    if (
+        openai_mcp_managed_locally
+        and _openai_mcp_instance
+        and _openai_mcp_instance._is_connected
+    ):
+        await _openai_mcp_instance.cleanup()
+
+    if current_transformation_code is None:
+        raise ValueError("Transformation code could not be obtained or generated.")
+
+    # Code Executor and Transformation
+    _code_executor = code_executor if code_executor is not None else LocalCodeExecutor()
+
+    transformer = CodeTransformer(
+        function=current_transformation_code,
+        code_executor=_code_executor,
+    )
+
+    exported_artifact_path = transformer.export(
+        sdif=sdif,
+        output_path=output_path,
+    )
+
+    return TransformationResult(
+        output_path=exported_artifact_path, function_code=current_transformation_code
+    )

satif_ai/{code_builders/transformation.py → transformation_builders/syncpulse.py}

@@ -8,7 +8,9 @@ from typing import Any, Dict, List, Optional, Union
 from agents import Agent, Runner, function_tool
 from agents.mcp.server import MCPServer
 from mcp import ClientSession
-from satif_core import AsyncCodeBuilder, CodeBuilder, SDIFDatabase
+from satif_core import AsyncTransformationBuilder
+from satif_core.types import FilePath
+from satif_sdk.code_executors.local_executor import LocalCodeExecutor
 from satif_sdk.comparators import get_comparator
 from satif_sdk.representers import get_representer
 from satif_sdk.transformers import CodeTransformer
@@ -61,7 +63,10 @@ async def execute_transformation(code: str) -> str:
     if INPUT_SDIF_PATH is None or OUTPUT_TARGET_FILES is None:
         return "Error: Transformation context not initialized"
 
-    code_transformer = CodeTransformer(function=code)
+    code_transformer = CodeTransformer(
+        function=code,
+        code_executor=LocalCodeExecutor(disable_security_warning=True),
+    )
     generated_output_path = code_transformer.export(INPUT_SDIF_PATH)
 
     comparisons = []
@@ -120,19 +125,7 @@ async def execute_transformation(code: str) -> str:
     return "\n".join(comparisons)
 
 
-class TransformationCodeBuilder(CodeBuilder):
-    def __init__(self, output_example: Path | List[Path] | Dict[str, Path]):
-        self.output_example = output_example
-
-    def build(
-        self,
-        sdif: Path | SDIFDatabase,
-        instructions: Optional[str] = None,
-    ) -> str:
-        pass
-
-
-class TransformationAsyncCodeBuilder(AsyncCodeBuilder):
+class SyncpulseTransformationBuilder(AsyncTransformationBuilder):
     """This class is used to build a transformation code that will be used to transform a SDIF database into a set of files following the format of the given output files."""
 
     def __init__(
@@ -147,23 +140,18 @@ class TransformationAsyncCodeBuilder(AsyncCodeBuilder):
 
     async def build(
         self,
-        sdif: Path,  # This will now be relative to project root (MCP server CWD)
-        output_target_files: Dict[Union[str, Path], str] | List[Path],
-        output_sdif: Optional[Path] = None,  # This will now be relative or None
+        sdif: Path,
+        output_target_files: Dict[FilePath, str] | List[FilePath] | FilePath,
+        output_sdif: Optional[Path] = None,
         instructions: str = "",
         schema_only: bool = False,
-        representer_options_for_build: Optional[Dict[str, Any]] = None,
+        representer_kwargs: Optional[Dict[str, Any]] = None,
     ) -> str:
         global INPUT_SDIF_PATH, OUTPUT_TARGET_FILES, SCHEMA_ONLY
-        # INPUT_SDIF_PATH is used by execute_transformation tool, needs to be accessible from where that tool runs.
-        # If execute_transformation runs in the same process as the builder, absolute path is fine.
-        # If it were a separate context, this might need adjustment.
-        # For now, assume execute_transformation can access absolute paths if needed for its *input SDIF*.
-        # However, the sdif for MCP URIs must be relative.
+
         INPUT_SDIF_PATH = Path(sdif).resolve()
         SCHEMA_ONLY = schema_only
-        # Paths for MCP URIs are now expected to be relative to MCP server CWD (project root)
-        # So, use them directly as strings.
+        # We must encode the path because special characters are not allowed in mcp read_resource()
         input_sdif_mcp_uri_path = base64.b64encode(str(sdif).encode()).decode()
         output_sdif_mcp_uri_path = (
             base64.b64encode(str(output_sdif).encode()).decode()
@@ -205,9 +193,14 @@ class TransformationAsyncCodeBuilder(AsyncCodeBuilder):
 
         # OUTPUT_TARGET_FILES keys are absolute paths to original example files for local reading by representers/comparators.
         # Values are agent-facing filenames.
-        if isinstance(output_target_files, list):
+        if isinstance(output_target_files, FilePath):
+            OUTPUT_TARGET_FILES = {
+                Path(output_target_files).resolve(): Path(output_target_files).name
+            }
+        elif isinstance(output_target_files, list):
             OUTPUT_TARGET_FILES = {
-                file_path.resolve(): file_path.name for file_path in output_target_files
+                Path(file_path).resolve(): Path(file_path).name
+                for file_path in output_target_files
             }
         elif isinstance(output_target_files, dict):
             temp_map = {}
@@ -229,7 +222,7 @@ class TransformationAsyncCodeBuilder(AsyncCodeBuilder):
                     # Representer uses the absolute path (file_key_abs_path) to read the example file.
                     representer = get_representer(file_key_abs_path)
                     representation, used_params = representer.represent(
-                        file_key_abs_path, **(representer_options_for_build or {})
+                        file_key_abs_path, **(representer_kwargs or {})
                     )
                     output_representation[agent_facing_name] = {
                         "representation": representation,

satif_ai/utils/__init__.py

@@ -0,0 +1,5 @@
+from .merge_sdif import merge_sdif_files
+from .openai_mcp import OpenAICompatibleMCP
+from .zip import extract_zip_archive_async
+
+__all__ = ["merge_sdif_files", "extract_zip_archive_async", "OpenAICompatibleMCP"]