# jumperchen/hymir architecture

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

- Interactive diagram: https://gitdiagram.com/jumperchen/hymir
- Repository: https://github.com/jumperchen/hymir

## Overview

HyMIR is a Text-to-SQL research system: it generates a typed semantic plan, compiles that plan into SQL, and evaluates predictions against benchmark queries. The main user workflow is running an experiment over benchmark data and database schemas, then measuring query results and accuracy. A separate oracle encoder converts reference SQL into HyMIR plans for conversion and round-trip evaluation. The README documents additional benchmark and model configurations, but sampled excerpts do not expose every runner call, so uncertain wiring is omitted.

Main entry points: [`scripts/run_experiment.py`](https://github.com/jumperchen/hymir/blob/main/scripts/run_experiment.py) (Experiment runner), [`src/dsl_generator.py`](https://github.com/jumperchen/hymir/blob/main/src/dsl_generator.py) (Plan generator), [`src/sql_generator.py`](https://github.com/jumperchen/hymir/blob/main/src/sql_generator.py) (SQL generator), [`src/evaluator.py`](https://github.com/jumperchen/hymir/blob/main/src/evaluator.py) (SQL evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Experiment Workflow"]
  node_experiment_runner["Experiment runner<br/>[run_experiment.py]"]
  node_dataset_loader["Dataset loader<br/>[dataset_loader.py]"]
  node_schema_sampler["Schema sampler"]
end

subgraph group_planning["HyMIR Planning"]
  node_dsl_generator["Plan generator<br/>[dsl_generator.py]"]
  node_dsl_validation["Plan validation<br/>[dsl_validation.py]"]
  node_semantic_catalog["Semantic catalog"]
  node_oracle_encoder["Oracle encoder<br/>[oracle_dsl.py]"]
end

subgraph group_sql["SQL Generation"]
  node_compiler["Plan compiler"]
  node_sql_generator["SQL generator<br/>[sql_generator.py]"]
  node_sql_repair["SQL postprocessing"]
  node_ast_rewriter["AST rewriter<br/>[ast_rewriter.py]"]
  node_llm_client["API model client<br/>[llm_client.py]"]
  node_qwen_client["Local Qwen client<br/>[qwen_dsl_client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["SQL evaluator<br/>[evaluator.py]"]
  node_canonicalizer["SQL canonicalizer"]
end

node_engineer(("Experiment user"))
node_benchmark["Benchmark data"]
node_database[("SQLite database")]

node_engineer -->|"runs experiment"| node_experiment_runner
node_benchmark -->|"provides samples"| node_dataset_loader
node_experiment_runner -->|"loads data"| node_dataset_loader
node_dataset_loader -->|"returns samples"| node_experiment_runner
node_experiment_runner -->|"prepares schema"| node_schema_sampler
node_database -->|"provides values"| node_schema_sampler
node_experiment_runner -->|"requests plan"| node_dsl_generator
node_dsl_generator -->|"validates plan"| node_dsl_validation
node_dsl_generator -.->|"generates locally"| node_qwen_client
node_dsl_generator -.->|"requests generation"| node_llm_client
node_experiment_runner -->|"requests SQL"| node_sql_generator
node_sql_generator -->|"requests generation"| node_llm_client
node_experiment_runner -->|"compiles plan"| node_compiler
node_compiler -->|"reads schema"| node_database
node_experiment_runner -->|"evaluates prediction"| node_evaluator
node_evaluator -->|"executes queries"| node_database
node_evaluator -->|"canonicalizes SQL"| node_canonicalizer
node_experiment_runner -.->|"encodes reference SQL"| node_oracle_encoder
node_oracle_encoder -->|"uses labels"| node_semantic_catalog
node_sql_generator -.->|"repairs SQL"| node_sql_repair
node_sql_repair -.->|"rewrites AST"| node_ast_rewriter

click node_experiment_runner "https://github.com/jumperchen/hymir/blob/main/scripts/run_experiment.py"
click node_dataset_loader "https://github.com/jumperchen/hymir/blob/main/src/dataset_loader.py"
click node_schema_sampler "https://github.com/jumperchen/hymir/blob/main/src/schema_value_sampler.py"
click node_dsl_generator "https://github.com/jumperchen/hymir/blob/main/src/dsl_generator.py"
click node_dsl_validation "https://github.com/jumperchen/hymir/blob/main/src/dsl_validation.py"
click node_semantic_catalog "https://github.com/jumperchen/hymir/blob/main/src/semantic_catalog.py"
click node_oracle_encoder "https://github.com/jumperchen/hymir/blob/main/src/oracle_dsl.py"
click node_compiler "https://github.com/jumperchen/hymir/blob/main/src/rule_based_dsl_to_sql.py"
click node_sql_generator "https://github.com/jumperchen/hymir/blob/main/src/sql_generator.py"
click node_sql_repair "https://github.com/jumperchen/hymir/blob/main/src/sql_postprocessing.py"
click node_ast_rewriter "https://github.com/jumperchen/hymir/blob/main/src/ast_rewriter.py"
click node_llm_client "https://github.com/jumperchen/hymir/blob/main/src/llm_client.py"
click node_qwen_client "https://github.com/jumperchen/hymir/blob/main/src/qwen_dsl_client.py"
click node_evaluator "https://github.com/jumperchen/hymir/blob/main/src/evaluator.py"
click node_canonicalizer "https://github.com/jumperchen/hymir/blob/main/src/sql_canonicalizer.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_experiment_runner,node_dataset_loader,node_schema_sampler,node_engineer toneBlue
class node_dsl_generator,node_dsl_validation,node_semantic_catalog,node_oracle_encoder,node_database toneAmber
class node_compiler,node_sql_generator,node_sql_repair,node_ast_rewriter,node_llm_client,node_qwen_client toneMint
class node_evaluator,node_canonicalizer toneRose
class node_benchmark toneIndigo
```

## Components

### Experiment Workflow

- [Experiment runner](https://github.com/jumperchen/hymir/blob/main/scripts/run_experiment.py): `scripts/run_experiment.py`
- [Dataset loader](https://github.com/jumperchen/hymir/blob/main/src/dataset_loader.py): `src/dataset_loader.py`
- [Schema sampler](https://github.com/jumperchen/hymir/blob/main/src/schema_value_sampler.py): `src/schema_value_sampler.py`

### HyMIR Planning

- [Plan generator](https://github.com/jumperchen/hymir/blob/main/src/dsl_generator.py): `src/dsl_generator.py`
- [Plan validation](https://github.com/jumperchen/hymir/blob/main/src/dsl_validation.py): `src/dsl_validation.py`
- [Semantic catalog](https://github.com/jumperchen/hymir/blob/main/src/semantic_catalog.py): `src/semantic_catalog.py`
- [Oracle encoder](https://github.com/jumperchen/hymir/blob/main/src/oracle_dsl.py): `src/oracle_dsl.py`

### SQL Generation

- [Plan compiler](https://github.com/jumperchen/hymir/blob/main/src/rule_based_dsl_to_sql.py): `src/rule_based_dsl_to_sql.py`
- [SQL generator](https://github.com/jumperchen/hymir/blob/main/src/sql_generator.py): `src/sql_generator.py`
- [SQL postprocessing](https://github.com/jumperchen/hymir/blob/main/src/sql_postprocessing.py): `src/sql_postprocessing.py`
- [AST rewriter](https://github.com/jumperchen/hymir/blob/main/src/ast_rewriter.py): `src/ast_rewriter.py`
- [API model client](https://github.com/jumperchen/hymir/blob/main/src/llm_client.py): `src/llm_client.py`
- [Local Qwen client](https://github.com/jumperchen/hymir/blob/main/src/qwen_dsl_client.py): `src/qwen_dsl_client.py`

### Evaluation

- [SQL evaluator](https://github.com/jumperchen/hymir/blob/main/src/evaluator.py): `src/evaluator.py`
- [SQL canonicalizer](https://github.com/jumperchen/hymir/blob/main/src/sql_canonicalizer.py): `src/sql_canonicalizer.py`

### Other components

- **Experiment user**
- **Benchmark data**
- **SQLite database**

## Connections

- Experiment user → Experiment runner: runs experiment
- Benchmark data → Dataset loader: provides samples
- Experiment runner → Dataset loader: loads data
- Dataset loader → Experiment runner: returns samples
- Experiment runner → Schema sampler: prepares schema
- SQLite database → Schema sampler: provides values
- Experiment runner → Plan generator: requests plan
- Plan generator → Plan validation: validates plan
- Plan generator → Local Qwen client: generates locally
- Plan generator → API model client: requests generation
- Experiment runner → SQL generator: requests SQL
- SQL generator → API model client: requests generation
- Experiment runner → Plan compiler: compiles plan
- Plan compiler → SQLite database: reads schema
- Experiment runner → SQL evaluator: evaluates prediction
- SQL evaluator → SQLite database: executes queries
- SQL evaluator → SQL canonicalizer: canonicalizes SQL
- Experiment runner → Oracle encoder: encodes reference SQL
- Oracle encoder → Semantic catalog: uses labels
- SQL generator → SQL postprocessing: repairs SQL
- SQL postprocessing → AST rewriter: rewrites AST