# ml-postech/epic architecture

> Architecture diagram of the GitHub repository ml-postech/epic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ml-postech/epic
- Repository: https://github.com/ml-postech/epic

## Overview

EPIC turns a text prompt into a fixed visual program, generates an image, checks its predicates, and iteratively edits or resamples until acceptance or the round budget is exhausted. Benchmark runners adapt several prompt datasets to the same generation workflow. The graph reflects documented capabilities and indexed imports; unsampled implementation details and model-service wiring are represented only where the README or excerpts support them.

Main entry points: [`src/graph/node_vp_pipeline.py`](https://github.com/ml-postech/epic/blob/main/src/graph/node_vp_pipeline.py) (Refinement loop), [`src/graph/graph_main.py`](https://github.com/ml-postech/epic/blob/main/src/graph/graph_main.py) (Generation API), [`src/graph/visual_program_verifier.py`](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_verifier.py) (Predicate verifier), [`src/graph/models.py`](https://github.com/ml-postech/epic/blob/main/src/graph/models.py) (Model clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["Generation API<br/>[graph_main.py]"]
  node_cli["Run options<br/>[cli.py]"]
  node_bench["Benchmark runners"]
end

subgraph group_control["Refinement control"]
  node_state["Run state<br/>[state.py]"]
  node_pipeline["Refinement loop"]
  node_context["VLM context<br/>[context.py]"]
end

subgraph group_program["Visual program"]
  node_parser["Program parser"]
  node_schema["Program schema<br/>[visual_program.py]"]
  node_support["Predicate vocabulary"]
  node_rewriter["Prompt rewriter"]
  node_selector["Action selector"]
  node_auditor["Loop auditor"]
end

subgraph group_vision["Generation and verification"]
  node_verifier["Predicate verifier"]
  node_runtime["Verification tools"]
  node_toolset["Region and depth tools"]
  node_depth["Depth estimation<br/>[depth.py]"]
  node_image["Image generation<br/>[image_runtime.py]"]
  node_models["Model clients<br/>[models.py]"]
end

subgraph group_results["Results and benchmarks"]
  node_artifacts["Images and traces<br/>[utils.py]"]
end

node_user(("Prompt author"))
node_vlm(("VLM endpoint"))
node_benchdata["Benchmark prompts"]

node_user -->|"submits prompt"| node_main
node_cli -->|"configures run"| node_main
node_bench -->|"invokes"| node_main
node_benchdata -->|"supplies prompts"| node_bench
node_main -->|"invokes"| node_pipeline
node_main -->|"builds context"| node_context
node_pipeline -->|"updates"| node_state
node_pipeline -->|"parses prompt"| node_parser
node_pipeline -->|"requests rewrites"| node_rewriter
node_pipeline -->|"selects actions"| node_selector
node_pipeline -->|"audits progress"| node_auditor
node_pipeline -->|"checks predicates"| node_verifier
node_pipeline -->|"generates edits"| node_image
node_pipeline -->|"saves results"| node_artifacts
node_parser -->|"builds program"| node_schema
node_parser -->|"uses vocabulary"| node_support
node_rewriter -->|"calls model"| node_models
node_selector -->|"reads predicates"| node_schema
node_selector -->|"uses verification"| node_verifier
node_auditor -->|"calls model"| node_models
node_verifier -->|"evaluates predicates"| node_schema
node_verifier -->|"uses proposals"| node_toolset
node_runtime -->|"dispatches tools"| node_toolset
node_runtime -->|"estimates depth"| node_depth
node_image -->|"uses generation model"| node_models
node_models -.->|"sends model requests"| node_vlm
node_image -->|"encodes images"| node_artifacts

click node_main "https://github.com/ml-postech/epic/blob/main/src/graph/graph_main.py"
click node_cli "https://github.com/ml-postech/epic/blob/main/src/graph/cli.py"
click node_state "https://github.com/ml-postech/epic/blob/main/src/graph/state.py"
click node_pipeline "https://github.com/ml-postech/epic/blob/main/src/graph/node_vp_pipeline.py"
click node_context "https://github.com/ml-postech/epic/blob/main/src/graph/context.py"
click node_parser "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_parser.py"
click node_schema "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program.py"
click node_support "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_support.py"
click node_rewriter "https://github.com/ml-postech/epic/blob/main/src/graph/rewritten_prompt_generator.py"
click node_selector "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_action_selector.py"
click node_auditor "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_auditor.py"
click node_verifier "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_verifier.py"
click node_runtime "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_runtime_tools.py"
click node_toolset "https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_tools.py"
click node_depth "https://github.com/ml-postech/epic/blob/main/src/graph/depth.py"
click node_image "https://github.com/ml-postech/epic/blob/main/src/graph/image_runtime.py"
click node_models "https://github.com/ml-postech/epic/blob/main/src/graph/models.py"
click node_artifacts "https://github.com/ml-postech/epic/blob/main/src/graph/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_bench toneBlue
class node_state,node_pipeline,node_context toneAmber
class node_parser,node_schema,node_support,node_rewriter,node_selector,node_auditor toneMint
class node_verifier,node_runtime,node_toolset,node_depth,node_image,node_models toneRose
class node_artifacts,node_user,node_vlm,node_benchdata toneIndigo
```

## Components

### Entry points

- [Generation API](https://github.com/ml-postech/epic/blob/main/src/graph/graph_main.py): `src/graph/graph_main.py`
- [Run options](https://github.com/ml-postech/epic/blob/main/src/graph/cli.py): `src/graph/cli.py`
- **Benchmark runners**

### Refinement control

- [Run state](https://github.com/ml-postech/epic/blob/main/src/graph/state.py): `src/graph/state.py`
- [Refinement loop](https://github.com/ml-postech/epic/blob/main/src/graph/node_vp_pipeline.py): `src/graph/node_vp_pipeline.py`
- [VLM context](https://github.com/ml-postech/epic/blob/main/src/graph/context.py): `src/graph/context.py`

### Visual program

- [Program parser](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_parser.py): `src/graph/visual_program_parser.py`
- [Program schema](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program.py): `src/graph/visual_program.py`
- [Predicate vocabulary](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_support.py): `src/graph/visual_program_support.py`
- [Prompt rewriter](https://github.com/ml-postech/epic/blob/main/src/graph/rewritten_prompt_generator.py): `src/graph/rewritten_prompt_generator.py`
- [Action selector](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_action_selector.py): `src/graph/visual_program_action_selector.py`
- [Loop auditor](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_auditor.py): `src/graph/visual_program_auditor.py`

### Generation and verification

- [Predicate verifier](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_verifier.py): `src/graph/visual_program_verifier.py`
- [Verification tools](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_runtime_tools.py): `src/graph/visual_program_runtime_tools.py`
- [Region and depth tools](https://github.com/ml-postech/epic/blob/main/src/graph/visual_program_tools.py): `src/graph/visual_program_tools.py`
- [Depth estimation](https://github.com/ml-postech/epic/blob/main/src/graph/depth.py): `src/graph/depth.py`
- [Image generation](https://github.com/ml-postech/epic/blob/main/src/graph/image_runtime.py): `src/graph/image_runtime.py`
- [Model clients](https://github.com/ml-postech/epic/blob/main/src/graph/models.py): `src/graph/models.py`

### Results and benchmarks

- [Images and traces](https://github.com/ml-postech/epic/blob/main/src/graph/utils.py): `src/graph/utils.py`

### Other components

- **Prompt author**
- **VLM endpoint**
- **Benchmark prompts**

## Connections

- Prompt author → Generation API: submits prompt (evidence: `README.md`)
- Run options → Generation API: configures run (evidence: `src/graph/graph_main.py`)
- Benchmark runners → Generation API: invokes
- Benchmark prompts → Benchmark runners: supplies prompts (evidence: `README.md`)
- Generation API → Refinement loop: invokes (evidence: `src/graph/graph_main.py`)
- Generation API → VLM context: builds context (evidence: `src/graph/graph_main.py`)
- Refinement loop → Run state: updates (evidence: `src/graph/graph_main.py`)
- Refinement loop → Program parser: parses prompt (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Prompt rewriter: requests rewrites (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Action selector: selects actions (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Loop auditor: audits progress (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Predicate verifier: checks predicates (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Image generation: generates edits (evidence: `src/graph/node_vp_pipeline.py`)
- Refinement loop → Images and traces: saves results (evidence: `src/graph/graph_main.py`)
- Program parser → Program schema: builds program (evidence: `src/graph/visual_program_parser.py`)
- Program parser → Predicate vocabulary: uses vocabulary (evidence: `src/graph/visual_program_parser.py`)
- Prompt rewriter → Model clients: calls model (evidence: `src/graph/rewritten_prompt_generator.py`)
- Action selector → Program schema: reads predicates (evidence: `src/graph/visual_program_action_selector.py`)
- Action selector → Predicate verifier: uses verification (evidence: `src/graph/visual_program_action_selector.py`)
- Loop auditor → Model clients: calls model (evidence: `src/graph/visual_program_auditor.py`)
- Predicate verifier → Program schema: evaluates predicates (evidence: `src/graph/visual_program_verifier.py`)
- Predicate verifier → Region and depth tools: uses proposals (evidence: `src/graph/visual_program_verifier.py`)
- Verification tools → Region and depth tools: dispatches tools (evidence: `src/graph/visual_program_runtime_tools.py`)
- Verification tools → Depth estimation: estimates depth (evidence: `src/graph/visual_program_runtime_tools.py`)
- Image generation → Model clients: uses generation model (evidence: `src/graph/image_runtime.py`)
- Model clients → VLM endpoint: sends model requests (evidence: `README.md`)
- Image generation → Images and traces: encodes images (evidence: `src/graph/utils.py`)
