@arkadia/ai-data-format 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arkadia Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @arkadia/ai-data-format
+
+```
+                            :SB@MMWBZSr,
+                         ,irXX7ri, iaBWMMMMM@a:    :,
+                    i2WMMMMMMMMMMMM@a:7ZZWMMMMM@7 :i,02,
+                 ,7S7;i::i;72Z2S0@ZZWMW;r7iBWWM@M2 rM0BM;
+                   ia@@08Z0B2:  :,i0r rBZ,: XSBMZM: 2MMMMi
+                 iBZ7i:,   iXZZSi   i;  ia   ;:@22: ;M@MMS
+                 ,:    ,, ,7:  ,Xi  ;r,   :   ,SS,  rBZ8MiX7,
+             r8WZ: XW@0Z8WMZ: rX: :M2;BZ ;r:   ;,   ::Si;ii   :7
+          :8MM@a,:@0:      XM2  , i@WZMZ 28MMMBr     , :ZW@a  iB@;
+        ,Z0MMWZi BB  ,aZ8i      S7,,  ;SXZMMMMMMMa::r ,         7M8,
+        :;MMZ:   8Z  :07Z7   @X XaSa,:8MMMM2ZMMMMMMM@MS   i2 ,BX :WW:
+        iM0:  ,X,i8r        XM:,S7a; XZWMMMM2,8MMMMMWr8M2, iS,    ,B@:
+        87  iB0:,,,XZX,  XW S@    ,;aZ00ZZ2SX7,:S8082,iM00, :i  ar ,WW,
+        : :0MB@Zi,,      iM2 Sr :;Xriirr:  ZM8      ,XBM@X   :   ,: i@a
+         rMMMW0X:  8Z     : ;a00Z7,,2BMMWBZXi  :,   iaWMMMMB7    :;  2Wi
+        rMMBr     ZW ,i   rW7a00Z702 78@MMMMMMMM0@MMM@@@MMMMMM0r     iWS
+       :MZ,  ,7: ;M2;Zii,:MrB,   2S07 ZZ8BZ,XB0WMMMMMMMMW280BWWWW8i   8Z
+       S:  ,ZZ   XMZW:rr, Z;B:  ,ZXSi S2222XXX7ZBZ;:BMMM@X:   irr:    ZZ
+          ;MZ;   rMMX   : ,27XZZS;S;     ii    ,i,ZMMMMMMMMM@7  ,8Z   aa
+         ;MM0: ,  BMi  iS   ,irr;:;, :7,,Wa S8Z,,aXMZWBBMMMMMMS:MM8  ,ZX
+        ,WMM0,2   :@,  0rr        ;@Br2,7S ::r7,ir;rr8ZZMMMMMMSiMMa  ;ai
+        rMMM8a7    ,:  @0:  ,:    ,   ,         ,Z222X77@MW02i iZW: ,SX
+        X@SM0@:        BB   ;r   :S     ,;7XS77; ,XZZZZ82r, :;i ,,  ;X:
+        ;riMMM:  , r , ;0 ,:7Z  ;SS   ;     ,       ,:  iZ@MMMMM2
+           8MM;  ; Z ;i ;, XrMi  B8   X7 , ,7        ,XZWMMMMMM@B
+           ,WM2  7;87:8    XXMW, ,Bi ;7@i i Z     ,;2aa8MWWMMMM02
+            ,B@, :ZaMiBX   :ZBMWr, ;  XB@iiXX2::     Xa7;80Z@0a :
+              X8  r8WMaMr   iZ0MM0,    ,X@;;ZWX8       :S; 7:
+               ,i  rBWMMMr   :X;WM@r      ir:0@W0
+                    ,0@MMM2    : ;BMWi        7@MW:
+                      :0MMMWi       ;aBS:       i8MZ:
+                         XBMMW;                    ,;r,
+                            iS0@8;
+```
+
+
+[![npm version](https://img.shields.io/npm/v/@arkadia/ai-data-format.svg)](https://www.npmjs.com/package/@arkadia/ai-data-format)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Official Parser and Stringifier for the Arkadia AI Data Format (AID).**
+
+AID is a schema-first, high-density data protocol designed specifically for **LLM context optimization**. It significantly reduces token usage compared to JSON by eliminating redundant syntax characters and enforcing strict typing via schemas.
+
+## ✨ Features
+
+- **Token Efficient:** Reduces context window usage by 15-30% compared to standard JSON.
+- **Type Safe:** Enforces types (int, float, bool, string) explicitly in the schema.
+- **Dual Mode:** Supports both **Named Records** (Map-like) and **Positional Records** (Tuple-like).
+- **Zero-Dependency:** Lightweight and fast, built for high-performance pipelines.
+
+## 📦 Installation
+
+```bash
+npm install @arkadia/ai-data-format
+
+```
+
+## 🚀 Usage
+
+### Importing
+
+```typescript
+import { encode, decode } from '@arkadia/ai-data-format';
+
+```
+
+### Encoding (JavaScript Object → AID String)
+
+Converts standard JavaScript objects into the token-optimized AID string format.
+
+```typescript
+const data = {
+  id: 1,
+  name: "Alice",
+  active: true
+};
+
+// Compact encoding (default)
+const aidString = encode(data);
+
+console.log(aidString);
+// Output: <id:number,name:string,active:bool>(1,"Alice",true)
+
+```
+
+### Decoding (AID String → AST / Value)
+
+Parses an AID string back into a usable node structure.
+
+```typescript
+const input = '<score:number>(98.5)';
+
+const result = decode(input);
+
+if (result.errors.length === 0) {
+  console.log(result.node.value); 
+  // Output: 98.5
+  
+  console.log(result.node.isRecord); 
+  // Output: true
+} else {
+  console.error("Parsing errors:", result.errors);
+}
+
+```
+
+## 📖 Syntax Guide
+
+The AID format uses a distinct syntax to separate schema definition from data values.
+
+### Primitives
+
+Primitive values are explicitly typed using angle brackets `<type>`.
+
+| Type | Input Example | Encoded Output |
+| --- | --- | --- |
+| Integer | `123` | `<number>123` |
+| Float | `12.34` | `<number>12.34` |
+| String | `"hello"` | `<string>"hello"` |
+| Boolean | `true` | `<bool>true` |
+| Null | `null` | `<null>null` |
+
+### Named Records
+
+Similar to JSON objects, but the keys are lifted into a schema definition.
+
+**Input:**
+
+```json
+{ "id": 1, "name": "Test" }
+
+```
+
+**Encoded (AID):**
+
+```text
+<id:number,name:string>(1,"Test")
+
+```
+
+### Positional Records (Tuples)
+
+Data without keys, where position determines meaning.
+
+**Input:**
+
+```javascript
+// (10, "Alice") - conceptually
+
+```
+
+**Encoded (AID):**
+
+```text
+<_0:number,_1:string>(10,"Alice")
+
+```
+
+## 🛠️ API Reference
+
+### `encode(input: any, options?: EncodeOptions): string`
+
+Serializes a JavaScript value into an AID string.
+
+* `input`: The data to encode.
+* `options`:
+* `compact`: (boolean) Remove whitespace. Default: `true`.
+* `colorize`: (boolean) Add ANSI colors for terminal output. Default: `false`.
+
+
+
+### `decode(text: string, options?: DecodeOptions): ParseResult`
+
+Parses an AID string.
+
+* `text`: The AID string to parse.
+* `options`:
+* `debug`: (boolean) Enable detailed logging.
+
+
+* **Returns** `ParseResult`:
+* `node`: The parsed AST node containing value and metadata.
+* `errors`: Array of parsing errors, if any.
+
+
+
+## 📄 License
+
+This project is licensed under the [MIT License].
+
+---
+
+<div align="center">
+<sub>Built by <strong>Arkadia AI</strong>. Engineering the kernel of distributed intelligence.</sub>
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkadia/ai-data-format",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Parser and Stringifier for Arkadia AI Data Format (AID)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",