Metadata-Version: 2.4
Name: shadowbench
Version: 0.2.1
Summary: Crowd-sourced, peer-to-peer benchmarking and local inference pooling for open-source AI models.
Project-URL: Homepage, https://github.com/Nidszxh/ShadowBench
Project-URL: Documentation, https://github.com/Nidszxh/ShadowBench/tree/main/docs
Project-URL: Repository, https://github.com/Nidszxh/ShadowBench
Project-URL: Issues, https://github.com/Nidszxh/ShadowBench/issues
Author: The ShadowBench Authors
License: Apache-2.0
Keywords: benchmark,gguf,inference,llama.cpp,llm,p2p
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: numpy>=1.26
Requires-Dist: platformdirs>=4.2
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: gguf
Requires-Dist: gguf>=0.9; extra == 'gguf'
Provides-Extra: nvidia
Requires-Dist: nvidia-ml-py>=12.535; extra == 'nvidia'
Provides-Extra: pool
Requires-Dist: cryptography>=42.0; extra == 'pool'
Requires-Dist: fastapi>=0.111; extra == 'pool'
Requires-Dist: uvicorn>=0.30; extra == 'pool'
Requires-Dist: websockets>=12.0; extra == 'pool'
Requires-Dist: zeroconf>=0.132; extra == 'pool'
Description-Content-Type: text/markdown

# shadowbench (core)

The Python sidecar that powers ShadowBench — hardware profiling, throughput prediction, and (later) the
peer-to-peer inference pool. It runs standalone as a CLI and is embedded by the Tauri desktop app as a sidecar
process.

See [`PROJECT_STRUCTURE.md`](https://github.com/Nidszxh/ShadowBench/blob/main/PROJECT_STRUCTURE.md) for the package layout and
[`DATAFLOW.md`](https://github.com/Nidszxh/ShadowBench/blob/main/docs/plan/DATAFLOW.md) for the math each module implements.

## Install (development)

```bash
uv sync --all-extras          # core + gpu + pool + dev deps
uv run shadowbench --help
```

## CLI

```bash
shadowbench profile                       # detect hardware, print a HardwareProfile as JSON
shadowbench recommend --task coding \      # recommend a model + quant + runtime flags
    --profile intelligence
shadowbench bench --contribute             # measure real tokens/sec, append to the golden dataset
shadowbench serve                          # start the local OpenAI-compatible proxy (Phase 4)
```

## Layout

| Package | Module |
|---|---|
| `profiler/` | Hardware detection + PCIe/compute stress kernel + GGUF parsing |
| `predictor/` | Dense/MoE throughput math, Config Coach, Requirement Discovery |
| `pool/` | mDNS discovery, TLS transport, OpenAI-compatible proxy (Phase 4) |
| `orchestrator/` | Model download + local engine process management (Phase 3) |
| `storage/` | SQLite datastore for predicted-vs-actual calibration (Phase 3) |
| `calibration/` | Ground-truth harness, accuracy report, opt-in telemetry sync |
| `ipc/` | JSON-RPC-over-stdio bridge for the Tauri frontend (Phase 3) |
| `common/` | Shared config, logging, typed errors, cross-module models |
