Metadata-Version: 2.4
Name: aidsc
Version: 0.1.3
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.9
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: Lightweight Classroom Inference Client

`aidsc` is a Python client designed for students and researchers to perform LLM inference on classroom clusters. It acts as a gateway to the **Zeus** control plane, allowing you to run models on high-performance classroom hardware from your local machine.

## 🚀 Key Features

- **Classroom-Ready**: Built specifically for inferencing classroom machines running LLMs.
- **Seamless Remote Access**: Works via SSH tunneling to bridge the gap between your local environment and the school's internal network.
- **Port Mapping**: Automatically maps the remote Zeus port `32553` to your `localhost:32553`.
- **Lightweight & Typed**: A small but powerful client with Pydantic-validated payloads for reliable integration.

---

## 🌐 Connectivity: Zeus & PAMD

Depending on your network location, there are two ways to connect:

1.  **Direct (Localhost)**: If you already know what **Zeus** is and it is reachable on your network (or you are running it locally), `aidsc` connects directly to `http://127.0.0.1:32553`.
2.  **Remote (PAMD Tunnel)**: If Zeus is not reachable, you must connect through **PAMD**.
    *   The client uses **SSH Tunneling** to bring the remote inference port to your machine.
    *   **Goal**: Bridge `remote:32553` → `localhost:32553`.
    *   **Logic**: The client will prompt for your PAMD credentials and establish a background tunnel via `ssh -f -N -L`.

---

## 📦 Installation

From the root of this repository:

```bash
uv sync
```

`aidsc` is installed as an editable package. You can then import it in your Python scripts:

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

---

## 🛠️ Setup & Usage

### 1. Interactive Bootstrap
If you are running this for the first time or need to set up your SSH tunnel, use the interactive setup:

```python
from aidsc import aidsc

client = aidsc()
client.setup_interactive()  # Prompts for PAMD username and establishes the tunnel
```

### 2. Performing Inference
Once connected, you can send requests to the classroom machines.

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

# Initialize client (reads .env automatically)
client = aidsc()

# Define your request
req = LanguageInferenceRequest(
    args=LanguageArgs(
        model="gpt-oss-20b",
        questions=["Explain quantum entanglement in one sentence."],
    ),
    max_new_tokens=256,
)

# Send to a specific classroom machine (e.g., class117)
# Zeus handles the orchestration; you just provide the request.
response = client.infer(req, server=117)
print(response)
```

---

## ⚙️ Environment Variables

The client reads from a `.env` file (created automatically during `setup_interactive()`).

| Variable | Default | Purpose |
|----------|---------|---------|
| `aidsc_ZEUS_LOCAL_URL` | `http://127.0.0.1:32553` | The primary endpoint for inference. |
| `PAMD_USER` | *(Prompted)* | Your school SSH username for the PAMD jump host. |
| `aidsc_ZEUS_REMOTE_URL` | `http://144.174.11.196:32553` | The internal IP of the Zeus host. |

---

## 🏗️ Technical Layout

| Component | Responsibility |
|-----------|----------------|
| `src/aidsc/client.py` | Main entry point; handles high-level orchestration and tunneling logic. |
| `src/aidsc/models.py` | Data schemas for inference requests and responses. |
| `src/aidsc/connectivity.py` | SSH tunnel verification and health checking. |
| `src/aidsc/zeus_client.py` | Low-level HTTP communication with the Zeus API. |

