Metadata-Version: 2.4
Name: dagr-cli
Version: 2026.9.2
Summary: Dagr — data-graph binary serialization: schema DSL, code generators for Swift, Rust, TypeScript, Go, Mojo, Odin and Python, and receipt/compatibility tooling
Author: Maxim Zaks
License-Expression: Apache-2.0
Project-URL: Homepage, https://codeberg.org/mzaks/dagr
Project-URL: Repository, https://codeberg.org/mzaks/dagr
Project-URL: Changelog, https://codeberg.org/mzaks/dagr/src/branch/main/CHANGELOG.md
Keywords: serialization,binary-format,code-generation,arena,graph,zero-copy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Go
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: asn1
Requires-Dist: asn1tools; extra == "asn1"
Dynamic: license-file

# Dagr

**Dagr** ("Data Graph") is a binary serialization format for **data graphs** — object graphs
with cycles and shared nodes — and a set of **code generators** that emit a complete,
self-contained implementation of your schema for Swift, Rust, TypeScript, Go, Mojo, Odin and
Python.

You describe a graph once, in a small Python DSL:

```python
from dagr.dsl import DataGraph, Node, Enum, t, required
from dagr.config import Library, Swift, Rust

address_book = DataGraph("AddressBook", root_type=t.ref("Book"), node_types=[
    Node("Book", fields=["people" >> t.ref("Person").array]),
    Node("Person", fields=[
        "name"    >> t.utf8 >> required,
        "age"     >> t.u8,
        "friends" >> t.ref("Person").array,      # cycles and shared nodes are fine
        "status"  >> t.ref("Status"),
    ]),
    Enum("Status", ["single", "married", "widowed"]),
])

library = Library("AddressBook", schemas=[address_book], targets=[
    Swift(out="gen/swift", features=["lazy", "path_query", "explain"]),
    Rust(out="gen/rust", features=["lazy", "path_query"]),
], wire_format_version=1)
```

`dagr build` then generates, per language, an **arena**-backed typed API (no reference
cycles to leak, value-type handles), byte-exact serialization and restore, and optionally
zero-allocation **lazy accessors**, **path queries** that read one field straight out of a
buffer, and an **explain** tool that annotates every byte. The generated code has no runtime
dependency — the runtime is emitted alongside it.

## Why Dagr

- **Graphs, not trees.** Cycles, back-references and shared nodes serialize naturally; the
  arena model is what makes that safe in every target language.
- **One schema, seven languages, identical bytes.** Swift, Rust, TypeScript, Go, Mojo, Odin
  and Python read and write the same buffers; a cross-language test corpus of ~1000 fixture
  permutations gates every change byte-for-byte.
- **Four node layouts to choose from.** Regular (vtable, evolvable), packed (compact),
  frozen (fixed-offset, O(1) reads) and frozen+packed — per node type, per schema
  (`spec/16-choosing-a-node-layout.md`).
- **More than graphs.** `DataSink` is an append-only record stream with the same type system
  (logs, event streams, attestable audit trails); `SharedBuffer` is a fixed-layout overlay for
  IPC, GPU and no-allocation embedded use, with seqlock, ring and double-buffer strategies.
- **Tooling around the format.** Schema import from `.proto`, FlatBuffers, JSON Schema and
  ASN.1; generation receipts and compatibility checks (`dagr check`); a browser schema editor
  (`dagr ui`); self-contained HTML explorers for any buffer; git diff and three-way merge
  drivers; an ImHex pattern exporter; a fuzzer; Arrow producers.

## Install

The tool is pure Python 3.9+ with no dependencies.

```bash
pip install dagr-cli            # or: uv tool install dagr-cli;  from a checkout: pip install -e .
dagr init --name my_schema      # scaffolds schema.py + pyproject.toml
dagr build                      # generates every target in Library.targets, writes dagr.lock.json
dagr check                      # diffs the schema against the committed receipt
```

Compiling and running the generated code needs the respective toolchain (Swift 6.2, Rust
1.85+, Node 20+, Go 1.22+, Mojo 1.0 via pixi, Odin). Generating never does.

## Targets

| Target | Arena + serde | Lazy | Path query | Explain | DataSink | SharedBuffer | Notes |
|---|---|---|---|---|---|---|---|
| Swift | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | primary target |
| Rust | ✓ | ✓ | ✓ | ✓ (tooling) | ✓ | ✓ | primary target; `no_std` tiers, Arrow, fuzz, git tools |
| TypeScript | ✓ | ✓ | – | – | ✓ | ✓ | HTML explorers are generated TS |
| Go | ✓ | ✓ | – | – | ✓ | ✓ | direct builder; `io.Writer` sinks; `sync/atomic` SharedBuffer strategies |
| Mojo | ✓ | ✓ | ✓ | – | ✓ | ✓ (+GPU) | |
| Odin | ✓ | ✓ | – | – | ✓ | ✓ | |
| Python | ✓ (reflective) | – | – | – | ✓ | ✓ (numpy zero-copy) | plus a native Arrow target |

## Documentation

- `spec/` — the numbered wire-format specification and design plans; start with
  `spec/README.md`, then `spec/01-motivation-for-arenas.md`.
- `docs/technical-feature-overview.md` — every feature with an engineering assessment.
- `examples/` — worked examples: an attested audit log, JWT-shaped tokens, a structured log
  sink, a package registry, stress graphs, a Swift↔Rust FFI demo.
- `CONTRIBUTING.md` — repository layout, toolchains, and the generate → test loop.

## Repository layout

```
dagr/        the Python package: DSL, config, CLI, code generators, importers, runtime, web UI
spec/        numbered specification documents
targets/     per-language runtimes, example packages and generated test crates
tests/       test generators, runners, unit tests, fixture schemas and (generated) fixture corpora
examples/    worked examples built with `dagr build`
benchmarks/  micro-benchmarks
site/        showcase site and spec-document generators
docs/        prose documentation, blog posts, images
```

Generated code is not committed. After cloning, run `./regen_all.sh` once to emit every
generated source, fixture and test suite (see `CONTRIBUTING.md`).

## Status

Dagr is used in production-style projects by its author and is versioned by CalVer
(`2026.9.0`); the wire format is versioned separately per schema (`wire_format_version`) and
checked by `dagr check`. Swift and Rust are the most complete targets; see `CHANGELOG.md` for
what changed and `spec/30-deferred-codegen-gaps.md` for known gaps per target.

## License

Apache License 2.0 — see `LICENSE`.
