Metadata-Version: 2.4
Name: yaarbal
Version: 0.1.5
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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<47,>=46.0.7
Requires-Dist: flask<4,>=3.1.3
Requires-Dist: python-dotenv<2,>=1.2.1
Requires-Dist: requests<3,>=2.32.5
Requires-Dist: torch<3,>=2.9
Requires-Dist: numpy<3,>=2.1
Requires-Dist: transformers<5,>=4.57.6
Requires-Dist: safetensors>=0.7.0
Requires-Dist: lz4<5,>=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 — distributed LLM inference over a credit-metered P2P network.

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

Every node hosts a complete model. A tracker brokers peer discovery. Inference requests are routed to available seeders, credits are earned by hosting and spent by querying. No central GPU pool — just peers.

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

## Quickstart

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

This auto-discovers seeders on the configured tracker (`https://tracker.yaarbal.app` by default), submits the prompt, and streams tokens to your terminal. If no seeder is reachable, the command exits with a clear error and tells you how to start one.

## Installation

### From PyPI

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

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

### From source (internal)

```bash
git clone <yaarbal repo> && cd yaarbal
pip install -e ".[dev]"
```

### Requirements

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

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

## Usage

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

### One-shot inference

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

Streams tokens to stdout. Discovers peers via the tracker; falls back to pull-mode if the seeder does not support SSE streaming. Configuration precedence: explicit flags > `YAARBAL_*` env vars > `~/.yaarbal/config.toml` > built-in defaults.

### Host a seeder

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

Loads the named model end-to-end, registers with the 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.

### Single-node mode (local, no tracker)

```bash
# Terminal 1
yaarbal seeder --mode single-node --model qwen2.5-0.5b-instruct --port 7001

# Terminal 2
YAARBAL_CHAT_BACKEND=single YAARBAL_SINGLE_NODE_URL=http://127.0.0.1:7001 \
  yaarbal chat --model qwen2.5-0.5b-instruct
```

Best for local development and offline use. See [QUICKSTART.md](QUICKSTART.md) for the full walkthrough.

### 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`.

### Other subcommands

| Command | Effect |
|---------|--------|
| `yaarbal status` | Credit balance, hosted models, tracker peer count (`--json` for scripting) |
| `yaarbal tracker [PORT]` | Run a tracker for a self-hosted Yaarbal network (default port 8000) |
| `yaarbal ui` | Serve the pre-built browser chat UI from `web/dist/` on `127.0.0.1:5173` (auto-opens browser; `--no-open` to suppress; requires `cd web && npm run build` first) |
| `yaarbal --version` | Print the installed package version |
| `yaarbal --help` | Full subcommand list |

### Browser UI (development)

To run the React frontend in dev mode:

```bash
cd web && npm install && npm run dev
```

Open `http://localhost:5173`. Configure the backend mode, model, and URLs in the Connection panel.

### Optional swarm authentication

Set `YAARBAL_AUTH_USER` and `YAARBAL_AUTH_PASS` before starting the tracker, seeders, and leechers to enable HTTP Basic Auth across all HTTP traffic. If unset, authentication is disabled. HTTP Basic is **not** a substitute for TLS — see [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).

## Docker

Role-separated services are defined in `docker-compose.yml`. The fastest path mirrors the single-node 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 profiles: `default` (tracker + minigpt seeders), `convenience` (all-in-one orchestrator), `query` (one-shot leecher), `web` (browser chat proxy). See [QUICKSTART.md](QUICKSTART.md#docker) for the full profile and port matrix.

## Testing

```bash
pip install -e ".[dev]"
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: `.github/workflows/python-ci.yml` (Python 3.10 syntax check on `*.py`) and `.github/workflows/pr-regression.yml` (`unittest discover` on PRs into `main`).

Note: `pyproject.toml` requires Python >=3.11 for installation; the CI syntax-check workflow uses 3.10. This is a known gap — see [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).

## For Engineers

Architecture, protocol design, model registry, BitTorrent-inspired inference routing, and credit economy mechanics: [PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md).

Open limitations (P0–P3 prioritized): [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md).

Deeper component documentation:

- [docs/architecture/](docs/architecture/) — protocol design and architectural notes
- [docs/api/reference.md](docs/api/reference.md) — HTTP endpoint reference
- [docs/deployment/](docs/deployment/) — Docker / multi-node deployment
- [docs/guides/](docs/guides/) — development and getting-started guides
- [docs/testing/](docs/testing/) — test plan and manual testing guide
- [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) — single-node walkthrough and Docker profile reference

## Contributing

This is a closed-source project; contributions are not accepted via public PRs. Internal contributors: see [docs/guides/development.md](docs/guides/development.md).

## Further Reading

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

## License

<!-- VERIFY: license direction — README declares Apache-2.0 but project is moving toward closed-source/proprietary. Decide whether to remove the open-source license, switch to proprietary "All rights reserved", or keep Apache-2.0 and revisit on commercial release. -->

[![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.
