Metadata-Version: 2.4
Name: trama
Version: 0.1.0
Summary: JSON format for composable model graphs
Author: Victor Poughon
Author-email: Victor Poughon <victor.poughon@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Dist: pydantic>=2.13.4
Requires-Python: >=3.11
Project-URL: homepage, https://codeberg.org/victorpoughon/trama
Project-URL: repository, https://codeberg.org/victorpoughon/trama
Description-Content-Type: text/markdown

# Trama

Trama is a standalone Python library that defines a JSON schema, validator, and
export/import framework for hierarchical model graphs in Static Single
Assignment (SSA) style. It is framework-agnostic and is designed to be used by
domain-specific modeling libraries that inject their own op registries. Models
are serialized to self-contained `.trama.json` files capturing both topology and
parameter values, and can be reconstructed back into runtime modules via
registered factory functions.

## Installation

```bash
# With pip:
pip install trama

# Or with uv:
uv add trama
```

## Quick-start

```python
import trama

# Export a module that implements ExportableOp + ImportableOp.
model = trama.export_model(module, inputs=["x"], outputs=["y"], registry=registry)

# Serialize to JSON and save.
trama.dump(model, "my_model.trama.json")

# Later: load and reconstruct the runtime module.
model = trama.load("my_model.trama.json")
instance = trama.import_model(model, registry=registry)
```

## JSON Schema

Trama exposes a JSON Schema for `.trama.json` files. Generate it with the
`tramaschema` command:

```sh
tramaschema > trama.schema.json
```

The schema validates format structure: required fields, field types, and
identifier patterns. Registry conformance — whether op names resolve and
parameter types match — is not expressible in JSON Schema and is enforced at
load time in Python by `trama.load()` or `trama.validate()`.

## Design

For detailed description of the design of Trama please see [the design document](./.notes/trama.md).

## Compared to other model export formats

Trama operates at a fundamentally different abstraction level than ONNX,
`torch.export`, and similar formats. Those tools target deployment: they
decompose user-authored modules into low-level tensor operations (aten.matmul,
aten.conv2d, ONNX Gemm) so a runtime can execute them efficiently. The user's
`Sequential(Encoder(), Decoder())` becomes a flat sequence of primitive ops with
the original module boundaries dissolved. Trama instead targets composition: it
preserves the user-authored module hierarchy as first-class structure, captures
only the wiring between the building blocks the consumer library defines, and
treats those blocks as opaque ops whose semantics live in the registry. This
makes trama files dramatically smaller and more readable than ONNX graphs of
equivalent models, diffable in code review, and meaningful to humans inspecting
"what does this model architecture actually look like" — at the cost of being
unsuitable for cross-framework deployment, since the ops are defined by the
consumer library rather than a standardized vocabulary. Trama is complementary
to ONNX, not a replacement: a natural pipeline is to author and review models in
trama, then lower to ONNX or `torch.export` when shipping to inference.
