Run an AMT file and look at the result

From nothing to a graph in your browser: what to install, what to clone, where to put your file, which command to type and where the result appears. The commands are for the Windows command prompt; Linux and macOS differences are noted.

1. What you need
2. Get the runner
3. Put your file somewhere
4. Check it
5. Run it
6. Find the result
7. Look at the graph
8. Or use the Explorer
9. Change the file and run again
10. If something goes wrong

1. What you need

Two programs, once:

Python 3.10 or newer. Check with python --version (on Windows py --version also works).
git. Check with git --version.

Nothing else: the runner fetches the engine and installs the three Python packages it needs (rdflib, pyshacl, pyvis) the first time you run it.

2. Get the runner

Open a command prompt in the folder where you keep your projects (for example C:\git) and clone the runner:

git clone https://github.com/alpaca-fair-framework/amt-runner.git

cd amt-runner

Optional, but tidy: keep the packages out of your global Python with a virtual environment.

python -m venv .venv

.venv\Scripts\activate

Linux and macOS: source .venv/bin/activate. On recent Debian and Ubuntu a virtual environment is required.

3. Put your file somewhere

Anywhere you can name by path. Two easy choices:

Next to the runner: copy my.ttl into the amt-runner folder and use my.ttl in the commands below.
Anywhere else: keep it where it is and give the path, for example C:/tmp/my.ttl (forward slashes work on Windows; put the path in quotes if it contains spaces).

The results are not written next to your file but into amt-runner\out\ (section 6). No file of yours is changed.

Not sure your file is an AMT file yet? How to build an AMT file has a complete one to start from.

4. Check it

This validates and diagnoses and writes nothing, so it is the command to repeat while you build:

python run_amt.py my.ttl --check-only

The first time it also clones the engine into .amt-cache\ and installs the packages, which takes about half a minute. You should see OK Validation passed. and a count such as 2 Concepts | 0 Roles | 11 Nodes | 7 Edges | 0 Axioms. If it prints ERR lines, fix them first: how to check an AMT file explains each one.

Use --update now and then, and always after someone tells you the engine has changed. The runner keeps its own copy of the engine and does not update it by itself:

python run_amt.py my.ttl --check-only --update

5. Run it

The same command without --check-only:

python run_amt.py my.ttl

It validates, loads, checks consistency, infers new edges with your axioms (none if you have no axioms), and writes the result. The last lines of the output name the folder:

✓ Outputs written to C:\git\amt-runner\out\run-20261027-130638
  (also accessible via C:\git\amt-runner\out\latest)

6. Find the result

Every run gets its own folder out\run-<date>-<time>\, so earlier results are kept. out\latest\ always points at the newest one. The files are named after your file:

File	What it is
`…reasoned.ttl`	Your graph plus everything the rules inferred, as Turtle. Load this one into the Explorer.
`…html`	The interactive graph. Double-click it; it opens in your browser and works offline.
`…report.md`	A readable record of the run: validation, diagnostics, counts, every inferred edge, options.
`…nodes.csv`	One row per node, for spreadsheets.
`…edges.csv`	One row per edge with its weight, whether it was inferred, which axioms produced it, and its type and method (empty if there is none).
`…cypher`	The same graph as Neo4j Cypher statements, if you want it in a graph database.

7. Look at the graph

Open out\latest\my.html by double-click. What you see:

One dot per node, coloured by its concept: all nodes of the first concept in orange, the second in blue, and so on.
Arrows are edges, labelled role: weight. The thicker the arrow, the higher the weight.
Red dashed arrows are edges the engine inferred from your axioms. Black ones are what you wrote.
A grey dot is an IRI that an edge points to but that was never declared as a node. That is the problem AMT-E101 reports; add an amt:instanceOf for it.
Hover over a node for its concept, over an edge for asserted or inferred. Drag nodes to rearrange them, scroll to zoom.

8. Or use the Explorer

The AMT Explorer loads a Turtle file and shows it in your browser. Open it, press the folder button and choose out\latest\my.reasoned.ttl. It opens in your browser; the file is not uploaded anywhere.

9. Change the file and run again

Edit my.ttl.
python run_amt.py my.ttl --check-only until it is clean.
python run_amt.py my.ttl for a new result in a new folder under out\.

Old run folders are never deleted by the runner. Delete the ones you do not need.

10. If something goes wrong

'git' is not recognized / 'python' is not recognized: The program is not installed or not on the PATH. Install it, open a new command prompt and try again. On Windows py run_amt.py my.ttl may work where python does not.
FAIL The cached AMT.engine does not know --check-only: The engine copy in .amt-cache\ is old. Add --update.
A Python traceback ending in AssertionError or something else: Almost always an old cached engine as well: add --update. If it stays, add --debug and open an issue at amt-engine with your file.
FAIL Validation failed: Your file is not valid AMT. Each message names the node and what to add: the messages explained.
ERR [AMT-E101] or another code: Your file is valid but does not say what you probably meant. The messages explained.
The graph is empty or has too few nodes: Look at the counts in the OK line and at the diagnostics; see the questions at the end of how to check an AMT file.
I have the engine installed and do not want the runner: With pip install -e . in a clone of amt-engine the same options work as amt-runner my.ttl --check-only and amt-runner my.ttl; the result goes into an out folder next to your file.