defiant-jazz 0.6.2 → 0.8.0

package/README.md

@@ -28,15 +28,21 @@ await refine("Hello world", "dylan");
 ```
 
 Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your environment and you're done —
-whichever is present is used automatically (Anthropic first if both are set).
+whichever one is present is used. If both are set, the library won't pick for
+you; pass `provider` instead (see [Choosing a provider](#choosing-a-provider)).
 
 **Default models: `claude-sonnet-5` (Anthropic), `gpt-4o-mini` (OpenAI).**
 Sonnet 5 was chosen over Opus 5 after a head-to-head comparison found
 matching output quality at 40% of the cost — see
 [model-comparison.md](model-comparison.md) for the full writeup, including a
 documented regression on Haiku 4.5 that ruled it out as a default. Override
-with `model` on `createDefiantJazz()` or per call; see
-[Choosing a provider](#choosing-a-provider).
+with `model` on `createDefiantJazz()` or per call. The defaults are also
+exported, so you can check what a zero-config call will run:
+
+```typescript
+import { DEFAULT_MODELS } from 'defiant-jazz';
+// { anthropic: 'claude-sonnet-5', openai: 'gpt-4o-mini' }
+```
 
 ## Lore
 
@@ -91,7 +97,28 @@ await claude.dylan("Hello world");
 await gpt.dylan("Hello world");
 ```
 
-`refine` is a shared default instance using auto-detected credentials. Use
+How the provider is chosen:
+
+- `provider` set → that provider. Its key comes from `apiKey`, or from
+  `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` if `apiKey` is omitted.
+- `provider` omitted, exactly one env key set → that provider.
+- `provider` omitted, both env keys set → throws. The library never decides
+  whose account gets billed.
+- `apiKey` passed without `provider` → throws, so a key is never sent to the
+  wrong service.
+
+Only those two env var names are read. To use a key stored under a different
+name, read it yourself and pass it as `apiKey`:
+
+```typescript
+const gpt = createDefiantJazz({
+  provider: 'openai',
+  apiKey: process.env.MY_TEAM_OPENAI_KEY,
+});
+```
+
+`refine` is a shared default instance that follows the same rules; point it at
+a provider with `refine.configure({ provider: 'openai' })`. Use
 `createDefiantJazz()` whenever you need an isolated instance — a specific
 provider, different API keys per request, a non-default model, testing.
 
@@ -101,6 +128,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

@@ -12,14 +12,23 @@ function resolveProvider(options) {
         }
         return { provider: options.provider, apiKey };
     }
+    // No explicit provider. Only infer one when there's exactly one candidate;
+    // never guess between two, since that picks whose account gets billed.
     if (options.apiKey) {
-        return { provider: "anthropic", apiKey: options.apiKey };
+        throw new Error("apiKey requires provider so the key isn't sent to the wrong service. " +
+            "Pass { provider: 'anthropic' } or { provider: 'openai' } alongside it.");
     }
-    if (process.env.ANTHROPIC_API_KEY) {
-        return { provider: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY };
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (anthropicKey && openaiKey) {
+        throw new Error("Both ANTHROPIC_API_KEY and OPENAI_API_KEY are set. " +
+            "Pass { provider: 'anthropic' } or { provider: 'openai' } to choose.");
     }
-    if (process.env.OPENAI_API_KEY) {
-        return { provider: "openai", apiKey: process.env.OPENAI_API_KEY };
+    if (anthropicKey) {
+        return { provider: "anthropic", apiKey: anthropicKey };
+    }
+    if (openaiKey) {
+        return { provider: "openai", apiKey: openaiKey };
     }
     throw new Error("No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY " +
         "(or pass apiKey/provider to configure()/createDefiantJazz()).");
@@ -51,13 +60,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/defaults.d.ts

@@ -0,0 +1,7 @@
+import type { Provider } from "./types.js";
+/**
+ * The model each provider uses when `model` is not set. Exported so callers
+ * can see what a zero-config call will run (and be billed for) without
+ * reading the docs. See model-comparison.md for why Sonnet 5 is the default.
+ */
+export declare const DEFAULT_MODELS: Readonly<Record<Provider, string>>;

package/dist/defaults.js

@@ -0,0 +1,9 @@
+/**
+ * The model each provider uses when `model` is not set. Exported so callers
+ * can see what a zero-config call will run (and be billed for) without
+ * reading the docs. See model-comparison.md for why Sonnet 5 is the default.
+ */
+export const DEFAULT_MODELS = Object.freeze({
+    anthropic: "claude-sonnet-5",
+    openai: "gpt-4o-mini",
+});

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { createDefiantJazz, type DefiantJazz } from "./client.js";
+import { DEFAULT_MODELS } from "./defaults.js";
 import { CHARACTERS } from "./prompt.js";
-import type { CharacterKey, DefiantJazzOptions, RefineOptions, RefineResult } from "./types.js";
-export type { CharacterKey, DefiantJazzOptions, RefineOptions, RefineResult };
-export { CHARACTERS, createDefiantJazz };
+import type { CharacterKey, DefiantJazzOptions, Effort, RefineOptions, RefineResult, TokenUsage } from "./types.js";
+export type { CharacterKey, DefiantJazzOptions, Effort, RefineOptions, RefineResult, TokenUsage, };
+export { CHARACTERS, DEFAULT_MODELS, createDefiantJazz };
 /**
  * Configure the default `refine` instance with an API key and optional
  * model/provider overrides. Prefer `createDefiantJazz()` for an isolated

package/dist/index.js

@@ -1,6 +1,7 @@
 import { createDefiantJazz } from "./client.js";
+import { DEFAULT_MODELS } from "./defaults.js";
 import { CHARACTERS } from "./prompt.js";
-export { CHARACTERS, createDefiantJazz };
+export { CHARACTERS, DEFAULT_MODELS, createDefiantJazz };
 let defaultInstance = null;
 function getDefaultInstance() {
     if (!defaultInstance) {

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

@@ -1,14 +1,17 @@
 import Anthropic from "@anthropic-ai/sdk";
-const DEFAULT_MODEL = "claude-sonnet-5";
+import { DEFAULT_MODELS } from "../defaults.js";
+const DEFAULT_MODEL = DEFAULT_MODELS.anthropic;
 const DEFAULT_MAX_TOKENS = 4096;
 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 +24,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

@@ -1,5 +1,6 @@
 import OpenAI from "openai";
-const DEFAULT_MODEL = "gpt-4o-mini";
+import { DEFAULT_MODELS } from "../defaults.js";
+const DEFAULT_MODEL = DEFAULT_MODELS.openai;
 const DEFAULT_MAX_TOKENS = 4096;
 export function createOpenAiClient(apiKey) {
     return new OpenAI({ apiKey });
@@ -20,5 +21,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,15 +1,37 @@
+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). */
+    /**
+     * Which API to call. Optional only when exactly one of `ANTHROPIC_API_KEY`
+     * or `OPENAI_API_KEY` is set and `apiKey` is not passed; when the choice
+     * would be ambiguous, the library throws rather than guess.
+     */
     provider?: Provider;
     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 +43,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.8.0",
   "description": "Transform quotes into Severance character voices using Claude or OpenAI",
   "license": "MIT",
   "author": "pelikenjones",