# xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place architecture

> Architecture diagram of the GitHub repository xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place
- Repository: https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place

## Overview

This repository reproduces a competition solution: it derives synthetic reasoning problems and solver-generated traces from Kaggle training data, fine-tunes a Nemotron LoRA adapter, and evaluates or packages the result. The graph emphasizes that workflow and the separate local evaluation viewer. Most workflow links are documented in the README; source excerpts and the SOURCE INDEX support the solver, trace, training, and viewer relationships. Unsampled implementation details are represented only at their documented subsystem level.

Main entry points: [`src/nvidia_nemotron_model_reasoning_challenge/sft.py`](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/sft.py) (SFT pipeline), [`src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py`](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py) (Solver dispatch), [`scripts/generate_reasoning_dataset.py`](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/generate_reasoning_dataset.py) (Generate traces), [`scripts/create_dataset_split.py`](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/create_dataset_split.py) (Create split)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_split_script["Create split"]
  node_splitter["Dataset splitting<br/>[dataset_split.py]"]
  node_analysis_script["Build priors"]
  node_analysis["Problem analysis"]
  node_prior["Equation prior"]
end

subgraph group_reasoning["Problems and traces"]
  node_problem_script["Generate problems"]
  node_problem_generation["Synthetic generation"]
  node_trace_script["Generate traces"]
  node_solver_registry["Solver dispatch<br/>[__init__.py]"]
  node_solvers["Rule solvers"]
  node_trace_generation["Trace generation<br/>[easy_reasoning.py]"]
  node_aggregates["SFT trace sets"]
end

subgraph group_model["Training and evaluation"]
  node_train_script["Train adapter<br/>[train_sft.py]"]
  node_sft["SFT pipeline<br/>[sft.py]"]
  node_adapter_package["Submission packaging"]
  node_evaluation["Model evaluation<br/>[generic.py]"]
  node_solver_evaluation["Solver evaluation"]
end

subgraph group_viewer["Result inspection"]
  node_viewer_app["Evaluation viewer"]
  node_viewer_data["Viewer data access<br/>[viewer_data.py]"]
end

node_competition(("Kaggle data"))
node_model_service["Nemotron model"]

node_competition -->|"provides CSV"| node_split_script
node_split_script -->|"creates split"| node_splitter
node_competition -->|"provides CSV"| node_analysis_script
node_analysis_script -->|"collects statistics"| node_analysis
node_analysis -->|"builds prior"| node_prior
node_problem_script -->|"generates problems"| node_problem_generation
node_prior -->|"guides sampling"| node_problem_generation
node_trace_script -->|"generates traces"| node_trace_generation
node_trace_generation -->|"requests solutions"| node_solver_registry
node_solver_registry -->|"dispatches to"| node_solvers
node_trace_script -->|"builds trace sets"| node_aggregates
node_aggregates -->|"supplies training data"| node_train_script
node_train_script -->|"runs training"| node_sft
node_sft -->|"fine-tunes"| node_model_service
node_sft -->|"produces checkpoint"| node_adapter_package
node_model_service -->|"generates answers"| node_evaluation
node_solver_evaluation -->|"evaluates solvers"| node_solver_registry
node_evaluation -->|"writes results"| node_viewer_data
node_viewer_app -->|"loads results"| node_viewer_data

click node_split_script "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/create_dataset_split.py"
click node_splitter "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/dataset_split.py"
click node_analysis_script "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/analysis/collect_problem_analysis_stats.py"
click node_analysis "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/problem_analysis"
click node_prior "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/problem_generation/problem_types/equation_transformation_prior.py"
click node_problem_script "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/generate_problems.py"
click node_problem_generation "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/problem_generation"
click node_trace_script "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/generate_reasoning_dataset.py"
click node_solver_registry "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py"
click node_solvers "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/solver"
click node_trace_generation "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/generate/easy_reasoning.py"
click node_aggregates "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/tools/merge_sft_jsonl_sources.py"
click node_train_script "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/train_sft.py"
click node_sft "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/sft.py"
click node_adapter_package "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/tools/package_kaggle_submission.py"
click node_evaluation "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/eval/generic.py"
click node_solver_evaluation "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/evaluate_rule_solvers.py"
click node_viewer_app "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/app/evaluation_viewer.py"
click node_viewer_data "https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/viewer_data.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_split_script,node_splitter,node_analysis_script,node_analysis,node_prior toneBlue
class node_problem_script,node_problem_generation,node_trace_script,node_solver_registry,node_solvers,node_trace_generation,node_aggregates toneAmber
class node_train_script,node_sft,node_adapter_package,node_evaluation,node_solver_evaluation toneMint
class node_viewer_app,node_viewer_data toneRose
class node_competition,node_model_service toneIndigo
```

## Components

### Data preparation

- [Create split](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/create_dataset_split.py): `scripts/create_dataset_split.py`
- [Dataset splitting](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/dataset_split.py): `src/nvidia_nemotron_model_reasoning_challenge/dataset_split.py`
- [Build priors](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/analysis/collect_problem_analysis_stats.py): `scripts/analysis/collect_problem_analysis_stats.py`
- [Problem analysis](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/problem_analysis): `src/nvidia_nemotron_model_reasoning_challenge/problem_analysis`
- [Equation prior](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/problem_generation/problem_types/equation_transformation_prior.py): `src/nvidia_nemotron_model_reasoning_challenge/problem_generation/problem_types/equation_transformation_prior.py`

### Problems and traces

- [Generate problems](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/generate_problems.py): `scripts/generate_problems.py`
- [Synthetic generation](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/problem_generation): `src/nvidia_nemotron_model_reasoning_challenge/problem_generation`
- [Generate traces](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/generate_reasoning_dataset.py): `scripts/generate_reasoning_dataset.py`
- [Solver dispatch](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py): `src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py`
- [Rule solvers](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/tree/main/src/nvidia_nemotron_model_reasoning_challenge/solver): `src/nvidia_nemotron_model_reasoning_challenge/solver`
- [Trace generation](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/generate/easy_reasoning.py): `src/nvidia_nemotron_model_reasoning_challenge/generate/easy_reasoning.py`
- [SFT trace sets](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/tools/merge_sft_jsonl_sources.py): `scripts/tools/merge_sft_jsonl_sources.py`

### Training and evaluation

- [Train adapter](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/train_sft.py): `scripts/train_sft.py`
- [SFT pipeline](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/sft.py): `src/nvidia_nemotron_model_reasoning_challenge/sft.py`
- [Submission packaging](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/tools/package_kaggle_submission.py): `scripts/tools/package_kaggle_submission.py`
- [Model evaluation](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/eval/generic.py): `src/nvidia_nemotron_model_reasoning_challenge/eval/generic.py`
- [Solver evaluation](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/scripts/evaluate_rule_solvers.py): `scripts/evaluate_rule_solvers.py`

### Result inspection

- [Evaluation viewer](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/app/evaluation_viewer.py): `app/evaluation_viewer.py`
- [Viewer data access](https://github.com/xrwr/kaggle-nvidia-nemotron-model-reasoning-challenge-1st-place/blob/main/src/nvidia_nemotron_model_reasoning_challenge/viewer_data.py): `src/nvidia_nemotron_model_reasoning_challenge/viewer_data.py`

### Other components

- **Kaggle data**
- **Nemotron model**

## Connections

- Kaggle data → Create split: provides CSV (evidence: `README.md`)
- Create split → Dataset splitting: creates split (evidence: `README.md`)
- Kaggle data → Build priors: provides CSV (evidence: `README.md`)
- Build priors → Problem analysis: collects statistics (evidence: `scripts/analysis/collect_problem_analysis_stats.py`)
- Problem analysis → Equation prior: builds prior (evidence: `README.md`)
- Generate problems → Synthetic generation: generates problems (evidence: `README.md`)
- Equation prior → Synthetic generation: guides sampling (evidence: `src/nvidia_nemotron_model_reasoning_challenge/problem_generation/problem_types/equation_transformation_generator.py`)
- Generate traces → Trace generation: generates traces (evidence: `README.md`)
- Trace generation → Solver dispatch: requests solutions (evidence: `src/nvidia_nemotron_model_reasoning_challenge/generate/easy_reasoning.py`)
- Solver dispatch → Rule solvers: dispatches to (evidence: `src/nvidia_nemotron_model_reasoning_challenge/solver/__init__.py`)
- Generate traces → SFT trace sets: builds trace sets (evidence: `README.md`)
- SFT trace sets → Train adapter: supplies training data (evidence: `README.md`)
- Train adapter → SFT pipeline: runs training (evidence: `scripts/train_sft.py`)
- SFT pipeline → Nemotron model: fine-tunes (evidence: `README.md`)
- SFT pipeline → Submission packaging: produces checkpoint (evidence: `README.md`)
- Nemotron model → Model evaluation: generates answers (evidence: `README.md`)
- Solver evaluation → Solver dispatch: evaluates solvers (evidence: `README.md`)
- Model evaluation → Viewer data access: writes results (evidence: `src/nvidia_nemotron_model_reasoning_challenge/eval/generic.py`)
- Evaluation viewer → Viewer data access: loads results (evidence: `app/evaluation_viewer.py`)
