Metadata-Version: 2.5
Name: acprof
Version: 0.3.0
Summary: Reproducible profiling of containerized Hugging Face inference services
Project-URL: Homepage, https://github.com/kainam15/AC-Prof
Project-URL: Documentation, https://github.com/kainam15/AC-Prof/blob/main/docs/README.md
Project-URL: Repository, https://github.com/kainam15/AC-Prof
Project-URL: Issues, https://github.com/kainam15/AC-Prof/issues
Project-URL: Changelog, https://github.com/kainam15/AC-Prof/releases
Author: AC-Prof contributors
License-Expression: Apache-2.0 AND CC-BY-4.0
License-File: LICENSE
License-File: NOTICE
License-File: licenses/CC-BY-4.0.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Benchmark
Requires-Python: >=3.12
Requires-Dist: httpx[socks]<1,>=0.28.1
Requires-Dist: huggingface-hub<2,>=1.0
Requires-Dist: matplotlib<4,>=3.7
Requires-Dist: modelscope-hub<0.2,>=0.1.9
Requires-Dist: numpy<3,>=1.24
Requires-Dist: nvidia-ml-py>=13.610.43
Requires-Dist: packaging<27,>=25
Requires-Dist: pandas<4,>=2.0
Requires-Dist: pillow>=10.0
Requires-Dist: plotly<8,>=7.1
Requires-Dist: requests<3,>=2.31
Requires-Dist: textual<9,>=8.2.8
Description-Content-Type: text/markdown

<p align="center">
  <img alt="AC-Prof" src="docs/assets/logos/acprof-logo-light.svg#gh-light-mode-only" width="55%">
  <img alt="AC-Prof" src="docs/assets/logos/acprof-logo-dark.svg#gh-dark-mode-only" width="55%">
</p>

**English** · [简体中文](docs/i18n/README_zh-CN.md)

AC-Prof profiles containerized AI model inference across CPU, memory, GPU, and input-size configurations. It prepares Docker runtimes, mounts shared model weights read-only, and produces reproducible measurements and analysis artifacts. Compatible models can be profiled without changing their code.

## What AC-Prof does

| Capability | Description |
| --- | --- |
| Performance and resources | Application latency, throughput, CPU and memory usage; GPU metrics when available |
| Full profiling | Energy, packet-level timing, CPU hardware counters, and optional independent profilers |
| Reproducible experiments | Input and environment metadata, layered CSV results, plots, and reports |

AC-Prof supports text, vision, audio, time series, diffusion, multimodal, and structured-data workloads when the model meets the [supported task interfaces](docs/models/supported-tasks.md#任务支持范围). A task label alone does not guarantee that every checkpoint will run.

## Quick start

Install the latest published release with [uv](https://docs.astral.sh/uv/getting-started/installation/) and launch the interactive terminal interface:

```bash
uv tool install acprof
acprof tui
```

Until the package is available on PyPI, install the verified v0.2.0 wheel from
[GitHub Releases](https://github.com/kainam15/AC-Prof/releases/tag/v0.2.0) instead:

```bash
uv tool install https://github.com/kainam15/AC-Prof/releases/download/v0.2.0/acprof-0.2.0-py3-none-any.whl
acprof tui
```

See the [installation guide](docs/getting_started/installation.md#github-release-fallback) for download checksums and the standalone Linux binary.

Collection requires a suitable Linux host with a local Docker Engine and cgroup v2. Native Linux x86_64 is the FULL measurement platform; WSL2 has limited basic/PARTIAL support. See [host requirements](docs/getting_started/installation.md#1-检查主机环境).

### Develop from source

To contribute or work on the latest source code, clone the repository and let uv prepare the editable project and development tools:

```bash
git clone https://github.com/kainam15/AC-Prof.git
cd AC-Prof
uv sync
uv run acprof tui
```

`uv sync` creates and updates this checkout's `.venv`; no manual activation is needed. Each Git worktree has its own environment and shares uv's download cache. Ordinary release users continue to use `uv tool install acprof` and `acprof tui`.

See [developer setup](docs/development/distribution.md#本地开发环境) and [testing](docs/development/testing.md) for the full workflow.

Current source builds reuse verified model images automatically and build missing ones. Use `--rebuild-image` or the TUI's advanced image options for a one-time rebuild; Docker cache may still be used. See [image preparation](docs/models/images.md#构建复用和验证).

The TUI tracks collection and probe progress through structured events. After a collection exits, it verifies the saved experiment identity and audits the result before reporting success; a successful process exit alone is insufficient.

## Documentation

| Goal | Guide |
| --- | --- |
| Prepare the host, run a first CPU experiment, or inspect results | [Installation and experiments](docs/getting_started/installation.md) |
| Understand the terminal interface | [TUI user guide](docs/usage/tui.md) |
| Use command-line options and tools | [CLI reference](docs/usage/cli.md) |
| Interpret metrics, CSV layers, and reports | [Metrics and results](docs/results/metrics.md) |
| Understand supported models and runtimes | [Runtime compatibility](docs/models/runtime.md) |
| Develop or contribute to AC-Prof | [Developer installation](docs/development/distribution.md#本地开发环境), [architecture](docs/development/architecture.md), [testing](docs/development/testing.md) |

[All documentation](docs/README.md) · [Troubleshooting](docs/usage/troubleshooting.md)

## Contributing and security

See [CONTRIBUTING.md](CONTRIBUTING.md) for development and review practices, and [SECURITY.md](SECURITY.md) for confidential vulnerability reporting and the third-party model trust boundary.

## License and origins

Project code is licensed under [Apache-2.0](LICENSE). Bundled LibriSpeech audio retains [CC-BY-4.0](licenses/CC-BY-4.0.txt); model code and weights have their own licenses. AC-Prof is part of the DOR project at JNU DISTINT. See [NOTICE](NOTICE) and [project origins](docs/development/history.md).
