# Oh My Pi

Oh My Pi (`omp`) is a terminal agent. It sends OpenAI Chat Completions requests and reads model names and token limits from `GET /v1/models`.

This guide uses a separate `liquid` profile, with the provider file `~/.omp/profiles/liquid/agent/models.yml`. Your default profile does not change.

## Start with the Liquid CLI

The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts Oh My Pi with the exchange as its provider. It sets the base URL, the key and the model for that process only. It writes no file of yours. Use it unless you must keep the settings in your own files.

```bash
curl -fsSL https://inference.ai.exchange/cli/install.sh | bash
liquid login
liquid omp
```

Add `--model liquid.auto:cheapest` to rank the offers by price, or `--cap 0.50` to limit what one request may cost. To set up Oh My Pi yourself, follow the steps below.

## Before you start

- A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md).
- [Bun](https://bun.com/docs/installation) 1.3.14 or newer.
- Omp 18.6.1 or newer.

```bash
bun install -g @oh-my-pi/pi-coding-agent
```

## 1. Create the profile directory

```bash
mkdir -p ~/.omp/profiles/liquid/agent
```

## 2. Export the buyer key

Replace the placeholder with your buyer key. Use the same shell for the next commands.

```bash
export LIQUID_API_KEY=sk-liquid-...
```

| Setting          | Why it is set                                |
| ---------------- | -------------------------------------------- |
| `LIQUID_API_KEY` | The buyer key that Omp reads from the shell. |

## 3. Write the provider

This command replaces the provider file. If the profile has other providers, add the `liquid` block to the existing file instead.

```bash
cat > ~/.omp/profiles/liquid/agent/models.yml <<'EOF'
providers:
  liquid:
    baseUrl: "https://router.inference.ai.exchange/v1"
    api: openai-completions
    apiKey: LIQUID_API_KEY
    auth: apiKey
    authHeader: true
    headers:
      X-Title: Oh My Pi
      x-liquid-cap-usd: "1.00"
    discovery:
      type: openai-models-list
EOF
```

| Setting            | Why it is set                                                      |
| ------------------ | ------------------------------------------------------------------ |
| `baseUrl`          | The exchange URL, with `/v1`.                                      |
| `api`              | Selects OpenAI Chat Completions.                                   |
| `apiKey`           | Names the environment variable that holds the buyer key.           |
| `auth`             | Selects API-key authentication.                                    |
| `authHeader`       | Sends the key as a bearer token.                                   |
| `X-Title`          | Gives model discovery and chat requests the Oh My Pi client label. |
| `x-liquid-cap-usd` | Limits the charge for each request.                                |
| `type`             | Selects native model discovery from `GET /v1/models`.              |

`apiKey` is the name `LIQUID_API_KEY`, without `$`. If the variable is absent, Omp sends the name itself as the key. Discovery uses each model's published output limit, so Omp needs no copied model catalogue.

## 4. Check the model list

```bash
omp --profile liquid models liquid --json --no-extensions
```

The list includes the exchange models and your workspace presets. To refresh a cached list after the book changes, run:

```bash
omp --profile liquid models refresh liquid --json --no-extensions
```

## 5. Run it

```bash
omp --profile liquid --model liquid/liquid.auto
```

The model selector is `liquid/<model>`. In a session, `/model` changes the model. Start Omp with `--profile liquid` each time.

## Control the cost

The provider's `x-liquid-cap-usd` header limits the charge for each request. Change its value to change the cap. A tool task can make several requests, so set a limit on the key to limit total spend. See [API keys](https://inference.ai.exchange/docs/keys.md).

For other purchasing rules, add `compat.extraBody.exchange` to the `liquid` provider:

```yaml
compat:
  extraBody:
    exchange:
      limits:
        price:
          output_usd_per_mtok: 10
```

Omp sends this `exchange` object in each request body. See [Purchasing rules](https://inference.ai.exchange/docs/rules.md).

## Troubleshooting

| Symptom                    | Cause and fix                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `omp` cannot find Bun.     | Install Bun. Make sure that `bun` is on `PATH`.                                       |
| `401`                      | Export a non-empty `LIQUID_API_KEY`. Keep `apiKey` as the variable name, without `$`. |
| The model is absent.       | Refresh the list. Make sure that the model has a live offer.                          |
| Omp uses another provider. | Start it with `--profile liquid` and `--model liquid/<model>`.                        |
| `output_bound_unsupported` | Refresh the list to get the current token limits.                                     |

## Next steps

- [Pi](https://inference.ai.exchange/docs/connect-pi.md): the separate Pi agent and its provider configuration.
- [Market data](https://inference.ai.exchange/docs/market.md): models and live offers.
- [Purchasing rules](https://inference.ai.exchange/docs/rules.md): price caps and service floors.