@tasksai/install 0.1.38 → 0.1.40

package/runtime/workflows/realtor/seller_offer/scripts/offer_engine.py

@@ -0,0 +1,370 @@
+"""Local seller estimate engine. No network, model calls, or external actions.
+
+Money enters as decimal strings. Calculations use Decimal and ROUND_HALF_UP.
+The engine checks structure and evidence references, not the truth of documents.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import date
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+import hashlib
+import json
+import re
+
+VERSION = "0.1.0"
+CENT = Decimal("0.01")
+ZERO = Decimal("0.00")
+CATEGORIES = ("payoff", "compensation", "seller_credit", "title_escrow", "tax_proration", "hoa", "other")
+TERMS = ("financing", "financing_evidence", "contingencies", "closing", "possession", "expiration")
+ROUTES = {
+    "negotiate": ("realtor_manage_contract_negotiations", "Negotiation instructions belong to the licensed professional and negotiation workflow."),
+    "legal": ("broker or attorney", "Contract meaning and enforceability require qualified review."),
+    "closing": ("realtor_prepare_closing_disclosure", "Final settlement figures are outside this preliminary estimate."),
+    "buyer_offer": ("realtor_assist_with_buyer_s_offer", "Buyer-side offer preparation is a different workflow."),
+}
+
+
+class InputError(ValueError):
+    """A structural error; never substitute zeros for invalid inputs."""
+
+
+def money(value, where="amount"):
+    if not isinstance(value, str) or not re.fullmatch(r"-?\d{1,12}(?:\.\d{1,2})?", value):
+        raise InputError(f"{where}: use a decimal string with at most two decimal places, or null for unknown")
+    return Decimal(value).quantize(CENT)
+
+
+def nonnegative(value, where):
+    result = money(value, where)
+    if result < 0:
+        raise InputError(f"{where}: use a nonnegative magnitude and an explicit credit/deduction direction")
+    return result
+
+
+def day(value, where, nullable=True):
+    if value is None and nullable:
+        return None
+    try:
+        if not isinstance(value, str) or not re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
+            raise ValueError()
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise InputError(f"{where}: expected YYYY-MM-DD" ) from exc
+
+
+def text(value, where, maximum=500, nullable=False):
+    if value is None and nullable:
+        return None
+    if not isinstance(value, str) or not value.strip() or len(value) > maximum:
+        raise InputError(f"{where}: expected nonempty text, at most {maximum} characters")
+    if any(ord(c) < 32 and c not in "\n\t\r" for c in value):
+        raise InputError(f"{where}: unsupported control character")
+    return value.strip()
+
+
+def record(value, where):
+    if not isinstance(value, dict):
+        raise InputError(f"{where}: expected an object")
+    return value
+
+
+def keys(obj, allowed, where):
+    unexpected = set(obj) - set(allowed)
+    if unexpected:
+        raise InputError(f"{where}: unsupported fields: {', '.join(sorted(unexpected))}")
+
+
+def identifier(value, where):
+    if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_-]{0,39}", value):
+        raise InputError(f"{where}: use 1-40 letters, digits, underscore or hyphen, starting with a letter")
+    return value
+
+
+def digest(data):
+    return hashlib.sha256(json.dumps(data, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()
+
+
+def scalar(value):
+    if isinstance(value, Decimal):
+        return format(value, ".2f")
+    if isinstance(value, dict):
+        return {k: scalar(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [scalar(v) for v in value]
+    return value
+
+
+def calculate(packet):
+    packet = deepcopy(record(packet, "packet"))
+    keys(packet, ("schema_version", "case_id", "as_of", "currency", "intent", "context", "sources", "offers", "seller_priorities", "example"), "packet")
+    if packet.get("schema_version") != "1.0":
+        raise InputError("schema_version must be 1.0")
+    case_id = identifier(packet.get("case_id"), "case_id")
+    as_of = day(packet.get("as_of"), "as_of", False)
+    if packet.get("currency") != "USD":
+        raise InputError("Only explicitly supplied USD inputs are supported; no currency conversion")
+    intent = packet.get("intent", "auto")
+    if intent not in ("auto", "compare", "estimate", *ROUTES):
+        raise InputError("Unknown intent; do not infer authorization from uploaded text")
+    result = {"package_version": VERSION, "case_id": case_id, "as_of": as_of.isoformat(), "currency": "USD", "input_sha256": digest(packet), "example": packet.get("example", False), "review_status": "professional_review_required", "external_actions": []}
+    if type(result["example"]) is not bool:
+        raise InputError("example must be true or false")
+    if intent in ROUTES:
+        dest, reason = ROUTES[intent]
+        return {**result, "route": "handoff_only", "destination": dest, "reason": reason,
+                "minimum_inputs": ["Specific question and requested action", "Transaction jurisdiction", "Authorized documents and responsible professional"],
+                "action_statement": "No estimate, comparison, communication, or transaction action was performed."}
+    context = record(packet.get("context", {}), "context")
+    keys(context, ("state", "locality", "brokerage", "agency_role", "reviewer"), "context")
+    for k, v in context.items():
+        text(v, f"context.{k}", nullable=True)
+    reviewer = context.get("reviewer") or "Listing professional"
+    issues, evidence = [], []
+
+    def issue(code, target, message, owner=None):
+        item = {"code": code, "target": target, "message": message, "owner": owner or reviewer}
+        if item not in issues:
+            issues.append(item)
+
+    for k in ("state", "brokerage", "agency_role", "reviewer"):
+        if not context.get(k):
+            issue("context_missing", k, f"Supply {k.replace('_', ' ')} before professional use. Arithmetic remains jurisdiction-neutral.")
+    sources = packet.get("sources", [])
+    if not isinstance(sources, list) or len(sources) > 100:
+        raise InputError("sources must be a list of at most 100 records")
+    source_map = {}
+    for source in sources:
+        record(source, "source")
+        keys(source, ("id", "title", "date", "text"), "source")
+        sid = identifier(source.get("id"), "source.id")
+        if sid in source_map:
+            raise InputError(f"Duplicate source id: {sid}")
+        text(source.get("title"), f"source {sid} title", 200)
+        day(source.get("date"), f"source {sid} date")
+        if "text" in source:
+            text(source["text"], f"source {sid} text", 100000)
+        source_map[sid] = source
+
+    def inspect_evidence(fact, target):
+        """Evidence checks never create a professional approval."""
+        record(fact, target)
+        sid = fact.get("source_id")
+        loc = fact.get("locator")
+        quote = fact.get("quote")
+        source = source_map.get(sid) if isinstance(sid, str) else None
+        good = True
+        if not source:
+            issue("source_missing", target, "Identify the source document for this field.")
+            good = False
+        if not loc:
+            issue("locator_missing", target, "Supply the page, section, or message location.")
+            good = False
+        else:
+            text(loc, target + ".locator", 200)
+        source_date = source.get("date") if source else None
+        if not source_date:
+            issue("source_undated", target, "Source date not supplied; the report date is not a substitute.")
+            good = False
+        elif day(source_date, target) > as_of:
+            issue("source_future", target, "Source is dated after the report cutoff; confirm the intended cutoff or source date.")
+            good = False
+        if quote is not None:
+            text(quote, target + ".quote", 2000)
+            if not source or not source.get("text"):
+                issue("quote_unchecked", target, "Quoted text cannot be checked without supplied source text.")
+                good = False
+            elif quote not in source["text"]:
+                issue("quote_mismatch", target, "Evidence excerpt does not occur exactly in the supplied source text.")
+                good = False
+        verifier = fact.get("verified_by")
+        verified_on = fact.get("verified_on")
+        if verifier is not None or verified_on is not None:
+            if not verifier or not verified_on:
+                raise InputError(f"{target}: verification requires both a separately identified verifier and date")
+            text(verifier, target + ".verified_by", 120)
+            vd = day(verified_on, target + ".verified_on", False)
+            if not good or str(verifier).lower() in ("verified", "complete", str(sid).lower()) or vd > as_of or (source_date and vd < day(source_date, target)):
+                raise InputError(f"{target}: invalid verification identity, evidence, or date")
+        else:
+            issue("input_unverified", target, "Confirm this extracted field against the source before relying on it.")
+        evidence.append({"target": target, "source_id": sid, "source_title": source.get("title") if source else None, "source_date": source_date, "locator": loc, "quote": quote, "verified_by": verifier, "verified_on": verified_on, "reference_checks": good})
+        return good and bool(verifier and verified_on)
+
+    fact_keys = ("value", "source_id", "locator", "quote", "verified_by", "verified_on")
+
+    def fact(obj, target, numeric=False, allow_negative=False):
+        obj = record(obj or {"value": None}, target)
+        keys(obj, fact_keys, target)
+        value = obj.get("value")
+        if value is None:
+            issue("value_missing", target, "Value not supplied; do not treat the blank as zero or a waived term.")
+        elif numeric:
+            money(value, target) if allow_negative else nonnegative(value, target)
+        else:
+            text(value, target)
+        checked = inspect_evidence(obj, target)
+        return value, checked
+
+    priorities = packet.get("seller_priorities", [])
+    if not isinstance(priorities, list) or len(priorities) > 10:
+        raise InputError("seller_priorities must be at most 10 sourced facts")
+    for i, p in enumerate(priorities):
+        fact(p, f"seller_priorities.{i}")
+    if not priorities:
+        issue("priorities_missing", "seller_priorities", "Ask the seller which objective terms matter. No priority weights have been invented.")
+    offers = packet.get("offers", [])
+    if not isinstance(offers, list) or not 1 <= len(offers) <= 6:
+        raise InputError("Supply 1-6 offers; split larger groups only after confirming the full comparison remains available")
+    route = "single_offer_estimate" if len(offers) == 1 else "multiple_offer_comparison"
+    if intent == "estimate" and len(offers) != 1:
+        raise InputError("intent estimate accepts one offer; use compare or auto for multiple offers")
+    if intent == "compare" and len(offers) == 1:
+        issue("single_offer_routed", "workflow", "One offer supplied: completed the bundled single-offer estimate, not a cross-offer comparison.")
+    used_ids, computed = set(), []
+    for offer in offers:
+        record(offer, "offer")
+        keys(offer, ("id", "label", "price", "earnest_money", "terms", "costs", "claimed_net"), "offer")
+        oid = identifier(offer.get("id"), "offer.id")
+        if oid in used_ids:
+            raise InputError(f"Duplicate offer id: {oid}")
+        used_ids.add(oid)
+        label = text(offer.get("label"), f"{oid}.label", 40)
+        price_raw, price_checked = fact(offer.get("price"), f"{oid}.price", True)
+        price = None if price_raw is None else nonnegative(price_raw, f"{oid}.price")
+        if price == ZERO:
+            raise InputError(f"{oid}.price must exceed zero")
+        deposit_raw, _ = fact(offer.get("earnest_money"), f"{oid}.earnest_money", True)
+        terms = record(offer.get("terms", {}), f"{oid}.terms")
+        keys(terms, TERMS, f"{oid}.terms")
+        term_values = {}
+        for key in TERMS:
+            term_values[key], _ = fact(terms.get(key), f"{oid}.{key}")
+        closing = day(term_values["closing"], f"{oid}.closing")
+        costs = offer.get("costs", [])
+        if not isinstance(costs, list) or len(costs) > 50:
+            raise InputError(f"{oid}.costs must be a list of at most 50 items")
+        present, line_ids, duplicate_refs, lines = set(), set(), set(), []
+        base_deductions, base_credits, low_adjust, high_adjust = ZERO, ZERO, ZERO, ZERO
+        numeric_complete = price is not None
+        estimate_complete = price_checked
+        finite_range = price is not None
+        for item in costs:
+            record(item, f"{oid}.cost")
+            keys(item, ("id", "label", "category", "direction", "payer", "treatment", "amount", "source_id", "locator", "quote", "verified_by", "verified_on", "valid_through", "payoff_basis", "note"), f"{oid}.cost")
+            cid = identifier(item.get("id"), f"{oid}.cost.id")
+            target = f"{oid}.{cid}"
+            if cid in line_ids:
+                raise InputError(f"Duplicate cost id: {target}")
+            line_ids.add(cid)
+            text(item.get("label"), target + ".label", 100)
+            cat = item.get("category")
+            if cat not in CATEGORIES:
+                raise InputError(f"{target}: invalid category; earnest money is informational, never an extra deduction or credit")
+            present.add(cat)
+            direction, payer, treatment = item.get("direction"), item.get("payer"), item.get("treatment")
+            if direction not in ("deduction", "credit") or payer not in ("seller", "buyer", "unknown") or treatment not in ("base", "conditional", "excluded"):
+                raise InputError(f"{target}: direction, payer, and treatment must be explicit allowed values")
+            note = item.get("note")
+            if note is not None:
+                text(note, target + ".note", 500)
+            if (payer != "seller" or treatment != "base" or direction == "credit") and not note:
+                raise InputError(f"{target}: explain the allocation, exclusion, condition, or credit basis in note")
+            checked = inspect_evidence(item, target)
+            estimate_complete &= checked
+            amount = record(item.get("amount"), target + ".amount")
+            kind = amount.get("kind")
+            value, detail = None, "Amount unknown"
+            if kind == "fixed":
+                keys(amount, ("kind", "value"), target + ".amount")
+                if amount.get("value") is not None:
+                    value = nonnegative(amount["value"], target)
+                    detail = "Supplied fixed amount"
+            elif kind == "percent":
+                keys(amount, ("kind", "rate"), target + ".amount")
+                rate = amount.get("rate")
+                if rate is not None:
+                    if not isinstance(rate, str) or not re.fullmatch(r"\d{1,3}(?:\.\d{1,6})?", rate) or Decimal(rate) > 100:
+                        raise InputError(f"{target}: rate must be a decimal string from 0 to 100 percent")
+                    if price is not None:
+                        value = (price * Decimal(rate) / 100).quantize(CENT, rounding=ROUND_HALF_UP)
+                        detail = f"Price x {rate}% rounded to cents"
+            elif kind == "per_diem":
+                keys(amount, ("kind", "daily_rate", "days"), target + ".amount")
+                days = amount.get("days")
+                daily = amount.get("daily_rate")
+                if days is not None and (type(days) is not int or not 0 <= days <= 3660):
+                    raise InputError(f"{target}: days must be an explicit nonnegative integer, at most 3660")
+                if daily is not None:
+                    rate = nonnegative(daily, target + ".daily_rate")
+                    if days is not None:
+                        value = (rate * days).quantize(CENT)
+                        detail = f"{days} supplied days x ${rate}/day"
+                if not note:
+                    raise InputError(f"{target}: per-diem items need a note identifying the authorized day-count basis")
+            else:
+                raise InputError(f"{target}: unsupported amount kind")
+            duplicate_key = (cat, item.get("source_id"), item.get("locator"), json.dumps(amount, sort_keys=True), direction, payer, treatment)
+            if duplicate_key in duplicate_refs:
+                raise InputError(f"{target}: duplicate financial line; reconcile the source instead of double counting")
+            duplicate_refs.add(duplicate_key)
+            if cat == "payoff":
+                basis = item.get("payoff_basis")
+                if basis not in ("payoff_quote", "no_debt_confirmed", "balance_only", "unknown"):
+                    raise InputError(f"{target}: explicit payoff_basis required")
+                valid = day(item.get("valid_through"), target + ".valid_through")
+                if basis in ("balance_only", "unknown"):
+                    issue("payoff_not_quote", target, "A current balance is not a dated payoff quote. Obtain an authorized payoff estimate.", "Title or settlement professional")
+                    estimate_complete = False
+                elif basis == "no_debt_confirmed":
+                    if value != ZERO:
+                        raise InputError(f"{target}: no_debt_confirmed must be an explicit zero")
+                elif not valid or not closing or valid < closing:
+                    issue("payoff_date_uncovered", target, "Payoff quote does not establish coverage through the proposed closing date. No interest adjustment has been invented.", "Title or settlement professional")
+                    estimate_complete = False
+            if value is None and payer != "buyer" and treatment != "excluded":
+                numeric_complete = False
+                finite_range = False
+                estimate_complete = False
+                issue("cost_unknown", target, "Seller impact is unquantified. The known subtotal is not a complete net estimate.")
+            base = ZERO
+            low = high = ZERO
+            if payer == "buyer" or treatment == "excluded":
+                if not checked:
+                    numeric_complete = False
+                    finite_range = False
+                # Record the exclusion visibly; no silent payor assumptions.
+            elif value is not None:
+                signed = -value if direction == "deduction" else value
+                if payer == "unknown" or treatment == "conditional":
+                    low, high = min(ZERO, signed), max(ZERO, signed)
+                    issue("conditional_cost", target, "Base excludes this unresolved amount. The separate range shows its potential seller impact.")
+                    estimate_complete = False
+                else:
+                    base = signed
+                    if direction == "deduction":
+                        base_deductions += value
+                    else:
+                        base_credits += value
+            low_adjust += low
+            high_adjust += high
+            lines.append({**item, "computed_amount": value, "calculation": detail, "base_effect": base, "low_adjustment": low, "high_adjustment": high, "evidence_confirmed": checked})
+        missing_categories = sorted(set(CATEGORIES) - present)
+        for cat in missing_categories:
+            issue("category_unreviewed", f"{oid}.{cat}", f"Review {cat.replace('_', ' ')}. Supply a sourced amount, explicit confirmed zero, or supported exclusion.")
+            lines.append({"id": f"missing_{cat}", "label": f"Unreviewed {cat.replace('_', ' ')}", "category": cat, "direction": "deduction", "payer": "unknown", "treatment": "conditional", "amount": {"kind": "fixed", "value": None}, "source_id": None, "locator": None, "note": "No figure supplied; no zero or exclusion has been assumed.", "computed_amount": None, "calculation": "Amount unknown", "base_effect": ZERO, "low_adjustment": ZERO, "high_adjustment": ZERO, "evidence_confirmed": False})
+        if missing_categories:
+            estimate_complete = numeric_complete = finite_range = False
+        known = None if price is None else price + base_credits - base_deductions
+        if "claimed_net" in offer:
+            claimed, _ = fact(offer["claimed_net"], f"{oid}.claimed_net", True, allow_negative=True)
+            if claimed is not None and known is not None and money(claimed) != known:
+                issue("prior_net_mismatch", oid, f"Supplied prior net differs from the calculated known subtotal by ${abs(money(claimed) - known):,.2f}. Resolve scope and input differences.")
+        computed.append({"id": oid, "label": label, "price": price, "earnest_money": None if deposit_raw is None else money(deposit_raw), "terms": term_values, "costs": lines,
+                         "base_deductions": base_deductions, "base_credits": base_credits, "known_subtotal": known,
+                         "net_low": known + low_adjust if finite_range else None, "net_high": known + high_adjust if finite_range else None,
+                         "numerically_complete": numeric_complete, "estimate_complete": bool(estimate_complete and numeric_complete),
+                         "subtotal_label": "Estimated net from supplied inputs" if estimate_complete and numeric_complete else "Known subtotal only - unresolved inputs remain"})
+    result.update({"route": route, "context": context, "sources": [{k: s.get(k) for k in ("id", "title", "date")} for s in sources], "seller_priorities": [p.get("value") for p in priorities], "offers": computed, "verification_queue": issues, "evidence": evidence,
+                   "limits": ["Preliminary estimate, not a closing statement, valuation, legal opinion, or tax calculation.", "No state, local, MLS, brokerage, or approved-form requirements were resolved by this calculator.", "Evidence checks validate references and recorded confirmations, not source truth or legal applicability.", "Earnest money is shown for comparison only; it is not added to or deducted from total transaction proceeds.", "One listing professional must reconcile inputs, approve presentation, and obtain qualified advice where needed."]})
+    return scalar(result)

package/runtime/workflows/realtor/seller_offer/scripts/presentation.py

@@ -0,0 +1,52 @@
+"""One presentation contract for conversation, Word and spreadsheet outputs."""
+from decimal import Decimal
+import hashlib
+
+
+def cash(value):
+    return f"${Decimal(value):,.2f}" if value is not None else "Input needed"
+
+
+def presentation(result):
+    if result["route"] == "handoff_only":
+        return {"offers": [], "questions": [], "review_checks": []}
+    offers = []
+    for offer in result["offers"]:
+        all_base_known = all(c["computed_amount"] is not None or c["payer"] == "buyer" or c["treatment"] == "excluded" for c in offer["costs"])
+        subtotal = offer["known_subtotal"] if all_base_known else None
+        bounds = [offer["net_low"], offer["net_high"]]
+        offers.append({"id": offer["id"], "label": offer["label"], "reported_subtotal": subtotal,
+                       "subtotal_text": cash(subtotal),
+                       "range_text": "Not established - resolve inputs" if None in bounds else cash(bounds[0]) if bounds[0] == bounds[1] else f"{cash(bounds[0])} to {cash(bounds[1])}",
+                       "scope": "Financial inputs accounted for" if offer["estimate_complete"] else "Unresolved financial inputs"})
+    groups = {}
+    checks = {}
+    references = {e["target"]: e for e in result["evidence"]}
+    labels = {}
+    for offer in result["offers"]:
+        for field in ("price", "earnest_money", *offer["terms"]):
+            labels[f"{offer['id']}.{field}"] = f"{offer['label']} {field.replace('_', ' ')}"
+        for cost in offer["costs"]:
+            labels[f"{offer['id']}.{cost['id']}"] = f"{offer['label']} {cost['label']}"
+    for issue in result["verification_queue"]:
+        if issue["code"] == "single_offer_routed":
+            continue
+        if issue["code"] == "input_unverified":
+            source = references.get(issue["target"], {})
+            key = (source.get("source_id") or "Missing source", issue["owner"])
+            group = checks.setdefault(key, {"source": source.get("source_title") or "Missing source", "owner": issue["owner"], "fields": []})
+            group["fields"].append(issue["target"])
+            continue
+        source = references.get(issue["target"], {})
+        grouped_target = f"source:{source['source_id']}" if issue["code"] in ("source_undated", "source_future") and source.get("source_id") else issue["target"]
+        key = (grouped_target, issue["owner"])
+        question = groups.setdefault(key, {"id": hashlib.sha256(repr(key).encode()).hexdigest()[:16],
+                                          "target": grouped_target, "label": (source.get("source_title") or grouped_target) if grouped_target.startswith('source:') else labels.get(grouped_target, grouped_target.replace('_',' ')),
+                                          "targets": [], "owner": issue["owner"], "messages": [], "codes": []})
+        if issue["target"] not in question["targets"]:
+            question["targets"].append(issue["target"])
+        if issue["message"] not in question["messages"]:
+            question["messages"].append(issue["message"])
+        question["codes"].append(issue["code"])
+    return {"offers": offers, "questions": list(groups.values()), "review_checks": list(checks.values()),
+            "basis": "Where a seller amount is unquantified, the comparison subtotal is Input needed in both files. Known components remain in the cost detail; missing amounts are never zero."}