# huggingface/repo2rlenv architecture

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

- Interactive diagram: https://gitdiagram.com/huggingface/repo2rlenv
- Repository: https://github.com/huggingface/repo2rlenv

## Overview

1. **What this repo is**
   Repo2RLEnv is a Python package and CLI that turns a source repository into a **Harbor-formatted RL dataset**. The core architectural boundary is between **repo mining / synthesis** on one side and **Harbor-compatible task emission** on the other.

2. **Top-level orchestration**
   The `repo2rlenv` CLI (`src/repo2rlenv/cli.py`) is the entry point for the main workflows:
   - `generate` to build tasks from a repo
   - `bootstrap` to prepare a runnable sandbox image for runtime-based pipelines
   - `validate` to check generated artifacts
   - `push` / `pull` to publish and retrieve datasets
   - auth checks and supporting commands
   This CLI delegates into the pipeline, bootstrap, registry, and source layers rather than implementing generation logic directly.

3. **Pipeline engine**
   The `src/repo2rlenv/pipelines/` package is the synthesis layer. Pipelines implement a common `Pipeline` contract and each writes a task set under an output directory. The repo supports six named pipelines:
   - stable: `pr_diff`, `pr_runtime`
   - experimental: `commit_runtime`, `cve_patches`, `code_instruct`, `equivalence_tests`
   Shared helpers in `_eval_script.py`, `_function_extractor.py`, `_oss_instruct.py`, `_pr_diff_verifier.py`, and `_pr_runtime_verifier.py` indicate that the pipelines reuse common extraction, prompting, and verification logic.

4. **Main data flow**
   The dominant flow is:
   **source repository → pipeline-specific mining/extraction → task synthesis → verifier/reward materialization → Harbor task directory**
   Each task is content-addressed and carries provenance metadata, including pipeline identity and source commit/PR references. That metadata is what makes the output reproducible and verifiable.

5. **Source repository abstraction**
   The `sources.py`, `git_local.py`, `github.py`, and `gitlab.py` modules define the input boundary. Pipelines can read from:
   - local git checkouts
   - GitHub repositories
   - GitLab repositories
   Some pipelines also need commit/PR APIs or OSV data, so the source layer is where those external constraints are enforced. This is important architecturally because not every pipeline accepts every source type.

6. **Bootstrap subsystem for runtime pipelines**
   Runtime pipelines depend on `src/repo2rlenv/bootstrap/`. This is a separate subsystem that builds a **per-repo Docker image** by iterating commands in a container until the project builds and tests collect/pass. Key pieces include:
   - Docker/image orchestration
   - language-specific setup
   - agent loop and prompt/preset logic
   - caching and spec tracking
   The bootstrap output is cached by repo/ref, so expensive setup happens once and is reused by downstream tasks.

7. **Verification and reward generation**
   A central design point is that tasks are **verifiable**. Reward logic lives in `src/repo2rlenv/reward.py`, while runtime and diff verification are supported by pipeline-specific verifiers and log parsers. The `log_parsers/` package contains parsers for pytest, Jest, Cargo, and Go output, which is how test-execution rewards are normalized across ecosystems. This is the boundary where “the agent’s output” becomes a machine-checkable score.

8. **Output format and Harbor integration**
   The repo does not define its own runtime format; it emits **Harbor-compatible datasets**. `src/repo2rlenv/emitter/harbor.py` is the publishing/export layer, and the README notes that tasks include a small `metadata.repo2env` provenance block. That means the output boundary is:
   - internal pipeline artifacts and task metadata on one side
   - Harbor dataset structure, reward files, and registry metadata on the other

9. **Registry, push/pull, and external services**
   The `registry/` package handles publishing concerns: naming, visibility, auth, integration, probing, and push behavior. There are adapters for cloud/container registry environments (`ecr.py`, `gar.py`), which suggests the project can integrate with external registries when packaging runnable artifacts. Separately, `hub.py`, `auth.py`, and `provider.py` mediate authentication and interaction with Hugging Face Hub, GitHub, and LLM providers. These are distinct from synthesis: they are the distribution and credential boundary.

10. **LLM usage is isolated by phase**
   The architecture deliberately scopes LLM calls to specific phases:
   - some pipelines use an LLM during **synthesis**
   - runtime pipelines may use an LLM during **bootstrap**
   - certain verifiers may use an LLM during **verification/judging**
   This separation matters because it keeps most generated artifacts deterministic and cacheable, while still allowing semantic scoring where needed.

11. **User-facing inspection and live feedback**
   `src/repo2rlenv/ui/` provides console/live views for generation and bootstrap progress. This is a presentation layer only; it does not change generation semantics. It exists to surface long-running pipeline and bootstrap state to the user during dataset creation.

12. **Quality and release boundary**
   The `tests/` tree is broad and maps closely to the architecture: pipeline contracts, bootstrap behavior, source integrations, registry behavior, reward/grading, log parsing, and end-to-end hub flows. CI and release workflows in `.github/workflows/` reinforce that the repo’s main invariant is not “the package imports,” but “a generated dataset is valid, reproducible, and publishable.”

13. **How to draw the diagram**
   A good architecture diagram would show:
   - **CLI/API entrypoints**
   - **Source adapters** feeding into
   - **Pipeline engine**
   - branching to **bootstrap** for sandboxed pipelines and **verifiers/log parsers** for scoring
   - then converging into **Harbor emitter**
   - then into **registry/Hugging Face Hub push-pull**
   - with **auth/provider integrations** and **LLM services** as external dependencies
   The key conceptual split is between **dataset synthesis** and **dataset distribution**.

Main entry points: [`src/repo2rlenv/pipelines`](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/pipelines) (Pipelines), [`src/repo2rlenv/cli.py`](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/cli.py) (CLI), [`src/repo2rlenv/sources.py`](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/sources.py) (Sources), [`src/repo2rlenv/registry`](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/registry) (Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_cli["CLI<br/>command entrypoint<br/>[cli.py]"]
  node_config["Config<br/>[config.py]"]
  node_ui["UI"]
end

subgraph group_synthesis["Synthesis"]
  node_sources[("Sources<br/>repo adapters<br/>[sources.py]")]
  node_git_local["Local git<br/>source adapter<br/>[git_local.py]"]
  node_github["GitHub<br/>source adapter<br/>[github.py]"]
  node_gitlab["GitLab<br/>source adapter<br/>[gitlab.py]"]
  node_pipelines["Pipelines<br/>pipeline engine"]
  node_pr_diff["PR diff<br/>stable pipeline<br/>[pr_diff.py]"]
  node_cve_patches["CVE patches<br/>security pipeline<br/>[cve_patches.py]"]
  node_code_instruct["Code instruct<br/>instruction pipeline<br/>[code_instruct.py]"]
  node_equivalence_tests["Equivalence tests<br/>test pipeline"]
  node_reward["Reward<br/>scoring<br/>[reward.py]"]
  node_log_parsers["Log parsers<br/>test output parsers"]
end

subgraph group_runtime["Runtime setup"]
  node_pr_runtime["PR runtime<br/>stable pipeline<br/>[pr_runtime.py]"]
  node_commit_runtime["Commit runtime<br/>runtime pipeline<br/>[commit_runtime.py]"]
  node_bootstrap["Bootstrap<br/>sandbox builder"]
end

subgraph group_distribution["Distribution"]
  node_emitter["Harbor emitter<br/>export layer<br/>[harbor.py]"]
  node_registry["Registry<br/>publish layer"]
  node_hub["Hub<br/>service integration<br/>[hub.py]"]
  node_auth["Auth<br/>credentials<br/>[auth.py]"]
  node_provider["Providers<br/>[provider.py]"]
  node_llm["LLM<br/>model client<br/>[llm.py]"]
  node_osv["OSV<br/>vuln data<br/>[osv.py]"]
end

node_cli -->|"select source"| node_sources
node_cli -->|"run generate"| node_pipelines
node_cli -->|"run bootstrap"| node_bootstrap
node_cli -->|"push/pull"| node_registry
node_cli -->|"check auth"| node_auth
node_cli -->|"show progress"| node_ui
node_config -->|"options"| node_cli
node_sources -->|"local"| node_git_local
node_sources -->|"github"| node_github
node_sources -->|"gitlab"| node_gitlab
node_sources -->|"input repo"| node_pipelines
node_pipelines -->|"stable"| node_pr_diff
node_pipelines -->|"stable"| node_pr_runtime
node_pipelines -->|"runtime"| node_commit_runtime
node_pipelines -->|"security"| node_cve_patches
node_pipelines -->|"instruction"| node_code_instruct
node_pipelines -->|"tests"| node_equivalence_tests
node_pr_runtime -->|"needs image"| node_bootstrap
node_commit_runtime -->|"needs image"| node_bootstrap
node_bootstrap -->|"optional assist"| node_llm
node_pipelines -->|"score tasks"| node_reward
node_reward -->|"normalize output"| node_log_parsers
node_pr_diff -->|"verify diff"| node_reward
node_pr_runtime -->|"verify runtime"| node_reward
node_code_instruct -->|"may use"| node_llm
node_cve_patches -->|"vuln lookup"| node_osv
node_pipelines -->|"emit dataset"| node_emitter
node_emitter -->|"publish"| node_registry
node_registry -->|"hub ops"| node_hub
node_registry -->|"registry auth"| node_auth
node_registry -->|"external services"| node_provider

click node_cli "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/cli.py"
click node_config "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/config.py"
click node_ui "https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/ui"
click node_sources "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/sources.py"
click node_git_local "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/git_local.py"
click node_github "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/github.py"
click node_gitlab "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/gitlab.py"
click node_pipelines "https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/pipelines"
click node_pr_diff "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/pr_diff.py"
click node_pr_runtime "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/pr_runtime.py"
click node_commit_runtime "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/commit_runtime.py"
click node_cve_patches "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/cve_patches.py"
click node_code_instruct "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/code_instruct.py"
click node_equivalence_tests "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/equivalence_tests.py"
click node_bootstrap "https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/bootstrap"
click node_reward "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/reward.py"
click node_log_parsers "https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/log_parsers"
click node_emitter "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/emitter/harbor.py"
click node_registry "https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/registry"
click node_hub "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/hub.py"
click node_auth "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/auth.py"
click node_provider "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/provider.py"
click node_llm "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/llm.py"
click node_osv "https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/osv.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_cli,node_config,node_ui toneBlue
class node_sources,node_git_local,node_github,node_gitlab,node_pipelines,node_pr_diff,node_cve_patches,node_code_instruct,node_equivalence_tests,node_reward,node_log_parsers toneAmber
class node_pr_runtime,node_commit_runtime,node_bootstrap toneMint
class node_emitter,node_registry,node_hub,node_auth,node_provider,node_llm,node_osv toneRose
```

## Components

### Entrypoints

CLI, config, and user-facing progress surfaces.

- [CLI](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/cli.py): command entrypoint · Main repo2rlenv command surface for generate, bootstrap, validate, push, pull, and auth flows. · `src/repo2rlenv/cli.py`
- [Config](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/config.py): runtime config · Shared configuration and environment handling used across commands and subsystems. · `src/repo2rlenv/config.py`
- [UI](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/ui): console ui · Live console views for generation and bootstrap progress. · `src/repo2rlenv/ui`

### Synthesis

Repository mining, pipeline execution, verification, and reward materialization.

- [Sources](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/sources.py): repo adapters · Input boundary for local, GitHub, and GitLab repositories. · `src/repo2rlenv/sources.py`
- [Local git](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/git_local.py): source adapter · Local checkout access for repository mining and commit-based workflows. · `src/repo2rlenv/git_local.py`
- [GitHub](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/github.py): source adapter · GitHub-backed repository and API access. · `src/repo2rlenv/github.py`
- [GitLab](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/gitlab.py): source adapter · GitLab-backed repository and API access. · `src/repo2rlenv/gitlab.py`
- [Pipelines](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/pipelines): pipeline engine · Common pipeline contract and shared synthesis helpers for task generation. · `src/repo2rlenv/pipelines`
- [PR diff](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/pr_diff.py): stable pipeline · Diff-oriented task synthesis with verifier support. · `src/repo2rlenv/pipelines/pr_diff.py`
- [CVE patches](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/cve_patches.py): security pipeline · Patch synthesis for vulnerability-oriented tasks. · `src/repo2rlenv/pipelines/cve_patches.py`
- [Code instruct](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/code_instruct.py): instruction pipeline · Instruction-style task synthesis built from source code understanding. · `src/repo2rlenv/pipelines/code_instruct.py`
- [Equivalence tests](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/equivalence_tests.py): test pipeline · Task synthesis focused on equivalence and test-driven verification. · `src/repo2rlenv/pipelines/equivalence_tests.py`
- [Reward](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/reward.py): scoring · Reward and grading logic that turns task outcomes into machine-checkable scores. · `src/repo2rlenv/reward.py`
- [Log parsers](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/log_parsers): test output parsers · Normalized parsers for pytest, Jest, Cargo, and Go execution output. · `src/repo2rlenv/log_parsers`

### Runtime setup

Bootstrap and sandbox image preparation for runtime pipelines.

- [PR runtime](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/pr_runtime.py): stable pipeline · Runtime-based PR task synthesis that depends on sandbox bootstrap. · `src/repo2rlenv/pipelines/pr_runtime.py`
- [Commit runtime](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/pipelines/commit_runtime.py): runtime pipeline · Commit-based runtime task synthesis using sandboxed execution. · `src/repo2rlenv/pipelines/commit_runtime.py`
- [Bootstrap](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/bootstrap): sandbox builder · Per-repo Docker image and environment preparation for runtime pipelines. · `src/repo2rlenv/bootstrap`

### Distribution

Harbor emission, registry publishing, and external service integration.

- [Harbor emitter](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/emitter/harbor.py): export layer · Publishes generated tasks into Harbor-compatible dataset structure. · `src/repo2rlenv/emitter/harbor.py`
- [Registry](https://github.com/huggingface/repo2rlenv/tree/main/src/repo2rlenv/registry): publish layer · Naming, auth, visibility, probing, and push/pull behavior for published artifacts. · `src/repo2rlenv/registry`
- [Hub](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/hub.py): service integration · Hugging Face Hub interaction for dataset publication and retrieval. · `src/repo2rlenv/hub.py`
- [Auth](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/auth.py): credentials · Authentication helpers shared by CLI, hub, and registry flows. · `src/repo2rlenv/auth.py`
- [Providers](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/provider.py): llm providers · Provider abstraction for external model services used during selected phases. · `src/repo2rlenv/provider.py`
- [LLM](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/llm.py): model client · Model access boundary used selectively in synthesis, bootstrap, or judging phases. · `src/repo2rlenv/llm.py`
- [OSV](https://github.com/huggingface/repo2rlenv/blob/main/src/repo2rlenv/osv.py): vuln data · External vulnerability data used by security-oriented pipelines. · `src/repo2rlenv/osv.py`

## Connections

- CLI → Sources: select source · CLI resolves repository inputs through the source abstraction.
- CLI → Pipelines: run generate · CLI dispatches repository generation into the pipeline engine.
- CLI → Bootstrap: run bootstrap · CLI invokes sandbox preparation for runtime workflows.
- CLI → Registry: push/pull · CLI delegates publishing and retrieval to registry flows.
- CLI → Auth: check auth · CLI uses shared authentication helpers for access checks.
- CLI → UI: show progress · CLI surfaces generation and bootstrap progress through the UI layer.
- Config → CLI: options · Configuration feeds command behavior and environment setup.
- Sources → Local git: local · Local git checkouts are one supported source type.
- Sources → GitHub: github · GitHub repositories and APIs are one supported source type.
- Sources → GitLab: gitlab · GitLab repositories and APIs are one supported source type.
- Sources → Pipelines: input repo · Pipelines consume repositories through the source boundary.
- Pipelines → PR diff: stable · PR diff is a core pipeline specialization.
- Pipelines → PR runtime: stable · PR runtime is a core pipeline specialization.
- Pipelines → Commit runtime: runtime · Commit runtime is an experimental pipeline specialization.
- Pipelines → CVE patches: security · CVE patch generation is a specialized pipeline.
- Pipelines → Code instruct: instruction · Code instruct generation is a specialized pipeline.
- Pipelines → Equivalence tests: tests · Equivalence test generation is a specialized pipeline.
- PR runtime → Bootstrap: needs image · Runtime PR tasks depend on per-repo sandbox bootstrapping.
- Commit runtime → Bootstrap: needs image · Commit runtime tasks depend on per-repo sandbox bootstrapping.
- Bootstrap → LLM: optional assist · Bootstrap may use an LLM for iterative setup or recovery.
- Pipelines → Reward: score tasks · Pipelines materialize verifier and reward artifacts.
- Reward → Log parsers: normalize output · Reward computation uses parsed test logs for cross-ecosystem scoring.
- PR diff → Reward: verify diff · PR diff tasks rely on pipeline-specific verification.
- PR runtime → Reward: verify runtime · PR runtime tasks rely on pipeline-specific verification.
- Code instruct → LLM: may use · Some instruction synthesis steps can call an LLM.
- CVE patches → OSV: vuln lookup · Security pipelines can incorporate OSV vulnerability data.
- Pipelines → Harbor emitter: emit dataset · Completed task sets are written as Harbor-compatible datasets.
- Harbor emitter → Registry: publish · Exported artifacts are handed to registry publishing flows.
- Registry → Hub: hub ops · Registry layer mediates interaction with Hugging Face Hub.
- Registry → Auth: registry auth · Publishing and retrieval use shared credential helpers.
- Registry → Providers: external services · Registry and distribution flows may integrate with external providers.