Metadata-Version: 2.4
Name: black-torch
Version: 0.1.0
Summary: Governed ML training framework (KinematicHead + CoherenceReward + Safety Ramp), integrated with BCIT.
Author: Velocity Stack Research
License-Expression: Apache-2.0
Keywords: machine-learning,pytorch,training,governance,bcit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Requires-Dist: transformers
Requires-Dist: datasets
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: bcit-deps
Requires-Dist: httpx; extra == "bcit-deps"
Requires-Dist: fastapi; extra == "bcit-deps"
Requires-Dist: pydantic; extra == "bcit-deps"
Requires-Dist: uvicorn; extra == "bcit-deps"
Dynamic: license-file

# Black Torch

Governed ML training framework (KinematicHead + CoherenceReward + Safety Ramp),
integrated with BCIT for live IGCS constants, TBI-predictive lambda adaptation,
and GEE-driven training suspension. BCIT is optional at runtime — the client
fails open to defaults if it isn't running, so nothing here requires BCIT/Redis
just to try the framework.

## Install

Four ways in, depending on whether you want the library, a self-contained
demo, or the full governed stack:

| Path | Command | BCIT governance |
|---|---|---|
| **Library** | `pip install black-torch` <sup>1</sup> | fallback defaults |
| **Container** | `docker build -t black-torch . && docker run --rm black-torch` | fallback defaults |
| **Full stack** | `docker compose up --build` <sup>2</sup> | **live** |
| **From source** | [Setup](#setup), below | **live** (with BCIT running) |

<sup>1</sup> Packaged and verified, but **not yet published to PyPI** — see
[docs/PACKAGING.md](docs/PACKAGING.md).
<sup>2</sup> Needs a sibling BCIT checkout — see [Docker](#docker).

Only the paths marked **live** exercise real governance. The others run
identically but with `BCITTrainingClient` failing open to hardcoded defaults
(`tau_warm=0.50`, `tau_hot=0.85`, no GEE suspension) — fine for trying the
framework out, not a demonstration of what it does.

## Setup

Requires [uv](https://docs.astral.sh/uv/) and Python 3.10+, plus a sibling
checkout of BCIT at `../BCIT/bme_packages/2_new-version_2` (this is what
`requirements.txt` installs as an editable dependency for the real BCIT client).

```bash
# create and activate a venv
uv venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

# install dependencies into it (includes BCIT's client SDK, editable, from ../BCIT)
uv pip install -r requirements.txt
```

### Running with real BCIT

In a separate terminal, start BCIT locally (no Docker/Redis/GPU required):

```bash
cd "../BCIT/bme_packages/2_new-version_2"
./scripts/run_stack.sh      # BCIT API on :8001, console on :8092
```

Then just run Black Torch as usual — `BCITTrainingClient` connects to
`http://127.0.0.1:8001` by default (override with `BCIT_URL`). If BCIT isn't
running, every read falls back to its default and training proceeds
ungoverned-by-BCIT but otherwise identically.

Set `VELOCITY_FORCE_MOCK=1` to disable all BCIT networking outright (useful
for unit tests or CI where no BCIT instance exists at all).

Known gap: a dedicated VKM host:port doesn't exist in BCIT's actual
deployment — telemetry goes to BCIT's REST endpoint instead. Crystal has no
real implementation in BCIT yet (`crystal_chain_head` is a permanent null
placeholder), so `SyncCrystalPoller` stays a stub until a real Crystal
system exists. Behavioral Manifest → BCIT certification submission (paper
§12) also has no concrete BCIT endpoint yet and isn't implemented.

The paper's `wcs_alpha/beta/gamma/delta` IGCS constants don't exist in BCIT
by default, but BCIT's registry has no allowlist — run
`python scripts/bootstrap_wcs_constants.py` once against a running BCIT to
certify them for real (idempotent, safe to re-run). Until you do, they fall
back to Black Torch's local defaults, same as before.

## Run

```bash
python run_example.py
```

This fine-tunes `distilgpt2` on a slice of Wikitext-2 with governance enabled,
then prints the resulting Behavioral Manifest (average WCS, whether Governed
Stupidity was triggered, final lambda). Per-step audit records are written to
`./glassbox_output/`.

## Device

`run_example.py` picks the device automatically: CUDA if available, otherwise
Apple's MPS backend (Apple Silicon GPU), otherwise CPU. No configuration
needed either way.

## Docker

**Standalone** — self-contained, builds from this repo alone:

```bash
docker build -t black-torch .
docker run --rm black-torch
```

CPU-only by design: Docker has no MPS passthrough on macOS, and a GPU
deployment would start from a CUDA base image instead, so the image installs
CPU-only torch and stays around 1.9GB rather than the 9.7GB the default PyPI
torch produces. It deliberately does **not** bundle BCIT's client SDK, so
governance sits on fallback defaults (`VELOCITY_FORCE_MOCK=1` makes that
explicit rather than implicit).

**Full stack** — BCIT + Black Torch networked together:

```bash
docker compose up --build
```

This is the only containerized path that produces real governed training.
It requires a sibling checkout of BCIT at
`../BCIT/bme_packages/2_new-version_2`: compose `include:`s BCIT's own stack
file and mounts its client SDK into the Black Torch container at startup.
Until BCIT ships a registry image and a PyPI SDK, this path can't work
without that local checkout — see [docs/PACKAGING.md](docs/PACKAGING.md).

## Using it in your own training script

```python
from black_torch.governed_model import GovernedModel
from black_torch.train import governed_train

model = GovernedModel(base=your_model, hidden_dim=your_model.config.hidden_size)
manifest = governed_train(model, dataloader, optimizer, run_id="my-run")
```

`bcit` and `crystal` are optional — omit them and defaults are used
automatically until a real BCIT/Crystal deployment exists to point at.

## More docs

- [docs/RUNNING.md](docs/RUNNING.md) — full runbook: start BCIT, run Black
  Torch, verify the integration is live, troubleshooting.
- [docs/PROJECT_GUIDE.md](docs/PROJECT_GUIDE.md) — module map, training-step
  walkthrough, `RampConfig` reference, known gaps.
- [docs/PACKAGING.md](docs/PACKAGING.md) — how this ships: the wheel, the
  Docker images, and what BCIT still has to publish before the governed path
  works outside this workspace.
- [docs/SESSION_2026-09-02_BCIT_INTEGRATION.md](docs/SESSION_2026-09-02_BCIT_INTEGRATION.md) —
  what was built to wire up the real BCIT integration and how it was verified.
- [docs/SESSION_2026-09-03_HARDENING.md](docs/SESSION_2026-09-03_HARDENING.md) —
  follow-up fixes: a dead-gradient bug, the YAML deployment config, dual-layer
  attachment for deep models, a GlassBox decoder, and a test suite.
