# @czottmann/pi-umans

Umans provider extension for [pi](https://pi.dev). It registers tool-capable [Umans](https://umans.ai/) models under the `umans` provider.

## How is it different from [the official Umans pi extension](https://github.com/umans-ai/pi-provider-umans)?

This extension is just the provider connection: it registers the Umans models and handles the subscription login. Nothing else.

Besides extra tools, the official extension also ships a client-side vision proxy. If you already run a pi media proxy plugin, the bundled one gets in the way. It kept interfering with mine. This package ships no media-handling code of its own. Models that Umans marks vision-capable take images straight through the gateway; for text-only models, image handling stays with whatever media proxy you run (see [Vision and images](#vision-and-images)).

## Install

From npm:

```bash
pi install npm:@czottmann/pi-umans
```

From a local checkout:

```bash
cd path/to/pi-umans
npm install
pi install "$PWD"
```

## Set up auth

Umans is a subscription, so it logs in under subscriptions, not API keys:

```bash
pi
/login
# Under "Subscriptions", choose "Umans".
# pi shows the API-keys page; create a key there and paste it when prompted.
```

Get the key from <https://app.umans.ai/billing?context=personal&tab=api-keys>. pi stores it in `~/.pi/agent/auth.json`.

Or set an environment variable before starting pi:

```bash
export UMANS_API_KEY=your-key-here
```

## Use

List registered models:

```bash
pi --list-models | grep umans
```

Start pi with Umans:

```bash
pi --provider umans
```

In interactive mode, `/umans-models` lists the Umans models registered by the extension.

## How it works

On startup the extension fetches `GET https://api.code.umans.ai/v1/models/info`, keeps the models that support tools, and registers them with `pi.registerProvider()` using pi's `anthropic-messages` API adapter.

Model metadata comes from the Umans catalog:

- `capabilities.context_window` becomes pi's context window.
- `capabilities.recommended_max_tokens` becomes pi's max output tokens, clamped just below `max_completion_tokens` so it never trips the gateway's hard cap.
- `capabilities.reasoning` marks a model as reasoning-capable and maps pi's thinking levels to Umans effort levels (pi's `xhigh` reaches Umans `max`; models that can't disable thinking keep it on).
- `capabilities.supports_vision` adds image input when it is `true` or `"via-handoff"` (see below).

The catalog reports no per-token pricing because Umans bills a flat subscription, so registered models carry a cost of 0.

The login flow only needs the static API key. The catalog endpoint is public, so models register without a key, but inference needs either a key saved through `/login` or `UMANS_API_KEY`.

## Vision and images

This provider talks to Umans over the Anthropic Messages endpoint, so every model Umans marks vision-capable accepts images: both native vision (`supports_vision: true`) and gateway-handoff models (`supports_vision: "via-handoff"`, e.g. `umans-glm-5.2`). For handoff models the gateway runs the vision step server-side; nothing on the client analyzes the image.

Models with no vision support register text-only. To send images to those, run a separate media proxy plugin that turns images into text before they reach the model. That part is out of scope here.

## Development

```bash
npm run check
npm run build
pi -e . --provider umans
```

## Publishing

GitHub Actions publishes the package to npm when a GitHub Release is published. The release tag must match `package.json` exactly, with or without a leading `v` (`v1.0.0` and `1.0.0` both work for version `1.0.0`).

The workflow uses npm Trusted Publishing, so it does not need an npm token secret. Configure this package on npm with this repository and workflow file (`.github/workflows/publish.yml`). The workflow builds the package, runs `npm run check`, and publishes with npm provenance.

## Author

Carlo Zottmann, <carlo@zottmann.dev>

- Website: https://actions.work
- GitHub: https://github.com/czottmann
- Bluesky: https://bsky.app/profile/zottmann.dev
- Mastodon: https://norden.social/@czottmann