tactus 0.31.2__py3-none-any.whl

tactus/stdlib/io/hdf5.py

@@ -0,0 +1,121 @@
+"""
+tactus.io.hdf5 - HDF5 file operations for Tactus.
+
+Provides HDF5 dataset read/write operations with sandboxing
+to the procedure's base directory.
+
+Requires: h5py
+
+Usage in .tac files:
+    local hdf5 = require("tactus.io.hdf5")
+
+    -- Read dataset from HDF5 file
+    local data = hdf5.read("data.h5", "measurements/temperature")
+
+    -- Write dataset to HDF5 file
+    hdf5.write("output.h5", "results/scores", {95, 87, 92, 88})
+
+    -- List all datasets in file
+    local datasets = hdf5.list("data.h5")
+"""
+
+import os
+import sys
+from typing import Any, List
+
+try:
+    import h5py
+    import numpy as np
+except ImportError:
+    raise ImportError("h5py is required for HDF5 support. Install with: pip install h5py")
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str, dataset: str) -> List[Any]:
+    """
+    Read dataset from HDF5 file.
+
+    Args:
+        filepath: Path to HDF5 file (relative to working directory)
+        dataset: Dataset path within the HDF5 file (e.g., "group/dataset")
+
+    Returns:
+        Dataset contents as a list
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        KeyError: If dataset does not exist in file
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    with h5py.File(filepath, "r") as f:
+        return f[dataset][:].tolist()
+
+
+def write(filepath: str, dataset: str, data: List[Any]) -> None:
+    """
+    Write data to HDF5 dataset.
+
+    If the dataset already exists, it will be replaced.
+    Parent groups will be created automatically.
+
+    Args:
+        filepath: Path to HDF5 file
+        dataset: Dataset path within the HDF5 file (e.g., "group/dataset")
+        data: Data to write (list or nested lists for multi-dimensional arrays)
+
+    Raises:
+        PermissionError: If path is outside working directory
+        ValueError: If data is invalid
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    with h5py.File(filepath, "a") as f:
+        # Delete existing dataset if present
+        if dataset in f:
+            del f[dataset]
+
+        # Create dataset
+        f.create_dataset(dataset, data=np.array(data))
+
+
+def list(filepath: str) -> List[str]:
+    """
+    List all datasets in HDF5 file.
+
+    Args:
+        filepath: Path to HDF5 file
+
+    Returns:
+        List of dataset paths
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    datasets = []
+
+    with h5py.File(filepath, "r") as f:
+
+        def visitor(name, obj):
+            if isinstance(obj, h5py.Dataset):
+                datasets.append(name)
+
+        f.visititems(visitor)
+
+    return datasets
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write", "list"]

tactus/stdlib/io/json.py

@@ -0,0 +1,109 @@
+"""
+tactus.io.json - JSON file operations for Tactus.
+
+Provides JSON read/write operations with automatic path validation
+and sandboxing to the procedure's base directory.
+
+Usage in .tac files:
+    local json = require("tactus.io.json")
+
+    -- Read JSON file
+    local data = json.read("config.json")
+
+    -- Write JSON file
+    json.write("output.json", {name = "Alice", score = 95})
+
+    -- Encode/decode strings
+    local str = json.encode({key = "value"})
+    local obj = json.decode('{"key": "value"}')
+"""
+
+import json
+import os
+import sys
+from typing import Any, Optional
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str) -> Any:
+    """
+    Read and parse a JSON file.
+
+    Args:
+        filepath: Path to JSON file (relative to working directory)
+
+    Returns:
+        Parsed JSON data (dict, list, or primitive)
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        json.JSONDecodeError: If file is not valid JSON
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write(filepath: str, data: Any, indent: int = 2) -> None:
+    """
+    Write data to a JSON file.
+
+    Args:
+        filepath: Path to JSON file
+        data: Data to write (dict, list, or primitive)
+        indent: Indentation level (default 2)
+
+    Raises:
+        PermissionError: If path is outside working directory
+        TypeError: If data is not JSON serializable
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=indent, ensure_ascii=False)
+
+
+def encode(data: Any, indent: Optional[int] = None) -> str:
+    """
+    Encode data to JSON string.
+
+    Args:
+        data: Data to encode
+        indent: Optional indentation
+
+    Returns:
+        JSON string
+
+    Raises:
+        TypeError: If data is not JSON serializable
+    """
+    return json.dumps(data, indent=indent, ensure_ascii=False)
+
+
+def decode(json_string: str) -> Any:
+    """
+    Decode JSON string to data.
+
+    Args:
+        json_string: JSON string to parse
+
+    Returns:
+        Parsed data
+
+    Raises:
+        json.JSONDecodeError: If string is not valid JSON
+    """
+    return json.loads(json_string)
+
+
+# Explicit exports (only these functions exposed to Lua)
+__tactus_exports__ = ["read", "write", "encode", "decode"]

tactus/stdlib/io/parquet.py

@@ -0,0 +1,83 @@
+"""
+tactus.io.parquet - Apache Parquet file operations for Tactus.
+
+Provides Parquet read/write operations with sandboxing
+to the procedure's base directory.
+
+Requires: pyarrow
+
+Usage in .tac files:
+    local parquet = require("tactus.io.parquet")
+
+    -- Read Parquet file
+    local data = parquet.read("data.parquet")
+
+    -- Write Parquet file
+    parquet.write("output.parquet", {
+        {name = "Alice", score = 95},
+        {name = "Bob", score = 87}
+    })
+"""
+
+import os
+import sys
+from typing import Any, Dict, List
+
+try:
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+except ImportError:
+    raise ImportError("pyarrow is required for Parquet support. Install with: pip install pyarrow")
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str) -> List[Dict[str, Any]]:
+    """
+    Read Parquet file, returning list of dictionaries.
+
+    Args:
+        filepath: Path to Parquet file (relative to working directory)
+
+    Returns:
+        List of dictionaries, one per row
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    table = pq.read_table(filepath)
+    return table.to_pylist()
+
+
+def write(filepath: str, data: List[Dict[str, Any]]) -> None:
+    """
+    Write list of dictionaries to Parquet file.
+
+    Args:
+        filepath: Path to Parquet file
+        data: List of dictionaries to write
+
+    Raises:
+        PermissionError: If path is outside working directory
+        ValueError: If data is empty or invalid
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    if not data:
+        raise ValueError("Cannot write empty data to Parquet")
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    table = pa.Table.from_pylist(data)
+    pq.write_table(table, filepath)
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write"]

tactus/stdlib/io/tsv.py

@@ -0,0 +1,88 @@
+"""
+tactus.io.tsv - TSV (tab-separated values) file operations for Tactus.
+
+Provides TSV read/write operations with automatic header handling
+and sandboxing to the procedure's base directory.
+
+Usage in .tac files:
+    local tsv = require("tactus.io.tsv")
+
+    -- Read TSV file
+    local data = tsv.read("data.tsv")
+
+    -- Write TSV file
+    tsv.write("output.tsv", {
+        {name = "Alice", age = 30},
+        {name = "Bob", age = 25}
+    })
+"""
+
+import csv
+import os
+import sys
+from typing import Any, Dict, List, Optional
+
+# Get context (injected by loader)
+_ctx = getattr(sys.modules[__name__], "__tactus_context__", None)
+
+
+def read(filepath: str) -> List[Dict[str, Any]]:
+    """
+    Read TSV file, returning list of dictionaries with headers as keys.
+
+    Args:
+        filepath: Path to TSV file (relative to working directory)
+
+    Returns:
+        List of dictionaries, one per row
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If path is outside working directory
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    with open(filepath, "r", encoding="utf-8", newline="") as f:
+        reader = csv.DictReader(f, delimiter="\t")
+        return list(reader)
+
+
+def write(
+    filepath: str, data: List[Dict[str, Any]], options: Optional[Dict[str, Any]] = None
+) -> None:
+    """
+    Write list of dictionaries to TSV file.
+
+    Args:
+        filepath: Path to TSV file
+        data: List of dictionaries to write
+        options: Optional dict with 'headers' key for custom header order
+
+    Raises:
+        PermissionError: If path is outside working directory
+        ValueError: If data is empty or cannot determine headers
+    """
+    if _ctx:
+        filepath = _ctx.validate_path(filepath)
+
+    if not data:
+        raise ValueError("Cannot write empty data to TSV")
+
+    # Determine headers
+    options = options or {}
+    headers = options.get("headers")
+    if not headers:
+        headers = list(data[0].keys())
+
+    # Create parent directories
+    os.makedirs(os.path.dirname(filepath) or ".", exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=headers, delimiter="\t")
+        writer.writeheader()
+        writer.writerows(data)
+
+
+# Explicit exports
+__tactus_exports__ = ["read", "write"]

tactus/stdlib/loader.py

@@ -0,0 +1,274 @@
+"""
+Python stdlib module loader for Tactus.
+
+Provides a mechanism to load Python modules from tactus/stdlib/
+via Lua's require() function. Only modules with the "tactus." prefix
+can be loaded, ensuring user code cannot import arbitrary Python modules.
+"""
+
+import importlib.util
+import inspect
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Callable, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class StdlibModuleLoader:
+    """
+    Loads Python modules from tactus/stdlib/ for Lua require().
+
+    Security: Only loads from the stdlib path, never user directories.
+    """
+
+    def __init__(self, lua_sandbox, base_path: str):
+        """
+        Initialize the stdlib loader.
+
+        Args:
+            lua_sandbox: LuaSandbox instance for table creation
+            base_path: Base path for file operations (passed to modules)
+        """
+        self.lua_sandbox = lua_sandbox
+        self.base_path = base_path
+        self.stdlib_path = self._get_stdlib_path()
+        self.loaded_modules: Dict[str, Any] = {}
+
+    def _get_stdlib_path(self) -> Path:
+        """Get the stdlib directory path."""
+        import tactus
+
+        package_root = Path(tactus.__file__).parent
+        return package_root / "stdlib"
+
+    def create_loader_function(self) -> Callable:
+        """
+        Create the loader function to inject into Lua's package.loaders.
+
+        Returns:
+            Python function that Lua can call as a module loader
+        """
+
+        def python_stdlib_loader(module_name: str):
+            """
+            Lua module loader for Python stdlib modules.
+
+            Args:
+                module_name: Module path like "tactus.io.json"
+
+            Returns:
+                Lua table with module functions, or None if not found
+            """
+            # Only handle tactus.* modules (stdlib)
+            if not module_name.startswith("tactus."):
+                return None
+
+            # Convert module path to file path
+            # "tactus.io.json" -> "io/json.py"
+            relative_path = module_name[7:].replace(".", "/")  # Remove "tactus." prefix
+            python_path = self.stdlib_path / f"{relative_path}.py"
+
+            # Security: Verify path is within stdlib
+            try:
+                python_path = python_path.resolve()
+                python_path.relative_to(self.stdlib_path.resolve())
+            except ValueError:
+                logger.warning(f"Path traversal attempt blocked: {module_name}")
+                return None
+
+            # Check if Python module exists
+            if not python_path.exists():
+                return None
+
+            # Load and wrap the Python module
+            try:
+                return self._load_python_module(module_name, python_path)
+            except Exception as e:
+                logger.error(f"Failed to load stdlib module {module_name}: {e}")
+                # Re-raise as a string for Lua error handling
+                raise RuntimeError(f"Failed to load module '{module_name}': {e}")
+
+        return python_stdlib_loader
+
+    def _load_python_module(self, module_name: str, path: Path) -> Any:
+        """
+        Load a Python module and convert to Lua table.
+
+        Args:
+            module_name: Full module name (e.g., "tactus.io.json")
+            path: Path to Python file
+
+        Returns:
+            Lua table with module exports
+        """
+        # Check cache
+        if module_name in self.loaded_modules:
+            return self.loaded_modules[module_name]
+
+        # Create unique module name for Python's import system
+        internal_name = f"tactus_stdlib_{module_name.replace('.', '_')}"
+
+        # Load module dynamically
+        spec = importlib.util.spec_from_file_location(internal_name, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not load spec for {path}")
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[internal_name] = module
+
+        # Inject context before executing module
+        module.__tactus_context__ = TactusStdlibContext(
+            base_path=self.base_path, lua_sandbox=self.lua_sandbox
+        )
+
+        spec.loader.exec_module(module)
+
+        # Get exports
+        exports = self._get_module_exports(module)
+
+        # Convert to Lua table
+        lua_table = self._create_lua_module(exports)
+
+        # Cache
+        self.loaded_modules[module_name] = lua_table
+
+        logger.debug(f"Loaded stdlib Python module: {module_name}")
+        return lua_table
+
+    def _get_module_exports(self, module) -> Dict[str, Callable]:
+        """
+        Get exportable functions from a module.
+
+        Args:
+            module: Loaded Python module
+
+        Returns:
+            Dict of function name -> function
+        """
+        exports = {}
+
+        # Check for explicit exports list
+        explicit_exports = getattr(module, "__tactus_exports__", None)
+
+        for name, obj in inspect.getmembers(module):
+            # Skip private
+            if name.startswith("_"):
+                continue
+
+            # Skip non-functions
+            if not callable(obj):
+                continue
+
+            # Skip if not in explicit exports (when defined)
+            if explicit_exports is not None and name not in explicit_exports:
+                continue
+
+            # Skip imports from other modules
+            if hasattr(obj, "__module__") and obj.__module__ != module.__name__:
+                continue
+
+            exports[name] = obj
+
+        return exports
+
+    def _create_lua_module(self, exports: Dict[str, Callable]) -> Any:
+        """
+        Create a Lua table from Python exports.
+
+        Args:
+            exports: Dict of function name -> function
+
+        Returns:
+            Lua table
+        """
+        lua_table = self.lua_sandbox.lua.table()
+
+        for name, func in exports.items():
+            # Wrap function to handle type conversion
+            wrapped = self._wrap_function(func, name)
+            lua_table[name] = wrapped
+
+        return lua_table
+
+    def _wrap_function(self, func: Callable, name: str) -> Callable:
+        """
+        Wrap a Python function for Lua interop.
+
+        Handles:
+        - Lua table -> Python dict conversion
+        - Python dict -> Lua table conversion
+        - Exception propagation
+        """
+
+        def wrapper(*args):
+            try:
+                # Convert Lua tables to Python dicts
+                python_args = [self._lua_to_python(arg) for arg in args]
+
+                # Call function
+                result = func(*python_args)
+
+                # Convert result to Lua
+                return self._python_to_lua(result)
+
+            except Exception as e:
+                logger.error(f"Error in stdlib function {name}: {e}")
+                raise
+
+        return wrapper
+
+    def _lua_to_python(self, value: Any) -> Any:
+        """Convert Lua value to Python."""
+        # Use existing conversion from safe_file_library
+        from tactus.utils.safe_file_library import _lua_to_python
+
+        return _lua_to_python(value)
+
+    def _python_to_lua(self, value: Any) -> Any:
+        """Convert Python value to Lua table recursively."""
+        if value is None:
+            return None
+        if isinstance(value, (str, int, float, bool)):
+            return value
+        if isinstance(value, dict):
+            # Convert dict to Lua table recursively
+            lua_table = self.lua_sandbox.lua.table()
+            for k, v in value.items():
+                lua_table[k] = self._python_to_lua(v)
+            return lua_table
+        if isinstance(value, (list, tuple)):
+            # Convert to Lua array (1-indexed)
+            lua_table = self.lua_sandbox.lua.table()
+            for i, item in enumerate(value, start=1):
+                lua_table[i] = self._python_to_lua(item)
+            return lua_table
+        # Fallback
+        return value
+
+
+class TactusStdlibContext:
+    """
+    Context object passed to stdlib Python modules.
+
+    Provides access to sandbox resources in a controlled way.
+    """
+
+    def __init__(self, base_path: str, lua_sandbox):
+        self.base_path = base_path
+        self._lua_sandbox = lua_sandbox
+        self._path_validator = None
+
+    @property
+    def path_validator(self):
+        """Lazy-create path validator."""
+        if self._path_validator is None:
+            from tactus.utils.safe_file_library import PathValidator
+
+            self._path_validator = PathValidator(self.base_path)
+        return self._path_validator
+
+    def validate_path(self, filepath: str) -> str:
+        """Validate and resolve a file path."""
+        return self.path_validator.validate(filepath)

tactus/stdlib/tac/tactus/tools/done.tac

@@ -0,0 +1,33 @@
+--[[
+tactus.tools.done: Signal task completion
+
+Usage:
+    local done = require("tactus.tools.done")
+
+    -- In an agent's toolset
+    agent = Agent {
+        tools = {"done"},
+        ...
+    }
+
+    -- Check if done was called
+    if done.called() then
+        local result = done.last_call()
+    end
+]]--
+
+-- Provide explicit name so the tool is recorded/mocked as "done"
+return Tool {
+    name = "done",
+    description = "Signal task completion",
+    input = {
+        reason = field.string{required = false, description = "Reason for completion"}
+    },
+    function(args)
+        return {
+            status = "completed",
+            reason = args.reason or "Task completed",
+            tool = "done"
+        }
+    end
+}