Metadata-Version: 2.4
Name: gseai
Version: 1.3.0
Summary: Python client for the GSE AI LocalAI server
Project-URL: Homepage, https://computationalliteracies.net/handbook/tools/ai-server/
Project-URL: Documentation, https://docs.makingwithcode.org/gseai
Requires-Python: >=3.14
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.28.1
Description-Content-Type: text/markdown

# GSE AI Server API

This package provides an API for connecting to UB GSE's AI server (powered by LocalAI).
See [the Computational Literacies Lab handbook page](https://computationalliteracies.net/handbook/tools/ai-server/)
for details about the server. 

The [documentation](https://docs.makingwithcode.org/gseai) provides details on 
using the API. 

## Quickstart

```python3
from gseai import GSEAIServer

with GSEAIServer("your-api-token") as server:
    # List available models
    models = server.list_models()

    # Simple single-turn chat
    response = server.chat("model-id", "What is machine learning?")

    # Multi-turn chat using the OpenAI-compatible API
    response = server.chat_completions(
        "model-id",
        messages=[{"role": "user", "content": "What is machine learning?"}],
    )
```

## Job queue

Large models can take longer than the server's HTTP timeout to respond. The job queue
lets you submit a request and collect the result later — no need to keep a connection open.

```python3
from gseai import GSEAIServer

with GSEAIServer("your-api-token") as server:
    # Submit a job and get an ID immediately
    job = server.submit_job("my-job", "qwen2.5-coder", "Explain transformers.")
    job_id = job["job_id"]

    # Come back later and wait for it
    result = server.wait_for_job(job_id)
    print(result["result"])

    # File-in jobs (transcribe, image_edit, etc.)
    job = server.submit_file_job("transcribe-lecture", "transcribe", "whisper-1", "lecture.mp3")

    # Binary-out jobs (speech, images) — fetch the file when done
    audio = server.get_job_result(job_id)
    open("output.mp3", "wb").write(audio)
```

The CLI supports the same workflow:

```bash
# Submit and walk away
gseai queue submit qwen2.5-coder "Explain transformers." -n my-job
# a3f1c7d2-...

# Check status, then fetch result when done
gseai queue status a3f1c7d2-...
gseai queue wait a3f1c7d2-...

# Or submit and wait in one step
gseai queue run qwen2.5-coder "Explain transformers." -n my-job

# File-in jobs
gseai queue upload whisper-1 lecture.mp3 --job-type transcribe -n lecture
gseai queue wait <job-id>
```
