Skip to content

Replace invented Guide patterns loop with canonical 3-phase#300

Open
PunchTheDev wants to merge 1 commit into
mainfrom
punch/guide-patterns-canonical
Open

Replace invented Guide patterns loop with canonical 3-phase#300
PunchTheDev wants to merge 1 commit into
mainfrom
punch/guide-patterns-canonical

Conversation

@PunchTheDev
Copy link
Copy Markdown
Owner

Summary

Rewrites Guide → Agent architecture patterns against the canonical source agents. The section previously claimed "best agents use a structured observe → plan → act loop rather than a single prompt" and showed a 6-phase loop (OBSERVE→PLAN→ACT→VERIFY→REFLECT→EXPORT) plus four library tiles, half of which are not used by any canonical agent.

Motivation

Audit against forge/agents/ and forge/examples/:

  • agents/baseline/agent.py is deterministic geometry, no LLM call. Docstring is explicit: "This agent accepts the LLMClient parameter but does not use it … This is permitted; the harness requires the parameter to be present in the signature, not necessarily used." Guide framing ("best agents use a loop") implied this is wrong — it's actually one of two legitimate patterns.
  • examples/llm-agent/agent.py uses literal 3-phase comments: ── Observe ──, ── Plan (LLM proposes dimensions) ──, ── Act (build geometry) ──. The Guide's 6-phase loop with VERIFY + REFLECT + EXPORT is not in any canonical agent.
  • Library tiles: gmsh and numpy/scipy are not imported by any agent in agents/ or examples/. Only build123d (both LLM examples) and raw OCP (baseline) are verified.
  • examples/llm-agent/ and examples/metric-aware-agent/ — the references the template literally tells users to read — were never linked from the Guide.
  • Canonical LLMClient.chat(messages, max_tokens=...) API was never surfaced.

Pattern matches steps 359 / 365 / 367 / 368 / 369 / 370 / 371 / 372 / 373 — canonical-source check before tooltip / before claim.

Changes

  • QuickstartGuide.tsx L639–743: lead reframed as "two canonical patterns, pick one" rather than "best agents use a loop"
  • Pattern A card — Deterministic geometry, references agents/baseline/agent.py, 247-char tooltip quoting the baseline docstring verbatim
  • Pattern B card — Observe → Plan → Act, references both LLM examples, 200-char tooltip pointing to the literal comment markers in examples/llm-agent/agent.py
  • 3-phase loop block replaces the 6-phase loop, with concrete field names (build_volume_mm, load_point_mm, bolt_pattern_mm, min_wall_thickness_mm) and the actual llm.chat([{"role":"user","content": prompt}], max_tokens=256) call from examples/llm-agent/agent.py:53
  • Harness-injection sentence with 213-char tooltip naming forge/sdk/llm.py and tying back to the Whitelisted models section
  • Library tiles reduced from 4 to 2 — build123d (recommended, used by both LLM examples) and Raw OCP (BRep) (used by baseline). Each tile gets a tooltip citing the specific OCP / build123d imports in the canonical files. gmsh and numpy/scipy tiles removed (not used by any canonical agent).
  • Three routed GitHub source links: examples/llm-agent/agent.py, examples/metric-aware-agent/agent.py, agents/baseline/agent.py

Verification: Puppeteer 1440×900 on /guide#patterns confirms 5 tooltips (lengths 247/200/213/176/135), 3 GitHub links pointing at the right files, old 6-phase / gmsh / numpy claims all gone, canonical 3-phase OBSERVE/PLAN/ACT + llm.chat( API + all 3 reference agent paths present. 0 new console errors (1 pre-existing 404).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant