brevit 0.1.2 → 0.1.3

package/README.md

@@ -213,7 +213,23 @@ const jsonString = '{"order": {"id": "o-456", "status": "SHIPPED"}}';
 
 // Brevit automatically detects JSON strings
 const optimized = await brevit.brevity(jsonString);
-// Output:
+// Output (with abbreviations enabled by default):
+// @o=order
+// @o.id:o-456
+// @o.status:SHIPPED
+```
+
+#### Example 1.2a: Abbreviations Disabled
+
+```javascript
+const brevitNoAbbr = new BrevitClient(new BrevitConfig({ 
+  jsonMode: JsonOptimizationMode.Flatten,
+  enableAbbreviations: false  // Disable abbreviations
+}));
+
+const jsonString = '{"order": {"id": "o-456", "status": "SHIPPED"}}';
+const optimized = await brevitNoAbbr.brevity(jsonString);
+// Output (without abbreviations):
 // order.id:o-456
 // order.status:SHIPPED
 ```
@@ -249,7 +265,54 @@ const complexData = {
 };
 
 const optimized = await brevit.brevity(complexData);
-// Output:
+// Output (with abbreviations enabled by default):
+// @c=context
+// @c.task:Our favorite hikes together
+// @c.location:Boulder
+// @c.season:spring_2025
+// friends[3]:ana,luis,sam
+// hikes[2]{companion,distanceKm,elevationGain,id,name,wasSunny}:
+// ana,7.5,320,1,Blue Lake Trail,true
+// luis,9.2,540,2,Ridge Overlook,false
+```
+
+#### Example 1.3a: Complex Data with Abbreviations Disabled
+
+```javascript
+const brevitNoAbbr = new BrevitClient(new BrevitConfig({ 
+  jsonMode: JsonOptimizationMode.Flatten,
+  enableAbbreviations: false  // Disable abbreviations
+}));
+
+const complexData = {
+  context: {
+    task: "Our favorite hikes together",
+    location: "Boulder",
+    season: "spring_2025"
+  },
+  friends: ["ana", "luis", "sam"],
+  hikes: [
+    {
+      id: 1,
+      name: "Blue Lake Trail",
+      distanceKm: 7.5,
+      elevationGain: 320,
+      companion: "ana",
+      wasSunny: true
+    },
+    {
+      id: 2,
+      name: "Ridge Overlook",
+      distanceKm: 9.2,
+      elevationGain: 540,
+      companion: "luis",
+      wasSunny: false
+    }
+  ]
+};
+
+const optimized = await brevitNoAbbr.brevity(complexData);
+// Output (without abbreviations):
 // context.task:Our favorite hikes together
 // context.location:Boulder
 // context.season:spring_2025
@@ -617,7 +680,9 @@ const config = new BrevitConfig({
   textMode: 'Clean',                        // Text optimization strategy
   imageMode: 'Ocr',                         // Image optimization strategy
   jsonPathsToKeep: [],                      // Paths to keep for Filter mode
-  longTextThreshold: 500                    // Character threshold for text optimization
+  longTextThreshold: 500,                   // Character threshold for text optimization
+  enableAbbreviations: true,                // Enable abbreviation feature (default: true)
+  abbreviationThreshold: 2                  // Minimum occurrences to create abbreviation (default: 2)
 });
 ```
 
@@ -670,6 +735,8 @@ const config: BrevitConfigOptions = {
   imageMode: ImageOptimizationMode.Ocr,
   jsonPathsToKeep: ['user.name', 'order.orderId'],
   longTextThreshold: 1000,
+  enableAbbreviations: true,         // Default: true
+  abbreviationThreshold: 2            // Default: 2
 };
 
 const client = new BrevitClient(new BrevitConfig(config));
@@ -879,12 +946,15 @@ Consider alternatives when:
 
 ### Token Reduction
 
-| Object Type | Original Tokens | Brevit Tokens | Reduction |
-|-------------|----------------|---------------|-----------|
-| Simple Object | 45 | 28 | 38% |
-| Complex Object | 234 | 127 | 46% |
-| Nested Arrays | 156 | 89 | 43% |
-| API Response | 312 | 178 | 43% |
+| Object Type | Original Tokens | Brevit (No Abbr) | Brevit (With Abbr) | Total Reduction |
+|-------------|----------------|------------------|-------------------|-----------------|
+| Simple Object | 45 | 28 | 26 | 42% |
+| Complex Object | 234 | 127 | 105 | 55% |
+| Nested Arrays | 156 | 89 | 75 | 52% |
+| API Response | 312 | 178 | 145 | 54% |
+| Deeply Nested | 95 | 78 | 65 | 32% |
+
+**Note**: Abbreviations are enabled by default and provide additional 10-25% savings on top of base optimization.
 
 ### Performance
 
@@ -969,13 +1039,23 @@ const order = {
 };
 ```
 
-**Output (with tabular optimization):**
+**Output (with tabular optimization and abbreviations enabled by default):**
+```
+orderId: o-456
+friends[3]: ana,luis,sam
+@i=items
+@i[2]{quantity,sku}:
+1,A-88
+2,T-22
+```
+
+**Output (with abbreviations disabled):**
 ```
 orderId: o-456
 friends[3]: ana,luis,sam
 items[2]{quantity,sku}:
-  1,A-88
-  2,T-22
+1,A-88
+2,T-22
 ```
 
 **For non-uniform arrays (fallback):**
@@ -1004,10 +1084,44 @@ items[2].quantity: 2
 - **Nested Objects**: Dot notation for nested properties
 - **Tabular Arrays**: Uniform object arrays automatically formatted in compact tabular format (`items[2]{field1,field2}:`)
 - **Primitive Arrays**: Comma-separated format (`friends[3]: ana,luis,sam`)
+- **Abbreviation System** (Default: Enabled): Automatically creates short aliases for repeated prefixes (`@u=user`, `@o=order`)
 - **Hybrid Approach**: Automatically detects optimal format, falls back to indexed format for mixed data
 - **Null Handling**: Explicit `null` values
 - **Type Preservation**: Numbers, booleans preserved as strings
 
+### Abbreviation System (Default: Enabled)
+
+Brevit automatically creates abbreviations for frequently repeated key prefixes, placing definitions at the top of the output:
+
+**Example:**
+```
+@u=user
+@o=order
+@u.name:John Doe
+@u.email:john@example.com
+@o.id:o-456
+@o.status:SHIPPED
+```
+
+**Benefits:**
+- **10-25% additional token savings** on nested data
+- **Self-documenting**: Abbreviations are defined at the top
+- **LLM-friendly**: Models easily understand the mapping
+- **Configurable**: Can be disabled with `enableAbbreviations: false`
+
+**When Abbreviations Help Most:**
+- Deeply nested JSON structures
+- Arrays of objects with repeated field names
+- API responses with consistent schemas
+- Data with many repeated prefixes (e.g., `user.profile.settings.theme`)
+
+**Disable Abbreviations:**
+```javascript
+const config = new BrevitConfig({
+  enableAbbreviations: false  // Disable abbreviation feature
+});
+```
+
 ## API
 
 ### BrevitClient
@@ -1061,6 +1175,8 @@ class BrevitConfig {
   imageMode: ImageOptimizationModeType;
   jsonPathsToKeep: string[];
   longTextThreshold: number;
+  enableAbbreviations: boolean;      // Default: true
+  abbreviationThreshold: number;      // Default: 2
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brevit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A high-performance JavaScript library for semantically compressing and optimizing data before sending it to a Large Language Model (LLM).",
   "main": "src/brevit.js",
   "types": "src/brevit.d.ts",