# pi-experientiallabs

[![npm version](https://img.shields.io/npm/v/pi-experientiallabs.svg)](https://www.npmjs.com/package/pi-experientiallabs)

A [Pi] extension that registers [Experiential Labs] as an inference provider,
using the OpenAI Responses API, dynamic model discovery, and showing your
remaining credit balance in the status line while an Experiential Labs model
is active.

[Pi]: https://pi.dev
[Experiential Labs]: https://platform.experientiallabs.ai

```sh
# via NPM
pi install npm:pi-experientiallabs
```

> [!IMPORTANT]
> As of v83, Pi only creates and updates provider extensions' model caches when
> launched interactively. If you mostly use Pi in headless or non-interactive
> environments, open the TUI whenever you want to get new models or updated
> metadata.

## Usage

- Mint an `xpl_…` key at [API Keys](https://platform.experientiallabs.ai/settings/api-keys).
- Set `EXPLABS_API_KEY`, then open `pi`. You can also send `/login` and pick
  `Experiential Labs`.
- For a self-hosted gateway, set `EXPLABS_BASE_URL` (with or without `/v1`).
  The default is `https://api.experientiallabs.ai/v1`.

Pick an Experiential Labs model by sending `/model` and filtering by either
provider name `explabs` or a slug like `claude-fable-5.1`.

After credentials are configured, Pi discovers available models and persists
the latest successful catalog in its standard model store. A previously
discovered catalog remains available when a later refresh fails. The catalog
is the public tool-capable text models, plus your organization's custom and
local models when a key is present. Batch slugs are omitted.

Pi restores the session model by requiring both the catalog entry and a
configured-auth snapshot, but that snapshot is filled in asynchronously. When a
session recorded on `explabs` loses that race — and other extensions doing
startup work make it more likely — Pi falls back to its default model and warns
`Could not restore model explabs/<slug>`. On `session_start` this extension
waits briefly for the provider to become available again and re-selects the
recorded model, so resuming such a session keeps you on the model you left off
with.

While an Experiential Labs model is active, your remaining credit balance is
shown in the status line (`total_credits − total_usage` from
`GET /api/v1/credits`). It refreshes after each turn. The line is cleared if
there is no key, the request fails, or you switch away from `explabs`.

Inference uses `POST /v1/responses`. Do not write the raw key into
`models.json`; Pi interpolates `EXPLABS_API_KEY` at request time.

## License

[MIT](./LICENSE)