@pouchy_ai/admin-sdk 0.16.1 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.18.0 — 2026-08-07
+
+- **`extractJson` takes `reasoningEffort`, and its server default moved to
+  `'low'`.** 0.17.0 shipped the endpoint running on the shared one-shot floor of
+  `'minimal'`, and nothing could change it — the request accepted a `model` but
+  not a thinking budget, so an integrator who noticed the quality had no lever
+  short of swapping models.
+
+  It is measured, not theoretical. An A/B over 26 utterances against an
+  integrator's own extractor agreed on kind for all 22 inputs carrying a SINGLE
+  directive, and diverged on exactly the two carrying more than one:
+  「以后别叫我宝贝，叫我老板」 came back labelled by its leading clause (a
+  boundary) instead of its operative one (a nickname), and 「叫我阿凯，别剧透，
+  我不喜欢虐心结局」 merged three directives into two. In both the summary text
+  was correct and complete — only the segmentation collapsed, and in both the
+  earlier-appearing kind absorbed the later one. That is the signature of a
+  budget that can write one good sentence but cannot deliberate over how many
+  items there are, which is exactly what an extraction endpoint is for.
+
+  `'minimal'` restores 0.17.0's behaviour if you want the cheapest, fastest
+  extraction; raise it further when one input can carry several directives at
+  once. `AdminReasoningEffort` is exported. Additive — every 0.17.0 call
+  compiles unchanged — but note the DEFAULT moved, so extraction calls that pass
+  nothing now think one notch harder and cost slightly more.
+
+  A domain precedence rule ("a nickname wins over a boundary when the user says
+  what to call them") still belongs in YOUR schema's `description`, not in this
+  endpoint: it forwards your schema verbatim and holds no opinion about your
+  vocabulary.
+
+## 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,101 @@ 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.
+
+#### `reasoningEffort` — matters most when one input carries several directives
+
+`reasoningEffort` (`'minimal' | 'low' | 'medium' | 'high'`, default `'low'`) is
+the thinking budget. It is worth a moment because extraction fails at the cheap
+tier in a specific, easy-to-miss way: **the summary comes out right and the
+segmentation collapses.**
+
+Measured over 26 utterances against an integrator's own extractor, the previous
+floor (`'minimal'`) agreed on kind for all 22 inputs carrying a SINGLE
+directive, then diverged on both inputs carrying more than one — 「以后别叫我宝
+贝，叫我老板」 labelled by its leading clause (a boundary) rather than its
+operative one (a nickname), and 「叫我阿凯，别剧透，我不喜欢虐心结局」 merged
+three directives into two. In each case the item's own text mentioned every
+clause; only the count and the label were wrong, which is exactly the failure a
+schema check cannot catch.
+
+Pass `'minimal'` for the cheapest, fastest extraction when each input carries at
+most one directive. Raise it above the default when the split matters more than
+the latency.
+
+Precedence between YOUR kinds — "a nickname wins over a boundary when the user
+also says what to call them" — belongs in the schema's `description`, not here:
+this endpoint forwards your schema verbatim and holds no opinion about your
+vocabulary.
+
+```ts
+const { data } = await admin.extractJson<{ items: { kind: string; summary: string }[] }>({
+  content: '以后别叫我宝贝，叫我老板',
+  reasoningEffort: 'low',
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['items'],
+    properties: {
+      items: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['kind', 'summary'],
+          properties: {
+            kind: {
+              type: 'string',
+              enum: ['nickname', 'boundary', 'preference'],
+              // The precedence rule lives HERE, in your vocabulary's own words.
+              description:
+                'One directive per item — never merge two of different kinds. If the user says what to CALL them (even alongside what not to), the item is `nickname` and the rejected form goes in the summary; `boundary` is only for a prohibition with no replacement.'
+            },
+            summary: { type: 'string' }
+          }
+        }
+      }
+    }
+  }
+});
+```
+
+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.18.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
@@ -436,6 +436,10 @@ export type SkillKnobResult<T> = T & {
     reprovisioned: number;
     truncated: boolean;
 };
+/** Thinking budget for `extractJson`, cheapest first. Mirrors the server's
+ *  vocabulary; an unknown value is refused with a 400 by the endpoint rather
+ *  than forwarded to the provider. */
+export type AdminReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 export interface AdminClient {
     listAgents(): Promise<{
         agents: Agent[];
@@ -652,6 +656,61 @@ 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).
+     *
+     *  `reasoningEffort` is the thinking budget, default `'low'`. It matters more
+     *  than it sounds for extraction: the shared one-shot floor is `'minimal'`,
+     *  and an A/B over 26 utterances found that floor agreed on kind for all 22
+     *  inputs carrying a SINGLE directive, then diverged on both inputs carrying
+     *  more than one — labelling "以后别叫我宝贝，叫我老板" by its leading clause
+     *  (a boundary) rather than its operative one (a nickname), and merging three
+     *  directives into two. The summary text was correct both times; only the
+     *  segmentation collapsed. Raise it when one input can carry several
+     *  directives at once and the split matters more than the latency; pass
+     *  `'minimal'` for the cheapest, fastest extraction.
+     *
+     *  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;
+        reasoningEffort?: AdminReasoningEffort;
+    }): 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.18.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.18.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",