Metadata-Version: 2.5
Name: brasskey
Version: 0.1.0a1
Summary: The key to every engine: deploy, tune, verify and serve open models on any hardware.
Project-URL: Homepage, https://github.com/Prcept-AI/brasskey
Project-URL: Repository, https://github.com/Prcept-AI/brasskey
Project-URL: Issues, https://github.com/Prcept-AI/brasskey/issues
Project-URL: Security, https://github.com/Prcept-AI/brasskey/blob/main/SECURITY.md
Author: Prcept AI LLP
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: benchmark,inference,llama.cpp,llm,mlx,openai-compatible,sglang,vllm
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx2>=2.16
Requires-Dist: huggingface-hub>=2.4
Requires-Dist: keyring>=25.7
Requires-Dist: nvidia-ml-py>=13.615
Requires-Dist: platformdirs>=4.14
Requires-Dist: psutil>=7.2
Requires-Dist: pydantic>=2.14
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0
Requires-Dist: starlette>=1.10
Requires-Dist: typer>=0.27
Requires-Dist: uvicorn>=0.54
Description-Content-Type: text/markdown

<br>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Prcept-AI/brasskey/v0.1.0a1/brand/logo/brasskey-wordmark-on-dark.svg">
    <img alt="Brasskey" src="https://raw.githubusercontent.com/Prcept-AI/brasskey/v0.1.0a1/brand/logo/brasskey-wordmark-on-light.svg" width="240">
  </picture>
</p>

<p align="center"><b>The key to every engine.</b></p>

<br>

Brasskey is an open-source tool to deploy, tune, verify and serve open models on any hardware,
measured on your own traffic.

```bash
brasskey run        # try any model on your machine
brasskey switch     # prove an open model can replace an expensive API (coming soon)
brasskey deploy     # ship it tuned, verified and secure (coming soon)
```

## Status

Pre-alpha. 0.1.0a1 is the first release on PyPI, on the way to v0.1 "It runs": `brasskey run`,
`brasskey bench` and `brasskey doctor --security` on NVIDIA GPUs, Apple Silicon and CPUs, with
llama.cpp, MLX, vLLM and SGLang. Done so far:

- `brasskey doctor`: hardware, engines and running servers.
- Planning with `brasskey run --dry-run`.
- `brasskey run` with llama.cpp, MLX (Apple Silicon), vLLM or SGLang (NVIDIA on Linux, as a
  process or from the official image pinned by digest). It downloads and verifies the model,
  then serves it on 127.0.0.1 through a Brasskey proxy that enforces API keys. Ctrl-C stops it
  cleanly. llama.cpp and MLX are tested on real hardware; vLLM and SGLang are not yet tested on
  real GPUs.
- `brasskey doctor --security`: checks this machine, or a URL, for exposed model servers.
- `brasskey bench`: repeated GuideLLM runs, 95% intervals on every metric, and PASS / FAIL /
  INCONCLUSIVE when comparing two setups.

Next: testing vLLM and SGLang on NVIDIA GPUs, then 0.1.0. Design decisions are recorded in
[docs/decisions](https://github.com/Prcept-AI/brasskey/tree/v0.1.0a1/docs/decisions/).

## Install

Python 3.11 or newer, on macOS or Linux (Windows through WSL2):

```bash
uv tool install brasskey       # or: pip install brasskey
brasskey doctor                # what Brasskey sees on this machine
brasskey run --dry-run         # the model it would pick for this machine, and why
```

`brasskey run` starts an engine you have installed, for example `brew install llama.cpp`; on
Apple Silicon, Brasskey can set up MLX itself if you have uv. `brasskey doctor` shows what's
installed and how to add the rest. Releases are signed and reproducible; see
[SECURITY.md](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/SECURITY.md#verifying-a-release).

## Try it from source

You need [uv](https://docs.astral.sh/uv/) 0.13.6 or newer.

```bash
git clone https://github.com/Prcept-AI/brasskey.git
cd brasskey
uv sync
uv run brasskey --help
uv run brasskey doctor          # what Brasskey sees on this machine (CPU, memory, GPUs)
uv run brasskey doctor --json
uv run brasskey run --dry-run           # the model Brasskey would pick for this machine, and why
uv run brasskey run qwen3-14b --dry-run --context 32768
uv run brasskey run hf:Qwen/Qwen3-4B-GGUF:Q8_0 --dry-run   # any Hugging Face repo

brew install llama.cpp                  # the engine (macOS or Linux)
uv run brasskey run qwen3-0.6b          # download (639 MB), start, serve; Ctrl-C stops it
uv run brasskey run qwen3-4b --save     # also writes brasskey.yaml + brasskey.lock
uv run brasskey run --engine mlx        # Apple Silicon: MLX via uv, set up on first use
uv run brasskey run --engine vllm       # NVIDIA on Linux: vLLM on PATH, or its pinned image

uv run brasskey bench http://127.0.0.1:8000/v1 --save base.json      # measure a server
uv run brasskey bench http://127.0.0.1:8001/v1 --baseline base.json  # PASS / FAIL / INCONCLUSIVE
uv run brasskey bench http://127.0.0.1:8001/v1 --compare http://127.0.0.1:8000/v1

uv run brasskey doctor --security       # exposed model servers, keys, Docker, firewall
uv run brasskey doctor --security http://gpu-box:8000/v1   # check a server you run elsewhere
uv run brasskey run qwen3-4b --host 0.0.0.0 --generate-api-key   # reachable from your network
```

Every command supports `--json` (one JSON document on stdout), `--debug` (logs and full
tracebacks on stderr) and `--yes` (skip confirmations), and ends with a `Next:` suggestion.

## Secure and private by default

Servers bind to `127.0.0.1`. Any other address requires a strong API key (from
`BRASSKEY_API_KEY` or your OS keychain, never a command-line argument). There is no telemetry,
and prompt content is never logged. See [SECURITY.md](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/SECURITY.md).

## Contributing

See [CONTRIBUTING.md](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/CODE_OF_CONDUCT.md).

## License and pledge

Apache-2.0 (see [LICENSE](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/LICENSE) and [NOTICE](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/NOTICE)). **The Brasskey core is Apache 2.0 and
stays Apache 2.0.** Paid features for organizations live in separate repositories and never
change the license of this one. The Brasskey name and logo are trademarks of Prcept AI LLP; see
[TRADEMARKS.md](https://github.com/Prcept-AI/brasskey/blob/v0.1.0a1/TRADEMARKS.md).

Made by Prcept AI LLP.
