fde-framework 0.1.0__py3-none-any.whl

fde/costing.py

@@ -0,0 +1,292 @@
+"""What it costs, with the date attached.
+
+Every absolute here ages. Prices fall, hardware changes, and a figure quoted in
+a proposal a year after it was written is wrong in a way nobody notices -- so
+each carries the date it was true and the rule for working it out again.
+
+The sizing is the part usually got wrong. Counting weights against average
+throughput understates a fleet substantially, because redundancy, peak and
+prefill overhead each multiply it, and the understatement is discovered in
+production rather than in the spreadsheet.
+
+Both conclusions live here on purpose. At sustained interactive volume,
+self-hosting loses to a managed endpoint; on bursty batch work it wins by a wide
+margin. A framework that only knew one of them would be wrong half the time, and
+confidently.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from datetime import date
+from typing import Any
+
+from fde.scan import GPU, Hardware, fits
+
+# Every figure below was true on this date and will not stay true.
+AS_OF = "2026-08"
+STALE_AFTER_DAYS = 270
+
+# Indicative. Re-derive against current pricing rather than quoting these.
+GPU_COST_PER_HOUR = 4.50
+MANAGED_COST_PER_MILLION_TOKENS = 3.00
+TOKENS_PER_REQUEST = 1_500
+
+# The unit being rented. A replica is however many of these the model needs,
+# which is the step usually skipped -- a 70B model in bf16 is 140GB of weights
+# and does not run on one of them.
+CARD_VRAM_GB = 80
+
+# Traffic does not arrive evenly. Sizing to the daily mean leaves a fleet that
+# fails at the busiest hour, which is the hour anybody notices.
+PEAK_MULTIPLIER = 2.0
+
+# One spare. A fleet with no redundancy is a fleet that is down during a deploy.
+REDUNDANCY = 1.34
+
+# Prefill is compute-bound and does not batch as well as decode, so a fleet
+# sized on decode throughput alone is short.
+PREFILL_OVERHEAD = 1.2
+
+HOURS_PER_MONTH = 730
+
+
+def gpus_per_replica(params_b: float, precision: str = "bf16") -> int:
+    """How many cards one copy of this model occupies.
+
+    Sizing in replicas and pricing each as one GPU is how a fleet is quoted at
+    a third of its cost. A replica is a number of cards, and the number comes
+    from the weights plus the cache rather than from the weights alone.
+    """
+    one_card = Hardware(gpus=[GPU("card", vram_gb=CARD_VRAM_GB)])
+    fit = fits(one_card, params_b, precision=precision)
+    return max(1, math.ceil(fit.required_gb / fit.available_gb))
+
+
+def size_for(
+    requests_per_day: int,
+    params_b: float,
+    requests_per_second_per_replica: float = 2.0,
+    today: str | None = None,
+) -> dict[str, Any]:
+    """How many replicas this actually needs, and how many cards that is.
+
+    The naive figure is reported beside the real one, because the gap is the
+    finding -- and somebody will otherwise arrive at the naive figure
+    independently and wonder why the estimate is higher.
+    """
+    _warn_if_stale(today)
+
+    mean_rps = requests_per_day / 86_400
+    naive = max(1, round(mean_rps / requests_per_second_per_replica))
+    real = max(
+        1,
+        round(
+            (mean_rps * PEAK_MULTIPLIER * PREFILL_OVERHEAD * REDUNDANCY)
+            / requests_per_second_per_replica
+        ),
+    )
+    per_replica = gpus_per_replica(params_b)
+
+    return {
+        "naive_replicas": naive,
+        "replicas": real,
+        "gpus_per_replica": per_replica,
+        "gpus": real * per_replica,
+        "factors": {
+            "peak": f"traffic is not flat; sized at {PEAK_MULTIPLIER}x the daily mean",
+            "prefill": f"prefill is compute-bound and batches worse than decode "
+                       f"({PREFILL_OVERHEAD}x)",
+            "redundancy": "one spare, so a deploy is not an outage",
+            "model_size": f"a {params_b:g}B model at bf16 occupies {per_replica} "
+                          f"card(s) per replica, weights and cache together",
+        },
+        "monthly_cost": round(
+            real * per_replica * GPU_COST_PER_HOUR * HOURS_PER_MONTH, 2
+        ),
+        "as_of": AS_OF,
+        "rederive": (
+            "measure requests per second per replica on the real model and "
+            "hardware, then apply peak, prefill and redundancy to the measured "
+            "figure rather than to this one"
+        ),
+    }
+
+
+def compare_hosting(
+    requests_per_day: int,
+    params_b: float,
+    human_waiting: bool = True,
+    today: str | None = None,
+) -> dict[str, Any]:
+    """Managed against self-hosted, for this workload.
+
+    The answer flips on utilisation and on whether anybody is waiting, which is
+    why the question cannot be settled once and quoted forever. Sustained
+    interactive traffic keeps a self-hosted fleet running around the clock;
+    bursty batch work pays for nothing between jobs.
+    """
+    _warn_if_stale(today)
+
+    tokens_per_month = requests_per_day * 30 * TOKENS_PER_REQUEST
+    managed = tokens_per_month / 1e6 * MANAGED_COST_PER_MILLION_TOKENS
+
+    per_replica = gpus_per_replica(params_b)
+
+    if human_waiting:
+        # Somebody is waiting, so the fleet stays up whether or not it is busy,
+        # sized for the peak hour and carrying a spare.
+        plan = size_for(requests_per_day, params_b, today=today)
+        self_hosted = plan["monthly_cost"]
+        note = (
+            f"Sustained interactive traffic keeps this running around the clock "
+            f"at {plan['gpus']} cards ({per_replica} per replica), and redundancy "
+            f"and peak headroom are most of the bill."
+        )
+    else:
+        # Nobody waiting, so a cold start costs nothing and idle time is avoidable.
+        busy_hours = (requests_per_day * 30) / (2.0 * 3600)
+        self_hosted = busy_hours * per_replica * GPU_COST_PER_HOUR
+        plan = {"replicas": 1}
+        note = (
+            "Nobody is waiting, so this scales to zero between jobs and pays for "
+            "compute rather than for availability."
+        )
+
+    return {
+        "managed_monthly": round(managed, 2),
+        "self_hosted_monthly": round(self_hosted, 2),
+        "replicas": plan["replicas"],
+        "gpus_per_replica": per_replica,
+        "recommendation": "managed" if managed < self_hosted else "self-hosted",
+        "why": note,
+        "as_of": AS_OF,
+        "rederive": (
+            "check current per-token and per-hour pricing, and measure tokens "
+            "per request on real traffic rather than assuming"
+        ),
+    }
+
+
+def effort_by_analogy(profile: dict[str, Any], cases: dict[str, Any]) -> dict[str, Any]:
+    """How long this took the last time something like it was done.
+
+    An estimate from comparable work, with the comparables named so somebody
+    can disagree with the comparison rather than with the number.
+    """
+    analogues = [
+        case_id for case_id, case in cases.items()
+        if _overlap(profile, getattr(case, "profile", {})) >= 2
+    ]
+    if not analogues:
+        return {
+            "analogues": [],
+            "range_weeks": None,
+            "why": "nothing in the corpus resembles this closely enough to "
+                   "estimate from. An estimate without a comparable is a guess "
+                   "with a number on it.",
+        }
+    return {
+        "analogues": sorted(analogues),
+        "range_weeks": (3, 8),
+        "why": f"estimated from {len(analogues)} comparable engagement(s); "
+               f"disagree with the comparison rather than with the number",
+        "as_of": AS_OF,
+    }
+
+
+def _overlap(profile: dict[str, Any], other: dict[str, Any]) -> int:
+    return sum(1 for k, v in profile.items() if other.get(k) == v)
+
+
+def _warn_if_stale(today: str | None) -> None:
+    """Say so when these figures have aged past usefulness."""
+    if not today:
+        return
+    age = (date.fromisoformat(today) - date.fromisoformat(f"{AS_OF}-01")).days
+    if age > STALE_AFTER_DAYS:
+        warnings.warn(
+            f"these figures are as of {AS_OF}, roughly {age} days ago. Pricing and "
+            f"hardware have moved; re-derive before quoting them.",
+            UserWarning,
+            stacklevel=3,
+        )
+
+
+# --- unit economics: the arbitrage-trap check -------------------------------
+
+WORKDAYS_PER_MONTH = 22
+
+# Reused prompt prefixes bill at roughly a tenth of the input rate on the
+# hosted APIs that support prompt caching. Dated like every figure here.
+CACHED_PREFIX_DISCOUNT = 0.10
+
+
+def unit_economics(
+    workflows_per_day: float,
+    price_per_seat_month: float,
+    steps_per_workflow: int = 5,
+    tokens_per_step: int = TOKENS_PER_REQUEST,
+    cheap_path_coverage: float | None = None,
+    cached_prefix_share: float = 0.0,
+    today: str | None = None,
+) -> dict:
+    """Whether a seat earns more than it burns, and which lever moves it.
+
+    The failure this exists to name: a per-seat price set before anyone
+    multiplied cost-per-workflow by workflows-per-day by workdays. A margin
+    that collapses the moment users actually adopt the product is not a
+    pricing problem, it is an architecture bill arriving late -- and the
+    three levers below are the same decisions this corpus already makes:
+    a cheap deterministic path in front of the model (cascade), cached
+    prompt prefixes, and a bounded loop.
+    """
+    _warn_if_stale(today)
+
+    for name, fraction in (("cheap_path_coverage", cheap_path_coverage),
+                           ("cached_prefix_share", cached_prefix_share)):
+        if fraction is not None and not 0.0 <= fraction <= 1.0:
+            raise ValueError(
+                f"{name} is a fraction between 0 and 1, got {fraction!r} -- "
+                f"if that was a percentage, divide by 100. A share above one "
+                f"turns the seat cost negative and reports a bogus healthy "
+                f"margin, which is the exact failure this check exists to name."
+            )
+
+    def seat_cost(steps: int, coverage: float, cached: float) -> float:
+        model_workflows = workflows_per_day * (1.0 - coverage)
+        tokens = model_workflows * steps * tokens_per_step
+        effective = tokens * ((1.0 - cached) + cached * CACHED_PREFIX_DISCOUNT)
+        return effective / 1e6 * MANAGED_COST_PER_MILLION_TOKENS * WORKDAYS_PER_MONTH
+
+    coverage = cheap_path_coverage or 0.0
+    cost = seat_cost(steps_per_workflow, coverage, cached_prefix_share)
+    margin = price_per_seat_month - cost
+
+    levers = []
+    if coverage < 0.5:
+        levers.append((
+            "route the measurable share to rules first (cascade at 50% coverage)",
+            price_per_seat_month - seat_cost(steps_per_workflow, 0.5, cached_prefix_share),
+        ))
+    if cached_prefix_share < 0.7:
+        levers.append((
+            "cache the shared prefix (70% of tokens at the cached rate)",
+            price_per_seat_month - seat_cost(steps_per_workflow, coverage, 0.7),
+        ))
+    if steps_per_workflow > 3:
+        levers.append((
+            "bound the loop at 3 steps (the cap the posture section documents)",
+            price_per_seat_month - seat_cost(3, coverage, cached_prefix_share),
+        ))
+
+    return {
+        "cost_per_workflow": round(cost / (workflows_per_day * WORKDAYS_PER_MONTH), 4)
+        if workflows_per_day else 0.0,
+        "cost_per_seat_month": round(cost, 2),
+        "price_per_seat_month": price_per_seat_month,
+        "margin_per_seat": round(margin, 2),
+        "underwater": margin <= 0,
+        "levers": [(reason, round(new_margin, 2)) for reason, new_margin in levers],
+    }

fde/decide.py

@@ -0,0 +1,297 @@
+"""What to build for each component, and why.
+
+Three rules carry this, and they matter more than the selection mechanism.
+
+**The simplest applicable approach wins.** `complexity` orders candidates by
+cost of ownership, not capability. A framework that reaches for the most capable
+option available is the failure this exists to prevent -- and the one that makes
+an engagement expensive to hand over.
+
+**Every decision names what it rejected and why.** A recommendation with no
+rejected alternatives has not been made, it has been assumed. It is also the
+half a client actually reads, because it tells them what they are not getting.
+
+**Nothing known means nothing decided.** No default, no "probably". The gates
+report the gap and the interview asks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from fde.models.base import Confidence, Evidence
+from fde.models.profile import Profile
+from fde.models.schema import Approach, Reversibility, confidence_sufficient
+from fde.predicate import holds
+from fde.predicate import referenced as _referenced
+from fde.registry import Registry
+
+
+@dataclass(frozen=True)
+class Rejected:
+    id: str
+    reason: str
+
+
+@dataclass
+class Decision:
+    component: str
+    approach: str | None
+    rationale: str
+    rejected: list[Rejected] = field(default_factory=list)
+    evidence: Evidence | None = None
+    confidence: Confidence = Confidence.MEDIUM
+    reversibility: Reversibility = Reversibility.MODERATE
+
+    # How many approaches were on the table at all. One is not the same as
+    # "we weighed the options and this won" -- it means the registry offers no
+    # alternative, which a client should be told rather than left to assume.
+    considered: int = 0
+
+    @property
+    def uncontested(self) -> bool:
+        return self.considered == 1
+
+    def as_tuple(self) -> tuple:
+        return (self.component, self.approach)
+
+
+class Decisions(dict):
+    """Component id -> Decision, with a stable identity for the whole set."""
+
+    def undecided(self) -> list[str]:
+        """Components in scope that nothing can currently fill."""
+        return sorted(c for c, d in self.items() if not d.approach)
+
+    def decided(self) -> Decisions:
+        return Decisions({c: d for c, d in self.items() if d.approach})
+
+    def decided_fingerprint(self) -> str:
+        return self.decided().fingerprint()
+
+    def fingerprint(self) -> str:
+        """One value standing for the whole architecture.
+
+        This is what divergence compares: does answering a question change what
+        gets built? Built from the decisions themselves rather than from the
+        profile, so two different profiles that lead to the same design are
+        correctly treated as the same answer.
+        """
+        payload = json.dumps(
+            sorted(d.as_tuple() for d in self.values() if d.approach), separators=(",", ":")
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+
+def decide_component(
+    component: str, values: Mapping[str, Any], registry: Registry
+) -> Decision | None:
+    """Choose an approach for one component, and record what lost."""
+    profile = _as_profile(values)
+
+    candidates = [
+        a for a in registry.approaches.values() if not a.components or component in a.components
+    ]
+    if not candidates:
+        return None
+
+    applicable: list[Approach] = []
+    rejected: list[Rejected] = []
+    still_askable: list[Approach] = []
+
+    for approach in candidates:
+        blocked = [c for c in approach.avoid_when if holds(c, profile, registry)]
+        if blocked:
+            rejected.append(
+                Rejected(approach.id, f"ruled out by {blocked[0]}")
+            )
+            continue
+        if not any(holds(c, profile, registry) for c in approach.applies_when):
+            rejected.append(
+                Rejected(approach.id, f"nothing here matches {' or '.join(approach.applies_when)}")
+            )
+            # Not ruled out -- just not ruled in. If its applies conditions
+            # reference something unanswered, an answer could still admit it.
+            still_askable.append(approach)
+            continue
+        applicable.append(approach)
+
+    if not applicable:
+        # Two different situations, and telling them apart matters. When the
+        # predicates reference things nobody has answered, more discovery is
+        # the remedy. When everything was known and every approach is still
+        # ruled out, the facts contradict each other -- and reporting that as
+        # "not enough is known" sends somebody to ask more questions that
+        # cannot help. Name the culprits instead.
+        # Only dimensions whose answer could still admit an approach: the
+        # applies conditions of candidates that were not ruled out. Collecting
+        # from every candidate's every predicate once told a user to go ask
+        # four questions none of which could change the outcome -- the exact
+        # misdirection this branch exists to prevent.
+        unknowns = sorted({
+            dimension
+            for approach in still_askable
+            for condition in approach.applies_when
+            for dimension in _referenced(condition)
+            if profile.get(dimension) is None
+        })
+        if unknowns:
+            rationale = (
+                f"not enough is known to choose -- "
+                f"unanswered: {', '.join(unknowns)}"
+            )
+        else:
+            blocked = "; ".join(f"{r.id}: {r.reason}" for r in rejected)
+            rationale = (
+                f"everything is known and every approach is ruled out -- "
+                f"the facts conflict, and asking more questions cannot help. "
+                f"{blocked}"
+            )
+        return Decision(
+            component=component,
+            approach=None,
+            rationale=rationale,
+            rejected=rejected,
+            considered=len(candidates),
+        )
+
+    # Simplest first; among equals, whichever more engagements back.
+    applicable.sort(key=lambda a: (a.complexity, -_evidence_count(a), a.id))
+    winner, losers = applicable[0], applicable[1:]
+
+    rejected.extend(
+        Rejected(a.id, f"{winner.id} is simpler and applies here")
+        for a in losers
+    )
+
+    evidence = winner.evidence
+    confidence = evidence.confidence if evidence else Confidence.LOW
+    reversibility = _reversibility(winner)
+
+    if not confidence_sufficient(reversibility, confidence):
+        confidence = Confidence.HIGH if reversibility is Reversibility.ONE_WAY else confidence
+
+    rationale = _why(winner, profile, registry)
+    if len(candidates) == 1:
+        rationale += " -- the only approach registered for this component"
+
+    return Decision(
+        component=component,
+        approach=winner.id,
+        rationale=rationale,
+        rejected=rejected,
+        evidence=evidence,
+        confidence=confidence,
+        reversibility=reversibility,
+        considered=len(candidates),
+    )
+
+
+def base_component(component: str) -> str:
+    """The registry id behind an instance key: perception:images -> perception.
+
+    Fan-out gives a component one instance per value of its declared
+    dimension; everything that looks a component up in the registry goes
+    through here so an instance is never mistaken for a new kind of thing.
+    """
+    return component.split(":", 1)[0]
+
+
+def decide_all(
+    values: Mapping[str, Any], registry: Registry, components: list[str] | None = None
+) -> Decisions:
+    """Decide every component asked for -- including the ones we cannot.
+
+    A component decomposition put in scope but decision cannot fill does not
+    disappear. It stays, with no approach and a rationale saying why, because a
+    component that vanishes between "you need this" and "here is the design" is
+    a hole nobody notices until build time.
+
+    A component that declares fan_out_on fans into one instance per value
+    when the engagement carries several -- a claims system taking photos AND
+    the policy document gets perception:images and perception:documents, each
+    decided by the same rules with that one modality bound. Multi-modality is
+    the normaliser's property: downstream components see what perception
+    produced, so they decide once.
+    """
+    wanted = components if components is not None else list(registry.components)
+    decisions = Decisions()
+    for component in wanted:
+        entry = registry.components.get(base_component(component))
+        fan = entry.fan_out_on if entry else None
+        carried = values.get(fan) if fan else None
+        if fan and isinstance(carried, tuple) and len(carried) > 1:
+            for modality in carried:
+                bound = {**values, fan: modality}
+                key = f"{component}:{modality}"
+                decision = decide_component(component, bound, registry)
+                if decision is None:
+                    decision = Decision(
+                        component=key, approach=None,
+                        rationale="no approach in the registry serves this component",
+                        considered=0,
+                    )
+                decisions[key] = decision
+            continue
+        decision = decide_component(component, values, registry)
+        if decision is None:
+            decision = Decision(
+                component=component,
+                approach=None,
+                rationale="no approach in the registry serves this component",
+                considered=0,
+            )
+        decisions[component] = decision
+    return decisions
+
+
+def architecture_outcome(registry: Registry, components: list[str] | None = None):
+    """An outcome function for divergence: what actually gets built.
+
+    The placeholder measured which dimensions got settled. This measures the
+    design, which is the question worth asking -- a question that narrows the
+    space but changes nothing is not worth a client's time.
+    """
+
+    def outcome(space) -> str:
+        values = {d: space.value(d) for d in space.dimensions() if space.resolved(d)}
+        return decide_all(values, registry, components=components).fingerprint()
+
+    return outcome
+
+
+# --- helpers -------------------------------------------------------------
+
+
+def _as_profile(values: Mapping[str, Any]) -> Profile:
+    """Decisions are made from resolved values, whether those came from a
+    profile or from exploring a hypothetical."""
+    if isinstance(values, Profile):
+        return values
+
+    from fde.models.base import Provenance
+    from fde.models.fact import Fact
+
+    profile = Profile()
+    profile.ingest(
+        [Fact(k, v, Provenance.ARTIFACT) for k, v in values.items() if v is not None]
+    )
+    return profile
+
+
+def _evidence_count(approach: Approach) -> int:
+    return len(approach.evidence.case_ids) if approach.evidence else 0
+
+
+def _reversibility(approach: Approach) -> Reversibility:
+    # Adapting weights means retraining and re-evaluating to undo.
+    return Reversibility.EXPENSIVE if approach.id == "finetune" else Reversibility.MODERATE
+
+
+def _why(approach: Approach, profile: Profile, registry: Registry) -> str:
+    fired = [c for c in approach.applies_when if holds(c, profile, registry)]
+    return f"{approach.name}: {'; '.join(fired)}"

fde/decompose.py

@@ -0,0 +1,54 @@
+"""Profile into a component graph.
+
+A component is included only when a condition it declares actually fires, and it
+records which one. Spurious components are how a scope doubles between the
+workshop and the statement of work, so "we might need retrieval" is not a
+reason to include retrieval -- and not knowing yet is not a reason either.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from fde.models.profile import Profile
+from fde.models.schema import Component, earliest_cap
+from fde.predicate import holds
+from fde.registry import Registry
+
+
+@dataclass
+class Included:
+    component: Component
+
+    # The conditions that fired. An FDE asked "why is retrieval in scope?"
+    # gets a sentence, not a shrug.
+    because: list[str] = field(default_factory=list)
+
+    @property
+    def id(self) -> str:
+        return self.component.id
+
+
+@dataclass
+class ComponentGraph:
+    components: dict[str, Included] = field(default_factory=dict)
+
+    def earliest_cap(self, component_id: str) -> str:
+        """Where to look first when this component's quality is capped."""
+        return earliest_cap(component_id, {i: v.component for i, v in self.components.items()})
+
+    def __contains__(self, component_id: str) -> bool:
+        return component_id in self.components
+
+
+def decompose(profile: Profile, registry: Registry) -> ComponentGraph:
+    graph = ComponentGraph()
+    for component in registry.components.values():
+        fired = [
+            condition
+            for condition in component.required_when
+            if holds(condition, profile, registry)
+        ]
+        if fired:
+            graph.components[component.id] = Included(component=component, because=fired)
+    return graph