# mantisanalytics/shockbench-flow-starter architecture

> Architecture diagram of the GitHub repository mantisanalytics/shockbench-flow-starter, 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/mantisanalytics/shockbench-flow-starter
- Repository: https://github.com/mantisanalytics/shockbench-flow-starter

## Overview

ShockBench-Flow starter kit helps users develop policies for a supply-network Gymnasium task, evaluate them locally, and validate or submit them to Codabench. The principal workflow is user → agent → local scoring, with a separate check-and-submit path. The graph includes documented training/search examples and the benchmark engine as external dependencies; their internal implementations are not in this repository. Relationships follow the excerpts, SOURCE INDEX references, or README, so some example links are documented rather than source-verified.

Main entry points: [`src/sbf_starter/cli.py`](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/cli.py) (sbf CLI), [`agents/template/agent.py`](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/template/agent.py) (Template agent), [`src/sbf_starter/scoring.py`](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/scoring.py) (Episode scoring), [`examples`](https://github.com/mantisanalytics/shockbench-flow-starter/tree/main/examples) (Training and search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_policy["Policies and examples"]
  node_template["Template agent<br/>[agent.py]"]
  node_random["Random agent<br/>[agent.py]"]
  node_heuristic["Heuristic agent<br/>[agent.py]"]
  node_examples["Training and search"]
end

subgraph group_local["Local scoring and checks"]
  node_cli["sbf CLI<br/>[cli.py]"]
  node_resolver["Agent resolution<br/>[agents.py]"]
  node_scoring["Episode scoring<br/>[scoring.py]"]
  node_checks["Submission checks<br/>[check.py]"]
  node_container["Container runs<br/>[container.py]"]
end

subgraph group_submit["Submission workflow"]
  node_package["Submission packaging<br/>[cli.py]"]
  node_codabench["Codabench client<br/>[codabench.py]"]
end

subgraph group_benchmark["Benchmark runtime"]
  node_engine["ShockBench engine"]
end

node_user(("Agent developer"))
node_platform["Codabench"]

node_user -->|"runs commands"| node_cli
node_user -->|"edits policy"| node_template
node_template -.->|"informs experiments"| node_examples
node_cli -->|"resolves agents"| node_resolver
node_cli -->|"requests scores"| node_scoring
node_scoring -->|"loads agents"| node_resolver
node_scoring -->|"builds episodes"| node_engine
node_cli -->|"runs checks"| node_checks
node_cli -->|"requests container run"| node_container
node_container -->|"plays container episodes"| node_engine
node_cli -->|"packs agent"| node_package
node_cli -->|"handles competition commands"| node_codabench
node_codabench -->|"authenticates and submits"| node_platform
node_examples -.->|"trains and searches"| node_engine
node_template -.->|"provides policy actions"| node_engine
node_random -.->|"provides policy actions"| node_engine
node_heuristic -.->|"provides policy actions"| node_engine

click node_cli "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/cli.py"
click node_template "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/template/agent.py"
click node_random "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/random/agent.py"
click node_heuristic "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/heuristic/agent.py"
click node_examples "https://github.com/mantisanalytics/shockbench-flow-starter/tree/main/examples"
click node_resolver "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/agents.py"
click node_scoring "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/scoring.py"
click node_checks "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/check.py"
click node_container "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/container.py"
click node_package "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/cli.py"
click node_codabench "https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/codabench.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_template,node_random,node_heuristic,node_examples toneBlue
class node_cli,node_resolver,node_scoring,node_checks,node_container toneAmber
class node_package,node_codabench toneMint
class node_engine toneRose
class node_user,node_platform toneIndigo
```

## Components

### Policies and examples

- [Template agent](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/template/agent.py): `agents/template/agent.py`
- [Random agent](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/random/agent.py): `agents/random/agent.py`
- [Heuristic agent](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/agents/heuristic/agent.py): `agents/heuristic/agent.py`
- [Training and search](https://github.com/mantisanalytics/shockbench-flow-starter/tree/main/examples): `examples`

### Local scoring and checks

- [sbf CLI](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/cli.py): `src/sbf_starter/cli.py`
- [Agent resolution](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/agents.py): `src/sbf_starter/agents.py`
- [Episode scoring](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/scoring.py): `src/sbf_starter/scoring.py`
- [Submission checks](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/check.py): `src/sbf_starter/check.py`
- [Container runs](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/container.py): `src/sbf_starter/container.py`

### Submission workflow

- [Submission packaging](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/cli.py): `src/sbf_starter/cli.py`
- [Codabench client](https://github.com/mantisanalytics/shockbench-flow-starter/blob/main/src/sbf_starter/codabench.py): `src/sbf_starter/codabench.py`

### Benchmark runtime

- **ShockBench engine**

### Other components

- **Agent developer**
- **Codabench**

## Connections

- Agent developer → sbf CLI: runs commands (evidence: `README.md`)
- Agent developer → Template agent: edits policy (evidence: `README.md`)
- Template agent → Training and search: informs experiments
- sbf CLI → Agent resolution: resolves agents (evidence: `src/sbf_starter/cli.py`)
- sbf CLI → Episode scoring: requests scores (evidence: `src/sbf_starter/cli.py`)
- Episode scoring → Agent resolution: loads agents (evidence: `src/sbf_starter/scoring.py`)
- Episode scoring → ShockBench engine: builds episodes (evidence: `src/sbf_starter/scoring.py`)
- sbf CLI → Submission checks: runs checks (evidence: `src/sbf_starter/cli.py`)
- sbf CLI → Container runs: requests container run (evidence: `src/sbf_starter/cli.py`)
- Container runs → ShockBench engine: plays container episodes (evidence: `src/sbf_starter/container.py`)
- sbf CLI → Submission packaging: packs agent (evidence: `src/sbf_starter/cli.py`)
- sbf CLI → Codabench client: handles competition commands (evidence: `src/sbf_starter/cli.py`)
- Codabench client → Codabench: authenticates and submits (evidence: `src/sbf_starter/codabench.py`)
- Training and search → ShockBench engine: trains and searches (evidence: `README.md`)
- Template agent → ShockBench engine: provides policy actions (evidence: `README.md`)
- Random agent → ShockBench engine: provides policy actions (evidence: `README.md`)
- Heuristic agent → ShockBench engine: provides policy actions (evidence: `README.md`)
