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,537 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import mimetypes
5
+ import os
6
+
7
+ from forma_core.config import config
8
+ import subprocess
9
+ import threading
10
+ import time
11
+ from concurrent.futures import ThreadPoolExecutor
12
+ from dataclasses import dataclass, field
13
+ from datetime import datetime, timezone
14
+ from pathlib import Path
15
+ from typing import Any, Callable, Iterable, Optional
16
+
17
+
18
+ def utc_now() -> str:
19
+ return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class StreamEvent:
24
+ schema_version: int
25
+ event_id: str
26
+ observed_at_unix_ms: int
27
+ kind: str
28
+ source_provider: str
29
+ source_type: str
30
+ source_name: str
31
+ payload: dict[str, Any]
32
+ metadata: dict[str, Any]
33
+
34
+ @classmethod
35
+ def from_json(cls, value: dict[str, Any]) -> "StreamEvent":
36
+ source = value.get("source") if isinstance(value.get("source"), dict) else {}
37
+ payload = value.get("payload") if isinstance(value.get("payload"), dict) else {}
38
+ metadata = value.get("metadata") if isinstance(value.get("metadata"), dict) else {}
39
+ return cls(
40
+ schema_version=int(value.get("schema_version") or 1),
41
+ event_id=str(value.get("event_id") or ""),
42
+ observed_at_unix_ms=int(value.get("observed_at_unix_ms") or 0),
43
+ kind=str(value.get("kind") or ""),
44
+ source_provider=str(source.get("provider") or ""),
45
+ source_type=str(source.get("source_type") or ""),
46
+ source_name=str(source.get("name") or ""),
47
+ payload=dict(payload),
48
+ metadata=dict(metadata),
49
+ )
50
+
51
+ def content_text(self) -> str:
52
+ value = self.payload.get("content")
53
+ return value if isinstance(value, str) else ""
54
+
55
+ def is_done(self) -> bool:
56
+ return bool(self.payload.get("done"))
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class AgentOutputEvent:
61
+ agent_name: str
62
+ kind: str
63
+ payload: dict[str, Any]
64
+ source_event_id: Optional[str] = None
65
+ created_at: str = field(default_factory=utc_now)
66
+
67
+ def to_json_line(self) -> str:
68
+ return json.dumps(
69
+ {
70
+ "schema_version": 1,
71
+ "created_at": self.created_at,
72
+ "agent_name": self.agent_name,
73
+ "kind": self.kind,
74
+ "source_event_id": self.source_event_id,
75
+ "payload": self.payload,
76
+ },
77
+ sort_keys=True,
78
+ )
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class MediaFinding:
83
+ severity: str
84
+ code: str
85
+ message: str
86
+ path: Optional[str] = None
87
+
88
+ def as_dict(self) -> dict[str, Any]:
89
+ return {
90
+ "severity": self.severity,
91
+ "code": self.code,
92
+ "message": self.message,
93
+ "path": self.path,
94
+ }
95
+
96
+
97
+ @dataclass(frozen=True)
98
+ class ImageInspection:
99
+ path: Path
100
+ exists: bool
101
+ mime_type: str
102
+ width: Optional[int] = None
103
+ height: Optional[int] = None
104
+ mode: Optional[str] = None
105
+ byte_size: Optional[int] = None
106
+ findings: tuple[MediaFinding, ...] = ()
107
+
108
+ def as_dict(self) -> dict[str, Any]:
109
+ return {
110
+ "path": str(self.path),
111
+ "exists": self.exists,
112
+ "mime_type": self.mime_type,
113
+ "width": self.width,
114
+ "height": self.height,
115
+ "mode": self.mode,
116
+ "byte_size": self.byte_size,
117
+ "findings": [finding.as_dict() for finding in self.findings],
118
+ }
119
+
120
+
121
+ @dataclass(frozen=True)
122
+ class VideoInspection:
123
+ path: Path
124
+ exists: bool
125
+ duration_seconds: Optional[float] = None
126
+ width: Optional[int] = None
127
+ height: Optional[int] = None
128
+ frame_rate: Optional[str] = None
129
+ byte_size: Optional[int] = None
130
+ findings: tuple[MediaFinding, ...] = ()
131
+
132
+ def as_dict(self) -> dict[str, Any]:
133
+ return {
134
+ "path": str(self.path),
135
+ "exists": self.exists,
136
+ "duration_seconds": self.duration_seconds,
137
+ "width": self.width,
138
+ "height": self.height,
139
+ "frame_rate": self.frame_rate,
140
+ "byte_size": self.byte_size,
141
+ "findings": [finding.as_dict() for finding in self.findings],
142
+ }
143
+
144
+
145
+ @dataclass(frozen=True)
146
+ class PromptIterationProposal:
147
+ revision: int
148
+ prompt: str
149
+ reason: str
150
+ findings: tuple[MediaFinding, ...] = ()
151
+
152
+ def as_dict(self) -> dict[str, Any]:
153
+ return {
154
+ "revision": self.revision,
155
+ "prompt": self.prompt,
156
+ "reason": self.reason,
157
+ "findings": [finding.as_dict() for finding in self.findings],
158
+ }
159
+
160
+
161
+ @dataclass
162
+ class ContinuousAgentState:
163
+ input_offset: int = 0
164
+ source_event_ids: set[str] = field(default_factory=set)
165
+ prompt_revision: int = 0
166
+ current_prompt: str = ""
167
+
168
+
169
+ @dataclass(frozen=True)
170
+ class ContinuousAgentCycleReport:
171
+ cycle_index: int
172
+ new_event_count: int
173
+ output_count: int
174
+ output_agent_names: tuple[str, ...]
175
+ input_offset: int
176
+ prompt_revision: int
177
+
178
+ def has_activity(self) -> bool:
179
+ return self.new_event_count > 0 or self.output_count > 0
180
+
181
+
182
+ class JsonlStreamStore:
183
+ def __init__(self, root_dir: Path, stream_id: str) -> None:
184
+ self.root_dir = root_dir
185
+ self.stream_id = stream_id
186
+ self.stream_dir = root_dir / "streams" / stream_id
187
+ self.events_path = self.stream_dir / "events.jsonl"
188
+ self.agents_dir = self.stream_dir / "agents"
189
+ self.state_path = self.stream_dir / "continuous-agent-state.json"
190
+ self.lock = threading.Lock()
191
+
192
+ def ensure(self) -> None:
193
+ self.agents_dir.mkdir(parents=True, exist_ok=True)
194
+ if not self.events_path.exists():
195
+ self.events_path.touch()
196
+
197
+ def agent_path(self, agent_name: str) -> Path:
198
+ return self.agents_dir / f"{agent_name}.jsonl"
199
+
200
+ def append_agent_output(self, event: AgentOutputEvent) -> None:
201
+ self.ensure()
202
+ path = self.agent_path(event.agent_name)
203
+ with self.lock:
204
+ with path.open("a", encoding="utf-8") as handle:
205
+ handle.write(event.to_json_line() + "\n")
206
+
207
+ def load_state(self) -> ContinuousAgentState:
208
+ if not self.state_path.exists():
209
+ return ContinuousAgentState()
210
+ raw = json.loads(self.state_path.read_text(encoding="utf-8"))
211
+ return ContinuousAgentState(
212
+ input_offset=int(raw.get("input_offset") or 0),
213
+ source_event_ids=set(str(item) for item in raw.get("source_event_ids", [])),
214
+ prompt_revision=int(raw.get("prompt_revision") or 0),
215
+ current_prompt=str(raw.get("current_prompt") or ""),
216
+ )
217
+
218
+ def save_state(self, state: ContinuousAgentState) -> None:
219
+ self.ensure()
220
+ payload = {
221
+ "input_offset": state.input_offset,
222
+ "source_event_ids": sorted(state.source_event_ids),
223
+ "prompt_revision": state.prompt_revision,
224
+ "current_prompt": state.current_prompt,
225
+ "saved_at": utc_now(),
226
+ }
227
+ with self.lock:
228
+ self.state_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
229
+
230
+ def read_new_events(self, state: ContinuousAgentState) -> list[StreamEvent]:
231
+ self.ensure()
232
+ events: list[StreamEvent] = []
233
+ with self.events_path.open("r", encoding="utf-8") as handle:
234
+ handle.seek(state.input_offset)
235
+ for line in handle:
236
+ stripped = line.strip()
237
+ if not stripped:
238
+ continue
239
+ parsed = json.loads(stripped)
240
+ event = StreamEvent.from_json(parsed)
241
+ if event.event_id and event.event_id in state.source_event_ids:
242
+ continue
243
+ events.append(event)
244
+ if event.event_id:
245
+ state.source_event_ids.add(event.event_id)
246
+ state.input_offset = handle.tell()
247
+ return events
248
+
249
+
250
+ class MediaInspector:
251
+ def inspect_images(self, paths: Iterable[Path]) -> list[ImageInspection]:
252
+ return [self.inspect_image(path) for path in paths]
253
+
254
+ def inspect_videos(self, paths: Iterable[Path]) -> list[VideoInspection]:
255
+ return [self.inspect_video(path) for path in paths]
256
+
257
+ def inspect_image(self, path: Path) -> ImageInspection:
258
+ mime_type = mimetypes.guess_type(path.name)[0] or "application/octet-stream"
259
+ if not path.exists():
260
+ return ImageInspection(
261
+ path=path,
262
+ exists=False,
263
+ mime_type=mime_type,
264
+ findings=(MediaFinding("error", "image_missing", "Image file does not exist.", str(path)),),
265
+ )
266
+ findings: list[MediaFinding] = []
267
+ byte_size = path.stat().st_size
268
+ width = height = None
269
+ mode = None
270
+ try:
271
+ from PIL import Image
272
+
273
+ with Image.open(path) as image:
274
+ width, height = image.size
275
+ mode = image.mode
276
+ except Exception as exc:
277
+ findings.append(MediaFinding("error", "image_unreadable", f"Image could not be decoded: {exc}", str(path)))
278
+ if byte_size == 0:
279
+ findings.append(MediaFinding("error", "image_empty", "Image file is empty.", str(path)))
280
+ if width is not None and height is not None:
281
+ if width < 256 or height < 256:
282
+ findings.append(MediaFinding("warning", "image_low_resolution", "Image resolution is below 256px on one axis.", str(path)))
283
+ aspect_ratio = width / max(1, height)
284
+ if aspect_ratio < 0.2 or aspect_ratio > 5:
285
+ findings.append(MediaFinding("warning", "image_extreme_aspect_ratio", "Image aspect ratio looks extreme.", str(path)))
286
+ return ImageInspection(path=path, exists=True, mime_type=mime_type, width=width, height=height, mode=mode, byte_size=byte_size, findings=tuple(findings))
287
+
288
+ def inspect_video(self, path: Path) -> VideoInspection:
289
+ if not path.exists():
290
+ return VideoInspection(
291
+ path=path,
292
+ exists=False,
293
+ findings=(MediaFinding("error", "video_missing", "Video file does not exist.", str(path)),),
294
+ )
295
+ findings: list[MediaFinding] = []
296
+ byte_size = path.stat().st_size
297
+ if byte_size == 0:
298
+ findings.append(MediaFinding("error", "video_empty", "Video file is empty.", str(path)))
299
+ duration = width = height = None
300
+ frame_rate = None
301
+ try:
302
+ completed = subprocess.run(
303
+ [
304
+ "ffprobe",
305
+ "-v",
306
+ "error",
307
+ "-print_format",
308
+ "json",
309
+ "-show_streams",
310
+ "-show_format",
311
+ str(path),
312
+ ],
313
+ check=False,
314
+ capture_output=True,
315
+ text=True,
316
+ timeout=15,
317
+ )
318
+ if completed.returncode != 0:
319
+ findings.append(MediaFinding("error", "video_probe_failed", completed.stderr.strip() or "ffprobe failed.", str(path)))
320
+ else:
321
+ data = json.loads(completed.stdout or "{}")
322
+ format_info = data.get("format") if isinstance(data.get("format"), dict) else {}
323
+ if format_info.get("duration") is not None:
324
+ duration = float(format_info["duration"])
325
+ streams = data.get("streams") if isinstance(data.get("streams"), list) else []
326
+ video_stream = next((stream for stream in streams if stream.get("codec_type") == "video"), {})
327
+ width = int(video_stream["width"]) if video_stream.get("width") is not None else None
328
+ height = int(video_stream["height"]) if video_stream.get("height") is not None else None
329
+ frame_rate = video_stream.get("avg_frame_rate") or video_stream.get("r_frame_rate")
330
+ except FileNotFoundError:
331
+ findings.append(MediaFinding("warning", "ffprobe_missing", "ffprobe is not installed, so video understanding is metadata-limited.", str(path)))
332
+ except Exception as exc:
333
+ findings.append(MediaFinding("error", "video_unreadable", f"Video could not be inspected: {exc}", str(path)))
334
+ if duration is not None and duration <= 0:
335
+ findings.append(MediaFinding("error", "video_zero_duration", "Video duration is zero.", str(path)))
336
+ if width is not None and height is not None and (width < 256 or height < 256):
337
+ findings.append(MediaFinding("warning", "video_low_resolution", "Video resolution is below 256px on one axis.", str(path)))
338
+ return VideoInspection(path=path, exists=True, duration_seconds=duration, width=width, height=height, frame_rate=frame_rate, byte_size=byte_size, findings=tuple(findings))
339
+
340
+
341
+ class ReaderAgent:
342
+ name = "reader"
343
+
344
+ def process(self, events: list[StreamEvent]) -> Optional[AgentOutputEvent]:
345
+ if not events:
346
+ return None
347
+ text = "".join(event.content_text() for event in events)
348
+ return AgentOutputEvent(
349
+ agent_name=self.name,
350
+ kind="agent.reader.batch",
351
+ source_event_id=events[-1].event_id,
352
+ payload={
353
+ "event_count": len(events),
354
+ "done_count": sum(1 for event in events if event.is_done()),
355
+ "text_preview": text[:2000],
356
+ "source_event_ids": [event.event_id for event in events if event.event_id],
357
+ },
358
+ )
359
+
360
+
361
+ class WriterAgent:
362
+ name = "writer"
363
+
364
+ def process(self, events: list[StreamEvent]) -> Optional[AgentOutputEvent]:
365
+ if not events:
366
+ return None
367
+ completed = [event for event in events if event.is_done()]
368
+ return AgentOutputEvent(
369
+ agent_name=self.name,
370
+ kind="agent.writer.summary",
371
+ source_event_id=events[-1].event_id,
372
+ payload={
373
+ "received_events": len(events),
374
+ "completed": bool(completed),
375
+ "last_content": events[-1].content_text(),
376
+ },
377
+ )
378
+
379
+
380
+ class ReviewerAgent:
381
+ name = "reviewer"
382
+
383
+ def __init__(self, inspector: Optional[MediaInspector] = None) -> None:
384
+ self.inspector = inspector or MediaInspector()
385
+
386
+ def process(self, events: list[StreamEvent], image_paths: Iterable[Path], video_paths: Iterable[Path]) -> Optional[AgentOutputEvent]:
387
+ image_reports = self.inspector.inspect_images(image_paths)
388
+ video_reports = self.inspector.inspect_videos(video_paths)
389
+ findings = [
390
+ *[finding for report in image_reports for finding in report.findings],
391
+ *[finding for report in video_reports for finding in report.findings],
392
+ ]
393
+ text = "".join(event.content_text() for event in events)
394
+ for event in events:
395
+ error_message = event.metadata.get("error_message")
396
+ if error_message:
397
+ findings.append(MediaFinding("error", "llm_stream_error", str(error_message)[:1000]))
398
+ if "failed" in event.kind.lower():
399
+ findings.append(MediaFinding("error", "llm_stream_failed", f"Stream event failed: {event.kind}"))
400
+ if "unknown" in text.lower():
401
+ findings.append(MediaFinding("warning", "placeholder_text", "Stream output contains placeholder text."))
402
+ if not text.strip() and events:
403
+ findings.append(MediaFinding("warning", "empty_stream_content", "Stream events were received but content was empty."))
404
+ if not events and not findings:
405
+ return None
406
+ return AgentOutputEvent(
407
+ agent_name=self.name,
408
+ kind="agent.reviewer.findings",
409
+ source_event_id=events[-1].event_id if events else None,
410
+ payload={
411
+ "event_count": len(events),
412
+ "image_reports": [report.as_dict() for report in image_reports],
413
+ "video_reports": [report.as_dict() for report in video_reports],
414
+ "findings": [finding.as_dict() for finding in findings],
415
+ },
416
+ )
417
+
418
+
419
+ class PromptIteratorAgent:
420
+ name = "prompt-iterator"
421
+
422
+ def process(self, state: ContinuousAgentState, review: Optional[AgentOutputEvent]) -> Optional[AgentOutputEvent]:
423
+ if review is None:
424
+ return None
425
+ findings = [
426
+ MediaFinding(
427
+ severity=str(item.get("severity") or "info"),
428
+ code=str(item.get("code") or "finding"),
429
+ message=str(item.get("message") or ""),
430
+ path=item.get("path"),
431
+ )
432
+ for item in review.payload.get("findings", [])
433
+ if isinstance(item, dict)
434
+ ]
435
+ actionable = [finding for finding in findings if finding.severity in {"warning", "error"}]
436
+ if not actionable:
437
+ return None
438
+ state.prompt_revision += 1
439
+ base_prompt = state.current_prompt or "Generate a precise Forma project output."
440
+ correction = "; ".join(f"{finding.code}: {finding.message}" for finding in actionable[:6])
441
+ proposal = PromptIterationProposal(
442
+ revision=state.prompt_revision,
443
+ prompt=f"{base_prompt}\n\nRevision {state.prompt_revision}: Correct these observed issues: {correction}",
444
+ reason="Reviewer found imperfections that should be corrected in the next prompt iteration.",
445
+ findings=tuple(actionable),
446
+ )
447
+ state.current_prompt = proposal.prompt
448
+ return AgentOutputEvent(
449
+ agent_name=self.name,
450
+ kind="agent.prompt_iteration.proposal",
451
+ source_event_id=review.source_event_id,
452
+ payload=proposal.as_dict(),
453
+ )
454
+
455
+
456
+ class ContinuousAgentCoordinator:
457
+ def __init__(
458
+ self,
459
+ store: JsonlStreamStore,
460
+ *,
461
+ image_paths: Iterable[Path] = (),
462
+ video_paths: Iterable[Path] = (),
463
+ poll_interval_seconds: float = 1.0,
464
+ ) -> None:
465
+ self.store = store
466
+ self.image_paths = tuple(image_paths)
467
+ self.video_paths = tuple(video_paths)
468
+ self.poll_interval_seconds = poll_interval_seconds
469
+ self.reader = ReaderAgent()
470
+ self.writer = WriterAgent()
471
+ self.reviewer = ReviewerAgent()
472
+ self.iterator = PromptIteratorAgent()
473
+ self.stop_event = threading.Event()
474
+
475
+ def run_cycle_report(self, state: ContinuousAgentState, *, cycle_index: int = 0) -> ContinuousAgentCycleReport:
476
+ events = self.store.read_new_events(state)
477
+ outputs: list[AgentOutputEvent] = []
478
+
479
+ with ThreadPoolExecutor(max_workers=3) as executor:
480
+ reader_future = executor.submit(self.reader.process, events)
481
+ writer_future = executor.submit(self.writer.process, events)
482
+ review_future = executor.submit(self.reviewer.process, events, self.image_paths, self.video_paths)
483
+
484
+ reader_output = reader_future.result()
485
+ writer_output = writer_future.result()
486
+ review_output = review_future.result()
487
+
488
+ if reader_output:
489
+ outputs.append(reader_output)
490
+ if writer_output:
491
+ outputs.append(writer_output)
492
+ if review_output:
493
+ outputs.append(review_output)
494
+
495
+ iterator_output = self.iterator.process(state, review_output)
496
+ if iterator_output:
497
+ outputs.append(iterator_output)
498
+ for output in outputs:
499
+ self.store.append_agent_output(output)
500
+ self.store.save_state(state)
501
+ return ContinuousAgentCycleReport(
502
+ cycle_index=cycle_index,
503
+ new_event_count=len(events),
504
+ output_count=len(outputs),
505
+ output_agent_names=tuple(output.agent_name for output in outputs),
506
+ input_offset=state.input_offset,
507
+ prompt_revision=state.prompt_revision,
508
+ )
509
+
510
+ def run_cycle(self, state: ContinuousAgentState) -> int:
511
+ return self.run_cycle_report(state).output_count
512
+
513
+ def run(
514
+ self,
515
+ *,
516
+ max_cycles: Optional[int] = None,
517
+ on_cycle: Optional[Callable[[ContinuousAgentCycleReport], None]] = None,
518
+ ) -> None:
519
+ self.store.ensure()
520
+ state = self.store.load_state()
521
+ cycle = 0
522
+ while not self.stop_event.is_set():
523
+ cycle += 1
524
+ report = self.run_cycle_report(state, cycle_index=cycle)
525
+ if on_cycle:
526
+ on_cycle(report)
527
+ if max_cycles is not None and cycle >= max_cycles:
528
+ break
529
+ time.sleep(self.poll_interval_seconds)
530
+
531
+ def stop(self) -> None:
532
+ self.stop_event.set()
533
+
534
+
535
+ def paths_from_env(name: str) -> tuple[Path, ...]:
536
+ value = config.get(name, "")
537
+ return tuple(Path(item).expanduser() for item in value.split(os.pathsep) if item.strip())