Metadata-Version: 2.5
Name: biocognia
Version: 0.1.0
Summary: The client every BioCognia product uses for licences, devices and AI credits
Author-email: Ajit Johnson Nirmal <ajitjohnson.n@gmail.com>
License-Expression: LicenseRef-Proprietary
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: platformdirs>=4
Description-Content-Type: text/markdown

# biocognia

The client every BioCognia product (SCIMAP Pro, Plexora, and the tools that
join later) uses for its licence, its devices and its AI credits. A port of
Plexora's licensing client, parameterised by product.

```python
from biocognia import Guard, Licensing, Product

PRODUCT = Product.from_manifest("manifest.json", version=__version__)
LICENSING = Licensing(PRODUCT)
GUARD = Guard(LICENSING)

GUARD.check("streaming")      # raises EntitlementRequired, or returns
GUARD.limit("max_cells")      # an int, or None for unlimited
```

- **Certificates.** `BIOC1.<kid>.<canonical JSON>.<Ed25519>`, signed only by
  the platform (`bioc-core`), verified offline here. `aud` names one product;
  entitlements and limits are that product's own. No personal data.
- **Devices.** One random secret per machine (`environment.json`), shared by
  every product; the platform is told its hash and compares it on every
  certificate. Connecting a device from one product connects it for all.
- **Activation.** `<cli> license activate` prints a short code; the person
  approves it at `account.biocognia.com`; the certificates arrive. Codes and
  `BIOCT1_` tokens from the portal work without a browser.
- **Offline.** Cached certificate to expiry, then grace, then the product's
  free tier. `.bioc` files for air-gapped machines; `BIOCD1` job certificates
  for clusters without `$HOME`; `BIOCOGNIA_OFFLINE=1` forbids every call.
- **AI.** `gateway.TokenSource` exchanges the certificate for a 30-minute
  `BIOCAI1` token; `gateway.GatewayClient` is the transport and the account
  endpoints. The model call itself lives in the harness.

`import biocognia` is stdlib-only: no file, thread, socket or third-party
import until something asks.

## Layout

| Module | Does |
| --- | --- |
| `product` | `Product` from the product's manifest; `validate_manifest` |
| `certificate`, `delegation` | `BIOC1` and `BIOCD1` parse and verify |
| `entitlements` | colon-path grants with ancestor match |
| `environment`, `store` | the device secret, where files live, the environment variables |
| `state` | `Licensing`: resolution, expiry, refresh, activation, lease |
| `client` | `api.biocognia.com/v1` |
| `guard` | `Guard`: `check`, `allows`, `limit`, refusal as data |
| `gateway` | `TokenSource`, `GatewayClient` |
| `cli` | the shared `license` verbs |
| `codes` | the platform's error codes, pinned by both halves |
| `testing` | `Issuer`, `FakeService`, opt-in pytest fixtures |

## Vectors

`vectors/biocognia-vectors.json` holds certificates signed with a public,
test-only key. The platform's test suite re-signs every payload and compares
bytes; this repository verifies every one. `python tools/make_test_vectors.py
--check` fails when the file is stale.

## Development

```bash
uv venv ~/.venvs/biocognia && VIRTUAL_ENV=~/.venvs/biocognia uv pip install -e . pytest
~/.venvs/biocognia/bin/python -m pytest
```

Keep the virtual environment outside any synced folder.
