pi-agnes-tools 0.1.0 → 0.3.4

package/README.md

@@ -1,62 +1,104 @@
 # pi-agnes-tools
 
-Pi extension that exposes **Agnes AI** image/video generation as callable tools — no model switch required. Pairs with [`pi-agnes`](https://pi.dev/packages/pi-agnes) for model registration / auth.
+The single Agnes AI plugin for [pi](https://pi.dev): **text model catalog**
+(selectable via `/model`) plus **image/video generation as custom tools + skill**.
+No model switch needed for media — the agent just calls a tool.
 
-## Install
+[![npm version](https://img.shields.io/npm/v/pi-agnes-tools)](https://www.npmjs.com/package/pi-agnes-tools)
+[![license: MIT](https://img.shields.io/badge/license-MIT)](./LICENSE)
+
+## Quick start
+
+```bash
+pi install npm:pi-agnes-tools
+```
+
+Export an API key, then use it:
 
 ```bash
-pi install path:/path/to/pi-agnes-tools
+export AGNES_API_KEY=sk-...          # international endpoint
+export AGNES_CN_API_KEY=cn-sk-...    # China endpoint (optional)
+```
+
+```bash
+# Text chat via the Agnes model catalog
+pi --model agnes/agnes-2.5-flash "hello"
+
+# Image / video: just ask in any pi session — the agnes-media skill teaches
+# the model to call the agnes_image / agnes_video tools.
+pi "Generate a 2-second video of a red apple falling off a wooden table, photorealistic"
 ```
 
+Or run `/login` once and pi stores the key in `~/.pi/agent/auth.json` for you.
+
 ## What it registers
 
-| Tool | Endpoint | What it does |
-|---|---|---|
-| `agnes_image` | `POST /v1/images/generations` | Generate an image. Saves to `.pi/generated-images/`. Returns the local path and (possibly expiring) remote URL. |
-| `agnes_video` | `POST /v1/videos` + poll | Generate a video. Polls every 5s (up to 30 min). Saves `.mp4` to `.pi/generated-videos/`. Supports image-to-video (1 ref image) and keyframes (>1 image). |
+### 1. Text models (in `/model`)
 
-## Parameters
+Only **text/LLM** models are registered. Image/video are **not** selectable
+models — they live in the tools + skill. Both regions:
 
-### `agnes_image`
-- `prompt` (required): text prompt
-- `model` (default `agnes-image-2.1-flash`): any `agnes-image-*` id
-- `endpoint` (`agnes` | `agnes-cn`, default `agnes`): which Agnes region
-- `images` (optional): array of base64 data URIs for reference/conditioning
-- `response_format` (default `png`)
+| Provider | Region | Base URL | Auth |
+|---|---|---|---|
+| `agnes` | International | `https://apihub.agnes-ai.com/v1` | `AGNES_API_KEY` |
+| `agnes-cn` | China | `https://api.agnes-ai.cn/v1` | `AGNES_CN_API_KEY` |
 
-### `agnes_video`
-- `prompt` (required): text prompt
-- `model` (default `agnes-video-2.5-flash`): any `agnes-video-*` id
-- `endpoint` (default `agnes`)
-- `images` (optional): 1 image → image-to-video, >1 → keyframes mode
-- `num_frames` (default 121), `frame_rate` (default 24)
+Seed text models: `agnes-2.0-flash`, `agnes-2.5-flash`, `agnes-2.5-pro`,
+`agnes-2.5-pro-alpha`, `agnes-3.0-flash`. Live `/v1/models` discovery adds
+newer text models automatically (image/video entries are filtered out).
 
-## Auth
+`agnes-cn` only appears once a CN key is configured (env var or a key stored
+under `agnes-cn` in `auth.json`).
 
-Key resolution order:
+### 2. Media tools + skill (any chat model)
 
-1. `AGNES_API_KEY` / `AGNES_CN_API_KEY` env vars (same as `pi-agnes`)
-2. `/login`-stored key from `~/.pi/agent/auth.json` (`agnes` provider)
+Two ways to generate media — no `/model` switch:
 
-| Provider | Endpoint | Env var |
-|---|---|---|
-| `agnes` | `https://apihub.agnes-ai.com/v1` | `AGNES_API_KEY` |
-| `agnes-cn` | `https://api.agnes-ai.cn/v1` | `AGNES_CN_API_KEY` |
+- **Tools** — `agnes_image`, `agnes_video` callable by any model.
+- **Skill** — `agnes-media` (auto-loaded) teaches the model how to call the
+  tools: prompt shaping, reference-image handling, endpoint choice, defaults.
 
-## Example (what the LLM sees / can call)
+Defaults: image `agnes-image-2.5-flash`, video `agnes-video-2.5-flash`.
+Output: `.pi/generated-images/`, `.pi/generated-videos/` (project-relative).
 
-```jsonc
-// Text-to-image
-{"name": "agnes_image", "arguments": {"prompt": "a watercolor painting of a fox in a misty pine forest"}}
+| Tool | Key params |
+|---|---|
+| `agnes_image` | `prompt`, `model`, `endpoint`, `images` (base64 data URIs), `response_format` |
+| `agnes_video` | `prompt`, `model`, `endpoint`, `images` (1 = img2vid, >1 = keyframes), `num_frames`, `frame_rate` |
 
-// Image-to-video
-{"name": "agnes_video", "arguments": {"prompt": "the fox slowly turns its head", "images": ["data:image/png;base64,..."]}}
+## Install sources
 
-// Multi-frame keyframes
-{"name": "agnes_video", "arguments": {"prompt": "fly through a canyon", "images": ["data:...frame1", "data:...frame2"], "model": "agnes-video-2.5"}}
+```bash
+pi install npm:pi-agnes-tools
+pi install git:github.com/DraconDev/pi-agnes-tools
 ```
 
+Listed in the [pi.dev/packages gallery](https://pi.dev/packages) — it auto-indexes
+npm packages tagged with the `pi-package` keyword (this package has it, plus
+`pi-extension` / `pi-skill`), and carries an `image` field in its `pi` manifest
+for a visual preview card.
+
+> **Replaces `pi-agnes`.** This plugin owns the `agnes` / `agnes-cn` providers
+> outright. Uninstall `pi-agnes` if you have it — two registrations would
+> overwrite each other.
+
+## Auth
+
+Resolution order: `AGNES_API_KEY` / `AGNES_CN_API_KEY` env vars →
+`/login`-stored key in `~/.pi/agent/auth.json`.
+
 ## Notes
 
-- Output paths are project-relative (`.pi/generated-images/`, `.pi/generated-videos/`) — matches where `pi-agnes` model-based generation saves.
-- `executionMode: parallel` for image (fast, stateless), `sequential` for video (long-running task, poll loop).
+- `executionMode: parallel` for image (fast, stateless); `sequential` for
+  video (long-running poll, up to 30 min).
+- **Video model availability is per-distributor.** In practice
+  `agnes-video-v2.0` is the reliable text-to-video model (5s / 720p clip,
+  completed payload carries the video at a top-level `url` — with
+  `metadata.url` as a fallback; the tool handles both). `agnes-video-2.5-flash`
+  may require a `mode` field this tool does not send, and `agnes-video-2.5`
+  can be unavailable under some plans ("No available channel"). If the
+  default `2.5-flash` fails, call the tool with `model: "agnes-video-v2.0"`.
+- `num_frames` / `frame_rate` are only sent when explicitly provided — some
+  video routes reject those request fields and apply their own defaults.
+- Debug: `PI_AGNES_TOOLS_DEBUG=1` logs registration + request decisions to stderr.
+- MIT licensed. Source: [github.com/DraconDev/pi-agnes-tools](https://github.com/DraconDev/pi-agnes-tools).