@sohqureshi/tokenwise 1.0.9 → 1.0.10

package/README.md

@@ -147,9 +147,25 @@ toNatural({
     }
   }
 });
-// policy: holder name Carlos Rivera, policy number HLT-2048, claim: status under review, requested amount 64000.
+// Carlos Rivera has policy HLT-2048. The claim is under review for 64,000.
 ```
 
+`toNatural()` uses semantic templates when the field relationships are
+unambiguous (for example, a policy holder, policy number, and claim). Unknown
+JSON shapes use a conservative key-value fallback so the formatter does not
+invent relationships or facts. For dynamic entity-shaped objects, it can
+recognize common subject fields such as `name`, `title`, `label`, `displayName`,
+`entityName`, `fullName`, `userName`, `customerName`, `ownerName`,
+`accountName`, `companyName`, `organizationName`, `teamName`, `projectName`,
+`productName`, `serviceName`, `resourceName`, `deviceName`, `patientName`,
+`taskName`, and `eventName`. These can be paired with state fields such as
+`status`, `state`, `condition`, `stage`, `role`, `type`, `category`, `priority`,
+`phase`, `mode`, `availability`, `outcome`, `result`, `health`, `progress`,
+`visibility`, `access`, `membership`, `sentiment`, and `severity`.
+Matching is case-insensitive and also supports keys that contain these
+concepts, such as `patientName`, `orderStatus`, `currentPhase`, or
+`incidentSeverity`.
+
 ### `toTOON()`
 
 Converts JSON into a compact TOON-like text format. Arrays of objects become table-style rows.
@@ -220,14 +236,27 @@ used by `tiktoken`.
 
 ## Release Notes
 
+### v1.0.10 — 2026-09-13
+
+- Add conservative contains-based semantic matching for dynamic subject and state keys, including fields such as `patientName`, `orderStatus`, and `incidentSeverity`.
+- Expand `toNatural()` regression coverage for dynamic entities, nested objects, arrays, metadata filtering, and alternate subject fields.
+- Update the browser demo to use the v1.0.10 CDN package.
+
 ### v1.0.8 — 2026-09-06
 
 - Expose exact tokenizer metadata when available (model + encoding), and fall back to a clear, model-aware estimator in browser demos.
 - Demo updated to show selected model and expected encoding when the exact tokenizer (tiktoken) is not available in-browser.
 - Updated analyze() to surface tokenizer encoding in analysis output so the demo shows "Estimator: model=gpt-4 expected_encoding=cl100k_base" even when using the heuristic fallback.
-- Misc: build artifacts updated and docs demo import bumped to v1.0.7 CDN bundle.
+- Misc: build artifacts updated.
+
+### v1.0.9 — 2026-09-13
 
-If you want the browser demo to display truly exact token counts, run the demo against a small Node endpoint (or local server) that has tiktoken installed and uses analyze(..., { exact: true }). The estimator will display the real tokenizer encoding when tiktoken is present.
+- Use `tiktoken` model-aware token counts by default in `estimateTokens()` and `analyze()`.
+- Keep the four-characters-per-token estimate available with `exact: false`.
+- Correctly identify `o200k_base` for modern OpenAI models such as `gpt-4o`, `gpt-4.1`, `o1`, and `o3`.
+- Update the browser demo to use the v1.0.9 CDN package.
+- Make demo analysis actionable by showing signed token and character changes, the selected transformation, and an explanation of whether the result is cheaper or larger.
+- Rename the demo's input-only Analyze view to Inspect, showing input size and structure without applying a transformation.
 
 ---
 

package/dist/chunk-BN3L7TUV.js

@@ -0,0 +1,241 @@
+// src/core/natural.ts
+function toNatural(data, depth = 0) {
+  if (data === null || data === void 0) return "nothing";
+  if (typeof data === "string") return data;
+  if (typeof data === "number") return String(data);
+  if (typeof data === "boolean") return data ? "yes" : "no";
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "empty list";
+    if (data.every(isPlainObject)) {
+      return data.map((item, index) => `${index + 1}. ${stripTrailingPeriod(toNatural(item, depth + 1))}.`).join(" ");
+    }
+    const items = data.map((item) => toNatural(item, depth + 1));
+    return joinNaturalList(items);
+  }
+  if (typeof data === "object") {
+    return buildContextualStory(data, depth);
+  }
+  return String(data);
+}
+function buildContextualStory(obj, depth = 0) {
+  const semanticStory = buildSemanticStory(obj);
+  if (semanticStory) return semanticStory;
+  const nestedEntity = Object.values(obj).find((value) => {
+    return isPlainObject(value) && buildSemanticStory(value) !== null;
+  });
+  if (nestedEntity) {
+    const nestedStory = buildSemanticStory(nestedEntity);
+    if (nestedStory) return nestedStory;
+  }
+  let name = obj.name || obj.userName || obj.user;
+  if (typeof name === "object" && name !== null && name.name) {
+    name = name.name;
+  }
+  const entries = Object.entries(obj).filter(([key]) => {
+    return !["id", "timestamp", "apiKey"].includes(key);
+  });
+  if (entries.length === 0) return "";
+  let story = name && typeof name === "string" ? `User ${name}` : "";
+  const clauses = entries.map(([key, value]) => {
+    if (key === "user" && name && typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const userProps = Object.entries(value).filter(([k]) => !["id", "name", "timestamp", "apiKey"].includes(k)).map(([k, v]) => formatPropertyClause(k, v, depth + 1)).filter((c) => c !== null && c !== "").join(", ");
+      return userProps ? `(${userProps})` : null;
+    }
+    return formatPropertyClause(key, value, depth);
+  }).filter((c) => c !== null && c !== "");
+  if (clauses.length === 0) return story;
+  if (story) {
+    story += " " + clauses.join(", ");
+  } else {
+    story = clauses.join(", ");
+  }
+  return story + ".";
+}
+function buildSemanticStory(obj) {
+  if (typeof obj.holderName === "string" && typeof obj.policyNumber === "string") {
+    const subject2 = `${obj.holderName} has policy ${obj.policyNumber}`;
+    const details = [
+      typeof obj.planType === "string" ? `a ${obj.planType} plan` : null,
+      typeof obj.premiumAmount === "number" ? `with a premium of ${formatNumber(obj.premiumAmount)}` : null
+    ].filter((value) => value !== null);
+    const sentences = [`${subject2}${details.length ? `, ${details.join(", ")}` : ""}.`];
+    if (isPlainObject(obj.claim)) {
+      const claim = describeClaim(obj.claim);
+      if (claim) sentences.push(claim);
+    }
+    if (Array.isArray(obj.dependents) && obj.dependents.length > 0) {
+      sentences.push(`${obj.holderName}'s dependents are ${joinNaturalList(obj.dependents.map(String))}.`);
+    }
+    return sentences.join(" ");
+  }
+  const subject = findSubject(obj);
+  const stateEntry = findSemanticEntry(obj, [
+    "status",
+    "state",
+    "condition",
+    "stage",
+    "role",
+    "type",
+    "category",
+    "classification",
+    "priority",
+    "phase",
+    "mode",
+    "availability",
+    "outcome",
+    "result",
+    "health",
+    "progress",
+    "visibility",
+    "access",
+    "membership",
+    "sentiment",
+    "severity"
+  ]);
+  if (subject && stateEntry && typeof stateEntry[1] === "string") {
+    const details = Object.entries(obj).filter(([key, value]) => key !== stateEntry[0] && key !== subject.key && shouldDescribeSemantically(key, value)).map(([key, value]) => `${camelToWords(key)} ${formatSemanticValue(value)}`);
+    return `${subject.value} is ${stateEntry[1]}${details.length ? ` and has ${details.join(", ")}` : ""}.`;
+  }
+  return null;
+}
+function findSubject(obj) {
+  const subjectKeys = [
+    "name",
+    "title",
+    "label",
+    "displayName",
+    "entityName",
+    "fullName",
+    "userName",
+    "username",
+    "personName",
+    "customerName",
+    "clientName",
+    "ownerName",
+    "accountName",
+    "companyName",
+    "organizationName",
+    "teamName",
+    "departmentName",
+    "projectName",
+    "productName",
+    "serviceName",
+    "resourceName",
+    "fileName",
+    "deviceName",
+    "hostName",
+    "applicationName",
+    "appName",
+    "taskName",
+    "eventName",
+    "itemName",
+    "orderName",
+    "patientName",
+    "employeeName"
+  ];
+  const entries = Object.entries(obj);
+  for (const key of subjectKeys) {
+    if (typeof obj[key] === "string" && obj[key].trim()) {
+      return { key, value: obj[key].trim() };
+    }
+  }
+  const nameEntry = entries.find(([key, value]) => {
+    return key.toLowerCase().includes("name") && typeof value === "string" && value.trim().length > 0;
+  });
+  if (nameEntry) {
+    return { key: nameEntry[0], value: nameEntry[1].trim() };
+  }
+  return null;
+}
+function findSemanticEntry(obj, keys) {
+  const entries = Object.entries(obj);
+  const exactEntry = entries.find(([key]) => keys.includes(key));
+  if (exactEntry) return exactEntry;
+  return entries.find(([key]) => {
+    const normalizedKey = key.toLowerCase();
+    return keys.some((semanticKey) => normalizedKey.includes(semanticKey.toLowerCase()));
+  }) ?? null;
+}
+function shouldDescribeSemantically(key, value) {
+  return (typeof value === "string" || typeof value === "number" || typeof value === "boolean") && !["id", "timestamp", "createdAt", "updatedAt", "apiKey", "debug"].includes(key);
+}
+function formatSemanticValue(value) {
+  if (typeof value === "number") return formatNumber(value);
+  if (typeof value === "boolean") return value ? "enabled" : "disabled";
+  return String(value);
+}
+function describeClaim(claim) {
+  const parts = [];
+  if (typeof claim.status === "string") parts.push(`The claim is ${claim.status}`);
+  if (typeof claim.requestedAmount === "number") {
+    parts.push(`for ${formatNumber(claim.requestedAmount)}`);
+  }
+  if (typeof claim.claimNumber === "string") {
+    parts.push(`(reference ${claim.claimNumber})`);
+  }
+  return parts.length ? `${parts.join(" ")}.` : null;
+}
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(value);
+}
+function formatPropertyClause(key, value, depth) {
+  const naturalKey = camelToWords(key);
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    if (["internal", "metadata", "debug"].includes(key)) {
+      return null;
+    }
+    const nested = Object.entries(value).filter(([k]) => !["id", "timestamp", "apiKey", "createdAt", "updatedAt"].includes(k)).map(([k, v]) => {
+      if (typeof v === "object" && v !== null) {
+        return formatPropertyClause(k, v, depth + 1);
+      }
+      const propValue = toNatural(v, depth + 1);
+      if (propValue === "yes" || propValue === "no") {
+        return `${camelToWords(k)} ${propValue === "yes" ? "enabled" : "disabled"}`;
+      }
+      return `${camelToWords(k)} ${propValue}`;
+    }).filter((c) => c && c.trim()).join(", ");
+    if (!nested) return null;
+    return `${naturalKey}: ${nested}`;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    if (["skills", "hobbies", "interests", "tags", "languages", "items"].includes(key)) {
+      const items2 = value.map((item) => {
+        const str = String(item);
+        return str.charAt(0).toUpperCase() + str.slice(1);
+      });
+      return `Having ${joinNaturalList(items2)}`;
+    }
+    const items = joinNaturalList(value.map((item) => toNatural(item, depth + 1)));
+    return `${naturalKey}: ${items}`;
+  }
+  const naturalValue = toNatural(value, depth + 1);
+  if (naturalValue === "yes") return `${naturalKey} enabled`;
+  if (naturalValue === "no") return `${naturalKey} disabled`;
+  if (key === "theme") return `prefers the ${naturalValue} ${key}`;
+  if (key === "age") return `age: ${naturalValue}`;
+  if (key === "email") return `email: ${naturalValue}`;
+  if (key === "city") return `address: ${naturalValue}`;
+  if (key === "debug" && naturalValue === "yes") return `debug enabled`;
+  return `${naturalKey}: ${naturalValue}`;
+}
+function camelToWords(str) {
+  return str.replace(/([A-Z])/g, " $1").toLowerCase().trim();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function joinNaturalList(items) {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  const lastItem = items[items.length - 1];
+  return `${items.slice(0, -1).join(", ")} and ${lastItem}`;
+}
+function stripTrailingPeriod(value) {
+  return value.replace(/\.+$/, "");
+}
+
+export {
+  toNatural
+};

package/dist/{chunk-QHCUNOUH.js → chunk-FBJ3DHS6.js}

@@ -12,7 +12,7 @@ import {
 } from "./chunk-L7BC62MT.js";
 import {
   toNatural
-} from "./chunk-D4CFTFM3.js";
+} from "./chunk-BN3L7TUV.js";
 import {
   prune
 } from "./chunk-ZD536GZF.js";

package/dist/cli.cjs

@@ -285,6 +285,15 @@ function toNatural(data, depth = 0) {
   return String(data);
 }
 function buildContextualStory(obj, depth = 0) {
+  const semanticStory = buildSemanticStory(obj);
+  if (semanticStory) return semanticStory;
+  const nestedEntity = Object.values(obj).find((value) => {
+    return isPlainObject2(value) && buildSemanticStory(value) !== null;
+  });
+  if (nestedEntity) {
+    const nestedStory = buildSemanticStory(nestedEntity);
+    if (nestedStory) return nestedStory;
+  }
   let name = obj.name || obj.userName || obj.user;
   if (typeof name === "object" && name !== null && name.name) {
     name = name.name;
@@ -309,6 +318,133 @@ function buildContextualStory(obj, depth = 0) {
   }
   return story + ".";
 }
+function buildSemanticStory(obj) {
+  if (typeof obj.holderName === "string" && typeof obj.policyNumber === "string") {
+    const subject2 = `${obj.holderName} has policy ${obj.policyNumber}`;
+    const details = [
+      typeof obj.planType === "string" ? `a ${obj.planType} plan` : null,
+      typeof obj.premiumAmount === "number" ? `with a premium of ${formatNumber(obj.premiumAmount)}` : null
+    ].filter((value) => value !== null);
+    const sentences = [`${subject2}${details.length ? `, ${details.join(", ")}` : ""}.`];
+    if (isPlainObject2(obj.claim)) {
+      const claim = describeClaim(obj.claim);
+      if (claim) sentences.push(claim);
+    }
+    if (Array.isArray(obj.dependents) && obj.dependents.length > 0) {
+      sentences.push(`${obj.holderName}'s dependents are ${joinNaturalList(obj.dependents.map(String))}.`);
+    }
+    return sentences.join(" ");
+  }
+  const subject = findSubject(obj);
+  const stateEntry = findSemanticEntry(obj, [
+    "status",
+    "state",
+    "condition",
+    "stage",
+    "role",
+    "type",
+    "category",
+    "classification",
+    "priority",
+    "phase",
+    "mode",
+    "availability",
+    "outcome",
+    "result",
+    "health",
+    "progress",
+    "visibility",
+    "access",
+    "membership",
+    "sentiment",
+    "severity"
+  ]);
+  if (subject && stateEntry && typeof stateEntry[1] === "string") {
+    const details = Object.entries(obj).filter(([key, value]) => key !== stateEntry[0] && key !== subject.key && shouldDescribeSemantically(key, value)).map(([key, value]) => `${camelToWords(key)} ${formatSemanticValue(value)}`);
+    return `${subject.value} is ${stateEntry[1]}${details.length ? ` and has ${details.join(", ")}` : ""}.`;
+  }
+  return null;
+}
+function findSubject(obj) {
+  const subjectKeys = [
+    "name",
+    "title",
+    "label",
+    "displayName",
+    "entityName",
+    "fullName",
+    "userName",
+    "username",
+    "personName",
+    "customerName",
+    "clientName",
+    "ownerName",
+    "accountName",
+    "companyName",
+    "organizationName",
+    "teamName",
+    "departmentName",
+    "projectName",
+    "productName",
+    "serviceName",
+    "resourceName",
+    "fileName",
+    "deviceName",
+    "hostName",
+    "applicationName",
+    "appName",
+    "taskName",
+    "eventName",
+    "itemName",
+    "orderName",
+    "patientName",
+    "employeeName"
+  ];
+  const entries = Object.entries(obj);
+  for (const key of subjectKeys) {
+    if (typeof obj[key] === "string" && obj[key].trim()) {
+      return { key, value: obj[key].trim() };
+    }
+  }
+  const nameEntry = entries.find(([key, value]) => {
+    return key.toLowerCase().includes("name") && typeof value === "string" && value.trim().length > 0;
+  });
+  if (nameEntry) {
+    return { key: nameEntry[0], value: nameEntry[1].trim() };
+  }
+  return null;
+}
+function findSemanticEntry(obj, keys) {
+  const entries = Object.entries(obj);
+  const exactEntry = entries.find(([key]) => keys.includes(key));
+  if (exactEntry) return exactEntry;
+  return entries.find(([key]) => {
+    const normalizedKey = key.toLowerCase();
+    return keys.some((semanticKey) => normalizedKey.includes(semanticKey.toLowerCase()));
+  }) ?? null;
+}
+function shouldDescribeSemantically(key, value) {
+  return (typeof value === "string" || typeof value === "number" || typeof value === "boolean") && !["id", "timestamp", "createdAt", "updatedAt", "apiKey", "debug"].includes(key);
+}
+function formatSemanticValue(value) {
+  if (typeof value === "number") return formatNumber(value);
+  if (typeof value === "boolean") return value ? "enabled" : "disabled";
+  return String(value);
+}
+function describeClaim(claim) {
+  const parts = [];
+  if (typeof claim.status === "string") parts.push(`The claim is ${claim.status}`);
+  if (typeof claim.requestedAmount === "number") {
+    parts.push(`for ${formatNumber(claim.requestedAmount)}`);
+  }
+  if (typeof claim.claimNumber === "string") {
+    parts.push(`(reference ${claim.claimNumber})`);
+  }
+  return parts.length ? `${parts.join(" ")}.` : null;
+}
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(value);
+}
 function formatPropertyClause(key, value, depth) {
   const naturalKey = camelToWords(key);
   if (typeof value === "object" && value !== null && !Array.isArray(value)) {

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   AIChain
-} from "./chunk-QHCUNOUH.js";
+} from "./chunk-FBJ3DHS6.js";
 import "./chunk-2TDVL6BJ.js";
 import "./chunk-6VRLDRJK.js";
 import "./chunk-XE36GLJP.js";
 import "./chunk-L7BC62MT.js";
-import "./chunk-D4CFTFM3.js";
+import "./chunk-BN3L7TUV.js";
 import "./chunk-ZD536GZF.js";
 import "./chunk-L3HY6AWL.js";
 

package/dist/core/natural.cjs

@@ -42,6 +42,15 @@ function toNatural(data, depth = 0) {
   return String(data);
 }
 function buildContextualStory(obj, depth = 0) {
+  const semanticStory = buildSemanticStory(obj);
+  if (semanticStory) return semanticStory;
+  const nestedEntity = Object.values(obj).find((value) => {
+    return isPlainObject(value) && buildSemanticStory(value) !== null;
+  });
+  if (nestedEntity) {
+    const nestedStory = buildSemanticStory(nestedEntity);
+    if (nestedStory) return nestedStory;
+  }
   let name = obj.name || obj.userName || obj.user;
   if (typeof name === "object" && name !== null && name.name) {
     name = name.name;
@@ -66,6 +75,133 @@ function buildContextualStory(obj, depth = 0) {
   }
   return story + ".";
 }
+function buildSemanticStory(obj) {
+  if (typeof obj.holderName === "string" && typeof obj.policyNumber === "string") {
+    const subject2 = `${obj.holderName} has policy ${obj.policyNumber}`;
+    const details = [
+      typeof obj.planType === "string" ? `a ${obj.planType} plan` : null,
+      typeof obj.premiumAmount === "number" ? `with a premium of ${formatNumber(obj.premiumAmount)}` : null
+    ].filter((value) => value !== null);
+    const sentences = [`${subject2}${details.length ? `, ${details.join(", ")}` : ""}.`];
+    if (isPlainObject(obj.claim)) {
+      const claim = describeClaim(obj.claim);
+      if (claim) sentences.push(claim);
+    }
+    if (Array.isArray(obj.dependents) && obj.dependents.length > 0) {
+      sentences.push(`${obj.holderName}'s dependents are ${joinNaturalList(obj.dependents.map(String))}.`);
+    }
+    return sentences.join(" ");
+  }
+  const subject = findSubject(obj);
+  const stateEntry = findSemanticEntry(obj, [
+    "status",
+    "state",
+    "condition",
+    "stage",
+    "role",
+    "type",
+    "category",
+    "classification",
+    "priority",
+    "phase",
+    "mode",
+    "availability",
+    "outcome",
+    "result",
+    "health",
+    "progress",
+    "visibility",
+    "access",
+    "membership",
+    "sentiment",
+    "severity"
+  ]);
+  if (subject && stateEntry && typeof stateEntry[1] === "string") {
+    const details = Object.entries(obj).filter(([key, value]) => key !== stateEntry[0] && key !== subject.key && shouldDescribeSemantically(key, value)).map(([key, value]) => `${camelToWords(key)} ${formatSemanticValue(value)}`);
+    return `${subject.value} is ${stateEntry[1]}${details.length ? ` and has ${details.join(", ")}` : ""}.`;
+  }
+  return null;
+}
+function findSubject(obj) {
+  const subjectKeys = [
+    "name",
+    "title",
+    "label",
+    "displayName",
+    "entityName",
+    "fullName",
+    "userName",
+    "username",
+    "personName",
+    "customerName",
+    "clientName",
+    "ownerName",
+    "accountName",
+    "companyName",
+    "organizationName",
+    "teamName",
+    "departmentName",
+    "projectName",
+    "productName",
+    "serviceName",
+    "resourceName",
+    "fileName",
+    "deviceName",
+    "hostName",
+    "applicationName",
+    "appName",
+    "taskName",
+    "eventName",
+    "itemName",
+    "orderName",
+    "patientName",
+    "employeeName"
+  ];
+  const entries = Object.entries(obj);
+  for (const key of subjectKeys) {
+    if (typeof obj[key] === "string" && obj[key].trim()) {
+      return { key, value: obj[key].trim() };
+    }
+  }
+  const nameEntry = entries.find(([key, value]) => {
+    return key.toLowerCase().includes("name") && typeof value === "string" && value.trim().length > 0;
+  });
+  if (nameEntry) {
+    return { key: nameEntry[0], value: nameEntry[1].trim() };
+  }
+  return null;
+}
+function findSemanticEntry(obj, keys) {
+  const entries = Object.entries(obj);
+  const exactEntry = entries.find(([key]) => keys.includes(key));
+  if (exactEntry) return exactEntry;
+  return entries.find(([key]) => {
+    const normalizedKey = key.toLowerCase();
+    return keys.some((semanticKey) => normalizedKey.includes(semanticKey.toLowerCase()));
+  }) ?? null;
+}
+function shouldDescribeSemantically(key, value) {
+  return (typeof value === "string" || typeof value === "number" || typeof value === "boolean") && !["id", "timestamp", "createdAt", "updatedAt", "apiKey", "debug"].includes(key);
+}
+function formatSemanticValue(value) {
+  if (typeof value === "number") return formatNumber(value);
+  if (typeof value === "boolean") return value ? "enabled" : "disabled";
+  return String(value);
+}
+function describeClaim(claim) {
+  const parts = [];
+  if (typeof claim.status === "string") parts.push(`The claim is ${claim.status}`);
+  if (typeof claim.requestedAmount === "number") {
+    parts.push(`for ${formatNumber(claim.requestedAmount)}`);
+  }
+  if (typeof claim.claimNumber === "string") {
+    parts.push(`(reference ${claim.claimNumber})`);
+  }
+  return parts.length ? `${parts.join(" ")}.` : null;
+}
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(value);
+}
 function formatPropertyClause(key, value, depth) {
   const naturalKey = camelToWords(key);
   if (typeof value === "object" && value !== null && !Array.isArray(value)) {

package/dist/core/natural.js

@@ -1,6 +1,6 @@
 import {
   toNatural
-} from "../chunk-D4CFTFM3.js";
+} from "../chunk-BN3L7TUV.js";
 export {
   toNatural
 };

package/dist/index.cjs

@@ -294,6 +294,15 @@ function toNatural(data, depth = 0) {
   return String(data);
 }
 function buildContextualStory(obj, depth = 0) {
+  const semanticStory = buildSemanticStory(obj);
+  if (semanticStory) return semanticStory;
+  const nestedEntity = Object.values(obj).find((value) => {
+    return isPlainObject2(value) && buildSemanticStory(value) !== null;
+  });
+  if (nestedEntity) {
+    const nestedStory = buildSemanticStory(nestedEntity);
+    if (nestedStory) return nestedStory;
+  }
   let name = obj.name || obj.userName || obj.user;
   if (typeof name === "object" && name !== null && name.name) {
     name = name.name;
@@ -318,6 +327,133 @@ function buildContextualStory(obj, depth = 0) {
   }
   return story + ".";
 }
+function buildSemanticStory(obj) {
+  if (typeof obj.holderName === "string" && typeof obj.policyNumber === "string") {
+    const subject2 = `${obj.holderName} has policy ${obj.policyNumber}`;
+    const details = [
+      typeof obj.planType === "string" ? `a ${obj.planType} plan` : null,
+      typeof obj.premiumAmount === "number" ? `with a premium of ${formatNumber(obj.premiumAmount)}` : null
+    ].filter((value) => value !== null);
+    const sentences = [`${subject2}${details.length ? `, ${details.join(", ")}` : ""}.`];
+    if (isPlainObject2(obj.claim)) {
+      const claim = describeClaim(obj.claim);
+      if (claim) sentences.push(claim);
+    }
+    if (Array.isArray(obj.dependents) && obj.dependents.length > 0) {
+      sentences.push(`${obj.holderName}'s dependents are ${joinNaturalList(obj.dependents.map(String))}.`);
+    }
+    return sentences.join(" ");
+  }
+  const subject = findSubject(obj);
+  const stateEntry = findSemanticEntry(obj, [
+    "status",
+    "state",
+    "condition",
+    "stage",
+    "role",
+    "type",
+    "category",
+    "classification",
+    "priority",
+    "phase",
+    "mode",
+    "availability",
+    "outcome",
+    "result",
+    "health",
+    "progress",
+    "visibility",
+    "access",
+    "membership",
+    "sentiment",
+    "severity"
+  ]);
+  if (subject && stateEntry && typeof stateEntry[1] === "string") {
+    const details = Object.entries(obj).filter(([key, value]) => key !== stateEntry[0] && key !== subject.key && shouldDescribeSemantically(key, value)).map(([key, value]) => `${camelToWords(key)} ${formatSemanticValue(value)}`);
+    return `${subject.value} is ${stateEntry[1]}${details.length ? ` and has ${details.join(", ")}` : ""}.`;
+  }
+  return null;
+}
+function findSubject(obj) {
+  const subjectKeys = [
+    "name",
+    "title",
+    "label",
+    "displayName",
+    "entityName",
+    "fullName",
+    "userName",
+    "username",
+    "personName",
+    "customerName",
+    "clientName",
+    "ownerName",
+    "accountName",
+    "companyName",
+    "organizationName",
+    "teamName",
+    "departmentName",
+    "projectName",
+    "productName",
+    "serviceName",
+    "resourceName",
+    "fileName",
+    "deviceName",
+    "hostName",
+    "applicationName",
+    "appName",
+    "taskName",
+    "eventName",
+    "itemName",
+    "orderName",
+    "patientName",
+    "employeeName"
+  ];
+  const entries = Object.entries(obj);
+  for (const key of subjectKeys) {
+    if (typeof obj[key] === "string" && obj[key].trim()) {
+      return { key, value: obj[key].trim() };
+    }
+  }
+  const nameEntry = entries.find(([key, value]) => {
+    return key.toLowerCase().includes("name") && typeof value === "string" && value.trim().length > 0;
+  });
+  if (nameEntry) {
+    return { key: nameEntry[0], value: nameEntry[1].trim() };
+  }
+  return null;
+}
+function findSemanticEntry(obj, keys) {
+  const entries = Object.entries(obj);
+  const exactEntry = entries.find(([key]) => keys.includes(key));
+  if (exactEntry) return exactEntry;
+  return entries.find(([key]) => {
+    const normalizedKey = key.toLowerCase();
+    return keys.some((semanticKey) => normalizedKey.includes(semanticKey.toLowerCase()));
+  }) ?? null;
+}
+function shouldDescribeSemantically(key, value) {
+  return (typeof value === "string" || typeof value === "number" || typeof value === "boolean") && !["id", "timestamp", "createdAt", "updatedAt", "apiKey", "debug"].includes(key);
+}
+function formatSemanticValue(value) {
+  if (typeof value === "number") return formatNumber(value);
+  if (typeof value === "boolean") return value ? "enabled" : "disabled";
+  return String(value);
+}
+function describeClaim(claim) {
+  const parts = [];
+  if (typeof claim.status === "string") parts.push(`The claim is ${claim.status}`);
+  if (typeof claim.requestedAmount === "number") {
+    parts.push(`for ${formatNumber(claim.requestedAmount)}`);
+  }
+  if (typeof claim.claimNumber === "string") {
+    parts.push(`(reference ${claim.claimNumber})`);
+  }
+  return parts.length ? `${parts.join(" ")}.` : null;
+}
+function formatNumber(value) {
+  return new Intl.NumberFormat("en-US").format(value);
+}
 function formatPropertyClause(key, value, depth) {
   const naturalKey = camelToWords(key);
   if (typeof value === "object" && value !== null && !Array.isArray(value)) {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   AIChain
-} from "./chunk-QHCUNOUH.js";
+} from "./chunk-FBJ3DHS6.js";
 import {
   analyze
 } from "./chunk-2TDVL6BJ.js";
@@ -15,7 +15,7 @@ import {
 } from "./chunk-L7BC62MT.js";
 import {
   toNatural
-} from "./chunk-D4CFTFM3.js";
+} from "./chunk-BN3L7TUV.js";
 import {
   prune
 } from "./chunk-ZD536GZF.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sohqureshi/tokenwise",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Optimize JSON data for AI by reducing token usage",
   "repository": {
     "type": "git",

package/dist/chunk-D4CFTFM3.js

@@ -1,105 +0,0 @@
-// src/core/natural.ts
-function toNatural(data, depth = 0) {
-  if (data === null || data === void 0) return "nothing";
-  if (typeof data === "string") return data;
-  if (typeof data === "number") return String(data);
-  if (typeof data === "boolean") return data ? "yes" : "no";
-  if (Array.isArray(data)) {
-    if (data.length === 0) return "empty list";
-    if (data.every(isPlainObject)) {
-      return data.map((item, index) => `${index + 1}. ${stripTrailingPeriod(toNatural(item, depth + 1))}.`).join(" ");
-    }
-    const items = data.map((item) => toNatural(item, depth + 1));
-    return joinNaturalList(items);
-  }
-  if (typeof data === "object") {
-    return buildContextualStory(data, depth);
-  }
-  return String(data);
-}
-function buildContextualStory(obj, depth = 0) {
-  let name = obj.name || obj.userName || obj.user;
-  if (typeof name === "object" && name !== null && name.name) {
-    name = name.name;
-  }
-  const entries = Object.entries(obj).filter(([key]) => {
-    return !["id", "timestamp", "apiKey"].includes(key);
-  });
-  if (entries.length === 0) return "";
-  let story = name && typeof name === "string" ? `User ${name}` : "";
-  const clauses = entries.map(([key, value]) => {
-    if (key === "user" && name && typeof value === "object" && value !== null && !Array.isArray(value)) {
-      const userProps = Object.entries(value).filter(([k]) => !["id", "name", "timestamp", "apiKey"].includes(k)).map(([k, v]) => formatPropertyClause(k, v, depth + 1)).filter((c) => c !== null && c !== "").join(", ");
-      return userProps ? `(${userProps})` : null;
-    }
-    return formatPropertyClause(key, value, depth);
-  }).filter((c) => c !== null && c !== "");
-  if (clauses.length === 0) return story;
-  if (story) {
-    story += " " + clauses.join(", ");
-  } else {
-    story = clauses.join(", ");
-  }
-  return story + ".";
-}
-function formatPropertyClause(key, value, depth) {
-  const naturalKey = camelToWords(key);
-  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-    if (["internal", "metadata", "debug"].includes(key)) {
-      return null;
-    }
-    const nested = Object.entries(value).filter(([k]) => !["id", "timestamp", "apiKey", "createdAt", "updatedAt"].includes(k)).map(([k, v]) => {
-      if (typeof v === "object" && v !== null) {
-        return formatPropertyClause(k, v, depth + 1);
-      }
-      const propValue = toNatural(v, depth + 1);
-      if (propValue === "yes" || propValue === "no") {
-        return `${camelToWords(k)} ${propValue === "yes" ? "enabled" : "disabled"}`;
-      }
-      return `${camelToWords(k)} ${propValue}`;
-    }).filter((c) => c && c.trim()).join(", ");
-    if (!nested) return null;
-    return `${naturalKey}: ${nested}`;
-  }
-  if (Array.isArray(value)) {
-    if (value.length === 0) return null;
-    if (["skills", "hobbies", "interests", "tags", "languages", "items"].includes(key)) {
-      const items2 = value.map((item) => {
-        const str = String(item);
-        return str.charAt(0).toUpperCase() + str.slice(1);
-      });
-      return `Having ${joinNaturalList(items2)}`;
-    }
-    const items = joinNaturalList(value.map((item) => toNatural(item, depth + 1)));
-    return `${naturalKey}: ${items}`;
-  }
-  const naturalValue = toNatural(value, depth + 1);
-  if (naturalValue === "yes") return `${naturalKey} enabled`;
-  if (naturalValue === "no") return `${naturalKey} disabled`;
-  if (key === "theme") return `prefers the ${naturalValue} ${key}`;
-  if (key === "age") return `age: ${naturalValue}`;
-  if (key === "email") return `email: ${naturalValue}`;
-  if (key === "city") return `address: ${naturalValue}`;
-  if (key === "debug" && naturalValue === "yes") return `debug enabled`;
-  return `${naturalKey}: ${naturalValue}`;
-}
-function camelToWords(str) {
-  return str.replace(/([A-Z])/g, " $1").toLowerCase().trim();
-}
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function joinNaturalList(items) {
-  if (items.length === 0) return "";
-  if (items.length === 1) return items[0];
-  if (items.length === 2) return `${items[0]} and ${items[1]}`;
-  const lastItem = items[items.length - 1];
-  return `${items.slice(0, -1).join(", ")} and ${lastItem}`;
-}
-function stripTrailingPeriod(value) {
-  return value.replace(/\.+$/, "");
-}
-
-export {
-  toNatural
-};