| """The seam between semantic plans and one video model's reality. |
| |
| Four methods, one implementation (H3). This is deliberately NOT a plugin |
| system: there is no factory, no registry of backends, no second backend. |
| The seam exists so H3's grid law, window planning, guide placement and |
| expand-to-end semantics live in timeline/h3/ and nothing above it has to |
| know they exist (architecture amendment, 2026-08-14 night). |
| |
| Stdlib only. |
| """ |
| import abc |
|
|
|
|
| class CompileResult(object): |
| """What a backend hands back. |
| |
| graph: the executable artifact (for H3: a ComfyUI .api.json dict). |
| compiled: the cache block to store in plan['compiled'][backend_id] |
| — hold maps, window geometry, dilated lengths, graph path. |
| report: human-readable receipt, printed by nodes and CLIs. |
| warnings: things the operator should see but that do not block. |
| """ |
|
|
| def __init__(self, graph, compiled, report, warnings=None): |
| self.graph = graph |
| self.compiled = compiled |
| self.report = report |
| self.warnings = list(warnings or []) |
|
|
| def __repr__(self): |
| return (f"CompileResult(nodes={len(self.graph or {})}, " |
| f"warnings={len(self.warnings)})") |
|
|
|
|
| class VideoModelBackend(abc.ABC): |
| """A model family's opinion about how to execute a plan.""" |
|
|
| backend_id = "abstract" |
|
|
| @abc.abstractmethod |
| def capabilities(self): |
| """-> dict. What lane types compile, what the model can be asked |
| for, which structural limits are non-negotiable. UIs use this to |
| grey out lanes instead of guessing.""" |
|
|
| @abc.abstractmethod |
| def validate(self, plan, ctx=None): |
| """-> list of problems with running THIS plan on THIS model. |
| Semantic validation already happened in schema.validate; this is |
| the model's own refusals (unsupported lane, illegal length that |
| cannot be reached, budget below the smallest possible pass).""" |
|
|
| @abc.abstractmethod |
| def compile(self, plan, ctx=None): |
| """-> CompileResult. Must be deterministic: same plan revision in, |
| same graph out.""" |
|
|
| @abc.abstractmethod |
| def estimate(self, plan, ctx=None): |
| """-> price.Estimate. The plan's cost on this model, without |
| running anything.""" |
|
|
