scihist 0.1.0__py3-none-any.whl

scihist/__init__.py

@@ -0,0 +1,68 @@
+"""SciHist: Lineage-tracked batch execution for scientific data pipelines.
+
+This package adds lineage tracking on top of scidb. It provides the same
+for_each() interface as scidb, but automatically wraps functions in
+LineageFcn for provenance recording.
+
+Example:
+    from scihist import for_each, Fixed, configure_database
+    from scilineage import lineage_fcn
+
+    configure_database("experiment.duckdb", ["subject", "session"])
+
+    @lineage_fcn
+    def process_data(raw, calibration):
+        return raw * calibration
+
+    for_each(
+        process_data,
+        inputs={"raw": RawData, "calibration": Fixed(Calibration, session="baseline")},
+        outputs=[ProcessedData],
+        subject=[1, 2, 3],
+        session=["A", "B", "C"],
+    )
+"""
+
+from .foreach import for_each, save
+from .database import configure_database, find_by_lineage
+from .state import check_combo_state, check_node_state, check_multiple_nodes_state
+
+# Re-export DB wrappers from scidb
+from scidb import Fixed, Merge, ColumnSelection, ForEachConfig
+
+# Re-export scifor helpers
+from scifor import Col, set_schema, get_schema, PathInput
+
+# Re-export scilineage system
+from scilineage import lineage_fcn, LineageFcn, LineageFcnResult, LineageFcnInvocation
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core batch execution
+    "for_each",
+    "save",
+    # Configuration
+    "configure_database",
+    # Lineage query
+    "find_by_lineage",
+    # Node staleness
+    "check_combo_state",
+    "check_node_state",
+    "check_multiple_nodes_state",
+    # DB wrappers
+    "Fixed",
+    "Merge",
+    "ColumnSelection",
+    "ForEachConfig",
+    "PathInput",
+    # Schema helpers
+    "Col",
+    "set_schema",
+    "get_schema",
+    # Lineage system
+    "lineage_fcn",
+    "LineageFcn",
+    "LineageFcnResult",
+    "LineageFcnInvocation",
+]

scihist/database.py

@@ -0,0 +1,51 @@
+"""SciHist database configuration — wraps scidb.configure_database with cache backend registration."""
+
+from typing import Any
+
+
+def configure_database(
+    db_path: str,
+    schema_keys: list[str] | None = None,
+    **kwargs,
+) -> Any:
+    """Configure the active database and register it as the lineage cache backend.
+
+    This is the scihist wrapper around scidb.configure_database(). In addition
+    to opening the DuckDB-backed database, it registers the database as the
+    cache backend so that lineage-tracked computations can look up previously
+    computed results.
+
+    Args:
+        db_path: Path to the DuckDB database file.
+        schema_keys: List of metadata keys that form the dataset schema.
+        **kwargs: Additional keyword arguments forwarded to scidb.configure_database().
+
+    Returns:
+        The configured DatabaseManager instance.
+    """
+    from scidb import configure_database as _scidb_configure
+    from scilineage import configure_backend
+
+    db = _scidb_configure(db_path, schema_keys, **kwargs)
+    configure_backend(db)
+    return db
+
+
+def find_by_lineage(invocation) -> list | None:
+    """Find output values by computation lineage.
+
+    Given a LineageFcnInvocation (function + inputs), finds any previously
+    computed outputs that match by querying the _lineage table via the active
+    database.
+
+    Args:
+        invocation: The LineageFcnInvocation computation to look up.
+
+    Returns:
+        List of output values if found, None otherwise.
+    """
+    from scidb.database import get_database
+
+    db = get_database()
+    lineage_hash = invocation.compute_lineage_hash()
+    return db.find_by_lineage_hash(lineage_hash)