@arkadia/ai-data-format 0.1.4

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/dist/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Configuration options for the AI Data Format Encoder.
+ */
+export interface EncoderConfig {
+    /**
+     * Embed schema directly inside sample data (useful for LLM prompting).
+     * Example: [ (name: string /name of user/, age: int) ]
+     * Default: false
+     */
+    promptOutput: boolean;
+    /**
+     * Number of spaces used for indentation.
+     * Default: 2
+     */
+    indent: number;
+    /**
+     * Initial indentation offset (level).
+     * Default: 0
+     */
+    startIndent: number;
+    /**
+     * Enable compact formatting. Removes unnecessary spaces and newlines.
+     * Default: false
+     */
+    compact: boolean;
+    /**
+     * Escape newline characters in strings as literal \n and \r.
+     * Default: false
+     */
+    escapeNewLines: boolean;
+    /**
+     * purely removes new lines from strings.
+     * Default: false
+     */
+    removeNewLines: boolean;
+    /**
+     * Enable ANSI colorized output for terminal debugging.
+     * Default: false
+     */
+    colorize: boolean;
+    /**
+     * Include comments in the output ).
+     * Default: true
+     */
+    includeComments: boolean;
+    /**
+     * Include array size information (e.g. [ $size=5 : ... ]).
+     * Default: false
+     */
+    includeArraySize: boolean;
+    /**
+     * Include the schema definition header (e.g. <name: string>).
+     * Default: true
+     */
+    includeSchema: boolean;
+    /**
+     * Include metadata attributes and tags ($attr=1 #tag).
+     * Default: true
+     */
+    includeMeta: boolean;
+    /**
+     * Include type signature after field names (e.g. name: string vs name).
+     * Default: true
+     */
+    includeType: boolean;
+}
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CONFIG: EncoderConfig;
+/**
+ * Helper to merge partial user config with defaults.
+ */
+export declare function resolveConfig(config?: Partial<EncoderConfig>): EncoderConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAa5B,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAE5E"}

package/dist/config.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.resolveConfig = resolveConfig;
+/**
+ * Default configuration values.
+ */
+exports.DEFAULT_CONFIG = {
+    indent: 2,
+    startIndent: 0,
+    compact: false,
+    escapeNewLines: false,
+    removeNewLines: false,
+    colorize: false,
+    includeComments: true,
+    includeArraySize: false,
+    includeSchema: true,
+    includeMeta: true,
+    includeType: true,
+    promptOutput: false,
+};
+/**
+ * Helper to merge partial user config with defaults.
+ */
+function resolveConfig(config) {
+    return { ...exports.DEFAULT_CONFIG, ...config };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AAmGA,sCAEC;AAvBD;;GAEG;AACU,QAAA,cAAc,GAAkB;IACzC,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,KAAK;IACd,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,KAAK;IACrB,QAAQ,EAAE,KAAK;IACf,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,KAAK;IACvB,aAAa,EAAE,IAAI;IACnB,WAAW,EAAE,IAAI;IACjB,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,KAAK;CACtB,CAAC;AAEF;;GAEG;AACH,SAAgB,aAAa,CAAC,MAA+B;IACzD,OAAO,EAAE,GAAG,sBAAc,EAAE,GAAG,MAAM,EAAE,CAAC;AAC5C,CAAC"}

package/dist/core/Decoder.d.ts

@@ -0,0 +1,86 @@
+import { Node } from '../models/Node';
+import { Schema } from '../models/Schema';
+export declare class DecodeError {
+    message: string;
+    position: number;
+    context: string;
+    schema: Schema | null;
+    node: Node | null;
+    constructor(message: string, position: number, schema?: Schema | null, node?: Node | null);
+    toString(): string;
+}
+export declare class DecodeWarning {
+    message: string;
+    position: number;
+    schema: Schema | null;
+    node: Node | null;
+    constructor(message: string, position: number, schema?: Schema | null, node?: Node | null);
+    toString(): string;
+}
+export interface DecodeResult {
+    node: Node;
+    schema: Schema | null;
+    errors: DecodeError[];
+    warnings: DecodeWarning[];
+}
+export declare class Decoder {
+    private static PRIMITIVES;
+    private static PRIMITIVES_MAPPING;
+    private static MAX_ERRORS;
+    private text;
+    private debug;
+    private i;
+    private line;
+    private col;
+    private pendingMeta;
+    private nodeStack;
+    private schemaStack;
+    private errors;
+    private warnings;
+    private namedSchemas;
+    constructor(text: string, schema?: string, removeAnsiColors?: boolean, debug?: boolean);
+    decode(): DecodeResult;
+    private parseSchemaAtRef;
+    private parseSchemaBody;
+    private parseSchemaBodyContent;
+    private parseSchemaType;
+    private parseNode;
+    private parseNodeWithSchemaRef;
+    private parseNodeWithInlineSchema;
+    private parseList;
+    private parsePositionalRecord;
+    private parseNamedRecord;
+    private parseMeta;
+    private parseCommentBlock;
+    private parseModifierInline;
+    private parseMetaBlock;
+    private parseMetaAttribute;
+    private parseMetaTag;
+    private parseMetaFlag;
+    private parseIdent;
+    private parseString;
+    private parseNumber;
+    private parseRawString;
+    private parsePrimitiveValue;
+    private readQuotedString;
+    private readNumber;
+    private get currentSchema();
+    private createSchema;
+    private pushSchema;
+    private popSchema;
+    private get currentNode();
+    private pushNode;
+    private popNode;
+    private createNode;
+    private applyMeta;
+    private advance;
+    private skipWhitespace;
+    private eof;
+    private peek;
+    private peekNext;
+    private expect;
+    private addError;
+    private addWarning;
+    private _dbg;
+}
+//# sourceMappingURL=Decoder.d.ts.map

package/dist/core/Decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decoder.d.ts","sourceRoot":"","sources":["../../src/core/Decoder.ts"],"names":[],"mappings":"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"}