🔗 pi-umans-provider

• OpenAI-compatible API - Uses UMANS's /v1/chat/completions endpoint
• Reasoning models - reasoning_effort-controlled thinking, surfaced as reasoning_content
• Vision models - Image input on all models
• Tool use - Function calling support across all models
• Streaming - Real-time token streaming
• Subscription-based - All models included in your plan, no per-token cost
• Usage status bar — Displays your plan, concurrent sessions, and remaining requests in the pi footer
• Quiet live model sync — Models refresh from the UMANS API in the background, at most hourly and by one pi process at a time (details)

Note: umans-flash-beta is deprecated (sunset 2026-06-07). Use umans-flash instead. umans-qwen3.6-35b-a3b is a technical alias for umans-flash.

Install directly from GitHub:

pi install https://github.com/monotykamary/pi-umans-provider

Then set your API key and run pi:

# Recommended: add to auth.json
# See Authentication section below

# Or set as environment variable
export UMANS_API_KEY=your-api-key-here

pi

Get your API key from code.umans.ai.

1. Clone this repository:

   git clone https://github.com/monotykamary/pi-umans-provider.git
   cd pi-umans-provider

2. Set your UMANS API key:

   # Recommended: add to auth.json
   # See Authentication section below
   
   # Or set as environment variable
   export UMANS_API_KEY=your-api-key-here

3. Run pi with the extension:

   pi -e /path/to/pi-umans-provider

The UMANS API key can be configured in multiple ways (resolved in this order):

1. auth.json (recommended) — Add to ~/.pi/agent/auth.json:

   { "umans": { "type": "api_key", "key": "your-api-key" } }

   The key field supports literal values, env var names, and shell commands (prefix with !). See pi's auth file docs for details.
2. Runtime override — Use the --api-key CLI flag
3. Environment variable — Set UMANS_API_KEY

Get your API key from code.umans.ai.

Add to your pi configuration for automatic loading:

{
  "extensions": [
    "/path/to/pi-umans-provider"
  ]
}

Once loaded, select a model with:

/model umans umans-coder

Or use /models to browse all available UMANS models.

• umans-coder — Best for complex, coding-heavy workloads. Optimized for coding agents.
• umans-flash — Fastest model for low-latency iteration with tools.
• umans-kimi-k2.7 — Moonshot's Kimi K2.7-Code for the hardest, multi-step coding tasks. Reasoning is always on.

For reasoning models, control thinking depth:

/reasoning high

Levels: off, minimal, low, medium, high (default: medium). off disables reasoning (maps to reasoning_effort: none); minimal is mapped to the nearest UMANS level.

Once authenticated, the pi footer shows your UMANS account status:

Code Max (Founding Seat) | ⟠ 1/4

• Plan name — Your current subscription plan
• ⟠ N/M — Active concurrent sessions / max concurrent sessions
• ⇄ N — Remaining requests in the current window (shown when limited)

The concurrent-session count is tracked locally: it's optimistically incremented the moment an agent run starts (no API call needed — the server has a brief registration lag anyway), reconciled with UMANS's /v1/usage endpoint after each agent run ends, and lightly polled while idle so the baseline stays fresh. The plan name and request budget are fetched on session start and model selection.

The footer (and every /v1/usage call) is interactive-only: print mode (pi -p) and headless child agents never poll. On session start, one pi process per 60 seconds calls /v1/usage and writes the result to ~/.pi/agent/cache/umans-usage.json (with the same lock and key fingerprint as the model sync); other sessions started within that window render it from disk.

Startup never waits on the network. pi starts with the cached catalog (~/.pi/agent/cache/umans-models.json, falling back to the bundled models.json) and revalidates against /v1/models/info in the background — only when:

• a UMANS API key is configured (no key, no request),
• the cache is older than 1 hour, missing, or was fetched with a different API key, and
• no other pi process is already refreshing it (an umans-models.lock file next to the cache).

So /new, /reload, pi -p and fan-out child agents share one cache instead of each calling the API; a session that skips the fetch still picks up a cache another process refreshed. Logging in with /login revalidates right away. A failed refresh is retried after 5 minutes at the earliest. PI_PROVIDER_SYNC_TTL_MS changes the window (0 revalidates on every session start). Only a hash fingerprint of the key is stored (umans-models.sync.json), never the key itself.

The UMANS API follows OpenAI conventions with these differences (handled via patch.json and before_provider_request hook):

The extension also sanitizes orphaned tool_calls in conversation history. Context compaction can drop tool result messages while keeping the assistant message that made the tool call, causing a 400 error from the API. The before_provider_request hook detects this and inserts synthetic tool results.

To refresh the model list from the UMANS API:

npm run update-models

This fetches from /v1/models/info, updates models.json, and regenerates the README model table. Idempotent — safe to run repeatedly.

• UMANS: https://code.umans.ai
• OpenAI-compatible endpoint: https://api.code.umans.ai/v1
• Models endpoint: https://api.code.umans.ai/v1/models
• Models info: https://api.code.umans.ai/v1/models/info
• Usage endpoint: https://api.code.umans.ai/v1/usage

MIT