Metadata-Version: 2.4
Name: qentl
Version: 0.6.1.post1
Summary: Qentl — Quantum Entanglement by Bloch Inc. Command-line interface.
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: cryptography>=42
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Provides-Extra: qwen
Requires-Dist: torch>=2.2; extra == "qwen"
Requires-Dist: transformers>=4.40; extra == "qwen"
Requires-Dist: accelerate>=0.29; extra == "qwen"
Provides-Extra: qwen-quant
Requires-Dist: qentl[qwen]; extra == "qwen-quant"
Requires-Dist: bitsandbytes>=0.43; extra == "qwen-quant"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: artifacts
Requires-Dist: python-pptx<2,>=1.0; extra == "artifacts"
Requires-Dist: reportlab<5,>=4; extra == "artifacts"
Requires-Dist: openpyxl<4,>=3.1; extra == "artifacts"
Requires-Dist: pypdf<7,>=5; extra == "artifacts"
Requires-Dist: Pillow<13,>=11; extra == "artifacts"
Provides-Extra: graphus
Requires-Dist: tree-sitter==0.23.2; extra == "graphus"
Requires-Dist: tree-sitter-javascript==0.23.1; extra == "graphus"
Requires-Dist: tree-sitter-typescript==0.23.2; extra == "graphus"

# BlockAI

**BlockAI** é uma rede de inferência de IA descentralizada: nós com GPU se
conectam a uma blockchain própria, recebem tarefas de inferência de um
modelo de linguagem (por padrão, [Qwen](https://github.com/QwenLM/Qwen)),
executam o cálculo e são recompensados em tokens **BAI** quando o resultado
bate com o de outros nós que rodaram a mesma tarefa — um mecanismo que
chamamos de **Proof-of-Compute**.

Este repositório é o protótipo funcional (v0): uma blockchain própria em
Python, um coordenador HTTP que escalona o trabalho, e um agente de nó que
detecta a GPU local e a oferece à rede.

O novo comando `blochai` oferece um terminal conversacional, Bloch Agents,
geração de documentos e um workspace com contas Qentl por convite e sincronização CLI com o Graphus. Instalação,
operação contínua e limitações verificadas estão em
[`docs/BLOCHAI_WORKSPACE.md`](docs/BLOCHAI_WORKSPACE.md).

## Como funciona

```
usuário               coordenador (blockchain)              nós de GPU
  │  TASK_SUBMIT + taxa        │                                  │
  ├───────────────────────────►│                                  │
  │                            │  escalona p/ N nós elegíveis     │
  │                            ├─────────────────────────────────►│
  │                            │        (heartbeat, stake)        │
  │                            │◄─────────────────────────────────┤
  │                            │      TASK_RESULT (assinado)      │
  │                            │◄─────────────────────────────────┤
  │                            │  consenso (hash/similaridade)    │
  │                            │  TASK_SETTLE: paga vencedores,    │
  │                            │  corta stake de divergentes,      │
  │                            │  reembolsa se não houver quorum   │
  │◄───────────────────────────┤                                  │
  │        resultado           │                                  │
```

- **Blockchain** (`blockai/chain`): contas, saldos e nonces em BAI (unidade
  inteira, 1 BAI = 1e6 unidades); transações assinadas com Ed25519; blocos
  com raiz de Merkle assinados pela autoridade (Proof-of-Authority na
  ordenação — ver roadmap); reconstrução total do estado por replay
  (`Blockchain.validate_chain`).
- **Proof-of-Compute** (`blockai/chain/consensus.py`): cada tarefa é
  replicada em `replication` nós (padrão 2). Os resultados são agrupados por
  hash exato dos tokens gerados e, secundariamente, por similaridade de
  texto (para tolerar não-determinismo leve de hardware). O grupo majoritário
  recebe a taxa + subsídio do tesouro, proporcional aos tokens gerados; os
  nós divergentes sofrem *slashing* de parte do stake e perdem reputação. Sem
  consenso, a taxa é devolvida ao usuário.
- **Coordenador** (`blockai/network`): API FastAPI que recebe transações,
  atende heartbeats dos nós, escalona tarefas pendentes (`scheduler.py`,
  ponderado por stake × reputação × VRAM) e roda um laço de fundo que
  liquida tarefas prontas e produz blocos.
- **Nó de GPU** (`blockai/worker`): detecta a GPU local (`torch.cuda`,
  `nvidia-smi`, MPS da Apple, ou fallback CPU), registra-se na cadeia, faz
  stake, e entra num loop de heartbeat → busca trabalho → executa → envia
  resultado assinado.
- **Backends de modelo** (`blockai/model`): `QwenBackend` roda modelos
  `Qwen2.5-*-Instruct` via `transformers` com decodificação gulosa
  (determinística, essencial para o consenso); `MockBackend` gera saída
  determinística sem GPU/dependências pesadas, para desenvolvimento e CI.
- `blockai/model/sharding.py` calcula, a partir da VRAM anunciada pelos nós,
  um plano de particionamento em camadas para modelos maiores que não cabem
  em uma única GPU — a base para o roadmap de inferência fragmentada
  (pipeline-parallel) entre vários nós.

## Instalação

Requer Python ≥ 3.9.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .            # núcleo (coordenador, cadeia, worker com backend mock)
pip install -e ".[qwen]"    # + torch/transformers, para rodar Qwen de verdade
```

## Uso rápido (rede local de demonstração)

Terminal 1 — sobe o coordenador (cria a cadeia e a chave da autoridade em
`~/.blockai/`):

```bash
blockai coordinator --port 8000
```

Terminal 2 — sobe um nó de GPU (usa `--backend mock` por padrão; use
`--backend qwen --model Qwen/Qwen2.5-0.5B-Instruct` com uma GPU/CPU
disponível e as dependências `qwen` instaladas):

```bash
blockai worker --coordinator-url http://127.0.0.1:8000 --backend mock
```

Suba pelo menos **dois** nós (dois terminais, ou passe `--key` para caminhos
de chave diferentes) — o consenso padrão exige 2 nós concordando.

Para conectar **várias GPUs de uma mesma máquina** (ex.: uma frota de 12
GPUs de 8 GB antes usada para mineração), veja
[`docs/FLEET.md`](docs/FLEET.md) — cobre dimensionamento de modelo por VRAM
(`blockai recommend`), quantização 4-bit/8-bit, o script
`scripts/fleet.sh` que sobe um worker por GPU, e os templates systemd em
`deploy/` para rodar isso de forma persistente em produção.

Terminal 3 — envie um prompt e acompanhe o estado da rede:

```bash
blockai submit "explique blockchain em uma frase" --coordinator-url http://127.0.0.1:8000
blockai status  --coordinator-url http://127.0.0.1:8000
```

Em modo de desenvolvimento (`dev_faucet=True`, padrão), a carteira do
usuário e o stake dos nós são financiados automaticamente por um faucet do
tesouro — não é preciso configurar nada a mais para testar.

## API do coordenador

Com o coordenador no ar, a documentação interativa (Swagger) fica em
`http://127.0.0.1:8000/docs`. Principais rotas: `POST /tx` (submeter
transações), `GET /work?node=<endereço>` (nó busca trabalho), `GET /nodes`,
`GET /tasks`, `GET /chain/blocks`, `GET /shards/plan`.

## Testes

```bash
pip install -e ".[dev]"
pytest -q
```

A suíte cobre criptografia/assinaturas, transições de estado da cadeia,
o ciclo completo de uma tarefa (sucesso, divergência com slashing, e falta
de consenso com reembolso), replay/validação da cadeia salva em disco, e um
teste de integração ponta a ponta do coordenador com dois nós via
`TestClient`.

## Limitações do v0 e roadmap

Veja [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) para o detalhamento de
decisões de design e o que falta para produção: ordenação com múltiplos
proponentes (hoje é Proof-of-Authority), rede P2P entre nós (hoje é
tudo via coordenador central), inferência fragmentada real entre GPUs
(hoje o plano de sharding é calculado mas não executado), verificação
criptográfica do cálculo (hoje o consenso é por maioria de nós, não por
prova de execução), e persistência do estado além de um único arquivo JSON.

## Private portal and future GPU rewards

The [private gateway runbook](docs/PORTAL_GATEWAY.md) documents the authenticated
BlochAI portal and permissioned GPU fleet. The
[GPU contribution and BLCH rewards roadmap](docs/GPU_REWARDS_ROADMAP.md) defines
the proposed public enrollment, verified work and funded payout gates. Public
operators must never receive private tenant AML workloads. This is a plan only:
BLCH payouts are not enabled, and prototype BAI is internal accounting with no
current BLCH conversion.
