# kaiwen-zhu/agenticir architecture

> Architecture diagram of the GitHub repository kaiwen-zhu/agenticir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaiwen-zhu/agenticir
- Repository: https://github.com/kaiwen-zhu/agenticir

## Overview

AgenticIR restores complexly degraded images by assessing degradation, planning an ordered sequence of restoration subtasks, executing restoration tools, and evaluating results to select outputs or revise the plan. It can use learned experience and rollback; the README also documents synthetic degradation data generation, exploration and distillation, and evaluation. Source excerpts are partial, so links are limited to documented capabilities or visible ownership; the exact wiring of unsampled modules is not asserted.

Main entry points: [`pipeline/iragent.py`](https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/iragent.py) (IR agent), [`llm/depictqa.py`](https://github.com/kaiwen-zhu/agenticir/blob/main/llm/depictqa.py) (LLM adapters), [`llm/gpt4.py`](https://github.com/kaiwen-zhu/agenticir/blob/main/llm/gpt4.py) (GPT-4 adapter), [`exploration/explore.py`](https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/explore.py) (Experience exploration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Restoration runtime"]
  node_infer["Inference entry<br/>[infer.py]"]
  node_agent["IR agent<br/>[iragent.py]"]
  node_prompts["Planning prompts<br/>[prompts.py]"]
  node_llm["LLM adapters<br/>[depictqa.py]"]
  node_gpt["GPT-4 adapter<br/>[gpt4.py]"]
  node_base["LLM base<br/>[base_llm.py]"]
  node_tree["Image workflow tree<br/>[img_tree.py]"]
end

subgraph group_tools["Restoration tools"]
  node_executor["Tool dispatcher<br/>[__init__.py]"]
  node_tool["Tool runner<br/>[tool.py]"]
  node_multitool["Restoration models<br/>[multitask_tools.py]"]
  node_subtasks["Restoration subtasks"]
end

subgraph group_learning["Experience and data"]
  node_synthesize["Degradation synthesis<br/>[synthesize.py]"]
  node_degradation["Degradation transforms"]
  node_explore_seq["Exploration sequences<br/>[exhaust_seq.py]"]
  node_explore["Experience exploration<br/>[explore.py]"]
  node_distill["Knowledge distillation<br/>[distill.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_score["Score computation<br/>[compute_scores.py]"]
  node_compare["Method comparison<br/>[compare_methods.py]"]
end

node_user(("Image user"))
node_model_service(("Model services"))
node_image_data[("Clean images and depth")]

node_user -->|"submits image"| node_infer
node_infer -->|"starts restoration"| node_agent
node_agent -->|"formats requests"| node_prompts
node_agent -->|"plans and reasons"| node_gpt
node_agent -->|"assesses results"| node_llm
node_gpt -->|"uses base"| node_base
node_llm -->|"uses base"| node_base
node_gpt -.->|"queries model"| node_model_service
node_llm -.->|"queries model"| node_model_service
node_agent -->|"dispatches subtasks"| node_executor
node_executor -->|"runs tools"| node_tool
node_tool -->|"invokes model adapters"| node_multitool
node_multitool -->|"handles restoration tasks"| node_subtasks
node_agent -->|"records workflow"| node_tree
node_synthesize -->|"applies transforms"| node_degradation
node_image_data -->|"supplies source data"| node_synthesize
node_explore_seq -->|"generates tool sequences"| node_executor
node_explore -->|"evaluates images"| node_llm
node_explore -->|"records explorations"| node_tree
node_distill -->|"summarizes experience"| node_explore
node_score -->|"provides scores"| node_compare

click node_infer "https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/infer.py"
click node_agent "https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/iragent.py"
click node_prompts "https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/prompts.py"
click node_llm "https://github.com/kaiwen-zhu/agenticir/blob/main/llm/depictqa.py"
click node_gpt "https://github.com/kaiwen-zhu/agenticir/blob/main/llm/gpt4.py"
click node_base "https://github.com/kaiwen-zhu/agenticir/blob/main/llm/base_llm.py"
click node_executor "https://github.com/kaiwen-zhu/agenticir/blob/main/executor/__init__.py"
click node_tool "https://github.com/kaiwen-zhu/agenticir/blob/main/executor/tool.py"
click node_multitool "https://github.com/kaiwen-zhu/agenticir/blob/main/executor/multitask_tools.py"
click node_subtasks "https://github.com/kaiwen-zhu/agenticir/tree/main/executor"
click node_tree "https://github.com/kaiwen-zhu/agenticir/blob/main/utils/img_tree.py"
click node_synthesize "https://github.com/kaiwen-zhu/agenticir/blob/main/dataset/synthesize.py"
click node_degradation "https://github.com/kaiwen-zhu/agenticir/blob/main/dataset/add_single_degradation.py"
click node_explore_seq "https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/exhaust_seq.py"
click node_explore "https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/explore.py"
click node_distill "https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/distill.py"
click node_score "https://github.com/kaiwen-zhu/agenticir/blob/main/eval/compute_scores.py"
click node_compare "https://github.com/kaiwen-zhu/agenticir/blob/main/eval/compare_methods.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_infer,node_agent,node_prompts,node_llm,node_gpt,node_base,node_tree,node_user toneBlue
class node_executor,node_tool,node_multitool,node_subtasks,node_image_data toneAmber
class node_synthesize,node_degradation,node_explore_seq,node_explore,node_distill toneMint
class node_score,node_compare toneRose
class node_model_service toneIndigo
```

## Components

### Restoration runtime

- [Inference entry](https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/infer.py): `pipeline/infer.py`
- [IR agent](https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/iragent.py): `pipeline/iragent.py`
- [Planning prompts](https://github.com/kaiwen-zhu/agenticir/blob/main/pipeline/prompts.py): `pipeline/prompts.py`
- [LLM adapters](https://github.com/kaiwen-zhu/agenticir/blob/main/llm/depictqa.py): `llm/depictqa.py`
- [GPT-4 adapter](https://github.com/kaiwen-zhu/agenticir/blob/main/llm/gpt4.py): `llm/gpt4.py`
- [LLM base](https://github.com/kaiwen-zhu/agenticir/blob/main/llm/base_llm.py): `llm/base_llm.py`
- [Image workflow tree](https://github.com/kaiwen-zhu/agenticir/blob/main/utils/img_tree.py): `utils/img_tree.py`

### Restoration tools

- [Tool dispatcher](https://github.com/kaiwen-zhu/agenticir/blob/main/executor/__init__.py): `executor/__init__.py`
- [Tool runner](https://github.com/kaiwen-zhu/agenticir/blob/main/executor/tool.py): `executor/tool.py`
- [Restoration models](https://github.com/kaiwen-zhu/agenticir/blob/main/executor/multitask_tools.py): `executor/multitask_tools.py`
- [Restoration subtasks](https://github.com/kaiwen-zhu/agenticir/tree/main/executor): `executor`

### Experience and data

- [Degradation synthesis](https://github.com/kaiwen-zhu/agenticir/blob/main/dataset/synthesize.py): `dataset/synthesize.py`
- [Degradation transforms](https://github.com/kaiwen-zhu/agenticir/blob/main/dataset/add_single_degradation.py): `dataset/add_single_degradation.py`
- [Exploration sequences](https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/exhaust_seq.py): `exploration/exhaust_seq.py`
- [Experience exploration](https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/explore.py): `exploration/explore.py`
- [Knowledge distillation](https://github.com/kaiwen-zhu/agenticir/blob/main/exploration/distill.py): `exploration/distill.py`

### Evaluation

- [Score computation](https://github.com/kaiwen-zhu/agenticir/blob/main/eval/compute_scores.py): `eval/compute_scores.py`
- [Method comparison](https://github.com/kaiwen-zhu/agenticir/blob/main/eval/compare_methods.py): `eval/compare_methods.py`

### Other components

- **Image user**
- **Model services**
- **Clean images and depth**

## Connections

- Image user → Inference entry: submits image
- Inference entry → IR agent: starts restoration
- IR agent → Planning prompts: formats requests
- IR agent → GPT-4 adapter: plans and reasons
- IR agent → LLM adapters: assesses results
- GPT-4 adapter → LLM base: uses base
- LLM adapters → LLM base: uses base
- GPT-4 adapter → Model services: queries model
- LLM adapters → Model services: queries model
- IR agent → Tool dispatcher: dispatches subtasks
- Tool dispatcher → Tool runner: runs tools
- Tool runner → Restoration models: invokes model adapters
- Restoration models → Restoration subtasks: handles restoration tasks
- IR agent → Image workflow tree: records workflow
- Degradation synthesis → Degradation transforms: applies transforms
- Clean images and depth → Degradation synthesis: supplies source data
- Exploration sequences → Tool dispatcher: generates tool sequences
- Experience exploration → LLM adapters: evaluates images
- Experience exploration → Image workflow tree: records explorations
- Knowledge distillation → Experience exploration: summarizes experience
- Score computation → Method comparison: provides scores