defiant-jazz 0.6.2 → 0.7.0

package/README.md

@@ -101,6 +101,42 @@ Per-call overrides work on both forms:
 await refine.dylan("Hello world", { model: 'claude-opus-5', maxTokens: 1024 });
 ```
 
+### Effort (Anthropic only)
+
+`effort` controls how much the model reasons before answering: `'low'`,
+`'medium'`, `'high'`, `'xhigh'` or `'max'`. Lower is cheaper and faster. Leave
+it unset to use the model's own default, which varies by model.
+
+```typescript
+const fast = createDefiantJazz({ effort: 'low' });
+await refine.dylan("Hello world", { effort: 'low' }); // per-call works too
+```
+
+- Setting `effort` with the OpenAI provider throws.
+- Not every model accepts every level (older models may reject `effort`
+  entirely); the API's error is passed through.
+- Reasoning tokens count toward `maxTokens`. At `xhigh` or `max`, raise
+  `maxTokens` if you see "returned no text content (stop_reason: max_tokens)".
+
+## Usage and cost
+
+Every result includes the model that answered and the request's token
+counts, normalized across providers:
+
+```typescript
+const result = await refine.dylan("Hello world");
+// {
+//   text: "...",
+//   character: "Dylan G.",
+//   model: "claude-sonnet-5",
+//   usage: { inputTokens: 2770, outputTokens: 77 },
+// }
+```
+
+`outputTokens` includes any reasoning tokens the model spent before answering
+(see [Effort](#effort-anthropic-only)). `usage` is omitted if the provider
+doesn't report it.
+
 ## Characters
 
 ```typescript

package/dist/client.js

@@ -51,13 +51,17 @@ export function createDefiantJazz(initialOptions = {}) {
         }
         const characterName = CHARACTERS[characterKey];
         const { provider, client } = getClient();
-        const defaults = { model: config.model, maxTokens: config.maxTokens };
+        const effort = options?.effort ?? config.effort;
+        if (effort !== undefined && provider === "openai") {
+            throw new Error("effort is only supported with the Anthropic provider.");
+        }
+        const defaults = { model: config.model, maxTokens: config.maxTokens, effort: config.effort };
         const lore = options?.lore ?? config.lore ?? true;
         const systemPrompt = buildSystemPrompt(lore);
-        const resultText = provider === "anthropic"
+        const result = provider === "anthropic"
             ? await runAnthropic(client, characterName, text, systemPrompt, defaults, options)
             : await runOpenAi(client, characterName, text, systemPrompt, defaults, options);
-        return { text: resultText, character: characterName };
+        return { ...result, character: characterName };
     }
     const fn = ((text, character, options) => transform(text, character, options));
     fn.mark = (text, options) => transform(text, "mark", options);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { createDefiantJazz, type DefiantJazz } from "./client.js";
 import { CHARACTERS } from "./prompt.js";
-import type { CharacterKey, DefiantJazzOptions, RefineOptions, RefineResult } from "./types.js";
-export type { CharacterKey, DefiantJazzOptions, RefineOptions, RefineResult };
+import type { CharacterKey, DefiantJazzOptions, Effort, RefineOptions, RefineResult, TokenUsage } from "./types.js";
+export type { CharacterKey, DefiantJazzOptions, Effort, RefineOptions, RefineResult, TokenUsage, };
 export { CHARACTERS, createDefiantJazz };
 /**
  * Configure the default `refine` instance with an API key and optional

package/dist/providers/anthropic.d.ts

@@ -1,7 +1,8 @@
 import Anthropic from "@anthropic-ai/sdk";
-import type { RefineOptions } from "../types.js";
+import type { Effort, RefineOptions, RefineResult } from "../types.js";
 export declare function createAnthropicClient(apiKey: string): Anthropic;
 export declare function runAnthropic(client: Anthropic, characterName: string, text: string, systemPrompt: string, defaults: {
     model?: string;
     maxTokens?: number;
-}, options?: RefineOptions): Promise<string>;
+    effort?: Effort;
+}, options?: RefineOptions): Promise<Omit<RefineResult, "character">>;

package/dist/providers/anthropic.js

@@ -5,10 +5,12 @@ export function createAnthropicClient(apiKey) {
     return new Anthropic({ apiKey });
 }
 export async function runAnthropic(client, characterName, text, systemPrompt, defaults, options) {
+    const effort = options?.effort ?? defaults.effort;
     try {
         const response = await client.messages.create({
             model: options?.model ?? defaults.model ?? DEFAULT_MODEL,
             max_tokens: options?.maxTokens ?? defaults.maxTokens ?? DEFAULT_MAX_TOKENS,
+            ...(effort !== undefined && { output_config: { effort } }),
             system: systemPrompt,
             messages: [
                 {
@@ -21,7 +23,14 @@ export async function runAnthropic(client, characterName, text, systemPrompt, de
         if (!textBlock) {
             throw new Error(`Anthropic returned no text content (stop_reason: ${response.stop_reason})`);
         }
-        return textBlock.text;
+        return {
+            text: textBlock.text,
+            model: response.model,
+            usage: response.usage && {
+                inputTokens: response.usage.input_tokens,
+                outputTokens: response.usage.output_tokens,
+            },
+        };
     }
     catch (error) {
         if (error instanceof Anthropic.AuthenticationError) {

package/dist/providers/openai.d.ts

@@ -1,7 +1,7 @@
 import OpenAI from "openai";
-import type { RefineOptions } from "../types.js";
+import type { RefineOptions, RefineResult } from "../types.js";
 export declare function createOpenAiClient(apiKey: string): OpenAI;
 export declare function runOpenAi(client: OpenAI, characterName: string, text: string, systemPrompt: string, defaults: {
     model?: string;
     maxTokens?: number;
-}, options?: RefineOptions): Promise<string>;
+}, options?: RefineOptions): Promise<Omit<RefineResult, "character">>;

package/dist/providers/openai.js

@@ -20,5 +20,12 @@ export async function runOpenAi(client, characterName, text, systemPrompt, defau
     if (!content) {
         throw new Error("OpenAI returned no content.");
     }
-    return content;
+    return {
+        text: content,
+        model: completion.model,
+        usage: completion.usage && {
+            inputTokens: completion.usage.prompt_tokens,
+            outputTokens: completion.usage.completion_tokens,
+        },
+    };
 }

package/dist/types.d.ts

@@ -1,8 +1,20 @@
+import type Anthropic from "@anthropic-ai/sdk";
 export type CharacterKey = "mark" | "irving" | "dylan" | "milchick";
 export type Provider = "anthropic" | "openai";
+/** Anthropic effort level, taken from the SDK so new levels arrive with SDK updates. */
+export type Effort = NonNullable<Anthropic.OutputConfig["effort"]>;
+export interface TokenUsage {
+    inputTokens: number;
+    /** Includes any reasoning tokens the model spent before answering. */
+    outputTokens: number;
+}
 export interface RefineResult {
     text: string;
     character: string;
+    /** The model that answered, as reported by the provider. */
+    model: string;
+    /** Token counts for this request, when the provider reports them. */
+    usage?: TokenUsage;
 }
 export interface DefiantJazzOptions {
     /** Explicit provider. Defaults to whichever API key is set (Anthropic first). */
@@ -10,6 +22,12 @@ export interface DefiantJazzOptions {
     apiKey?: string;
     model?: string;
     maxTokens?: number;
+    /**
+     * How much the model reasons before answering (Anthropic only). Lower is
+     * cheaper and faster. Leave unset to use the model's own default, which
+     * varies by model. Setting it with the OpenAI provider throws.
+     */
+    effort?: Effort;
     /**
      * Whether characters reach for Lumon/Severance vocabulary (the break room,
      * waffle parties, Kier, innie/outie, etc.) when a quote's situation calls
@@ -21,6 +39,11 @@ export interface DefiantJazzOptions {
 export interface RefineOptions {
     model?: string;
     maxTokens?: number;
+    /**
+     * How much the model reasons before answering (Anthropic only). Overrides
+     * the instance-level setting. Leave unset to use the model's own default.
+     */
+    effort?: Effort;
     signal?: AbortSignal;
     /**
      * Whether this call reaches for Lumon/Severance vocabulary. Overrides the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "defiant-jazz",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Transform quotes into Severance character voices using Claude or OpenAI",
   "license": "MIT",
   "author": "pelikenjones",