Metadata-Version: 2.4
Name: cyai-client
Version: 0.1.0
Summary: CLI client for Cysic decentralized AI providers
Author: Cysic-Curry
License-Expression: LicenseRef-Proprietary
Keywords: cysic,cyai,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"

# cyai-client Wheel Release Usage Notes

Version `0.1.0` starts the `cyai-client` distribution.

## Install

```bash
python3 -m venv ~/cyai-client-env
. ~/cyai-client-env/bin/activate
python -m pip install -U pip
python -m pip install cyai-client==0.1.0
cyai --help
```

## Configure

Create `~/.cyai/config.json`:

```bash
mkdir -p ~/.cyai
cat > ~/.cyai/config.json <<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,
  "vllm_health_interval_sec": 30,
  "vllm_health_timeout_sec": 5,
  "vllm_health_failure_threshold": 2,
  "debug": false
}
EOF
chmod 600 ~/.cyai/config.json
```

The client reads values in this order:

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

## Check Local vLLM

`cyai check` sends a tiny OpenAI-compatible chat request to the local model
server. It does not inspect GPU utilization or require `nvidia-smi`.

```bash
cyai check
```

Expected success:

```text
[INFO][2026-07-09 10:00:00] vLLM normal
```

If it fails, confirm that vLLM is running and that `model_name` matches the
served model name from:

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

## Dry Run

```bash
cyai connect --dry-run
```

Dry run prints the derived WebSocket URL, masked `PROVIDER_SIGN` header,
register payload, and local vLLM check result. It does not connect to the
server and does not print the raw API key.

## One-Shot Register Test

```bash
cyai connect --exit-after-register
```

This validates WebSocket handshake and `register_ok`, then exits.

## Start Worker

```bash
cyai connect
```

Keep this process running. Logs are printed to the terminal and appended to:

```text
~/.cyai/cyai.log
```

Output format:

```text
[INFO][2026-07-09 10:00:00] connect attempt 1: wss://...
[INFO][2026-07-09 10:00:00] registered: attempt=1 worker_id=w-... status=available
```

After registration, the client checks local `GET /v1/models` every 30 seconds
by default. After two consecutive failures, it closes the current gateway
connection, keeps the process alive, and reconnects after vLLM recovers.
Failures include host, port, URL, request body, response body, status code,
response time, and reason in the log.

## Migrate From cydeai-client

The old and new distributions share the internal `cydeai` Python namespace.
Remove the old package before installing this release:

```bash
python -m pip uninstall cydeai-client
python -m pip install cyai-client==0.1.0
cyai --help
```

When `~/.cyai/config.json` is absent, the client can temporarily read the old
`~/.cydeai/config.json` and `CYDEAI_*` environment variables and emits a
migration warning.

## Debug Server Errors

Normal mode logs only stable error categories such as `http_403` or
`websocket_closed_1008`. To include the error description returned by the
server, run:

```bash
cyai connect --debug
```

Debug mode can also be enabled with `"debug": true` in the config file or
`CYAI_DEBUG=true`. Server details are normalized to one line, truncated, and
the active provider API key is masked before logging.

## Release Notes Checklist

- package name: `cyai-client`
- CLI command: `cyai`
- version: `0.1.0`
- install command: `python -m pip install cyai-client==0.1.0`
- required Python version: Python 3.11+
- vLLM must already be running locally
- config path: `~/.cyai/config.json`

