From e1ea329a7539d68c6ad361b6eec298ccd02eabc7 Mon Sep 17 00:00:00 2001 From: Benjamin Hackl Date: Tue, 3 Nov 2026 20:53:13 +0100 Subject: [PATCH] README: concise install and setup guide --- README.md | 155 ++++++++++++++++++++++++------------------------------ 1 file changed, 69 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 7ee53cf..7e8c123 100644 --- a/README.md +++ b/README.md @@ -1,125 +1,109 @@ # pi-unigpt -Use [UniGPT](https://unigpt.uni-graz.at), the University of Graz's MyGPT +Use [uniGPT](https://unigpt.uni-graz.at), the University of Graz's AI platform, as a model provider in [pi](https://pi.dev). -- Log in with **`/login unigpt`**; your key is checked before pi saves it. -- Models are discovered automatically. No model list to maintain. -- Context size, output limit, and image support come from pi's own model - catalog, so they stay current as pi updates. -- Tool calling, streaming, and image input work through pi's built-in - OpenAI Responses support. +Models are discovered automatically, and their limits come from pi's model +catalog, so there is no model list to maintain. Tool calling, streaming, and +image input work. -Requires pi **1.5.x** and Node.js **22.19+**. +## Requirements -## Install +- pi **1.5.x** and Node.js **22.19+** +- A uniGPT **API key**. If you don't have one, ask the uniGPT team at the + [IDea_Lab](https://idea-lab.uni-graz.at/en/digital-innovation-lab/unigpt-and-studigpt). + +## Setup + +**1. Install the extension** ```sh pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt ``` -This follows the latest version; `pi update --extensions` pulls updates. To -stay on one release instead, pin its tag: -`pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt@v0.1.0`. +To stay on a fixed release instead of following the latest version, add the +tag: `…/pi-unigpt@v0.1.0`. -Then start pi (or run `/reload` in a running session) and log in: +**2. Log in** + +Start pi (or run `/reload` if it is already running) and enter: ```text /login unigpt ``` -Paste your UniGPT API key into the masked dialog, **not into the chat**. Pi -confirms how many models your key can use. Pick one with `/model`; UniGPT -models are listed under `unigpt`. +Paste your API key into the masked dialog, **not into the chat**. Pi checks +the key and reports how many models it can use. -To try the extension without installing it: +**3. Pick a model** -```sh -pi -e git:imsc.uni-graz.at/git/behackl/pi-unigpt +Run `/model` and choose one of the models listed under `unigpt`. + +**4. Optional: make uniGPT your default** + +Add this to `~/.pi/agent/settings.json` to start pi with a uniGPT model: + +```json +{ + "defaultProvider": "unigpt", + "defaultModel": "gpt-5.4" +} ``` +**Already configured uniGPT by hand?** Remove the `unigpt` entry under +`providers` in `~/.pi/agent/models.json` first. Otherwise your old settings +take precedence over the extension. + ## Commands -| Command | What it does | +| Command | Purpose | | --- | --- | | `/login unigpt` | Save and verify your API key | -| `/logout` | Remove the saved key from pi (it stays valid at UniGPT) | -| `/model` | Pick a model; also reloads the model list | -| `/unigpt-refresh` | Reload the UniGPT model list now and show how many models you have | +| `/model` | Pick a model (also reloads the model list) | +| `/unigpt-refresh` | Reload the model list and report any problem | +| `/logout` | Remove the saved key from pi (it stays valid at uniGPT) | -## How models are described +## Keeping your key out of auth.json -UniGPT's API only lists deployment IDs such as `gpt-5.4`. Those IDs are -OpenAI model names, so the extension looks each one up in pi's bundled model -catalog and uses its name, context window, output limit, and image support. -Where OpenAI and Azure list different limits, the smaller one is used. - -IDs that pi does not know get pi's standard defaults for custom models: -128k context, 16k output, text only. Update pi to pick up newer models. - -Two things are deliberately not taken from the catalog: - -- **Thinking levels are off for every model.** UniGPT ignores the requested - reasoning effort and uses a fixed one per deployment, so pi's thinking - levels would have no effect. Reasoning models still reason. -- **Costs are shown as zero.** That means "not tracked", not "free". - -You can override any value in `~/.pi/agent/models.json`: +Pi saves the key unencrypted in `~/.pi/agent/auth.json`, readable only by +your user account. To avoid that, edit the `unigpt` entry there to read the +key from an environment variable or a password manager: ```json -{ - "providers": { - "unigpt": { - "modelOverrides": { - "gpt-5.4": { "contextWindow": 200000 } - } - } - } -} -``` - -## Your API key - -Pi stores the key under `unigpt` in `~/.pi/agent/auth.json`. That file is -private to your user account but **not encrypted**. To keep the key out of -it, replace the stored value with an environment variable or a password -manager command; pi resolves either when it needs the key: - -```json -{ - "unigpt": { "type": "api_key", "key": "${UNIGPT_API_KEY}" } -} +{ "unigpt": { "type": "api_key", "key": "${UNIGPT_API_KEY}" } } ``` ```json -{ - "unigpt": { "type": "api_key", "key": "!op read op://Private/UniGPT/credential" } -} +{ "unigpt": { "type": "api_key", "key": "!op read op://Private/uniGPT/credential" } } ``` -## Upgrading from a models.json setup +## Good to know -If you configured UniGPT by hand before, delete the `unigpt` entry under -`providers` in `~/.pi/agent/models.json` (overrides as shown above are -fine). Otherwise your old model list and key take precedence over the -extension. Then run `/reload` and `/login unigpt`. +- **Thinking levels are off.** uniGPT applies a fixed reasoning effort per + model and ignores pi's setting. Reasoning models still reason. +- **Costs show as zero.** That means "not tracked", not "free". +- **Model limits** come from pi's catalog. Models pi doesn't know get 128k + context and 16k output; update pi to pick up newer ones. To override a + value, use `modelOverrides` in `~/.pi/agent/models.json`: + + ```json + { "providers": { "unigpt": { "modelOverrides": { "gpt-5.4": { "contextWindow": 200000 } } } } } + ``` ## Troubleshooting -- **No UniGPT models in `/model`:** run `/unigpt-refresh`; it reports the - exact problem (rejected key, unreachable server, empty model list). -- **`pi -p` says a UniGPT model was not found:** print mode only reads the - saved model list and never fetches it. Start pi interactively once after - logging in; later print runs reuse that list. -- **A specific model fails with HTTP 500:** some deployments are - misconfigured on the server side; try another model and tell the UniGPT - team. +- **No uniGPT models in `/model`:** run `/unigpt-refresh`; it names the + problem (rejected key, unreachable server, empty model list). +- **`pi -p` can't find a uniGPT model:** print mode doesn't fetch model + lists. Start pi interactively once after logging in. +- **One model fails with HTTP 500:** that deployment is broken on the + server; pick another model and tell the uniGPT team. +- **Install fails with `spawn npm ENOENT`:** you use pnpm instead of npm. + Add `"npmCommand": ["pnpm"]` to `~/.pi/agent/settings.json`. -## Feedback - -Please report problems and ideas at -. Include the output -of `/unigpt-refresh` and the model you used, but never your API key. +Report bugs at . +Include the `/unigpt-refresh` output and the model you used, never your +API key. ## Development @@ -128,9 +112,8 @@ pnpm install pnpm run ci # type check + tests ``` -Tests use fake keys and a local HTTP server; they never contact UniGPT or -read your pi configuration. +Tests use fake keys and a local server; they never contact uniGPT. ## License -MIT +[MIT](LICENSE)