Metadata-Version: 2.4
Name: cydeai-client
Version: 0.1.3
Summary: CLI client for Cysic decentralized AI providers
Author: Cysic-Curry
License-Expression: LicenseRef-Proprietary
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-client Wheel Release Usage Notes

Use this document as the user-facing usage note when publishing a new
`cydeai-client` wheel.

## Package

Install package:

```bash
python -m pip install cydeai-client==0.1.3
```

Installed CLI command:

```bash
cydeai
```

Check installation:

```bash
cydeai --help
```

## What This Client Does

`cydeai` runs on a provider GPU machine. It:

- checks local NVIDIA GPU and vLLM readiness
- verifies vLLM is actually using GPU memory
- connects to cydeai-server through WebSocket
- registers the worker with model and endpoint metadata
- forwards gateway traffic to the local vLLM OpenAI-compatible endpoint

The client does not install or start vLLM, install models, configure systemd,
perform chain transactions, or manage system packages.

## Requirements

Run on a Linux GPU provider machine with:

- Python 3.11+
- NVIDIA driver and `nvidia-smi`
- vLLM already running
- local vLLM OpenAI-compatible API, usually `http://127.0.0.1:8000/v1`
- a server-issued provider API key
- a server URL, for example `https://<server-host>/<base-path>`

macOS can be used for basic CLI smoke tests, but `cydeai check` is expected to
fail there if `nvidia-smi` is unavailable.

## Basic Setup

Create a virtual environment:

```bash
python3 -m venv ~/cydeai-client-env
. ~/cydeai-client-env/bin/activate
python -m pip install -U pip
python -m pip install cydeai-client==0.1.3
```

Confirm the local vLLM model name:

```bash
curl -sS http://127.0.0.1:8000/v1/models | python3 -m json.tool
```

Create the default config file:

```bash
mkdir -p ~/.config/cydeai
cat > ~/.config/cydeai/config.toml <<EOF
server_url = "https://<server-host>/<base-path>"
api_key = "<provider_api_key>"
worker_name = "<worker-display-name>"
model_name = "<served-model-name-from-vllm>"
model_port = 8000
EOF
chmod 600 ~/.config/cydeai/config.toml
```

For released-wheel usage, prefer config-file based setup. The CLI still applies
this precedence internally:

```text
CLI args > environment variables > config file > defaults
```

## Local Readiness Check

Before connecting to the server, run:

```bash
cydeai check --json
```

The check passes only when:

- 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 `nvidia-smi` GPU process list

If this fails, fix the local vLLM/GPU state first.

## Dry Run

Dry run does not connect to the server. It prints the WebSocket URL, masked
headers, local check result, and register payload:

```bash
cydeai connect --dry-run
```

If `api_key` in config is set, the output should include a masked header:

```json
{
  "headers": {
    "PROVIDER_SIGN": "********"
  }
}
```

The worker id is generated automatically from the machine MAC address unless
`--worker-id` is provided explicitly for integration testing:

```json
{
  "register_control": {
    "payload": {
      "worker_id": "w-..."
    }
  }
}
```

## One-Shot Register Test

Use this to validate WebSocket handshake and worker registration without
keeping the worker online:

```bash
cydeai connect --exit-after-register
```

Expected success:

```json
{
  "registered": true,
  "status": "available"
}
```

Common failures:

- `http_401`: API key is missing, stale, or invalid
- `http_403`: provider or key is rejected by server policy
- `model not allowed`: server does not allow this model name
- local check failure: vLLM/GPU readiness gate failed before network connect

## Start Long-Running Worker

Run the worker in the foreground:

```bash
PYTHONUNBUFFERED=1 cydeai connect
```

Successful startup prints JSON events similar to:

```json
{"event":"connect_attempt","attempt":1}
{"event":"registered","worker_id":"w-...","result":{"registered":true,"status":"available"}}
```

Keep this process running.

## Notes For Release Announcements

When announcing a wheel release, include:

- package name: `cydeai-client`
- CLI command: `cydeai`
- version: `0.1.3`
- install command: `python -m pip install cydeai-client==0.1.3`
- required Python version: Python 3.11+
- reminder that vLLM must already be running locally
- reminder that `api_key` should be set in `~/.config/cydeai/config.toml`
- reminder that `cydeai connect` emits JSON by default
