@pouchy_ai/admin-sdk 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.17.0 — 2026-08-07
+
+- **New `extractJson()` — structured JSON output, outside the companion.**
+  `POST /v1/admin/utility/json`. Additive; nothing else changed.
+
+  This exists because using a companion agent for extraction does not work, and
+  did not fail in a way that explained itself. A companion turn is a
+  conversation engine — persona prompt, memory recall, tools — and when the
+  model returns an empty completion it answers with a natural-language fallback
+  line rather than shipping an empty bubble. Correct for a chat surface, wrong
+  for a parser. An extraction prompt reliably *reaches* that fallback, because
+  the reasoning-effort bump off the cheapest tier is gated on conversational and
+  functional cues (weather, search, wallet, social) that an extraction input
+  never matches. The result was a soft chat sentence where JSON was expected.
+
+  `extractJson()` shares none of that machinery: no persona, no memory, no
+  tools, no session, no fallback. One provider call with `response_format` set,
+  and a parsed result.
+
+  ```ts
+  const { data } = await admin.extractJson<{ nickname: string | null }>({
+    content: '叫我 Alex',
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['nickname'],
+      properties: { nickname: { type: ['string', 'null'] } }
+    }
+  });
+  // → { nickname: 'Alex' }
+  ```
+
+- **`strict` defaults to true**, which asks the provider to ENFORCE the schema.
+  The schema must then sit inside the provider's structured-output subset: root
+  object, `additionalProperties: false`, and every property listed in
+  `required` — model an optional field as a union with `null` rather than by
+  omitting it from `required`. A schema outside the subset comes back as `400`
+  / `code: 'schema_invalid'` carrying the provider's own reason instead of
+  failing at generation time. Pass `strict: false` to fall back to plain JSON
+  mode plus server-side validation.
+
+- **Failures are typed, not prose.** `schema_invalid` (400 — fix the schema;
+  retrying verbatim cannot help), `unavailable` (5xx — transient, back off),
+  `invalid_json` (502 — a completion arrived but did not parse or did not
+  satisfy the schema). `invalid_json` carries `raw`, the text actually
+  returned, so the failure is debuggable rather than opaque.
+
+- **Note on schema key names.** The companion reply path strips objects
+  matching internal memory-pipeline signatures, among them
+  `{domain, key, value, label}` and `{content, kind, importance}`. That
+  stripping does not apply to this endpoint — but if you were previously
+  extracting through a companion agent with a schema shaped like either of
+  those, a *correct* answer could be removed before you saw it. Another reason
+  to move extraction here.
+
 ## 0.16.1 — 2026-08-06
 
 Documentation only — no type, signature or runtime change. Two doc comments

package/README.md

@@ -58,6 +58,44 @@ console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
 // The agent can now drive the API from the skill's prose via http_request.
 ```
 
+### Structured JSON — use `extractJson`, not a companion agent
+
+```ts
+const { data } = await admin.extractJson<{ nickname: string | null }>({
+  content: '叫我 Alex',
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['nickname'],                 // strict mode: EVERY property, always
+    properties: { nickname: { type: ['string', 'null'] } }  // optional → union with null
+  }
+});
+console.log(data.nickname); // 'Alex'
+```
+
+A companion turn is a **conversation** engine — persona prompt, memory recall,
+tools — and when the model returns an empty completion it answers with a
+natural-language fallback line rather than an empty bubble. That is right for a
+chat surface and wrong for a parser, and an extraction prompt reliably reaches
+it, because the reasoning-effort bump off the cheapest tier is gated on
+conversational/functional cues an extraction input never matches. So a companion
+agent asked for JSON returns chat filler, fairly consistently.
+
+`extractJson` shares none of that: no persona, no memory, no tools, no session,
+no fallback — one provider call with `response_format` set. `strict` defaults to
+true, which makes the provider **enforce** the schema; the schema must then sit
+inside the provider's structured-output subset (root object,
+`additionalProperties: false`, every property listed in `required`). Pass
+`strict: false` for schemas outside it — you still get JSON mode plus
+server-side validation.
+
+Failures are typed rather than prose, so the recoveries are distinguishable:
+`schema_invalid` (400 — fix the schema; retrying verbatim cannot help),
+`unavailable` (5xx — transient, back off), and `invalid_json` (502 — a
+completion arrived but did not parse or satisfy the schema; the error carries
+`raw`, the text actually returned). Tokens roll into the project's month usage
+like any other model call.
+
 Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`) returns
 `SkillKnobResult<T>` — the knob you set plus `reprovisioned` (instances the new
 def reached) and `truncated`. A knob only binds a running agent once the def

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.16.1";
+export declare const ADMIN_SDK_VERSION = "0.17.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -652,6 +652,49 @@ export interface AdminClient {
         mode: 'semantic' | 'lexical';
         hits: unknown[];
     }>;
+    /** Structured JSON extraction, OUTSIDE the companion.
+     *
+     *  Use this — not a companion agent — whenever you want machine-readable
+     *  output. A companion turn is a conversation engine: it carries a persona
+     *  prompt, recalls memory, and when the model returns nothing it answers with
+     *  a natural-language fallback line rather than dead air. That is right for a
+     *  chat bubble and wrong for a parser, and an extraction prompt reliably
+     *  triggers it, because the reasoning-effort bump off the cheapest tier is
+     *  gated on conversational/functional cues that an extraction input does not
+     *  match. This endpoint shares none of that: no persona, no memory, no tools,
+     *  no session, no fallback — one provider call with `response_format` set.
+     *
+     *  `strict` (default true) asks the provider to ENFORCE the schema. It must
+     *  then sit inside the provider's structured-output subset: a root object,
+     *  `additionalProperties: false`, and EVERY property listed in `required`
+     *  (model an optional field as a union with `null`, not by omitting it from
+     *  `required`). A schema outside the subset is rejected with `400` /
+     *  `code: 'schema_invalid'` naming the provider's reason — pass
+     *  `strict: false` to fall back to plain JSON mode plus server-side
+     *  validation.
+     *
+     *  Failures are typed rather than prose, which is the point:
+     *  `schema_invalid` (400 — fix the schema, retrying verbatim cannot help),
+     *  `unavailable` (5xx — transient, back off), `invalid_json` (502 — a
+     *  completion arrived but did not parse or did not satisfy the schema; the
+     *  error carries `raw`, the text actually returned).
+     *
+     *  Tokens roll into the project's month usage like any other model call. */
+    extractJson<T = unknown>(input: {
+        schema: Record<string, unknown>;
+        content: string;
+        system?: string;
+        strict?: boolean;
+        model?: string;
+        schemaName?: string;
+    }): Promise<{
+        data: T;
+        raw: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.16.1';
+export const ADMIN_SDK_VERSION = '0.17.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -247,6 +247,7 @@ export function createAdminClient(opts) {
         ingestKnowledgeFile: (input) => request('POST', '/knowledge/file', input),
         ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
         searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
+        extractJson: (input) => request('POST', '/utility/json', input),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",