behackl/pi-unigpt
Watch
1
0
Fork
You've already forked pi-unigpt
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README: concise install and setup guide
Some checks failed
CI / test (22) (push) Failing after 31s
Details
CI / test (24) (push) Failing after 32s
Details

Browse source
This commit is contained in:
Benjamin Hackl 2026-11-03 20:53:13 +01:00
commit e1ea329a75
1 changed files with 68 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

155
README.md
View file

@ -1,125 +1,109 @@
# pi-unigpt # 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). 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, and their limits come from pi's model
- Models are discovered automatically. No model list to maintain. catalog, so there is no model list to maintain. Tool calling, streaming, and
- Context size, output limit, and image support come from pi's own model image input work.
catalog, so they stay current as pi updates.
- Tool calling, streaming, and image input work through pi's built-in
OpenAI Responses support.
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 ```sh
pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt
``` ```
This follows the latest version; `pi update --extensions` pulls updates. To To stay on a fixed release instead of following the latest version, add the
stay on one release instead, pin its tag: tag: `…/pi-unigpt@v0.1.0`.
`pi install git:imsc.uni-graz.at/git/behackl/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 ```text
/login unigpt /login unigpt
``` ```
Paste your UniGPT API key into the masked dialog, **not into the chat**. Pi Paste your API key into the masked dialog, **not into the chat**. Pi checks
confirms how many models your key can use. Pick one with `/model`; UniGPT the key and reports how many models it can use.
models are listed under `unigpt`.
To try the extension without installing it: **3. Pick a model**
```sh Run `/model` and choose one of the models listed under `unigpt`.
pi -e git:imsc.uni-graz.at/git/behackl/pi-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 ## Commands
| Command | What it does | | Command | Purpose |
| --- | --- | | --- | --- |
| `/login unigpt` | Save and verify your API key | | `/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) |
| `/model` | Pick a model; also reloads the model list | | `/unigpt-refresh` | Reload the model list and report any problem |
| `/unigpt-refresh` | Reload the UniGPT model list now and show how many models you have | | `/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 Pi saves the key unencrypted in `~/.pi/agent/auth.json`, readable only by
OpenAI model names, so the extension looks each one up in pi's bundled model your user account. To avoid that, edit the `unigpt` entry there to read the
catalog and uses its name, context window, output limit, and image support. key from an environment variable or a password manager:
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`:
```json ```json
{ { "unigpt": { "type": "api_key", "key": "${UNIGPT_API_KEY}" } }
"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}" }
}
``` ```
```json ```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 - **Thinking levels are off.** uniGPT applies a fixed reasoning effort per
`providers` in `~/.pi/agent/models.json` (overrides as shown above are model and ignores pi's setting. Reasoning models still reason.
fine). Otherwise your old model list and key take precedence over the - **Costs show as zero.** That means "not tracked", not "free".
extension. Then run `/reload` and `/login unigpt`. - **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 ## Troubleshooting
- **No UniGPT models in `/model`:** run `/unigpt-refresh`; it reports the - **No uniGPT models in `/model`:** run `/unigpt-refresh`; it names the
exact problem (rejected key, unreachable server, empty model list). problem (rejected key, unreachable server, empty model list).
- **`pi -p` says a UniGPT model was not found:** print mode only reads the - **`pi -p` can't find a uniGPT model:** print mode doesn't fetch model
saved model list and never fetches it. Start pi interactively once after lists. Start pi interactively once after logging in.
logging in; later print runs reuse that list. - **One model fails with HTTP 500:** that deployment is broken on the
- **A specific model fails with HTTP 500:** some deployments are server; pick another model and tell the uniGPT team.
misconfigured on the server side; try another model and tell the UniGPT - **Install fails with `spawn npm ENOENT`:** you use pnpm instead of npm.
team. Add `"npmCommand": ["pnpm"]` to `~/.pi/agent/settings.json`.
## Feedback Report bugs at <https://imsc.uni-graz.at/git/behackl/pi-unigpt/issues>.
Include the `/unigpt-refresh` output and the model you used, never your
Please report problems and ideas at API key.
<https://imsc.uni-graz.at/git/behackl/pi-unigpt/issues>. Include the output
of `/unigpt-refresh` and the model you used, but never your API key.
## Development ## Development
@ -128,9 +112,8 @@ pnpm install
pnpm run ci # type check + tests pnpm run ci # type check + tests
``` ```
Tests use fake keys and a local HTTP server; they never contact UniGPT or Tests use fake keys and a local server; they never contact uniGPT.
read your pi configuration.
## License ## License
MIT [MIT](LICENSE)