lhumina_code/hero_logic
1
0
Fork 0
Code Issues 17 Pull requests 1 Projects Releases 1 Packages Wiki Activity Actions

Epic: Flows as Python, Visualization Always On #10

New issue
Open
opened 2026-04-21 14:18:05 +00:00 by timur · 1 comment
timur commented 2026-04-21 14:18:05 +00:00
Owner
Copy link

Context

PRD: docs/flows-as-python.md

The DAG-as-JSON authoring model is being deleted. Flows become Python functions decorated with @flow(...), with with flow.step(name): blocks for named steps. A span tree is emitted at runtime and rendered live in the UI. One authoring mode, one viewer, zero hand-written SDK code in consumer repos.

Prerequisites

  • hero_rpc#29 — Generated Python clients must emit service methods, not just rootobject CRUD

(hero_rpc#30 was closed — its scope moved into hero_logic#11. Tracing helpers live in hero_logic, not in the generator.)

Stories

All-at-once release. No DAG back-compat. Rollout: Story 1 → (Story 2 + Story 3 in parallel).

  • Story 1 — Foundation: executor + schema + hero_tracing.py + span socket listener — #11
  • Story 2 — UI: kill Cytoscape, monaco editor + live span-tree viewer — #12
  • Story 3 — Migrate 6 built-in flows + library search — #13

Out of scope

  • Human-in-the-loop pauses (handled by Python scripts talking to Slack if needed)
  • Edit-by-tree for non-coders (schema leaves room; v2 feature)
  • Pre-execution visualization (tree is rendered from actual span events)
  • Meta-DSL — rejected in the PRD

Done when

  • All three stories closed
  • The 6 existing built-in flows run as Python and render span trees identically in the UI
  • node_runs / Node / Edge / template_loader.rs / node_executors.rs deleted from the codebase
  • Service Agent v3 consults the flow library as its first step
## Context PRD: [`docs/flows-as-python.md`](https://forge.ourworld.tf/lhumina_code/hero_logic/src/branch/development/docs/flows-as-python.md) The DAG-as-JSON authoring model is being deleted. Flows become Python functions decorated with `@flow(...)`, with `with flow.step(name):` blocks for named steps. A span tree is emitted at runtime and rendered live in the UI. One authoring mode, one viewer, zero hand-written SDK code in consumer repos. ## Prerequisites - [ ] hero_rpc#29 — Generated Python clients must emit service methods, not just rootobject CRUD (hero_rpc#30 was closed — its scope moved into hero_logic#11. Tracing helpers live in hero_logic, not in the generator.) ## Stories All-at-once release. No DAG back-compat. Rollout: Story 1 → (Story 2 + Story 3 in parallel). - [ ] **Story 1** — Foundation: executor + schema + `hero_tracing.py` + span socket listener — #11 - [ ] **Story 2** — UI: kill Cytoscape, monaco editor + live span-tree viewer — #12 - [ ] **Story 3** — Migrate 6 built-in flows + library search — #13 ## Out of scope - Human-in-the-loop pauses (handled by Python scripts talking to Slack if needed) - Edit-by-tree for non-coders (schema leaves room; v2 feature) - Pre-execution visualization (tree is rendered from actual span events) - Meta-DSL — rejected in the PRD ## Done when - All three stories closed - The 6 existing built-in flows run as Python and render span trees identically in the UI - `node_runs` / `Node` / `Edge` / `template_loader.rs` / `node_executors.rs` deleted from the codebase - Service Agent v3 consults the flow library as its first step
timur commented 2026-05-05 10:26:03 +00:00
Author
Owner
Copy link

Alignment review against hero_router/docs/agentic_calling.md

The doc is now the chosen architectural reference for Python-on-the-router execution. Three things tracked off the back of that:

Closed

  • hero_rpc#29 — generator emits service methods without the LogicService. prefix. Landed in hero_router#40 (commit 31ec54cd). ~/.hero/var/router/python/hero_logic_client.py already exposes the 25 LogicService methods. Story 1 (#11)'s prerequisite is met.
  • hero_rpc#31 — closed. The doc places codegen in the router (where it lives today); moving it to hero_rpc was the architecturally cleaner option but loses runtime composability for multi-context dispatch. Re-file later if pressure changes.

Promoted to prerequisite

  • hero_rpc#32 (stale rpc.discover cache) — was "land any time"; now a prerequisite for #13. Reason: Service Agent v3's library-first lookup + LLM-generated calls both depend on the cached client matching the live service. If rpc.discover serves a stale embedded spec, the agent generates calls against a phantom API. Promote in priority alongside #13 kickoff.

New

  • #14 — Flow execution sandbox roadmap. Tiered (Tier 0 env scrub + ulimits → Tier 1 bwrap/sandbox-exec → Tier 2 container → Tier 3 microVM). Tier 0 is small enough to land inside #11. Tier 1 is the prerequisite for safely executing LLM-generated scripts as the doc envisions; without it, "the LLM does not need access to service data" is aspirational. Treat Tier 1 as a hard precondition for the router agent feature, but not for #11/#12/#13 themselves (those are human-authored).

Doc gaps to close (low priority, won't block stories)

  • The doc's example registry layout (router/generated/{service}/{interface,client,md5}.py) doesn't match the actual flat layout (~/.hero/var/router/python/{service}_{client,interface}.py + .hash). Update so #11 implementers don't second-guess paths.
  • Doc doesn't mention the library-first lookup path that #13's Service Agent v3 will add — worth a section.
  • Doc doesn't mention hero_tracing.py / instrument(client) from #11 — worth a paragraph since instrumented clients are how span-tree visualization composes with the doc's "sandbox executes the generated script" picture.

Net

Stories #11 / #12 / #13 are aligned with the doc. The two real risks are (1) cache drift via #32 and (2) the gap between "subprocess" and "sandbox" tracked in #14 — both are now visible and prioritized.

## Alignment review against `hero_router/docs/agentic_calling.md` The doc is now the chosen architectural reference for Python-on-the-router execution. Three things tracked off the back of that: ### Closed - **hero_rpc#29** — generator emits service methods without the `LogicService.` prefix. Landed in hero_router#40 (commit `31ec54cd`). `~/.hero/var/router/python/hero_logic_client.py` already exposes the 25 LogicService methods. **Story 1 (#11)'s prerequisite is met.** - **hero_rpc#31** — closed. The doc places codegen in the router (where it lives today); moving it to hero_rpc was the architecturally cleaner option but loses runtime composability for multi-context dispatch. Re-file later if pressure changes. ### Promoted to prerequisite - **hero_rpc#32** (stale `rpc.discover` cache) — was "land any time"; now a **prerequisite for #13**. Reason: Service Agent v3's library-first lookup + LLM-generated calls both depend on the cached client matching the live service. If `rpc.discover` serves a stale embedded spec, the agent generates calls against a phantom API. Promote in priority alongside #13 kickoff. ### New - **#14 — Flow execution sandbox roadmap.** Tiered (Tier 0 env scrub + ulimits → Tier 1 bwrap/sandbox-exec → Tier 2 container → Tier 3 microVM). Tier 0 is small enough to land inside #11. Tier 1 is the **prerequisite for safely executing LLM-generated scripts** as the doc envisions; without it, "the LLM does not need access to service data" is aspirational. Treat Tier 1 as a hard precondition for the router agent feature, but not for #11/#12/#13 themselves (those are human-authored). ### Doc gaps to close (low priority, won't block stories) - The doc's example registry layout (`router/generated/{service}/{interface,client,md5}.py`) doesn't match the actual flat layout (`~/.hero/var/router/python/{service}_{client,interface}.py` + `.hash`). Update so #11 implementers don't second-guess paths. - Doc doesn't mention the library-first lookup path that #13's Service Agent v3 will add — worth a section. - Doc doesn't mention `hero_tracing.py` / `instrument(client)` from #11 — worth a paragraph since instrumented clients are how span-tree visualization composes with the doc's "sandbox executes the generated script" picture. ### Net Stories #11 / #12 / #13 are aligned with the doc. The two real risks are (1) cache drift via #32 and (2) the gap between "subprocess" and "sandbox" tracked in #14 — both are now visible and prioritized.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
main
feat/39-logic-model
fix/revert-workflow-editor-island
fix/island-in-workflow-editor
fix/runtime-compat-importer-and-play-redirect
fix/flowfield-back-compat-alias
fix/root-flow-span-kind
feature/issue-29-prd-gaps
feature/issue-28-ask-user-resume
v0.1.0-rc2
v0.1.0-rc1
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_logic#10
No description provided.