# zhezh/kddcup2026_champion architecture

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

- Interactive diagram: https://gitdiagram.com/zhezh/kddcup2026_champion
- Repository: https://github.com/zhezh/kddcup2026_champion

## Overview

This repository is a benchmark data-agent application: it reads task directories, analyzes tabular, document, and video context, and produces task predictions. The documented entry point is `zz_agent_v2.py`; sampled code confirms its video-result and table-relevance stages and a solver fallback. The tree and excerpts support the main capability areas, but not every handoff among agents, so uncertain wiring is omitted.

Main entry points: [`src/data_agent_baseline/zz_agent_v2.py`](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/zz_agent_v2.py) (Task runner), [`src/data_agent_baseline/video/build_video_input.py`](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/build_video_input.py) (Timeline assembly), [`src/data_agent_baseline/agents_v2/video_result_agent.py`](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/video_result_agent.py) (Video answer review), [`src/data_agent_baseline/doc_tools/doc_prepare.py`](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/doc_tools/doc_prepare.py) (Document structuring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Task orchestration"]
  node_agent["Task runner<br/>[zz_agent_v2.py]"]
  node_preflight["Preflight checks<br/>[preflight.py]"]
end

subgraph group_context["Task understanding"]
  node_relevance["Table relevance"]
  node_planning["Query planning<br/>[plan_agent.py]"]
  node_doc_relevance["Document relevance"]
end

subgraph group_data["Data preparation"]
  node_doc_agent["Document extraction<br/>[doc_agent.py]"]
  node_doc_prepare["Document structuring<br/>[doc_prepare.py]"]
  node_fanout["Section structuring<br/>[fanout_struct.py]"]
  node_schema["Schema inference"]
  node_extractor["Record extraction<br/>[doc_extractor.py]"]
  node_sqlite[("Structured document tables")]
end

subgraph group_solve["Query and prediction"]
  node_scaffold["Datasource setup<br/>[scaffold_tool.py]"]
  node_runtime["Datasource runtime"]
  node_explore["Data exploration<br/>[explore_tool.py]"]
  node_solver["Solver agent<br/>[solver_agent.py]"]
  node_run_solver["Solver execution<br/>[run_solver_tool.py]"]
end

subgraph group_video["Video analysis"]
  node_video_result["Video answer review"]
  node_video_build["Timeline assembly"]
  node_slides["Slide detection"]
  node_transcribe["Audio transcription"]
end

node_operator(("Benchmark operator"))
node_task_input["Task files"]
node_prediction["Task prediction"]
node_video_input["Video and audio"]
node_asr_service["Whisper service<br/>[server.py]"]
node_model(("Model API"))

node_operator -->|"starts run"| node_agent
node_task_input -->|"provides tasks"| node_agent
node_agent -->|"checks tasks"| node_preflight
node_agent -->|"requests analysis"| node_relevance
node_agent -->|"reviews video"| node_video_result
node_agent -->|"runs fallback"| node_run_solver
node_agent -->|"writes results"| node_prediction
node_doc_prepare -->|"structures documents"| node_fanout
node_fanout -->|"writes tables"| node_sqlite
node_doc_prepare -->|"stores tables"| node_sqlite
node_schema -->|"supplies schema"| node_extractor
node_scaffold -->|"reads tables"| node_sqlite
node_scaffold -->|"builds datasource"| node_runtime
node_explore -->|"queries datasource"| node_runtime
node_run_solver -->|"invokes solver"| node_solver
node_solver -->|"produces answer"| node_prediction
node_video_input -->|"provides media"| node_video_build
node_video_build -->|"extracts frames"| node_slides
node_video_build -->|"transcribes audio"| node_transcribe
node_transcribe -.->|"requests transcription"| node_asr_service
node_video_build -->|"provides timeline"| node_video_result
node_relevance -.->|"requests analysis"| node_model
node_planning -.->|"requests plan"| node_model
node_doc_relevance -.->|"requests analysis"| node_model
node_doc_agent -.->|"extracts records"| node_model
node_video_result -.->|"reviews answer"| node_model

click node_agent "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/zz_agent_v2.py"
click node_preflight "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/preflight.py"
click node_relevance "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/table_relevance_agent.py"
click node_planning "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/plan_agent.py"
click node_doc_relevance "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/doc_relevance_agent.py"
click node_doc_agent "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/doc_agent.py"
click node_doc_prepare "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/doc_tools/doc_prepare.py"
click node_fanout "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/doc_tools/fanout_struct.py"
click node_schema "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/schema_inference.py"
click node_extractor "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/doc_extractor.py"
click node_scaffold "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/scaffold_tool.py"
click node_runtime "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/datasource_runtime.py"
click node_explore "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/explore_tool.py"
click node_solver "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/solver_agent.py"
click node_run_solver "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/run_solver_tool.py"
click node_video_result "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/video_result_agent.py"
click node_video_build "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/build_video_input.py"
click node_slides "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/slide_coarse_det.py"
click node_transcribe "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/audio_transcribe.py"
click node_asr_service "https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/asr/server.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_agent,node_preflight toneBlue
class node_relevance,node_planning,node_doc_relevance toneAmber
class node_doc_agent,node_doc_prepare,node_fanout,node_schema,node_extractor,node_sqlite,node_model toneMint
class node_scaffold,node_runtime,node_explore,node_solver,node_run_solver,node_task_input,node_prediction toneRose
class node_video_result,node_video_build,node_slides,node_transcribe,node_operator,node_video_input toneIndigo
class node_asr_service toneTeal
```

## Components

### Task orchestration

- [Task runner](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/zz_agent_v2.py): `src/data_agent_baseline/zz_agent_v2.py`
- [Preflight checks](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/preflight.py): `src/data_agent_baseline/preflight.py`

### Task understanding

- [Table relevance](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/table_relevance_agent.py): `src/data_agent_baseline/agents_v2/table_relevance_agent.py`
- [Query planning](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/plan_agent.py): `src/data_agent_baseline/agents_v2/plan_agent.py`
- [Document relevance](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/doc_relevance_agent.py): `src/data_agent_baseline/agents_v2/doc_relevance_agent.py`

### Data preparation

- [Document extraction](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/doc_agent.py): `src/data_agent_baseline/agents_v2/doc_agent.py`
- [Document structuring](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/doc_tools/doc_prepare.py): `src/data_agent_baseline/doc_tools/doc_prepare.py`
- [Section structuring](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/doc_tools/fanout_struct.py): `src/data_agent_baseline/doc_tools/fanout_struct.py`
- [Schema inference](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/schema_inference.py): `src/data_agent_baseline/tools_v2/schema_inference.py`
- [Record extraction](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/doc_extractor.py): `src/data_agent_baseline/tools_v2/doc_extractor.py`
- **Structured document tables**

### Query and prediction

- [Datasource setup](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/scaffold_tool.py): `src/data_agent_baseline/tools_v2/scaffold_tool.py`
- [Datasource runtime](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/datasource_runtime.py): `src/data_agent_baseline/tools_v2/datasource_runtime.py`
- [Data exploration](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/explore_tool.py): `src/data_agent_baseline/tools_v2/explore_tool.py`
- [Solver agent](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/solver_agent.py): `src/data_agent_baseline/agents_v2/solver_agent.py`
- [Solver execution](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/tools_v2/run_solver_tool.py): `src/data_agent_baseline/tools_v2/run_solver_tool.py`

### Video analysis

- [Video answer review](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/agents_v2/video_result_agent.py): `src/data_agent_baseline/agents_v2/video_result_agent.py`
- [Timeline assembly](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/build_video_input.py): `src/data_agent_baseline/video/build_video_input.py`
- [Slide detection](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/slide_coarse_det.py): `src/data_agent_baseline/video/slide_coarse_det.py`
- [Audio transcription](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/video/audio_transcribe.py): `src/data_agent_baseline/video/audio_transcribe.py`

### Other components

- **Benchmark operator**
- **Task files**
- **Task prediction**
- **Video and audio**
- [Whisper service](https://github.com/zhezh/kddcup2026_champion/blob/main/src/data_agent_baseline/asr/server.py): `src/data_agent_baseline/asr/server.py`
- **Model API**

## Connections

- Benchmark operator → Task runner: starts run
- Task files → Task runner: provides tasks
- Task runner → Preflight checks: checks tasks
- Task runner → Table relevance: requests analysis
- Task runner → Video answer review: reviews video
- Task runner → Solver execution: runs fallback
- Task runner → Task prediction: writes results
- Document structuring → Section structuring: structures documents
- Section structuring → Structured document tables: writes tables
- Document structuring → Structured document tables: stores tables
- Schema inference → Record extraction: supplies schema
- Datasource setup → Structured document tables: reads tables
- Datasource setup → Datasource runtime: builds datasource
- Data exploration → Datasource runtime: queries datasource
- Solver execution → Solver agent: invokes solver
- Solver agent → Task prediction: produces answer
- Video and audio → Timeline assembly: provides media
- Timeline assembly → Slide detection: extracts frames
- Timeline assembly → Audio transcription: transcribes audio
- Audio transcription → Whisper service: requests transcription
- Timeline assembly → Video answer review: provides timeline
- Table relevance → Model API: requests analysis
- Query planning → Model API: requests plan
- Document relevance → Model API: requests analysis
- Document extraction → Model API: extracts records
- Video answer review → Model API: reviews answer