Split README into user guide and DEVELOPMENT.md
This commit is contained in:
Benjamin Hackl
parent
75d15827ab
commit
8172f41c56
1 changed files with 144 additions and 58 deletions
123
README.md
123
README.md
|
|
@ -1,16 +1,16 @@
|
|||
# pi-unigpt
|
||||
|
||||
Use [uniGPT](https://unigpt.uni-graz.at), the University of Graz's AI
|
||||
platform, as a model provider in [pi](https://pi.dev).
|
||||
assistant, inside the [pi](https://pi.dev) coding agent.
|
||||
|
||||
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.
|
||||
Once set up, every model your uniGPT account offers appears in pi's model
|
||||
picker, including GPT-4o, GPT-4.1, and the GPT-5 and GPT-6 families. Tools,
|
||||
streaming responses, and image input all work.
|
||||
|
||||
## Requirements
|
||||
## What you need
|
||||
|
||||
- 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
|
||||
- **pi 1.5 or newer** ([installation guide](https://pi.dev))
|
||||
- **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
|
||||
|
|
@ -21,27 +21,25 @@ image input work.
|
|||
pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt
|
||||
```
|
||||
|
||||
To stay on a fixed release instead of following the latest version, add the
|
||||
tag: `…/pi-unigpt@v0.1.0`.
|
||||
|
||||
**2. Log in**
|
||||
|
||||
Start pi (or run `/reload` if it is already running) and enter:
|
||||
Start pi (or type `/reload` if it is already running), then type:
|
||||
|
||||
```text
|
||||
/login 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.
|
||||
A dialog asks for your API key. Paste it there, **not into the chat**. Pi
|
||||
checks the key and tells you how many models you can use.
|
||||
|
||||
**3. Pick a model**
|
||||
|
||||
Run `/model` and choose one of the models listed under `unigpt`.
|
||||
Type `/model` and choose one of the models listed under **unigpt**.
|
||||
|
||||
**4. Optional: make uniGPT your default**
|
||||
That's it. Pi remembers your key and your last model for next time.
|
||||
|
||||
Add this to `~/.pi/agent/settings.json` to start pi with a uniGPT model:
|
||||
**Optional: start pi with uniGPT by default.** Add this to
|
||||
`~/.pi/agent/settings.json`, using any model from the list:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -52,18 +50,48 @@ Add this to `~/.pi/agent/settings.json` to start pi with a uniGPT model:
|
|||
|
||||
## Commands
|
||||
|
||||
| Command | Purpose |
|
||||
| Command | What it does |
|
||||
| --- | --- |
|
||||
| `/login unigpt` | Save and verify your API key |
|
||||
| `/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) |
|
||||
| `/login unigpt` | Save your API key (or replace it with a new one) |
|
||||
| `/model` | Choose a model |
|
||||
| `/unigpt-refresh` | Reload the list of models, e.g. after uniGPT adds new ones |
|
||||
| `/logout` | Remove your key from pi (the key itself stays valid) |
|
||||
|
||||
## Keeping your key out of auth.json
|
||||
## Updating
|
||||
|
||||
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:
|
||||
```sh
|
||||
pi update --extensions
|
||||
```
|
||||
|
||||
## Things to know
|
||||
|
||||
- **The thinking level setting has no effect.** uniGPT decides how much each
|
||||
model reasons; models that reason still do so.
|
||||
- **Costs are shown as zero.** Pi doesn't track uniGPT usage; this does not
|
||||
mean usage is unlimited. Your university's usage rules still apply.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **No uniGPT models in `/model`:** type `/unigpt-refresh`. It tells you
|
||||
what is wrong, e.g. a rejected key or no network connection.
|
||||
- **One model always fails with an error:** that model may be unavailable
|
||||
on uniGPT's side. Pick another one and let the uniGPT team know.
|
||||
- **`pi -p "…"` says a uniGPT model was not found:** start pi normally once
|
||||
after logging in, so it can load the model list.
|
||||
- **Installation fails with `spawn npm ENOENT`:** you use pnpm instead of
|
||||
npm. Add `"npmCommand": ["pnpm"]` to `~/.pi/agent/settings.json` and try
|
||||
again.
|
||||
|
||||
Still stuck? [Open an issue](https://imsc.uni-graz.at/git/behackl/pi-unigpt/issues)
|
||||
with the output of `/unigpt-refresh` and the model you used. **Never include
|
||||
your API key.**
|
||||
|
||||
## Advanced
|
||||
|
||||
**Storing the key elsewhere.** Pi saves your key unencrypted in
|
||||
`~/.pi/agent/auth.json`, readable only by your user account. To keep it out
|
||||
of that file, change the `unigpt` entry there to read it from an environment
|
||||
variable or a password manager command:
|
||||
|
||||
```json
|
||||
{ "unigpt": { "type": "api_key", "key": "${UNIGPT_API_KEY}" } }
|
||||
|
|
@ -73,42 +101,21 @@ key from an environment variable or a password manager:
|
|||
{ "unigpt": { "type": "api_key", "key": "!op read op://Private/uniGPT/credential" } }
|
||||
```
|
||||
|
||||
## Good to know
|
||||
**Adjusting model limits.** Pi knows the context size and output limit of
|
||||
common models. For a model it doesn't recognize, it assumes 128k tokens of
|
||||
context and 16k of output. If you know better, override them in
|
||||
`~/.pi/agent/models.json`:
|
||||
|
||||
- **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 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`.
|
||||
|
||||
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
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm run ci # type check + tests
|
||||
```json
|
||||
{ "providers": { "unigpt": { "modelOverrides": { "gpt-5.4": { "contextWindow": 200000 } } } } }
|
||||
```
|
||||
|
||||
Tests use fake keys and a local server; they never contact uniGPT.
|
||||
**Pinning a version.** To stay on one release, install with its tag, e.g.
|
||||
`pi install git:imsc.uni-graz.at/git/behackl/pi-unigpt@v0.1.0`.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [DEVELOPMENT.md](DEVELOPMENT.md).
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue