platformforge 0.1.0__py3-none-any.whl

platformforge/federation/node.py

@@ -0,0 +1,135 @@
+"""Cycle 5 Phase J — federation contracts (§167–177).
+
+Federation = intelligence exchange, never distributed execution
+(§168, §172). Each node keeps its own execution authority; remote
+nodes can never grant it (§301). Credentials never cross the boundary
+(§175, §302).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from platformforge.fleet.models import classify
+from platformforge.live.models import canonical_hash
+
+MANIFEST_SCHEMA = "platformforge/node-manifest/v1"
+SUMMARY_SCHEMA = "platformforge/federation-summary/v1"
+EXPORT_ACTIONS = ("allow", "redact", "aggregate", "deny")
+
+
+@dataclass
+class NodeManifest:
+    """§170 — what a Forge node is and what it may share."""
+    node_id: str
+    capabilities: list[str] = field(default_factory=list)
+    fleet_scope: dict[str, Any] = field(default_factory=dict)
+    data_freshness: str = "unknown"
+    authority: str = "local"          # only ever "local" (§172)
+    version: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": MANIFEST_SCHEMA, **asdict(self)}
+
+
+@dataclass
+class FederationPolicy:
+    """§177/§309 — what may leave this node, per classification.
+    Default for unmapped classifications: `deny` (fail closed)."""
+    rules: dict[str, str] = field(default_factory=lambda: {
+        "public": "allow", "internal": "aggregate",
+        "sensitive": "redact", "restricted": "deny"})
+
+    def action_for(self, classification: str) -> str:
+        return self.rules.get(classification, "deny")
+
+
+SECRET_KEYS = ("password", "secret", "token", "credential", "api_key",
+               "private_key", "access_key", "session")
+
+
+def _contains_secret(obj: Any, depth: int = 0) -> bool:
+    if depth > 8:
+        return True
+    if isinstance(obj, dict):
+        return any(
+            any(s in str(k).lower() for s in SECRET_KEYS)
+            or _contains_secret(v, depth + 1)
+            for k, v in obj.items())
+    if isinstance(obj, (list, tuple)):
+        return any(_contains_secret(v, depth + 1) for v in obj)
+    return False
+
+
+def export_summary(node: NodeManifest, payload: dict[str, Any],
+                   classification: str,
+                   policy: FederationPolicy | None = None,
+                   ) -> dict[str, Any]:
+    """§174–177 — build a shareable summary under the export policy.
+    Refuses anything containing credential-shaped fields regardless of
+    classification (§175/§302)."""
+    cls = classify(classification)
+    pol = policy or FederationPolicy()
+    action = pol.action_for(cls)
+    if _contains_secret(payload):
+        return {"schema": SUMMARY_SCHEMA, "node_id": node.node_id,
+                "action": "deny",
+                "reason": "PF-FED-SECRET-BOUNDARY",
+                "note": "credentials never leave the node"}
+    if action == "deny":
+        return {"schema": SUMMARY_SCHEMA, "node_id": node.node_id,
+                "action": "deny", "classification": cls}
+    out: dict[str, Any] = {"schema": SUMMARY_SCHEMA,
+                           "node_id": node.node_id, "action": action,
+                           "classification": cls,
+                           "authority": "local",
+                           "freshness": node.data_freshness}
+    if action == "aggregate":
+        out["payload"] = _aggregate(payload)
+    elif action == "redact":
+        out["payload"] = _redact(payload)
+    else:
+        out["payload"] = payload
+    out["hash"] = "sha256:" + canonical_hash(out["payload"])
+    return out
+
+
+def _aggregate(payload: dict[str, Any]) -> dict[str, Any]:
+    """Counts + ratios only — individual records stay home (§310)."""
+    out: dict[str, Any] = {"aggregated": True}
+    for k, v in payload.items():
+        if isinstance(v, list):
+            out[f"{k}.count"] = len(v)
+        elif isinstance(v, dict):
+            out[k] = _aggregate(v)
+        elif isinstance(v, (int, float)):
+            out[k] = v
+        else:
+            out[f"{k}.present"] = bool(v)
+    return out
+
+
+def _redact(payload: dict[str, Any]) -> dict[str, Any]:
+    import json
+
+    from platformforge.live.store import redact_for_output
+    return json.loads(redact_for_output(json.dumps(payload)))
+
+
+def federated_query(nodes: list[NodeManifest],
+                    query_fn, question: str) -> dict[str, Any]:
+    """§171 — fan out a question to node summaries; each node answers
+    *from its own data* — authority and credentials stay local."""
+    answers = []
+    for n in nodes:
+        r = query_fn(n, question)
+        answers.append({"node_id": n.node_id,
+                        "freshness": n.data_freshness, **r})
+    covered = sum(1 for a in answers if a.get("answered"))
+    return {"question": question, "nodes": len(nodes),
+            "answered": covered,
+            "coverage": round(covered / len(nodes), 3) if nodes else 0.0,
+            "answers": answers,
+            "note": "intelligence federation — no execution authority "
+                    "crossed the boundary"}

platformforge/finops/__init__.py

@@ -0,0 +1,14 @@
+"""FinOps: cost facts, tag allocation, unit economics, graph costing,
+FOCUS-shaped output. Deterministic — cost without measurement is a refusal."""
+
+from platformforge.finops.alloc import allocate
+from platformforge.finops.costs import cost_facts, cost_summary
+from platformforge.finops.focus import to_focus, validate_focus
+from platformforge.finops.graph_cost import graph_cost
+from platformforge.finops.ingest import ingest_billing
+from platformforge.finops.insights import finops_report
+from platformforge.finops.unit import unit_economics
+
+__all__ = ["allocate", "cost_facts", "cost_summary", "finops_report",
+           "graph_cost", "ingest_billing", "to_focus", "unit_economics",
+           "validate_focus"]

platformforge/finops/alloc.py

@@ -0,0 +1,31 @@
+"""Tag-based cost allocation — spend grouped by a tag dimension; untagged
+spend is surfaced as unallocated, never silently dropped."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+
+def allocate(facts: list[dict[str, Any]], by: str = "cost_center") \
+        -> dict[str, Any]:
+    buckets: dict[str, float] = defaultdict(float)
+    unalloc: list[str] = []
+    for f in facts:
+        if f.get("kind") != "finops.cost":
+            continue
+        a = f["attrs"]
+        key = (a.get("tags") or {}).get(by)
+        if key:
+            buckets[key] += a["amount"]
+        else:
+            buckets["UNALLOCATED"] += a["amount"]
+            unalloc.append(a["resource"])
+    total = sum(buckets.values())
+    return {"by": by,
+            "allocation": {k: round(v, 4) for k, v in sorted(buckets.items())},
+            "shares": {k: round(v / total, 4) for k, v in
+                       sorted(buckets.items())} if total else {},
+            "unallocated_resources": sorted(set(unalloc)),
+            "unallocated_amount": round(buckets.get("UNALLOCATED", 0.0), 4),
+            "total": round(total, 4)}

platformforge/finops/costs.py

@@ -0,0 +1,79 @@
+"""Cost facts — ingest billing exports (JSON/CSV rows) into `finops.cost`
+facts and aggregates. Currency/period mismatches surface as unresolved."""
+
+from __future__ import annotations
+
+import csv
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+REQ_FIELDS = ("resource", "amount")
+OPT_FIELDS = ("service", "period", "currency", "unit", "tags")
+
+
+def _rows(path: Path) -> list[dict[str, Any]]:
+    if path.suffix == ".csv":
+        return list(csv.DictReader(path.open()))
+    doc = json.loads(path.read_text())
+    return doc if isinstance(doc, list) else doc.get("rows", [])
+
+
+def cost_facts_from_rows(rows: list[dict[str, Any]],
+                         source: str = "rows") -> dict[str, Any]:
+    """Row list → finops.cost facts (shared by file + ingest paths)."""
+    facts: list[dict[str, Any]] = []
+    skipped = 0
+    for r in rows:
+        if not all(r.get(k) not in (None, "") for k in REQ_FIELDS):
+            skipped += 1
+            continue
+        tags = r.get("tags")
+        if isinstance(tags, str):
+            try:
+                tags = json.loads(tags)
+            except json.JSONDecodeError:
+                tags = {}
+        attrs = {"resource": r["resource"],
+                 "amount": float(r["amount"]),
+                 "currency": r.get("currency") or "USD",
+                 "period": r.get("period") or "unknown",
+                 "service": r.get("service"),
+                 "tags": tags or {}}
+        facts.append({"fact_id": stable_id("PF-FIN", r["resource"],
+                                           str(r.get("period")),
+                                           str(r["amount"])),
+                      "kind": "finops.cost", "source": source,
+                      "location": r["resource"], "tier": 1, "attrs": attrs})
+    return {"facts": facts,
+            "counts": {"rows": len(rows), "facts": len(facts),
+                       "skipped_incomplete": skipped}}
+
+
+def cost_facts(path: str | Path) -> dict[str, Any]:
+    return cost_facts_from_rows(_rows(Path(path)), source=str(path))
+
+
+def cost_summary(facts: list[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate by period/service/currency; mixed currencies → unresolved."""
+    by_period: dict[str, dict[str, float]] = defaultdict(
+        lambda: defaultdict(float))
+    currencies: set[str] = set()
+    for f in facts:
+        if f.get("kind") != "finops.cost":
+            continue
+        a = f["attrs"]
+        currencies.add(a["currency"])
+        by_period[a["period"]][a.get("service") or "unknown"] += a["amount"]
+    out = {"by_period": {p: dict(svcs) for p, svcs in sorted(by_period.items())},
+           "currencies": sorted(currencies)}
+    if len(currencies) > 1:
+        out["unresolved"] = "mixed currencies — totals withheld"
+    else:
+        out["total"] = round(
+            sum(f["attrs"]["amount"] for f in facts
+                if f.get("kind") == "finops.cost"), 4)
+    return out

platformforge/finops/focus.py

@@ -0,0 +1,100 @@
+"""§93 FOCUS — projection plus *explicit* compliance validation.
+
+`to_focus` maps internal cost records to FOCUS column names and reports
+unmapped fields. `validate_focus` then checks the ratified FOCUS 1.x
+column contract — `focus_compliant` is only ever True after that check
+passes, and the checked spec version is always reported. The word
+'compliant' is never emitted without schema+version evidence.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+FOCUS_MAP = {
+    "resource": "ResourceId", "amount": "BilledCost", "currency": "Currency",
+    "period": "BillingPeriod", "service": "ServiceName",
+    "unit": "PricingUnit", "region": "RegionId", "account": "BillingAccountId",
+}
+
+# FOCUS required columns for the Cost and Usage dataset — stable
+# across the ratified 1.x line (1.0 → 1.4; presence-only check, dtype
+# validation is a host-side concern). FOCUS 1.3/1.4 added new datasets
+# (Billing Period, Contract Commitment) — detected, not validated here.
+FOCUS_REQUIRED_V1 = {
+    "BilledCost", "BillingAccountId", "BillingPeriodStart",
+    "BillingPeriodEnd", "ChargeCategory", "ChargeClass",
+    "ChargePeriodStart", "ChargePeriodEnd", "Currency",
+    "ServiceName", "SkuId",
+}
+
+# Versions whose Cost-and-Usage column contract we can honestly check.
+# An unknown version must never produce a "compliant" verdict.
+FOCUS_KNOWN_VERSIONS = ("1.0", "1.1", "1.2", "1.3", "1.4")
+
+# Dataset column signatures — best-effort detection, not conformance.
+_FOCUS_DATASETS = {
+    "cost-and-usage": {"BilledCost", "BillingPeriodStart",
+                       "ChargeCategory"},
+    "billing-period": {"BillingPeriodStatus", "InvoiceIssuerName"},
+    "contract-commitment": {"ContractCommitmentId", "ContractId",
+                            "ContractCommitmentCost"},
+}
+
+
+def to_focus(rows: list[dict[str, Any]]) -> dict[str, Any]:
+    out_rows, unmapped = [], set()
+    for r in rows:
+        row = {FOCUS_MAP.get(k, k): v for k, v in r.items()}
+        for k in r:
+            if k not in FOCUS_MAP:
+                unmapped.add(k)
+        row.setdefault("ChargeCategory", "usage")
+        out_rows.append(row)
+    return {"focus_rows": out_rows, "unmapped_fields": sorted(unmapped),
+            "spec": "FOCUS-like projection; validate against the ratified "
+                    "FOCUS version before external use",
+            "counts": {"rows": len(out_rows)}}
+
+
+def detect_datasets(rows: list[dict[str, Any]]) -> list[str]:
+    """Best-effort: which FOCUS datasets do these rows look like?
+    Detection ≠ conformance — reported as `detected`, never `compliant`."""
+    cols = set().union(*(r.keys() for r in rows)) if rows else set()
+    return [name for name, sig in _FOCUS_DATASETS.items()
+            if sig <= cols]
+
+
+def validate_focus(rows: list[dict[str, Any]],
+                   spec_version: str = "1.0") -> dict[str, Any]:
+    """§93 — explicit compliance verdict, never implied."""
+    if spec_version not in FOCUS_KNOWN_VERSIONS:
+        return {"focus_compliant": False,
+                "refusal": "PF-FINOPS-FOCUS-VERSION",
+                "spec_version": spec_version,
+                "unlock": "supported versions: "
+                          f"{list(FOCUS_KNOWN_VERSIONS)}"}
+    if not rows:
+        return {"focus_compliant": False, "spec_version": spec_version,
+                "reason": "no rows to validate",
+                "missing_columns": sorted(FOCUS_REQUIRED_V1)}
+    missing_per_row = []
+    for i, r in enumerate(rows):
+        missing = sorted(FOCUS_REQUIRED_V1 - set(r))
+        if missing:
+            missing_per_row.append({"row": i, "missing": missing})
+    ok = not missing_per_row
+    return {"focus_compliant": ok,
+            "spec_version": spec_version,
+            "datasets_detected": detect_datasets(rows),
+            "rows_checked": len(rows),
+            "rows_failing": len(missing_per_row),
+            "missing_columns": missing_per_row[:10],
+            "scope": "Cost and Usage columns only — Billing Period / "
+                     "Contract Commitment datasets are detected, not "
+                     "conformance-checked",
+            "note": ("schema+version validated against FOCUS "
+                     f"{spec_version} required columns" if ok else
+                     "not FOCUS-compliant — missing required columns; "
+                     "fix before claiming compliance")}
+

platformforge/finops/graph_cost.py

@@ -0,0 +1,51 @@
+"""Graph costing — join platform graph (billed_to edges) with cost facts to
+price workloads and dependency paths. Missing edges → unresolved, never zero."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from platformforge.graph.model import Graph
+from platformforge.graph.query import dependencies
+
+
+def graph_cost(graph: Graph, cost_facts: list[dict[str, Any]]) -> dict[str, Any]:
+    """cost per cost_center via billed_to edges; direct cost per node."""
+    node_cost: dict[str, float] = {}
+    for f in cost_facts:
+        if f.get("kind") != "finops.cost":
+            continue
+        res = f["attrs"]["resource"]
+        node_cost[res] = node_cost.get(res, 0.0) + f["attrs"]["amount"]
+    billed: dict[str, str] = {}
+    for e in graph.edges.values():
+        if e.kind == "billed_to":
+            billed[e.src] = e.dst
+    per_center: dict[str, float] = defaultdict(float)
+    unattributed: list[str] = []
+    for nid, amt in node_cost.items():
+        # resolve resource node id variants
+        cand = [nid] + [n for n in graph.nodes if n.endswith("/" + nid)]
+        hit = next((c for c in cand if c in billed), None)
+        if hit:
+            per_center[billed[hit]] += amt
+        else:
+            unattributed.append(nid)
+    # downstream dependency cost: for each node, sum costs of its deps
+    dep_cost = {}
+    for nid in graph.nodes:
+        deps = dependencies(graph, nid)
+        tot = sum(node_cost.get(d.split("/", 1)[-1], 0.0) +
+                  node_cost.get(d, 0.0) for d in deps)
+        own = node_cost.get(nid, 0.0) or \
+            node_cost.get(nid.split("/", 1)[-1], 0.0)
+        if own or tot:
+            dep_cost[nid] = {"own": round(own, 4),
+                             "dependencies": round(tot, 4),
+                             "total": round(own + tot, 4)}
+    return {"per_cost_center": {k: round(v, 4)
+                                for k, v in sorted(per_center.items())},
+            "unattributed_resources": sorted(unattributed),
+            "dependency_costs": dep_cost,
+            "unresolved": bool(unattributed)}

platformforge/finops/ingest.py

@@ -0,0 +1,144 @@
+"""§91 cloud cost ingestion — normalize provider billing exports into
+generic cost rows that `cost_facts` consumes.
+
+Recognized formats (detected by column shape, never by filename):
+  AWS CUR:          lineItem/ResourceId, lineItem/UnblendedCost, …
+  Azure Cost Mgmt:  ResourceId, PreTaxCost / CostInBillingCurrency, …
+  GCP Billing:      resource.name / labels, cost + usage.unit, …
+  OpenCost:         window/totalCost or per-item totalCost
+  Kubecost:         result[].cost / totalCost per resource
+
+Undetected formats produce `unresolved`, never silent skipping.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _rows(path: Path) -> list[dict[str, Any]]:
+    if path.suffix == ".csv":
+        return list(csv.DictReader(path.open()))
+    doc = json.loads(path.read_text())
+    if isinstance(doc, list):
+        return doc
+    # OpenCost/Kubecost shapes keep rows nested
+    for key in ("rows", "data", "results", "result", "items"):
+        if isinstance(doc.get(key), list):
+            return doc[key]
+    return []
+
+
+def _num(v: Any) -> float | None:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def detect_format(row: dict[str, Any]) -> str | None:
+    ks = set(row)
+    if any(k.startswith("lineItem/") for k in ks) or \
+            "lineItem/UnblendedCost" in ks:
+        return "aws_cur"
+    if "PreTaxCost" in ks or "CostInBillingCurrency" in ks or \
+            "microsoft.costmanagement" in str(row.get("type", "")).lower():
+        return "azure_costmgmt"
+    if "cost" in ks and ("usage" in ks or "labels" in ks or
+                         "sku.description" in ks or "project.id" in ks):
+        return "gcp_billing"
+    if "totalCost" in ks or ("window" in ks and "totalEfficiency" in ks):
+        return "opencost" if "window" in ks else "kubecost"
+    return None
+
+
+def normalize_row(row: dict[str, Any], fmt: str) -> dict[str, Any] | None:
+    """Provider row → generic {resource, amount, service, period,
+    currency, tags}. Returns None when the amount is unmeasurable."""
+    if fmt == "aws_cur":
+        amount = _num(row.get("lineItem/UnblendedCost"))
+        res = row.get("lineItem/ResourceId") or \
+            row.get("lineItem/LineItemDescription")
+        return {"resource": str(res), "amount": amount,
+                "service": row.get("product/ProductName")
+                or row.get("lineItem/ProductCode"),
+                "period": row.get("lineItem/BillingPeriodStartDate")
+                or row.get("bill/BillingPeriodStartDate"),
+                "currency": row.get("lineItem/CurrencyCode"),
+                "tags": row.get("resourceTags") or {}} \
+            if res and amount is not None else None
+    if fmt == "azure_costmgmt":
+        amount = _num(row.get("PreTaxCost")) or \
+            _num(row.get("CostInBillingCurrency"))
+        res = row.get("ResourceId") or row.get("MeterCategory")
+        return {"resource": str(res), "amount": amount,
+                "service": row.get("ServiceName") or row.get("MeterCategory"),
+                "period": row.get("UsageDate") or row.get("BillingPeriod"),
+                "currency": row.get("Currency"),
+                "tags": row.get("Tags") or {}} \
+            if res and amount is not None else None
+    if fmt == "gcp_billing":
+        amount = _num(row.get("cost"))
+        res = row.get("resource.name") or row.get("resource") or \
+            row.get("sku.description") or row.get("project.id")
+        labels = row.get("labels")
+        if isinstance(labels, str):
+            labels = dict(kv.split(":", 1) for kv in labels.split(",")
+                          if ":" in kv) if labels else {}
+        return {"resource": str(res), "amount": amount,
+                "service": row.get("service.description")
+                or row.get("sku.description"),
+                "period": row.get("usage_start_time")
+                or row.get("invoice.month"),
+                "currency": row.get("currency"),
+                "tags": labels or {}} \
+            if res and amount is not None else None
+    if fmt in ("opencost", "kubecost"):
+        amount = _num(row.get("totalCost"))
+        props = row.get("properties") if isinstance(
+            row.get("properties"), dict) else {}
+        res = row.get("name") or row.get("resource") or props.get("name")
+        win = row.get("window")
+        return {"resource": str(res or "unresolved"),
+                "amount": amount,
+                "service": props.get("service") or row.get("service"),
+                "period": win.get("start") if isinstance(win, dict)
+                else win,
+                "currency": "USD",
+                "tags": props.get("labels") or {}} \
+            if amount is not None else None
+    return None
+
+
+def ingest_billing(path: str | Path) -> dict[str, Any]:
+    """Detect provider format → normalized rows → cost_facts shape."""
+    rows = _rows(Path(path))
+    formats: dict[str, int] = {}
+    normalized: list[dict[str, Any]] = []
+    unrecognized = 0
+    for r in rows:
+        if not isinstance(r, dict):
+            unrecognized += 1
+            continue
+        fmt = detect_format(r)
+        if fmt is None:
+            unrecognized += 1
+            continue
+        formats[fmt] = formats.get(fmt, 0) + 1
+        nr = normalize_row(r, fmt)
+        if nr is None:
+            unrecognized += 1
+            continue
+        normalized.append(nr)
+    out = {"format": next(iter(formats), "unresolved"),
+           "formats_seen": formats,
+           "rows": normalized,
+           "counts": {"rows_in": len(rows), "normalized": len(normalized),
+                      "unrecognized": unrecognized}}
+    if not normalized and rows:
+        out["unresolved"] = "billing format not recognized — no rows " \
+                            "normalized; no costs reported"
+    return out