Setup
=====

Requirements
------------

You need two things before making any requests:

- A connection to the **UB campus network** or the **UB VPN**
- An **API key** (see below)

Getting an API key
------------------

Email `Chris Proctor <mailto:chrisp@buffalo.edu>`_ with a brief description
of your project. Once issued, your key is a long alphanumeric string. Treat it
like a password:

- Store it in a password manager or your OS keychain
- Never hard-code it in a script or commit it to a repository

If a key is lost it cannot be recovered — request a new one.

Setting the environment variable
---------------------------------

The most convenient way to supply your key is the ``GSEAI_API_TOKEN`` environment
variable. Add it to your shell profile (``~/.zshrc``, ``~/.bashrc``, etc.):

.. code-block:: bash

   export GSEAI_API_TOKEN=your-api-key

The ``gseai`` CLI and the ``GSEAIServer`` class both read this variable
automatically, so you won't need to pass the key on every call.

HTTPS (recommended for sensitive data)
---------------------------------------

The server is accessible over plain HTTP or HTTPS on port 11434. If your work
involves sensitive or confidential data, use HTTPS:

.. code-block:: text

   https://gseai.gse.buffalo.edu:11434

**Step 1 — Download the CA certificate:**

.. code-block:: bash

   curl -O http://gseai.gse.buffalo.edu:11434/gseai.pem

**Step 2 — Install it system-wide:**

*macOS:*

.. code-block:: bash

   sudo security add-trusted-cert -d -r trustRoot \
       -k /Library/Keychains/System.keychain gseai.pem

*Linux (Debian/Ubuntu):*

.. code-block:: bash

   sudo cp gseai.pem /usr/local/share/ca-certificates/gseai.crt
   sudo update-ca-certificates

*Windows:* Double-click ``gseai.pem``, choose *Install Certificate*, select
*Local Machine*, and place it in the *Trusted Root Certification Authorities*
store.

**Alternative — Python only (no system install):**

If you prefer not to touch system certificates, point the standard
``REQUESTS_CA_BUNDLE`` variable at the file; both ``httpx`` and ``requests``
honour it:

.. code-block:: bash

   export REQUESTS_CA_BUNDLE=/path/to/gseai.pem

Then pass ``https://gseai.gse.buffalo.edu:11434`` as the host when constructing
``GSEAIServer``:

.. code-block:: python

   server = GSEAIServer("your-token", host="https://gseai.gse.buffalo.edu")

OpenAI SDK compatibility
------------------------

The server implements the OpenAI API, so any code written for OpenAI works
with GSEAI by changing the base URL and API key:

.. code-block:: python

   from openai import OpenAI

   client = OpenAI(
       api_key="your-gseai-token",
       base_url="http://gseai.gse.buffalo.edu:11434/v1",
   )

The ``gseai`` package wraps this API directly and does not require the OpenAI
SDK.

Infrastructure and performance
-------------------------------

The server runs on **CPU-only** hardware with 700 GB of RAM in the
Computational Literacies Lab (Foster Hall). This makes it well suited to
research and batch processing but not to latency-sensitive applications.

Rough performance expectations:

- **Chat / text generation** — seconds to a minute depending on model and
  response length; use ``--stream`` / ``stream=True`` for incremental output
- **Speech transcription** — roughly real-time for short clips
- **Image generation** — 1–5 minutes per image depending on size and prompt
  complexity

All processing happens within the UB network. No request data is transmitted
to external services or cloud providers, and the server does not maintain
persistent logs of request content.

IRB considerations
------------------

If your project involves human-subjects research, the following points are
relevant for IRB applications:

- The server is operated on hardware under direct research-team control in
  Foster Hall
- All traffic between your workstation and the server is encrypted with
  TLS 1.2 or 1.3
- Access is controlled by individual API keys, revocable at any time
- No participant data is transmitted to external services, cloud providers,
  or third-party AI platforms
- The server does not retain persistent logs of request content

Researchers are responsible for documenting how they store and manage the
*outputs* produced by the server. For technical clarification regarding IRB
language, contact `Chris Proctor <mailto:chrisp@buffalo.edu>`_.