ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= pi-requesty-discover

image:https://img.shields.io/npm/v/pi-requesty-discover.svg[npm version,link=https://www.npmjs.com/package/pi-requesty-discover]

This extension helps you discover currently available models in requesty.ai for your Pi Coding Agent.

This is a fork of https://github.com/requestyai/pi-requesty[pi-requesty] with additional features:

* Use the `apiKey` from the model registry allowing you to use
https://pi.dev/docs/latest/models#value-resolution[pi's full value resolution] capabilities
* Health-check available models and write a log about them
* Brief information about what was found, including added/removed models, health summary
* Confirm before writing `models.json`, with a dry-run mode that only previews
* A footer status line showing your monthly Requesty spend against your monthly limit
* Optional Settings file in *json5* format

== When and why use it

Use this extension if

- you are on Requesty.ai
- you are limited to certain models by a company policy (for instance, for data residency/protection reasons)
- you don't want to handcraft your own curated list of models constantly
- you want to health-check models and preview the diff before writing
- you want to keep in touch with your usage without having to constantly visit the Requesty dashboard

== Installation

[source,bash]
----
# NPM
pi install npm:pi-requesty-discover
# GitHub
pi install git:github.com/enolive/pi-requesty-discover
----

== Install locally

Check out the code from the official code repository `https://github.com/enolive/pi-requesty-discover`, and then:

[source,bash]
----
pi install ./pi-requesty-discover
----

To run once without installing:

[source,bash]
----
pi -e ./pi-requesty-discover
----

== Configuration

The extension reads the `requesty-export` provider from `~/.pi/agent/models.json`.
You can override the provider id via the settings.

Example:

[source,json]
----
{
  "providers": {
    "requesty-export": {
      "name": "Requesty",
      "baseUrl": "https://router.requesty.ai/v1",
      "api": "openai-completions",
      "apiKey": "$REQUESTY_API_KEY",
      "models": []
    }
  }
}
----

IMPORTANT: Health checks are designed to use only a few tokens, but they still make real Requesty API calls and **will** consume credits.

On startup, the extension fetches `<baseUrl>/models` using the configured `apiKey` as the bearer token and registers discovered and healthy models with Pi.

=== Discovery settings

The discovery workflow reads optional settings from `requesty-discovery-settings.json5` in the Pi config directory (`PI_CODING_AGENT_DIR`).
The file uses JSON5, so it supports comments.
It is optional. When missing, it will be created including defaults.

Example:

[source,json5]
----
{
  "$schema": "https://raw.githubusercontent.com/enolive/pi-requesty-discover/main/docs/requesty-discovery-settings.schema.json",

  // override the default provider id
  providerId: "requesty-export",
  // configure the health check mode
  healthCheckMode: "full", // or "basic", "off"
  // models excluded from discovery; useful for models that keep failing health checks
  bannedModels: [
    // hangs on tool calls
    'requesty/unstable-model',
  ],
}
----

Banned models are excluded before health checks run (so they cost no credits) and are removed from `models.json` on the next discovery write.

=== Environment variables

[cols="1,1,1,1,2",options="header"]
|===
| Name | Required | Type | Default | Meaning

| `PI_CODING_AGENT_DIR`
| no
| `string`
| `~/.pi/agent`
| pi configuration directory
|===

== Command

Inside Pi:

[source,text]
----
/requesty-discover
----

The command:

- discovers Requesty models (and optional health checks)
- shows a summary notification (added/removed IDs, health summary)
- asks for confirmation before writing `~/.pi/agent/models.json`
- refreshes Pi's model registry so the new models are immediately available in `/model`
- reports whether the file was updated

If there are no model ID changes, confirmation still offers a metadata refresh write, which might have changed as well.

[source,text]
----
/requesty-discover --dry-run
----

Same discovery and health checks, but never prompts to write and leaves `models.json` unchanged.

[source,bash]
----
pi -p "/requesty-discover"
pi -p "/requesty-discover --dry-run"
----

You can also run the command from the CLI in a non-interactive mode.

== Usage status

The extension shows your current Requesty monthly spend as a persistent line in Pi's footer, e.g.:

[source,text]
----
<API Key Name>: $63.55/$150.00 (42%)
----

When your API key has no monthly limit (`monthly_limit` is `0`), the limit is treated as unlimited:

[source,text]
----
<API Key Name>: $63.55 (unlimited)
----

When you select a model from a provider other than `REQUESTY_PROVIDER_ID`, the status is cleared — there is no Requesty usage to show for it.

NOTE: The footer update is best-effort and never blocks a turn.
If it fails (network error, stale context after `/reload`), it fails silently without spamming notifications.