Reference SDK and verifier for the .aim document format — AI proposals and human accept/reject as file primitives
Reason this release was yanked:
Pre-release build published in error; superseded by 0.2.0 (pip install aimformat)
Project description
.aim — an open document format for human + AI co-authoring
Status: v0.1 draft — spec and reference tooling published, breaking changes possible until 1.0. Specification · Getting started · Examples
A .aim file is a single HTML document that is, at the same time:
- the rendered artifact — open it in any browser, styled, no tooling;
- the accepted current version — every block covered by a stable, uniquely-identified chunk that AI and tools can address;
- the pending-change lane — AI/human proposals carried in the file, visible to any reader, applied only on explicit accept;
- the full edit history — an append-only, invertible event log; any past version is reconstructible and verifiable against checkpoint hashes;
- derived caches — summary, TOC, embeddings, packed assets — that help agents but are never load-bearing.
Documents are increasingly written with AI, in formats designed for a
single human at a single cursor. Everyone building document workflows with
AI reinvents the same primitives: addressing a region of a document,
tracking which edits came from the model, letting a human accept or reject
them, proving what the document said before. .aim makes those primitives
part of the file format — open, editor-agnostic, MIT.
┌──────────────────────────── one .aim file ────────────────────────────┐
│ <head> summary + TOC cache · versioned stylesheet · theme │
│ <body> the accepted document (chunks + containers, renderable) │
│ <aim-proposals> pending AI/human changes + explanations │
│ <aim-assets> content-addressed packed images │
│ history append-only invertible event log (JSONL) │
│ embeddings per-chunk vectors w/ staleness hashes │
└────────────────────────────────────────────────────────────────────────┘
Install
pip install aimformat # zero runtime dependencies (stdlib only)
pip install 'aimformat[docx]' # + DOCX export (python-docx)
Sixty seconds
import aimformat as aim
doc = aim.new_document(title="Q3 Proposal")
me, bot = aim.human("ada"), aim.agent("model-id")
# direct edits append invertible history events
intro = doc.add_chunk("<p>We propose a three-year engagement.</p>", author=bot)
# the pending lane: propose → human decides
p = doc.propose_modify(intro.id,
f'<p data-aim="{intro.id}">Acme saves €2.1M over three years.</p>',
author=bot, explanation="Lead with the outcome.")
doc.accept(p.id, decided_by=me) # or .reject(...), or accept with tweaks
doc.checkpoint("sent-to-client") # pins a verifiable doc_hash
assert doc.verify() == [] # replay the log, check every hash
doc.save("proposal.aim") # canonical bytes; renders in a browser
aim lint proposal.aim # structure + vocabulary + security + history chain
aim show proposal.aim # chunks, pending lane, history at a glance
aim hash proposal.aim # current doc_hash
What makes this different from "HTML with extra attributes":
- Identity is part of the format. Chunk ids live in the file, edits target ids (never character offsets), and identity survives any tool.
- Byte-canonical serialization. Attribute order, class order, escaping, line structure — all specified. Equality is byte equality; diffs are string compares; no editor's parser is the arbiter of truth.
- The history verifies. Every state-changing event carries enough to
undo it;
verify()replays the log backwards and byte-compares every payload, catching out-of-band edits, and checks every checkpoint hash. - Provenance is first-class. Every event and proposal records its actor
(
human/agent+ exact model id /external), timestamp, batch, and a one-line explanation.
Interop: anything → .aim → DOCX
Ingest whatever docling can read (PDF, DOCX, PPTX, images, HTML) — without adding docling as a dependency of this package:
from docling.document_converter import DocumentConverter
import aimformat as aim
result = DocumentConverter().convert("contract.pdf")
doc = aim.from_docling(result.document) # chunks, lists, tables, figures
doc.save("contract.aim") # ingestion itself is history
Export back to Word — with the pending lane as real tracked changes
(w:ins/w:del, attributed to the proposing human or model), or resolved
with a caller-chosen default:
aim.to_docx(doc, "out.docx", pending="tracked") # reviewable in Word
aim.to_docx(doc, "out.docx", pending="accept-all") # resolved on a copy
aim.to_docx(doc, "out.docx", pending="reject-all")
The API in one table
| load / create | load, loads, new_document, doc.save, doc.dumps |
| read | doc.chunks, doc.chunk(id), doc.containers, doc.proposals, doc.history, doc.meta, doc.theme, doc.doc_hash, doc.seq |
| direct edits | add_chunk, modify_chunk, delete_chunk, move_chunk, set_theme, doc.batch() |
| pending lane | propose_modify/add/delete/move/theme, accept (with optional applied= tweaks), reject; supersede and chain rebinding are automatic |
| history | verify, state_at(seq), checkpoint, undo, redo, flatten, prune, reconcile (repair out-of-band edits / adopt hand-written files) |
| caches | set_summary, generate_toc, set_embedding, stale_embeddings |
| assets | pack_assets (data-URIs → content-addressed registry), gc_assets |
| interop | from_docling, to_docx |
| verifier | lint, lint_text, lint_path → Finding(code, level, message, where) |
Actors: aim.human("ada"), aim.agent("model-id"), aim.external("tool").
Format at a glance
The specification is one file, and it is executable: every
```aim snippet in it is linted in CI, the construct reference appendix
is generated from the same registry that
drives the linter and the stylesheet, and the conformance suite
(tests/fixtures/) pins every rule with an ok_* /
nok_<CODE>_* file pair that third-party implementations can reuse.
Design pillars (details and rationale in the spec):
- HTML + a closed Tailwind-vocabulary subset — models read and write it accurately; a finite vocabulary plus one versioned stylesheet kills cross-model drift; every browser renders it for free.
- Semantic chunking — chunk boundaries are authorial; the chunk is the unit of meaning, retrieval, edit targeting, and explanation.
- Propose/accept as file primitives — with persisted attribution,
explanations, accept-with-tweaks (
appliedvsproposed), and deterministic supersede/chain semantics. - Docs and slides in one format — slides are fixed-canvas containers of positioned chunks; same proposals, same history.
- Security as conformance — no script, no event handlers, no dangerous
URL schemes, enforced by the linter (
aim lintis the gate).
Repository map
spec.md |
the normative specification (single file, executable snippets) |
src/aimformat/ |
reference SDK: document ops, verifier, canonical form, CSS generator, ingest/export |
src/aimformat/registry.json |
the machine-readable vocabulary — single source for linter, stylesheet, spec appendix |
tests/ |
310+ tests; tests/fixtures/ is the conformance suite |
examples/ |
worked documents, generated by the SDK (readme) |
scripts/ |
appendix/fixture/example generators |
docs/ |
contributor + agent memory (knowledge base and decision log) |
Planned next (tracked in the spec's Future Extensions): MCP server, reference viewer, PPTX export, pagination.
Relationship to Tndm
The format is maintained by Tndm, which builds a commercial editor on top of it — the same model as ProseMirror/Tiptap or Git/GitHub. The format itself is neutral ground: open, MIT-licensed, and designed to be adopted (and extended) by anyone, including other editors.
Contributing
See CONTRIBUTING.md — including how the registry,
generated appendix, fixtures, and executable spec snippets fit together.
AI agents: start at AGENTS.md.
License
MIT © Luca Campanella
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file aimformat-0.1.0.tar.gz.
File metadata
- Download URL: aimformat-0.1.0.tar.gz
- Upload date:
- Size: 169.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b8f42e65bba68cee5d0f6d21e5c693b2b473f6f75d2020bf6e991d2521cad37a
|
|
| MD5 |
dd6d9a730e7b5aaa953e24b5f2f80532
|
|
| BLAKE2b-256 |
d2fb54b80a8e748c3928f94a5e02da725d25ebfc1c3f5b5ce372dd352094ac5f
|
File details
Details for the file aimformat-0.1.0-py3-none-any.whl.
File metadata
- Download URL: aimformat-0.1.0-py3-none-any.whl
- Upload date:
- Size: 87.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9e45afa1d2301e3712a1311d8775181f58e8a2c22e126bd665a98534711b0739
|
|
| MD5 |
c0418511bc8fca45e4f7c07702d85aa4
|
|
| BLAKE2b-256 |
109571807115a173c3d0de306dcc6377275c7645f1a7a46ec58819377d5ed27f
|
