Metadata-Version: 2.4
Name: figurant
Version: 0.1.0
Summary: Synthetic organisational and identity data for testing identity governance
Keywords: synthetic-data,test-data,identity-governance,iam,hr,answer-key,reproducible
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
Classifier: Operating System :: OS Independent
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy<3,>=2.0
Requires-Dist: polars<3,>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-xdist>=3; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: complexipy>=3; extra == "dev"

# figurant — synthetic HR and identity data for testing identity governance

A reproducible generator of organisations that look like real ones: an org tree,
people with Dutch names and plausible ages, employments and registrations over a
history, accounts on several systems, and **an answer key** so a consuming system
can be *scored* rather than eyeballed.

It is an **exporter, not a connector**. It writes files that resemble what a source
system holds; it never reads from or writes into a live directory or HR system, and
it has no code path that can be pointed at real data. No organisation it produces is
recognisable as a real one, and no national identifier is produced in any mode.

```bash
pip install -e .
figurant --scenario examples/acme-small.toml --out ./set
```

That is a 400-person installer with its answer key, from a declaration you can read
in one screen. Three ship to start from: `examples/acme.toml` (the full one),
`examples/acme-small.toml` (the same organisation, smaller and faster) and
`examples/loop.toml` (four weeks of one organisation, for the simulation loop).

Nothing is on by default. A set is clean until a declaration asks for a fault, a
malformed value or a policy breach — so a clean set is the control that proves a
consumer is not reporting problems that are not there.

## The sixty-second version

```bash
# 1. Generate, and serve it where a consuming system can reach it
figurant --simulation examples/loop.toml --run ./run --reference 2026-10-12 --step 0
(cd run/current && python3 -m http.server 8080)   # GET /json/index.json

# 2. Import it. Then say next, and import the same URL again
figurant --simulation examples/loop.toml --run ./run --reference 2026-10-12 --next

# 3. Reconcile backwards instead of reloading
figurant --simulation examples/loop.toml --run ./run --reference 2026-10-12 --revert
```

`--reference` is the anchor every step counts back from, and it is required rather
than defaulted: nothing in the package reads the clock, so running the loop in a
later week is `--reference "$(date -I)"` at the call site and the whole loop shifts
with it — the same people, the same units, every event date moved.

`run/current/` is the same path at every step, so a consuming system is pointed at it
once and never reconfigured, and `run/feed/` holds what changed since the last step —
in both directions, so a revert is a reconciliation rather than a reload. Next week
the same declaration, anchored seven days later, replays the same situations against
the same organisation. See [the loop](docs/loop.md).

## What you get

Sixteen tables — the organisation tree, people, employments over a history, teams,
and the access layer of systems, accounts, resources and assignments — written as
CSV, JSON pages, NDJSON, Parquet or a WireMock stub. Beside them, in `set/key/`, a
**separate** answer key: every planted fault with the value the data held before,
every malformed value and what it replaced, which personnel numbers belong to one
human, and the right answer for every copy of every attribute rather than only the
wrong ones. Full tables and formats in [the output](docs/output.md).

## Where to go

| you want to… | read |
|---|---|
| start from nothing, write your own declaration, and share it so a colleague gets the same people | [getting started](docs/getting-started.md) |
| see a real set and what each part of it is for | [the walkthrough](docs/walkthrough.md) |
| decide which organisation comes out | [declaring an organisation](docs/organisations.md) |
| feed a system the same set over and over, with changes | [the loop](docs/loop.md) |
| ask for the situation you came to test | [scripting a case](docs/cases.md) |
| know what the files hold, and score a tool against the key | [the output](docs/output.md) |
| look up an option, a fault family or a dirt kind | [the reference](docs/reference.md) |
| know what every entity and field of the export holds | [the schema](docs/schema.md) |
| point a product's collector at a set, field by field | [the consumer mapping](docs/mapping.md) |
| load a set into a database | [importing](docs/import.md) |
| know what this tool will not do, and what to do instead | [for a consuming product](docs/consumers.md) |
| work on the tool itself | [development](docs/development.md) |

The walkthrough is the place to start if you have not seen a set before: it goes
through one, defect by defect, and says what each is a test of.

## What it is built against

`docs/requirements.md` holds every requirement, each with how to verify it and —
where one was settled by measurement — the number that settled it.
`tests/TRACEABILITY.md` records which requirement each test covers, and
`tools/check_requirements.py` fails when one is covered by nothing.

[The case mapping](docs/conformance.md) records which set carries which scorable case, because the cases
live across sets rather than within one: a clean set is the control, so the faults are
in another.

Three more records exist because a claim nobody measured is a claim:
[platforms](docs/platforms.md) (the same set on Windows and Linux, hash for hash),
[importing](docs/import.md) (PostgreSQL accepting 46,290 rows with every foreign key
in place) and [the mutation score](docs/mutation.md) (what the suite detects when
faults are injected into the generator on purpose).
