# SAAYN OpenAI Bundle

This bundle may be packaged in four variants:

- Ultra-light source: source, docs, and install/run scripts only. No workbook, CSV parameters, virtualenv, or model cache.
- Full: includes the original Excel workbook and the CSV parameter bundle.
- Lite: omits the original 1.34 GB Excel workbook, but keeps the CSV parameter bundle required by the fast headless runtime.
- Runtime Linux: includes the full artifacts plus a ready `.venv`, installed dependencies, compiled Python bytecode, and precompiled NumPy model cache under `runtime_data/`.

The full bundle contains:

- The Spreadsheets-are-all-you-need source files and examples.
- The OpenAI-compatible Python wrapper and CLI chat interface.
- The original Excel workbook artifact: `artifacts/GPT2-spreadsheets-are-all-you-need.v0.7.0.xlsb` if using the full bundle.
- The GPT-2 CSV parameter bundle used by the optimized headless runtime: `artifacts/gpt2-small-csv.zip`.
- Install and run scripts under `bundle_scripts/`.

The runtime does not open a spreadsheet window. It uses a faithful NumPy implementation of the published spreadsheet/browser GPT-2 math graph and the project CSV parameters. The `.xlsb` workbook is useful as the original reference artifact, but it is not required to run the optimized chat/API backend.

The ultra-light source bundle downloads everything required for normal operation during install:

```bash
bash bundle_scripts/install.sh
```

That command installs dependencies, downloads the GPT-2 CSV parameter bundle, and compiles the local NumPy cache. Add `--with-workbook` if you also want the original 1.34 GB spreadsheet workbook:

```bash
bash bundle_scripts/install.sh --with-workbook
```

The lite bundle deliberately omits the 1.34 GB `.xlsb` workbook. To download it later from the official GitHub release, run:

```bash
bash bundle_scripts/install.sh --with-workbook
```

The runtime Linux bundle is intended for this machine or a similar Linux/Python 3.10 x86_64 environment. From the unzipped bundle root, it can usually run immediately:

```bash
bash bundle_scripts/run_chat.sh
```

It is not universal across operating systems or Python ABIs because NumPy is native code. If the bundled virtualenv does not match the target machine, rebuild it in place:

```bash
bash bundle_scripts/install.sh
```

An experimental stdlib-only pure backend is present for inspection, but it is not the default shipped runtime because full-context generation is too slow for chat. Force it only for diagnostics:

```bash
SAAYN_ENGINE=pure SAAYN_PURE_MAX_CONTEXT=1 bash bundle_scripts/run_chat.sh --max-tokens 1
```

## Quick Start

From the unzipped bundle root:

```bash
bash bundle_scripts/install.sh
bash bundle_scripts/run_chat.sh
```

The first real model call may take a moment while the Python package loads GPT-2 arrays. If the NumPy cache is missing, the installer compiles it from `artifacts/gpt2-small-csv.zip`. If the CSV parameter zip is missing, the normal installer downloads it from the official release before compiling. In `--offline` mode, missing artifacts or dependencies are treated as errors.

## API Server

```bash
bash bundle_scripts/run_server.sh
```

The server listens at `http://127.0.0.1:8787/v1` and implements:

- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /v1/responses`

## Chat Behavior

The chat script streams tokens automatically and prints a compact math trace for each generated token:

```text
[math token #0: id=18435 repr=' Hello' logit=-87.764 ctx=115 elapsed=2821ms]
```

Use this to hide the trace while keeping token streaming:

```bash
.venv/bin/python saayn_chat.py --quiet-visualization
```

Use raw GPT-2 completion mode:

```bash
.venv/bin/python saayn_chat.py --raw-completion
```

Use normal plain completion mode, with no dialogue primer, no session-history prompt, no role labels, no injected `Assistant:`, and no dialogue stop markers:

```bash
.venv/bin/python saayn_chat.py --normal-completion
```

Inside chat, switch modes with:

```text
/completion on
/completion off
/mode completion
/mode dialogue
/mode raw
```

## Files

- `saayn_chat.py`: Python 3 chat script.
- `saayn_chat_py2.py`: nostalgic Python 2 syntax-converted aside. It is not a full runtime because the backend package is Python 3-only.
- `src/saayn_openai/spreadsheet_gpt2.py`: optimized spreadsheet GPT-2 forward pass.
- `src/saayn_openai/spreadsheet_gpt2_pure.py`: experimental stdlib-only evaluator; slow diagnostic fallback.
- `SAAYN_OPENAI_WRAPPER.md`: deeper notes on the local wrapper.
- `NamedFunctions.md`: original spreadsheet named-function notes.

## Requirements

- Python 3.10 or newer recommended.
- `pip` and `venv` for source installs; the runtime Linux bundle includes a ready `.venv`.
- Enough disk for artifacts plus the compiled NumPy cache. Expect roughly 2.5 GB after install.

Python dependencies are installed by `bundle_scripts/install.sh` using the local `pyproject.toml`. If `wheelhouse/` exists, installation uses those local wheels with `--no-index` instead of contacting PyPI.
