Metadata-Version: 2.4
Name: aidsc
Version: 0.1.0
Summary: Package for Inferencing AI at DSC
Project-URL: Homepage, https://github.com/brendito/DSCAI
Author: Brendon DGR
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.13.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# aidsc

Small Python client for the **Zeus** control plane (`vllm-orchestrator`): typed **language** inference payloads, **health checks**, optional **PAMD SSH** when Zeus is not on localhost, and `POST /api/requests`.

## Install (this monorepo)

From the repository root:

```bash
uv sync
```

`aidsc` is linked as an editable path dependency; then:

```python
from aidsc import aidsc, LanguageArgs, LanguageInferenceRequest
```

## Quick usage

```python
from aidsc import aidsc, LanguageArgs, LanguageInferenceRequest

client = aidsc()  # reads .env via python-dotenv
client.ensure_ready()

req = LanguageInferenceRequest(
    args=LanguageArgs(
        model="gpt-oss-20b",
        questions=["Answer in one sentence: what is 2+2?"],
    ),
    max_context_length=8192,
    max_server_uptime=604800,
    max_new_tokens=512,
    total_concurrent_models=1,
    max_num_seqs=8,
)
out = client.infer(req, server=117)  # pin class117.sc.fsu.edu
print(out)
```

## How this relates to Zeus

1. **Your code** builds a `LanguageInferenceRequest` and calls `aidsc.infer`, which sends JSON to **`POST /api/requests`** on Zeus (see [app.py](../../app.py)).
2. **Zeus** validates a `ZeusRequest`, picks a lab machine (or honors `server`), and drives the receiver on that host over SSH (see [utils/ssh/orchestrator.py](../../utils/ssh/orchestrator.py)).
3. **`GET /api/zeus-health`** on Zeus returns `{"healthy": true}` for local liveness only.

## Environment variables

| Variable | Purpose |
|----------|---------|
| `aidsc_ZEUS_LOCAL_URL` | Default `http://127.0.0.1:32553` — Zeus when you are on the Zeus host. |
| `aidsc_ZEUS_REMOTE_URL` | Default `http://144.174.11.196:32553` — Zeus URL as reachable **from PAMD** (used when localhost is down). |
| `aidsc_SSH_PAMD` | Full SSH prefix, e.g. `ssh user@pamd.sc.fsu.edu`, used when localhost health fails. |

Interactive bootstrap (writes `.env` and ensures `.gitignore` contains `.env` when in a git repo):

```python
aidsc().setup_interactive()
```

## Payload shape

Matches `data/sample_payload.json`: `type` is always `"language"` for now; `args` holds `model` and `questions`. These map to Zeus ``POST /api/requests`` fields:

| Field | Zeus JSON key | Default |
|--------|----------------|---------|
| `max_context_length` | `max_context_length` | `8192` |
| `max_model_len` | *(alias for* `max_context_length` *)* | — |
| `max_server_uptime` | `max_server_uptime` | `604800` (7 days) |
| `max_new_tokens` | `max_new_tokens` | `512` |
| `total_concurrent_models` | `total_concurrent_models` | `1` |
| `max_num_seqs` | `max_num_seqs` | `8` |

``aidsc.infer(..., max_new_tokens=...)`` still overrides the request’s ``max_new_tokens`` when passed.

## Layout

| Path | Role |
|------|------|
| `src/aidsc/client.py` | `aidsc`, mapping to Zeus JSON |
| `src/aidsc/models.py` | Pydantic payload models |
| `src/aidsc/zeus_client.py` | HTTP health + `/api/requests` |
| `src/aidsc/connectivity.py` | Localhost vs PAMD+remote health |
| `src/aidsc/env_bootstrap.py` | `.env` load, `.gitignore` for `.env` |
