openforma 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. forma_cli/__init__.py +5 -0
  2. forma_cli/app.py +1139 -0
  3. forma_cli/config.py +112 -0
  4. forma_cli/credentials.py +141 -0
  5. forma_cli/local.py +562 -0
  6. forma_cli/metadata_api.py +138 -0
  7. forma_cli/project_artifacts.py +182 -0
  8. forma_cli/sdk.py +571 -0
  9. forma_core/__init__.py +9 -0
  10. forma_core/__main__.py +4 -0
  11. forma_core/_version.py +3 -0
  12. forma_core/agents/__init__.py +50 -0
  13. forma_core/agents/clarification.py +194 -0
  14. forma_core/agents/component_reconciliation.py +99 -0
  15. forma_core/agents/context_gathering.py +115 -0
  16. forma_core/agents/continuous.py +537 -0
  17. forma_core/agents/contracts.py +247 -0
  18. forma_core/agents/firecrawl_mcp.py +484 -0
  19. forma_core/agents/lattice.py +239 -0
  20. forma_core/agents/orchestrator.py +3724 -0
  21. forma_core/agents/pipeline.py +843 -0
  22. forma_core/agents/project_correction.py +83 -0
  23. forma_core/agents/prompt_compaction.py +428 -0
  24. forma_core/agents/system_architecture.py +345 -0
  25. forma_core/agents/video_correction.py +119 -0
  26. forma_core/agents/web_research_workflow.py +1256 -0
  27. forma_core/agents/workflows.py +176 -0
  28. forma_core/assets/__init__.py +1 -0
  29. forma_core/assets/models.py +156 -0
  30. forma_core/assets/project.py +17 -0
  31. forma_core/assets/repository.py +48 -0
  32. forma_core/assets/service.py +142 -0
  33. forma_core/assets/validation.py +35 -0
  34. forma_core/benchmarks/__init__.py +5 -0
  35. forma_core/benchmarks/ir_triad_v1.py +477 -0
  36. forma_core/biology/__init__.py +28 -0
  37. forma_core/biology/benchmark.py +80 -0
  38. forma_core/biology/ewart_liverchip.py +279 -0
  39. forma_core/biology/ir.py +25 -0
  40. forma_core/biology/liverbench.py +416 -0
  41. forma_core/biology/liverbench_assay.py +251 -0
  42. forma_core/biology/liverbench_baselines.py +133 -0
  43. forma_core/biology/liverbench_independent.py +229 -0
  44. forma_core/biology/liverchip_demo.py +154 -0
  45. forma_core/biology/liverchip_evidence.py +149 -0
  46. forma_core/biology/models.py +247 -0
  47. forma_core/biology/validation.py +72 -0
  48. forma_core/cad_migrations/__init__.py +6 -0
  49. forma_core/cad_migrations/cli.py +101 -0
  50. forma_core/cad_migrations/emitters.py +227 -0
  51. forma_core/cad_migrations/models.py +121 -0
  52. forma_core/cad_migrations/planner.py +68 -0
  53. forma_core/chemistry/__init__.py +5 -0
  54. forma_core/chemistry/models.py +215 -0
  55. forma_core/chemistry/stoichiometry.py +272 -0
  56. forma_core/chemistry/validation.py +179 -0
  57. forma_core/cli/__init__.py +1 -0
  58. forma_core/cli/__main__.py +4 -0
  59. forma_core/cli/main.py +370 -0
  60. forma_core/config/__init__.py +28 -0
  61. forma_core/config/compatibility.py +282 -0
  62. forma_core/config/contract.py +184 -0
  63. forma_core/config/environment.py +129 -0
  64. forma_core/config/parti.py +34 -0
  65. forma_core/config/runtime.py +303 -0
  66. forma_core/control/__init__.py +10 -0
  67. forma_core/control/actions.py +136 -0
  68. forma_core/control/adapters.py +36 -0
  69. forma_core/control/cli.py +49 -0
  70. forma_core/control/client.py +124 -0
  71. forma_core/control/models.py +168 -0
  72. forma_core/control/opencode_worker.py +80 -0
  73. forma_core/control/package.py +318 -0
  74. forma_core/control/rover_scene/__init__.py +1 -0
  75. forma_core/control/rover_scene/__main__.py +34 -0
  76. forma_core/control/rover_scene/assets.py +65 -0
  77. forma_core/control/rover_scene/fleet.py +214 -0
  78. forma_core/control/rover_scene/host.py +258 -0
  79. forma_core/control/rover_scene/kinematics.py +35 -0
  80. forma_core/control/rover_scene/machine.py +347 -0
  81. forma_core/control/rover_scene/robot.py +166 -0
  82. forma_core/control/rover_scene/scene.py +206 -0
  83. forma_core/control/rover_scene/view.py +80 -0
  84. forma_core/control/rover_scene/web/index.html +25 -0
  85. forma_core/control/rover_scene/web/viewer.js +148 -0
  86. forma_core/control/runtime.py +356 -0
  87. forma_core/control/so101.py +235 -0
  88. forma_core/control/tasks.py +287 -0
  89. forma_core/database.py +2362 -0
  90. forma_core/debug.py +314 -0
  91. forma_core/domains/__init__.py +7 -0
  92. forma_core/domains/agents.py +85 -0
  93. forma_core/domains/base.py +69 -0
  94. forma_core/domains/benchmark.py +87 -0
  95. forma_core/domains/cli.py +48 -0
  96. forma_core/domains/compatibility.py +234 -0
  97. forma_core/domains/composition.py +372 -0
  98. forma_core/domains/diagnostics.py +15 -0
  99. forma_core/domains/generation.py +479 -0
  100. forma_core/domains/interaction.py +301 -0
  101. forma_core/domains/planning.py +140 -0
  102. forma_core/domains/providers.py +214 -0
  103. forma_core/domains/registry.py +267 -0
  104. forma_core/domains/selection.py +75 -0
  105. forma_core/domains/storage.py +60 -0
  106. forma_core/domains/tools.py +180 -0
  107. forma_core/electronics/__init__.py +1 -0
  108. forma_core/electronics/models.py +84 -0
  109. forma_core/electronics/primitives.py +43 -0
  110. forma_core/electronics/rules.py +340 -0
  111. forma_core/external_sources.py +497 -0
  112. forma_core/fabricator/__init__.py +33 -0
  113. forma_core/fabricator/__main__.py +7 -0
  114. forma_core/fabricator/main.py +578 -0
  115. forma_core/firmware/__init__.py +60 -0
  116. forma_core/firmware/drivers.py +140 -0
  117. forma_core/firmware/examples.py +503 -0
  118. forma_core/firmware/generate.py +520 -0
  119. forma_core/firmware/models.py +34 -0
  120. forma_core/firmware/sil/__init__.py +5 -0
  121. forma_core/firmware/sil/adapter.py +71 -0
  122. forma_core/firmware/sil/build.py +49 -0
  123. forma_core/firmware/sil/native/CMakeLists.txt +9 -0
  124. forma_core/firmware/sil/native/bridge.cpp +112 -0
  125. forma_core/firmware/sil/native/controller.cpp +123 -0
  126. forma_core/firmware/sil/native/controller.h +49 -0
  127. forma_core/firmware/sil/simulator.py +139 -0
  128. forma_core/firmware/targets.py +111 -0
  129. forma_core/firmware/validation.py +130 -0
  130. forma_core/fluidics/__init__.py +6 -0
  131. forma_core/fluidics/benchmark.py +217 -0
  132. forma_core/fluidics/calculations.py +79 -0
  133. forma_core/fluidics/examples.py +54 -0
  134. forma_core/fluidics/ir.py +25 -0
  135. forma_core/fluidics/models.py +132 -0
  136. forma_core/fluidics/topology.py +47 -0
  137. forma_core/fluidics/validation.py +134 -0
  138. forma_core/generation.py +32 -0
  139. forma_core/geometry_bindings/__init__.py +20 -0
  140. forma_core/geometry_bindings/cad_adapter.py +80 -0
  141. forma_core/geometry_bindings/models.py +163 -0
  142. forma_core/geometry_bindings/resolution.py +340 -0
  143. forma_core/geometry_bindings/tools.py +125 -0
  144. forma_core/image_providers.py +3049 -0
  145. forma_core/images.py +3 -0
  146. forma_core/integrations/__init__.py +1 -0
  147. forma_core/integrations/huggingface/__init__.py +29 -0
  148. forma_core/integrations/huggingface/huggingface_artifacts.py +272 -0
  149. forma_core/jobs/__init__.py +1 -0
  150. forma_core/jobs/context.py +277 -0
  151. forma_core/jobs/continuous.py +719 -0
  152. forma_core/jobs/metrics.py +124 -0
  153. forma_core/jobs/migrations.py +161 -0
  154. forma_core/jobs/persistence.py +28 -0
  155. forma_core/jobs/repositories.py +422 -0
  156. forma_core/jobs/schema.py +28 -0
  157. forma_core/jobs/source_usage.py +230 -0
  158. forma_core/jobs/store.py +476 -0
  159. forma_core/llm.py +3 -0
  160. forma_core/llm_providers.py +2682 -0
  161. forma_core/logs.py +107 -0
  162. forma_core/mechanics/__init__.py +1 -0
  163. forma_core/mechanics/gear_benchmark.py +85 -0
  164. forma_core/mechanics/mechanism_benchmarks.py +345 -0
  165. forma_core/mechanics/models.py +72 -0
  166. forma_core/mechanics/primitives.py +109 -0
  167. forma_core/mechanics/solid_cad.py +83 -0
  168. forma_core/observability.py +237 -0
  169. forma_core/openai_streams.py +780 -0
  170. forma_core/opencode/__init__.py +25 -0
  171. forma_core/opencode/architecture.py +82 -0
  172. forma_core/opencode/capabilities.py +130 -0
  173. forma_core/opencode/models.py +419 -0
  174. forma_core/opencode/persistence.py +62 -0
  175. forma_core/opencode/public_events.py +91 -0
  176. forma_core/opencode/schema.py +28 -0
  177. forma_core/opencode/store.py +874 -0
  178. forma_core/persistence/__init__.py +16 -0
  179. forma_core/persistence/base.py +38 -0
  180. forma_core/persistence/images.py +598 -0
  181. forma_core/persistence/migrations.py +200 -0
  182. forma_core/persistence/models.py +439 -0
  183. forma_core/persistence/project_artifacts.py +341 -0
  184. forma_core/persistence/project_reconciliation.py +1094 -0
  185. forma_core/persistence/providers/__init__.py +4 -0
  186. forma_core/persistence/providers/sqlite.py +114 -0
  187. forma_core/persistence/providers/supabase.py +31 -0
  188. forma_core/persistence/repositories/__init__.py +9 -0
  189. forma_core/persistence/repositories/base.py +335 -0
  190. forma_core/persistence/repositories/sqlite.py +1571 -0
  191. forma_core/persistence/repositories/supabase.py +1576 -0
  192. forma_core/persistence/schema.py +176 -0
  193. forma_core/processes/__init__.py +5 -0
  194. forma_core/processes/models.py +338 -0
  195. forma_core/processes/validation.py +141 -0
  196. forma_core/project_list_cache.py +316 -0
  197. forma_core/prompt_continuity.py +387 -0
  198. forma_core/providers/__init__.py +39 -0
  199. forma_core/providers/base.py +28 -0
  200. forma_core/providers/models.py +138 -0
  201. forma_core/providers/openai.py +92 -0
  202. forma_core/providers/openai_compatible.py +190 -0
  203. forma_core/providers/registry.py +68 -0
  204. forma_core/providers/registry_utils.py +46 -0
  205. forma_core/py.typed +1 -0
  206. forma_core/runtime.py +3 -0
  207. forma_core/selectors.py +36 -0
  208. forma_core/signups/__init__.py +5 -0
  209. forma_core/signups/models.py +49 -0
  210. forma_core/terminal/__init__.py +1 -0
  211. forma_core/terminal/dashboard.py +475 -0
  212. forma_core/terminal/images.py +156 -0
  213. forma_core/thermal/__init__.py +5 -0
  214. forma_core/thermal/models.py +361 -0
  215. forma_core/thermal/validation.py +175 -0
  216. forma_core/user_integrations.py +2069 -0
  217. forma_core/utils.py +291 -0
  218. forma_core/validation.py +83 -0
  219. forma_core/vertex_auth.py +92 -0
  220. forma_core/video_prompts.py +193 -0
  221. forma_core/video_review.py +1006 -0
  222. forma_core/wiring.py +356 -0
  223. forma_core/workers/__init__.py +120 -0
  224. forma_core/workers/contracts.py +183 -0
  225. forma_core/workers/generation.py +753 -0
  226. forma_core/workers/orchestration.py +805 -0
  227. forma_core/workers/registry.py +222 -0
  228. forma_core/workers/reverse_engineering.py +272 -0
  229. forma_core/workers/validation.py +291 -0
  230. forma_core/workspaces/__init__.py +5 -0
  231. forma_core/workspaces/chats/__init__.py +11 -0
  232. forma_core/workspaces/chats/models.py +48 -0
  233. forma_core/workspaces/context/__init__.py +15 -0
  234. forma_core/workspaces/context/agent.py +260 -0
  235. forma_core/workspaces/context/models.py +117 -0
  236. forma_core/workspaces/context/pdf.py +418 -0
  237. forma_core/workspaces/design_briefs/__init__.py +25 -0
  238. forma_core/workspaces/design_briefs/models.py +85 -0
  239. forma_core/workspaces/design_briefs/references.py +56 -0
  240. forma_core/workspaces/models.py +41 -0
  241. forma_core/workspaces/projects/__init__.py +88 -0
  242. forma_core/workspaces/projects/cad_generation.py +1016 -0
  243. forma_core/workspaces/projects/context_governance.py +365 -0
  244. forma_core/workspaces/projects/design_lifecycle.py +668 -0
  245. forma_core/workspaces/projects/fabrication/__init__.py +54 -0
  246. forma_core/workspaces/projects/fabrication/demo_printers.py +236 -0
  247. forma_core/workspaces/projects/fabrication/models.py +120 -0
  248. forma_core/workspaces/projects/fabrication/printer_config.py +205 -0
  249. forma_core/workspaces/projects/fabrication/slicers/__init__.py +7 -0
  250. forma_core/workspaces/projects/fabrication/slicers/base.py +25 -0
  251. forma_core/workspaces/projects/fabrication/slicers/cura.py +125 -0
  252. forma_core/workspaces/projects/fabrication/slicers/orca.py +208 -0
  253. forma_core/workspaces/projects/fabrication/slicing.py +202 -0
  254. forma_core/workspaces/projects/fabrication/validation.py +103 -0
  255. forma_core/workspaces/projects/gear_benchmark.py +6 -0
  256. forma_core/workspaces/projects/generation_mode.py +70 -0
  257. forma_core/workspaces/projects/identity.py +28 -0
  258. forma_core/workspaces/projects/iteration.py +680 -0
  259. forma_core/workspaces/projects/manifest.py +362 -0
  260. forma_core/workspaces/projects/mechanism_benchmarks.py +12 -0
  261. forma_core/workspaces/projects/models.py +913 -0
  262. forma_core/workspaces/projects/objects.py +731 -0
  263. forma_core/workspaces/projects/outcomes.py +47 -0
  264. forma_core/workspaces/projects/output.py +735 -0
  265. forma_core/workspaces/projects/resolver.py +397 -0
  266. forma_core/workspaces/projects/solid_cad.py +8 -0
  267. forma_core/workspaces/projects/state.py +622 -0
  268. forma_core/workspaces/readiness/__init__.py +28 -0
  269. forma_core/workspaces/readiness/evaluator.py +103 -0
  270. forma_core/workspaces/readiness/models.py +97 -0
  271. forma_core/workspaces/readiness/service.py +225 -0
  272. forma_core/workspaces/reverse_engineering/__init__.py +37 -0
  273. forma_core/workspaces/reverse_engineering/analyzer.py +246 -0
  274. forma_core/workspaces/reverse_engineering/models.py +128 -0
  275. forma_core/workspaces/validation/__init__.py +37 -0
  276. forma_core/workspaces/validation/evaluator.py +327 -0
  277. forma_core/workspaces/validation/models.py +146 -0
  278. forma_core/workspaces/validation/service.py +212 -0
  279. forma_core/workspaces/workflow/__init__.py +29 -0
  280. forma_core/workspaces/workflow/guard.py +33 -0
  281. forma_core/workspaces/workflow/models.py +77 -0
  282. forma_core/workspaces/workflow/service.py +287 -0
  283. openforma-0.4.0.dist-info/METADATA +247 -0
  284. openforma-0.4.0.dist-info/RECORD +288 -0
  285. openforma-0.4.0.dist-info/WHEEL +5 -0
  286. openforma-0.4.0.dist-info/entry_points.txt +4 -0
  287. openforma-0.4.0.dist-info/licenses/LICENSE +373 -0
  288. openforma-0.4.0.dist-info/top_level.txt +2 -0
@@ -0,0 +1,361 @@
1
+ """Independent ThermalIR v1: thermal design topology, constraints and provenance.
2
+
3
+ No thermal value is inferred from CAD geometry, chemistry or electrical power.
4
+ Numerical results belong to a separately versioned, explicitly requested check.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Literal
10
+
11
+ from pydantic import Field, model_validator
12
+
13
+ from forma_core.domains.base import DomainDocument, DomainModel, Text, unique
14
+
15
+ EvidenceBasis = Literal["specified", "measured", "derived", "assumed", "illustrative", "unknown"]
16
+ QuantityKind = Literal[
17
+ "temperature", "temperature_difference", "heat_rate", "energy",
18
+ "resistance", "conductance", "capacity", "conductivity", "area",
19
+ "heat_flux", "convection_coefficient", "emissivity",
20
+ ]
21
+ UNITS: dict[str, frozenset[str]] = {
22
+ "temperature": frozenset({"K", "degC"}),
23
+ "temperature_difference": frozenset({"K", "delta_degC"}),
24
+ "heat_rate": frozenset({"W", "kW"}),
25
+ "energy": frozenset({"J", "kJ"}),
26
+ "resistance": frozenset({"K/W"}),
27
+ "conductance": frozenset({"W/K"}),
28
+ "capacity": frozenset({"J/K"}),
29
+ "conductivity": frozenset({"W/(m*K)"}),
30
+ "area": frozenset({"m2"}),
31
+ "heat_flux": frozenset({"W/m2"}),
32
+ "convection_coefficient": frozenset({"W/(m2*K)"}),
33
+ "emissivity": frozenset({"1"}),
34
+ }
35
+
36
+
37
+ class ThermalContext(DomainModel):
38
+ """Required thermal-only authoring inputs; no global HardwareIR or scene."""
39
+
40
+ scope: Text
41
+ thermal_requirements: list[Text] = Field(min_length=1)
42
+ boundary_requirements: list[Text] = Field(min_length=1)
43
+ evidence_requirements: list[Text] = Field(min_length=1)
44
+
45
+
46
+ class ThermalEvidence(DomainModel):
47
+ """A locatable source or an explicit unverified engineering assumption."""
48
+
49
+ source_id: Text
50
+ basis: EvidenceBasis
51
+ title: Text
52
+ publisher: Text | None = None
53
+ locator: Text | None = None
54
+ published_at: Text | None = None
55
+ retrieved_at: Text | None = None
56
+ effective_at: Text | None = None
57
+ undated_reason: Text | None = None
58
+ applicability: Text | None = None
59
+ uncertainty: Text | None = None
60
+ rationale: Text | None = None
61
+
62
+ @model_validator(mode="after")
63
+ def require_source_or_rationale(self) -> "ThermalEvidence":
64
+ """Do not pass illustrative data off as sourced measurements."""
65
+ if self.basis in {"measured", "specified"}:
66
+ if not self.publisher or not self.locator or not self.retrieved_at:
67
+ raise ValueError("Specified/measured evidence requires publisher, locator and retrieval time.")
68
+ if not self.published_at and not self.undated_reason:
69
+ raise ValueError("Undated sourced evidence requires undated_reason.")
70
+ if self.basis in {"assumed", "illustrative"} and not self.rationale:
71
+ raise ValueError("Assumed/illustrative evidence requires rationale.")
72
+ return self
73
+
74
+
75
+ class ThermalClaim(DomainModel):
76
+ """The authority and traceability of one engineering design statement."""
77
+
78
+ basis: EvidenceBasis = "unknown"
79
+ source_ids: list[Text] = Field(default_factory=list)
80
+ rationale: Text | None = None
81
+
82
+ @model_validator(mode="after")
83
+ def require_evidence(self) -> "ThermalClaim":
84
+ """Evidence requirements depend on what authority is claimed."""
85
+ if self.basis in {"measured", "specified"} and not self.source_ids:
86
+ raise ValueError("Specified/measured claims require source_ids.")
87
+ if self.basis in {"assumed", "illustrative"} and not self.rationale:
88
+ raise ValueError("Assumed/illustrative claims require rationale.")
89
+ return self
90
+
91
+
92
+ class ThermalQuantity(DomainModel):
93
+ """One strictly dimensioned quantity; absolute and differential °C differ."""
94
+
95
+ kind: QuantityKind
96
+ value: float
97
+ unit: Text
98
+ claim: ThermalClaim = Field(default_factory=ThermalClaim)
99
+
100
+ @model_validator(mode="after")
101
+ def validate_dimension_and_physics(self) -> "ThermalQuantity":
102
+ """Reject dimensional mismatches and physically nonsensical magnitudes."""
103
+ if self.unit not in UNITS[self.kind]:
104
+ raise ValueError(f"Unit '{self.unit}' is unsupported for '{self.kind}'.")
105
+ if self.kind == "temperature":
106
+ kelvin = self.value if self.unit == "K" else self.value + 273.15
107
+ if kelvin < 0:
108
+ raise ValueError("Temperature below absolute zero.")
109
+ if self.kind in {"resistance", "conductance", "capacity", "conductivity",
110
+ "area", "convection_coefficient"} and self.value <= 0:
111
+ raise ValueError(f"'{self.kind}' must be positive.")
112
+ if self.kind in {"heat_rate", "energy", "heat_flux"} and self.value < 0:
113
+ raise ValueError(f"'{self.kind}' is a nonnegative magnitude; use source/sink direction.")
114
+ if self.kind == "emissivity" and not 0 <= self.value <= 1:
115
+ raise ValueError("Emissivity must be between 0 and 1.")
116
+ return self
117
+
118
+
119
+ class ThermalPort(DomainModel):
120
+ """Stable thermal-energy interface for ProcessIR and other domains."""
121
+
122
+ port_id: Text
123
+ kind: Literal["heat"] = "heat"
124
+
125
+
126
+ class ThermalNode(DomainModel):
127
+ """A lumped temperature/energy node or fixed environmental boundary."""
128
+
129
+ node_id: Text
130
+ kind: Literal["zone", "body", "boundary"]
131
+ ports: list[ThermalPort] = Field(default_factory=lambda: [ThermalPort(port_id="heat")])
132
+ capacity: ThermalQuantity | None = None
133
+ initial_temperature: ThermalQuantity | None = None
134
+ target_temperature: ThermalQuantity | None = None
135
+ maximum_temperature: ThermalQuantity | None = None
136
+ material_reference: Text | None = None
137
+ description: Text | None = None
138
+
139
+ @model_validator(mode="after")
140
+ def check_node(self) -> "ThermalNode":
141
+ """Do not confuse thermal capacity or initial temperature with other units."""
142
+ unique([p.port_id for p in self.ports], "thermal port ID")
143
+ if self.capacity is not None and self.capacity.kind != "capacity":
144
+ raise ValueError("Thermal node capacity must use J/K.")
145
+ for label, quantity in (
146
+ ("initial", self.initial_temperature),
147
+ ("target", self.target_temperature),
148
+ ("maximum", self.maximum_temperature),
149
+ ):
150
+ if quantity is not None and quantity.kind != "temperature":
151
+ raise ValueError(f"{label} temperature must be absolute.")
152
+ if self.target_temperature is not None and self.maximum_temperature is not None:
153
+ target = (self.target_temperature.value if self.target_temperature.unit == "K"
154
+ else self.target_temperature.value + 273.15)
155
+ maximum = (self.maximum_temperature.value if self.maximum_temperature.unit == "K"
156
+ else self.maximum_temperature.value + 273.15)
157
+ if target > maximum:
158
+ raise ValueError("Target temperature exceeds declared design maximum.")
159
+ return self
160
+
161
+
162
+ class ThermalEdge(DomainModel):
163
+ """A heat-transfer design edge, optionally with measured/effective R or G."""
164
+
165
+ edge_id: Text
166
+ source_node_id: Text
167
+ target_node_id: Text
168
+ mechanism: Literal["lumped", "conduction", "convection", "radiation"]
169
+ resistance: ThermalQuantity | None = None
170
+ conductance: ThermalQuantity | None = None
171
+ claim: ThermalClaim = Field(default_factory=ThermalClaim)
172
+
173
+ @model_validator(mode="after")
174
+ def check_transfer(self) -> "ThermalEdge":
175
+ """A single edge may not have conflicting resistance descriptions."""
176
+ if self.source_node_id == self.target_node_id:
177
+ raise ValueError("Thermal transfer endpoints must differ.")
178
+ if self.resistance is not None and self.resistance.kind != "resistance":
179
+ raise ValueError("Thermal resistance must use K/W.")
180
+ if self.conductance is not None and self.conductance.kind != "conductance":
181
+ raise ValueError("Thermal conductance must use W/K.")
182
+ if self.resistance is not None and self.conductance is not None:
183
+ raise ValueError("Declare resistance or conductance, not both.")
184
+ return self
185
+
186
+
187
+ class ThermalBoundary(DomainModel):
188
+ """A fixed temperature, prescribed heat magnitude, or insulated condition."""
189
+
190
+ boundary_id: Text
191
+ node_id: Text
192
+ kind: Literal["fixed_temperature", "prescribed_heat", "adiabatic"]
193
+ quantity: ThermalQuantity | None = None
194
+ claim: ThermalClaim = Field(default_factory=ThermalClaim)
195
+
196
+ @model_validator(mode="after")
197
+ def check_boundary(self) -> "ThermalBoundary":
198
+ """Reject contradictory boundary field/unit combinations."""
199
+ wanted = {"fixed_temperature": "temperature", "prescribed_heat": "heat_rate"}
200
+ if self.kind == "adiabatic" and self.quantity is not None:
201
+ raise ValueError("Adiabatic boundary cannot specify a heat or temperature quantity.")
202
+ if self.kind in wanted and self.quantity is not None and self.quantity.kind != wanted[self.kind]:
203
+ raise ValueError("Thermal boundary quantity kind does not match its boundary.")
204
+ return self
205
+
206
+
207
+ class ThermalSourceReference(DomainModel):
208
+ """Pinned external engineering input, not copied domain semantics."""
209
+
210
+ domain: Literal["chemical", "process", "electrical", "fluidic", "mechanical"]
211
+ artifact_id: Text
212
+ entity_id: Text
213
+ schema_version: Text
214
+ revision: int = Field(ge=1)
215
+ sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
216
+ port_id: Text | None = None
217
+ model_version: Text | None = None
218
+
219
+
220
+ class ThermalLoad(DomainModel):
221
+ """A signed-by-role heat source/sink; the magnitude may be unknown."""
222
+
223
+ load_id: Text
224
+ node_id: Text
225
+ direction: Literal["source", "sink"]
226
+ heat_rate: ThermalQuantity | None = None
227
+ origin: Literal["illustrative", "electrical", "chemical_reaction", "process", "fluidic"] = "illustrative"
228
+ references: list[ThermalSourceReference] = Field(default_factory=list)
229
+ calculation_model: Text | None = None
230
+ claim: ThermalClaim = Field(default_factory=ThermalClaim)
231
+
232
+ @model_validator(mode="after")
233
+ def verify_heat_source(self) -> "ThermalLoad":
234
+ """A chemical heat duty needs a supported chemistry and extent/rate input."""
235
+ if self.heat_rate is not None and self.heat_rate.kind != "heat_rate":
236
+ raise ValueError("Thermal load requires heat-rate magnitude.")
237
+ kinds = {item.domain for item in self.references}
238
+ expected = {"electrical": "electrical", "process": "process", "fluidic": "fluidic"}
239
+ if self.origin in expected and self.heat_rate is not None and expected[self.origin] not in kinds:
240
+ raise ValueError(f"Explicit {self.origin} heat requires a pinned {expected[self.origin]} input.")
241
+ if self.origin == "chemical_reaction" and self.heat_rate is not None:
242
+ if not {"chemical", "process"} <= kinds or not self.calculation_model:
243
+ raise ValueError("Reaction heat requires chemical and process references plus model identity.")
244
+ return self
245
+
246
+
247
+ class ThermalProperty(DomainModel):
248
+ """A bounded, evidence-traceable thermophysical property claim."""
249
+
250
+ property_id: Text
251
+ name: Text
252
+ quantity: ThermalQuantity
253
+ min_temperature: ThermalQuantity | None = None
254
+ max_temperature: ThermalQuantity | None = None
255
+ claim: ThermalClaim = Field(default_factory=ThermalClaim)
256
+
257
+ @model_validator(mode="after")
258
+ def check_interval(self) -> "ThermalProperty":
259
+ """Validate an optional absolute-temperature applicability interval."""
260
+ for item in (self.min_temperature, self.max_temperature):
261
+ if item is not None and item.kind != "temperature":
262
+ raise ValueError("Thermal-property validity range uses absolute temperatures.")
263
+ if self.min_temperature is not None and self.max_temperature is not None:
264
+ lo = self.min_temperature.value if self.min_temperature.unit == "K" else self.min_temperature.value + 273.15
265
+ hi = self.max_temperature.value if self.max_temperature.unit == "K" else self.max_temperature.value + 273.15
266
+ if lo > hi:
267
+ raise ValueError("Thermal-property applicability interval is inverted.")
268
+ return self
269
+
270
+
271
+ class SteadyStateCase(DomainModel):
272
+ """A request for the bounded, explicitly versioned one-zone evaluator."""
273
+
274
+ case_id: Text
275
+ zone_node_id: Text
276
+ ambient_node_id: Text
277
+ edge_id: Text
278
+ load_ids: list[Text] = Field(min_length=1)
279
+ model: Literal["lumped-resistance"] = "lumped-resistance"
280
+ model_version: Literal["1.0"] = "1.0"
281
+ tolerance_w: float = Field(1e-9, gt=0)
282
+
283
+
284
+ class ThermalIR(DomainDocument):
285
+ """Thermal engineering design envelope; valid without any other domain."""
286
+
287
+ domain: Literal["thermal"] = "thermal"
288
+ schema_version: Literal["1.0"] = "1.0"
289
+ nodes: list[ThermalNode] = Field(min_length=1)
290
+ edges: list[ThermalEdge] = Field(default_factory=list)
291
+ boundaries: list[ThermalBoundary] = Field(default_factory=list)
292
+ loads: list[ThermalLoad] = Field(default_factory=list)
293
+ properties: list[ThermalProperty] = Field(default_factory=list)
294
+ cases: list[SteadyStateCase] = Field(default_factory=list)
295
+ evidence: list[ThermalEvidence] = Field(default_factory=list)
296
+
297
+ @model_validator(mode="after")
298
+ def check_local_topology(self) -> "ThermalIR":
299
+ """Keep referential/structural validation separate from solver readiness."""
300
+ collections = [
301
+ ([item.node_id for item in self.nodes], "node"),
302
+ ([item.edge_id for item in self.edges], "edge"),
303
+ ([item.boundary_id for item in self.boundaries], "boundary"),
304
+ ([item.load_id for item in self.loads], "load"),
305
+ ([item.property_id for item in self.properties], "thermal property"),
306
+ ([item.case_id for item in self.cases], "case"),
307
+ ([item.source_id for item in self.evidence], "source"),
308
+ ]
309
+ for values, label in collections:
310
+ unique(values, f"thermal {label} ID")
311
+ unique([value for values, _ in collections[:-1] for value in values], "thermal entity ID")
312
+ nodes = {item.node_id: item for item in self.nodes}
313
+ edges = {item.edge_id: item for item in self.edges}
314
+ loads = {item.load_id: item for item in self.loads}
315
+ sources = {item.source_id for item in self.evidence}
316
+ claims = [item.claim for item in self.edges + self.boundaries + self.loads + self.properties]
317
+ quantities = (
318
+ [q for node in self.nodes for q in (
319
+ node.capacity, node.initial_temperature, node.target_temperature,
320
+ node.maximum_temperature) if q is not None] +
321
+ [q for edge in self.edges for q in (
322
+ edge.resistance, edge.conductance) if q is not None] +
323
+ [load.heat_rate for load in self.loads if load.heat_rate is not None] +
324
+ [item.quantity for item in self.boundaries if item.quantity is not None] +
325
+ [q for item in self.properties for q in (
326
+ item.quantity, item.min_temperature, item.max_temperature) if q is not None]
327
+ )
328
+ claims.extend(q.claim for q in quantities)
329
+ for claim in claims:
330
+ if set(claim.source_ids) - sources:
331
+ raise ValueError("Thermal claim references an unknown evidence source.")
332
+ for item in self.edges:
333
+ if item.source_node_id not in nodes or item.target_node_id not in nodes:
334
+ raise ValueError(f"Thermal edge '{item.edge_id}' references an unknown node.")
335
+ for item in self.boundaries:
336
+ if item.node_id not in nodes:
337
+ raise ValueError(f"Thermal boundary '{item.boundary_id}' references an unknown node.")
338
+ for item in self.loads:
339
+ if item.node_id not in nodes:
340
+ raise ValueError(f"Thermal load '{item.load_id}' references an unknown node.")
341
+ for item in self.cases:
342
+ if item.zone_node_id not in nodes or item.ambient_node_id not in nodes:
343
+ raise ValueError("Steady-state case references an unknown node.")
344
+ if item.zone_node_id == item.ambient_node_id:
345
+ raise ValueError("Steady-state zone and ambient must differ.")
346
+ if item.edge_id not in edges:
347
+ raise ValueError("Steady-state case references an unknown transfer edge.")
348
+ if set(item.load_ids) - set(loads):
349
+ raise ValueError("Steady-state case references an unknown thermal load.")
350
+ unique(item.load_ids, "steady-state load ID")
351
+ boundaries: dict[str, set[str]] = {}
352
+ for item in self.boundaries:
353
+ active = boundaries.setdefault(item.node_id, set())
354
+ if item.kind in active:
355
+ raise ValueError("Duplicate thermal boundary condition at node.")
356
+ active.add(item.kind)
357
+ if "adiabatic" in active and len(active) > 1:
358
+ raise ValueError("Adiabatic boundary conflicts with another boundary.")
359
+ if "fixed_temperature" in active and "prescribed_heat" in active:
360
+ raise ValueError("Fixed temperature conflicts with prescribed heat at node.")
361
+ return self
@@ -0,0 +1,175 @@
1
+ """Bounded, auditable steady-state thermal screening; never CFD or FEA.
2
+
3
+ Only one lumped zone connected to one fixed-temperature ambient via exactly
4
+ one declared lumped thermal resistance/conductance is supported in v1. All
5
+ other networks may be valid designs without a supported numeric prediction.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from decimal import Decimal
11
+ from typing import Literal
12
+
13
+ from pydantic import Field
14
+
15
+ from forma_core.domains.base import DomainModel, Finding, fingerprint
16
+ from .models import SteadyStateCase, ThermalIR, ThermalQuantity
17
+
18
+
19
+ class ThermalEvaluation(DomainModel):
20
+ """A calculation receipt with explicit coverage and input identity."""
21
+
22
+ case_id: str
23
+ model: str
24
+ model_version: str
25
+ status: Literal["pass", "fail", "unknown", "unsupported"]
26
+ input_digest: str
27
+ zone_temperature_kelvin: str | None = None
28
+ zone_temperature_celsius: str | None = None
29
+ ambient_temperature_kelvin: str | None = None
30
+ net_heat_w: str | None = None
31
+ transferred_heat_w: str | None = None
32
+ residual_w: str | None = None
33
+ message: str
34
+
35
+
36
+ class ThermalAnalysis(DomainModel):
37
+ """Pure design-time report, not an operational or compliance decision."""
38
+
39
+ results: list[ThermalEvaluation] = Field(default_factory=list)
40
+
41
+
42
+ def temperature_kelvin(quantity: ThermalQuantity) -> Decimal:
43
+ """Convert an absolute temperature to kelvin, not an interval."""
44
+ if quantity.kind != "temperature":
45
+ raise ValueError("Expected an absolute temperature.")
46
+ value = Decimal(str(quantity.value))
47
+ return value if quantity.unit == "K" else value + Decimal("273.15")
48
+
49
+
50
+ def heat_watts(quantity: ThermalQuantity) -> Decimal:
51
+ """Convert a heat-rate magnitude to watts with explicit dimensional check."""
52
+ if quantity.kind != "heat_rate":
53
+ raise ValueError("Expected heat rate.")
54
+ magnitude = Decimal(str(quantity.value))
55
+ return magnitude if quantity.unit == "W" else magnitude * Decimal("1000")
56
+
57
+
58
+ def effective_resistance(edge: object) -> Decimal | None:
59
+ """Return explicit effective K/W or None when transfer data are missing."""
60
+ resistance = getattr(edge, "resistance", None)
61
+ if resistance is not None:
62
+ return Decimal(str(resistance.value))
63
+ conductance = getattr(edge, "conductance", None)
64
+ if conductance is not None:
65
+ return Decimal(1) / Decimal(str(conductance.value))
66
+ return None
67
+
68
+
69
+ def evaluate_case(document: ThermalIR, case: SteadyStateCase) -> ThermalEvaluation:
70
+ """Evaluate a single-zone lumped-resistance request with exact decimal input.
71
+
72
+ Source heat is positive and sink heat negative. The one-zone steady balance
73
+ is Q_net - (T_zone - T_ambient)/R = 0, so T_zone = T_ambient + Q_net * R.
74
+ Changing a selected input invalidates the receipt digest; unrelated
75
+ artifacts are not included.
76
+ """
77
+ node = next(n for n in document.nodes if n.node_id == case.zone_node_id)
78
+ ambient = next(n for n in document.nodes if n.node_id == case.ambient_node_id)
79
+ edge = next(e for e in document.edges if e.edge_id == case.edge_id)
80
+ loads = [next(load for load in document.loads if load.load_id == load_id)
81
+ for load_id in case.load_ids]
82
+ boundaries = [item for item in document.boundaries
83
+ if item.node_id in {case.zone_node_id, case.ambient_node_id}]
84
+ input_digest = fingerprint({
85
+ "case": case.model_dump(mode="json"),
86
+ "zone": node.model_dump(mode="json"),
87
+ "ambient": ambient.model_dump(mode="json"),
88
+ "edge": edge.model_dump(mode="json"),
89
+ "loads": [item.model_dump(mode="json") for item in loads],
90
+ "boundaries": [item.model_dump(mode="json") for item in boundaries],
91
+ })
92
+
93
+ def outcome(status: Literal["pass", "fail", "unknown", "unsupported"],
94
+ message: str, **kwargs: str) -> ThermalEvaluation:
95
+ """Create one stable, version-pinned screening receipt."""
96
+ return ThermalEvaluation(case_id=case.case_id, model=case.model,
97
+ model_version=case.model_version,
98
+ input_digest=input_digest, status=status,
99
+ message=message, **kwargs)
100
+
101
+ if node.kind == "boundary" or ambient.kind != "boundary":
102
+ return outcome("unsupported", "A supported screening case requires a zone/body and a boundary node.")
103
+ if set((edge.source_node_id, edge.target_node_id)) != {case.zone_node_id, case.ambient_node_id}:
104
+ return outcome("unsupported", "Selected edge is not the zone-to-ambient connection.")
105
+ if edge.mechanism != "lumped":
106
+ return outcome("unsupported", "Only an explicitly lumped resistance/conductance is evaluated in v1.")
107
+ if len([e for e in document.edges
108
+ if case.zone_node_id in (e.source_node_id, e.target_node_id)]) != 1:
109
+ return outcome("unsupported", "Additional thermal connections require a network solver.")
110
+ if any(b.node_id == case.zone_node_id and b.kind == "fixed_temperature" for b in boundaries):
111
+ return outcome("unsupported", "A fixed zone temperature is not solved by the one-zone model.")
112
+ ambient_conditions = [b for b in boundaries
113
+ if b.node_id == case.ambient_node_id and b.kind == "fixed_temperature"]
114
+ if len(ambient_conditions) != 1 or ambient_conditions[0].quantity is None:
115
+ return outcome("unknown", "Fixed ambient temperature is missing.")
116
+ if any(b.kind == "prescribed_heat" for b in boundaries):
117
+ return outcome("unsupported", "Prescribed boundary heat is not part of the one-zone evaluator.")
118
+ if any(item.heat_rate is None for item in loads):
119
+ return outcome("unknown", "A selected thermal load has unknown power; no zero is inferred.")
120
+ if any(item.node_id != case.zone_node_id for item in loads):
121
+ return outcome("unsupported", "A selected thermal load is outside the zone.")
122
+ resistance = effective_resistance(edge)
123
+ if resistance is None:
124
+ return outcome("unknown", "Effective thermal resistance/conductance is missing.")
125
+ ambient_k = temperature_kelvin(ambient_conditions[0].quantity)
126
+ net = sum((heat_watts(item.heat_rate) *
127
+ (Decimal(1) if item.direction == "source" else Decimal(-1))
128
+ for item in loads if item.heat_rate is not None), Decimal(0))
129
+ zone_k = ambient_k + net * resistance
130
+ if zone_k < 0:
131
+ return outcome("fail", "Predicted zone temperature is below absolute zero.",
132
+ ambient_temperature_kelvin=str(ambient_k), net_heat_w=str(net))
133
+ if node.maximum_temperature is not None:
134
+ maximum_k = temperature_kelvin(node.maximum_temperature)
135
+ if zone_k > maximum_k:
136
+ return outcome(
137
+ "fail", "Predicted screening temperature exceeds the declared design maximum; "
138
+ "this is not a legal or safety qualification.",
139
+ ambient_temperature_kelvin=str(ambient_k),
140
+ zone_temperature_kelvin=str(zone_k),
141
+ zone_temperature_celsius=str(zone_k - Decimal("273.15")),
142
+ net_heat_w=str(net),
143
+ )
144
+ transferred = (zone_k - ambient_k) / resistance
145
+ residual = net - transferred
146
+ result = "pass" if abs(residual) <= Decimal(str(case.tolerance_w)) else "fail"
147
+ return outcome(
148
+ result,
149
+ "Lumped one-zone energy balance satisfied; screening result is not a safety qualification."
150
+ if result == "pass" else "Explicit one-zone energy balance failed.",
151
+ ambient_temperature_kelvin=str(ambient_k),
152
+ zone_temperature_kelvin=str(zone_k),
153
+ zone_temperature_celsius=str(zone_k - Decimal("273.15")),
154
+ net_heat_w=str(net),
155
+ transferred_heat_w=str(transferred),
156
+ residual_w=str(residual),
157
+ )
158
+
159
+
160
+ def analyze_thermal(document: ThermalIR) -> ThermalAnalysis:
161
+ """Evaluate only explicitly requested, bounded thermal design cases."""
162
+ return ThermalAnalysis(results=[evaluate_case(document, case) for case in document.cases])
163
+
164
+
165
+ def validate_thermal(document: ThermalIR) -> list[Finding]:
166
+ """Local validation remains separate from externally required source checks."""
167
+ findings: list[Finding] = []
168
+ for result in analyze_thermal(document).results:
169
+ if result.status != "pass":
170
+ findings.append(Finding(
171
+ code=f"thermal_{result.status}", location=result.case_id,
172
+ severity="error" if result.status == "fail" else "warning",
173
+ message=result.message,
174
+ ))
175
+ return findings