# devlup-labs/autosetter architecture

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

- Interactive diagram: https://gitdiagram.com/devlup-labs/autosetter
- Repository: https://github.com/devlup-labs/autosetter

## Overview

#### Purpose and entry point
AutoSetter converts a problem-statement image or PDF into a reviewable Codeforces/Polygon-style package: specification, statement, C++ solution/validator/generator/checker, accepted tests, validation report, and manifest. The CLI entry point is `app.py`; its output pipeline is represented concretely under `example/01_intake` through `example/04_package`.

#### 1. Intake and specification extraction
`app.py` accepts an image/PDF and produces the canonical `problem.json` specification. Image/PDF handling and structured-model-output processing are separated into `utils/image_parser.py` and `utils/json_generator.py`. The extraction prompt is `prompts/json_extraction.txt`; `example/01_intake/problem.json` shows the handoff format.

#### 2. Local model boundary
All generation is driven by local Qwen models exposed through Ollama, isolated behind `utils/ollama_client.py`. Prompt selection/loading is centralized in `utils/prompt_loader.py`, with artifact-specific contracts in `prompts/statement.txt`, `prompts/solution.txt`, `prompts/validator.txt`, `prompts/generator.txt`, and `prompts/checker.txt`. This boundary allows most pipeline logic to run without a model service.

#### 3. Artifact generation
The normalized JSON spec is faned out into independently generated deliverables: Markdown statement plus four C++ programs. File materialization is handled by `utils/file_generator.py`; the expected generated set is illustrated by `example/02_build/statement.md`, `example/02_build/solution.cpp`, and `example/02_build/validator.cpp`. Generated C++ is compiled against the vendored `third_party/testlib.h`.

#### 4. Test planning and validation pipeline
`utils/test_plan.py` defines test-shape intent (boundary, structural, and multi-case distributions), rather than relying only on random seeds. `utils/test_pipeline.py` performs the critical control flow: compile artifacts; verify validator acceptance of statement samples; generate candidates; reject validator-invalid inputs; solve accepted inputs; and run the checker on reference answers. Outputs include numbered `.in`/`.ans` pairs and a diagnosis-bearing report, as shown in `example/03_validate/validation_report.json`.

#### 5. Independent correctness gates
Release readiness is deliberately stricter than successful generation. The validator is checked against problem samples and against generated tests. The checker must reject deliberately bad outputs (empty, truncated, perturbed), preventing a checker that merely accepts matching files. Test-plan conformance checks generator behavior, including deterministic minimum-case generation. These gates determine whether the process exits successfully or returns the “not fit to release” status.

#### 6. Packaging boundary
`utils/packager.py` converts accepted artifacts and tests into the portable package layout: problem metadata, statement, source files, solutions, tests, report, and manifest. `example/04_package/manifest.json`, `example/04_package/problem.json`, and `example/04_package/tests` demonstrate the release bundle. The manifest’s readiness flag and validation report are the human-review decision surface.

#### 7. Execution infrastructure
Python is the orchestration runtime; generated contestants/tooling are C++ compiled with `g++`. A separate Node.js sandbox service executes untrusted C++ inside Docker/nsjail: `sandbox/server/src/server.js`, `sandbox/server/src/executor.js`, and `sandbox/server/src/config.js`. Docker construction is in `sandbox/docker/Dockerfile`; configuration enforces CPU, memory, PID, and network limits. Ollama is the only required external model service.

Main entry points: [`utils/packager.py`](https://github.com/devlup-labs/autosetter/blob/main/utils/packager.py) (Package builder), [`example/01_intake/problem.json`](https://github.com/devlup-labs/autosetter/blob/main/example/01_intake/problem.json) (Canonical problem spec), [`utils/json_generator.py`](https://github.com/devlup-labs/autosetter/blob/main/utils/json_generator.py) (Spec extractor), [`example/02_build/solution.cpp`](https://github.com/devlup-labs/autosetter/blob/main/example/02_build/solution.cpp) (Generated statement and C++)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake"]
  node_cli["AutoSetter CLI<br/>Python entry point<br/>[app.py]"]
  node_image_parser["Image/PDF parser<br/>input decoder<br/>[image_parser.py]"]
  node_json_generator["Spec extractor<br/>structured generation<br/>[json_generator.py]"]
  node_extraction_prompt["Extraction prompt<br/>prompt contract"]
  node_problem_spec["Canonical problem spec<br/>JSON artifact<br/>[problem.json]"]
end

subgraph group_generation["Model generation"]
  node_prompt_loader["Prompt loader<br/>prompt registry<br/>[prompt_loader.py]"]
  node_ollama{{"Local Qwen via Ollama<br/>model service<br/>[ollama_client.py]"}}
  node_artifact_prompts["Artifact prompts<br/>prompt contracts<br/>[statement.txt]"]
  node_file_generator["Artifact materializer<br/>file generation<br/>[file_generator.py]"]
  node_build_artifacts["Generated statement and C++<br/>build artifacts<br/>[solution.cpp]"]
  node_testlib["testlib<br/>C++ validation library<br/>[testlib.h]"]
end

subgraph group_validation["Validation"]
  node_test_plan["Test-shape plan<br/>test policy<br/>[test_plan.py]"]
  node_test_pipeline["Compile and test pipeline<br/>validation orchestrator<br/>[test_pipeline.py]"]
  node_accepted_tests["Accepted test pairs<br/>test corpus"]
  node_validation_report["Validation report<br/>release gate report"]
end

subgraph group_release["Release package"]
  node_packager["Package builder<br/>release assembly<br/>[packager.py]"]
  node_release_bundle["Portable problem package<br/>release bundle<br/>[manifest.json]"]
end

subgraph group_sandbox["Execution sandbox"]
  node_sandbox_server["Sandbox service<br/>Node.js execution API<br/>[server.js]"]
  node_sandbox_executor["Sandbox executor<br/>Node.js runner<br/>[executor.js]"]
  node_sandbox_limits["Sandbox limits<br/>resource policy<br/>[config.js]"]
  node_sandbox_image{{"Sandbox container<br/>Docker/nsjail runtime"}}
end

node_cli -->|"reads input"| node_image_parser
node_image_parser -->|"image/PDF content"| node_json_generator
node_extraction_prompt -->|"extraction contract"| node_json_generator
node_json_generator -->|"structured request"| node_ollama
node_json_generator -->|"writes"| node_problem_spec
node_problem_spec -->|"generation context"| node_file_generator
node_prompt_loader -->|"loads"| node_artifact_prompts
node_artifact_prompts -->|"artifact requests"| node_ollama
node_ollama -->|"generated content"| node_file_generator
node_file_generator -->|"writes"| node_build_artifacts
node_testlib -->|"compiled against"| node_build_artifacts
node_problem_spec -->|"defines coverage for"| node_test_plan
node_build_artifacts -->|"compile and execute"| node_test_pipeline
node_test_plan -->|"candidate distributions"| node_test_pipeline
node_test_pipeline -->|"accepted .in/.ans pairs"| node_accepted_tests
node_test_pipeline -->|"diagnoses and gates"| node_validation_report
node_build_artifacts -->|"accepted sources"| node_packager
node_problem_spec -->|"metadata"| node_packager
node_accepted_tests -->|"tests"| node_packager
node_validation_report -->|"readiness decision"| node_packager
node_packager -->|"assembles"| node_release_bundle
node_sandbox_server -->|"dispatches"| node_sandbox_executor
node_sandbox_limits -->|"enforces limits"| node_sandbox_executor
node_sandbox_image -->|"runtime isolation"| node_sandbox_executor

click node_cli "https://github.com/devlup-labs/autosetter/blob/main/app.py"
click node_image_parser "https://github.com/devlup-labs/autosetter/blob/main/utils/image_parser.py"
click node_json_generator "https://github.com/devlup-labs/autosetter/blob/main/utils/json_generator.py"
click node_extraction_prompt "https://github.com/devlup-labs/autosetter/blob/main/prompts/json_extraction.txt"
click node_problem_spec "https://github.com/devlup-labs/autosetter/blob/main/example/01_intake/problem.json"
click node_prompt_loader "https://github.com/devlup-labs/autosetter/blob/main/utils/prompt_loader.py"
click node_ollama "https://github.com/devlup-labs/autosetter/blob/main/utils/ollama_client.py"
click node_artifact_prompts "https://github.com/devlup-labs/autosetter/blob/main/prompts/statement.txt"
click node_file_generator "https://github.com/devlup-labs/autosetter/blob/main/utils/file_generator.py"
click node_build_artifacts "https://github.com/devlup-labs/autosetter/blob/main/example/02_build/solution.cpp"
click node_testlib "https://github.com/devlup-labs/autosetter/blob/main/third_party/testlib.h"
click node_test_plan "https://github.com/devlup-labs/autosetter/blob/main/utils/test_plan.py"
click node_test_pipeline "https://github.com/devlup-labs/autosetter/blob/main/utils/test_pipeline.py"
click node_accepted_tests "https://github.com/devlup-labs/autosetter/blob/main/example/03_validate/validation_report.json"
click node_validation_report "https://github.com/devlup-labs/autosetter/blob/main/example/03_validate/validation_report.json"
click node_packager "https://github.com/devlup-labs/autosetter/blob/main/utils/packager.py"
click node_release_bundle "https://github.com/devlup-labs/autosetter/blob/main/example/04_package/manifest.json"
click node_sandbox_server "https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/server.js"
click node_sandbox_executor "https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/executor.js"
click node_sandbox_limits "https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/config.js"
click node_sandbox_image "https://github.com/devlup-labs/autosetter/blob/main/sandbox/docker/Dockerfile"

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_cli,node_image_parser,node_json_generator,node_extraction_prompt,node_problem_spec toneBlue
class node_prompt_loader,node_ollama,node_artifact_prompts,node_file_generator,node_build_artifacts,node_testlib toneAmber
class node_test_plan,node_test_pipeline,node_accepted_tests,node_validation_report toneMint
class node_packager,node_release_bundle toneRose
class node_sandbox_server,node_sandbox_executor,node_sandbox_limits,node_sandbox_image toneIndigo
```

## Components

### Intake

- [AutoSetter CLI](https://github.com/devlup-labs/autosetter/blob/main/app.py): Python entry point · Orchestrates the end-to-end conversion and release decision. · `app.py`
- [Image/PDF parser](https://github.com/devlup-labs/autosetter/blob/main/utils/image_parser.py): input decoder · `utils/image_parser.py`
- [Spec extractor](https://github.com/devlup-labs/autosetter/blob/main/utils/json_generator.py): structured generation · `utils/json_generator.py`
- [Extraction prompt](https://github.com/devlup-labs/autosetter/blob/main/prompts/json_extraction.txt): prompt contract · `prompts/json_extraction.txt`
- [Canonical problem spec](https://github.com/devlup-labs/autosetter/blob/main/example/01_intake/problem.json): JSON artifact · Normalized handoff for all generated deliverables. · `example/01_intake/problem.json`

### Model generation

- [Prompt loader](https://github.com/devlup-labs/autosetter/blob/main/utils/prompt_loader.py): prompt registry · Loads artifact-specific generation contracts. · `utils/prompt_loader.py`
- [Local Qwen via Ollama](https://github.com/devlup-labs/autosetter/blob/main/utils/ollama_client.py): model service · External local-model boundary. · `utils/ollama_client.py`
- [Artifact prompts](https://github.com/devlup-labs/autosetter/blob/main/prompts/statement.txt): prompt contracts · Statement, solution, validator, generator, and checker prompts. · `prompts/statement.txt`
- [Artifact materializer](https://github.com/devlup-labs/autosetter/blob/main/utils/file_generator.py): file generation · `utils/file_generator.py`
- [Generated statement and C++](https://github.com/devlup-labs/autosetter/blob/main/example/02_build/solution.cpp): build artifacts · Statement plus solution, validator, generator, and checker sources. · `example/02_build/solution.cpp`
- [testlib](https://github.com/devlup-labs/autosetter/blob/main/third_party/testlib.h): C++ validation library · `third_party/testlib.h`

### Validation

- [Test-shape plan](https://github.com/devlup-labs/autosetter/blob/main/utils/test_plan.py): test policy · Defines boundary, structural, multi-case, and minimum-case intent. · `utils/test_plan.py`
- [Compile and test pipeline](https://github.com/devlup-labs/autosetter/blob/main/utils/test_pipeline.py): validation orchestrator · Compiles tools, filters tests, solves them, and checks reference answers. · `utils/test_pipeline.py`
- [Accepted test pairs](https://github.com/devlup-labs/autosetter/blob/main/example/03_validate/validation_report.json): test corpus · Numbered input and reference-answer pairs. · `example/03_validate/validation_report.json`
- [Validation report](https://github.com/devlup-labs/autosetter/blob/main/example/03_validate/validation_report.json): release gate report · Records diagnoses and readiness gates, including bad-output checker tests. · `example/03_validate/validation_report.json`

### Release package

- [Package builder](https://github.com/devlup-labs/autosetter/blob/main/utils/packager.py): release assembly · `utils/packager.py`
- [Portable problem package](https://github.com/devlup-labs/autosetter/blob/main/example/04_package/manifest.json): release bundle · Contains metadata, statement, sources, solutions, tests, report, and manifest. · `example/04_package/manifest.json`

### Execution sandbox

- [Sandbox service](https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/server.js): Node.js execution API · Executes untrusted C++ separately from orchestration. · `sandbox/server/src/server.js`
- [Sandbox executor](https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/executor.js): Node.js runner · `sandbox/server/src/executor.js`
- [Sandbox limits](https://github.com/devlup-labs/autosetter/blob/main/sandbox/server/src/config.js): resource policy · Enforces CPU, memory, PID, and network restrictions. · `sandbox/server/src/config.js`
- [Sandbox container](https://github.com/devlup-labs/autosetter/blob/main/sandbox/docker/Dockerfile): Docker/nsjail runtime · `sandbox/docker/Dockerfile`

## Connections

- AutoSetter CLI → Image/PDF parser: reads input
- Image/PDF parser → Spec extractor: image/PDF content
- Extraction prompt → Spec extractor: extraction contract
- Spec extractor → Local Qwen via Ollama: structured request
- Spec extractor → Canonical problem spec: writes
- Canonical problem spec → Artifact materializer: generation context
- Prompt loader → Artifact prompts: loads
- Artifact prompts → Local Qwen via Ollama: artifact requests
- Local Qwen via Ollama → Artifact materializer: generated content
- Artifact materializer → Generated statement and C++: writes
- testlib → Generated statement and C++: compiled against
- Canonical problem spec → Test-shape plan: defines coverage for
- Generated statement and C++ → Compile and test pipeline: compile and execute
- Test-shape plan → Compile and test pipeline: candidate distributions
- Compile and test pipeline → Accepted test pairs: accepted .in/.ans pairs
- Compile and test pipeline → Validation report: diagnoses and gates
- Generated statement and C++ → Package builder: accepted sources
- Canonical problem spec → Package builder: metadata
- Accepted test pairs → Package builder: tests
- Validation report → Package builder: readiness decision
- Package builder → Portable problem package: assembles
- Sandbox service → Sandbox executor: dispatches
- Sandbox limits → Sandbox executor: enforces limits
- Sandbox container → Sandbox executor: runtime isolation