floe-python 0.5.0__tar.gz → 0.5.1__tar.gz

{floe_python-0.5.0 → floe_python-0.5.1}/Cargo.lock

@@ -3508,7 +3508,7 @@ dependencies = [
 
 [[package]]
 name = "floe-cli"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "assert_cmd",
  "clap",
@@ -3521,7 +3521,7 @@ dependencies = [
 
 [[package]]
 name = "floe-core"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "apache-avro 0.16.0",
  "arrow",
@@ -3565,7 +3565,7 @@ dependencies = [
 
 [[package]]
 name = "floe-python"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "floe-core",
  "pyo3",

{floe_python-0.5.0 → floe_python-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: floe-python
-Version: 0.5.0
+Version: 0.5.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "floe-core"
-version = "0.5.0"
+version = "0.5.1"
 edition = "2021"
 description = "Core library for Floe, a YAML-driven technical ingestion tool."
 license = "MIT"

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-core/README.md

@@ -50,6 +50,11 @@ docker run --rm -v "$PWD:/work" ghcr.io/malon64/floe:latest run -c /work/config.
 Or download a prebuilt binary from [GitHub Releases](https://github.com/malon64/floe/releases), or `cargo install floe-cli`.  
 → [Full installation guide](docs/installation.md)
 
+**DuckDB sink** is shipped as a companion (the default artifacts are lean): use the
+`ghcr.io/malon64/floe-duckdb` image, a `floe-duckdb` binary on your `PATH`, or the
+off-PyPI `floe-duckdb` wheel. The lean `floe` auto-delegates DuckDB-sink runs to it.
+→ [DuckDB support](docs/installation.md#duckdb-support-companion-distribution)
+
 ## Quick start
 
 ```bash

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "floe-python"
-version = "0.5.0"
+version = "0.5.1"
 edition = "2021"
 description = "Python bindings for floe-core (PyO3-based)"
 license = "Apache-2.0"
@@ -14,7 +14,7 @@ name = "_floe"
 crate-type = ["cdylib"]
 
 [dependencies]
-floe-core = { path = "../floe-core", version = "0.5.0", default-features = false }
+floe-core = { path = "../floe-core", version = "0.5.1", default-features = false }
 pyo3 = { version = "0.22", features = ["extension-module", "abi3-py310"] }
 serde_json = "1"
 

floe_python-0.5.1/crates/floe-python/pyproject.duckdb.toml

@@ -0,0 +1,62 @@
+# Build manifest for the heavy `floe-duckdb` companion wheel.
+#
+# This builds the SAME `floe-python` crate as `pyproject.toml`, but with the
+# `duckdb` feature on (bundled native DuckDB). The bundled C++ build fails to
+# cross-compile in the manylinux/musllinux wheel containers and exceeds PyPI's
+# 100 MB per-file limit, so this wheel is published OFF PyPI (GitHub Release
+# assets + a PEP 503 index, like PyTorch's own download index) rather than to
+# PyPI.
+#
+# It compiles to a distinct extension module — `floe._floe_duckdb` — and ships
+# ONLY that compiled `.so` (no python-source). That lets it install into the
+# same `floe` package directory as the lean PyPI `floe` wheel without file
+# collisions, so the two coexist and the lean `floe.run` delegates DuckDB sinks
+# to this companion at runtime.
+#
+# Build with: maturin build --release --features duckdb \
+#               --manifest-path crates/floe-python/Cargo.toml \
+#               -o dist crates/floe-python/pyproject.duckdb.toml
+[build-system]
+requires = ["maturin>=1.7,<2"]
+build-backend = "maturin"
+
+[project]
+name = "floe-duckdb"
+version = "0.5.1"
+description = "DuckDB companion extension for floe — adds the native DuckDB sink to the floe Python package"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Floe contributors" }]
+keywords = ["ingestion", "data-quality", "yaml", "polars", "duckdb"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Rust",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+# The lean `floe` wheel provides the Python source and public API; this companion
+# only contributes the compiled DuckDB extension module into that package. Pin to
+# the exact lean version so the companion's `_floe_duckdb` ABI always matches the
+# `floe` package it plugs into.
+dependencies = ["floe-python==0.5.1"]
+
+[project.urls]
+Homepage = "https://github.com/malon64/floe"
+Repository = "https://github.com/malon64/floe"
+"Bug Tracker" = "https://github.com/malon64/floe/issues"
+
+[tool.maturin]
+# Compiled extension is installed as floe._floe_duckdb (matches the
+# `#[pymodule] fn _floe_duckdb` entry point gated behind the `duckdb` feature).
+# No python-source: ship only the .so so this coexists with the lean wheel.
+module-name = "floe._floe_duckdb"
+manifest-path = "Cargo.toml"
+features = ["duckdb"]

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-python/src/functions.rs

@@ -105,6 +105,40 @@ pub fn load_config(config_path: &str) -> PyResult<PyRootConfig> {
         .map_err(to_py_err)
 }
 
+/// True when the config writes to a DuckDB *accepted* sink. The lean `floe`
+/// Python wrapper calls this to decide whether a run must be delegated to the
+/// `floe._floe_duckdb` companion module. Only the accepted sink can target
+/// DuckDB: rejected sinks accept `csv` only, so a `rejected.format: duckdb` is
+/// always invalid and must fall through to the lean run path so its real
+/// unsupported-rejected-sink validation error surfaces, rather than being
+/// delegated (which would yield a misleading companion-install hint). The same
+/// `profile_vars` / `profile_path` the run will use are applied first, so a sink
+/// format selected through a profile variable (e.g. `format: "{{SINK_FORMAT}}"`)
+/// is detected and delegated rather than silently run on the lean build. A load
+/// failure returns `false` so the lean run path surfaces the real error rather
+/// than masking it.
+#[pyfunction]
+#[pyo3(signature = (config_path, profile_vars=None, profile_path=None))]
+pub fn config_targets_duckdb(
+    config_path: &str,
+    profile_vars: Option<HashMap<String, String>>,
+    profile_path: Option<String>,
+) -> bool {
+    let path = Path::new(config_path);
+    let vars = match load_optional_profile(profile_path, profile_vars) {
+        Ok(Some(profile)) => profile.variables,
+        Ok(None) => HashMap::new(),
+        Err(_) => return false,
+    };
+    match floe_core::load_config_with_profile_vars(path, &vars) {
+        Ok(config) => config
+            .entities
+            .iter()
+            .any(|entity| entity.sink.accepted.format == "duckdb"),
+        Err(_) => false,
+    }
+}
+
 #[pyfunction]
 pub fn extract_config_env_vars(config_path: &str) -> PyResult<HashMap<String, String>> {
     let path = Path::new(config_path);

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-python/src/lib.rs

@@ -11,8 +11,13 @@ use types::config::{PyEntityConfig, PyRootConfig};
 use types::errors::{FloeConfigError, FloeError, FloeIoError, FloeRunError, FloeStorageError};
 use types::outcome::PyRunOutcome;
 
-#[pymodule]
-fn _floe(m: &Bound<'_, PyModule>) -> PyResult<()> {
+// Shared registration for both the lean (`_floe`) and full (`_floe_duckdb`)
+// extension modules. The two entry points below differ only in name so the
+// compiled symbol (`PyInit__floe` vs `PyInit__floe_duckdb`) matches the dotted
+// module each wheel installs; everything they expose is identical save for the
+// `HAS_DUCKDB` capability flag the lean Python wrapper uses to decide whether to
+// delegate a DuckDB-sink run to the companion module.
+fn register(m: &Bound<'_, PyModule>) -> PyResult<()> {
     // Exception hierarchy
     m.add("FloeError", m.py().get_type_bound::<FloeError>())?;
     m.add(
@@ -26,6 +31,10 @@ fn _floe(m: &Bound<'_, PyModule>) -> PyResult<()> {
     )?;
     m.add("FloeIoError", m.py().get_type_bound::<FloeIoError>())?;
 
+    // Capability flag: true only in the `+duckdb` build. The lean Python wrapper
+    // reads this to know whether it must delegate DuckDB sinks to the companion.
+    m.add("HAS_DUCKDB", cfg!(feature = "duckdb"))?;
+
     // Types
     m.add_class::<PyRootConfig>()?;
     m.add_class::<PyEntityConfig>()?;
@@ -38,6 +47,7 @@ fn _floe(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(functions::extract_config_env_vars, m)?)?;
     m.add_function(wrap_pyfunction!(functions::inspect_entity_state, m)?)?;
     m.add_function(wrap_pyfunction!(functions::reset_entity_state, m)?)?;
+    m.add_function(wrap_pyfunction!(functions::config_targets_duckdb, m)?)?;
 
     // Observer
     m.add_function(wrap_pyfunction!(observer::set_observer, m)?)?;
@@ -45,3 +55,19 @@ fn _floe(m: &Bound<'_, PyModule>) -> PyResult<()> {
 
     Ok(())
 }
+
+/// Lean extension module, installed as `floe._floe` by the PyPI `floe` wheel.
+#[cfg(not(feature = "duckdb"))]
+#[pymodule]
+fn _floe(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    register(m)
+}
+
+/// Full extension module, installed as `floe._floe_duckdb` by the off-PyPI
+/// `floe-duckdb` companion wheel. Ships only the compiled `.so` into the shared
+/// `floe` package so it can coexist with the lean wheel.
+#[cfg(feature = "duckdb")]
+#[pymodule]
+fn _floe_duckdb(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    register(m)
+}

{floe_python-0.5.0 → floe_python-0.5.1}/crates/floe-python/src/types/outcome.rs

@@ -48,6 +48,24 @@ impl From<DryRunEntityPreview> for DryRunPreviewData {
     }
 }
 
+impl DryRunPreviewData {
+    fn from_dict(d: &Bound<'_, PyAny>) -> PyResult<Self> {
+        Ok(DryRunPreviewData {
+            name: d.get_item("name")?.extract()?,
+            input_path: d.get_item("input_path")?.extract()?,
+            input_format: d.get_item("input_format")?.extract()?,
+            accepted_path: d.get_item("accepted_path")?.extract()?,
+            accepted_format: d.get_item("accepted_format")?.extract()?,
+            rejected_path: d.get_item("rejected_path")?.extract()?,
+            rejected_format: d.get_item("rejected_format")?.extract()?,
+            archive_path: d.get_item("archive_path")?.extract()?,
+            archive_storage: d.get_item("archive_storage")?.extract()?,
+            report_file: d.get_item("report_file")?.extract()?,
+            scanned_files: d.get_item("scanned_files")?.extract()?,
+        })
+    }
+}
+
 impl TryFrom<RunOutcome> for PyRunOutcome {
     type Error = serde_json::Error;
 
@@ -79,6 +97,46 @@ fn json_loads<'py>(py: Python<'py>, s: &str) -> PyResult<Bound<'py, PyAny>> {
 
 #[pymethods]
 impl PyRunOutcome {
+    /// Rebuild a lean `RunOutcome` from the `to_dict()` payload of a companion's
+    /// `RunOutcome`. The lean `_floe` and companion `_floe_duckdb` are separate
+    /// native libraries, so a companion-returned outcome is a *different* Python
+    /// class. Delegated DuckDB runs round-trip through this so callers always get
+    /// the lean `RunOutcome` type they imported, not the companion's.
+    #[staticmethod]
+    fn from_dict(data: Bound<'_, PyAny>) -> PyResult<Self> {
+        let py = data.py();
+        let json = py.import_bound("json")?;
+        let dumps = |obj: Bound<'_, PyAny>| -> PyResult<String> {
+            json.call_method1("dumps", (obj,))?.extract()
+        };
+        let run_id: String = data.get_item("run_id")?.extract()?;
+        let report_base_path: Option<String> = data.get_item("report_base_path")?.extract()?;
+        let dry_run: bool = data.get_item("dry_run")?.extract()?;
+        let summary_json = dumps(data.get_item("summary")?)?;
+        let mut entity_reports_json = Vec::new();
+        for item in data.get_item("entity_reports")?.iter()? {
+            entity_reports_json.push(dumps(item?)?);
+        }
+        let previews = data.get_item("dry_run_previews")?;
+        let dry_run_previews_data = if previews.is_none() {
+            None
+        } else {
+            let mut v = Vec::new();
+            for item in previews.iter()? {
+                v.push(DryRunPreviewData::from_dict(&item?)?);
+            }
+            Some(v)
+        };
+        Ok(PyRunOutcome {
+            run_id,
+            report_base_path,
+            dry_run,
+            summary_json,
+            entity_reports_json,
+            dry_run_previews_data,
+        })
+    }
+
     #[getter]
     fn summary(&self, py: Python<'_>) -> PyResult<PyObject> {
         Ok(json_loads(py, &self.summary_json)?.into_py(py))

{floe_python-0.5.0 → floe_python-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "floe-python"
-version = "0.5.0"
+version = "0.5.1"
 description = "Python bindings for floe-core — run floe pipelines at Rust speed from Python and notebooks"
 readme = "README.md"
 requires-python = ">=3.10"

floe_python-0.5.1/python/floe/__init__.py

@@ -0,0 +1,222 @@
+"""
+floe — Python bindings for the floe ingestion engine.
+
+Run floe pipelines at Rust speed from Python notebooks::
+
+    import floe
+
+    # Live progress
+    floe.set_observer(lambda e: print(f"[{e['event']}]", e.get("name", "")))
+
+    # Validate config
+    floe.validate("pipeline.yml")
+
+    # Execute pipeline
+    outcome = floe.run("pipeline.yml", entities=["customers"])
+    print(outcome.summary["results"])
+
+    # Dry run
+    outcome = floe.run("pipeline.yml", dry_run=True)
+    for p in outcome.dry_run_previews:
+        print(p["name"], p["scanned_files"])
+
+    # Inspect incremental state
+    state = floe.inspect_entity_state("pipeline.yml", "customers")
+    print(state["incremental_mode"], state["state"])
+
+    # Use a profile (with catalog / variable overrides)
+    floe.run("pipeline.yml", profile_path="profile.yml")
+    floe.run("pipeline.yml", profile_vars={"output_bucket": "s3://my-bucket"})
+"""
+
+import importlib
+import importlib.util
+import sys
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("floe-python")
+except Exception:
+    __version__ = "unknown"
+
+from floe._floe import (
+    FloeError,
+    FloeConfigError,
+    FloeRunError,
+    FloeStorageError,
+    FloeIoError,
+    RootConfig,
+    EntityConfig,
+    RunOutcome,
+    validate,
+    run as _run,
+    load_config,
+    extract_config_env_vars,
+    inspect_entity_state,
+    reset_entity_state,
+    set_observer as _lean_set_observer,
+    clear_observer as _lean_clear_observer,
+)
+from floe import _floe as _lean
+
+# DuckDB sinks compile a bundled native build that is too large for PyPI, so the
+# published `floe` wheel is lean. DuckDB support ships as a separate off-PyPI
+# `floe-duckdb` wheel that installs a `floe._floe_duckdb` companion extension into
+# this same package. When a run targets a DuckDB sink and this is the lean build,
+# `run` transparently delegates to that companion, mirroring the lean `floe` CLI
+# re-execing the `floe-duckdb` binary. Install instructions for the companion:
+# `--index-url` (not `--extra-index-url`) so pip resolves the `floe-duckdb`
+# name ONLY from the off-PyPI index: `floe-duckdb` is intentionally absent from
+# PyPI, and `--extra-index-url` would leave PyPI in play, letting a squatted /
+# higher-version `floe-duckdb` there shadow the real companion (dependency
+# confusion). The companion's `floe-python` dependency is already satisfied
+# here — this hint only fires from an installed lean `floe` — so replacing PyPI
+# for this single install does not break dependency resolution.
+_DUCKDB_INSTALL_HINT = (
+    "this config writes to a DuckDB sink, but the installed `floe` wheel is the "
+    "lean build without DuckDB support and the `floe-duckdb` companion wheel is "
+    "not installed. Install it from the off-PyPI index, e.g. "
+    "`pip install floe-duckdb --index-url "
+    "https://malon64.github.io/floe/simple/`, or use the "
+    "`ghcr.io/malon64/floe-duckdb` image."
+)
+
+
+# The lean `_floe` and companion `_floe_duckdb` are separate native libraries
+# with independent observer state, so the registered callback must be mirrored
+# into the companion before a delegated run or its progress/log events are lost.
+# Track the active observer here so delegation can re-install it.
+_current_observer = None
+
+
+def set_observer(callback):
+    """Register a callback for live run/validation events.
+
+    Mirrors into the DuckDB companion only if it is *already* loaded, so
+    delegated DuckDB runs emit the same events as native runs. Registering an
+    observer must not trigger a companion import: if the companion is installed
+    but its native extension fails to load, that error should surface when a
+    DuckDB run is actually attempted, not as a side effect of setting an
+    observer. `run` re-installs the tracked observer into the companion right
+    before delegating, so a companion loaded later still gets the callback.
+    """
+    global _current_observer
+    _current_observer = callback
+    companion = _loaded_duckdb_module()
+    if companion is not None:
+        companion.set_observer(callback)
+    return _lean_set_observer(callback)
+
+
+def clear_observer():
+    """Remove the previously registered event callback."""
+    global _current_observer
+    _current_observer = None
+    companion = _loaded_duckdb_module()
+    if companion is not None:
+        companion.clear_observer()
+    return _lean_clear_observer()
+
+
+def _loaded_duckdb_module():
+    """Return the companion module only if it is already imported, else None.
+
+    Unlike `_duckdb_module`, this never triggers an import, so it cannot raise a
+    companion load error. Used on paths (observer registration) where a broken
+    companion must not surface until a DuckDB run is actually attempted.
+    """
+    return sys.modules.get("floe._floe_duckdb")
+
+
+def _duckdb_module():
+    """Return the `floe._floe_duckdb` companion extension, or None if not installed.
+
+    A genuinely absent companion maps to None. If the companion IS installed but
+    its native extension fails to load (incompatible libc, unresolved symbol), the
+    loader error is allowed to propagate so it surfaces instead of a misleading
+    "companion wheel is not installed" hint. `find_spec` distinguishes the two:
+    `from floe import _floe_duckdb` would raise a plain ImportError for the absent
+    case too (attribute fallback), so the exception type alone cannot tell them
+    apart — but `find_spec` returns None only when the module is truly not there.
+    """
+    if importlib.util.find_spec("floe._floe_duckdb") is None:
+        return None
+    return importlib.import_module("floe._floe_duckdb")
+
+
+def run(config_path, *args, **kwargs):
+    """Execute a floe pipeline.
+
+    Transparently delegates to the `floe-duckdb` companion when the config
+    targets a DuckDB sink and this lean build lacks native DuckDB support.
+    """
+    # Dry runs resolve inputs and return previews before any sink write, so they
+    # never touch the DuckDB writer — run them on the lean build without the
+    # companion. Positional order mirrors the native `run`:
+    # (config_path, entities, dry_run, run_id, full_refresh, profile_vars, profile_path).
+    dry_run = kwargs.get("dry_run", args[1] if len(args) >= 2 else False)
+    # The sink format can be selected through a profile variable (e.g.
+    # `format: "{{SINK_FORMAT}}"`), so the delegation check must apply the same
+    # profile inputs as the run or it would miss the DuckDB sink and run lean.
+    profile_vars = kwargs.get("profile_vars", args[4] if len(args) >= 5 else None)
+    profile_path = kwargs.get("profile_path", args[5] if len(args) >= 6 else None)
+    if (
+        not dry_run
+        and not getattr(_lean, "HAS_DUCKDB", False)
+        and _lean.config_targets_duckdb(
+            config_path, profile_vars=profile_vars, profile_path=profile_path
+        )
+    ):
+        companion = _duckdb_module()
+        if companion is None:
+            raise FloeConfigError(_DUCKDB_INSTALL_HINT)
+        if _current_observer is not None:
+            companion.set_observer(_current_observer)
+        try:
+            outcome = companion.run(config_path, *args, **kwargs)
+        except companion.FloeError as exc:
+            raise _translate_companion_error(exc) from exc
+        # The companion is a separate native library, so its RunOutcome is a
+        # distinct Python class. Round-trip through the dict form so callers get
+        # the lean `RunOutcome` type they imported from `floe`.
+        return RunOutcome.from_dict(outcome.to_dict())
+    return _run(config_path, *args, **kwargs)
+
+
+# The companion's exception classes are distinct objects from the lean ones
+# (separate native libraries), so `except floe.FloeRunError` on a caller's side
+# would not catch a companion-raised error. Map each companion exception to the
+# matching lean class by name so delegated runs raise the types callers expect.
+_LEAN_EXCEPTIONS = {
+    "FloeConfigError": FloeConfigError,
+    "FloeRunError": FloeRunError,
+    "FloeStorageError": FloeStorageError,
+    "FloeIoError": FloeIoError,
+    "FloeError": FloeError,
+}
+
+
+def _translate_companion_error(exc):
+    lean_cls = _LEAN_EXCEPTIONS.get(type(exc).__name__, FloeError)
+    return lean_cls(str(exc))
+
+
+__all__ = [
+    "__version__",
+    "FloeError",
+    "FloeConfigError",
+    "FloeRunError",
+    "FloeStorageError",
+    "FloeIoError",
+    "RootConfig",
+    "EntityConfig",
+    "RunOutcome",
+    "validate",
+    "run",
+    "load_config",
+    "extract_config_env_vars",
+    "inspect_entity_state",
+    "reset_entity_state",
+    "set_observer",
+    "clear_observer",
+]

{floe_python-0.5.0 → floe_python-0.5.1}/python/floe/_floe.pyi

@@ -143,10 +143,22 @@ class RunOutcome:
     def _repr_html_(self) -> str: ...
     def __repr__(self) -> str: ...
 
+# ---------------------------------------------------------------------------
+# Capability flags
+# ---------------------------------------------------------------------------
+
+HAS_DUCKDB: bool
+"""True only in the `+duckdb` build (the off-PyPI `floe-duckdb` companion)."""
+
 # ---------------------------------------------------------------------------
 # Core functions
 # ---------------------------------------------------------------------------
 
+def config_targets_duckdb(config_path: str) -> bool:
+    """True when the config writes to a DuckDB sink. Returns False if the config
+    cannot be loaded, so the normal run path surfaces the real error."""
+    ...
+
 def validate(
     config_path: str,
     entities: list[str] | None = None,

floe_python-0.5.0/python/floe/__init__.py

@@ -1,76 +0,0 @@
-"""
-floe — Python bindings for the floe ingestion engine.
-
-Run floe pipelines at Rust speed from Python notebooks::
-
-    import floe
-
-    # Live progress
-    floe.set_observer(lambda e: print(f"[{e['event']}]", e.get("name", "")))
-
-    # Validate config
-    floe.validate("pipeline.yml")
-
-    # Execute pipeline
-    outcome = floe.run("pipeline.yml", entities=["customers"])
-    print(outcome.summary["results"])
-
-    # Dry run
-    outcome = floe.run("pipeline.yml", dry_run=True)
-    for p in outcome.dry_run_previews:
-        print(p["name"], p["scanned_files"])
-
-    # Inspect incremental state
-    state = floe.inspect_entity_state("pipeline.yml", "customers")
-    print(state["incremental_mode"], state["state"])
-
-    # Use a profile (with catalog / variable overrides)
-    floe.run("pipeline.yml", profile_path="profile.yml")
-    floe.run("pipeline.yml", profile_vars={"output_bucket": "s3://my-bucket"})
-"""
-
-from importlib.metadata import version as _pkg_version
-
-try:
-    __version__ = _pkg_version("floe-python")
-except Exception:
-    __version__ = "unknown"
-
-from floe._floe import (
-    FloeError,
-    FloeConfigError,
-    FloeRunError,
-    FloeStorageError,
-    FloeIoError,
-    RootConfig,
-    EntityConfig,
-    RunOutcome,
-    validate,
-    run,
-    load_config,
-    extract_config_env_vars,
-    inspect_entity_state,
-    reset_entity_state,
-    set_observer,
-    clear_observer,
-)
-
-__all__ = [
-    "__version__",
-    "FloeError",
-    "FloeConfigError",
-    "FloeRunError",
-    "FloeStorageError",
-    "FloeIoError",
-    "RootConfig",
-    "EntityConfig",
-    "RunOutcome",
-    "validate",
-    "run",
-    "load_config",
-    "extract_config_env_vars",
-    "inspect_entity_state",
-    "reset_entity_state",
-    "set_observer",
-    "clear_observer",
-]