Metadata-Version: 2.4
Name: soon-format
Version: 0.1.0
Summary: SOON (Shape-Oriented Object Notation): lossless, token-efficient encoding of nested JSON for LLM prompts
Project-URL: Homepage, https://github.com/soon-format/soon-python
Project-URL: Repository, https://github.com/soon-format/soon-python
Project-URL: Issues, https://github.com/soon-format/soon-python/issues
Project-URL: Spec, https://github.com/soon-format/soon
Author-email: Yasin Ughur <yasinugur.cs@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: compression,json,llm,prompt,soon,tokens,toon
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: tiktoken>=0.5; extra == 'dev'
Requires-Dist: toon-py; extra == 'dev'
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.5; extra == 'tokens'
Description-Content-Type: text/markdown

# soon-format

**SOON (Shape-Oriented Object Notation)** — lossless, token-efficient encoding
of nested JSON for LLM prompts. Python implementation.

## Install

```bash
pip install soon-format            # library + `soon` CLI
pip install "soon-format[tokens]"  # + tiktoken-based cost decisions
```

## Usage

```python
from soon_format import encode, decode, stats

doc = encode(data)                        # auto mode, never-worse guarantee
data == decode(doc)                       # True — lossless
stats(data)                               # {"json_chars": …, "soon_chars": …, "saving": 0.604}

# Real-token cost decisions
encode(data, tokenizer="o200k_base")
stats(data, tokenizer="o200k_base")       # adds json_tokens / soon_tokens
```

## CLI

```bash
soon encode data.json --stats
soon decode doc.soon              # compact JSON to stdout
soon decode doc.soon --pretty     # indented JSON
soon check data.json              # round-trip verification
```

## Spec & conformance

This implementation passes the shared [conformance suite](https://github.com/soon-format/soon/tree/main/conformance)
byte-for-byte. See the [SOON spec](https://github.com/soon-format/soon/blob/main/SPEC.md) for the normative format definition.

## License

[MIT](LICENSE) © Yasin Ughur
