openom-cli 0.1.0__tar.gz

openom_cli-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# --- OpenOM repo hygiene (see CLAUDE.md Rule 2) ---
+
+# Marketing mock - NEVER committed
+OpenOM - Make your deal legible to the buy-side's AI.htm
+OpenOM - Make your deal legible to the buy-side's AI_files/
+
+# Planning scratch - git-ignored by rule
+docs/superpowers/
+.planning/
+
+# Eval / tooling scratch
+.deepeval/
+
+# Real OM corpus - private test fixtures, never committed (confidential)
+OMs/
+
+# --- Python (/core, /cli, /mcp) ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# --- Node / TS (/js, /extension) ---
+node_modules/
+*.tsbuildinfo
+.npm/
+extension/src/generated/
+extension/test-results/
+extension/playwright-report/
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+coverage/
+extension/*.zip
+
+js/test-results/
+
+# marketing mock (Rule 2 - never commit)
+*.htm
+*_files/
+.playwright-mcp/
+om-normative-spec-draft-v0.1.md
+om-standard-handoff-v4-updated.md
+recon.md
+openOM-decision-memo.md
+
+# audit/backlog scratch is temp - lives in .planning/ (see Rule 2)
+/BACKLOG.md
+/*-audit*.md

openom_cli-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: openom-cli
+Version: 0.1.0
+Summary: openOM CLI - the `om` command over openom-core. Zero inference.
+Project-URL: Homepage, https://openom.app
+Project-URL: Documentation, https://openom.app/docs/
+Project-URL: Repository, https://github.com/Vervelio-Labs/OpenOM
+License-Expression: MIT
+Keywords: cli,commercial-real-estate,cre,data-standard,json-ld,json-schema,offering-memorandum,open-standard,openom,pdf,proptech,real-estate
+Requires-Python: >=3.11
+Requires-Dist: openom-core[render]<0.2,>=0.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openom-cli
+
+The `om` command over [`openom-core`](../core) - no UI, no inference; also the server-side path.
+
+```sh
+# From a clone (not yet on PyPI): install core first, then cli.
+pip install -e core && pip install -e cli   # add [dev] to either only to contribute
+# Once published:  pip install openom-cli
+
+om inspect  offering.pdf
+om embed    offering.pdf --payload deal.json --out out.pdf --asserted-date 2026-08-16 --validate
+om read     out.pdf
+om validate deal.json
+om check    out.pdf               # consistency only
+om --version
+```
+
+## Conformance (CI integrity gate)
+
+`om conformance` reproduces the pinned spec vectors + samples with your installed openOM - run it in
+CI so an environment/version change can't silently drift from the standard. It reads the repo's
+`spec/` tree (pass `--spec-dir <path>/spec` from outside a checkout):
+
+```sh
+om --quiet conformance                       # exit 0 = conformant, 1 = a check failed
+om conformance --impl-dir ./my-output        # certify a THIRD-PARTY implementation's output
+```
+
+## Bulk / back-catalog embed
+
+Embed openOM data into many OMs in one run - the adoption path (seed supply at the source):
+
+```sh
+# a folder of *.pdf, each paired with a sibling <name>.om.json payload:
+om embed-batch --dir ./catalog --out-dir ./embedded --asserted-date 2026-08-22 \
+   --schema ../spec/om-0.1.schema.json
+#   --dry-run        preview (validate + report, write nothing)
+#   --skip-existing  resume a large run;  --force  overwrite;  --jobs 4  parallel
+
+# or a JSON manifest of {pdf, payload, out?, assertedDate?} items:
+om embed-batch --manifest ./manifest.json --out-dir ./embedded --schema ../spec/om-0.1.schema.json
+```
+
+Deterministic, non-destructive, idempotent (re-embed replaces + records `supersedes`); schema errors
+skip that item (never embedded); emits a JSON summary (per-status counts) and `--report FILE`.
+
+### From Buildout (connector -> manifest)
+
+Turn fetched Buildout listings into an `embed-batch` manifest. Save each `buildout_get_listing` JSON
+as `<id>.json` and its OM PDF as `<id>.pdf`, then:
+
+```sh
+om buildout-manifest --listings-dir ./listings --pdf-dir ./oms --out-dir ./staged \
+   --broker "Jane Broker" --brokerage "Acme NNN" --license "MI 000" \
+   --asserted-date 2026-08-22 --noi-type in-place
+om embed-batch --manifest ./staged/manifest.json --out-dir ./embedded --schema ../spec/om-0.1.schema.json
+```
+
+The map is deterministic (names/units normalized, absent fields omitted, `cap_rate_derived` used);
+the assertion identity is yours (flags), never inferred. Review the staged payloads before embedding.
+
+## Watch-folder (server-side automation)
+
+Drop `<name>.pdf` + `<name>.json` pairs into a folder and get embedded OMs out - no UI:
+
+```sh
+om watch ./inbox --out ./outbox --asserted-date 2026-08-18 \
+   --schema ../spec/om-0.1.schema.json      # a payload with schema errors is skipped, not embedded
+
+om watch ./inbox --out ./outbox --asserted-date 2026-08-18 --once   # drain the backlog + exit (cron/CI)
+```
+
+Deterministic, zero inference. A pair is re-embedded when its pdf/json changes; `--once` processes
+the current backlog and exits (otherwise it polls every `--interval` seconds until Ctrl-C).
+
+Reads stdin / writes stdout with `--format`/`--quiet`; exit codes follow the §I contract.
+Tests: `pytest cli -q`.

openom_cli-0.1.0/README.md

@@ -0,0 +1,77 @@
+# openom-cli
+
+The `om` command over [`openom-core`](../core) - no UI, no inference; also the server-side path.
+
+```sh
+# From a clone (not yet on PyPI): install core first, then cli.
+pip install -e core && pip install -e cli   # add [dev] to either only to contribute
+# Once published:  pip install openom-cli
+
+om inspect  offering.pdf
+om embed    offering.pdf --payload deal.json --out out.pdf --asserted-date 2026-08-16 --validate
+om read     out.pdf
+om validate deal.json
+om check    out.pdf               # consistency only
+om --version
+```
+
+## Conformance (CI integrity gate)
+
+`om conformance` reproduces the pinned spec vectors + samples with your installed openOM - run it in
+CI so an environment/version change can't silently drift from the standard. It reads the repo's
+`spec/` tree (pass `--spec-dir <path>/spec` from outside a checkout):
+
+```sh
+om --quiet conformance                       # exit 0 = conformant, 1 = a check failed
+om conformance --impl-dir ./my-output        # certify a THIRD-PARTY implementation's output
+```
+
+## Bulk / back-catalog embed
+
+Embed openOM data into many OMs in one run - the adoption path (seed supply at the source):
+
+```sh
+# a folder of *.pdf, each paired with a sibling <name>.om.json payload:
+om embed-batch --dir ./catalog --out-dir ./embedded --asserted-date 2026-08-22 \
+   --schema ../spec/om-0.1.schema.json
+#   --dry-run        preview (validate + report, write nothing)
+#   --skip-existing  resume a large run;  --force  overwrite;  --jobs 4  parallel
+
+# or a JSON manifest of {pdf, payload, out?, assertedDate?} items:
+om embed-batch --manifest ./manifest.json --out-dir ./embedded --schema ../spec/om-0.1.schema.json
+```
+
+Deterministic, non-destructive, idempotent (re-embed replaces + records `supersedes`); schema errors
+skip that item (never embedded); emits a JSON summary (per-status counts) and `--report FILE`.
+
+### From Buildout (connector -> manifest)
+
+Turn fetched Buildout listings into an `embed-batch` manifest. Save each `buildout_get_listing` JSON
+as `<id>.json` and its OM PDF as `<id>.pdf`, then:
+
+```sh
+om buildout-manifest --listings-dir ./listings --pdf-dir ./oms --out-dir ./staged \
+   --broker "Jane Broker" --brokerage "Acme NNN" --license "MI 000" \
+   --asserted-date 2026-08-22 --noi-type in-place
+om embed-batch --manifest ./staged/manifest.json --out-dir ./embedded --schema ../spec/om-0.1.schema.json
+```
+
+The map is deterministic (names/units normalized, absent fields omitted, `cap_rate_derived` used);
+the assertion identity is yours (flags), never inferred. Review the staged payloads before embedding.
+
+## Watch-folder (server-side automation)
+
+Drop `<name>.pdf` + `<name>.json` pairs into a folder and get embedded OMs out - no UI:
+
+```sh
+om watch ./inbox --out ./outbox --asserted-date 2026-08-18 \
+   --schema ../spec/om-0.1.schema.json      # a payload with schema errors is skipped, not embedded
+
+om watch ./inbox --out ./outbox --asserted-date 2026-08-18 --once   # drain the backlog + exit (cron/CI)
+```
+
+Deterministic, zero inference. A pair is re-embedded when its pdf/json changes; `--once` processes
+the current backlog and exits (otherwise it polls every `--interval` seconds until Ctrl-C).
+
+Reads stdin / writes stdout with `--format`/`--quiet`; exit codes follow the §I contract.
+Tests: `pytest cli -q`.

openom_cli-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openom-cli"
+version = "0.1.0"
+description = "openOM CLI - the `om` command over openom-core. Zero inference."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = [
+    "openom", "offering-memorandum", "commercial-real-estate", "cre", "real-estate",
+    "proptech", "pdf", "cli", "json-ld", "json-schema", "open-standard", "data-standard",
+]
+# openom-core pinned to the same 0.x spec line (a 0.2 core may change the payload contract).
+dependencies = ["openom-core[render]>=0.1,<0.2", "typer>=0.12"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "mypy>=1.10", "ruff>=0.5"]
+
+[project.urls]
+Homepage = "https://openom.app"
+Documentation = "https://openom.app/docs/"
+Repository = "https://github.com/Vervelio-Labs/OpenOM"
+
+[project.scripts]
+om = "openom_cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openom_cli"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["openom_cli"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = ["pragma: no cover", "if __name__"]

openom_cli-0.1.0/src/openom_cli/buildout.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: MIT
+"""Deterministic Buildout listing -> openOM payload mapper (the connector->manifest bridge).
+
+Grounded in the REAL Buildout `get_listing` shape (nested ``core.research_property_attributes.*`` +
+``custom_fields.*`` + ``financials``). Pure + zero-inference: it normalizes names/units and omits
+anything absent - it never guesses. The human/CLI supplies the assertion identity (assertedBy,
+assertedDate, noiType, noiAsOfDate); those are never inferred from Buildout. The output is a schema-
+valid openOM payload ready for ``om embed-batch``.
+
+Note the two cap rates: ``cap_rate`` is Buildout's stated "Average CAP Rate" over the term (often
+absent); ``cap_rate_derived`` is current NOI/price. We map the derived one because it is what the
+openOM consistency check (NOI/price vs capRate) expects and what the OM's headline cap reflects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+NS = "https://openom.app/ns/0.1"
+
+
+def _num(v: Any) -> float | None:
+    try:
+        return float(str(v).replace(",", "").strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _int(v: Any) -> int | None:
+    n = _num(v)
+    return int(n) if n is not None else None
+
+
+def _pct_to_fraction(v: Any) -> float | None:
+    n = _num(v)
+    return round(n / 100, 6) if n is not None else None
+
+
+def _iso_date(mdy: Any) -> str | None:
+    """'10/1/2026' -> '2026-10-01'. Returns None if not an M/D/Y date."""
+    if not mdy:
+        return None
+    parts = str(mdy).strip().split("/")
+    if len(parts) != 3:
+        return None
+    try:
+        m, d, y = (int(p) for p in parts)
+    except ValueError:
+        return None
+    if not (1 <= m <= 12 and 1 <= d <= 31 and y > 1900):
+        return None
+    return f"{y:04d}-{m:02d}-{d:02d}"
+
+
+def _state_code(v: Any) -> str | None:
+    """'GA - Georgia' -> 'GA'; 'GA' -> 'GA'."""
+    if not v:
+        return None
+    head = str(v).split("-")[0].strip()
+    return head.upper() if len(head) == 2 else None
+
+
+def _lease_type(v: Any) -> str | None:
+    """Map Buildout's free-text lease type to the openOM asserted value."""
+    if not v:
+        return None
+    s = str(v).upper()
+    if "NNN" in s:
+        return "NNN"
+    if "NN" in s:
+        return "NN"
+    if "GROSS" in s:
+        return "gross"
+    return str(v)
+
+
+def _compact(d: dict[str, Any]) -> dict[str, Any]:
+    # drop absent values, incl. empty strings (schema forbids ""), but keep 0/0.0/False
+    return {k: v for k, v in d.items() if v not in (None, "", {}, [])}
+
+
+def _months_between(start_iso: str | None, end_iso: str | None) -> int | None:
+    """Whole months between two ISO (YYYY-MM-DD) dates, or None. Deterministic (no clock)."""
+    if not start_iso or not end_iso:
+        return None
+    try:
+        sy, sm, sd = (int(x) for x in start_iso.split("-"))
+        ey, em, ed = (int(x) for x in end_iso.split("-"))
+    except ValueError:
+        return None
+    months = (ey - sy) * 12 + (em - sm)
+    if ed < sd:  # a partial trailing month doesn't count
+        months -= 1
+    return months if months >= 0 else None
+
+
+# Canonical fields tracked for a back-catalog coverage report (the numbers a buyer underwrites).
+# Used to flag near-empty payloads before a bulk embed (Rule 6: review at scale).
+_COVERAGE_FIELDS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("askingPrice", ("deal", "askingPrice")),
+    ("capRate", ("deal", "capRate")),
+    ("noi", ("deal", "noi")),
+    ("address", ("property", "address")),
+    ("buildingSF", ("property", "buildingSF")),
+    ("tenant", ("lease", "tenantEntity")),
+    ("leaseType", ("lease", "leaseTypeAsserted")),
+    ("expiration", ("lease", "expiration")),
+)
+
+
+def payload_coverage(payload: dict[str, Any]) -> dict[str, Any]:
+    """Which tracked fields a mapped payload actually carries - for a pre-embed coverage report."""
+    present: list[str] = []
+    missing: list[str] = []
+    for name, path in _COVERAGE_FIELDS:
+        cur: Any = payload
+        for seg in path:
+            cur = cur.get(seg) if isinstance(cur, dict) else None
+        (present if cur not in (None, "", {}, []) else missing).append(name)
+    return {
+        "filled": len(present), "of": len(_COVERAGE_FIELDS),
+        "present": present, "missing": missing,
+    }
+
+
+def listing_to_payload(
+    listing: dict[str, Any],
+    *,
+    asserted_by: dict[str, str],
+    asserted_date: str,
+    noi_type: str,
+    noi_as_of: str | None = None,
+) -> dict[str, Any]:
+    """Map one Buildout ``get_listing`` object to a schema-valid openOM payload (partial fields only
+    where Buildout has them). ``asserted_by``/``asserted_date``/``noi_type``/``noi_as_of`` are the
+    human's assertion identity and are stamped verbatim, never inferred."""
+    core: dict[str, Any] = listing.get("core", {})
+    cf: dict[str, Any] = listing.get("custom_fields", {})
+    fin: dict[str, Any] = listing.get("financials", {})
+
+    def rp(attr: str) -> Any:
+        return core.get(f"research_property_attributes.{attr}")
+
+    address = _compact({
+        "streetAddress": rp("address"),
+        "addressLocality": rp("city"),
+        "addressRegion": _state_code(rp("state")),
+        "postalCode": rp("zip"),
+        "addressCountry": "US" if str(rp("country_id")) == "1" else None,
+    })
+    lat, lng = _num(rp("latitude")), _num(rp("longitude"))
+    geo = {"latitude": lat, "longitude": lng} if lat is not None and lng is not None else None
+    lot = _num(rp("lot_size")) if str(rp("lot_size_units")).lower().startswith("acre") else None
+    building_sf = _int(rp("building_size"))
+    units = _int(rp("number_of_units"))
+    # propertyType ([M4]): the primary asset-class filter, trivially mappable and never auto-filled
+    # before. Buildout exposes it as a research attribute; omitted (never guessed) when absent.
+    prop_type = rp("property_type") or rp("property_sub_type") or cf.get("Property type")
+    property_ = _compact({
+        "propertyType": str(prop_type).strip().lower() if prop_type else None,
+        "address": address or None,
+        "geo": geo,
+        "buildingSF": building_sf,
+        "yearBuilt": _int(rp("year_built")),
+        "lotAcres": lot,
+        "units": units,
+        "occupancy": _pct_to_fraction(rp("occupancy_pct")),
+    })
+
+    price = _int(fin.get("sale_price"))
+    deal = _compact({
+        "askingPrice": price,
+        "capRate": _pct_to_fraction(fin.get("cap_rate_derived") or fin.get("cap_rate")),
+        "noi": _int(fin.get("noi") or cf.get("NOI")),
+        # Deterministically derived from mapped values ([M4]); not in Buildout, computed here.
+        "pricePerUnit": round(price / units) if price and units else None,
+        "pricePerSF": round(price / building_sf, 2) if price and building_sf else None,
+        "noiType": noi_type,
+        "noiAsOfDate": noi_as_of or asserted_date,
+        "status": "active",
+    })
+
+    commencement = _iso_date(cf.get("Lease start date"))
+    expiration = _iso_date(cf.get("Lease expiration date"))
+    guarantor_name = cf.get("Lease guarantor")
+    lease = _compact({
+        "tenantEntity": cf.get("Tenant"),
+        "leaseTypeAsserted": _lease_type(cf.get("Lease type")),
+        "commencement": commencement,
+        "expiration": expiration,
+        # termMonths ([M4]): derived from the two dates above, deterministic (no clock).
+        "termMonths": _months_between(commencement, expiration),
+        "guarantor": {"name": guarantor_name, "type": "corporate"} if guarantor_name else None,
+    })
+
+    return _compact({
+        "@context": ["https://schema.org", NS],
+        "@type": "RealEstateListing",
+        "specVersion": "0.1",
+        "assertedBy": _compact(dict(asserted_by)),
+        "assertedDate": asserted_date,
+        "property": property_ or None,
+        "deal": deal or None,
+        "lease": lease or None,
+        # A fresh assertion has no prior; a re-embed records supersedes = prior payload hash (core).
+        "meta": {"supersedes": None},
+    })