OpenTopos — Architecture & Control Flow

flowchart TD
  L7["CLI"]
  L6["Domain Workflows"]
  L5["Orchestrator"]
  L4["Critic"]
  L3["Knowledge / Skills"]
  L2["Tools"]
  L1["Agent Backends"]
  L0["Substrate"]

  L7 --> L6 --> L5
  L5 --> L4
  L5 --> L3
  L5 --> L2
  L5 --> L1
  L1 --> L0
  L2 --> L0
          

flowchart LR
  USER["user prompt\n+ images"] --> MAKE["cli.py\nmake()"]
  MAKE -->|"create"| WS["workspace\noutputs/slug/"]
  MAKE -->|"generate"| PLAN["plan.json"]
  PLAN --> RUN["Runner.run()"]
  RUN -->|"agent tasks"| SRC["src/\nPython source"]
  RUN -->|"tool tasks"| ART["artifacts/\nglb · urdf · png"]
  RUN --> REPORT["run_report.json"]
          

flowchart TD
  LOAD["load plan.json\ntopo-sort tasks"]
  READY["find ready tasks\n(deps all done)"]
  RUN["execute in parallel\nThreadPoolExecutor"]
  RECORD["record TaskResult\n(success, cost, output)"]
  SKIP["cascade-skip\ndownstreams"]
  MORE{"more tasks?"}
  CHECK{"early-stop?"}
  FIX["build fix agents\nfrom judge feedback"]
  REPORT["RunReport"]

  LOAD --> READY --> RUN --> RECORD
  RECORD -->|"task failed"| SKIP --> MORE
  RECORD -->|"task ok"| MORE
  MORE -->|"yes"| READY
  MORE -->|"no"| CHECK
  CHECK -->|"judge pass"| REPORT
  CHECK -->|"max iters"| REPORT
  CHECK -->|"regression"| REPORT
  CHECK -->|"saturation"| REPORT
  CHECK -->|"continue"| FIX --> READY
          

flowchart TD
  DESIGN["01 design agent\nsrc/design.json"]
  SG["02 subgraph\nexpand from design.json"]

  P1["part agent — Frame\nsrc/parts/Frame.py"]
  P2["part agent — DrawerFront\nsrc/parts/DrawerFront.py"]
  P3["part agent — Handle\nsrc/parts/Handle.py"]

  J1["judge — Frame"]
  J2["judge — DrawerFront"]
  J3["judge — Handle"]

  VER["verify_parts\nBlender import check"]
  BUILD["03 build agent\nsrc/build.py"]
  JOINTS["04 joints agent\nsrc/joints.yaml"]

  DESIGN --> SG
  SG --> P1 & P2 & P3
  P1 --> J1
  P2 --> J2
  P3 --> J3
  J1 & J2 & J3 --> VER
  VER --> BUILD
  DESIGN -.->|"parallel"| JOINTS
          

flowchart LR
  JUDGE["judge\n(assembly)"]
  PASS{"passed?"}
  DONE["stop\njudge_pass ✓"]

  FIX["fix agent\nfeed judge feedback\nas goal prompt"]
  BUILD["build agent\nre-stitch assembly"]
  RENDER["render\n8 new views"]

  HALT{"regression or\nsaturation or\nmax iters?"}
  STOP2["halt"]

  JUDGE --> PASS
  PASS -->|"yes"| DONE
  PASS -->|"no"| FIX
  FIX --> BUILD --> RENDER --> JUDGE
  JUDGE --> HALT
  HALT -->|"yes"| STOP2
  HALT -->|"no"| PASS
          

flowchart LR
  TASK["AgentTask\ndispatched by Runner"]
  PROMPT["build prompt\nsystem base\n+ goal\n+ skills"]
  SPAWN["spawn subprocess\nclaude -p prompt\n--output-format stream-json\n--add-dir src/"]
  PARSE["parse stream-json\nassistant · tool_use\ntool_result · result"]
  WD{"idle >\ngrace_s?"}
  KILL["kill\ntimeout"]
  DONE["exit 0\ncompleted"]
  RETRY["retry?\nquota → backoff\ntimeout → once"]
  RESULT["AgentRunResult\nsuccess · cost · files_modified"]

  TASK --> PROMPT --> SPAWN --> PARSE
  PARSE --> WD
  WD -->|"no"| PARSE
  WD -->|"yes"| KILL --> RETRY --> SPAWN
  PARSE -->|"result event"| DONE --> RESULT
          

flowchart LR
  TOOL["judge tool\nimage_pattern + rubric"]
  RUBRIC["load rubric YAML\ncriteria · weights\npass_threshold"]
  IMAGES["collect renders\nview_000…007.png"]
  CRITIC["critic backend\nclaude_vision\ngemini · openai"]
  SCORE["score per criterion\n0–1 + feedback text\n+ suggested_fixes"]
  AGG["weighted average\ncheck min_floors"]
  RESULT["CriticResult\npassed · overall_score\nsuggested_fixes"]

  TOOL --> RUBRIC & IMAGES
  RUBRIC & IMAGES --> CRITIC --> SCORE --> AGG --> RESULT
          

flowchart LR
  PROMPT["user prompt\n+ references"]
  DESIGN["src/design.json"]
  PARTS["src/parts/*.py"]
  BUILD["src/build.py"]
  JOINTS["src/joints.yaml"]
  RENDERS["artifacts/view_*.png"]
  GLB["artifacts/object.glb"]
  URDF["artifacts/object.urdf"]
  SCORES["judge scores\n+ suggested_fixes"]

  PROMPT -->|"01 design agent"| DESIGN
  DESIGN -->|"02 part agents"| PARTS
  DESIGN & PARTS -->|"03 build agent"| BUILD
  DESIGN -->|"04 joints agent"| JOINTS
  BUILD -->|"05 render"| RENDERS
  BUILD -->|"06 export"| GLB
  BUILD & JOINTS -->|"07 export"| URDF
  RENDERS -->|"08 judge"| SCORES
  SCORES -->|"fix loop"| PARTS
  SCORES -->|"fix loop"| BUILD