Pi

Pi connects to Actualyze through pi-actualyze, an extension package Actualyze publishes. Models are discovered automatically after you log in, so there is nothing to list or configure. The provider asks Actualyze which models your API key can call and adds each one to Pi with its context and output limits. Requests go through Pi's built-in OpenAI Chat Completions support.

#Before you start

• Pi 0.84.2 or newer, and pi-actualyze 1.1.0 or newer. Version 1.0.0 also asks for a target label at login.
• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your Pi usage draws down.

#Install

If Pi isn't installed yet, the installer works on macOS and Linux:

curl -fsSL https://pi.dev/install.sh | sh

Pi's quickstart covers Windows and the npm install.

Then install the provider package:

pi install npm:pi-actualyze

npm currently serves pi-actualyze 1.0.0, which also asks for a target at login. To get 1.1.0, install the tagged release from GitHub instead:

pi install git:github.com/actualyze-ai/pi-actualyze@v1.1.0

If you already installed from npm, run pi remove npm:pi-actualyze first so only one copy loads. pi list shows the source each installed package came from. To pin an npm version, append it to the spec, for example npm:pi-actualyze@<version>. To remove the package, run pi remove with the same spec you installed.

#Connect to Actualyze

Start Pi and log in:

/login actualyze

Login asks for one value, your API key. The prompt names the host it connects to, app.actualyze.ai. Paste your Actualyze API key.

Login checks the key by downloading your model list before it saves anything. If the check fails, nothing is stored. Pi keeps the key in its own credential store, and your models are ready as soon as login finishes.

Instead of /login, you can set the key in the environment before starting Pi. The key alone is enough:

export ACTUALYZE_API_KEY="<your-actualyze-api-key>"
pi

A credential saved through /login takes precedence over the variable. To remove the saved credential, run /logout and choose Actualyze; if the variable is still set, Pi keeps using it.

#Choose a model

Open the model selector and pick a model under the actualyze provider:

/model

• The list is every model your key can call. The provider fetches it at login, again each time you start Pi interactively, and each time you open /model, so models added to your key appear without any change on your side.
• Context and output limits come from Actualyze's model listing. When a model doesn't advertise them, the provider uses 128,000 and 16,384 tokens as placeholders to satisfy Pi's model schema; they aren't the model's real limits.
• Models that Actualyze lists as reasoning models accept Pi's thinking level, which is sent as reasoning_effort. Models that list image input accept images.
• Pi shows a cost of 0 for these models. Actualyze's model listing includes prices, but the provider doesn't pass them to Pi, so Pi can't estimate spend. Your usage is still metered and charged to the key's budget.

There is nothing to add to models.json. The provider only sends requests for models in the list it discovered.

#Troubleshooting

• Login asks for a target as well as the key: you have pi-actualyze 1.0.0, the npm release. Install 1.1.0 from GitHub (see Install), or enter app as the target.
• Environment-only setup finds no Actualyze models with 1.0.0: that version also needs export ACTUALYZE_TARGET=app. Version 1.1.0 needs only the key.
• actualyze doesn't appear in /login: the package isn't installed. Run pi list to check, then install it (see Install).
• Login fails with an authentication or catalog error: check the key and that https://app.actualyze.ai/openai/v1/models is reachable. The provider rejects redirects and non-JSON responses, so a proxy that returns an HTML page or a redirect breaks login.
• pi -p or pi --list-models finds no Actualyze models: neither one fetches model lists. Both use the list Pi saved during an interactive session, so start Pi interactively once on that machine first.
• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.

#Reference

• Provider source and README: actualyze-ai/pi-actualyze
• The --actualyze-target flag and ACTUALYZE_TARGET select a non-production environment. The hosted service doesn't need either.
• Pi's documentation and packages guide

Requests you cancel mid-stream still draw down the usage they consumed.