aidsc 0.1.3

Package for Inferencing AI at DSC

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:

uv sync

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

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:

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.

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.