Metadata-Version: 2.4
Name: yaarbal
Version: 0.1.2
Summary: BitTorrent-inspired peer-to-peer distributed LLM inference
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/hannanabdul55/distributed-full-gpt-inference
Project-URL: Issues, https://github.com/hannanabdul55/distributed-full-gpt-inference/issues
Project-URL: Documentation, https://github.com/hannanabdul55/distributed-full-gpt-inference/blob/main/README.md
Project-URL: Source, https://github.com/hannanabdul55/distributed-full-gpt-inference
Project-URL: Known Limitations, https://github.com/hannanabdul55/distributed-full-gpt-inference/blob/main/KNOWN_LIMITATIONS.md
Keywords: llm,p2p,distributed,inference,bittorrent,ai,ml
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography==46.0.7
Requires-Dist: flask==3.1.3
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: requests==2.32.5
Requires-Dist: torch==2.8.0
Requires-Dist: numpy==2.0.2
Requires-Dist: transformers==4.57.6
Requires-Dist: safetensors>=0.7.0
Requires-Dist: lz4==4.4.5
Provides-Extra: dev
Requires-Dist: pytest==8.4.2; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: psutil>=5.9.0; extra == "dev"
Provides-Extra: gguf
Requires-Dist: llama-cpp-python==0.3.20; extra == "gguf"
Dynamic: license-file

# Yaarbal

Yaarbal — the open model library. Contribute compute, access every model.

> ⚠ Status: early prototype. The credit economy and trust system are demo-grade; do not run production workloads on the public network.

![Yaarbal quickstart demo](docs/assets/yaarbal-quickstart.svg)

Visit [yaarbal.app](https://yaarbal.app) for the demo network.

## Quickstart

```bash
pip install yaarbal && yaarbal run qwen2.5-0.5b-instruct "hello"
```

The single command above installs `yaarbal` from PyPI and runs a one-shot inference against a small (~600 MB) Qwen 2.5 0.5B instruct model. By default it auto-discovers any seeders on your local network or the configured tracker, submits the prompt, and streams tokens back to your terminal. If no seeder is reachable, the command exits with a clear error pointing at `yaarbal seed` (see [Usage](#usage) below).

## Installation

### From PyPI (recommended)

```bash
pip install yaarbal
yaarbal --version
```

See [docs/distribution/INSTALL.md](docs/distribution/INSTALL.md) for Homebrew + Docker install paths and troubleshooting.

### Alternate: install from source

```bash
git clone https://github.com/<owner>/yaarbal
cd yaarbal
pip install -e .
```

### Requirements

- Python 3.11 or newer
- macOS or Linux (Windows is untested)
- (Optional) A Hugging Face token in `HF_TOKEN` for gated models such as Llama 3.1 8B and above

The shipped CLI works on a CPU-only laptop for small models (Qwen 0.5B, Phi-3-mini Q4_K_M, MiniGPT). GPU acceleration (CUDA / Apple MPS) is auto-detected when available; pass `--device cpu` to force CPU.

## Usage

`yaarbal` is a single binary with five subcommands. Run `yaarbal --help` for the full list.

### Run inference (one-shot)

```bash
yaarbal run qwen2.5-0.5b-instruct "your prompt here"
```

Streams tokens to stdout. Falls back to a non-streaming pull-mode if the seeder does not advertise SSE support. Configuration precedence: explicit flags > `YAARBAL_*` environment variables > `~/.yaarbal/config.toml` > built-in defaults.

### Host a seeder (contribute compute)

```bash
yaarbal seed --model qwen2.5-0.5b-instruct
```

Loads the named model end-to-end, registers with the configured tracker, and serves `/inference`, `/inference/stream`, `/v1/chat/completions`, and `/v1/models` over HTTP. Seeders earn credits on every settled inference and spend them when running `yaarbal run` against the network.

### Interactive chat

```bash
yaarbal chat --model qwen2.5-0.5b-instruct
```

Multi-turn REPL with rolling conversation history. In-REPL commands: `/models`, `/health`, `/metrics`, `/reset`, `/quit`. Honors `YAARBAL_CHAT_BACKEND=single` + `YAARBAL_SINGLE_NODE_URL` when you want to talk to a local seeder without a tracker.

### Other subcommands

| Command | Effect |
|---------|--------|
| `yaarbal status` | Credit balance, hosted models, tracker peer count (plain-text by default; `--json` for scripting) |
| `yaarbal tracker [PORT]` | Run a tracker for a self-hosted Yaarbal network (default port 8000) |
| `yaarbal ui` | Serve the local browser chat UI on `127.0.0.1:5173` (auto-opens in your browser; `--no-open` to suppress) |
| `yaarbal --version` | Print the installed package version |
| `yaarbal --help` | Full subcommand list |

### Optional swarm authentication

Set `YAARBAL_AUTH_USER` and `YAARBAL_AUTH_PASS` in the environment before starting tracker, seeders, and leechers so all HTTP traffic uses HTTP Basic Auth. If unset, authentication is disabled (typical for local dev). HTTP Basic is **not** a substitute for TLS — see [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).

## For Engineers

For the engineering deep-dive — architecture, protocol design, model registry, BitTorrent-inspired piece-wise inference, credit economy mechanics — see [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md).

For the issue tracker (open limitations, P0–P3 prioritized), see [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).

For deeper component documentation:

- [docs/architecture/](docs/architecture/) — protocol design and architectural notes
- [docs/deployment/](docs/deployment/) — Docker / multi-node deployment
- [docs/guides/](docs/guides/) — getting started, development, contributing
- [docs/testing/](docs/testing/) — test plan and manual testing guide
- [docs/api/reference.md](docs/api/reference.md) — HTTP endpoint reference
- [bittorrent/README.md](bittorrent/README.md) — internal docs for the inference-routing component
- [MODELS.md](MODELS.md) — full model catalog (30+ entries) with hardware requirements
- [QUICKSTART.md](QUICKSTART.md) — alternate single-node walkthrough and Docker (Compose) profile reference

### Run with Docker (Compose)

The repo ships role-separated services (tracker, seeder, leecher, chat-proxy) in `docker-compose.yml`. The fastest container path is the `single-node` profile, which mirrors the local quickstart:

```bash
docker compose --profile single-node up single-node
# from a second terminal:
YAARBAL_CHAT_BACKEND=single YAARBAL_SINGLE_NODE_URL=http://127.0.0.1:7001 \
  yaarbal chat --model qwen2.5-0.5b-instruct
```

Other available profiles: `default`, `convenience`, `query`, `web`. See [QUICKSTART.md](QUICKSTART.md#docker-compose) for the full profile / port matrix.

## Testing

The project ships a `pytest`-managed test suite under `tests/` covering unit, integration, regression, and large-scale tiers.

```bash
pip install -e .
make test                # full suite
make test-unit           # unit tier only
make test-integration    # integration tier only
make test-verbose        # full suite with verbose output
python -m pytest tests/unit/test_tracker.py -v   # one file
```

CI runs on every push and PR via `.github/workflows/python-ci.yml` (Python 3.10 syntax check) and `.github/workflows/pr-regression.yml` (full unittest on PRs into `main`).

## Contributing

Pull requests are welcome.

1. Fork the repository and create a feature branch.
2. Match the existing style — Python type hints + docstrings throughout; conventional-commit messages on commits.
3. Add or update tests under `tests/unit/` or `tests/integration/` for any new behavior.
4. Run `make test` to confirm a green suite before opening a PR.
5. Open a PR against `main` with a short description of the change and a link to any tracking issue.

Issues, feature requests, and protocol-design discussion: file an issue on github.com/<owner>/yaarbal. For deeper protocol questions, the research artifacts under [docs/research/](docs/research/) are a good starting point.

## Further reading

Yaarbal originated as research on P2P inference — see [docs/research/](docs/research/) for the original protocol design and rebuttal exchange.

## License

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Copyright 2026 Abdul Hannan Kanji. Licensed under Apache-2.0.
