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,1006 @@
1
+ from __future__ import annotations
2
+
3
+ import base64
4
+ from dataclasses import dataclass
5
+ import json
6
+ import logging
7
+ from forma_core.config import config
8
+ import re
9
+ import shutil
10
+ import subprocess
11
+ import tempfile
12
+ import urllib.error
13
+ import urllib.parse
14
+ import urllib.request
15
+ from pathlib import Path
16
+ from typing import Any, Dict, List, Optional, Protocol
17
+
18
+ from pydantic import BaseModel, Field, field_validator
19
+
20
+ from forma_core.workspaces.projects.iteration import compact_hardware_ir_for_iteration, coerce_hardware_ir
21
+ from forma_core.llm import LLMProviderConfigError, LLMProviderOutputError
22
+ from forma_core.workspaces.projects.models import HardwareIntermediateRepresentation
23
+ from forma_core.workspaces.projects.objects import normalize_project_namespace
24
+
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+ DEFAULT_FIREWORKS_BASE_URL = "https://api.fireworks.ai/inference/v1"
29
+ DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL_SLUG = "qwen3-omni-30b-a3b-instruct"
30
+ DEFAULT_FIREWORKS_FRAME_REVIEW_MODEL_SLUG = "kimi-k2p6"
31
+ DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL_SLUG = DEFAULT_FIREWORKS_FRAME_REVIEW_MODEL_SLUG
32
+ DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL = f"accounts/fireworks/models/{DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL_SLUG}"
33
+ DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL = f"accounts/fireworks/models/{DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL_SLUG}"
34
+ FIREWORKS_VIDEO_REVIEW_NATIVE_MODELS = {
35
+ "qwen3-omni-30b-a3b-instruct": "video-audio-text",
36
+ "molmo2-4b": "video-text",
37
+ "molmo2-8b": "video-text",
38
+ }
39
+ FIREWORKS_VIDEO_REVIEW_FRAME_MODELS = {
40
+ "kimi-k2p6": "image-text",
41
+ }
42
+ DEFAULT_FIREWORKS_TIMEOUT_SECONDS = 180.0
43
+ DEFAULT_VIDEO_REVIEW_MAX_FRAMES = 8
44
+ DEFAULT_VIDEO_REVIEW_MAX_SECONDS = 60
45
+ DEFAULT_VIDEO_REVIEW_NATIVE_FPS = 1.0
46
+ DEFAULT_VIDEO_REVIEW_NATIVE_HEIGHT = 360
47
+ DEFAULT_VIDEO_REVIEW_MAX_MEDIA_BYTES = 10_000_000
48
+ DEFAULT_VIDEO_REVIEW_INPUT_MODE = "auto"
49
+ VIDEO_REVIEW_ALLOWED_NAMESPACES = {
50
+ "product.overview",
51
+ "product.electrical",
52
+ "product.mech",
53
+ "product.validation",
54
+ "product.assembly",
55
+ "project.docs",
56
+ "project.history",
57
+ }
58
+
59
+
60
+ class VideoCoherenceIssue(BaseModel):
61
+ severity: str = Field("warning", description="Issue severity: critical, warning, or info.")
62
+ category: str = Field("continuity", description="Issue type such as coherence, logic, continuity, rendering, or assembly.")
63
+ frame_reference: Optional[str] = Field(None, description="Frame or time reference where the issue is visible.")
64
+ description: str = Field(..., description="What is wrong or incoherent in the video.")
65
+ evidence: str = Field("", description="Visual evidence from the sampled video frames.")
66
+ suggested_correction: str = Field("", description="Concrete change to make in the project iteration.")
67
+
68
+ @field_validator("severity", "category", mode="before")
69
+ @classmethod
70
+ def normalize_short_text(cls, value: Any) -> Any:
71
+ if isinstance(value, str):
72
+ return value.strip().lower().replace("_", " ") or None
73
+ return value
74
+
75
+
76
+ class VideoIterationReview(BaseModel):
77
+ summary: str = Field(..., description="Short review of the video and project coherence.")
78
+ coherence_score: float = Field(0.0, ge=0.0, le=1.0, description="0-1 assessment of video/project coherence.")
79
+ needs_iteration: bool = Field(True, description="Whether the project should be revised.")
80
+ target_namespace: str = Field("product.mech", description="Forma namespace best suited for the correction.")
81
+ issues: List[VideoCoherenceIssue] = Field(default_factory=list)
82
+ iteration_instruction: str = Field(..., description="Natural-language instruction for Forma's project iterator.")
83
+
84
+ @field_validator("target_namespace", mode="before")
85
+ @classmethod
86
+ def normalize_target_namespace(cls, value: Any) -> str:
87
+ normalized = normalize_project_namespace(str(value or "product.mech"))
88
+ if normalized in VIDEO_REVIEW_ALLOWED_NAMESPACES:
89
+ return normalized
90
+ return "product.mech"
91
+
92
+ @field_validator("iteration_instruction", "summary", mode="before")
93
+ @classmethod
94
+ def require_non_empty_text(cls, value: Any) -> str:
95
+ text = str(value or "").strip()
96
+ if not text:
97
+ raise ValueError("Video review text fields must not be empty.")
98
+ return text
99
+
100
+
101
+ class VideoReviewClient(Protocol):
102
+ model: str
103
+
104
+ def review_video(
105
+ self,
106
+ current_ir: HardwareIntermediateRepresentation,
107
+ *,
108
+ video_url: str,
109
+ original_prompt: Optional[str] = None,
110
+ project_id: Optional[str] = None,
111
+ ) -> VideoIterationReview:
112
+ ...
113
+
114
+
115
+ @dataclass(frozen=True)
116
+ class FireworksPreparedVideo:
117
+ video_data_url: str
118
+ audio_data_url: Optional[str] = None
119
+
120
+
121
+ def _env(name: str, default: Optional[str] = None) -> Optional[str]:
122
+ value = config.get(name)
123
+ if value is None:
124
+ return default
125
+ stripped = value.strip()
126
+ return stripped if stripped else default
127
+
128
+
129
+ def _env_float(name: str, default: float) -> float:
130
+ raw_value = _env(name)
131
+ if raw_value is None:
132
+ return default
133
+ try:
134
+ return float(raw_value)
135
+ except ValueError:
136
+ return default
137
+
138
+
139
+ def _env_bool(name: str, default: bool) -> bool:
140
+ raw_value = _env(name)
141
+ if raw_value is None:
142
+ return default
143
+ return raw_value.strip().lower() in {"1", "true", "yes", "on"}
144
+
145
+
146
+ def _env_int(name: str, default: int, minimum: int, maximum: int) -> int:
147
+ raw_value = _env(name)
148
+ if raw_value is None:
149
+ return default
150
+ try:
151
+ return max(minimum, min(maximum, int(raw_value)))
152
+ except ValueError:
153
+ return default
154
+
155
+
156
+ def _validate_http_video_url(video_url: str) -> str:
157
+ url = str(video_url or "").strip()
158
+ parsed = urllib.parse.urlparse(url)
159
+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:
160
+ raise ValueError("video_url must be an http(s) URL.")
161
+ return url
162
+
163
+
164
+ def _fireworks_video_model_slug(model: str) -> str:
165
+ base_model = str(model or "").split("#", 1)[0].strip().strip("/")
166
+ if not base_model:
167
+ return DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL_SLUG
168
+ return base_model.rsplit("/", 1)[-1]
169
+
170
+
171
+ def _fireworks_model_path_for_slug(slug_or_model: str) -> str:
172
+ normalized = str(slug_or_model or "").strip()
173
+ if not normalized:
174
+ normalized = DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL_SLUG
175
+ if normalized.startswith("accounts/"):
176
+ return normalized
177
+ return f"accounts/fireworks/models/{normalized}"
178
+
179
+
180
+ def _resolve_fireworks_video_review_model(
181
+ model: Optional[str],
182
+ *,
183
+ account_id: Optional[str],
184
+ deployment_id: Optional[str],
185
+ ) -> str:
186
+ raw_model = str(model or DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL).strip()
187
+ if "#" in raw_model:
188
+ return raw_model
189
+ if account_id and deployment_id:
190
+ slug = _fireworks_video_model_slug(raw_model)
191
+ return f"accounts/{account_id}/models/{slug}#accounts/{account_id}/deployments/{deployment_id}"
192
+ return _fireworks_model_path_for_slug(raw_model)
193
+
194
+
195
+ def _fireworks_video_model_requires_deployment(model: str) -> bool:
196
+ return _fireworks_video_model_slug(model) in FIREWORKS_VIDEO_REVIEW_NATIVE_MODELS
197
+
198
+
199
+ def _fireworks_video_model_supports_audio(model: str) -> bool:
200
+ return FIREWORKS_VIDEO_REVIEW_NATIVE_MODELS.get(_fireworks_video_model_slug(model)) == "video-audio-text"
201
+
202
+
203
+ def _extract_json_document(text: str) -> Dict[str, Any]:
204
+ stripped = text.strip()
205
+ if stripped.startswith("```"):
206
+ lines = stripped.splitlines()
207
+ if lines and lines[0].startswith("```"):
208
+ lines = lines[1:]
209
+ if lines and lines[-1].startswith("```"):
210
+ lines = lines[:-1]
211
+ stripped = "\n".join(lines).strip()
212
+
213
+ try:
214
+ parsed = json.loads(stripped)
215
+ except json.JSONDecodeError:
216
+ decoder = json.JSONDecoder()
217
+ parsed = None
218
+ for index, char in enumerate(stripped):
219
+ if char not in {"{", "["}:
220
+ continue
221
+ try:
222
+ parsed, _ = decoder.raw_decode(stripped[index:])
223
+ break
224
+ except json.JSONDecodeError:
225
+ continue
226
+ if parsed is None:
227
+ raise
228
+ if not isinstance(parsed, dict):
229
+ raise ValueError("Video review response must be a JSON object.")
230
+ return parsed
231
+
232
+
233
+ def _response_preview(value: Any, *, limit: int = 1200) -> str:
234
+ text = str(value or "").strip()
235
+ if not text:
236
+ return "<empty>"
237
+ single_line = " ".join(text.split())
238
+ return single_line[:limit] + ("..." if len(single_line) > limit else "")
239
+
240
+
241
+ def _message_content_text(message: Dict[str, Any]) -> str:
242
+ for key in ("content", "reasoning_content", "reasoning", "analysis"):
243
+ value = message.get(key)
244
+ if not value:
245
+ continue
246
+ if isinstance(value, list):
247
+ parts = []
248
+ for item in value:
249
+ if isinstance(item, dict):
250
+ parts.append(str(item.get("text") or item.get("content") or item))
251
+ else:
252
+ parts.append(str(item))
253
+ text = "\n".join(parts).strip()
254
+ else:
255
+ text = str(value).strip()
256
+ if text:
257
+ return text
258
+ return ""
259
+
260
+
261
+ def _review_finding_sentences(text: str) -> List[str]:
262
+ normalized = re.sub(r"\s+", " ", str(text or "")).strip()
263
+ if not normalized:
264
+ return []
265
+ sentences = re.split(r"(?<=[.!?])\s+", normalized)
266
+ meta_prefixes = (
267
+ "the user wants me",
268
+ "i need to",
269
+ "i should",
270
+ "first, let me",
271
+ "let me",
272
+ "we need to",
273
+ "the task is",
274
+ )
275
+ finding_sentences = []
276
+ for sentence in sentences:
277
+ cleaned = sentence.strip(" -\t\n")
278
+ if not cleaned:
279
+ continue
280
+ lowered = cleaned.lower()
281
+ if any(lowered.startswith(prefix) for prefix in meta_prefixes):
282
+ continue
283
+ finding_sentences.append(cleaned)
284
+ return finding_sentences
285
+
286
+
287
+ def _distill_unstructured_review_text(text: str, *, limit: int = 1400) -> str:
288
+ sentences = _review_finding_sentences(text)
289
+ if not sentences:
290
+ return ""
291
+ issue_keywords = (
292
+ "mismatch",
293
+ "inconsistent",
294
+ "inconsistency",
295
+ "does not match",
296
+ "doesn't match",
297
+ "do not match",
298
+ "not match",
299
+ "issue",
300
+ "problem",
301
+ "concern",
302
+ "however",
303
+ "but",
304
+ "instead",
305
+ "wrong",
306
+ "not visible",
307
+ "not shown",
308
+ "missing",
309
+ "video shows",
310
+ "frames show",
311
+ "looks like",
312
+ "appears to",
313
+ )
314
+ selected = [sentence for sentence in sentences if any(keyword in sentence.lower() for keyword in issue_keywords)]
315
+ if not selected:
316
+ selected = sentences
317
+ distilled = " ".join(selected[:6]).strip()
318
+ return _response_preview(distilled, limit=limit)
319
+
320
+
321
+ def _unstructured_review_target_namespace(text: str) -> str:
322
+ lowered = str(text or "").lower()
323
+
324
+ visual_keywords = (
325
+ "frame",
326
+ "video",
327
+ "enclosure",
328
+ "placement",
329
+ "mechanical",
330
+ "display",
331
+ "lcd",
332
+ "oled",
333
+ "screen",
334
+ "motor",
335
+ "servo",
336
+ "printer",
337
+ "gantry",
338
+ "nozzle",
339
+ "bed",
340
+ "gear",
341
+ "impeller",
342
+ "visual",
343
+ "looks like",
344
+ "appears",
345
+ "shown",
346
+ "visible",
347
+ )
348
+ electrical_keywords = (
349
+ "wire",
350
+ "wiring",
351
+ "net",
352
+ "netlist",
353
+ "pin",
354
+ "gpio",
355
+ "voltage",
356
+ "short",
357
+ "ground",
358
+ "circuit",
359
+ "electrical connection",
360
+ "power rail",
361
+ )
362
+ if any(keyword in lowered for keyword in visual_keywords):
363
+ return "product.mech"
364
+ if any(keyword in lowered for keyword in electrical_keywords):
365
+ return "product.electrical"
366
+ return "project.docs"
367
+
368
+
369
+ def _review_from_unstructured_text(text: str, *, model: str) -> Optional[VideoIterationReview]:
370
+ preview = _distill_unstructured_review_text(text, limit=1400)
371
+ if not preview or preview == "<empty>":
372
+ return None
373
+ namespace = _unstructured_review_target_namespace(preview)
374
+ score = 0.3 if any(keyword in preview.lower() for keyword in ("mismatch", "does not match", "not match", "inconsistent")) else 0.5
375
+ return VideoIterationReview(
376
+ summary=f"Video review findings from Fireworks {model}: {preview}",
377
+ coherence_score=score,
378
+ needs_iteration=True,
379
+ target_namespace=namespace,
380
+ issues=[
381
+ VideoCoherenceIssue(
382
+ severity="warning",
383
+ category="coherence",
384
+ frame_reference="sampled video review",
385
+ description="The video review identified coherence or continuity findings in unstructured text.",
386
+ evidence=preview,
387
+ suggested_correction="Revise the targeted project namespace so the generated video and HardwareIntermediateRepresentation describe the same physical build.",
388
+ )
389
+ ],
390
+ iteration_instruction=(
391
+ "Apply the Fireworks video review findings to make the HardwareIntermediateRepresentation and generated video coherent. "
392
+ f"Target {namespace}. Findings: {preview}"
393
+ ),
394
+ )
395
+
396
+
397
+ def _fireworks_http_error_message(*, status_code: int, body: str, model: str) -> str:
398
+ raw_body = (body or "").strip()
399
+ provider_message = raw_body[:800] if raw_body else "No response body returned."
400
+ provider_code = ""
401
+ request_id = ""
402
+ try:
403
+ parsed = json.loads(raw_body) if raw_body else {}
404
+ except json.JSONDecodeError:
405
+ parsed = {}
406
+ if isinstance(parsed, dict):
407
+ error = parsed.get("error")
408
+ if isinstance(error, dict):
409
+ provider_message = str(error.get("message") or provider_message)
410
+ provider_code = str(error.get("code") or "")
411
+ elif parsed.get("message"):
412
+ provider_message = str(parsed.get("message"))
413
+ request_id = str(parsed.get("request_id") or "")
414
+
415
+ message = f"forma_core.video_review Fireworks video review failed for model {model} with HTTP {status_code}"
416
+ if provider_code:
417
+ message += f" ({provider_code})"
418
+ message += f": {provider_message}"
419
+ if status_code == 404 or provider_code == "NOT_FOUND":
420
+ message += (
421
+ " The model may be unavailable to this Fireworks API key or not deployed; deploy it in Fireworks "
422
+ "or set FIREWORKS_VIDEO_REVIEW_MODEL to a deployed model path."
423
+ )
424
+ if request_id:
425
+ message += f" Fireworks request_id={request_id}."
426
+ return message
427
+
428
+
429
+ def _ffprobe_duration_seconds(video_url: str) -> Optional[float]:
430
+ if not shutil.which("ffprobe"):
431
+ return None
432
+ command = [
433
+ "ffprobe",
434
+ "-v",
435
+ "error",
436
+ "-show_entries",
437
+ "format=duration",
438
+ "-of",
439
+ "default=noprint_wrappers=1:nokey=1",
440
+ video_url,
441
+ ]
442
+ try:
443
+ completed = subprocess.run(command, check=True, capture_output=True, text=True, timeout=30)
444
+ return max(0.0, float(completed.stdout.strip()))
445
+ except Exception:
446
+ return None
447
+
448
+
449
+ def sample_video_frames(video_url: str, *, max_frames: Optional[int] = None) -> List[bytes]:
450
+ """Sample chronological JPEG frames from a video URL for VLM review."""
451
+ url = _validate_http_video_url(video_url)
452
+ frame_count = max_frames or _env_int("FIREWORKS_VIDEO_REVIEW_MAX_FRAMES", DEFAULT_VIDEO_REVIEW_MAX_FRAMES, 1, 16)
453
+ if not shutil.which("ffmpeg"):
454
+ logger.warning("Video self-correction frame sampling is unavailable because ffmpeg is not installed.")
455
+ raise LLMProviderConfigError("ffmpeg is required for video self-correction frame sampling.")
456
+
457
+ duration = _ffprobe_duration_seconds(url)
458
+ fps = 1.0
459
+ if duration and duration > 0:
460
+ fps = min(2.0, max(0.05, frame_count / duration))
461
+ logger.info(
462
+ "Sampling video frames for self-correction: max_frames=%s fps=%.4f duration_seconds=%s",
463
+ frame_count,
464
+ fps,
465
+ f"{duration:.2f}" if duration is not None else "unknown",
466
+ )
467
+
468
+ with tempfile.TemporaryDirectory(prefix="forma-video-review-") as temp_dir:
469
+ output_pattern = str(Path(temp_dir) / "frame-%03d.jpg")
470
+ command = [
471
+ "ffmpeg",
472
+ "-hide_banner",
473
+ "-loglevel",
474
+ "error",
475
+ "-y",
476
+ "-i",
477
+ url,
478
+ "-vf",
479
+ f"fps={fps:.4f},scale=768:-2:force_original_aspect_ratio=decrease",
480
+ "-frames:v",
481
+ str(frame_count),
482
+ "-q:v",
483
+ "4",
484
+ output_pattern,
485
+ ]
486
+ try:
487
+ subprocess.run(command, check=True, capture_output=True, text=True, timeout=120)
488
+ except subprocess.CalledProcessError as exc:
489
+ logger.warning("Video self-correction frame sampling failed: %s", exc.stderr.strip() or exc)
490
+ raise LLMProviderOutputError(f"Could not sample video frames: {exc.stderr.strip() or exc}") from exc
491
+ except subprocess.TimeoutExpired as exc:
492
+ logger.warning("Video self-correction frame sampling timed out.")
493
+ raise LLMProviderOutputError("Timed out while sampling video frames.") from exc
494
+
495
+ frames = [path.read_bytes() for path in sorted(Path(temp_dir).glob("frame-*.jpg")) if path.stat().st_size > 0]
496
+ if not frames:
497
+ logger.warning("Video self-correction frame sampling returned no frames.")
498
+ raise LLMProviderOutputError("Video self-correction could not sample any frames from the video.")
499
+ logger.info("Sampled %s video frames for self-correction.", len(frames[:frame_count]))
500
+ return frames[:frame_count]
501
+
502
+
503
+ def _bounded_float(value: Optional[float], default: float, minimum: float, maximum: float) -> float:
504
+ if value is None:
505
+ return default
506
+ return max(minimum, min(maximum, float(value)))
507
+
508
+
509
+ def _bounded_int(value: Optional[int], default: int, minimum: int, maximum: int) -> int:
510
+ if value is None:
511
+ return default
512
+ return max(minimum, min(maximum, int(value)))
513
+
514
+
515
+ def _run_ffmpeg(command: List[str], *, error_message: str) -> None:
516
+ try:
517
+ subprocess.run(command, check=True, capture_output=True, text=True, timeout=180)
518
+ except subprocess.CalledProcessError as exc:
519
+ raise LLMProviderOutputError(f"{error_message}: {exc.stderr.strip() or exc}") from exc
520
+ except subprocess.TimeoutExpired as exc:
521
+ raise LLMProviderOutputError(f"{error_message}: timed out.") from exc
522
+
523
+
524
+ def prepare_video_for_fireworks_native_review(
525
+ video_url: str,
526
+ *,
527
+ include_audio: bool = True,
528
+ max_seconds: Optional[int] = None,
529
+ fps: Optional[float] = None,
530
+ height: Optional[int] = None,
531
+ max_media_bytes: Optional[int] = None,
532
+ ) -> FireworksPreparedVideo:
533
+ """Transcode a remote video URL into Fireworks native video/audio data URLs."""
534
+ url = _validate_http_video_url(video_url)
535
+ if not shutil.which("ffmpeg"):
536
+ logger.warning("Fireworks native video review is unavailable because ffmpeg is not installed.")
537
+ raise LLMProviderConfigError("ffmpeg is required for Fireworks native video review preprocessing.")
538
+
539
+ duration_seconds = _bounded_int(max_seconds, DEFAULT_VIDEO_REVIEW_MAX_SECONDS, 1, 300)
540
+ video_fps = _bounded_float(fps, DEFAULT_VIDEO_REVIEW_NATIVE_FPS, 0.05, 5.0)
541
+ video_height = _bounded_int(height, DEFAULT_VIDEO_REVIEW_NATIVE_HEIGHT, 144, 1080)
542
+ media_cap = _bounded_int(max_media_bytes, DEFAULT_VIDEO_REVIEW_MAX_MEDIA_BYTES, 100_000, 50_000_000)
543
+
544
+ logger.info(
545
+ "Preparing Fireworks native video input: max_seconds=%s fps=%.3f height=%s include_audio=%s",
546
+ duration_seconds,
547
+ video_fps,
548
+ video_height,
549
+ include_audio,
550
+ )
551
+
552
+ with tempfile.TemporaryDirectory(prefix="forma-fireworks-video-") as temp_dir:
553
+ output_video = Path(temp_dir) / "review-video.mp4"
554
+ video_command = [
555
+ "ffmpeg",
556
+ "-hide_banner",
557
+ "-loglevel",
558
+ "error",
559
+ "-y",
560
+ "-i",
561
+ url,
562
+ "-t",
563
+ str(duration_seconds),
564
+ "-vf",
565
+ f"fps={video_fps:.4f},scale=-2:{video_height}:force_original_aspect_ratio=decrease",
566
+ "-an",
567
+ "-c:v",
568
+ "libx264",
569
+ "-preset",
570
+ "veryfast",
571
+ "-crf",
572
+ "28",
573
+ "-movflags",
574
+ "+faststart",
575
+ str(output_video),
576
+ ]
577
+ _run_ffmpeg(video_command, error_message="Could not prepare video for Fireworks review")
578
+
579
+ video_bytes = output_video.read_bytes()
580
+ if len(video_bytes) > media_cap:
581
+ raise LLMProviderOutputError(
582
+ f"Prepared Fireworks review video is {len(video_bytes)} bytes, above the {media_cap} byte limit. "
583
+ "Lower FIREWORKS_VIDEO_REVIEW_MAX_SECONDS, FIREWORKS_VIDEO_REVIEW_NATIVE_FPS, or FIREWORKS_VIDEO_REVIEW_NATIVE_HEIGHT."
584
+ )
585
+
586
+ audio_data_url: Optional[str] = None
587
+ if include_audio:
588
+ output_audio = Path(temp_dir) / "review-audio.ogg"
589
+ audio_command = [
590
+ "ffmpeg",
591
+ "-hide_banner",
592
+ "-loglevel",
593
+ "error",
594
+ "-y",
595
+ "-i",
596
+ url,
597
+ "-t",
598
+ str(duration_seconds),
599
+ "-vn",
600
+ "-ac",
601
+ "1",
602
+ "-ar",
603
+ "16000",
604
+ "-c:a",
605
+ "libopus",
606
+ "-b:a",
607
+ "24k",
608
+ str(output_audio),
609
+ ]
610
+ try:
611
+ _run_ffmpeg(audio_command, error_message="Could not prepare audio for Fireworks review")
612
+ audio_bytes = output_audio.read_bytes()
613
+ if len(audio_bytes) <= media_cap:
614
+ audio_data_url = f"data:audio/ogg;base64,{base64.b64encode(audio_bytes).decode('ascii')}"
615
+ else:
616
+ logger.warning(
617
+ "Skipping Fireworks review audio because prepared audio is %s bytes, above the %s byte limit.",
618
+ len(audio_bytes),
619
+ media_cap,
620
+ )
621
+ except LLMProviderOutputError as exc:
622
+ logger.info("Skipping Fireworks review audio: %s", exc)
623
+
624
+ logger.info(
625
+ "Prepared Fireworks native video input: video_bytes=%s audio=%s",
626
+ len(video_bytes),
627
+ "yes" if audio_data_url else "no",
628
+ )
629
+ return FireworksPreparedVideo(
630
+ video_data_url=f"data:video/mp4;base64,{base64.b64encode(video_bytes).decode('ascii')}",
631
+ audio_data_url=audio_data_url,
632
+ )
633
+
634
+
635
+ def _image_data_url(image_bytes: bytes) -> str:
636
+ encoded = base64.b64encode(image_bytes).decode("ascii")
637
+ return f"data:image/jpeg;base64,{encoded}"
638
+
639
+
640
+ def _video_review_system_prompt() -> str:
641
+ return (
642
+ "You are Forma's video self-correction reviewer. You inspect generated hardware video evidence "
643
+ "against the current HardwareIntermediateRepresentation. Find visual coherence, physical logic, assembly continuity, camera continuity, "
644
+ "component placement, wiring, enclosure, and documentation issues. Return one valid JSON object only. "
645
+ "Do not include prose, markdown, or hidden reasoning."
646
+ )
647
+
648
+
649
+ def _video_review_user_content(
650
+ current_ir: HardwareIntermediateRepresentation,
651
+ *,
652
+ video_url: str,
653
+ frames: List[bytes],
654
+ original_prompt: Optional[str],
655
+ project_id: Optional[str],
656
+ ) -> List[Dict[str, Any]]:
657
+ compact_ir = compact_hardware_ir_for_iteration(current_ir, max_string_chars=1600)
658
+ instructions = {
659
+ "required_json_shape": {
660
+ "summary": "string",
661
+ "coherence_score": "number between 0 and 1",
662
+ "needs_iteration": "boolean",
663
+ "target_namespace": "one of product.overview, product.electrical, product.mech, product.validation, product.assembly, project.docs, project.history",
664
+ "issues": [
665
+ {
666
+ "severity": "critical|warning|info",
667
+ "category": "coherence|logic|continuity|rendering|assembly|mechanical|electrical",
668
+ "frame_reference": "frame/time reference",
669
+ "description": "specific issue",
670
+ "evidence": "what the frames show",
671
+ "suggested_correction": "project change",
672
+ }
673
+ ],
674
+ "iteration_instruction": "single concise instruction for Forma's project iterator to revise the HardwareIntermediateRepresentation",
675
+ },
676
+ "review_rules": [
677
+ "Do not invent invisible parts. Ground findings in the frames and HardwareIntermediateRepresentation.",
678
+ "Prefer the smallest coherent project iteration.",
679
+ "If the video is mostly correct, write an iteration that records the review and fixes minor documentation/continuity issues.",
680
+ "Mention video continuity evidence in the iteration_instruction.",
681
+ ],
682
+ }
683
+ content: List[Dict[str, Any]] = [
684
+ {
685
+ "type": "text",
686
+ "text": (
687
+ f"Project id: {project_id or (current_ir.assembly_metadata or {}).get('project_id') or 'unknown'}\n"
688
+ f"Original prompt: {original_prompt or 'unknown'}\n"
689
+ f"Video URL: {video_url}\n"
690
+ f"Current HardwareIntermediateRepresentation JSON:\n{json.dumps(compact_ir, indent=2, sort_keys=True)}\n\n"
691
+ f"Instructions:\n{json.dumps(instructions, indent=2, sort_keys=True)}"
692
+ ),
693
+ }
694
+ ]
695
+ for index, frame in enumerate(frames, start=1):
696
+ content.append({"type": "text", "text": f"Chronological sampled frame {index} of {len(frames)}."})
697
+ content.append({"type": "image_url", "image_url": {"url": _image_data_url(frame)}})
698
+ return content
699
+
700
+
701
+ def _video_review_instructions() -> Dict[str, Any]:
702
+ return {
703
+ "required_json_shape": {
704
+ "summary": "string",
705
+ "coherence_score": "number between 0 and 1",
706
+ "needs_iteration": "boolean",
707
+ "target_namespace": "one of product.overview, product.electrical, product.mech, product.validation, product.assembly, project.docs, project.history",
708
+ "issues": [
709
+ {
710
+ "severity": "critical|warning|info",
711
+ "category": "coherence|logic|continuity|rendering|assembly|mechanical|electrical",
712
+ "frame_reference": "frame/time reference",
713
+ "description": "specific issue",
714
+ "evidence": "what the video shows",
715
+ "suggested_correction": "project change",
716
+ }
717
+ ],
718
+ "iteration_instruction": "single concise instruction for Forma's project iterator to revise the HardwareIntermediateRepresentation",
719
+ },
720
+ "review_rules": [
721
+ "Do not invent invisible parts. Ground findings in the video/audio and HardwareIntermediateRepresentation.",
722
+ "Prefer the smallest coherent project iteration.",
723
+ "If the video is mostly correct, write an iteration that records the review and fixes minor documentation/continuity issues.",
724
+ "Mention video continuity evidence in the iteration_instruction.",
725
+ ],
726
+ }
727
+
728
+
729
+ def _video_review_text_prompt(
730
+ current_ir: HardwareIntermediateRepresentation,
731
+ *,
732
+ video_url: str,
733
+ original_prompt: Optional[str],
734
+ project_id: Optional[str],
735
+ ) -> str:
736
+ compact_ir = compact_hardware_ir_for_iteration(current_ir, max_string_chars=1600)
737
+ return (
738
+ f"Project id: {project_id or (current_ir.assembly_metadata or {}).get('project_id') or 'unknown'}\n"
739
+ f"Original prompt: {original_prompt or 'unknown'}\n"
740
+ f"Video URL: {video_url}\n"
741
+ f"Current HardwareIntermediateRepresentation JSON:\n{json.dumps(compact_ir, indent=2, sort_keys=True)}\n\n"
742
+ f"Instructions:\n{json.dumps(_video_review_instructions(), indent=2, sort_keys=True)}"
743
+ )
744
+
745
+
746
+ def _video_review_native_user_content(
747
+ current_ir: HardwareIntermediateRepresentation,
748
+ *,
749
+ video_url: str,
750
+ prepared_video: FireworksPreparedVideo,
751
+ original_prompt: Optional[str],
752
+ project_id: Optional[str],
753
+ ) -> List[Dict[str, Any]]:
754
+ content: List[Dict[str, Any]] = [
755
+ {"type": "video_url", "video_url": {"url": prepared_video.video_data_url}},
756
+ ]
757
+ if prepared_video.audio_data_url:
758
+ content.append({"type": "audio_url", "audio_url": {"url": prepared_video.audio_data_url}})
759
+ content.append(
760
+ {
761
+ "type": "text",
762
+ "text": _video_review_text_prompt(
763
+ current_ir,
764
+ video_url=video_url,
765
+ original_prompt=original_prompt,
766
+ project_id=project_id,
767
+ ),
768
+ }
769
+ )
770
+ return content
771
+
772
+
773
+ class FireworksVideoReviewClient:
774
+ """Fireworks-hosted VLM reviewer for generated project videos."""
775
+
776
+ def __init__(
777
+ self,
778
+ *,
779
+ api_key: Optional[str] = None,
780
+ base_url: Optional[str] = None,
781
+ model: Optional[str] = None,
782
+ account_id: Optional[str] = None,
783
+ deployment_id: Optional[str] = None,
784
+ timeout_seconds: Optional[float] = None,
785
+ max_frames: Optional[int] = None,
786
+ input_mode: Optional[str] = None,
787
+ include_audio: Optional[bool] = None,
788
+ max_seconds: Optional[int] = None,
789
+ native_fps: Optional[float] = None,
790
+ native_height: Optional[int] = None,
791
+ max_media_bytes: Optional[int] = None,
792
+ ) -> None:
793
+ self.api_key = api_key or _env("FIREWORKS_API_KEY") or _env("FIREWORKS_AI_API_KEY")
794
+ self.base_url = (base_url or _env("FIREWORKS_BASE_URL", DEFAULT_FIREWORKS_BASE_URL) or DEFAULT_FIREWORKS_BASE_URL).rstrip("/")
795
+ self.account_id = account_id or _env("FIREWORKS_ACCOUNT_ID") or _env("FIREWORKS_VIDEO_REVIEW_ACCOUNT_ID")
796
+ self.deployment_id = deployment_id or _env("FIREWORKS_VIDEO_REVIEW_DEPLOYMENT_ID") or _env("FIREWORKS_DEPLOYMENT_ID")
797
+ self.timeout_seconds = timeout_seconds or _env_float("FIREWORKS_TIMEOUT_SECONDS", DEFAULT_FIREWORKS_TIMEOUT_SECONDS)
798
+ self.max_frames = max_frames or _env_int("FIREWORKS_VIDEO_REVIEW_MAX_FRAMES", DEFAULT_VIDEO_REVIEW_MAX_FRAMES, 1, 16)
799
+ self.input_mode = (input_mode or _env("FIREWORKS_VIDEO_REVIEW_INPUT_MODE", DEFAULT_VIDEO_REVIEW_INPUT_MODE) or DEFAULT_VIDEO_REVIEW_INPUT_MODE).strip().lower().replace("-", "_")
800
+ if self.input_mode not in {"auto", "native_video", "frames"}:
801
+ self.input_mode = DEFAULT_VIDEO_REVIEW_INPUT_MODE
802
+ requested_model = model or _env("FIREWORKS_VIDEO_REVIEW_MODEL")
803
+ explicit_model_is_native = bool(requested_model) and (
804
+ "#" in str(requested_model) or _fireworks_video_model_requires_deployment(str(requested_model))
805
+ )
806
+ has_native_deployment = bool(self.account_id and self.deployment_id)
807
+ if self.input_mode == "auto":
808
+ if explicit_model_is_native or (has_native_deployment and not requested_model):
809
+ self.input_mode = "native_video"
810
+ requested_model = requested_model or DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL
811
+ else:
812
+ self.input_mode = "frames"
813
+ requested_model = requested_model or DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL
814
+ elif self.input_mode == "native_video":
815
+ requested_model = requested_model or DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL
816
+ else:
817
+ requested_model = requested_model or DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL
818
+ self.model = _resolve_fireworks_video_review_model(
819
+ requested_model,
820
+ account_id=self.account_id if self.input_mode == "native_video" else None,
821
+ deployment_id=self.deployment_id if self.input_mode == "native_video" else None,
822
+ )
823
+ self.include_audio = _fireworks_video_model_supports_audio(self.model) if include_audio is None else include_audio
824
+ if _env("FIREWORKS_VIDEO_REVIEW_INCLUDE_AUDIO") is not None:
825
+ self.include_audio = _env_bool("FIREWORKS_VIDEO_REVIEW_INCLUDE_AUDIO", self.include_audio)
826
+ self.max_seconds = max_seconds or _env_int("FIREWORKS_VIDEO_REVIEW_MAX_SECONDS", DEFAULT_VIDEO_REVIEW_MAX_SECONDS, 1, 300)
827
+ self.native_fps = native_fps or _env_float("FIREWORKS_VIDEO_REVIEW_NATIVE_FPS", DEFAULT_VIDEO_REVIEW_NATIVE_FPS)
828
+ self.native_height = native_height or _env_int("FIREWORKS_VIDEO_REVIEW_NATIVE_HEIGHT", DEFAULT_VIDEO_REVIEW_NATIVE_HEIGHT, 144, 1080)
829
+ self.max_media_bytes = max_media_bytes or _env_int("FIREWORKS_VIDEO_REVIEW_MAX_MEDIA_BYTES", DEFAULT_VIDEO_REVIEW_MAX_MEDIA_BYTES, 100_000, 50_000_000)
830
+
831
+ @property
832
+ def configured(self) -> bool:
833
+ return bool(self.api_key)
834
+
835
+ @property
836
+ def deployment_configured(self) -> bool:
837
+ return "#" in self.model or not _fireworks_video_model_requires_deployment(self.model)
838
+
839
+ def get_debug_config(self) -> Dict[str, Any]:
840
+ reason = None
841
+ if not self.configured:
842
+ reason = "Set FIREWORKS_API_KEY to enable video self-correction."
843
+ elif self.input_mode == "native_video" and not self.deployment_configured:
844
+ reason = "Fireworks native video models require a dedicated deployment. Set FIREWORKS_ACCOUNT_ID and FIREWORKS_VIDEO_REVIEW_DEPLOYMENT_ID."
845
+ return {
846
+ "provider": "fireworks",
847
+ "model": self.model,
848
+ "configured": self.configured,
849
+ "reason": reason,
850
+ "base_url": self.base_url,
851
+ "max_frames": self.max_frames,
852
+ "input_mode": self.input_mode,
853
+ "include_audio": self.include_audio,
854
+ "deployment_configured": self.deployment_configured,
855
+ "available_native_models": list(FIREWORKS_VIDEO_REVIEW_NATIVE_MODELS),
856
+ "available_frame_models": list(FIREWORKS_VIDEO_REVIEW_FRAME_MODELS),
857
+ }
858
+
859
+ def review_video(
860
+ self,
861
+ current_ir: HardwareIntermediateRepresentation,
862
+ *,
863
+ video_url: str,
864
+ original_prompt: Optional[str] = None,
865
+ project_id: Optional[str] = None,
866
+ ) -> VideoIterationReview:
867
+ if not self.api_key:
868
+ logger.warning("Fireworks video review is not configured; set FIREWORKS_API_KEY.")
869
+ raise LLMProviderConfigError("Set FIREWORKS_API_KEY to enable video self-correction.")
870
+ url = _validate_http_video_url(video_url)
871
+ logger.info(
872
+ "Starting Fireworks video review: project_id=%s model=%s input_mode=%s max_frames=%s",
873
+ project_id or (current_ir.assembly_metadata or {}).get("project_id") or "unknown",
874
+ self.model,
875
+ self.input_mode,
876
+ self.max_frames,
877
+ )
878
+ if self.input_mode == "native_video" and not self.deployment_configured:
879
+ logger.warning(
880
+ "Fireworks native video review is using a base model path without a deployment suffix: model=%s. "
881
+ "Set FIREWORKS_ACCOUNT_ID and FIREWORKS_VIDEO_REVIEW_DEPLOYMENT_ID or provide a full FIREWORKS_VIDEO_REVIEW_MODEL path.",
882
+ self.model,
883
+ )
884
+ if self.input_mode == "native_video":
885
+ prepared_video = prepare_video_for_fireworks_native_review(
886
+ url,
887
+ include_audio=self.include_audio,
888
+ max_seconds=self.max_seconds,
889
+ fps=self.native_fps,
890
+ height=self.native_height,
891
+ max_media_bytes=self.max_media_bytes,
892
+ )
893
+ user_content = _video_review_native_user_content(
894
+ current_ir,
895
+ video_url=url,
896
+ prepared_video=prepared_video,
897
+ original_prompt=original_prompt,
898
+ project_id=project_id,
899
+ )
900
+ input_count = 1 + int(bool(prepared_video.audio_data_url))
901
+ else:
902
+ frames = sample_video_frames(url, max_frames=self.max_frames)
903
+ user_content = _video_review_user_content(
904
+ current_ir,
905
+ video_url=url,
906
+ frames=frames,
907
+ original_prompt=original_prompt,
908
+ project_id=project_id,
909
+ )
910
+ input_count = len(frames)
911
+ payload = {
912
+ "model": self.model,
913
+ "messages": [
914
+ {"role": "system", "content": _video_review_system_prompt()},
915
+ {"role": "user", "content": user_content},
916
+ ],
917
+ "temperature": 0.0,
918
+ "max_tokens": 1800,
919
+ "response_format": {"type": "json_object"},
920
+ }
921
+ request = urllib.request.Request(
922
+ f"{self.base_url}/chat/completions",
923
+ data=json.dumps(payload).encode("utf-8"),
924
+ headers={
925
+ "Authorization": f"Bearer {self.api_key}",
926
+ "Content-Type": "application/json",
927
+ "User-Agent": "Forma-OSS/0.1",
928
+ },
929
+ method="POST",
930
+ )
931
+ try:
932
+ logger.info(
933
+ "Submitting Fireworks video review: project_id=%s model=%s input_mode=%s inputs=%s",
934
+ project_id or (current_ir.assembly_metadata or {}).get("project_id") or "unknown",
935
+ self.model,
936
+ self.input_mode,
937
+ input_count,
938
+ )
939
+ with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
940
+ response_payload = json.loads(response.read().decode("utf-8"))
941
+ except urllib.error.HTTPError as exc:
942
+ body = exc.read().decode("utf-8", errors="replace")
943
+ message = _fireworks_http_error_message(status_code=exc.code, body=body, model=self.model)
944
+ logger.error(message)
945
+ raise LLMProviderOutputError(
946
+ message
947
+ ) from exc
948
+ except Exception as exc:
949
+ message = f"forma_core.video_review Fireworks video review failed for model {self.model}: {exc}"
950
+ logger.exception(message)
951
+ raise LLMProviderOutputError(message) from exc
952
+
953
+ try:
954
+ message_payload = response_payload["choices"][0]["message"]
955
+ content = _message_content_text(message_payload)
956
+ parsed = _extract_json_document(content)
957
+ review = VideoIterationReview.model_validate(parsed)
958
+ logger.info(
959
+ "Completed Fireworks video review: project_id=%s model=%s coherence_score=%.3f issue_count=%s target_namespace=%s",
960
+ project_id or (current_ir.assembly_metadata or {}).get("project_id") or "unknown",
961
+ self.model,
962
+ review.coherence_score,
963
+ len(review.issues),
964
+ review.target_namespace,
965
+ )
966
+ return review
967
+ except Exception as exc:
968
+ try:
969
+ message_payload = response_payload["choices"][0].get("message") or {}
970
+ except Exception:
971
+ message_payload = {}
972
+ content = _message_content_text(message_payload) if isinstance(message_payload, dict) else ""
973
+ fallback_review = _review_from_unstructured_text(content, model=self.model)
974
+ if fallback_review:
975
+ logger.warning(
976
+ "forma_core.video_review Fireworks video review returned unstructured text; using fallback review. "
977
+ "message_keys=%s finding_preview=%s parse_error=%s",
978
+ sorted(message_payload.keys()) if isinstance(message_payload, dict) else [],
979
+ _response_preview(fallback_review.issues[0].evidence if fallback_review.issues else fallback_review.summary),
980
+ exc,
981
+ )
982
+ return fallback_review
983
+ message = (
984
+ f"forma_core.video_review Fireworks video review returned unusable JSON: {exc}; "
985
+ f"message_keys={sorted(message_payload.keys()) if isinstance(message_payload, dict) else []}; "
986
+ f"content_preview={_response_preview(content)}"
987
+ )
988
+ logger.error(message)
989
+ raise LLMProviderOutputError(message) from exc
990
+
991
+
992
+ __all__ = [
993
+ "DEFAULT_FIREWORKS_FRAME_REVIEW_MODEL_SLUG",
994
+ "DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL",
995
+ "DEFAULT_FIREWORKS_NATIVE_VIDEO_REVIEW_MODEL_SLUG",
996
+ "DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL",
997
+ "DEFAULT_FIREWORKS_VIDEO_REVIEW_MODEL_SLUG",
998
+ "FIREWORKS_VIDEO_REVIEW_FRAME_MODELS",
999
+ "FIREWORKS_VIDEO_REVIEW_NATIVE_MODELS",
1000
+ "FireworksVideoReviewClient",
1001
+ "FireworksPreparedVideo",
1002
+ "VideoCoherenceIssue",
1003
+ "VideoIterationReview",
1004
+ "prepare_video_for_fireworks_native_review",
1005
+ "sample_video_frames",
1006
+ ]