flatland-client 0.1.0__py3-none-any.whl

flatland_client/__init__.py

@@ -0,0 +1,49 @@
+"""flatland-client — the durable, dependency-free Python client for hosted Flatland.
+
+Option C: your model is a file YOU own (``~/.flatland/models/<name>.flatland.json``),
+versioned in your own git, diffable, re-runnable anywhere. The hosted server is a
+pure function (``/api/v2/*``): the client ships the IR in, the server
+computes/transforms and returns, and retains NOTHING at rest.
+
+This is the SAME durability mechanism as the in-engine reference
+``flatland.client`` (kept byte-for-byte in semantics), repackaged as a thin,
+stdlib-only install so a Python user gets the durable metered path WITHOUT
+pulling in the full engine (fastapi/uvicorn/stripe/...). It talks to the public
+hosted ``/api/v2`` surface over HTTPS with the user's ``X-API-Key``; auth +
+metering + the server-derived tenant key all apply.
+
+Quickstart::
+
+    from flatland_client import create, load, http_transport
+    t = http_transport(api_key="fl_live_...")
+    h = create("acme_plan", t)              # writes ~/.flatland/models/acme_plan.flatland.json
+    h.bulk_add([{"name": "revenue", "type": "Currency", "value": 1000}])
+    print(h.compile()["values"])            # metered compute, nothing stored server-side
+    # --- new session / new machine that has the file ---
+    h = load("acme_plan", t)                # durable across restart
+"""
+
+from .client import (
+    DEFAULT_CLIENT_STORE_DIR,
+    PORTABLE_IR_VERSION,
+    FlatlandModelFile,
+    FlatlandMutationError,
+    Transport,
+    create,
+    http_transport,
+    load,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Transport",
+    "http_transport",
+    "FlatlandModelFile",
+    "FlatlandMutationError",
+    "create",
+    "load",
+    "DEFAULT_CLIENT_STORE_DIR",
+    "PORTABLE_IR_VERSION",
+    "__version__",
+]

flatland_client/client.py

@@ -0,0 +1,347 @@
+"""Flatland thin client — the CLIENT-SIDE half of Option C (durability mechanism).
+
+This is the load-bearing durability contract: **the customer's model is a file
+THE CLIENT owns and persists locally, and it survives across sessions and process
+restarts because it lives on the client's disk — never the server's.** The hosted
+server is a pure function (``/api/v2/*``): the client ships the IR in, the server
+computes/transforms and returns, and retains nothing.
+
+This is the dependency-free, pip-packaged twin of the in-engine reference
+``flatland.client``. The semantics are identical; the only thing dropped is the
+engine-coupled ``in_process_transport`` (a test/dev convenience that needs the
+full engine) — a thin client install has nothing to call it against. Use
+``http_transport`` against the hosted ``/api/v2`` surface.
+
+Where the file lives (the durability mechanism, spelled out):
+  * Default: ``~/.flatland/models/<name>.flatland.json`` ON THE CLIENT'S machine.
+  * Override: any path the caller chooses (a project dir, a git working tree).
+  The file is a plain JSON envelope (``PORTABLE_IR_VERSION`` + the IR). It is
+  exactly what a customer commits to their own git — versioned, diffable,
+  re-runnable anywhere. The server is never the system of record.
+
+How it survives a restart: a mutation call (``add_driver`` / ``bulk_add`` / ...)
+returns the NEW IR; the client writes it to the local file IMMEDIATELY (atomic
+tmp+replace). A fresh process (new session, after a reboot, on another laptop
+that has the file) calls :meth:`load` and continues exactly where it left off.
+
+F2 (data-safety): a failed or 5xx mutation MUST raise and leave the local file
+UNTOUCHED — never a silent stale-file "success".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Protocol
+
+#: Wire-format version for the portable IR envelope. Kept in lockstep with the
+#: server's ``portable.PORTABLE_IR_VERSION``. A client file tagged with an older
+#: version must keep loading — the client-durability contract.
+PORTABLE_IR_VERSION = 1
+
+DEFAULT_CLIENT_STORE_DIR = Path.home() / ".flatland" / "models"
+_FILE_SUFFIX = ".flatland.json"
+
+
+class FlatlandMutationError(RuntimeError):
+    """A mutation call did not produce an updated model IR (F2).
+
+    Raised when the server rejected the mutation (an error response) or returned
+    no new IR. The client is the system-of-record, so a failed mutation must be
+    loud — the local file is left untouched and the caller cannot mistake the
+    failure for success. ``response`` carries the structured error body (if any)
+    for inspection."""
+
+    def __init__(self, message: str, *, response: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.response = response
+
+
+class Transport(Protocol):
+    """A function that POSTs a JSON body to a ``/api/v2/*`` path and returns the
+    decoded JSON response. The concrete HTTP implementation lives in
+    :func:`http_transport`."""
+
+    def __call__(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """POST ``body`` to ``path`` and return the decoded JSON response."""
+
+
+def http_transport(
+    api_key: str,
+    base_url: str = "https://api.flatlandfi.com",
+    timeout: float = 60.0,
+) -> Transport:
+    """Build an HTTPS transport for the hosted per-call surface.
+
+    Uses urllib (stdlib) so the client carries no third-party dependency. The
+    API key goes in the server-validated ``X-API-Key`` header — the tenant key
+    is derived server-side (sha256), never sent by the client.
+
+    ``timeout`` (seconds) bounds every request: without it a stalled connection
+    or a server that stops sending mid-response would block create/mutations/
+    compute FOREVER, and the caller would never receive the fail-loud error the
+    durable contract promises (Greptile #78). On timeout urllib raises (a
+    ``URLError`` wrapping ``socket.timeout``), which propagates exactly like a
+    5xx/network failure — the local file is left untouched."""
+    import urllib.error
+    import urllib.request
+
+    def _post(path: str, body: dict[str, Any]) -> dict[str, Any]:
+        url = base_url.rstrip("/") + path
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json", "X-API-Key": api_key},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 — https hosted API
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            # EXPECTED 4xx (400 bad IR, 402 billing-gate, 413 too-large) carry a
+            # STRUCTURED JSON body — decode it and tag the status so the caller
+            # can branch (e.g. 402 = quota). A rejected mutation must be
+            # distinguishable from a network failure.
+            #
+            # A 5xx is DIFFERENT and MUST RAISE (F2). The client is the
+            # system-of-record: a 5xx means the server failed to process the
+            # mutation, so there is NO trustworthy new IR. Returning a decoded
+            # 5xx body would let ``_apply`` treat a failed mutation as success
+            # (no ``ir`` key → keeps the stale local file) — silent data loss.
+            if exc.code >= 500:
+                raise
+            raw = exc.read()
+            try:
+                payload = json.loads(raw.decode("utf-8"))
+            except (ValueError, UnicodeDecodeError):
+                raise
+            if isinstance(payload, dict):
+                payload.setdefault("http_status", exc.code)
+                return payload
+            raise
+
+    return _post
+
+
+def _check_envelope_version(envelope: dict[str, Any], where: str) -> None:
+    """Reject an envelope this client is too old to handle, BEFORE persisting it.
+
+    Mixed-version safety: if the server returns a newer envelope than this client
+    supports, persisting it would write a file the same client cannot ``load()``
+    next session. Fail at receipt instead, with a clear upgrade message."""
+    version = envelope.get("flatland_ir_version", PORTABLE_IR_VERSION)
+    if not isinstance(version, int) or version > PORTABLE_IR_VERSION:
+        raise ValueError(
+            f"{where}: server returned flatland_ir_version {version}; this "
+            f"client supports up to {PORTABLE_IR_VERSION}. Upgrade flatland-client "
+            f"before persisting this model file."
+        )
+
+
+class FlatlandModelFile:
+    """A client-owned model file + the pure-function calls that operate on it.
+
+    Hold one of these per model. Compute calls ship the local IR and return
+    results without changing the file. Mutation calls ship the local IR, receive
+    the new IR, and PERSIST it locally so the change survives the next restart.
+    """
+
+    def __init__(self, path: Path | str, transport: Transport, ir: dict[str, Any]):
+        self.path = Path(path)
+        self._transport = transport
+        self._ir = ir  # the portable envelope {flatland_ir_version, ir:{...}}
+
+    @property
+    def ir(self) -> dict[str, Any]:
+        """The current in-memory IR envelope (mirror of the on-disk file)."""
+        return self._ir
+
+    def save(self) -> Path:
+        """Atomically write the current IR to the local file (tmp + replace), so
+        a restart loses nothing. Returns the file path."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(self.path.suffix + f".tmp.{os.getpid()}")
+        tmp.write_text(json.dumps(self._ir, indent=2))
+        # 0600: the model is the user's sensitive IP.
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            # Best-effort: some filesystems (e.g. Windows/FAT) don't support
+            # POSIX modes. Persistence must still proceed for durability, so we
+            # swallow the chmod failure rather than abort the save.
+            pass
+        os.replace(tmp, self.path)
+        return self.path
+
+    def _apply(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Adopt + persist a successful mutation's new IR locally; raise on a
+        failed mutation so it is never silently mistaken for success (F2)."""
+        if isinstance(response, dict) and isinstance(response.get("ir"), dict):
+            _check_envelope_version(response["ir"], "mutation")
+            self._ir = response["ir"]
+            self.save()
+            return {k: v for k, v in response.items() if k != "ir"}
+        if isinstance(response, dict) and response.get("error"):
+            raise FlatlandMutationError(
+                response.get("message") or str(response.get("error")),
+                response=response,
+            )
+        raise FlatlandMutationError(
+            "Mutation returned no updated model IR; the local file was not "
+            "changed.",
+            response=response if isinstance(response, dict) else None,
+        )
+
+    # -- compute (pure; file unchanged) -------------------------------------
+
+    def compile(self, scenario: str = "base") -> dict[str, Any]:
+        return self._transport("/api/v2/compile", {"ir": self._ir, "scenario": scenario})
+
+    def sensitivity(self, target: str, perturbation: float = 0.10, scenario: str = "base") -> dict[str, Any]:
+        return self._transport("/api/v2/sensitivity", {
+            "ir": self._ir, "target": target, "perturbation": perturbation, "scenario": scenario,
+        })
+
+    def diff(self, from_scenario: str, to_scenario: str, target: str | None = None) -> dict[str, Any]:
+        return self._transport("/api/v2/diff", {
+            "ir": self._ir, "from_scenario": from_scenario, "to_scenario": to_scenario, "target": target,
+        })
+
+    def explain(self, driver: str, max_depth: int = 5) -> dict[str, Any]:
+        return self._transport("/api/v2/explain", {
+            "ir": self._ir, "driver": driver, "max_depth": max_depth,
+        })
+
+    def impact_preview(self, proposed_changes: list[dict[str, Any]], target_drivers: list[str] | None = None) -> dict[str, Any]:
+        return self._transport("/api/v2/impact_preview", {
+            "ir": self._ir, "proposed_changes": proposed_changes, "target_drivers": target_drivers,
+        })
+
+    # -- mutations (ship IR, receive new IR, persist locally) ---------------
+
+    def bulk_add(self, drivers: list[dict[str, Any]]) -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/bulk_add", {"ir": self._ir, "drivers": drivers}))
+
+    def add_driver(self, **kwargs: Any) -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/add_driver", {"ir": self._ir, **kwargs}))
+
+    def add_computed(self, **kwargs: Any) -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/add_computed", {"ir": self._ir, **kwargs}))
+
+    def update_driver(self, **kwargs: Any) -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/update_driver", {"ir": self._ir, **kwargs}))
+
+    def remove_driver(self, name: str, cascade: bool = False) -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/remove_driver", {
+            "ir": self._ir, "name": name, "cascade": cascade,
+        }))
+
+    def create_scenario(self, name: str, overrides: dict[str, Any], description: str = "") -> dict[str, Any]:
+        return self._apply(self._transport("/api/v2/create_scenario", {
+            "ir": self._ir, "name": name, "overrides": overrides, "description": description,
+        }))
+
+
+def _assert_safe_name(name: str) -> str:
+    """Validate a bare model name as a safe single path segment (path-traversal
+    defense — the name is untrusted). A dotted name ("acme.v2") is fine; a
+    separator, ``..``, leading dot, or NUL is not."""
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("Model name must be a non-empty string.")
+    n = name.strip()
+    if n in (".", ".."):
+        raise ValueError(f"Model name {n!r} is not allowed.")
+    if "/" in n or "\\" in n or "\0" in n:
+        raise ValueError(f"Model name {n!r} may not contain path separators.")
+    # Reject a name already ending in the reserved suffix: create() would save
+    # ``report.flatland.json`` as ``report.flatland.json.flatland.json`` while
+    # load() (which treats a suffixed arg as a path) would resolve a different
+    # file — the durable model would appear missing (Greptile #78).
+    if n.endswith(_FILE_SUFFIX):
+        raise ValueError(
+            f"Model name {n!r} may not end with the reserved {_FILE_SUFFIX!r} "
+            f"suffix; pass a bare name (the suffix is added for you)."
+        )
+    if n.startswith("."):
+        raise ValueError(f"Model name {n!r} may not start with a dot.")
+    return n
+
+
+def _path_for(name: str, store_dir: Path | str | None) -> Path:
+    base = Path(store_dir) if store_dir is not None else DEFAULT_CLIENT_STORE_DIR
+    return base / f"{_assert_safe_name(name)}{_FILE_SUFFIX}"
+
+
+def create(
+    name: str,
+    transport: Transport,
+    *,
+    store_dir: Path | str | None = None,
+    currency: str = "USD",
+    period_start: str = "2026-01",
+    period_end: str = "2026-12",
+    grain: str = "monthly",
+    description: str = "",
+    path: Path | str | None = None,
+) -> FlatlandModelFile:
+    """Create a new model on the server (pure call), persist its IR to a LOCAL
+    file the client owns, and return a handle. The file is the system of record
+    from here on; the server holds nothing."""
+    resp = transport("/api/v2/model/create", {
+        "name": name, "currency": currency, "period_start": period_start,
+        "period_end": period_end, "grain": grain, "description": description,
+    })
+    ir = resp.get("ir")
+    if not isinstance(ir, dict):
+        raise FlatlandMutationError(f"create did not return an IR envelope: {resp}", response=resp if isinstance(resp, dict) else None)
+    _check_envelope_version(ir, "create")
+    file_path = Path(path) if path is not None else _path_for(name, store_dir)
+    handle = FlatlandModelFile(file_path, transport, ir)
+    handle.save()
+    return handle
+
+
+def load(
+    name_or_path: str | Path,
+    transport: Transport,
+    *,
+    store_dir: Path | str | None = None,
+) -> FlatlandModelFile:
+    """Load a model from the LOCAL file the client owns (durability across
+    sessions / restarts). Accepts a model name (resolved under ``store_dir``) or
+    a direct path. Raises ``FileNotFoundError`` if the client has no such file —
+    there is NO server fallback by design (the server never held it)."""
+    p = Path(name_or_path)
+    # Decide name-vs-path WITHOUT keying on ``.suffix`` (a valid model NAME may
+    # contain a dot). Treat the argument as a path only if it is unambiguously
+    # one: absolute, has a directory component, or carries the model-file suffix.
+    looks_like_path = (
+        p.is_absolute()
+        or p.parent != Path(".")
+        or str(name_or_path).endswith(_FILE_SUFFIX)
+    )
+    if not looks_like_path:
+        p = _path_for(str(name_or_path), store_dir)
+    if not p.exists():
+        raise FileNotFoundError(
+            f"No local model file at {p}. The client owns the model — there is "
+            f"no server copy to fall back to (Option C). Create it with "
+            f"flatland_client.create()."
+        )
+    envelope = json.loads(p.read_text())
+    _check_envelope_version(envelope, f"load {p}")
+    return FlatlandModelFile(p, transport, envelope)
+
+
+__all__ = [
+    "Transport",
+    "http_transport",
+    "FlatlandModelFile",
+    "FlatlandMutationError",
+    "create",
+    "load",
+    "DEFAULT_CLIENT_STORE_DIR",
+    "PORTABLE_IR_VERSION",
+]

flatland_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: flatland-client
+Version: 0.1.0
+Summary: Durable, dependency-free Python client for the hosted Flatland engine. Your model is a file you own; the server is a pure function that holds nothing at rest.
+Project-URL: Homepage, https://flatlandfi.com
+Project-URL: Repository, https://github.com/Flatlandfi/flatland
+Author-email: Flatland <info@flatlandfi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decision-modeling,financial-modeling,flatland,fpa,local-first
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# flatland-client
+
+The durable, dependency-free Python client for the hosted [Flatland](https://flatlandfi.com) engine.
+
+**Your model is a file you own.** It lives at `~/.flatland/models/<name>.flatland.json`
+on *your* machine — versioned in your own git, diffable, re-runnable anywhere.
+The hosted server is a pure function (`/api/v2/*`): the client ships the model IR
+in, the server computes/transforms and returns, and **retains nothing at rest**.
+
+This package is `pip install`-light: stdlib `urllib` only, no engine, no
+fastapi/uvicorn/stripe. It is the supported durable, metered hosted path for
+Python users.
+
+## Install
+
+```bash
+pip install flatland-client
+```
+
+## Quickstart
+
+```python
+from flatland_client import create, load, http_transport
+
+t = http_transport(api_key="fl_live_...")        # HTTPS to api.flatlandfi.com
+
+h = create("acme_plan", t)                         # writes ~/.flatland/models/acme_plan.flatland.json
+h.bulk_add([
+    {"name": "revenue", "type": "Currency", "value": 1000},
+    {"name": "cost", "type": "Currency", "value": 400},
+    {"name": "profit", "type": "Currency", "formula": "revenue - cost"},
+])
+print(h.compile()["values"]["profit"]["value"])    # metered compute, nothing stored server-side
+
+# --- new session / a new machine that has the file ---
+h = load("acme_plan", t)                            # durable across restart
+```
+
+## Durability + safety contract
+
+- **Atomic writes.** Every mutation persists the new IR with a tmp + `os.replace`
+  rename, so a crash never leaves a half-written model file.
+- **Fail-loud (F2).** A failed mutation (a `5xx`, or a rejected `4xx`) raises and
+  **leaves the local file untouched** — a failure is never silently mistaken for
+  success.
+- **No server fallback.** `load()` of a missing file raises — the server never
+  held your model, so it cannot supply one.
+- **Envelope versioning.** The file is `{ "flatland_ir_version": 1, "ir": {...} }`.
+  A file written by an older client keeps loading; a too-new envelope is refused
+  before it is persisted.
+- **Path-traversal-safe** model names.
+
+Get a key at https://flatlandfi.com/install.

flatland_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+flatland_client/__init__.py,sha256=IAGobINxVsL8XsflN3g6PTLc0ktaXpLJwkolf8228O0,1748
+flatland_client/client.py,sha256=cOLgy5LOhy61pTOA6Yn1xORadu-wN1os5jq7HW-zOVw,15680
+flatland_client-0.1.0.dist-info/METADATA,sha256=GAVK6o_FrkiztUreD4a6atJ1rt7qS9K4nBeFPCCYsKg,2889
+flatland_client-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+flatland_client-0.1.0.dist-info/licenses/LICENSE,sha256=d9kPorFrFdeE8m9-ulSAVKTHXDkO0c2MZMVtThRaV54,1528
+flatland_client-0.1.0.dist-info/RECORD,,

flatland_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

flatland_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Isaac Lestienne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This MIT license covers the flatland-agent terminal client only. The
+Flatland engine and API (accessed at https://api.flatlandfi.com) are a
+separate, proprietary service. "Flatland", "Flatland Agent", and the Flatland
+marks are used as product identifiers by Isaac Lestienne; this MIT license does
+not grant rights to the names, branding, or associated service. You bring your
+own LLM provider key; inference is billed to you by your provider.