pi-agnes-tools 0.3.1 → 0.3.4

package/README.md

@@ -1,88 +1,104 @@
 # pi-agnes-tools
 
-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.
+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
 ```
 
-Or from git:
+Export an API key, then use it:
 
 ```bash
-pi install git:github.com/DraconDev/pi-agnes-tools
+export AGNES_API_KEY=sk-...          # international endpoint
+export AGNES_CN_API_KEY=cn-sk-...    # China endpoint (optional)
 ```
 
-> 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).
+```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
 
-### Models (`/model` selector)
+### 1. Text models (in `/model`)
 
-Only **text/LLM** models are registered — image and video live in the skill
-+ tools, not in the chat model list. Both regions:
+Only **text/LLM** models are registered. Image/video are **not** selectable
+models — they live in the tools + skill. Both regions:
 
 | 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` |
 
-Text models: `agnes-2.0-flash`, `agnes-2.5-flash`, `agnes-2.5-pro`,
+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 are filtered out).
-
-```bash
-pi --model agnes/agnes-2.5-flash "hello"
-pi --model agnes-cn/agnes-2.5-flash "你好"
-```
+newer text models automatically (image/video entries are filtered out).
 
-### Image / video — via tools + skill (not in `/model`)
+`agnes-cn` only appears once a CN key is configured (env var or a key stored
+under `agnes-cn` in `auth.json`).
 
-Two ways to generate media:
+### 2. Media tools + skill (any chat model)
 
-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.
+Two ways to generate media — no `/model` switch:
 
-The LLM does not need to switch models. Default image model:
-`agnes-image-2.5-flash`. Default video model: `agnes-video-2.5-flash`.
+- **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.
 
-#### `agnes_image`
+Defaults: image `agnes-image-2.5-flash`, video `agnes-video-2.5-flash`.
+Output: `.pi/generated-images/`, `.pi/generated-videos/` (project-relative).
 
-| Param | Notes |
+| Tool | Key params |
 |---|---|
-| `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` |
+| `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` |
 
-#### `agnes_video`
+## Install sources
 
-| 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 |
+```bash
+pi install npm:pi-agnes-tools
+pi install git:github.com/DraconDev/pi-agnes-tools
+```
 
-Output paths are project-relative (`.pi/generated-images/`, `.pi/generated-videos/`).
+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.
 
-## Auth
+> **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.
 
-Key resolution order: env var → `/login`-stored key in `~/.pi/agent/auth.json`.
+## Auth
 
-`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).
+Resolution order: `AGNES_API_KEY` / `AGNES_CN_API_KEY` env vars →
+`/login`-stored key in `~/.pi/agent/auth.json`.
 
 ## Notes
 
-- `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.
+- `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).

package/extensions/agnes-tools.ts

@@ -183,6 +183,10 @@ async function pollVideo(baseUrl, videoId, apiKey, signal) {
 }
 
 async function requestVideo(baseUrl, apiKey, opts) {
+  // NOTE: the API accepts different fields per model. The flash/2.5 routes
+  // reject `num_frames` / `frame_rate` as request fields; v2.0 accepts the
+  // request with defaults. So we only send them when the caller explicitly
+  // provides them — never as hard-coded defaults.
   const body = { model: opts.model, prompt: opts.prompt };
   if (opts.num_frames) body.num_frames = opts.num_frames;
   if (opts.frame_rate) body.frame_rate = opts.frame_rate;
@@ -204,8 +208,10 @@ async function requestVideo(baseUrl, apiKey, opts) {
   if (!videoId) throw new Error("Agnes video API returned no video_id");
 
   const result = task.status === "completed" ? task : await pollVideo(baseUrl, videoId, apiKey, opts.signal);
-  const url = result && result.metadata && result.metadata.url;
-  if (!url) throw new Error("Agnes video API returned no metadata.url");
+  // The completed payload carries the video URL at top-level `url` (v2.0 and
+  // friends). Some routes nest it under `metadata.url`, so check both.
+  const url = (result && (result.url || (result.metadata && result.metadata.url))) || null;
+  if (!url) throw new Error("Agnes video API returned no video url");
 
   const directory = join(process.cwd(), ".pi", "generated-videos");
   await mkdir(directory, { recursive: true });
@@ -298,8 +304,10 @@ async function executeVideo(_toolCallId, params, signal) {
     model: rawModel,
     prompt,
     images: params.images || [],
-    num_frames: params.num_frames || 121,
-    frame_rate: params.frame_rate || 24,
+    // Only forward when explicitly provided — some Agnes video routes reject
+    // num_frames/frame_rate as request fields and use their own defaults.
+    num_frames: params.num_frames,
+    frame_rate: params.frame_rate,
     signal,
   });
 
@@ -463,6 +471,7 @@ function streamStandaloneVideo(model, context, options) {
         signal: options && options.signal,
       });
       pushDone(stream, output, "Generated video saved to: " + fileLink(saved.filePath) + "\n\nVideo URL: " + saved.remoteUrl);
+      pushDone(stream, output, "Generated video saved to: " + fileLink(saved.filePath) + "\n\nVideo URL: " + saved.remoteUrl);
     } catch (error) {
       pushError(stream, output, error, options && options.signal);
     }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "pi-agnes-tools",
-  "version": "0.3.1",
-  "description": "Pi extension for Agnes AI: text model catalog (selectable via /model) plus image/video generation as custom tools + skill. No model switch needed for media.",
+  "version": "0.3.4",
+  "description": "Agnes AI for pi: /model text model catalog (intl + CN) plus image/video generation as callable tools + auto-loaded skill. No model switch needed for media.",
   "type": "module",
   "keywords": [
     "pi",
-    "extension",
     "pi-package",
+    "pi-extension",
+    "pi-skill",
     "agnes",
     "agnes-ai",
     "image-generation",
@@ -21,7 +22,8 @@
   "files": [
     "extensions",
     "skills",
-    "README.md"
+    "README.md",
+    ".github/banner.png"
   ],
   "scripts": {
     "test": "node --test"
@@ -37,6 +39,7 @@
     ],
     "skills": [
       "./skills"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/DraconDev/pi-agnes-tools/main/.github/banner.png"
   }
 }

package/skills/agnes-media/SKILL.md

@@ -28,7 +28,14 @@ directly — do NOT switch to an Agnes model.
 | `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 (base64 data URIs) |
-| `num_frames` / `frame_rate` | defaults 121 / 24 |
+| `num_frames` / `frame_rate` | only sent when you pass them; some routes reject these fields |
+
+**Model availability is per-distributor:** `agnes-video-v2.0` is the reliable
+text-to-video model (returns a top-level `url`). `agnes-video-2.5-flash`
+(sometimes the default) may require a `mode` field this tool does not send,
+and `agnes-video-2.5` can be unavailable under some plans. If a video call
+fails with `mode is required` or `No available channel`, retry with
+`model: "agnes-video-v2.0"`.
 
 ## Notes