Metadata-Version: 2.4
Name: anla-archive
Version: 0.1.0
Summary: Reference implementation of the Agent-Native Lossless Archive — readable, dependency-light, and slower than the Rust writer by design
Author: Neo.K
License-Expression: Apache-2.0
Project-URL: Homepage, https://anla.evemisslab.com
Project-URL: Source, https://github.com/kakon77777-commits/anla
Project-URL: Specification, https://anla.evemisslab.com/spec/
Keywords: archive,lossless,deduplication,content-addressed,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Archiving :: Compression
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: blake3>=1.0; extra == "dev"
Requires-Dist: zstandard>=0.22; extra == "dev"
Provides-Extra: speed
Requires-Dist: blake3>=1.0; extra == "speed"
Provides-Extra: zstd
Requires-Dist: zstandard>=0.22; extra == "zstd"

# anla — Agent-Native Lossless Archive

**An AI may plan how to pack. A public, deterministic, model-independent decoder must
recover every byte that was declared into the archive.**

```text
Extract(Pack(F, P)) = F
```

This is the **reference implementation**: dependency-light, readable, and the
executable half of the specification. A second implementation in Rust lives in the
same repository and produces byte-identical archives; the two are held to each other
by a conformance suite and a differential fuzzer.

- Site and browser workbench — <https://anla.evemisslab.com>
- Specification — <https://anla.evemisslab.com/spec/>
- Source, papers, conformance vectors — <https://github.com/kakon77777-commits/anla>

## Install

```bash
pip install anla-archive                  # reader, writer, verifier, both CLIs
pip install "anla-archive[speed,zstd]"    # the BLAKE3 and Zstandard fast paths
```

The distribution is `anla-archive`; the import packages and the commands are `anla`
and `anla1`. PyPI refuses the bare name — it is one character from several existing
projects — and the two names are independent anyway.

```python
import anla, anla1          # after pip install anla-archive
```

Python 3.10+. No required dependencies: `blake3` and `zstandard` are optional, and
the package carries a readable pure-Python BLAKE3 so the format's hash can be checked
by reading rather than by trusting a compiled wheel.

## Two commands, two profiles

```bash
anla  pack ./project -o project.anla        # ANLA-MVP v0.1 — frozen
anla1 pack ./project -o project.anla        # ANLA 1.0 — draft
```

Separate commands rather than a flag, for the same reason 1.0 has its own magic
number: they are different formats, and one command switching between them on a flag
invites an archive written under one profile and read under the other.

`anla1` also carries the context layer — an agent's own history, stored losslessly
and addressable back to the exact bytes of a turn:

```bash
anla1 context capture  memory.anla
anla1 context segment  memory.anla --scheme changepoint-v1
anla1 context address  memory.anla "how was the gear table produced"
```

## Read the format from Python

```python
from anla1.snapshot import list_snapshots, extract_snapshot, verify_archive

data = open("project.anla", "rb").read()
report = verify_archive(data)                      # every chunk, every root
files = extract_snapshot(data, list_snapshots(data)[-1])
```

## Speed, stated rather than discovered

Content-defined chunking is the default, because fixed chunking destroys
deduplication. In this writer it is also the slow path, by a wide margin — measured
on 64 MiB of incompressible data:

| | MiB/s |
|---|---|
| this writer, fixed chunking | 64.4 |
| **this writer, `anla-cdc-1`** | **3.8** |
| the Rust writer, `anla-cdc-1` | 107.3 |
| this reader, verify | 538.1 |

So: use this package to read archives, to check the format, to embed in Python, and
for trees measured in megabytes. Use `anla1-rs` from the same repository for volume.
The two produce identical bytes; only one of them is worth an afternoon.

Every figure above is produced by `bench/run_bench.py` and republished at
<https://anla.evemisslab.com/bench/>, including the rows where ANLA loses.

## Status

`ANLA-MVP v0.1` is frozen. `ANLA 1.0` is a **draft** and says so: the freeze rule —
two independent implementations producing byte-identical archives with no verdict
divergence under differential fuzzing — is met, but two implementations by one author
are weaker evidence than two by two authors, and the specification records that
rather than rounding it up.

> This is a research profile. It is tested, but it is young. Do not make an ANLA
> archive the only copy of anything you cannot lose.

Apache-2.0.
