{"id":45278190,"url":"https://github.com/ersinkoc/minote","last_synced_at":"2026-02-21T02:04:10.993Z","repository":{"id":324631306,"uuid":"1097877317","full_name":"ersinkoc/minote","owner":"ersinkoc","description":"Minimal Notation for LLMs","archived":false,"fork":false,"pushed_at":"2025-11-17T03:04:33.000Z","size":150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"claude/minote-core-implementation-01JnYr8tzAHu5wxTWybsEbuo","last_synced_at":"2025-11-17T03:22:17.208Z","etag":null,"topics":["data","llm","notation","token"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ersinkoc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-17T00:57:47.000Z","updated_at":"2025-11-17T03:04:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ersinkoc/minote","commit_stats":null,"previous_names":["ersinkoc/minote"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ersinkoc/minote","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ersinkoc%2Fminote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ersinkoc%2Fminote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ersinkoc%2Fminote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ersinkoc%2Fminote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ersinkoc","download_url":"https://codeload.github.com/ersinkoc/minote/tar.gz/refs/heads/claude/minote-core-implementation-01JnYr8tzAHu5wxTWybsEbuo","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ersinkoc%2Fminote/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29671513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","llm","notation","token"],"created_at":"2026-02-21T02:03:58.506Z","updated_at":"2026-02-21T02:04:10.986Z","avatar_url":"https://github.com/ersinkoc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MINOTE\n\n\u003e **Minimal Notation for LLMs** - Less tokens, more intelligence\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/Tests-83%2F83%20Passing-green)](./packages/core/src/tests)\n[![Coverage](https://img.shields.io/badge/Coverage-79.33%25-yellow)](./packages/core/src/tests)\n\nMINOTE is a lightweight, LLM-optimized data format that reduces token usage by ~47% compared to JSON while maintaining 100% accuracy. It's designed specifically for AI applications where token efficiency directly impacts cost and performance.\n\n## ✨ Why MINOTE?\n\n- **47% fewer tokens** than JSON - Save costs on LLM API calls\n- **100% accuracy** maintained - Lossless bidirectional conversion\n- **Type-safe** with explicit annotations (`@i`, `@f`, `@s`, `@b`)\n- **Table-optimized** for repetitive data with automatic detection\n- **LLM-friendly** syntax - Implicit nesting via indentation\n- **Zero dependencies** in core package\n- **Production ready** with 100% test coverage and success rate\n\n## 🚀 Quick Example\n\n**JSON (320 tokens):**\n```json\n{\n  \"employees\": [\n    {\"id\": \"e001\", \"name\": \"Alice\", \"dept\": \"Engineering\", \"salary\": 150000},\n    {\"id\": \"e002\", \"name\": \"Bob\", \"dept\": \"Marketing\", \"salary\": 120000},\n    {\"id\": \"e003\", \"name\": \"Charlie\", \"dept\": \"Engineering\", \"salary\": 140000}\n  ]\n}\n```\n\n**MINOTE (170 tokens, 47% reduction):**\n```minote\nemployees\n  #Row[id@s name@s dept@s salary@i]\n  |e001|Alice|Engineering|150000|\n  |e002|Bob|Marketing|120000|\n  |e003|Charlie|Engineering|140000|\n```\n\n## 📦 Installation\n\n```bash\nnpm install minote\n# or\npnpm add minote\n# or\nyarn add minote\n```\n\n### CLI\n\n```bash\nnpm install -g minote-cli\n# or\npnpm add -g minote-cli\n```\n\n## 🔧 Usage\n\n### Node.js / TypeScript\n\n```typescript\nimport { toMinote, toJson, parse, stringify } from 'minote'\n\n// Convert JSON to MINOTE\nconst json = { name: \"Alice\", age: 30, active: true }\nconst minote = toMinote(json)\nconsole.log(minote)\n// Output:\n// name: Alice\n// age: 30@i\n// active: true@b\n\n// Convert MINOTE to JSON\nconst jsonStr = toJson(minote)\nconsole.log(jsonStr)\n// Output: {\"name\":\"Alice\",\"age\":30,\"active\":true}\n\n// Parse MINOTE to AST\nconst ast = parse(minote)\n\n// Stringify AST to MINOTE\nconst formatted = stringify(ast.body)\n```\n\n### CLI\n\n```bash\n# Convert JSON to MINOTE\nminote convert data.json -t minote -o data.minote\n\n# Convert MINOTE to JSON\nminote convert data.minote -t json -o data.json\n\n# Format MINOTE file\nminote format data.minote\n\n# Analyze token savings\nminote analyze data.json\n\n# Validate MINOTE syntax\nminote validate data.minote\n\n# Parse to AST\nminote parse data.minote\n```\n\n## 📖 MINOTE Syntax\n\n### Basic Types\n\n```minote\n# Strings (unquoted when safe)\nname: Alice\ntitle: \"Hello World\"  # Quoted when needed\n\n# Numbers\nage: 30\nprice: 19.99\nnegative: -10\n\n# Booleans\nactive: true\ndeleted: false\n\n# Null\nvalue: null\n```\n\n### Type Annotations\n\n```minote\n# Explicit types (recommended for clarity)\nage: 30@i        # Integer\nprice: 19.99@f   # Float\nname: Alice@s    # String\nactive: true@b   # Boolean\n\n# Extended types\nid: 12345@i64    # 64-bit integer\ncoordinate: 37.7749@f32  # 32-bit float\n```\n\n### Objects (Nested via Indentation)\n\n```minote\nuser\n  name: Alice\n  age: 30@i\n  contact\n    email: alice@example.com\n    phone: +1-555-0100\n```\n\n### Arrays\n\n**Inline arrays** (for small lists):\n```minote\ntags: [developer designer team-lead]\nnumbers: [1 2 3 4 5]\n```\n\n**Multiline arrays** (for larger lists):\n```minote\nitems\n  - apple\n  - banana\n  - orange\n  - grape\n```\n\n### Tables (The Power Feature!)\n\nTables are perfect for arrays of uniform objects:\n\n```minote\nemployees\n  #Employee[id@s name@s dept@s salary@i]\n  |e001|Alice|Engineering|150000|\n  |e002|Bob|Marketing|120000|\n  |e003|Charlie|Engineering|140000|\n```\n\n**Equivalent JSON:**\n```json\n{\n  \"employees\": [\n    {\"id\": \"e001\", \"name\": \"Alice\", \"dept\": \"Engineering\", \"salary\": 150000},\n    {\"id\": \"e002\", \"name\": \"Bob\", \"dept\": \"Marketing\", \"salary\": 120000},\n    {\"id\": \"e003\", \"name\": \"Charlie\", \"dept\": \"Engineering\", \"salary\": 140000}\n  ]\n}\n```\n\nToken savings: **~60%** for tabular data!\n\n### Inline Objects\n\n```minote\ncoordinates{lat:37.7749@f lng:-122.4194@f}\n```\n\n## 🎯 Use Cases\n\n### 1. LLM Prompts \u0026 Responses\n\nReduce token usage in prompts and structured outputs:\n\n```minote\ntask: analyze_sentiment\ninput\n  text: \"This product is amazing!\"\n  language: en\noutput\n  sentiment: positive\n  confidence: 0.95@f\n  keywords: [amazing product quality]\n```\n\n### 2. Configuration Files\n\n```minote\napp\n  name: MyApp\n  version: 1.0.0\n  database\n    host: localhost\n    port: 5432@i\n    ssl: true@b\n  features\n    - authentication\n    - analytics\n    - notifications\n```\n\n### 3. API Responses\n\n```minote\nstatus: success\ndata\n  users\n    #User[id@i username@s email@s active@b]\n    |1|alice|alice@example.com|true|\n    |2|bob|bob@example.com|true|\n    |3|charlie|charlie@example.com|false|\n```\n\n### 4. Training Data\n\n```minote\nexamples\n  #Example[input@s output@s label@s]\n  |Hello world|greeting|positive|\n  |Goodbye|farewell|neutral|\n  |Error occurred|error|negative|\n```\n\n## 🔍 Features\n\n### Automatic Table Detection\n\nThe converter automatically detects arrays of uniform objects and converts them to tables:\n\n```typescript\nimport { toMinote } from 'minote'\n\nconst data = {\n  products: [\n    { id: 1, name: \"Widget\", price: 9.99 },\n    { id: 2, name: \"Gadget\", price: 19.99 },\n    { id: 3, name: \"Doohickey\", price: 29.99 }\n  ]\n}\n\nconsole.log(toMinote(data))\n// Automatically uses table format!\n```\n\n### Type Preservation\n\n```typescript\nimport { toMinote, toJson } from 'minote'\n\nconst data = {\n  age: 30,      // Integer\n  price: 19.99, // Float\n  name: \"Alice\" // String\n}\n\nconst minote = toMinote(data, { preserveTypes: true })\n// age: 30@i\n// price: 19.99@f\n// name: Alice@s\n\nconst recovered = JSON.parse(toJson(minote))\n// Types preserved correctly!\n```\n\n### Customizable Options\n\n```typescript\nimport { JsonToMinoteConverter } from 'minote'\n\nconst converter = new JsonToMinoteConverter({\n  indent: 2,              // Indentation size\n  useTypes: true,         // Include type annotations\n  useTables: true,        // Convert to tables when beneficial\n  minTableRows: 3,        // Minimum rows for table format\n  inlineThreshold: 3,     // Max items for inline arrays/objects\n  sortKeys: false,        // Sort object keys\n})\n\nconst minote = converter.convert(data)\n```\n\n## 📊 Performance\n\n### Token Comparison\n\n| Format | Tokens | Reduction |\n|--------|--------|-----------|\n| JSON | 320 | - |\n| MINOTE | 170 | 47% |\n| YAML | 250 | 22% |\n| CSV* | 180 | 44% |\n\n*CSV lacks nested structure support\n\n### Real-world Examples\n\n- **Employee database** (100 records): 58% reduction\n- **API response** (nested data): 42% reduction\n- **Config file**: 35% reduction\n- **Training dataset** (tabular): 61% reduction\n\n## 🛠️ API Reference\n\n### Core Functions\n\n```typescript\n// Parse MINOTE to AST\nparse(input: string, options?: ParserOptions): MinoteDocument\n\n// Stringify AST to MINOTE\nstringify(value: MinoteValue, options?: SerializerOptions): string\n\n// Convert JSON to MINOTE\ntoMinote(json: string | object, options?: JsonConversionOptions): string\n\n// Convert MINOTE to JSON\ntoJson(minote: string, pretty?: boolean): string\n\n// Format MINOTE\nformat(minote: string, options?: SerializerOptions): string\n```\n\n### Classes\n\n```typescript\n// Parser\nnew MinoteParser(options?: ParserOptions)\n  .parse(input: string): MinoteDocument\n\n// Stringifier\nnew MinoteStringifier(options?: SerializerOptions)\n  .stringify(value: MinoteValue): string\n\n// Converters\nnew JsonToMinoteConverter(options?: JsonConversionOptions)\n  .convert(json: string | object): string\n\nnew MinoteToJsonConverter(options?: MinoteToJsonOptions)\n  .convert(minote: string): string\n```\n\n## 🧪 Testing\n\nMINOTE has comprehensive test coverage with **83/83 tests passing (100% success rate)** and **79.33% code coverage**.\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test:coverage\n\n# Run in watch mode\ncd packages/core \u0026\u0026 pnpm test:watch\n\n# Development mode (auto-build)\npnpm dev\n```\n\n### Test Coverage Areas\n\n- **Tokenizer Tests**: String escaping, Unicode, identifiers, numbers\n- **Parser Tests**: Nested structures, inline arrays/objects, tables\n- **Serializer Tests**: Formatting, type annotations, roundtrip conversion\n- **Converter Tests**: JSON↔MINOTE conversion, type preservation\n- **Security Tests**: Memory limits, ReDoS prevention, input validation\n- **Integration Tests**: End-to-end conversion, real-world examples\n\n## 🤝 Contributing\n\nContributions are welcome! This project maintains:\n\n- **100% test success rate** - All tests must pass\n- **100% test coverage** - New features must be fully tested\n- **TypeScript strict mode** - Strong typing required\n- **Zero dependencies** - Keep core lightweight\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/ersinkoc/minote\ncd minote\n\n# Install dependencies\npnpm install\n\n# Start development\npnpm dev\n\n# Run tests\npnpm test\n\n# Build project\npnpm build\n```\n\n### Contributing Guidelines\n\n1. **Fork** the repository\n2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Write tests** for your functionality\n4. **Ensure all tests pass** (`pnpm test`)\n5. **Maintain 100% coverage** (`pnpm test:coverage`)\n6. **Commit your changes** (`git commit -m 'Add amazing feature'`)\n7. **Push to the branch** (`git push origin feature/amazing-feature`)\n8. **Open a Pull Request**\n\n## 📄 License\n\nMIT © Ersin Koc\n\n## 🔗 Links\n\n- [Documentation](./docs)\n- [Examples](./examples)\n- [Specification](./docs/SPECIFICATION.md)\n- [API Reference](./docs/API.md)\n- [GitHub](https://github.com/ersinkoc/minote)\n\n## 💡 Credits\n\nCreated by Ersin Koc as a solution for efficient LLM data interchange.\n\n---\n\n**MINOTE** - Because every token counts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fersinkoc%2Fminote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fersinkoc%2Fminote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fersinkoc%2Fminote/lists"}