# kainam15/ac-prof architecture

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

- Interactive diagram: https://gitdiagram.com/kainam15/ac-prof
- Repository: https://github.com/kainam15/ac-prof

## Overview

AC-Prof is a model-inference benchmarking application: users select a model and resource/input configuration, prepare a containerized runtime, execute measurement cases, and inspect reproducible results. The graph retains documented collection modes, workload families, model coverage, post-hoc profiling, and comparison/reporting capabilities. Several runtime links are based on README descriptions because the relevant implementation excerpts were not provided; those edges are marked dashed with null evidence.

Main entry points: [`acprof/host/orchestrator.py`](https://github.com/kainam15/ac-prof/blob/main/acprof/host/orchestrator.py) (Run orchestration), [`acprof/host/client.py`](https://github.com/kainam15/ac-prof/blob/main/acprof/host/client.py) (Measurement client), [`acprof/container/server.py`](https://github.com/kainam15/ac-prof/blob/main/acprof/container/server.py) (Inference server), [`acprof/artifact_layout.py`](https://github.com/kainam15/ac-prof/blob/main/acprof/artifact_layout.py) (Experiment artifacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_tui["Terminal UI<br/>[app.py]"]
  node_cli["CLI commands<br/>[main.py]"]
end

subgraph group_planning["Experiment planning"]
  node_model_resolution["Model resolution"]
  node_model_spec["Model contracts<br/>[model_spec.py]"]
  node_coverage["Model coverage<br/>[model_coverage.py]"]
  node_host_checks["Host capabilities<br/>[detect.py]"]
  node_model_store[("Shared model store<br/>[model_store.py]")]
  node_image_management["Runtime images"]
end

subgraph group_runtime["Inference and measurement"]
  node_orchestrator["Run orchestration<br/>[orchestrator.py]"]
  node_run_state[("Run state and resume<br/>[run_state.py]")]
  node_container_server["Inference server<br/>[server.py]"]
  node_workloads["Task workloads<br/>[contract.py]"]
  node_client["Measurement client<br/>[client.py]"]
  node_metric_registry["Metric definitions<br/>[metric_registry.py]"]
  node_profilers["Optional profilers"]
  node_energy["Energy monitoring<br/>[energy_cpu.py]"]
  node_packet_metrics["Packet latency"]
end

subgraph group_results["Results and analysis"]
  node_artifacts[("Experiment artifacts<br/>[artifact_layout.py]")]
  node_csv_results["CSV measurements<br/>[result_csv.py]"]
  node_posthoc["Post-hoc profiling<br/>[service.py]"]
  node_analysis["Comparison and analysis<br/>[comparison.py]"]
  node_plotting["Reports and plots<br/>[report.py]"]
end

node_user(("Benchmark user"))
node_docker["Docker Engine"]
node_huggingface["Hugging Face Hub"]

node_user -->|"starts runs"| node_tui
node_user -->|"configures runs"| node_cli
node_tui -.->|"launches run"| node_orchestrator
node_cli -.->|"launches run"| node_orchestrator
node_orchestrator -->|"checks host"| node_host_checks
node_orchestrator -.->|"resolves model"| node_model_resolution
node_model_resolution -->|"uses contract"| node_model_spec
node_orchestrator -->|"prepares weights"| node_model_store
node_huggingface -->|"provides weights"| node_model_store
node_orchestrator -->|"prepares runtime"| node_image_management
node_image_management -->|"builds or pulls"| node_docker
node_orchestrator -.->|"tracks cases"| node_run_state
node_orchestrator -->|"starts inference"| node_container_server
node_container_server -->|"serves task"| node_workloads
node_client -->|"sends requests"| node_container_server
node_client -->|"records metrics"| node_metric_registry
node_client -->|"collects energy"| node_energy
node_client -.->|"runs optional profiling"| node_profilers
node_client -->|"merges packet latency"| node_packet_metrics
node_orchestrator -->|"publishes results"| node_artifacts
node_client -.->|"writes measurements"| node_csv_results
node_artifacts -.->|"stores measurements"| node_csv_results
node_user -->|"assesses coverage"| node_coverage
node_user -->|"requests profiling"| node_posthoc
node_posthoc -->|"updates artifacts"| node_artifacts
node_user -->|"compares results"| node_analysis
node_csv_results -.->|"supplies measurements"| node_analysis
node_analysis -->|"generates reports"| node_plotting

click node_tui "https://github.com/kainam15/ac-prof/blob/main/acprof/tui/app.py"
click node_cli "https://github.com/kainam15/ac-prof/blob/main/acprof/cli/main.py"
click node_model_resolution "https://github.com/kainam15/ac-prof/blob/main/acprof/model_resolution.py"
click node_model_spec "https://github.com/kainam15/ac-prof/blob/main/acprof/model_spec.py"
click node_coverage "https://github.com/kainam15/ac-prof/blob/main/acprof/host/model_coverage.py"
click node_host_checks "https://github.com/kainam15/ac-prof/blob/main/acprof/host/detect.py"
click node_model_store "https://github.com/kainam15/ac-prof/blob/main/acprof/host/model_store.py"
click node_image_management "https://github.com/kainam15/ac-prof/blob/main/acprof/host/image_management.py"
click node_orchestrator "https://github.com/kainam15/ac-prof/blob/main/acprof/host/orchestrator.py"
click node_run_state "https://github.com/kainam15/ac-prof/blob/main/acprof/host/run_state.py"
click node_container_server "https://github.com/kainam15/ac-prof/blob/main/acprof/container/server.py"
click node_workloads "https://github.com/kainam15/ac-prof/blob/main/acprof/workloads/contract.py"
click node_client "https://github.com/kainam15/ac-prof/blob/main/acprof/host/client.py"
click node_metric_registry "https://github.com/kainam15/ac-prof/blob/main/acprof/metric_registry.py"
click node_profilers "https://github.com/kainam15/ac-prof/tree/main/acprof/host/profilers"
click node_energy "https://github.com/kainam15/ac-prof/blob/main/acprof/monitors/energy_cpu.py"
click node_packet_metrics "https://github.com/kainam15/ac-prof/blob/main/acprof/packet/merge_packet_latency.py"
click node_artifacts "https://github.com/kainam15/ac-prof/blob/main/acprof/artifact_layout.py"
click node_csv_results "https://github.com/kainam15/ac-prof/blob/main/acprof/result_csv.py"
click node_posthoc "https://github.com/kainam15/ac-prof/blob/main/acprof/host/posthoc/service.py"
click node_analysis "https://github.com/kainam15/ac-prof/blob/main/acprof/analysis/comparison.py"
click node_plotting "https://github.com/kainam15/ac-prof/blob/main/acprof/plotting/report.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_tui,node_cli,node_user toneBlue
class node_model_resolution,node_model_spec,node_coverage,node_host_checks,node_model_store,node_image_management toneAmber
class node_orchestrator,node_run_state,node_container_server,node_workloads,node_client,node_metric_registry,node_profilers,node_energy,node_packet_metrics toneMint
class node_artifacts,node_csv_results,node_posthoc,node_analysis,node_plotting toneRose
class node_docker,node_huggingface toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/kainam15/ac-prof/blob/main/acprof/tui/app.py): `acprof/tui/app.py`
- [CLI commands](https://github.com/kainam15/ac-prof/blob/main/acprof/cli/main.py): `acprof/cli/main.py`

### Experiment planning

- [Model resolution](https://github.com/kainam15/ac-prof/blob/main/acprof/model_resolution.py): `acprof/model_resolution.py`
- [Model contracts](https://github.com/kainam15/ac-prof/blob/main/acprof/model_spec.py): `acprof/model_spec.py`
- [Model coverage](https://github.com/kainam15/ac-prof/blob/main/acprof/host/model_coverage.py): `acprof/host/model_coverage.py`
- [Host capabilities](https://github.com/kainam15/ac-prof/blob/main/acprof/host/detect.py): `acprof/host/detect.py`
- [Shared model store](https://github.com/kainam15/ac-prof/blob/main/acprof/host/model_store.py): `acprof/host/model_store.py`
- [Runtime images](https://github.com/kainam15/ac-prof/blob/main/acprof/host/image_management.py): `acprof/host/image_management.py`

### Inference and measurement

- [Run orchestration](https://github.com/kainam15/ac-prof/blob/main/acprof/host/orchestrator.py): `acprof/host/orchestrator.py`
- [Run state and resume](https://github.com/kainam15/ac-prof/blob/main/acprof/host/run_state.py): `acprof/host/run_state.py`
- [Inference server](https://github.com/kainam15/ac-prof/blob/main/acprof/container/server.py): `acprof/container/server.py`
- [Task workloads](https://github.com/kainam15/ac-prof/blob/main/acprof/workloads/contract.py): `acprof/workloads/contract.py`
- [Measurement client](https://github.com/kainam15/ac-prof/blob/main/acprof/host/client.py): `acprof/host/client.py`
- [Metric definitions](https://github.com/kainam15/ac-prof/blob/main/acprof/metric_registry.py): `acprof/metric_registry.py`
- [Optional profilers](https://github.com/kainam15/ac-prof/tree/main/acprof/host/profilers): `acprof/host/profilers`
- [Energy monitoring](https://github.com/kainam15/ac-prof/blob/main/acprof/monitors/energy_cpu.py): `acprof/monitors/energy_cpu.py`
- [Packet latency](https://github.com/kainam15/ac-prof/blob/main/acprof/packet/merge_packet_latency.py): `acprof/packet/merge_packet_latency.py`

### Results and analysis

- [Experiment artifacts](https://github.com/kainam15/ac-prof/blob/main/acprof/artifact_layout.py): `acprof/artifact_layout.py`
- [CSV measurements](https://github.com/kainam15/ac-prof/blob/main/acprof/result_csv.py): `acprof/result_csv.py`
- [Post-hoc profiling](https://github.com/kainam15/ac-prof/blob/main/acprof/host/posthoc/service.py): `acprof/host/posthoc/service.py`
- [Comparison and analysis](https://github.com/kainam15/ac-prof/blob/main/acprof/analysis/comparison.py): `acprof/analysis/comparison.py`
- [Reports and plots](https://github.com/kainam15/ac-prof/blob/main/acprof/plotting/report.py): `acprof/plotting/report.py`

### Other components

- **Benchmark user**
- **Docker Engine**
- **Hugging Face Hub**

## Connections

- Benchmark user → Terminal UI: starts runs (evidence: `README.md`)
- Benchmark user → CLI commands: configures runs (evidence: `README.md`)
- Terminal UI → Run orchestration: launches run
- CLI commands → Run orchestration: launches run
- Run orchestration → Host capabilities: checks host (evidence: `README.md`)
- Run orchestration → Model resolution: resolves model
- Model resolution → Model contracts: uses contract (evidence: `acprof/model_resolution.py`)
- Run orchestration → Shared model store: prepares weights (evidence: `README.md`)
- Hugging Face Hub → Shared model store: provides weights (evidence: `README.md`)
- Run orchestration → Runtime images: prepares runtime (evidence: `README.md`)
- Runtime images → Docker Engine: builds or pulls (evidence: `README.md`)
- Run orchestration → Run state and resume: tracks cases
- Run orchestration → Inference server: starts inference (evidence: `README.md`)
- Inference server → Task workloads: serves task (evidence: `acprof/container/server.py`)
- Measurement client → Inference server: sends requests (evidence: `README.md`)
- Measurement client → Metric definitions: records metrics (evidence: `acprof/host/client.py`)
- Measurement client → Energy monitoring: collects energy (evidence: `README.md`)
- Measurement client → Optional profilers: runs optional profiling (evidence: `README.md`)
- Measurement client → Packet latency: merges packet latency (evidence: `acprof/packet/merge_packet_latency.py`)
- Run orchestration → Experiment artifacts: publishes results (evidence: `README.md`)
- Measurement client → CSV measurements: writes measurements
- Experiment artifacts → CSV measurements: stores measurements
- Benchmark user → Model coverage: assesses coverage (evidence: `README.md`)
- Benchmark user → Post-hoc profiling: requests profiling (evidence: `README.md`)
- Post-hoc profiling → Experiment artifacts: updates artifacts (evidence: `acprof/host/posthoc/service.py`)
- Benchmark user → Comparison and analysis: compares results (evidence: `README.md`)
- CSV measurements → Comparison and analysis: supplies measurements
- Comparison and analysis → Reports and plots: generates reports (evidence: `README.md`)
