cydeai-client 0.1.0__tar.gz

cydeai_client-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include pyproject.toml
+include TEST_MATRIX.md
+include examples/*.toml
+recursive-include docs *.md
+recursive-exclude docs/codex_prompts *
+global-exclude .DS_Store
+global-exclude ._*

cydeai_client-0.1.0/PKG-INFO

@@ -0,0 +1,491 @@
+Metadata-Version: 2.4
+Name: cydeai-client
+Version: 0.1.0
+Summary: CLI client for Cysic decentralized AI providers
+Author: Cysic
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/cysic-labs/cydeai-client
+Project-URL: Documentation, https://github.com/cysic-labs/cydeai-client#readme
+Project-URL: Issues, https://github.com/cysic-labs/cydeai-client/issues
+Keywords: cysic,cydeai,vllm,gpu,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# cydeai
+
+`cydeai` is the CLI client for Cysic decentralized AI providers. It is intended to run on provider GPU machines, collect hardware details, verify that vLLM is running on NVIDIA GPU memory, then connect the worker to `cydeai-server`.
+
+The MVP is intentionally narrow: it does not start vLLM, install models, configure tunnels, interact with chain contracts, or manage system services.
+
+The formal worker flow is `cydeai connect`: run local readiness checks, open the WebSocket worker tunnel, send the `register` control message on `stream_id=0`, then proxy inference streams to the local vLLM endpoint. The older `cydeai register` command is kept only as a legacy REST/compatibility path.
+
+## Requirements
+
+- Python 3.11 or newer.
+- `nvidia-smi` on Linux GPU provider machines.
+- A running vLLM process serving the configured model.
+- A server-issued `api_key` for the provider.
+- Network access to the configured `cydeai-server` inference router.
+
+Development and unit tests must also work on macOS without NVIDIA GPU, `nvidia-smi`, vLLM, or a real server.
+
+## Install
+
+From a local checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+After installation, the CLI command should be available as:
+
+```bash
+cydeai --help
+```
+
+## Build A Wheel
+
+Install build tooling:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Build wheel and source distribution:
+
+```bash
+rm -rf dist build src/cydeai.egg-info
+python -m build
+python -m twine check dist/*
+```
+
+Clean-install the wheel in a temporary environment:
+
+```bash
+python -m venv /tmp/cydeai-wheel-test
+. /tmp/cydeai-wheel-test/bin/activate
+python -m pip install -U pip
+python -m pip install dist/cydeai_client-*.whl
+cydeai --help
+cydeai check --json
+deactivate
+rm -rf /tmp/cydeai-wheel-test
+```
+
+On macOS, `cydeai check --json` may report a controlled failure because
+`nvidia-smi` is unavailable. That is acceptable for packaging smoke tests.
+
+See `docs/pypi_release.md` for the full TestPyPI/PyPI release process.
+
+## Configuration
+
+Configuration values are merged in this order:
+
+```text
+CLI args > environment variables > config file > defaults
+```
+
+The default config path is:
+
+```text
+~/.config/cydeai/config.toml
+```
+
+An example file is provided at `examples/config.toml`.
+
+Common options:
+
+```bash
+--server-url
+--provider-id
+--address
+--api-key
+--worker-name
+--model-name
+--model-port
+--router-url
+--model-endpoint
+--max-num-seqs
+--initial-window-bytes
+--config
+--json
+--dry-run
+```
+
+`cydeai connect` uses these values to build the WebSocket handshake and register control message. `cydeai register` uses the same compatibility options for the legacy REST payload.
+
+Environment variable names should mirror the option names with a `CYDEAI_` prefix, for example:
+
+```bash
+export CYDEAI_SERVER_URL="http://127.0.0.1:8000"
+export CYDEAI_API_KEY="provider-api-key"
+```
+
+For the WebSocket worker protocol, `api_key` is required. It is sent as the `PROVIDER_SIGN` handshake header. `address` is optional and, when provided, is sent as the `PROVIDER_ADDRESS` handshake header.
+
+`provider_id` is not part of the current server WebSocket protocol. If kept in local config, it is only a local compatibility or display field and should not be treated as the formal server identity.
+
+`worker_id` is generated automatically from the local machine hardware MAC
+address. The client sends the normalized MAC-based id with this shape:
+
+```text
+w-<12 lowercase hex characters>
+```
+
+Users should not configure `worker_id`. Existing `worker_id` values in config
+files or `CYDEAI_WORKER_ID` are ignored.
+
+The ID is `w-` plus `normalized_mac`, where `normalized_mac` is the 48-bit MAC
+address rendered as 12 lowercase hex characters without separators.
+
+`model_name` is sent to the server in the register control message for scheduling. The client should only require it to be a non-empty string. It should not enforce a hardcoded local model allowlist, because the server is responsible for deciding whether a submitted model name is accepted or schedulable.
+
+## Commands
+
+### `cydeai info`
+
+Prints detected hardware information:
+
+- CPU model
+- total memory
+- GPU model and count
+
+Example:
+
+```bash
+cydeai info --json
+```
+
+### `cydeai check`
+
+Runs local readiness checks for the worker. This command only inspects the
+local machine; it does not connect to the server.
+
+It collects:
+
+- CPU model.
+- Total system memory.
+- NVIDIA GPU model and count.
+- Per-GPU memory total, used memory, and memory usage percentage.
+- vLLM-related local processes.
+- GPU process ownership from `nvidia-smi`.
+
+The check passes only when all of the following are true:
+
+- At least one NVIDIA GPU is detected.
+- At least one GPU has memory usage greater than 10%.
+- At least one vLLM process exists.
+- At least one vLLM PID appears in the GPU process list returned by `nvidia-smi`.
+
+If `nvidia-smi` is missing, vLLM is missing, GPU memory usage is too low, or the vLLM PID is not using GPU memory, the command must fail cleanly with a clear reason. It should not crash.
+
+Example:
+
+```bash
+cydeai check --json
+```
+
+On macOS development machines without NVIDIA GPU, this command is expected to report a controlled failure in structured JSON.
+
+Successful output includes:
+
+```json
+{
+  "passed": true,
+  "reason": "vLLM is running and using NVIDIA GPU memory"
+}
+```
+
+Failure output includes a structured reason, for example:
+
+```json
+{
+  "passed": false,
+  "reason": "nvidia-smi is not available"
+}
+```
+
+The purpose of this command is to gate `cydeai connect`: before the client joins
+the network, it verifies that the machine is a real GPU/vLLM worker and that
+vLLM is actually using NVIDIA GPU memory.
+
+### `cydeai connect`
+
+Official worker flow. `cydeai connect` first runs the same readiness checks as `cydeai check`. If GPU/vLLM validation fails, it prints a structured local failure and does not connect to the server.
+
+After readiness passes, it establishes a WebSocket connection to:
+
+```text
+GET ws://<router-host>:8080/v1/provider/connect
+```
+
+The WebSocket handshake uses:
+
+- `PROVIDER_SIGN`: required `api_key`
+- `PROVIDER_ADDRESS`: optional `address`
+
+Then it sends a `CONTROL` frame on `stream_id=0` with a `register` message:
+
+```json
+{
+  "type": "register",
+  "ts": 1716700000,
+  "payload": {
+    "worker_id": "w-aabbccddeeff",
+    "worker_name": "gpu-node-01",
+    "model_name": "llama-3.1-8b",
+    "max_num_seqs": 32,
+    "model_endpoint": "http://127.0.0.1:8000/v1"
+  }
+}
+```
+
+The local hardware summary and check result are used as a client-side gate. They are not part of the documented WebSocket register payload unless the server protocol is extended later.
+
+Normal output must not print the raw `api_key`; it should be masked.
+
+Example:
+
+```bash
+cydeai connect \
+  --server-url ws://127.0.0.1:8080/v1/provider/connect \
+  --api-key provider-api-key \
+  --worker-name gpu-node-01 \
+  --model-name llama-3.1-8b \
+  --model-port 8000 \
+  --json
+```
+
+### `cydeai register` legacy REST compatibility
+
+`cydeai register` is not the formal worker connection path. It is retained for legacy REST compatibility and sends a payload to:
+
+```text
+POST {server_url}/api/v1/workers/register
+```
+
+Legacy required fields:
+
+- one of `provider_id`, `address`, or `api_key`
+- automatically generated `worker_id`
+- `worker_name`
+- `model_name`
+- `model_port`
+- hardware summary
+- check result
+
+Dry run prints the legacy REST payload without sending an HTTP request:
+
+```bash
+cydeai register \
+  --dry-run \
+  --server-url http://127.0.0.1:8000 \
+  --api-key provider-api-key \
+  --worker-name gpu-node-01 \
+  --model-name llama-3.1-8b \
+  --model-port 8000 \
+  --json
+```
+
+## Local Verification
+
+Run these commands before claiming the client is complete:
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+cydeai --help
+cydeai check --json
+cydeai connect --dry-run --server-url ws://127.0.0.1:8080 --api-key test-secret --worker-name gpu-node-01 --model-name new-server-model --model-port 8000 --json
+```
+
+`cydeai check --json` may fail on macOS because there is no NVIDIA GPU, but it must fail cleanly with structured output.
+
+## Start Client On A Linux GPU Machine
+
+Use this flow on a provider GPU machine after vLLM is already running. The
+client does not start vLLM, install models, or configure system services.
+
+Enter the remote project directory and activate the virtual environment:
+
+```bash
+ssh shanxiTitan57
+cd ~/cydeai-client-test
+. .venv/bin/activate
+```
+
+If the `cydeai` command is not installed in the environment:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Verify the local GPU/vLLM gate before connecting to the server:
+
+```bash
+cydeai check --json
+```
+
+The command should return `"passed": true`. If it fails, fix the local GPU,
+`nvidia-smi`, or vLLM state before starting the worker connection.
+
+Set the server-issued worker API key. Avoid writing raw keys into files or
+shell history when possible:
+
+```bash
+read -s WORKER_API_KEY
+export WORKER_API_KEY
+```
+
+Start the client in the foreground:
+
+```bash
+PYTHONUNBUFFERED=1 cydeai connect \
+  --server-url https://api-testnet.prover.xyz/cysicdai \
+  --api-key "$WORKER_API_KEY" \
+  --address 0xtest0000000000000000000000000000000000 \
+  --worker-name gpu-node-01 \
+  --model-name qwen3-coder \
+  --model-port 8000 \
+  --json
+```
+
+Successful startup prints structured events similar to:
+
+```json
+{"attempt": 1, "connect_url": "wss://api-testnet.prover.xyz/cysicdai/v1/provider/connect", "event": "connect_attempt"}
+{"attempt": 1, "event": "registered", "result": {"registered": true, "status": "available"}, "worker_id": "w-aabbccddeeff"}
+```
+
+Use the `worker_id` from the `registered` event in the gateway path for manual
+testing.
+
+After registration, the client keeps the WebSocket open, sends application-level
+CONTROL heartbeat every 30 seconds by default, proxies gateway streams to local
+vLLM, and reconnects after reconnectable disconnects.
+
+For temporary background testing, use `nohup`:
+
+```bash
+nohup env PYTHONUNBUFFERED=1 cydeai connect \
+  --server-url https://api-testnet.prover.xyz/cysicdai \
+  --api-key "$WORKER_API_KEY" \
+  --address 0xtest0000000000000000000000000000000000 \
+  --worker-name gpu-node-01 \
+  --model-name qwen3-coder \
+  --model-port 8000 \
+  --json > cydeai-worker.log 2>&1 &
+```
+
+Inspect and stop the temporary background process:
+
+```bash
+tail -f cydeai-worker.log
+pgrep -af "cydeai connect"
+pkill -f "cydeai connect"
+```
+
+This is only a temporary run method. A production deployment should use a
+dedicated service manager configuration, such as a systemd unit, once that is
+designed and approved.
+
+## Remote Linux Verification
+
+Use the Linux GPU machine only for integration testing. Do not make destructive changes, stop services, install system packages, or modify system configuration without explicit approval.
+
+Prepared remote verification commands. Do not run these until remote validation is explicitly requested.
+
+First verify the remote environment:
+
+```bash
+ssh shanxiTitan52 'python3 --version && command -v nvidia-smi && nvidia-smi'
+```
+
+Sync the checkout to a temporary remote directory with tar over SSH. This is preferred over `rsync` so macOS metadata can be disabled consistently:
+
+```bash
+ssh shanxiTitan52 'rm -rf ~/cydeai-client-test && mkdir -p ~/cydeai-client-test'
+COPYFILE_DISABLE=1 tar \
+  --exclude .DS_Store \
+  --exclude '._*' \
+  --exclude .git \
+  --exclude .venv \
+  --exclude __pycache__ \
+  --exclude .pytest_cache \
+  --exclude '*.egg-info' \
+  -cf - . | ssh shanxiTitan52 'cd ~/cydeai-client-test && tar -xf -'
+ssh shanxiTitan52 'cd ~/cydeai-client-test && find . \( -name ".DS_Store" -o -name "._*" \) -delete'
+```
+
+Run tests and CLI smoke checks remotely:
+
+```bash
+ssh shanxiTitan52 'cd ~/cydeai-client-test && python3 -m venv .venv && . .venv/bin/activate && python -m pip install -U pip && python -m pip install -e ".[dev]" && pytest'
+ssh shanxiTitan52 'cd ~/cydeai-client-test && . .venv/bin/activate && cydeai --help'
+ssh shanxiTitan52 'cd ~/cydeai-client-test && . .venv/bin/activate && cydeai check --json'
+ssh shanxiTitan52 'cd ~/cydeai-client-test && . .venv/bin/activate && cydeai connect --dry-run --server-url ws://127.0.0.1:8080 --api-key test-secret --worker-name gpu-node-01 --model-name new-server-model --model-port 8000 --json'
+ssh shanxiTitan52 'cd ~/cydeai-client-test && . .venv/bin/activate && cydeai register --dry-run --server-url http://127.0.0.1:8000 --provider-id provider123 --worker-name gpu-node-01 --model-name llama-3.1-8b --model-port 8000 --json'
+```
+
+## Development Notes
+
+Keep system calls injectable or mockable. Do not execute system commands at import time.
+
+Expected package layout:
+
+```text
+src/cydeai/
+  __init__.py
+  cli.py
+  config.py
+  hardware.py
+  checks.py
+  processes.py
+  models.py
+  validation.py
+  client.py
+  protocol.py
+  tunnel.py
+  streams.py
+  vllm_proxy.py
+```
+
+The `protocol.py`, `tunnel.py`, `streams.py`, and `vllm_proxy.py` modules are expected for the WebSocket worker protocol implementation:
+
+- `protocol.py`: binary frame encode/decode and control message helpers.
+- `tunnel.py`: WebSocket connection, handshake headers, register control message, read loop, and reconnect decisions.
+- `streams.py`: stream lifecycle, per-stream window accounting, and frame dispatch.
+- `vllm_proxy.py`: byte-level bridge between server streams and the local vLLM endpoint.
+
+Recommended test coverage:
+
+- config precedence
+- GPU info parsing
+- memory usage greater than 10% passes
+- memory usage less than or equal to 10% fails
+- missing `nvidia-smi` fails cleanly
+- missing vLLM fails cleanly
+- vLLM PID not in GPU process list fails
+- valid and invalid worker IDs
+- API key/address identity handling
+- dry-run payload construction
+- CLI help
+- protocol frame encode/decode
+- register control message construction
+- WebSocket handshake headers mask raw API keys in output
+- local check failure prevents server connection
+- model name is required but not locally allowlisted