Metadata-Version: 2.4
Name: cohesix
Version: 1.1.0b0
Summary: Cohesix Python client (filesystem + TCP console backends)
License: Apache-2.0
Project-URL: Homepage, https://github.com/lukasbower/cohesix
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: integrations
Requires-Dist: docker>=7.0.0; extra == "integrations"
Requires-Dist: kubernetes>=29.0.0; extra == "integrations"
Requires-Dist: nvidia-ml-py>=12.560.30; extra == "integrations"
Provides-Extra: ml
Requires-Dist: peft>=0.15.0; extra == "ml"
Requires-Dist: transformers>=4.48.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

<!-- Copyright 2026 Lukas Bower -->
<!-- SPDX-License-Identifier: Apache-2.0 -->
<!-- Purpose: Describe Cohesix Python SDK installation, orchestration playbooks, and integration adapters. -->
<!-- Author: Lukas Bower -->
# cohesix (Python)

`cohesix` is a thin, non-authoritative Python SDK for Cohesix control-plane
operations. It mirrors existing control-file and console semantics; it does not
introduce new protocol behavior.

## Install

Editable source install:

```bash
python3 -m pip install -e tools/cohesix-py
```

With host integration adapters:

```bash
python3 -m pip install -e 'tools/cohesix-py[integrations]'
```

For the qualified native import/training workflow, see
[Private LoRA release](../../docs/PRIVATE_LORA_RELEASE.md).
`cohesix.playbooks.run_peft_release` routes plan/apply/watch/explain/verify/recover
to the same Rust CLI, journal and signed verifier. `examples/private_lora_release.py`
prepares the pinned native profile; `examples/private_lora_request.py` prepares
subsequent requests from reviewed provenance. Preparation is not execution evidence.

With PEFT/LoRA helper package probes:

```bash
python3 -m pip install -e 'tools/cohesix-py[ml]'
```

The core wheel requires Python 3.11 or later. Release compatibility is tested
on CPython 3.11 and 3.13. The wheel is target-neutral; it does not bundle or
select a QEMU/Pi manifest.

## Backends

- `TcpBackend`: direct console (`AUTH` + `ATTACH`) for single-client workflows.
- `RestBackend`: hive-gateway REST projection for multiplexed clients,
  including request-auth headers.
- `FilesystemBackend`: mounted Secure9P namespace (`coh mount`).
- `MockBackend`: deterministic `host-model` backend for tests and local demos;
  never target evidence.

Optional REST Worker bounds are declarations only, and missing bounds or
`backend_class` remain `unknown`. No backend connection, control ACK, local
file, or JSON object creates Worker READY or target proof.

## Milestone 26e Worker compatibility

Worker APIs require an explicit generated `cohesix-python-profile/v2`
contract. The QEMU contract must match the selected `qemu_smp_production` Mac
or `qemu_smp_kvm_production` Linux build. Use the Pi contract only with
`pi4_production`:

```python
from cohesix import CohesixClient, MockBackend, load_profile_contract

contract = load_profile_contract(
    "configs/generated/cohesix_python_qemu_smp_production.json",
    expected_target="qemu",
)
client = CohesixClient(
    MockBackend("out/examples/worker-model"),
    profile_contract=contract,
)

admitted = client.worker_spawn("gpu", "gpu-receipt-1")
ready = client.worker_wait_ready("gpu", "gpu-receipt-1")
closing = client.worker_teardown("gpu", "gpu-receipt-1")
```

`admitted.lifecycle == "queued"` is only request admission. `ready` is a
separate bounded telemetry observation; under Mock its proof class is
`host-model`. Heartbeat, GPU, and LoRA are executable. WorkerBus is model-only
and is refused before any backend write. Telemetry uses the generated canonical
`/shard/<label>/worker/<id>/telemetry` path; legacy `/worker` is gated by the
selected contract. A bound `MockBackend` derives the same target-specific shard
width from that contract before it creates any Worker observation.

`parse_receipt` preserves version-1 compatibility and accepts the
generation-bound GPU/LoRA receipt encodings only when classified as
`source="local-admitted"`. The exact actions are GPU grant/renew/release and
PEFT export/import/activate/rollback. Python receipt objects remain
non-authoritative; stale identity is reported as `stale`, never rebound.

The independent state axes are request admission, READY, provider completion,
receipt, artifact, execution proof, Python projection compatibility,
runtime-release acceptance, and production-use-case acceptance. The last two
remain false until their separate evidence gates promote them.

## High-level orchestration

- `CohesixOrchestrator`: typed schedule/lease/export/approval controls.
- `/proc` observability snapshots for scheduler and lease state.
- Host integration probes for `systemd`, Docker, Kubernetes, NVML, and PEFT
  runtime versions.
- Native evidence + receipt APIs on `CohesixClient`:

  - `evidence_pack(...)` and `evidence_timeline(...)`
  - `gpu_lease_with_receipt(...)` and `run_command_with_receipt(...)`

## Playbooks (bounded deployment rehearsal)

The nine built-in playbooks are control-model fixtures. They make approvals,
schedules, leases, exports, and selected local provider probes visible before a
team writes deployment-specific integration code. Their names describe the
intended composition; they do not run the named industry application, train or
serve a model, or establish provider, target, safety, or compliance acceptance.

`--list` reports each playbook's linked use-case id, current capability summary,
selected provider probes, planned control counts, and the milestone that owns
the complete live workflow:

List playbooks:

```bash
cohesix-playbook --list
```

Dry-run a playbook with no control writes, then inspect the explicit boundary:

```bash
cohesix-playbook --playbook mixed-closed-loop-ai-factory --dry-run --mock
jq '{workflow_kind, use_case_id, plan_summary, production_use_case_accepted}' \
  out/examples/playbooks/mixed-closed-loop-ai-factory/report.json
```

The expected `workflow_kind` is `control-model`, and
`production_use_case_accepted` remains `false`. Remove `--dry-run --mock` only
after selecting and reviewing a live backend; doing so submits the existing
generic control plan, not the complete sector workflow. For example:

```bash
cohesix-playbook --playbook jetson-traffic-safety --tcp-host 127.0.0.1 --tcp-port 31337
```

Artifacts are written under `out/examples/playbooks/<playbook-id>/`.
See [`docs/USE_CASES.md`](../../docs/USE_CASES.md) for the capability map and
the contribution path toward complete generated workflows.

## Existing examples

```bash
python3 tools/cohesix-py/examples/lease_run.py --mock
python3 tools/cohesix-py/examples/peft_roundtrip.py --mock
python3 tools/cohesix-py/examples/telemetry_write_pull.py --mock
```

## Evidence pack integration kits (Milestone 25e)

These examples operate on an evidence pack directory produced by
`coh evidence pack` and run offline once the pack exists.

```bash
cargo run -p coh -- --mock evidence pack --out out/evidence/mock
python3 tools/cohesix-py/examples/ci_evidence_pack.py --pack out/evidence/mock \
  --out out/evidence/mock/ci_summary.json
python3 tools/cohesix-py/examples/siem_export_ndjson.py --pack out/evidence/mock \
  --out out/evidence/mock/siem.ndjson
```

## Notes

- Target-neutral fallback bounds are generated in `cohesix/generated.py`;
  Worker identity and bounds come from an explicit target profile contract.
- Keep one TCP console client at a time (or use REST via `hive-gateway`).
- `RestBackend` sends request-auth headers when `request_auth_token` is set or
  when `HIVE_GATEWAY_REQUEST_AUTH_TOKEN`, `COHSH_REST_AUTH_TOKEN`, or
  `COH_REST_AUTH_TOKEN` is present.

Build and verify the target-neutral wheel on both supported interpreters:

```bash
python3 -m pip wheel --no-deps --wheel-dir out/python-wheels tools/cohesix-py
scripts/ci/python_compat_run.sh \
  --wheel-smoke \
  --wheel-dir out/python-wheels \
  --package-manifest out/python-compat/m26e-python-package.json \
  --state-dir out/python-compat/m26e-wheel
```

See [`docs/PYTHON_SUPPORT.md`](../../docs/PYTHON_SUPPORT.md) for target
projection commands and proof-boundary details.

## Installed CUDA and LoRA journeys

`cohesix-journey identity|validate|doctor|run` wraps the existing Rust lifecycle
and signed verifier. `cohesix.journey.run` returns the same versioned outcome
and exit mapping. Only verified requested completion returns zero; an ACK,
timeout or recovered failed canary does not. Keep state outside runner scratch.
See [Adoption](../../docs/ADOPTION.md) and [CI workflows](../../docs/CI_WORKFLOWS.md)
for exact installation, config, authority and recovery steps.
