pi-agnes-tools 0.1.0 → 0.3.1

package/README.md

@@ -1,62 +1,88 @@
 # 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: text model catalog (selectable via `/model`)
+plus image/video generation as custom tools + skill. No model switch needed
+for media.
 
 ## Install
 
 ```bash
-pi install path:/path/to/pi-agnes-tools
+pi install npm:pi-agnes-tools
 ```
 
+Or from git:
+
+```bash
+pi install git:github.com/DraconDev/pi-agnes-tools
+```
+
+> Replaces `pi-agnes` — uninstall it if you have it (this plugin owns the
+> `agnes` / `agnes-cn` providers outright; keeping both installed causes the
+> two registrations to overwrite each other).
+
 ## 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). |
+### Models (`/model` selector)
 
-## Parameters
+Only **text/LLM** models are registered — image and video live in the skill
++ tools, not in the chat model list. 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)
+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 are filtered out).
 
-## Auth
+```bash
+pi --model agnes/agnes-2.5-flash "hello"
+pi --model agnes-cn/agnes-2.5-flash "你好"
+```
 
-Key resolution order:
+### Image / video — via tools + skill (not in `/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:
 
-| 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` |
+1. **Tool calls** — `agnes_image`, `agnes_video` are exposed to any chat model.
+2. **Skill** — `agnes-media` (auto-loaded with this package) tells the agent
+   exactly how to call the tools: prompt shaping, reference-image handling,
+   endpoint selection, defaults.
 
-## Example (what the LLM sees / can call)
+The LLM does not need to switch models. Default image model:
+`agnes-image-2.5-flash`. Default video model: `agnes-video-2.5-flash`.
 
-```jsonc
-// Text-to-image
-{"name": "agnes_image", "arguments": {"prompt": "a watercolor painting of a fox in a misty pine forest"}}
+#### `agnes_image`
 
-// Image-to-video
-{"name": "agnes_video", "arguments": {"prompt": "the fox slowly turns its head", "images": ["data:image/png;base64,..."]}}
+| Param | Notes |
+|---|---|
+| `prompt` | required |
+| `model` | default `agnes-image-2.5-flash`; others: `agnes-image-2.1-flash`, `agnes-image-2.0-flash` |
+| `endpoint` | `agnes` (default) or `agnes-cn` |
+| `images` | optional base64 data URIs for reference/conditioning |
+| `response_format` | default `png` |
 
-// Multi-frame keyframes
-{"name": "agnes_video", "arguments": {"prompt": "fly through a canyon", "images": ["data:...frame1", "data:...frame2"], "model": "agnes-video-2.5"}}
-```
+#### `agnes_video`
+
+| Param | Notes |
+|---|---|
+| `prompt` | required |
+| `model` | default `agnes-video-2.5-flash`; others: `agnes-video-2.5`, `agnes-video-v2.0` |
+| `endpoint` | `agnes` (default) or `agnes-cn` |
+| `images` | 1 image = image-to-video; >1 = keyframes mode |
+| `num_frames` / `frame_rate` | defaults 121 / 24 |
+
+Output paths are project-relative (`.pi/generated-images/`, `.pi/generated-videos/`).
+
+## Auth
+
+Key resolution order: env var → `/login`-stored key in `~/.pi/agent/auth.json`.
+
+`agnes-cn` only appears in the model list once a CN key is configured
+(`AGNES_CN_API_KEY` env or a key stored under `agnes-cn` in 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 loop, up to 30 min).
+- Debug: `PI_AGNES_TOOLS_DEBUG=1` logs registration decisions to stderr.