satif-ai 0.2.9__tar.gz → 0.2.10__tar.gz

{satif_ai-0.2.9 → satif_ai-0.2.10}/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.3
 Name: satif-ai
-Version: 0.2.9
+Version: 0.2.10
 Summary: AI Agents for Satif
 License: MIT
 Author: Syncpulse
 Maintainer: Bryan Djafer
 Maintainer-email: bryan.djafer@syncpulse.fr
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.10,<3.14
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: xlsx
 Requires-Dist: openai-agents (>=0.0.9,<0.0.10)
 Requires-Dist: satif-sdk (>=0.1.0,<1.0.0)
 Requires-Dist: sdif-mcp (>=0.1.0,<1.0.0)

{satif_ai-0.2.9 → satif_ai-0.2.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "satif-ai"
-version = "0.2.9"
+version = "0.2.10"
 description = "AI Agents for Satif"
 authors = [
     {name = "Syncpulse"}
@@ -11,7 +11,7 @@ maintainers = [
 license = "MIT"
 readme = "README.md"
 
-requires-python = ">=3.10,<4.0"
+requires-python = ">=3.10,<3.14"
 
 [tool.poetry.dependencies]
 openai-agents = ">=0.0.9,<0.0.10"
@@ -22,6 +22,9 @@ sdif-mcp = ">=0.1.0,<1.0.0"
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
 
+[tool.poetry.extras]
+xlsx = ["xlsx-to-sdif"]
+
 [project.scripts]
 satif-ai = "satif.cli:main"
 
@@ -31,6 +34,7 @@ satif-core = {path = "../core", develop = true}
 satif-sdk = {path = "../sdk", develop = true}
 sdif-mcp = {path = "../mcp", develop = true}
 sdif-db = {path = "../sdif", develop = true}
+xlsx-to-sdif = {path = "../xlsx-to-sdif", develop = true}
 ipykernel = "^6.29.5"
 
 

{satif_ai-0.2.9 → satif_ai-0.2.10}/satif_ai/adapters/tidy.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Optional, Union
 
 from agents import Agent, Runner, function_tool
-from agents.mcp.server import MCPServerStdio
+from agents.mcp.server import MCPServer
 from mcp import ClientSession
 from satif_core.adapters.base import Adapter
 from satif_core.types import Datasource, SDIFPath
@@ -224,7 +224,7 @@ class TidyAdapter(Adapter):
 
     def __init__(
         self,
-        mcp_server: MCPServerStdio,
+        mcp_server: MCPServer,
         mcp_session: ClientSession,
         llm_model: str = "o4-mini",
         max_iterations: int = 5,
@@ -233,7 +233,7 @@ class TidyAdapter(Adapter):
         Initialize the TidyAdapter.
 
         Args:
-            mcp_server: An instance of MCPServerStdio for agent communication.
+            mcp_server: An instance of MCPServer for agent communication.
             mcp_session: An instance of ClientSession for resource/prompt fetching.
             llm_model: Name of the language model to use for the agent.
             max_iterations: Maximum number of attempts the agent gets to refine the code.
@@ -349,7 +349,7 @@ class TidyAdapter(Adapter):
         if isinstance(sdif, SDIFDatabase):
             input_path = Path(sdif.path)
         else:
-            input_path = sdif
+            input_path = Path(sdif)
         if not input_path.exists():
             raise FileNotFoundError(f"Input SDIF file not found: {input_path}")
 

{satif_ai-0.2.9 → satif_ai-0.2.10}/satif_ai/standardizers/ai.py

@@ -11,6 +11,7 @@ from satif_core.standardizers.base import AsyncStandardizer
 from satif_core.types import Datasource, FilePath, SDIFPath, StandardizationResult
 
 from satif_ai.adapters.tidy import TidyAdapter
+from satif_ai.standardizers.ai_xlsx import AIXLSXStandardizer
 from satif_ai.utils.merge_sdif import merge_sdif_files
 from satif_ai.utils.zip import extract_zip_archive_async
 
@@ -43,8 +44,9 @@ class AIStandardizer(AsyncStandardizer):
 
         self.ai_standardizer_map: Dict[str, Type[AsyncStandardizer]] = {
             ".csv": AICSVStandardizer,
-            # Future standardizers:
-            # ".xlsx": AIXLSXStandardizer,
+            ".xlsx": AIXLSXStandardizer,
+            ".xls": AIXLSXStandardizer,
+            ".xlsm": AIXLSXStandardizer,
             # ".pdf": AIPDFStandardizer,
             # ".json": AIJSONStandardizer,
             # ".xml": AIXMLStandardizer,
@@ -332,11 +334,9 @@ class AIStandardizer(AsyncStandardizer):
             logger.info(
                 f"Merging {len(intermediate_sdif_files)} intermediate SDIF SQLite files into '{final_sdif_file_target}'."
             )
-            # merge_sdif_files must accept a list of source SQLite file paths and a target SQLite file path.
-            merged_target_path = await merge_sdif_files(
+            merged_target_path = merge_sdif_files(
                 intermediate_sdif_files,
                 final_sdif_file_target,
-                overwrite=False,  # We handled overwrite for final_sdif_file_target
             )
             final_sdif_path_str = str(merged_target_path)
 
@@ -414,13 +414,11 @@ class AIStandardizer(AsyncStandardizer):
         file_processing_temp_dir.mkdir(parents=True, exist_ok=True)
 
         try:
-            # 1. Resolve input datasource to a list of processable file paths
             resolved_files = await self._resolve_input_files(
                 datasource, file_processing_temp_dir
             )
             logger.info(f"Resolved {len(resolved_files)} file(s) for standardization.")
 
-            # 2. Group files by the AI standardizer responsible for them
             grouped_by_std, unsupported = self._group_files_by_standardizer(
                 resolved_files
             )
@@ -438,7 +436,6 @@ class AIStandardizer(AsyncStandardizer):
                 f"File groups for standardization: { {cls.__name__: [f.name for f in paths] for cls, paths in grouped_by_std.items()} }"
             )
 
-            # 3. Process each group of files, generating intermediate SDIF SQLite files
             (
                 intermediate_sdif_files,
                 aggregated_file_configs,
@@ -454,7 +451,6 @@ class AIStandardizer(AsyncStandardizer):
                 f"Successfully generated {len(intermediate_sdif_files)} intermediate SDIF SQLite file(s)."
             )
 
-            # 4. Consolidate intermediate SDIF files into the final target file
             final_result = await self._consolidate_results(
                 intermediate_sdif_files,
                 aggregated_file_configs,

{satif_ai-0.2.9 → satif_ai-0.2.10}/satif_ai/standardizers/ai_csv.py

@@ -12,6 +12,7 @@ from agents import Agent, Runner, function_tool
 from agents.mcp.server import MCPServerStdio
 from charset_normalizer import detect
 from mcp import ClientSession
+from satif_core import AsyncStandardizer
 from satif_core.types import Datasource, SDIFPath, StandardizationResult
 from satif_sdk.standardizers.csv import (
     CSVStandardizer,
@@ -274,7 +275,9 @@ async def read_raw_lines(
 
 
 # --- AICSVStandardizer Class ---
-class AICSVStandardizer(CSVStandardizer):  # Inherits from the enhanced CSVStandardizer
+class AICSVStandardizer(
+    CSVStandardizer, AsyncStandardizer
+):  # Inherits from the enhanced CSVStandardizer
     def __init__(
         self,
         mcp_server: Optional[MCPServerStdio] = None,

satif_ai-0.2.10/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-0.2.9 → satif_ai-0.2.10}/satif_ai/transform.py

@@ -1,7 +1,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from fastmcp import FastMCP
+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
@@ -28,7 +28,7 @@ async def atransform(
     transformation_builder: Optional[AsyncTransformationBuilder] = None,
     code_executor: Optional[CodeExecutor] = None,
     mcp_server: Optional[FastMCP] = None,
-    mcp_transport: Optional[FastMCPTransport] = None,
+    mcp_client: Optional[Client] = None,
     llm_model: str = "o4-mini",
     schema_only: bool = False,
     representer_kwargs: Optional[Dict[str, Any]] = None,
@@ -38,7 +38,7 @@ async def atransform(
     an AI-generated or provided transformation code.
 
     This function orchestrates the process of:
-    1. Optionally generating transformation code using an AI model via a `CodeBuilder`
+    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`.
@@ -53,18 +53,21 @@ async def atransform(
                              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 `TransformationAsyncCodeBuilder` is instantiated.
+                      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.
-        mcp_transport: Optional. A `FastMCPTransport` instance for communication with
-                       the `mcp_server`. Defaults to a new transport using `mcp_server`
-                       if `transformation_builder` is None.
+                    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)
@@ -78,44 +81,75 @@ async def atransform(
         A `TransformationResult` object containing the path to the output
         and the transformation code used.
     """
-    if transformation_builder is None:
-        if mcp_server is None:
-            mcp_server = mcp
-
-        if mcp_transport is None:
-            mcp_transport = FastMCPTransport(mcp=mcp_server)
-
-        openai_compatible_mcp = OpenAICompatibleMCP(mcp=mcp_server)
-        await openai_compatible_mcp.connect()
-
-        transformation_builder = SyncpulseTransformationBuilder(
-            mcp_server=openai_compatible_mcp,
-            mcp_session=mcp_transport,
-            llm_model=llm_model,
-        )
-
-    if transformation_code is None:
-        function_code = await transformation_builder.build(
-            sdif=sdif,
-            output_target_files=output_target_files,
-            instructions=instructions,
-            schema_only=schema_only,
-            representer_kwargs=representer_kwargs,
-        )
-    else:
-        function_code = transformation_code
-
-    if code_executor is None:
-        code_executor = LocalCodeExecutor()
+    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=function_code,
-        code_executor=code_executor,
+        function=current_transformation_code,
+        code_executor=_code_executor,
     )
 
-    output_path = transformer.export(
+    exported_artifact_path = transformer.export(
         sdif=sdif,
         output_path=output_path,
     )
 
-    return TransformationResult(output_path=output_path, function_code=function_code)
+    return TransformationResult(
+        output_path=exported_artifact_path, function_code=current_transformation_code
+    )

satif_ai-0.2.10/satif_ai/utils/merge_sdif.py

@@ -0,0 +1,535 @@
+import json
+import logging
+import shutil
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from satif_core.types import SDIFPath
+from sdif_db.database import (
+    SDIFDatabase,  # Assuming this is the conventional import path
+)
+
+log = logging.getLogger(__name__)
+
+
+class _SDIFMerger:
+    def __init__(self, target_sdif_path: Path):
+        self.target_db = SDIFDatabase(target_sdif_path, overwrite=True)
+        # Mappings per source_db_idx:
+        self.source_id_map: Dict[int, Dict[int, int]] = {}
+        self.table_name_map: Dict[int, Dict[str, str]] = {}
+        self.object_name_map: Dict[int, Dict[str, str]] = {}
+        self.media_name_map: Dict[int, Dict[str, str]] = {}
+
+    def _get_new_source_id(self, source_db_idx: int, old_source_id: int) -> int:
+        return self.source_id_map[source_db_idx][old_source_id]
+
+    def _get_new_table_name(self, source_db_idx: int, old_table_name: str) -> str:
+        return self.table_name_map[source_db_idx].get(old_table_name, old_table_name)
+
+    def _get_new_object_name(self, source_db_idx: int, old_object_name: str) -> str:
+        return self.object_name_map[source_db_idx].get(old_object_name, old_object_name)
+
+    def _get_new_media_name(self, source_db_idx: int, old_media_name: str) -> str:
+        return self.media_name_map[source_db_idx].get(old_media_name, old_media_name)
+
+    def _generate_unique_name_in_target(self, base_name: str, list_func) -> str:
+        """Generates a unique name for the target DB by appending a suffix if base_name exists."""
+        if base_name not in list_func():
+            return base_name
+        i = 1
+        while True:
+            new_name = f"{base_name}_{i}"
+            if new_name not in list_func():
+                return new_name
+            i += 1
+            if i > 1000:  # Safety break
+                raise RuntimeError(
+                    f"Could not generate a unique name for base '{base_name}' after 1000 attempts."
+                )
+
+    def _merge_properties(self, source_db: SDIFDatabase, source_db_idx: int):
+        source_props = source_db.get_properties()
+        if not source_props:
+            log.warning(
+                f"Source database {source_db.path} has no properties. Skipping properties merge for this source."
+            )
+            return
+
+        if source_props.get("sdif_version") != "1.0":
+            # Or allow a configurable expected version
+            raise ValueError(
+                f"Source database {source_db.path} has unsupported SDIF version: {source_props.get('sdif_version')}. Expected '1.0'."
+            )
+
+        if source_db_idx == 0:  # First database sets the version for the target
+            try:
+                self.target_db.conn.execute(
+                    "UPDATE sdif_properties SET sdif_version = ?",
+                    (
+                        source_props.get("sdif_version", "1.0"),
+                    ),  # Default to 1.0 if somehow missing
+                )
+                self.target_db.conn.commit()
+            except sqlite3.Error as e:
+                log.error(
+                    f"Failed to set sdif_version in target DB from {source_db.path}: {e}"
+                )
+                raise
+        # creation_timestamp will be set at the end of the entire merge process.
+
+    def _merge_sources(self, source_db: SDIFDatabase, source_db_idx: int):
+        self.source_id_map[source_db_idx] = {}
+        source_sources = source_db.list_sources()
+        for old_source_entry in source_sources:
+            old_source_id = old_source_entry["source_id"]
+            new_source_id = self.target_db.add_source(
+                file_name=old_source_entry["original_file_name"],
+                file_type=old_source_entry["original_file_type"],
+                description=old_source_entry.get("source_description"),
+            )
+            # original processing_timestamp is not directly carried over, new one is set by add_source
+            self.source_id_map[source_db_idx][old_source_id] = new_source_id
+
+    def _merge_tables(self, source_db: SDIFDatabase, source_db_idx: int):
+        self.table_name_map[source_db_idx] = {}
+        source_schema = source_db.get_schema()
+        source_tables_schema = source_schema.get("tables", {})
+
+        # Pass 1: Determine new table names for all tables from this source DB
+        # This is to ensure FKs can be remapped correctly to tables from the *same* source db.
+        temp_name_map_for_this_source = {}
+        for old_table_name in source_tables_schema.keys():
+            # Use create_table with if_exists='add' to get a unique name, but only for name generation.
+            # This is a bit of a workaround. A dedicated _generate_unique_target_table_name might be cleaner.
+            # The SDIFDatabase.create_table(if_exists='add') will actually create metadata entries.
+            # This might be acceptable if we're careful.
+            # Let's use the simpler approach of generating unique name first.
+            effective_new_name = self._generate_unique_name_in_target(
+                old_table_name, self.target_db.list_tables
+            )
+            temp_name_map_for_this_source[old_table_name] = effective_new_name
+        self.table_name_map[source_db_idx] = temp_name_map_for_this_source
+
+        # Pass 2: Create tables with remapped FKs and copy data
+        for old_table_name, table_detail_from_schema in source_tables_schema.items():
+            new_table_name = self.table_name_map[source_db_idx][old_table_name]
+
+            columns_for_create: Dict[str, Dict[str, Any]] = {}
+            original_columns_detail = table_detail_from_schema.get("columns", [])
+
+            for col_detail in original_columns_detail:
+                col_name = col_detail["name"]
+                col_props = {
+                    "type": col_detail["sqlite_type"],
+                    "not_null": col_detail["not_null"],
+                    "primary_key": col_detail[
+                        "primary_key"
+                    ],  # Assumes single col PK flag
+                    "description": col_detail.get("description"),
+                    "original_column_name": col_detail.get("original_column_name"),
+                    # 'unique' constraint not in get_schema output, assumed not used or handled by primary_key
+                }
+
+                # Remap foreign keys defined for this column
+                table_fks_detail = table_detail_from_schema.get("foreign_keys", [])
+                for fk_info in table_fks_detail:
+                    if fk_info["from_column"] == col_name:
+                        original_fk_target_table = fk_info["target_table"]
+                        # FKs are assumed to target tables within the same source SDIF file.
+                        remapped_fk_target_table = self.table_name_map[
+                            source_db_idx
+                        ].get(original_fk_target_table)
+                        if not remapped_fk_target_table:
+                            log.warning(
+                                f"Could not remap FK target table '{original_fk_target_table}' for column '{col_name}' in table '{old_table_name}'. FK might be dropped or invalid."
+                            )
+                            # Decide: skip FK, or raise error, or create FK pointing to original name (which might conflict or be wrong)
+                            # For now, we'll proceed without this FK if target not found in map (shouldn't happen if all tables from source are processed)
+                            continue
+
+                        col_props["foreign_key"] = {
+                            "table": remapped_fk_target_table,
+                            "column": fk_info["target_column"],
+                            "on_delete": fk_info[
+                                "on_delete"
+                            ].upper(),  # Ensure standard casing
+                            "on_update": fk_info[
+                                "on_update"
+                            ].upper(),  # Ensure standard casing
+                        }
+                        break  # Assuming one FK per 'from_column' for this col_props structure
+                columns_for_create[col_name] = col_props
+
+            source_table_metadata = table_detail_from_schema.get("metadata", {})
+            old_source_id_for_table = source_table_metadata.get("source_id")
+            if old_source_id_for_table is None:
+                raise ValueError(
+                    f"Table '{old_table_name}' from {source_db.path} is missing source_id in its metadata."
+                )
+
+            new_source_id_for_table = self._get_new_source_id(
+                source_db_idx, old_source_id_for_table
+            )
+
+            # Create the table structure in the target database
+            # Using if_exists="fail" because new_table_name should already be unique.
+            # SDIFDatabase.create_table handles complex PKs via table_constraints reconstruction.
+            actual_created_name = self.target_db.create_table(
+                table_name=new_table_name,
+                columns=columns_for_create,
+                source_id=new_source_id_for_table,
+                description=source_table_metadata.get("description"),
+                original_identifier=source_table_metadata.get("original_identifier"),
+                if_exists="fail",
+            )
+            if actual_created_name != new_table_name:
+                # This case should ideally not happen if _generate_unique_target_table_name was correct
+                # and create_table used if_exists='fail'. If create_table internally changes name even with 'fail',
+                # this is an issue. For now, assume 'fail' means it uses the name or errors.
+                log.warning(
+                    f"Table name discrepancy: expected {new_table_name}, created as {actual_created_name}. Using created name."
+                )
+                self.table_name_map[source_db_idx][old_table_name] = (
+                    actual_created_name  # Update map
+                )
+
+            # Copy data
+            try:
+                data_df = source_db.read_table(old_table_name)
+                if not data_df.empty:
+                    # SDIFDatabase.insert_data expects List[Dict].
+                    # SDIFDatabase.write_dataframe is higher level but might re-create table.
+                    # Let's use insert_data.
+
+                    # Handle data type conversions that pandas might do, to align with SQLite expectations
+                    # For example, pandas bools to int 0/1, datetimes to ISO strings.
+                    # The SDIFDatabase.write_dataframe has logic for this.
+                    # We can replicate parts or simplify if read_table and insert_data are robust.
+                    # For now, assume read_table gives compatible data for insert_data
+                    # or insert_data can handle common pandas types.
+                    # A quick check: SDIFDatabase.insert_data does not do type conversion.
+                    # SDIFDatabase.write_dataframe does. So it's safer to go df -> records -> insert
+                    # after manual conversion like in write_dataframe.
+
+                    df_copy = data_df.copy()
+                    for col_name_str in df_copy.columns:
+                        col_name = str(col_name_str)  # Ensure string
+                        if pd.api.types.is_bool_dtype(df_copy[col_name].dtype):
+                            df_copy[col_name] = df_copy[col_name].astype(int)
+                        elif pd.api.types.is_datetime64_any_dtype(
+                            df_copy[col_name].dtype
+                        ):
+                            df_copy[col_name] = df_copy[col_name].apply(
+                                lambda x: x.isoformat() if pd.notnull(x) else None
+                            )
+                        elif pd.api.types.is_timedelta64_dtype(df_copy[col_name].dtype):
+                            df_copy[col_name] = df_copy[col_name].astype(str)
+                        # Handle potential np.nan to None for JSON compatibility if objects were stored as text
+                        if df_copy[col_name].dtype == object:
+                            df_copy[col_name] = df_copy[col_name].replace(
+                                {np.nan: None}
+                            )
+
+                    data_records = df_copy.to_dict("records")
+                    if data_records:  # Ensure there are records to insert
+                        self.target_db.insert_data(actual_created_name, data_records)
+            except Exception as e:
+                log.error(
+                    f"Failed to copy data for table {old_table_name} to {actual_created_name}: {e}"
+                )
+                # Decide: continue with other tables or raise? For robustness, log and continue.
+                # Or add a strict mode flag. For now, log and continue.
+
+    def _merge_objects(self, source_db: SDIFDatabase, source_db_idx: int):
+        self.object_name_map[source_db_idx] = {}
+        for old_object_name in source_db.list_objects():
+            obj_data = source_db.get_object(
+                old_object_name, parse_json=False
+            )  # Get raw JSON strings
+            if not obj_data:
+                log.warning(
+                    f"Could not retrieve object '{old_object_name}' from {source_db.path}. Skipping."
+                )
+                continue
+
+            new_object_name = self._generate_unique_name_in_target(
+                old_object_name, self.target_db.list_objects
+            )
+            self.object_name_map[source_db_idx][old_object_name] = new_object_name
+
+            new_source_id = self._get_new_source_id(
+                source_db_idx, obj_data["source_id"]
+            )
+
+            # Data is already string from parse_json=False. Schema hint also string.
+            # SDIFDatabase.add_object expects data to be Any (serializable) and schema_hint Dict.
+            # So we need to parse them back if they are strings.
+            parsed_json_data = json.loads(obj_data["json_data"])
+            parsed_schema_hint = (
+                json.loads(obj_data["schema_hint"])
+                if obj_data.get("schema_hint")
+                else None
+            )
+
+            self.target_db.add_object(
+                object_name=new_object_name,
+                json_data=parsed_json_data,
+                source_id=new_source_id,
+                description=obj_data.get("description"),
+                schema_hint=parsed_schema_hint,
+            )
+
+    def _merge_media(self, source_db: SDIFDatabase, source_db_idx: int):
+        self.media_name_map[source_db_idx] = {}
+        for old_media_name in source_db.list_media():
+            media_entry = source_db.get_media(
+                old_media_name, parse_json=False
+            )  # Get raw JSON for tech_metadata
+            if not media_entry:
+                log.warning(
+                    f"Could not retrieve media '{old_media_name}' from {source_db.path}. Skipping."
+                )
+                continue
+
+            new_media_name = self._generate_unique_name_in_target(
+                old_media_name, self.target_db.list_media
+            )
+            self.media_name_map[source_db_idx][old_media_name] = new_media_name
+
+            new_source_id = self._get_new_source_id(
+                source_db_idx, media_entry["source_id"]
+            )
+
+            parsed_tech_metadata = (
+                json.loads(media_entry["technical_metadata"])
+                if media_entry.get("technical_metadata")
+                else None
+            )
+
+            self.target_db.add_media(
+                media_name=new_media_name,
+                media_data=media_entry["media_data"],  # Should be bytes
+                media_type=media_entry["media_type"],
+                source_id=new_source_id,
+                description=media_entry.get("description"),
+                original_format=media_entry.get("original_format"),
+                technical_metadata=parsed_tech_metadata,
+            )
+
+    def _remap_element_spec(
+        self, element_type: str, element_spec_json: str, source_db_idx: int
+    ) -> str:
+        if not element_spec_json:
+            return element_spec_json
+
+        try:
+            spec_dict = json.loads(element_spec_json)
+        except json.JSONDecodeError:
+            log.warning(
+                f"Invalid JSON in element_spec: {element_spec_json}. Returning as is."
+            )
+            return element_spec_json
+
+        new_spec_dict = spec_dict.copy()
+
+        # Remap source_id if present (relevant for 'source' element_type in annotations, not directly in semantic_links spec)
+        # Semantic links link to other entities which carry their own source_id.
+        # But if spec itself contains a source_id key (e.g. for target_element_type='source' in annotations)
+        if "source_id" in new_spec_dict and isinstance(new_spec_dict["source_id"], int):
+            new_spec_dict["source_id"] = self._get_new_source_id(
+                source_db_idx, new_spec_dict["source_id"]
+            )
+
+        # Remap names based on element_type
+        if element_type in ["table", "column"]:
+            if "table_name" in new_spec_dict:
+                new_spec_dict["table_name"] = self._get_new_table_name(
+                    source_db_idx, new_spec_dict["table_name"]
+                )
+        elif element_type == "object":  # Direct object reference
+            if "object_name" in new_spec_dict:
+                new_spec_dict["object_name"] = self._get_new_object_name(
+                    source_db_idx, new_spec_dict["object_name"]
+                )
+        elif element_type == "json_path":  # JSONPath typically refers to an object
+            if (
+                "object_name" in new_spec_dict
+            ):  # If the spec identifies the object container
+                new_spec_dict["object_name"] = self._get_new_object_name(
+                    source_db_idx, new_spec_dict["object_name"]
+                )
+        elif element_type == "media":
+            if "media_name" in new_spec_dict:
+                new_spec_dict["media_name"] = self._get_new_media_name(
+                    source_db_idx, new_spec_dict["media_name"]
+                )
+        # 'file' type needs no remapping of spec content.
+        # 'source' type: primary key is 'source_id', remapped above.
+
+        return json.dumps(new_spec_dict)
+
+    def _merge_semantic_links(self, source_db: SDIFDatabase, source_db_idx: int):
+        # SDIFDatabase.list_semantic_links default parses JSON spec. We need this.
+        source_links = source_db.list_semantic_links(parse_json=True)
+
+        for link in source_links:
+            # The specs are already dicts because parse_json=True was used.
+            try:
+                from_spec_dict = link["from_element_spec"]
+                to_spec_dict = link["to_element_spec"]
+
+                # Remap the dicts directly
+                new_from_spec_dict = self._remap_element_spec_dict(
+                    link["from_element_type"], from_spec_dict, source_db_idx
+                )
+                new_to_spec_dict = self._remap_element_spec_dict(
+                    link["to_element_type"], to_spec_dict, source_db_idx
+                )
+
+                self.target_db.add_semantic_link(
+                    link_type=link["link_type"],
+                    from_element_type=link["from_element_type"],
+                    from_element_spec=new_from_spec_dict,  # add_semantic_link takes dict
+                    to_element_type=link["to_element_type"],
+                    to_element_spec=new_to_spec_dict,  # add_semantic_link takes dict
+                    description=link.get("description"),
+                )
+            except Exception as e:
+                link_id = link.get("link_id", "Unknown")
+                log.error(
+                    f"Failed to merge semantic link ID {link_id} from {source_db.path}: {e}. Skipping link."
+                )
+
+    def _remap_element_spec_dict(
+        self, element_type: str, spec_dict: Dict, source_db_idx: int
+    ) -> Dict:
+        # Helper for _merge_semantic_links that works with dicts directly
+        new_spec_dict = spec_dict.copy()
+
+        if "source_id" in new_spec_dict and isinstance(new_spec_dict["source_id"], int):
+            new_spec_dict["source_id"] = self._get_new_source_id(
+                source_db_idx, new_spec_dict["source_id"]
+            )
+
+        if element_type in ["table", "column"]:
+            if "table_name" in new_spec_dict:
+                new_spec_dict["table_name"] = self._get_new_table_name(
+                    source_db_idx, new_spec_dict["table_name"]
+                )
+        elif element_type == "object" or (
+            element_type == "json_path" and "object_name" in new_spec_dict
+        ):
+            if "object_name" in new_spec_dict:
+                new_spec_dict["object_name"] = self._get_new_object_name(
+                    source_db_idx, new_spec_dict["object_name"]
+                )
+        elif element_type == "media":
+            if "media_name" in new_spec_dict:
+                new_spec_dict["media_name"] = self._get_new_media_name(
+                    source_db_idx, new_spec_dict["media_name"]
+                )
+        return new_spec_dict
+
+    def merge_all(self, source_sdif_paths: List[SDIFPath]):
+        # Import pandas and numpy here to avoid making them a hard dependency of the module if not used.
+        # However, SDIFDatabase itself uses them. So they are effectively dependencies.
+        global pd, np
+        import numpy as np
+        import pandas as pd
+
+        for idx, source_path_item in enumerate(source_sdif_paths):
+            source_path = Path(source_path_item)  # Ensure Path object
+            log.info(
+                f"Processing source SDIF ({idx + 1}/{len(source_sdif_paths)}): {source_path}"
+            )
+            source_db = SDIFDatabase(source_path, read_only=True)
+            try:  # Ensure source_db is closed
+                self._merge_properties(source_db, idx)
+                self._merge_sources(source_db, idx)
+                self._merge_tables(source_db, idx)  # This needs pandas for data reading
+                self._merge_objects(source_db, idx)
+                self._merge_media(source_db, idx)
+                self._merge_semantic_links(source_db, idx)
+                # Not merging sdif_annotations in this version.
+            finally:
+                source_db.close()
+
+        # Finalize target DB properties
+        try:
+            current_timestamp_utc_z = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+            self.target_db.conn.execute(
+                "UPDATE sdif_properties SET creation_timestamp = ?",
+                (current_timestamp_utc_z,),
+            )
+            self.target_db.conn.commit()
+        except sqlite3.Error as e:
+            log.error(f"Failed to update final creation_timestamp in target DB: {e}")
+            # Non-fatal, proceed.
+
+        self.target_db.close()
+        log.info(
+            f"Successfully merged {len(source_sdif_paths)} SDIF files into {self.target_db.path}"
+        )
+        return self.target_db.path
+
+
+def merge_sdif_files(sdif_paths: List[SDIFPath], output_path: Path) -> Path:
+    """
+    Merges multiple SDIF files into a single new SDIF file.
+
+    Args:
+        sdif_paths: A list of paths to the SDIF files to merge.
+        output_path: The full path where the merged SDIF file should be saved.
+                     Its parent directory will be created if it doesn't exist.
+                     If output_path is an existing file, it will be overwritten.
+                     If output_path is an existing directory, a ValueError is raised.
+
+    Returns:
+        Path to the newly created merged SDIF file (same as output_path).
+
+    Raises:
+        ValueError: If no SDIF files are provided, or output_path is invalid (e.g., an existing directory).
+        FileNotFoundError: If a source SDIF file does not exist.
+        sqlite3.Error: For database-related errors during merging.
+        RuntimeError: For critical errors like inability to generate unique names.
+    """
+    if not sdif_paths:
+        raise ValueError("No SDIF files provided for merging.")
+
+    output_path = Path(output_path).resolve()
+
+    if output_path.is_dir():
+        raise ValueError(
+            f"Output path '{output_path}' is an existing directory. Please provide a full file path."
+        )
+
+    # Ensure parent directory of output_path exists
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Ensure all source paths are Path objects and exist
+    processed_sdif_paths: List[Path] = []
+    for p in sdif_paths:
+        path_obj = Path(p).resolve()
+        if not path_obj.exists():
+            raise FileNotFoundError(f"Source SDIF file not found: {path_obj}")
+        if not path_obj.is_file():
+            raise ValueError(f"Source SDIF path is not a file: {path_obj}")
+        processed_sdif_paths.append(path_obj)
+
+    if len(processed_sdif_paths) == 1:
+        source_file = processed_sdif_paths[0]
+
+        # If the source and target are the same file, no copy is needed.
+        if source_file == output_path:
+            return source_file
+
+        shutil.copy(source_file, output_path)
+        log.info(f"Copied single SDIF file to '{output_path}' as no merge was needed.")
+        return output_path
+
+    # For multiple files, merge them into the output_path
+    merger = _SDIFMerger(output_path)
+    return merger.merge_all(processed_sdif_paths)

satif_ai-0.2.9/satif_ai/utils/merge_sdif.py

@@ -1,22 +0,0 @@
-from pathlib import Path
-from typing import List
-
-
-async def merge_sdif_files(sdif_paths: List[Path], output_dir: Path) -> Path:
-    """Placeholder function to merge multiple SDIF files into one.
-
-    Args:
-        sdif_paths: A list of paths to the SDIF files to merge.
-        output_dir: The directory where the merged file should be saved.
-
-    Returns:
-        Path to the merged SDIF file.
-    """
-    if not sdif_paths:
-        raise ValueError("No SDIF files provided for merging.")
-
-    if len(sdif_paths) == 1:
-        return sdif_paths[0]  # No merge needed
-
-    # TODO: Implement SDIF merge
-    raise NotImplementedError("Merge not implemented yet.")