@pouchy_ai/admin-sdk 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.**

package/README.md

@@ -89,6 +89,63 @@ inside the provider's structured-output subset (root object,
 `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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.17.0";
+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[];
@@ -679,6 +683,17 @@ export interface AdminClient {
      *  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>;
@@ -687,6 +702,7 @@ export interface AdminClient {
         strict?: boolean;
         model?: string;
         schemaName?: string;
+        reasoningEffort?: AdminReasoningEffort;
     }): Promise<{
         data: T;
         raw: string;

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.17.0';
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.17.0",
+  "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",