# SAAYN OpenAI Wrapper

This local wrapper exposes Spreadsheets-are-all-you-need through OpenAI-style interfaces while keeping the runtime editable and headless.

The serving engine is `spreadsheet-gpt2-numpy`: a faithful NumPy port of the spreadsheet/browser GPT-2 computation graph using the project's own CSV parameter release. The downloaded `.xlsb` workbook is retained as the canonical Excel artifact, but serving does not require a visible spreadsheet window.

## Install

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -U pip setuptools wheel
.venv/bin/python -m pip install -e .
```

## Chat

```bash
.venv/bin/python saayn_chat.py --max-tokens 24
```

Chat memory is persisted in SQLite at `~/.local/share/saayn-openai/chat_sessions.sqlite3`.

The CLI uses a short hard-coded dialogue memory by default so GPT-2 sees prior `User:` and `Assistant:` turns before the live session. It also stops before generating the next `User:` line. Use raw completion mode when you want canonical next-token behavior:

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

Use normal completion mode when you want the current input completed as plain text without dialogue memories, role labels, an injected `Assistant:`, or dialogue stop markers:

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

Inside the chat UI, use `/completion on`, `/completion off`, or `/mode completion`.

By default the CLI streams each generated token as it is selected and prints a compact math trace:

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

Use `--quiet-visualization` to keep streaming output but hide the trace.

## API Server

```bash
.venv/bin/saayn-openai-server --host 127.0.0.1 --port 8787
```

Implemented endpoints:

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

## Artifacts

The release workbook and parameter bundle are large, so they are installed on demand:

```bash
.venv/bin/saayn-artifacts --kind workbook
.venv/bin/saayn-artifacts --kind parameters
.venv/bin/saayn-artifacts --kind all
```

Compile the parameter bundle into the reusable NumPy cache:

```bash
.venv/bin/saayn-compile --predict "Mike is quick. He moves"
```

Expected smoke-test output:

```text
 quickly
```

## Engines

The wrapper chooses engines in this order:

1. `SAAYN_BRIDGE_CMD`: process bridge for a workbook/spreadsheet evaluator.
2. Local `spreadsheet-gpt2-numpy` engine when `gpt2-small-csv.zip` is installed.
3. `SAAYN_UPSTREAM_BASE_URL` plus `SAAYN_UPSTREAM_API_KEY`, or `OPENAI_API_KEY`: OpenAI-compatible upstream.
4. Deterministic local status engine.

The spreadsheet model is GPT-2 Small next-token prediction, not an instruction-tuned chat model. The CLI and API repeat next-token prediction autoregressively to create assistant text; the CLI adds dialogue scaffolding by default to bias output toward assistant replies.

Bridge commands receive JSON on stdin:

```json
{"model":"saayn-gpt2-spreadsheet","messages":[{"role":"user","content":"Hello"}],"temperature":0.7,"max_tokens":null}
```

They may return either raw text or JSON:

```json
{"text":"assistant reply"}
```
