hpc-as-api 0.3.2__tar.gz → 0.3.4__tar.gz

{hpc_as_api-0.3.2 → hpc_as_api-0.3.4}/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.3.4 (2026-06-10)
+
+### Messaging: domain-agnostic positioning throughout
+
+All public-facing materials now consistently present `hpc-as-api` as a
+**domain-agnostic HTTP gateway for any HPC function** — not as an LLM-specific tool.
+
+- **README**: Rewritten to lead with `HPCApp` and the general-purpose streaming
+  gateway pattern. The simulation example appears before the LLM preset. "OpenAI-compatible
+  gateway" is now framed as a built-in preset, not the product's identity.
+- **paper/paper.md**: Title changed to *"A Domain-Agnostic HTTP Gateway for HPC Functions…"*.
+  `HPCApp`, `make_app()`, and the framework architecture are now described as first-class
+  subjects. The LLM preset is introduced as one application of the framework.
+- **`hpc_as_api/__init__.py`**: Module docstring updated to lead with the domain-agnostic
+  description and mark the LLM preset as "built-in application of the framework".
+- **`pyproject.toml`**: Description updated to "Domain-agnostic HTTP gateway…"; keywords
+  updated to add `domain-agnostic` and `scientific-computing`, remove `openai`.
+
+No API or behavior changes.
+
+## 0.3.3 (2026-06-10)
+
+### Refactor: `make_app()` factory — multiple independent instances, no env-var injection
+
+`app.py` now exposes a `make_app()` factory function.  Every call returns a
+fresh, independent `FastAPI` instance that captures its configuration in closures
+— there are no module-level globals involved in request handling.
+
+**Before (0.3.x):** `create_openai_app()` in `presets/openai.py` worked by
+injecting arguments into `os.environ` and then importing the cached module-level
+singleton.  Calling it a second time with different arguments silently had no
+effect.
+
+**After:** `create_openai_app()` calls `make_app()` directly.  Each call returns
+a genuinely independent app — two gateways with different endpoints, models, or
+auth settings can live in the same process without interfering.
+
+### Fix: per-user Globus token fully wired end-to-end
+
+`app.py` now passes `caller.globus_token` to `submit_streaming_inference()` when
+the caller authenticated with a Globus token.  In 0.3.1–0.3.2, `submit_streaming_inference()`
+gained the `globus_token=` parameter but `app.py` never forwarded it.
+
+### Fix: `HPCApp` payload size check
+
+`HPCApp._add_route` now strips old images and enforces the Globus payload limit
+before submitting any job with a `messages` field.  Previously only
+`GlobusComputeClient.submit_inference()` did this check; the domain-agnostic
+`HPCApp` path bypassed it entirely.
+
+### Fix: version mismatch
+
+`__init__.py.__version__` was stuck at `"0.2.0"` while `pyproject.toml` had
+already advanced to `0.3.2`.  Both are now `"0.3.3"`.
+
+### Fix: `globus_sdk.authorizers` mock missing in test_compute.py
+
+The `mock_globus_modules` fixture now also stubs `globus_sdk.authorizers`, which
+`compute.py` imports at module level via `AccessTokenAuthorizer`.
+
+### Notes
+
+- No breaking changes.  `app.py` still exposes a module-level `app` singleton
+  (built from env vars) and a `router` for embedding; both continue to work.
+- `make_app()` is now the recommended entry point for programmatic configuration.
+
 ## 0.3.2 (2026-06-04)
 
 ### New feature: programmatic auth configuration (`AuthConfig`)

{hpc_as_api-0.3.2 → hpc_as_api-0.3.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hpc-as-api
-Version: 0.3.2
-Summary: HTTP gateway for any HPC function via Globus Compute + WebSocket relay
+Version: 0.3.4
+Summary: Domain-agnostic HTTP gateway for any HPC function via Globus Compute + WebSocket relay
 Project-URL: Homepage, https://github.com/uicacer/hpc-as-api
 Project-URL: Repository, https://github.com/uicacer/hpc-as-api
 Project-URL: Bug Tracker, https://github.com/uicacer/hpc-as-api/issues
@@ -160,7 +160,7 @@ License:                                  Apache License
            See the License for the specific language governing permissions and
            limitations under the License.
 License-File: LICENSE
-Keywords: api-gateway,globus-compute,hpc,llm,openai,slurm,streaming,vllm
+Keywords: api-gateway,domain-agnostic,globus-compute,hpc,llm,scientific-computing,slurm,streaming,vllm
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: Apache Software License
@@ -193,58 +193,63 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/uicacer/hpc-as-api/blob/main/LICENSE)
 [![Tests](https://github.com/uicacer/hpc-as-api/actions/workflows/tests.yml/badge.svg)](https://github.com/uicacer/hpc-as-api/actions)
 
-**OpenAI-compatible API gateway for HPC clusters via Globus Compute.**
+**HTTP gateway for any HPC function — real-time streaming from any HPC workload.**
 
-`hpc-as-api` exposes any vLLM-served model running on an HPC cluster (SLURM, PBS, etc.) as a standard OpenAI-compatible REST API. It handles authentication, rate limiting, payload size management, and real-time token streaming — so your existing OpenAI clients work without modification.
+`hpc-as-api` turns any Python function running on an HPC cluster into a streaming HTTP endpoint. Register your function, define its input schema with Pydantic, and get a production-ready REST API with authentication, rate limiting, and live SSE streaming — no open ports, no VPN, no firewall changes on the HPC side.
 
 ```python
-from hpc_as_api.compute import GlobusComputeClient
-
-client = GlobusComputeClient(
-    endpoint_id="8d978809-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-    models={
-        "qwen25-vl-72b": {
-            "hf_name": "Qwen/Qwen2.5-VL-72B-Instruct-AWQ",
-            "url": "http://ghi2-002:8000",
-            "context_reserve_output": 4096,
-        }
-    },
-)
-result = await client.submit_inference(
-    messages=[{"role": "user", "content": "Explain quantum entanglement."}],
-    model="qwen25-vl-72b",
-)
+from hpc_as_api.core import HPCApp
+from pydantic import BaseModel
+
+class SimRequest(BaseModel):
+    steps: int = 1000
+    grid_size: int = 100
+
+def hpc_simulation(steps, grid_size, relay_url, channel_id, relay_secret=""):
+    from streamrelay import RelayProducer
+    with RelayProducer(relay_url, channel_id, relay_secret=relay_secret) as relay:
+        for i in range(steps):
+            result = run_timestep(i, grid_size)
+            relay.send_token(f"step={i} energy={result:.4f}\n")
+
+app = HPCApp(endpoint_id="...", relay_url="wss://relay.example.com") \
+    .mount("/simulate", hpc_simulation, SimRequest) \
+    .create_app()
 ```
 
+Any output produced incrementally on the HPC side arrives in real time: simulation checkpoints, solver residuals, genome alignment progress, molecular dynamics snapshots, LLM tokens — anything.
+
 ## Why
 
-HPC clusters run the largest open-source LLMs (72B+ parameters) on GPU hardware that typical cloud users can't afford. But HPC infrastructure has no standard API surface — each cluster has its own SLURM scripts, SSH tunnels, and authentication systems. `hpc-as-api` provides a uniform OpenAI-compatible interface over any vLLM-served model, using [Globus Compute](https://www.globus.org/compute) for authentication and job dispatch (no open ports required on the HPC side).
+HPC clusters run workloads impossible on commodity hardware — 72B+ parameter models, climate simulations, molecular dynamics at scale. But they expose no standard API. Each cluster has its own SLURM scripts, SSH tunnels, authentication systems, and job submission conventions.
+
+`hpc-as-api` provides a uniform HTTP interface over any HPC function using [Globus Compute](https://www.globus.org/compute) for authentication and job dispatch and [streamrelay](https://github.com/uicacer/streamrelay) for real-time output streaming. Callers send a POST request; the framework handles everything else.
 
 ## Architecture
 
 ![Relay architecture: the HPC compute node and gateway consumer both connect outbound to the WebSocket relay, traversing firewalls without VPN or inbound ports.](Relay_Architecture.png)
 
 ```
-Your App / OpenAI Client
-        │  POST /v1/chat/completions
+Your Application / HTTP Client
+        │  POST /your-endpoint  (any input schema)
         ▼
   hpc-as-api (FastAPI)
         │  Globus Compute (AMQP — no HPC firewall holes)
         ▼
-  HPC Cluster (SLURM)
-        │  vLLM HTTP API (internal LAN)
+  HPC Cluster (SLURM / PBS / …)
+        │  your function runs; output flows via streamrelay
         ▼
-  GPU Compute Node
-        │  tokens flow via WebSocket relay (streamrelay)
+  GPU / CPU Compute Node
+        │  tokens / results / checkpoints via WebSocket relay
         ▼
-  hpc-as-api → SSE stream → Your App
+  hpc-as-api → SSE stream → Your Application
 ```
 
 Key design points:
 - **No open ports on HPC**: Globus Compute is outbound-only from the cluster
-- **Real-time streaming**: Tokens stream back via [streamrelay](https://github.com/uicacer/streamrelay) WebSocket relay
-- **E2E encryption**: Optional AES-256-GCM encryption between HPC and consumer (relay sees only ciphertext)
-- **OpenAI-compatible**: Drop-in for any client using the OpenAI SDK
+- **Real-time streaming**: Any incremental output arrives as SSE via [streamrelay](https://github.com/uicacer/streamrelay)
+- **E2E encryption**: Optional AES-256-GCM encryption — relay sees only ciphertext
+- **Domain-agnostic**: Register any Python function; not limited to LLMs
 
 ## Installation
 
@@ -256,9 +261,69 @@ pip install hpc-as-api
 pip install "hpc-as-api[globus]"
 ```
 
-## Quickstart: Run as a service
+## Quickstart: Domain-agnostic gateway
 
-Set environment variables and start:
+Register any HPC function and stream its output:
+
+```python
+from hpc_as_api.core import HPCApp
+from pydantic import BaseModel
+
+class RunRequest(BaseModel):
+    steps: int = 1000
+    param: float = 0.5
+
+def my_hpc_function(steps, param, relay_url, channel_id, relay_secret=""):
+    from streamrelay import RelayProducer
+    with RelayProducer(relay_url, channel_id, relay_secret=relay_secret) as relay:
+        for i in range(steps):
+            relay.send_token(f"step={i} value={compute(i, param)}\n")
+
+gateway = HPCApp(
+    endpoint_id="your-globus-endpoint-uuid",
+    relay_url="wss://relay.example.com",
+    relay_secret="your-relay-secret",
+)
+gateway.mount("/run", my_hpc_function, RunRequest)
+app = gateway.create_app()
+```
+
+Run with:
+```bash
+uvicorn mymodule:app --host 0.0.0.0 --port 8001
+```
+
+Clients stream the output in real time:
+```bash
+curl -X POST http://localhost:8001/run \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"steps": 500, "param": 0.7}'
+```
+
+## Built-in preset: OpenAI-compatible LLM gateway
+
+For vLLM-served language models, the OpenAI preset provides a drop-in
+`/v1/chat/completions` endpoint compatible with any OpenAI client:
+
+```python
+from hpc_as_api.presets.openai import create_openai_app
+
+app = create_openai_app(
+    endpoint_id="8d978809-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    models={
+        "qwen25-vl-72b": {
+            "hf_name": "Qwen/Qwen2.5-VL-72B-Instruct-AWQ",
+            "url": "http://ghi2-002:8000",
+            "context_reserve_output": 4096,
+        }
+    },
+    relay_url="wss://relay.example.com",
+    relay_secret="your-relay-secret",
+)
+```
+
+Or run as a service from environment variables:
 
 ```bash
 export GLOBUS_COMPUTE_ENDPOINT_ID="your-endpoint-uuid"
@@ -269,7 +334,24 @@ export RELAY_SECRET="your-relay-secret"
 uvicorn hpc_as_api.app:app --host 0.0.0.0 --port 8001
 ```
 
-The gateway is now reachable at `http://localhost:8001/v1/chat/completions` with the standard OpenAI API schema.
+Any OpenAI client works without modification:
+```python
+import openai
+client = openai.OpenAI(base_url="http://localhost:8001/v1", api_key="sk-xxxx")
+response = client.chat.completions.create(model="qwen25-vl-72b", messages=[...], stream=True)
+```
+
+## Multiple independent gateways
+
+`make_app()` returns a fresh, independent instance each time — safe to use
+multiple gateways with different configurations in the same process:
+
+```python
+from hpc_as_api.app import make_app
+
+sim_app = make_app(endpoint_id="endpoint-a", relay_url="wss://relay.example.com", models={...})
+llm_app = make_app(endpoint_id="endpoint-b", relay_url="wss://relay.example.com", models={...})
+```
 
 ## Embed in an existing FastAPI app
 
@@ -281,21 +363,47 @@ app = FastAPI()
 app.include_router(router, prefix="/hpc")
 ```
 
+## Programmatic auth configuration
+
+```python
+from hpc_as_api import AuthConfig
+from hpc_as_api.core import HPCApp
+
+gateway = HPCApp(
+    endpoint_id="...",
+    relay_url="wss://relay.example.com",
+    auth=AuthConfig(
+        globus_client_id="your-client-id",
+        globus_client_secret="your-client-secret",
+        allowed_domains=["university.edu"],
+        api_keys={"my-service": "sk-xxxx"},
+        rate_limit_requests=20,
+        rate_limit_window=60,
+    ),
+)
+```
+
 ## Configuration reference
 
+### HPCApp / make_app()
+
+| Argument | Env var fallback | Description |
+|---|---|---|
+| `endpoint_id` | `GLOBUS_COMPUTE_ENDPOINT_ID` | Globus endpoint UUID for the HPC cluster |
+| `relay_url` | `RELAY_URL` | WebSocket relay URL for streaming |
+| `relay_secret` | `RELAY_SECRET` | Shared secret for relay auth |
+| `relay_encryption_key` | `RELAY_ENCRYPTION_KEY` | AES-256 hex key for E2E encryption |
+| `auth` | — | `AuthConfig` or `Authenticator` instance |
+
+### OpenAI preset additional settings
+
 | Variable | Default | Description |
 |---|---|---|
-| `GLOBUS_COMPUTE_ENDPOINT_ID` | — | Globus endpoint UUID for the HPC cluster |
 | `HPC_MODELS` | `{}` | JSON dict: model name → HPC config |
-| `RELAY_URL` | — | WebSocket relay URL for token streaming |
-| `RELAY_SECRET` | — | Shared secret for relay auth |
-| `RELAY_ENCRYPTION_KEY` | — | AES-256 hex key for E2E encryption |
-| `USE_GLOBUS_COMPUTE` | `true` | `false` to route directly via SSH tunnel |
-| `LAKESHORE_VLLM_ENDPOINT` | `http://localhost:8000` | Direct vLLM URL (SSH mode) |
-| `HPC_PROXY_HOST` | `0.0.0.0` | Bind host |
-| `HPC_PROXY_PORT` | `8001` | Bind port |
+| `USE_GLOBUS_COMPUTE` | `true` | `false` to route directly via vLLM URL |
+| `LAKESHORE_VLLM_ENDPOINT` | `http://localhost:8000` | Direct vLLM URL (non-Globus mode) |
 
-### HPC_MODELS schema
+### HPC_MODELS schema (LLM preset)
 
 ```json
 {
@@ -309,10 +417,12 @@ app.include_router(router, prefix="/hpc")
 
 ## Authentication
 
-The gateway supports two auth modes (configured in `hpc_as_api/auth.py`):
+Two auth modes, configurable via `AuthConfig` or environment variables:
+
+- **Globus token**: Bearer token from Globus Auth, validated via introspection; email domain filtering supported
+- **API key**: Static key from `HPC_API_KEYS` env var (comma-separated `name:key` pairs)
 
-- **Globus token**: Bearer token from Globus Auth, validated via introspection
-- **API key**: Static key from `HPC_API_KEYS` env var (comma-separated)
+Both modes coexist on the same endpoint.
 
 ## Development
 
@@ -325,7 +435,7 @@ uv run pytest
 
 ## Related
 
-- [streamrelay](https://github.com/uicacer/streamrelay) — WebSocket relay for real-time token streaming from Globus Compute
+- [streamrelay](https://github.com/uicacer/streamrelay) — WebSocket relay for real-time output streaming from Globus Compute
 - [STREAM](https://github.com/uicacer/stream) — Full tiered LLM routing system that uses hpc-as-api
 
 ## License
@@ -339,7 +449,7 @@ If you use hpc-as-api in research, please cite:
 ```bibtex
 @software{nassar2025hpcgateway,
   author = {Nassar, Anas},
-  title  = {hpc-as-api: OpenAI-compatible API gateway for HPC clusters via Globus Compute},
+  title  = {hpc-as-api: HTTP gateway for any HPC function via Globus Compute and WebSocket relay},
   year   = {2025},
   url    = {https://github.com/uicacer/hpc-as-api}
 }

hpc_as_api-0.3.4/README.md

@@ -0,0 +1,267 @@
+# hpc-as-api
+
+[![PyPI](https://img.shields.io/pypi/v/hpc-as-api)](https://pypi.org/project/hpc-as-api/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/uicacer/hpc-as-api/blob/main/LICENSE)
+[![Tests](https://github.com/uicacer/hpc-as-api/actions/workflows/tests.yml/badge.svg)](https://github.com/uicacer/hpc-as-api/actions)
+
+**HTTP gateway for any HPC function — real-time streaming from any HPC workload.**
+
+`hpc-as-api` turns any Python function running on an HPC cluster into a streaming HTTP endpoint. Register your function, define its input schema with Pydantic, and get a production-ready REST API with authentication, rate limiting, and live SSE streaming — no open ports, no VPN, no firewall changes on the HPC side.
+
+```python
+from hpc_as_api.core import HPCApp
+from pydantic import BaseModel
+
+class SimRequest(BaseModel):
+    steps: int = 1000
+    grid_size: int = 100
+
+def hpc_simulation(steps, grid_size, relay_url, channel_id, relay_secret=""):
+    from streamrelay import RelayProducer
+    with RelayProducer(relay_url, channel_id, relay_secret=relay_secret) as relay:
+        for i in range(steps):
+            result = run_timestep(i, grid_size)
+            relay.send_token(f"step={i} energy={result:.4f}\n")
+
+app = HPCApp(endpoint_id="...", relay_url="wss://relay.example.com") \
+    .mount("/simulate", hpc_simulation, SimRequest) \
+    .create_app()
+```
+
+Any output produced incrementally on the HPC side arrives in real time: simulation checkpoints, solver residuals, genome alignment progress, molecular dynamics snapshots, LLM tokens — anything.
+
+## Why
+
+HPC clusters run workloads impossible on commodity hardware — 72B+ parameter models, climate simulations, molecular dynamics at scale. But they expose no standard API. Each cluster has its own SLURM scripts, SSH tunnels, authentication systems, and job submission conventions.
+
+`hpc-as-api` provides a uniform HTTP interface over any HPC function using [Globus Compute](https://www.globus.org/compute) for authentication and job dispatch and [streamrelay](https://github.com/uicacer/streamrelay) for real-time output streaming. Callers send a POST request; the framework handles everything else.
+
+## Architecture
+
+![Relay architecture: the HPC compute node and gateway consumer both connect outbound to the WebSocket relay, traversing firewalls without VPN or inbound ports.](Relay_Architecture.png)
+
+```
+Your Application / HTTP Client
+        │  POST /your-endpoint  (any input schema)
+        ▼
+  hpc-as-api (FastAPI)
+        │  Globus Compute (AMQP — no HPC firewall holes)
+        ▼
+  HPC Cluster (SLURM / PBS / …)
+        │  your function runs; output flows via streamrelay
+        ▼
+  GPU / CPU Compute Node
+        │  tokens / results / checkpoints via WebSocket relay
+        ▼
+  hpc-as-api → SSE stream → Your Application
+```
+
+Key design points:
+- **No open ports on HPC**: Globus Compute is outbound-only from the cluster
+- **Real-time streaming**: Any incremental output arrives as SSE via [streamrelay](https://github.com/uicacer/streamrelay)
+- **E2E encryption**: Optional AES-256-GCM encryption — relay sees only ciphertext
+- **Domain-agnostic**: Register any Python function; not limited to LLMs
+
+## Installation
+
+```bash
+# Base package (no Globus SDK)
+pip install hpc-as-api
+
+# With Globus Compute support
+pip install "hpc-as-api[globus]"
+```
+
+## Quickstart: Domain-agnostic gateway
+
+Register any HPC function and stream its output:
+
+```python
+from hpc_as_api.core import HPCApp
+from pydantic import BaseModel
+
+class RunRequest(BaseModel):
+    steps: int = 1000
+    param: float = 0.5
+
+def my_hpc_function(steps, param, relay_url, channel_id, relay_secret=""):
+    from streamrelay import RelayProducer
+    with RelayProducer(relay_url, channel_id, relay_secret=relay_secret) as relay:
+        for i in range(steps):
+            relay.send_token(f"step={i} value={compute(i, param)}\n")
+
+gateway = HPCApp(
+    endpoint_id="your-globus-endpoint-uuid",
+    relay_url="wss://relay.example.com",
+    relay_secret="your-relay-secret",
+)
+gateway.mount("/run", my_hpc_function, RunRequest)
+app = gateway.create_app()
+```
+
+Run with:
+```bash
+uvicorn mymodule:app --host 0.0.0.0 --port 8001
+```
+
+Clients stream the output in real time:
+```bash
+curl -X POST http://localhost:8001/run \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"steps": 500, "param": 0.7}'
+```
+
+## Built-in preset: OpenAI-compatible LLM gateway
+
+For vLLM-served language models, the OpenAI preset provides a drop-in
+`/v1/chat/completions` endpoint compatible with any OpenAI client:
+
+```python
+from hpc_as_api.presets.openai import create_openai_app
+
+app = create_openai_app(
+    endpoint_id="8d978809-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    models={
+        "qwen25-vl-72b": {
+            "hf_name": "Qwen/Qwen2.5-VL-72B-Instruct-AWQ",
+            "url": "http://ghi2-002:8000",
+            "context_reserve_output": 4096,
+        }
+    },
+    relay_url="wss://relay.example.com",
+    relay_secret="your-relay-secret",
+)
+```
+
+Or run as a service from environment variables:
+
+```bash
+export GLOBUS_COMPUTE_ENDPOINT_ID="your-endpoint-uuid"
+export HPC_MODELS='{"qwen25-vl-72b": {"hf_name": "Qwen/Qwen2.5-VL-72B-Instruct-AWQ", "url": "http://ghi2-002:8000", "context_reserve_output": 4096}}'
+export RELAY_URL="wss://relay.example.com"
+export RELAY_SECRET="your-relay-secret"
+
+uvicorn hpc_as_api.app:app --host 0.0.0.0 --port 8001
+```
+
+Any OpenAI client works without modification:
+```python
+import openai
+client = openai.OpenAI(base_url="http://localhost:8001/v1", api_key="sk-xxxx")
+response = client.chat.completions.create(model="qwen25-vl-72b", messages=[...], stream=True)
+```
+
+## Multiple independent gateways
+
+`make_app()` returns a fresh, independent instance each time — safe to use
+multiple gateways with different configurations in the same process:
+
+```python
+from hpc_as_api.app import make_app
+
+sim_app = make_app(endpoint_id="endpoint-a", relay_url="wss://relay.example.com", models={...})
+llm_app = make_app(endpoint_id="endpoint-b", relay_url="wss://relay.example.com", models={...})
+```
+
+## Embed in an existing FastAPI app
+
+```python
+from fastapi import FastAPI
+from hpc_as_api.app import router
+
+app = FastAPI()
+app.include_router(router, prefix="/hpc")
+```
+
+## Programmatic auth configuration
+
+```python
+from hpc_as_api import AuthConfig
+from hpc_as_api.core import HPCApp
+
+gateway = HPCApp(
+    endpoint_id="...",
+    relay_url="wss://relay.example.com",
+    auth=AuthConfig(
+        globus_client_id="your-client-id",
+        globus_client_secret="your-client-secret",
+        allowed_domains=["university.edu"],
+        api_keys={"my-service": "sk-xxxx"},
+        rate_limit_requests=20,
+        rate_limit_window=60,
+    ),
+)
+```
+
+## Configuration reference
+
+### HPCApp / make_app()
+
+| Argument | Env var fallback | Description |
+|---|---|---|
+| `endpoint_id` | `GLOBUS_COMPUTE_ENDPOINT_ID` | Globus endpoint UUID for the HPC cluster |
+| `relay_url` | `RELAY_URL` | WebSocket relay URL for streaming |
+| `relay_secret` | `RELAY_SECRET` | Shared secret for relay auth |
+| `relay_encryption_key` | `RELAY_ENCRYPTION_KEY` | AES-256 hex key for E2E encryption |
+| `auth` | — | `AuthConfig` or `Authenticator` instance |
+
+### OpenAI preset additional settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `HPC_MODELS` | `{}` | JSON dict: model name → HPC config |
+| `USE_GLOBUS_COMPUTE` | `true` | `false` to route directly via vLLM URL |
+| `LAKESHORE_VLLM_ENDPOINT` | `http://localhost:8000` | Direct vLLM URL (non-Globus mode) |
+
+### HPC_MODELS schema (LLM preset)
+
+```json
+{
+  "my-model-name": {
+    "hf_name": "org/ModelName",
+    "url": "http://compute-node:8000",
+    "context_reserve_output": 4096
+  }
+}
+```
+
+## Authentication
+
+Two auth modes, configurable via `AuthConfig` or environment variables:
+
+- **Globus token**: Bearer token from Globus Auth, validated via introspection; email domain filtering supported
+- **API key**: Static key from `HPC_API_KEYS` env var (comma-separated `name:key` pairs)
+
+Both modes coexist on the same endpoint.
+
+## Development
+
+```bash
+git clone https://github.com/uicacer/hpc-as-api
+cd hpc-as-api
+uv sync --extra dev
+uv run pytest
+```
+
+## Related
+
+- [streamrelay](https://github.com/uicacer/streamrelay) — WebSocket relay for real-time output streaming from Globus Compute
+- [STREAM](https://github.com/uicacer/stream) — Full tiered LLM routing system that uses hpc-as-api
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+## Citation
+
+If you use hpc-as-api in research, please cite:
+
+```bibtex
+@software{nassar2025hpcgateway,
+  author = {Nassar, Anas},
+  title  = {hpc-as-api: HTTP gateway for any HPC function via Globus Compute and WebSocket relay},
+  year   = {2025},
+  url    = {https://github.com/uicacer/hpc-as-api}
+}
+```