Metadata-Version: 2.4
Name: omni-compress
Version: 0.2.0
Summary: OMNI — install-and-go neural compression for source code
License-Expression: MIT
Project-URL: Homepage, https://github.com/ben-blance/omni
Project-URL: Repository, https://github.com/ben-blance/omni
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Compression
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# OMNI

<img width="500" height="500" alt="1shot__6_-removebg-preview" src="https://github.com/user-attachments/assets/7e11c236-aa11-4371-9e34-e327a8c39b71" />

</div>
OMNI is a neural compressor for Python source code. It combines a trained
sequence model with explicit long-range copy matching and entropy coding to
beat general-purpose compressors on ratio.

```
omni compress my_project/
# -> my_project.satish_andromeda

omni decompress my_project.satish_andromeda
# -> my_project/  (byte-identical to the original)
```

## Benchmark

Compression saving vs. original size, measured on 9 real-world Python
repositories OMNI was never trained on, compared against `tar+xz` (the
standard general-purpose baseline):

| repo | OMNI | tar+xz | margin |
|---|---|---|---|
| flask | 82.9% | 79.7% | +3.2pp |
| pytest | 79.9% | 73.7% | +6.2pp |
| click | 82.2% | 79.2% | +3.0pp |
| rich | 72.9% | 70.5% | +2.4pp |
| attrs | 83.6% | 81.1% | +2.5pp |
| httpx | 86.1% | 84.1% | +2.0pp |
| starlette | 84.1% | 80.9% | +3.2pp |
| alembic | 85.8% | 84.7% | +1.1pp |
| pydantic | 83.6% | 81.6% | +2.0pp |

**9 out of 9 unseen repos beat tar+xz**, by 1.1 to 6.2 percentage points.
Every result above is a full round-trip: decompressed output verified
byte-identical to the original source across all files in every repo.

These numbers are for the `.py` files specifically (both sides of the
comparison see the same file set). `omni compress` on a real project also
packs everything else — docs, configs, images — through generic codecs, so
the overall saving % on a real `omni compress my_project/` run will differ
from this table; it reflects the whole project, not just the Python source.

## Install

```
pipx install omni-compress
omni engine install
omni model update
```

(`pip install omni-compress` works too if you don't use `pipx`.) `engine
install` and `model update` are one-time setup — the engine and the
current model generation both need to be present before `compress`/
`decompress` will do anything.

## Quickstart

```
omni engine install                  # one-time: install the compression engine
omni model update                    # one-time: install the latest model
omni compress my_project/            # -> my_project.satish_andromeda
omni decompress my_project.satish_andromeda
```

## Commands

```
omni compress <path> [--model NAME] [--out FILE]
```
Compress a single file or a whole directory into one archive — every file
is preserved, not just `.py` (skipping `.git`, `__pycache__`, `venv`,
`node_modules`, etc.). Python source gets the trained neural engine;
everything else goes through a generic codec (compressed or stored as-is,
depending on the format) — `omni compress` never silently drops a file.
Uses the latest installed model generation unless `--model` is given.
Writes `<name>.satish_<generation>` unless `--out` is given.

```
omni decompress <file.satish_*> [--out PATH]
```
Reconstructs the original file or directory tree. Always uses whichever
model generation the archive itself says it needs, regardless of what's
set as default — run `omni model update` first if that generation isn't
installed yet. Without `--out`, a directory archive restores into a folder
named after the original; a single-file archive restores as that file in
the current directory.

```
omni info <file.satish_*>
```
Prints an archive's metadata — model generation, size, and a breakdown of
which codec compressed each file — without needing any model installed
(unless the archive actually contains Python files).

```
omni models
```
Lists installed model generations and which one is the default.

```
omni model update [--force]
```
Installs or refreshes the latest model generation. `--force` re-downloads
even if that generation is already installed.

```
omni model register <name> <year> <model.pt> --so <arithmetic_coder.so> [--default]
```
Registers a local model file as a named generation, for offline use.

```
omni model default <name>
```
Sets which installed generation `omni compress` uses by default.

```
omni engine install [--force]
```
Installs the compiled compression engine (one-time setup, before `compress`/
`decompress` can run). `--force` reinstalls even if already present.

```
omni version
```
Prints the CLI and format versions.

## The `.satish_<generation>` file

Every OMNI archive's extension names the model generation that produced it
— `andromeda-2026` compresses to `.satish_andromeda`, a later generation to
its own extension, and so on. That name isn't cosmetic: it's read from the
archive's own header, so `omni decompress` always knows exactly which model
to use, even years later or on a machine with several generations
installed. New generations are additive — decompressing an old archive
never requires upgrading anything, only having that generation's model
available (`omni model update` fetches whichever is current; older
generations can still be installed manually via `omni model register` if
needed).

## Try it

[`examples/`](examples/) has a walkthrough against a small sample project.

## License

MIT — see [LICENSE](LICENSE).
