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
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
<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.
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
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)