florecon-host 0.1.0__tar.gz

florecon_host-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: florecon-host
+Version: 0.1.0
+Summary: The Python host for florecon: a generic wasmtime embedder that drives self-describing reconciliation plugins. Brings its own plugin wasm; imports as `florecon`. Nothing created, nothing lost.
+License: MIT
+Project-URL: Homepage, https://github.com/spoj/florecon
+Project-URL: Repository, https://github.com/spoj/florecon
+Project-URL: Issues, https://github.com/spoj/florecon/issues
+Keywords: reconciliation,finance,matching,wasm,min-cost-flow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: wasmtime>=20
+Requires-Dist: pyarrow>=14
+
+# florecon (Python host)
+
+A generic [wasmtime](https://github.com/bytecodealliance/wasmtime-py) host that
+drives self-describing **florecon** reconciliation plugins. The host knows
+nothing about any domain: it loads a plugin `.wasm`, reads its `describe()`, and
+ships the raw columns the plugin declares. The same code runs every florecon
+plugin.
+
+Money is integer minor units; nothing is created or lost.
+
+```python
+from florecon import Workspace
+
+ws = Workspace("interco_plugin.wasm")     # any florecon plugin wasm
+
+ws.upsert(
+    {"row_id": 1, "company": "A", "icp": "B", "objsub": "61500",
+     "indicative_usd_amt": 100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 0, "reference": "INV0001"},
+    {"row_id": 2, "company": "B", "icp": "A", "objsub": "61500",
+     "indicative_usd_amt": -100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 1, "reference": "INV0001"},
+)
+rep = ws.solve()              # the proposal: groups + per-row allocations
+ws.pin_clean(tol=0)           # sign off every clean net-zero match
+ws.solve()                    # warm re-solve; pinned groups kept verbatim
+```
+
+## Surface
+
+A group lives on a lifecycle axis — `proposed` (the solver's current opinion,
+recomputed each `solve`) or `pinned` (your decision, kept verbatim).
+
+```text
+ledger      upsert(*rows) · remove(*ids)
+machine     solve()
+lifecycle   pin(gid) · pin_clean(tol) · pin_singletons(ids) · unpin(gid)
+partition   merge(allocs, label, reason) · detach(gid, ids) · dissolve(gid)
+read        report()
+```
+
+Failures raise `PluginError` carrying a stable `code` (e.g. `"frozen_group"`,
+`"conservation_violated"`) plus the `id` / `group_id` it concerns.
+`strict_assignments` / `connected_components` project the allocation hypergraph
+into per-row assignments or settlement clusters.
+
+The plugin/host ABI is versioned: the host refuses a wasm whose `abi_version`
+differs from `florecon.ABI_VERSION`.

florecon_host-0.1.0/README.md

@@ -0,0 +1,48 @@
+# florecon (Python host)
+
+A generic [wasmtime](https://github.com/bytecodealliance/wasmtime-py) host that
+drives self-describing **florecon** reconciliation plugins. The host knows
+nothing about any domain: it loads a plugin `.wasm`, reads its `describe()`, and
+ships the raw columns the plugin declares. The same code runs every florecon
+plugin.
+
+Money is integer minor units; nothing is created or lost.
+
+```python
+from florecon import Workspace
+
+ws = Workspace("interco_plugin.wasm")     # any florecon plugin wasm
+
+ws.upsert(
+    {"row_id": 1, "company": "A", "icp": "B", "objsub": "61500",
+     "indicative_usd_amt": 100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 0, "reference": "INV0001"},
+    {"row_id": 2, "company": "B", "icp": "A", "objsub": "61500",
+     "indicative_usd_amt": -100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 1, "reference": "INV0001"},
+)
+rep = ws.solve()              # the proposal: groups + per-row allocations
+ws.pin_clean(tol=0)           # sign off every clean net-zero match
+ws.solve()                    # warm re-solve; pinned groups kept verbatim
+```
+
+## Surface
+
+A group lives on a lifecycle axis — `proposed` (the solver's current opinion,
+recomputed each `solve`) or `pinned` (your decision, kept verbatim).
+
+```text
+ledger      upsert(*rows) · remove(*ids)
+machine     solve()
+lifecycle   pin(gid) · pin_clean(tol) · pin_singletons(ids) · unpin(gid)
+partition   merge(allocs, label, reason) · detach(gid, ids) · dissolve(gid)
+read        report()
+```
+
+Failures raise `PluginError` carrying a stable `code` (e.g. `"frozen_group"`,
+`"conservation_violated"`) plus the `id` / `group_id` it concerns.
+`strict_assignments` / `connected_components` project the allocation hypergraph
+into per-row assignments or settlement clusters.
+
+The plugin/host ABI is versioned: the host refuses a wasm whose `abi_version`
+differs from `florecon.ABI_VERSION`.

florecon_host-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "florecon-host"
+version = "0.1.0"
+description = "The Python host for florecon: a generic wasmtime embedder that drives self-describing reconciliation plugins. Brings its own plugin wasm; imports as `florecon`. Nothing created, nothing lost."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["reconciliation", "finance", "matching", "wasm", "min-cost-flow"]
+dependencies = ["wasmtime>=20", "pyarrow>=14"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Rust",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.urls]
+Homepage = "https://github.com/spoj/florecon"
+Repository = "https://github.com/spoj/florecon"
+Issues = "https://github.com/spoj/florecon/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# The generic host ships no domain plugin: a `.wasm` is brought by the caller
+# (or a thin per-domain wheel). Exclude the local interco test fixture from
+# both wheel and sdist so the package stays a pure host.
+[tool.setuptools.exclude-package-data]
+"*" = ["_engine.wasm"]

florecon_host-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

florecon_host-0.1.0/src/florecon/__init__.py

@@ -0,0 +1,58 @@
+"""florecon — incremental financial reconciliation by min-cost flow.
+
+The host is a thin, generic wasmtime driver. A *plugin* ``.wasm`` owns the
+domain (preprocessing, identity, matching) and describes itself; the host ships
+the raw columns it asks for and drives the interactive workspace.
+
+    from florecon import Workspace
+    import polars as pl
+
+    ws = Workspace("interco_plugin.wasm")
+    ws.upsert(pl.DataFrame([
+        {"row_id": 1, "company": "A", "icp": "B", "objsub": "61500",
+         "indicative_usd_amt": 100.0, "trx_currency": "USD", "trx_amt": 100.0,
+         "gl_date": 0, "reference": "INV0001", ...},
+    ]))
+    print(ws.solve())
+"""
+
+from ._host import (
+    ABI_VERSION,
+    ContractMismatch,
+    Florecon,
+    PluginError,
+    SchemaError,
+    Workspace,
+)
+from .persist import (
+    decisions,
+    groups_csv,
+    load_workspace,
+    report_frames,
+    result_json,
+    results_csv,
+    save_workspace,
+)
+from .projections import connected_components, primary_assignments, strict_assignments
+from .tags import TagStore
+
+__all__ = [
+    "Florecon",
+    "Workspace",
+    "ABI_VERSION",
+    "ContractMismatch",
+    "PluginError",
+    "SchemaError",
+    "TagStore",
+    "strict_assignments",
+    "primary_assignments",
+    "connected_components",
+    "decisions",
+    "save_workspace",
+    "load_workspace",
+    "report_frames",
+    "groups_csv",
+    "results_csv",
+    "result_json",
+]
+__version__ = "0.1.0"

florecon_host-0.1.0/src/florecon/_host.py

@@ -0,0 +1,277 @@
+"""The wasmtime host for a florecon plugin.
+
+The host is generic and dumb: it loads a plugin ``.wasm``, asks it to
+``describe()`` itself (which raw columns it needs, which one is the headline
+amount), then ships a columnar table as Arrow IPC and drives the planless
+``Cmd`` protocol. State lives inside the module; only JSON + Arrow cross the
+boundary. The host knows *nothing* about any domain — the same code runs every
+florecon plugin.
+"""
+
+import json
+
+import pyarrow as pa
+import wasmtime
+
+# Must equal the SDK's florecon::sdk::ABI_VERSION export.
+ABI_VERSION = 1
+
+
+class ContractMismatch(RuntimeError):
+    """The plugin wasm speaks a different ABI than this host."""
+
+
+class SchemaError(RuntimeError):
+    """A dataframe handed to :meth:`Workspace.upsert` does not match the
+    plugin's declared input schema (a column is missing or uncastable)."""
+
+
+class PluginError(RuntimeError):
+    """A typed failure returned by the plugin's dispatch envelope.
+
+    Carries the stable ``code`` (e.g. ``"unknown_group"``, ``"frozen_group"``,
+    ``"conservation_violated"``) plus the row ``id`` / ``group_id`` it concerns
+    when the plugin knows them.
+    """
+
+    def __init__(self, code: str, message: str, id=None, group_id=None):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.id = id
+        self.group_id = group_id
+
+
+_PA_TYPE = {"i64": pa.int64(), "f64": pa.float64(), "utf8": pa.string()}
+
+
+class Florecon:
+    """Low-level handle around a plugin wasm: alloc/write/call/read over linear
+    memory, plus the ``describe`` and ``dispatch`` exports."""
+
+    def __init__(self, wasm_path):
+        engine = wasmtime.Engine()
+        self.store = wasmtime.Store(engine)
+        module = wasmtime.Module.from_file(engine, str(wasm_path))
+        self.inst = wasmtime.Instance(self.store, module, [])
+        ex = self.inst.exports(self.store)
+        self.memory = ex["memory"]
+        self._alloc = ex["alloc"]
+        self._dealloc = ex["dealloc"]
+        self._dispatch = ex["dispatch"]
+        self._describe = ex["describe"]
+        self.abi_version = ex["abi_version"](self.store)
+        if self.abi_version != ABI_VERSION:
+            raise ContractMismatch(f"plugin ABI v{self.abi_version} != host v{ABI_VERSION}")
+
+    def _read_packed(self, packed: int) -> bytes:
+        out_ptr = packed & 0xFFFFFFFF
+        out_len = (packed >> 32) & 0xFFFFFFFF
+        out = self.memory.read(self.store, out_ptr, out_ptr + out_len)
+        self._dealloc(self.store, out_ptr, out_len)
+        return bytes(out)
+
+    def describe(self) -> dict:
+        """The plugin's self-description: ``{abi_version, domain, input, ...}``."""
+        return json.loads(self._read_packed(self._describe(self.store)))
+
+    def dispatch(self, command: dict, arrow_bytes: bytes = None) -> dict:
+        """Drive the persistent session with one ``Cmd`` dict. ``init``/``upsert``
+        carry their rows in ``arrow_bytes``. Returns the raw envelope."""
+        data = json.dumps(command).encode("utf-8")
+        n = len(data)
+        ptr = self._alloc(self.store, n)
+        self.memory.write(self.store, data, ptr)
+
+        arrow_n = len(arrow_bytes) if arrow_bytes else 0
+        arrow_ptr = 0
+        if arrow_n > 0:
+            arrow_ptr = self._alloc(self.store, arrow_n)
+            self.memory.write(self.store, arrow_bytes, arrow_ptr)
+
+        packed = self._dispatch(self.store, ptr, n, arrow_ptr, arrow_n)
+
+        self._dealloc(self.store, ptr, n)
+        if arrow_n > 0:
+            self._dealloc(self.store, arrow_ptr, arrow_n)
+        return json.loads(self._read_packed(packed))
+
+
+def _ok(env: dict) -> dict:
+    """Unwrap a dispatch envelope to its report, or raise the typed error."""
+    if not env.get("ok"):
+        e = env.get("error") or {}
+        raise PluginError(
+            e.get("code", "unknown"),
+            e.get("message", "unknown plugin error"),
+            id=e.get("id"),
+            group_id=e.get("group_id"),
+        )
+    return env.get("report", {})
+
+
+def _ipc(batch: "pa.RecordBatch") -> bytes:
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, batch.schema) as writer:
+        writer.write_batch(batch)
+    return sink.getvalue().to_pybytes()
+
+
+class Workspace:
+    """An interactive reconciliation session over one plugin.
+
+    The plugin owns the domain (preprocessing, identity, matching). The host
+    just ships the raw columns the plugin's ``describe()`` declares — as a
+    **dataframe** (polars / pandas / pyarrow) whose columns are validated and
+    cast against that schema — and drives the lifecycle (``pin``/``unpin``) and
+    partition (``merge``/``detach``/``dissolve``) verbs. State lives in the wasm
+    module, so repeated :meth:`solve` calls warm re-solve.
+
+    ``config`` (a JSON-able dict) is handed to the plugin at ``init`` — runtime
+    tunables (tolerances, windows) the plugin reads, so tuning needs no rebuild.
+
+    A group lives on a lifecycle axis: ``proposed`` groups are the solver's
+    current opinion (recomputed each :meth:`solve`); ``pinned`` groups are your
+    decisions, kept verbatim across solves.
+    """
+
+    def __init__(self, wasm_path=None, _engine: Florecon = None, config: dict = None):
+        self.fe = _engine or Florecon(wasm_path)
+        self.spec = self.fe.describe()
+        self.fields = self.spec["input"]
+        self.domain = self.spec.get("domain", {})
+        #: Name of the column the plugin flags as the headline display amount.
+        self.amount_field = next(
+            (f["name"] for f in self.fields if f.get("amount")), None
+        )
+        self._schema = pa.schema(
+            [pa.field(f["name"], _PA_TYPE[f["type"]]) for f in self.fields]
+        )
+        init_cmd = {"op": "init"}
+        if config is not None:
+            init_cmd["config"] = config
+        self.last = self.fe.dispatch(init_cmd, _ipc(self._empty_batch()))
+        _ok(self.last)
+
+    # --- schema bridge -------------------------------------------------------
+
+    def _empty_batch(self) -> "pa.RecordBatch":
+        """A zero-row batch carrying the declared schema (used by ``init``)."""
+        arrays = [pa.array([], type=_PA_TYPE[f["type"]]) for f in self.fields]
+        return pa.RecordBatch.from_arrays(arrays, schema=self._schema)
+
+    @staticmethod
+    def _as_table(frame) -> "pa.Table":
+        """Normalize a polars / pandas / pyarrow frame to a pyarrow Table."""
+        if isinstance(frame, pa.Table):
+            return frame
+        if isinstance(frame, pa.RecordBatch):
+            return pa.Table.from_batches([frame])
+        mod = type(frame).__module__.split(".", 1)[0]
+        if mod == "polars" and hasattr(frame, "to_arrow"):
+            return frame.to_arrow()
+        if mod == "pandas":
+            return pa.Table.from_pandas(frame, preserve_index=False)
+        raise TypeError(
+            f"upsert expects a polars/pandas/pyarrow dataframe, got {type(frame).__name__}"
+        )
+
+    def _batch(self, frame) -> "pa.RecordBatch":
+        """Validate a frame against the declared schema and project it to the
+        declared columns (extra columns ignored), cast to the declared types."""
+        table = self._as_table(frame)
+        present = set(table.column_names)
+        missing = [f["name"] for f in self.fields if f["name"] not in present]
+        if missing:
+            raise SchemaError(
+                f"dataframe is missing columns declared by {self.domain.get('id')}: {missing}"
+            )
+        arrays = []
+        for f in self.fields:
+            arr = table.column(f["name"]).combine_chunks()
+            try:
+                arr = arr.cast(_PA_TYPE[f["type"]])
+            except (pa.ArrowInvalid, pa.ArrowTypeError, pa.ArrowNotImplementedError) as e:
+                raise SchemaError(
+                    f"column {f['name']!r}: cannot cast {arr.type} -> {f['type']}: {e}"
+                ) from e
+            arrays.append(arr)
+        return pa.RecordBatch.from_arrays(arrays, schema=self._schema)
+
+    # --- ledger --------------------------------------------------------------
+
+    def upsert(self, *frames) -> "Workspace":
+        """Insert/replace rows from one or more dataframes (polars / pandas /
+        pyarrow). Each frame must carry the plugin's declared raw columns;
+        extra columns are ignored, declared columns are cast to their wire type."""
+        for frame in frames:
+            batch = self._batch(frame)
+            if batch.num_rows:
+                self.last = self.fe.dispatch({"op": "upsert"}, _ipc(batch))
+                _ok(self.last)
+        return self
+
+    def remove(self, *ids: int) -> "Workspace":
+        self.last = self.fe.dispatch({"op": "remove", "ids": list(ids)})
+        _ok(self.last)
+        return self
+
+    # --- machine -------------------------------------------------------------
+
+    def solve(self) -> dict:
+        self.last = self.fe.dispatch({"op": "solve"})
+        return _ok(self.last)
+
+    # --- lifecycle -----------------------------------------------------------
+
+    def pin(self, group_id: int) -> dict:
+        """Pin one proposed group — keep it verbatim across later solves."""
+        self.last = self.fe.dispatch({"op": "pin", "by": "group", "group_id": group_id})
+        return _ok(self.last)
+
+    def pin_clean(self, tol: int = 0) -> dict:
+        """Pin every proposed match that nets to zero within ``tol``."""
+        self.last = self.fe.dispatch({"op": "pin", "by": "clean", "tol": int(tol)})
+        return _ok(self.last)
+
+    def pin_singletons(self, ids) -> dict:
+        """Pin the named lone lots (proposed singletons) as accepted-as-is."""
+        self.last = self.fe.dispatch({"op": "pin", "by": "singletons", "ids": list(ids)})
+        return _ok(self.last)
+
+    def unpin(self, group_id: int) -> dict:
+        """Release a pinned group back to the solver's control."""
+        self.last = self.fe.dispatch({"op": "unpin", "group_id": group_id})
+        return _ok(self.last)
+
+    # --- partition -----------------------------------------------------------
+
+    def merge(self, allocations, label: str = "manual", reason=None) -> dict:
+        """Assert a pinned group over exact allocations ``[{"id", "amount"}, ...]``."""
+        cmd = {
+            "op": "merge",
+            "allocations": [
+                {"id": int(a["id"]), "amount": int(a["amount"])} for a in allocations
+            ],
+            "label": label,
+        }
+        if reason is not None:
+            cmd["reason"] = str(reason)
+        self.last = self.fe.dispatch(cmd)
+        return _ok(self.last)
+
+    def detach(self, group_id: int, ids) -> dict:
+        """Pull rows out of a proposed group into lone singletons."""
+        self.last = self.fe.dispatch(
+            {"op": "detach", "group_id": group_id, "ids": list(ids)}
+        )
+        return _ok(self.last)
+
+    def dissolve(self, group_id: int) -> dict:
+        """Break a proposed group back into singletons."""
+        self.last = self.fe.dispatch({"op": "dissolve", "group_id": group_id})
+        return _ok(self.last)
+
+    # --- read ----------------------------------------------------------------
+
+    def report(self) -> dict:
+        return _ok(self.fe.dispatch({"op": "report"}))

florecon_host-0.1.0/src/florecon/persist.py

@@ -0,0 +1,177 @@
+"""Workspace persistence and result export.
+
+One module that knows how to (a) serialize/restore the *operator's* durable
+decisions to a portable file, and (b) export a reconciliation result as
+dataframes / CSV / JSON.
+
+Design note — what is durable state?
+    Everything *proposed* is a deterministic function of (rows, plugin) via
+    :meth:`Workspace.solve`, so it never needs saving. The only durable operator
+    state is:
+      * the **pinned** groups (committed decisions), expressed allocation-native
+        in stable row-id terms (group ids are ephemeral across solves), and
+      * the **tag** overlay (review buckets), already keyed by stable row id.
+    So a saved workspace = pinned decisions + tags (+ optional metadata). On load
+    we re-solve to recover the proposals, then re-assert the pinned decisions on
+    top. Robust and small — it survives plugin tweaks that only move proposals.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .projections import primary_assignments
+
+WORKSPACE_KIND = "florecon.workspace"
+WORKSPACE_VERSION = 1
+
+
+# --- durable-decision extraction -------------------------------------------
+
+def decisions(report: dict) -> list[dict]:
+    """Collapse a report into the allocation-native *pinned* decisions, keyed by
+    row id. Each is ``{reason, allocations: [{id, amount}, ...]}``."""
+    by_g: dict[int, dict] = {}
+    for g in report.get("groups", []):
+        if g.get("status") == "pinned":
+            by_g[int(g["group_id"])] = {
+                "reason": g.get("reason"),
+                "origin": g.get("origin", "manual"),
+                "allocations": [],
+            }
+    for a in report.get("allocations", []):
+        d = by_g.get(int(a["group_id"]))
+        if d is not None:
+            d["allocations"].append({"id": int(a["id"]), "amount": int(a["amount"])})
+    return [d for d in by_g.values() if d["allocations"]]
+
+
+def apply_decisions(ws, saved: list[dict]) -> dict:
+    """Re-assert saved pinned decisions onto a freshly solved workspace.
+
+    Multi-leg groups go through :meth:`Workspace.merge` (exact amounts, so splits
+    survive); lone accepted rows go through :meth:`Workspace.pin_singletons`.
+    Merges are applied first so they pull their rows out of any proposed group,
+    leaving accepted singletons free to pin. Returns a short apply summary.
+    """
+    multi = [d for d in saved if len([a for a in d["allocations"] if a["amount"]]) >= 2]
+    singles: list[int] = []
+    for d in saved:
+        nz = [a for a in d["allocations"] if a["amount"]]
+        if len(nz) < 2:
+            singles.extend(a["id"] for a in d["allocations"])
+
+    groups = failed = 0
+    errors = []
+    for d in multi:
+        allocs = [a for a in d["allocations"] if a["amount"]]
+        try:
+            ws.merge(allocs, label=d.get("origin", "manual"), reason=d.get("reason"))
+            groups += 1
+        except Exception as e:  # noqa: BLE001 - collected, not swallowed
+            failed += 1
+            errors.append(str(e))
+    pinned_singles = 0
+    if singles:
+        try:
+            ws.pin_singletons(singles)
+            pinned_singles = len(singles)
+        except Exception as e:  # noqa: BLE001
+            failed += 1
+            errors.append(str(e))
+    return {"groups": groups, "singles": pinned_singles, "failed": failed, "errors": errors}
+
+
+# --- serialize / restore ----------------------------------------------------
+
+def serialize(report: dict, *, tags=None, meta: dict | None = None) -> dict:
+    """A portable workspace: pinned decisions + the tag overlay + metadata. The
+    raw rows are *not* embedded (re-supply them with ``upsert`` before load)."""
+    return {
+        "kind": WORKSPACE_KIND,
+        "version": WORKSPACE_VERSION,
+        "domain": (meta or {}).get("domain"),
+        "decisions": decisions(report),
+        "tags": tags.dump() if tags is not None else {"tags": {}, "meta": {}},
+        "meta": meta or {},
+    }
+
+
+def parse(obj_or_text) -> dict:
+    o = json.loads(obj_or_text) if isinstance(obj_or_text, (str, bytes)) else obj_or_text
+    if not isinstance(o, dict) or o.get("kind") != WORKSPACE_KIND:
+        raise ValueError("not a florecon workspace")
+    if o.get("version") != WORKSPACE_VERSION:
+        raise ValueError(f"workspace version {o.get('version')} != supported {WORKSPACE_VERSION}")
+    return o
+
+
+def save_workspace(path, report: dict, *, tags=None, meta: dict | None = None) -> dict:
+    """Write a workspace JSON file; returns the serialized object."""
+    obj = serialize(report, tags=tags, meta=meta)
+    Path(path).write_text(json.dumps(obj, indent=2))
+    return obj
+
+
+def load_workspace(path_or_obj, ws, *, tags=None) -> dict:
+    """Restore decisions (and optionally tags) onto a workspace that has already
+    been re-``upsert``ed and ``solve``d. Returns the apply summary."""
+    obj = parse(Path(path_or_obj).read_text() if isinstance(path_or_obj, (str, Path)) and Path(path_or_obj).exists() else path_or_obj)
+    if tags is not None:
+        tags.restore(obj.get("tags"))
+    return apply_decisions(ws, obj.get("decisions", []))
+
+
+# --- result export ----------------------------------------------------------
+
+def report_frames(report: dict):
+    """The report as two pyarrow Tables ``(groups, allocations)`` — the natural
+    bridge for writing results back to Spark/Delta in a notebook."""
+    import pyarrow as pa
+
+    groups = pa.Table.from_pylist(report.get("groups", []))
+    allocations = pa.Table.from_pylist(report.get("allocations", []))
+    return groups, allocations
+
+
+def _csv(rows: list[list]) -> str:
+    def cell(v):
+        s = "" if v is None else str(v)
+        return '"' + s.replace('"', '""') + '"' if any(c in s for c in ',"\n') else s
+    return "\n".join(",".join(cell(c) for c in r) for r in rows)
+
+
+def groups_csv(report: dict, *, money_scale: float = 0.01) -> str:
+    """One line per group. ``money_scale`` converts the numeraire minor units to
+    display (default cents -> currency units)."""
+    head = ["group_id", "origin", "reason", "status", "size", "net"]
+    rows = [head]
+    for g in report.get("groups", []):
+        rows.append([
+            g["group_id"], g.get("origin", ""), g.get("reason", "") or "",
+            g.get("status", ""), g.get("size", ""),
+            f"{int(g.get('net', 0)) * money_scale:.2f}",
+        ])
+    return _csv(rows)
+
+
+def results_csv(report: dict, *, policy: str = "largest_abs", money_scale: float = 0.01) -> str:
+    """Row-level result: every row with the group it primarily landed in."""
+    gmeta = {int(g["group_id"]): g for g in report.get("groups", [])}
+    head = ["row_id", "group_id", "origin", "reason", "status", "group_net"]
+    rows = [head]
+    for rid, gid in primary_assignments(report, policy=policy):
+        g = gmeta.get(int(gid), {})
+        rows.append([
+            rid, gid, g.get("origin", ""), g.get("reason", "") or "",
+            g.get("status", ""), f"{int(g.get('net', 0)) * money_scale:.2f}",
+        ])
+    return _csv(rows)
+
+
+def result_json(report: dict, *, meta: dict | None = None) -> str:
+    """The whole allocation-native result plus a little context."""
+    return json.dumps(
+        {"kind": "florecon.result", "meta": meta or {}, "report": report}, indent=2
+    )

florecon_host-0.1.0/src/florecon/projections.py

@@ -0,0 +1,86 @@
+"""Explicit projections from the allocation-native Report hypergraph."""
+
+
+def strict_assignments(report: dict) -> list[tuple[int, int]]:
+    """Return one (row id, group id) per row only if the report is not split.
+
+    Raises ValueError if a row id participates in multiple groups.
+    """
+    by_id = {}
+    for a in report.get("allocations", []):
+        by_id.setdefault(int(a["id"]), set()).add(int(a["group_id"]))
+    out = []
+    for id_, groups in sorted(by_id.items()):
+        if len(groups) != 1:
+            raise ValueError(f"row {id_} is split across groups {sorted(groups)}")
+        out.append((id_, next(iter(groups))))
+    return out
+
+
+def primary_assignments(report: dict, policy: str = "largest_abs") -> list[tuple[int, int]]:
+    """Return one (row id, group id) per row, choosing a primary group when a
+    row is split across several (lot strategies). ``policy`` is one of
+    ``largest_abs`` (default), ``prefer_clean``, or ``first_group``.
+
+    Unlike :func:`strict_assignments` this never raises — use it for row-level
+    exports where every row needs exactly one home.
+    """
+    by_id: dict[int, list[dict]] = {}
+    for a in report.get("allocations", []):
+        by_id.setdefault(int(a["id"]), []).append(a)
+    groups = {int(g["group_id"]): g for g in report.get("groups", [])}
+
+    def score(a: dict):
+        g = groups.get(int(a["group_id"]), {})
+        clean = 1 if abs(int(g.get("net", 0))) == 0 else 0
+        if policy == "first_group":
+            return (-int(a["group_id"]),)
+        if policy == "prefer_clean":
+            return (clean, abs(int(a["amount"])), -int(a["group_id"]))
+        return (abs(int(a["amount"])), clean, -int(a["group_id"]))
+
+    out = []
+    for id_, allocs in sorted(by_id.items()):
+        best = max(allocs, key=score)
+        out.append((id_, int(best["group_id"])))
+    return out
+
+
+def connected_components(report: dict) -> list[dict]:
+    """Connected components of the bipartite graph row id <-> group id."""
+    row_to_groups = {}
+    group_to_rows = {}
+    for a in report.get("allocations", []):
+        r = int(a["id"])
+        g = int(a["group_id"])
+        row_to_groups.setdefault(r, []).append(g)
+        group_to_rows.setdefault(g, []).append(r)
+
+    seen_rows = set()
+    seen_groups = set()
+    out = []
+    for start in list(row_to_groups):
+        if start in seen_rows:
+            continue
+        rows = set()
+        groups = set()
+        row_stack = [start]
+        group_stack = []
+        while row_stack or group_stack:
+            while row_stack:
+                r = row_stack.pop()
+                if r in seen_rows:
+                    continue
+                seen_rows.add(r)
+                rows.add(r)
+                group_stack.extend(row_to_groups.get(r, []))
+            while group_stack:
+                g = group_stack.pop()
+                if g in seen_groups:
+                    continue
+                seen_groups.add(g)
+                groups.add(g)
+                row_stack.extend(group_to_rows.get(g, []))
+        out.append({"rows": sorted(rows), "groups": sorted(groups)})
+    out.sort(key=lambda c: (c["rows"][0] if c["rows"] else 0, c["groups"][0] if c["groups"] else 0))
+    return out

florecon_host-0.1.0/src/florecon/tags.py

@@ -0,0 +1,99 @@
+"""Host-side review/attention overlay.
+
+A *tag* is a many-to-many review axis (e.g. "needs-review", "escalate",
+"FX-difference") that an operator drapes over rows. It is **orthogonal** to the
+engine's lifecycle axis (``proposed`` | ``pinned``): the conservation engine
+never learns the word "review". Tags are owned entirely by the host and keyed by
+the **stable row id** (``ExtId``), never by group id — proposed group ids are
+re-minted every solve, so keying by row id makes tags survive a re-solve for
+free.
+
+This mirrors the same orthogonality the engine enforces for groups, one layer
+out: status is the machine's business, review is the operator's, and the two
+never contaminate each other.
+"""
+
+# A small, stable chip palette; tags get a colour by creation order.
+_PALETTE = [
+    "#217346", "#6d3fd1", "#b7791f", "#0f8d80",
+    "#c2410c", "#2563eb", "#be185d", "#4d7c0f",
+]
+
+
+class TagStore:
+    """An in-memory overlay of ``row_id -> {tag_id}`` plus tag metadata.
+
+    Nothing is persisted implicitly; serialize with :meth:`dump` (and embed it in
+    a saved workspace) for durability. A row may carry several tags or none.
+    """
+
+    def __init__(self):
+        self.tags: dict[int, set[str]] = {}
+        self.meta: dict[str, dict] = {}
+
+    def ensure_tag(self, label: str, kind: str = "bucket") -> str | None:
+        """Create (or look up) a tag by human label. Idempotent on the slugged
+        id, so reusing a bucket name reuses the same tag and colour."""
+        name = (label or "").strip()
+        if not name:
+            return None
+        tid = "tag:" + name.lower()
+        if tid not in self.meta:
+            self.meta[tid] = {
+                "label": name,
+                "color": _PALETTE[len(self.meta) % len(_PALETTE)],
+                "kind": kind,
+            }
+        return tid
+
+    def tags_of(self, row_id: int) -> set[str]:
+        return self.tags.get(int(row_id), set())
+
+    def label(self, tid: str) -> str:
+        return self.meta.get(tid, {}).get("label", tid)
+
+    def color(self, tid: str) -> str:
+        return self.meta.get(tid, {}).get("color", "#6b7280")
+
+    def add(self, row_id: int, tid: str) -> None:
+        self.tags.setdefault(int(row_id), set()).add(tid)
+
+    def remove(self, row_id: int, tid: str) -> None:
+        s = self.tags.get(int(row_id))
+        if not s:
+            return
+        s.discard(tid)
+        if not s:
+            del self.tags[int(row_id)]
+
+    def clear(self, row_id: int) -> None:
+        """Drop every tag on a row."""
+        self.tags.pop(int(row_id), None)
+
+    def tagged(self, tid: str) -> list[int]:
+        """Every row id currently carrying ``tid`` (sorted)."""
+        return sorted(r for r, s in self.tags.items() if tid in s)
+
+    def dump(self) -> dict:
+        """Serialize the whole overlay to a plain JSON-able object."""
+        return {
+            "tags": {str(r): sorted(s) for r, s in self.tags.items() if s},
+            "meta": dict(self.meta),
+        }
+
+    def restore(self, obj: dict | None) -> "TagStore":
+        """Replace the overlay from a :meth:`dump`. Row id keys are coerced back
+        to ints. Returns self."""
+        self.tags = {}
+        self.meta = {}
+        if not obj:
+            return self
+        for tid, m in (obj.get("meta") or {}).items():
+            self.meta[tid] = m
+        for r, arr in (obj.get("tags") or {}).items():
+            try:
+                key = int(r)
+            except (TypeError, ValueError):
+                key = r
+            self.tags[key] = set(arr)
+        return self

florecon_host-0.1.0/src/florecon_host.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: florecon-host
+Version: 0.1.0
+Summary: The Python host for florecon: a generic wasmtime embedder that drives self-describing reconciliation plugins. Brings its own plugin wasm; imports as `florecon`. Nothing created, nothing lost.
+License: MIT
+Project-URL: Homepage, https://github.com/spoj/florecon
+Project-URL: Repository, https://github.com/spoj/florecon
+Project-URL: Issues, https://github.com/spoj/florecon/issues
+Keywords: reconciliation,finance,matching,wasm,min-cost-flow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: wasmtime>=20
+Requires-Dist: pyarrow>=14
+
+# florecon (Python host)
+
+A generic [wasmtime](https://github.com/bytecodealliance/wasmtime-py) host that
+drives self-describing **florecon** reconciliation plugins. The host knows
+nothing about any domain: it loads a plugin `.wasm`, reads its `describe()`, and
+ships the raw columns the plugin declares. The same code runs every florecon
+plugin.
+
+Money is integer minor units; nothing is created or lost.
+
+```python
+from florecon import Workspace
+
+ws = Workspace("interco_plugin.wasm")     # any florecon plugin wasm
+
+ws.upsert(
+    {"row_id": 1, "company": "A", "icp": "B", "objsub": "61500",
+     "indicative_usd_amt": 100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 0, "reference": "INV0001"},
+    {"row_id": 2, "company": "B", "icp": "A", "objsub": "61500",
+     "indicative_usd_amt": -100.0, "trx_currency": "USD", "trx_amt": 100.0,
+     "gl_date": 1, "reference": "INV0001"},
+)
+rep = ws.solve()              # the proposal: groups + per-row allocations
+ws.pin_clean(tol=0)           # sign off every clean net-zero match
+ws.solve()                    # warm re-solve; pinned groups kept verbatim
+```
+
+## Surface
+
+A group lives on a lifecycle axis — `proposed` (the solver's current opinion,
+recomputed each `solve`) or `pinned` (your decision, kept verbatim).
+
+```text
+ledger      upsert(*rows) · remove(*ids)
+machine     solve()
+lifecycle   pin(gid) · pin_clean(tol) · pin_singletons(ids) · unpin(gid)
+partition   merge(allocs, label, reason) · detach(gid, ids) · dissolve(gid)
+read        report()
+```
+
+Failures raise `PluginError` carrying a stable `code` (e.g. `"frozen_group"`,
+`"conservation_violated"`) plus the `id` / `group_id` it concerns.
+`strict_assignments` / `connected_components` project the allocation hypergraph
+into per-row assignments or settlement clusters.
+
+The plugin/host ABI is versioned: the host refuses a wasm whose `abi_version`
+differs from `florecon.ABI_VERSION`.

florecon_host-0.1.0/src/florecon_host.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/florecon/__init__.py
+src/florecon/_host.py
+src/florecon/persist.py
+src/florecon/projections.py
+src/florecon/tags.py
+src/florecon_host.egg-info/PKG-INFO
+src/florecon_host.egg-info/SOURCES.txt
+src/florecon_host.egg-info/dependency_links.txt
+src/florecon_host.egg-info/requires.txt
+src/florecon_host.egg-info/top_level.txt

florecon_host-0.1.0/src/florecon_host.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

florecon_host-0.1.0/src/florecon_host.egg-info/requires.txt

@@ -0,0 +1,2 @@
+wasmtime>=20
+pyarrow>=14

florecon_host-0.1.0/src/florecon_host.egg-info/top_level.txt

@@ -0,0 +1 @@
+florecon