promptopskit 0.9.0 → 0.9.2

package/README.md

@@ -5,17 +5,30 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 
-**Turn hardcoded AI prompts into versioned, tested application assets.**
+**Prompts are becoming production code. Manage them that way.**
 
-Your prompts are already in Git. PromptOpsKit makes them manageable.
+AI features often start with a few prompt strings. Then model settings, tools, provider quirks, context limits, environment overrides, tests, and customer-specific behavior start spreading across the codebase.
 
-Keep prompts, model settings, tools, input validation, shared instructions, environment overrides, and tests together in Markdown files that live in Git and ship with your app. Render provider-ready request bodies without giving up your SDK, gateway, auth, retries, routing, observability, or billing.
+PromptOpsKit is an open-source toolkit for turning hardcoded AI prompts into versioned, tested application assets. Keep prompts, model settings, tools, input validation, shared instructions, environment overrides, and tests together in Markdown files that live in Git and ship with your app.
+
+No hosted dashboard. No gateway required. No vendor lock-in. Render provider-ready request bodies while keeping your SDK, auth, routing, retries, observability, and billing.
 
 PromptOpsKit is not a prompt dashboard, LLM gateway, or hosted runtime service. It is the repo-native layer between scattered prompt strings and production AI calls.
 
+## Where this fits in the AI production stack
+
+PromptOpsKit handles the open-source prompt asset layer: prompts, model settings, tools, input rules, overrides, and tests in Git.
+
+As AI features grow, adjacent production concerns usually appear:
+
+- **Provider operations** — routing, caching, cost controls, customer attribution, and gateway reliability. See LLMAsAService.
+- **Customer usage and billing** — usage metering, entitlements, limits, alerts, and usage-based billing. See UsageTap.
+
+PromptOpsKit does not require either service. It keeps the prompt layer repo-native and transport-light so teams can adopt the rest of their AI production stack when they need it.
+
 ## Why PromptOpsKit?
 
-From scattered prompt glue:
+When prototypes become real product features, prompt glue is hard to review and easy to drift:
 
 - Prompt strings live inline in code
 - Model config and tools drift in separate files
@@ -23,7 +36,7 @@ From scattered prompt glue:
 - Environment logic hides in if/else branches
 - Testing is ad hoc and hard to review
 
-To one reviewable asset:
+PromptOpsKit turns that behavior into one reviewable asset:
 
 - Prompt, model, tools, and input rules live together
 - `includes` and `defaults.md` avoid copy-paste drift
@@ -279,7 +292,7 @@ cache:
     retention: 24h
 ```
 
-At render time, pass the caller-owned API key. PromptOpsKit calls `POST https://api.thetokencompany.com/v1/compress` directly with `fetch`; no TheTokenCompany SDK is required.
+At render time, pass the caller-owned API key. PromptOpsKit calls `POST https://api.thetokencompany.com/v1/compress` directly with `fetch`; no TheTokenCompany SDK is required. If credentials are unavailable or the backend call fails, PromptOpsKit preserves the original prompt text, returns a `POK057` warning in `warnings`, and reports zero token savings with matching input/output token counts. Library rendering does not log this fallback to the console.
 
 ```typescript
 const result = await kit.renderPrompt({

package/dist/{chunk-NS6OTKY2.js → chunk-6ICAKKV3.js}

@@ -1632,6 +1632,7 @@ async function applyPromptCompressionForRender(asset, runtime) {
       aggressiveness: theTokenCompanyConfig?.aggressiveness
     });
     promptTemplate = result.output;
+    warnings.push(...result.warnings ?? []);
     compression.push({
       provider: "thetokencompany",
       model,
@@ -1697,39 +1698,97 @@ function reportHeuristicCompressionWarnings2(warnings, compressionWarnings, scop
 async function compressWithTheTokenCompany(input, options) {
   const apiKey = options.apiKey ?? getEnv("THETOKENCOMPANY_API_KEY") ?? getEnv("TTC_API_KEY");
   if (!apiKey) {
-    throw new Error(
-      "TheTokenCompany compression is enabled, but no API key was provided. Pass theTokenCompany.apiKey to renderPrompt() or set THETOKENCOMPANY_API_KEY."
+    return createTheTokenCompanyFallback(
+      input,
+      "no API key was provided"
     );
   }
   const fetchImpl = options.fetch ?? globalThis.fetch;
   if (!fetchImpl) {
-    throw new Error("TheTokenCompany compression requires a runtime with fetch support.");
+    return createTheTokenCompanyFallback(
+      input,
+      "fetch is unavailable in this runtime"
+    );
   }
   const baseURL = (options.baseURL ?? THETOKENCOMPANY_DEFAULT_BASE_URL).replace(/\/+$/, "");
   const compressionSettings = options.aggressiveness === void 0 ? void 0 : { aggressiveness: options.aggressiveness };
-  const response = await fetchImpl(`${baseURL}/v1/compress`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${apiKey}`,
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({
-      model: options.model,
+  let response;
+  try {
+    response = await fetchImpl(`${baseURL}/v1/compress`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        model: options.model,
+        input,
+        ...compressionSettings ? { compression_settings: compressionSettings } : {}
+      })
+    });
+  } catch (error) {
+    return createTheTokenCompanyFallback(
       input,
-      ...compressionSettings ? { compression_settings: compressionSettings } : {}
-    })
-  });
+      `request failed: ${toErrorMessage(error)}`
+    );
+  }
   if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `TheTokenCompany compression failed with HTTP ${response.status}` + (body ? `: ${body}` : ".")
+    return createTheTokenCompanyFallback(
+      input,
+      `service returned HTTP ${response.status}`
+    );
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch (error) {
+    return createTheTokenCompanyFallback(
+      input,
+      `response body was not valid JSON: ${toErrorMessage(error)}`
     );
   }
-  const data = await response.json();
-  if (typeof data.output !== "string" || typeof data.output_tokens !== "number" || typeof data.input_tokens !== "number" || typeof data.tokens_saved !== "number" || typeof data.compression_ratio !== "number") {
-    throw new Error("TheTokenCompany compression returned an invalid response payload.");
+  const normalized = normalizeTheTokenCompanyCompressResponse(data);
+  if (!normalized) {
+    return createTheTokenCompanyFallback(
+      input,
+      "response payload was invalid"
+    );
   }
-  return data;
+  return normalized;
+}
+function createTheTokenCompanyFallback(input, reason) {
+  const tokens = estimateHeuristicTokens(input);
+  return {
+    output: input,
+    output_tokens: tokens,
+    input_tokens: tokens,
+    tokens_saved: 0,
+    compression_ratio: tokens === 0 ? 0 : 1,
+    warnings: [
+      `POK057: TheTokenCompany compression skipped; using uncompressed prompt with zero token savings (${reason}).`
+    ]
+  };
+}
+function toErrorMessage(error) {
+  return error instanceof Error && error.message ? error.message : "unknown error";
+}
+function normalizeTheTokenCompanyCompressResponse(data) {
+  if (typeof data.output !== "string" || typeof data.output_tokens !== "number") {
+    return void 0;
+  }
+  const inputTokens = typeof data.input_tokens === "number" ? data.input_tokens : data.original_input_tokens;
+  if (typeof inputTokens !== "number") {
+    return void 0;
+  }
+  const tokensSaved = typeof data.tokens_saved === "number" ? data.tokens_saved : inputTokens - data.output_tokens;
+  const compressionRatio = typeof data.compression_ratio === "number" ? data.compression_ratio : data.output_tokens === 0 ? 0 : inputTokens / data.output_tokens;
+  return {
+    output: data.output,
+    output_tokens: data.output_tokens,
+    input_tokens: inputTokens,
+    tokens_saved: tokensSaved,
+    compression_ratio: compressionRatio
+  };
 }
 function getEnv(name) {
   if (typeof process === "undefined") {
@@ -1838,4 +1897,4 @@ export {
   withPromptInputSupport,
   applyRawProviderBody
 };
-//# sourceMappingURL=chunk-NS6OTKY2.js.map
+//# sourceMappingURL=chunk-6ICAKKV3.js.map