AK Data
Format
The high-density protocol for LLM communication. AK-Data injects a metadata layer into your data, allowing for comments, tags, and attributes that LLMs can read but parsers can ignore.
; i :J U, .j..fraaM. nl b h.obWMkkWWMMWMCdkvz,k ! .mQWM:o hiMoMW v.uaXMdohbi hI,MMmaIao.Wo .IMkoh FCMwqoXa ,.c.aWdM. d,aToW . Mb!. MopfQ.L jhj.xoM :k aCu F: w MpmqMvMMI,I bzMhz:W .Mw . o lYh ai M iMa pM.j hzqWWM; M;o.WMWWMkMX f.a aa bModpo. ;tMbbv xp oJMMWWWWMMMM iv dLMXakM:T mdh MMWWWWWWWbQLCzurjktvMor ,QFw ;M,b .MWWWWWWWMWMWd xz M,kd X qjMIo IMTW.WWWWWMWWWM.o.I rpULaMdi. .mMM uoWWWMWWWWWWp qM,,M l M;mMbrI f nm MMW MWWjMuMj I o LbMac WWdMWWWW Mv a.b..aauMhMwQf MoWWW,WWtjonJMWtoMdoaoMI MMMM Mi xd:Mm tMwo Cr, xMMc .otqokWMMMao:oio. MW . C..MkTIo WW QWM WW uMW WW MW ARKADIA DATA PROTOCOL v0.1.11 -------------------------------------------------- Status: Public Beta Docs: https://arkadia.solutions/akdata QUICK START: $ npm install @arkadia/data $ pip install arkadia-data ADVANCED USAGE: /* Define Schema with Attributes ($) and Tags (#) */ @Agent < // $version="1.0" #deprecated // id: number, name: str, prompt: str > /* List with metadata and mixed record types */ [ $env="prod" /* Positional Record (Dense) */ (1, "HelpBot", "You are helpful"), /* Named Record (Flexible) */ { id: 2, name: "AutoBot" } ]
The AK-Data Advantage
Benchmarks
By moving structure definition to the schema header and utilizing positional tuples, AK-Data reduces syntactical noise by up to 50% compared to JSON.
# Run Token/Speed analysis $ akd benchmark ./data GLOBAL PERFORMANCE REPORT FILE JSON AKCD AKD TOON SAVINGS (AKCD) -------------------------------------------------------------------------------------------------------- aid-test-01.json 7t/ 0.0ms 13t/ 0.0ms 20t/ 0.0ms 10t/ 0.0ms +85.7% arrays-nested.json 675t/ 0.0ms 584t/ 0.5ms 724t/ 0.4ms 841t/ 0.2ms -13.5% arrays-objects.json 1023t/ 0.0ms 823t/ 0.6ms 990t/ 0.7ms 1207t/ 0.3ms -19.6% arrays-primitive.json 431t/ 0.0ms 367t/ 0.3ms 471t/ 0.3ms 520t/ 0.2ms -14.8% arrays-tabular.json 413t/ 0.0ms 343t/ 0.2ms 399t/ 0.2ms 441t/ 0.1ms -16.9% delimiters.json 1292t/ 0.0ms 971t/ 0.9ms 1193t/ 0.9ms 1498t/ 0.5ms -24.8% normalization.json 527t/ 0.0ms 410t/ 0.3ms 467t/ 0.3ms 625t/ 0.2ms -22.2% objects.json 833t/ 0.0ms 584t/ 0.6ms 650t/ 0.6ms 1041t/ 0.3ms -29.9% options.json 423t/ 0.0ms 337t/ 0.3ms 427t/ 0.3ms 482t/ 0.2ms -20.3% primitives.json 1015t/ 0.0ms 733t/ 0.6ms 845t/ 0.6ms 1264t/ 0.4ms -27.8% toon.json 139t/ 0.0ms 115t/ 0.1ms 145t/ 0.1ms 104t/ 0.0ms -17.3% whitespace.json 143t/ 0.0ms 136t/ 0.1ms 157t/ 0.1ms 165t/ 0.1ms -4.9% -------------------------------------------------------------------------------------------------------- BENCHMARK SUMMARY: JSON █████████████████████░░░░ 6921 tok 0.16 ms AKCD ████████████████░░░░░░░░░ 5416 tok 4.69 ms AKD ███████████████████░░░░░░ 6488 tok 4.55 ms TOON █████████████████████████ 8198 tok 2.41 ms FORMAT TOKENS TIME (Total) AVG TIME/FILE VS JSON ---------------------------------------------------------------------- AKCD 5416 4.69 ms 0.39 ms -21.7% AKD 6488 4.55 ms 0.38 ms -6.3% JSON 6921 0.16 ms 0.01 ms +0.0% TOON 8198 2.41 ms 0.20 ms +18.5% CONCLUSION: Switching to AKCD saves 1505 tokens (21.7%) compared to JSON.
@ Schema-First Design
Define structure once. AK-Data validates data types (int, number, bool) before they reach
your LLM context, preventing hallucinated formats.
# Metadata Injection
Use #tags and $attributes="value" to pass
context to the LLM (e.g., deprecated flags, source origins) that is
invisible to the application logic but visible to the model.
/* */ Semantic Layer
Full support for C-style comments, multiline strings (using backticks), and mixed records (tuples for density, objects for optional fields).
Core Syntax Blueprint
( 101, "gpt-4-turbo", 0.7, true ),
( 102, "claude-3-opus (optimized)", 0.2, true ),
{ #experimental id: 200, model_name: "llama-3-70b" /* temperature defaults to 0.0 */ }
Playground
LIVE CONVERTERSee the Efficiency.
Start typing JSON below. The conversion happens automatically.
NPM / TypeScript
GitHub →npm i @arkadia/data Copy PyPI / Python
GitHub →pip install arkadia-data Copy ENCODE
Convert your native objects (Dictionaries, Maps, Objects) into the optimized AK-Data string format. Supports both compact and readable modes.
import { encode } from '@arkadia/data'; // Encode Object -> AKD String const data = { id: 1, active: true }; console.log(encode(data)); // Output: <id:number,active:bool>(1,true)
import arkadia.data as akd data = { "id": 1, "active": True } config = { "compact": True, "indent": 2 } # Encode Dict -> AKD String result = akd.encode(data, config) print(result) # Output: <id:number,active:bool>(1,true)
DECODE
Parse AKD strings back into usable data structures. The parser is robust and includes error handling for malformed input.
import { decode } from '@arkadia/data'; // 1. Input AKD String const input = '<id:number,active:bool>(1,true)'; // 2. Parse to AST const { node, errors } = decode(input); if (!errors.length) { // Access data as JS Object console.log(result.node.dict()); // Output: { id: 1, active: true } console.log(result.node.JSON()); // Output: '{ id: 1, active: true }' }
import arkadia.data as akd aid_str = '<id:number,active:bool>(1,true)' # 1. Decode -> Result Object result = akd.decode(aid_str) if not result.errors: # 2. Access Node and convert to Dict print(result.node.dict()) # Output: {'id': 1, 'active': True} # Alternative: Get JSON string print(result.node.json()) # Output: '{ id: 1, active: true }'
CLI (Python Only)
Use the command line interface to integrate AKD into your CI/CD pipelines or for quick file conversions and testing.
# 1. Pipe JSON directly $ echo '{"a":1}' | akd enc - # 2. Convert File $ akd enc data.json -o data.akd # 3. Decode back to JSON $ akd dec data.akd -f json
01. Primitives
AKD automatically infers basic types like integers, booleans, and nulls. Strings can often be unquoted if they don't contain special characters, saving tokens.
// Auto-inference of types encode(123); // <number>123 encode("hello"); // <string>"hello" encode(true); // <bool>true encode(null); // <null>null
# Auto-inference of types encode(123) # <number>123 encode("hello") # <string>"hello" encode(True) # <bool>true encode(None) # <null>null
02. Schema Definition
Define strict structures using the @Type syntax. Schemas
act as contracts, ensuring that LLMs output data that perfectly matches
your application's expectations.
/* User Profile Schema Definition */ @UserProfiles <[ /* Schema Metadata */ // $version="1.2.0" #public $author="Arkadia Team" // /* Fields */ /* Unique ID */ $required id: number, /* Public handle */ username: string, /* Nested Object for Preferences */ preferences: < theme: string, #daily notifications: bool >, /* List of Tags with Metadata */ tags: [ // $maxItems=10 // string ] ]>
03. List
Lists in AKD are optimized for density. You can define homogenous lists (e.g., list of strings) to avoid repeating type information for every item.
/* Define a list of numbers */ @Temperatures <[number]> /* Data follows the schema */ [10, 20, 30, 40, 50]
/* Define a list of strings */ @StatusLog <[string]> [ "active", "pending", /* Exception: Number inside String list requires tag */ <number> 404, "closed" ]
/* Define a 2D array (Matrix) of numbers */ @Matrix3x3 <[[number]]> [ [1, 0, 0], [0, 1, 0], [0, 0, 1] ]
04. Record (Tuple)
Records are the most efficient way to represent objects. By using a schema, AKD removes the need for repeating keys (like "x":, "y":) for every single entry, drastically reducing token count.
// High Density (No keys) @Point<x:number,y:number> (10, 20)
05. Named Record
When flexibility is required, or for sparse data, AKD supports standard key-value records similar to JSON objects.
// Flexible (JSON-like) { id: 1, name: "Admin" }
06. Metadata Injection
Inject context directly into the data stream using / ... /
blocks. This data is visible to the LLM but is ignored by the parser
when decoding back to your application.
/* Metadata block //...// */ [ // $source="db" #verified // 1, 2, 3 ]
07. Comments
Standard C-style comments are fully supported. Use them to provide hints to the model or document the data structure without affecting the payload.
/* Standard C-style comments /* inner comment */ */ @Config < /* enable logs */ debug: bool >
08. Attributes ($)
Use the $ prefix to attach key-value metadata to schemas,
specific fields, or individual data records. Ideal for versioning,
authorship, or source tracking.
/* 1. SCHEMA DEFINITION */ @Product < /* Global Schema Meta */ // $version="2.1" $strict=true $author="System" // /* Field Meta */ $desc="Unique SKU" sku: string, $unit="USD" $min=0 $precision=2 price: number, #deprecated $replacedBy="sku_v2" legacy_id: int > /* 2. DATA INSTANCE */ { /* Instance Meta (Header) */ // $source="warehouse_db" $syncId=204 // /* Instance Fields with Meta */ $verified=true sku: "PROD-123", $discount="10%" $final=true price: 49.99, $note="migration_pending" legacy_id: 9901 }
09. Tags (#)
Simple boolean flags using the # prefix. Use tags to mark
states like #deprecated, #experimental, or #private without adding
overhead to your data structure.
/* 1. SCHEMA FLAGS */ @FeatureConfig < /* Global Schema Tags */ // #public #stable #versioned // /* Field Tags */ #deprecated legacy_mode: bool, #experimental #beta ai_engine_v2: string, #readonly #internal system_id: int > /* 2. DATA INSTANCE FLAGS */ { /* Instance Tags (Header) */ // #cached #verified // #ignored legacy_mode: true, #active ai_engine_v2: "deep_thought_xl", system_id: 9900 }
10. Modifiers ($required)
Enforce strict validation rules directly in the schema. The
$required modifier ensures critical fields are never missing
from the LLM's output.
/* Schema Definition */ @UserCredentials < /* 1. Mandatory Field */ $required uuid: string, /* 2. Optional Field (Default) */ display_name: string, /* 3. Mixed: Modifier + Attribute */ $required $minLen=8 password_hash: string, /* 4. Mixed: Modifier + Tag */ $required #unique email: string >
11. Escaped Identifiers (Backticks)
Support for complex names using backticks (`). This allows
identifiers to contain spaces, mathematical operators, or special symbols,
making AKD a perfect proxy for legacy databases and descriptive labels.
# Encode JSON with spaces in keys $ echo '{"User ID": 1}' | akd enc - # Output: <`User ID`:number>(1)
@`Inventory DB` < `Product ID+`: int, `Stock (units)`: number > /* Instance matching keys */ { `Product ID+`: 501, `Stock (units)`: 1200 }
12. AI Prompt Output Mode
Transform dense data into a Structural Blueprint. The
--prompt-output flag expands schemas into descriptive,
recursive templates—perfect for providing LLMs with contextually rich instructions.
# Generate LLM-friendly template $ echo '<id:number, name:string, val:<id:string, top:number>>(1, "Alice")' \ | akd dec -f akd --prompt-output --no-schema -
{ id: number, name: string, val: { id: string, top: number } }