Phony Documentation

Phony turns a small schema into realistic fake data — names that sound right for a locale, valid emails composed from them, coherent addresses, chronological event timelines, referentially-intact foreign keys — that looks real without being real. It's N-gram-powered (no LLM), and the same schema + seed produces byte-identical data on every run and every machine.

This is the technical documentation. The full internal design and specification (including roadmap features) lives in the Spec.

Sections

Section	What it covers
The PGDL Language	what PGDL is, the schema, every generator, the expression language, and how generation works
Concepts	the ideas — determinism, the generator types, locales
The engine (Rust)	phony-core: install, call a generator, and the full Rust API

New to PGDL? Start with What is PGDL?. Want to call a generator now? See The engine → Quick start.

What's built today

• A phony CLI — train an N-gram model from a word/phrase/prose list, then generate values from a PGDL definition or a registered generator, as JSON or NDJSON, under an explicit --seed and --reference-time. Plus info / validate / stats for inspecting .ngram models.
• A git-based package manager — install / add / remove / update / list: a package is just a git repo, resolved by minimal version selection, pinned to a commit in phony.lock, and cached in a content-addressed store. Installing never runs code.
• The full generator vocabulary — five core generators (Logic, List, Model, Statistical, Event Sequence) plus composition, including the repeat step for N items per parent and coherent multi-field records.
• A first-class agent surface — PGDL and PEL are plain JSON, hand- and tool-editable, and Git-diffable; determinism means an agent can write a test against generated data and have it stay green. No LLM in the loop.

The one-minute picture

PGDL defines generators — pure, deterministic producers of values:

{ "type": "model", "source": "person.first_names", "generation": { "mode": "word" } }

You feed a generator a seed and the engine returns a value — call it once, or a thousand times. Generators range from pure-algorithm IDs and numbers, to locale-aware names trained from samples, to compositions that build one generator out of others — see The core generators. Tables, foreign keys, and row counts aren't PGDL — they belong to the Phony cloud product, which consumes generators.

Project status

The PGDL language, the Rust engine, and the phony CLI (train / generate / info / validate / stats, plus the git-based package manager: install / add / remove / update / list) are implemented and documented here. Language libraries (PHP first, then JS/Python bindings) — and the product-style guides that come with them — are on the roadmap.