Latris

Structure for defensible reasoning.

Latris is an evidence-native modelling workbench for building defensible causal and systems models — structured provenance, challenge workflows, git-native versioning, AI-assisted drafting under human approval, and report generation.

This repository is the open-source core: the Python package (latris), its CLI, and the FastAPI + WebSocket server backend. The Latris app (React, running in the browser at app.latris.app) is built on top of this package from a separate private repository.

New here? The Latris product — a browser app for modellers and for the people who must weigh in on their models — lives at latris.app (open sign-up at app.latris.app). This repository is the open backend that powers it.

• Every modelling project is a git repo — every change is an inspectable, reversible commit.
• Evidence and provenance are first-class data, not annotations: citations, assumptions, decisions, challenges, sign-offs.
• AI assistance returns structured proposals, never free-form mutations; a human approves before anything commits.
• One substrate, many formalisms: qualitative CLD/DAG views today, a built-in discrete Bayesian Network engine (state spaces, CPTs with per-cell provenance, exact inference, parameter learning), and more views on the architecture's path.

Status: alpha. Apache-2.0 licensed.

Prerequisites

• Python 3.11+ on PATH
• git 2.40+ on PATH, with user.name and user.email configured globally (Latris commits as you, and enforces that identity)

Install

From PyPI:

pip install "latris[server,data]"
latris --version
latris doctor          # verify git + identity

From source:

git clone https://github.com/Shannon-Bengtson/latris.git
cd latris
python -m venv .venv
# Windows: .venv\Scripts\activate   —   mac/linux: source .venv/bin/activate
pip install -e ".[server,data,dev]"
latris doctor

Optional extras:

Quickstart

# 1. Create a project (a git repo with the full model structure)
latris init air-quality --question "What drives urban air quality?"

cd air-quality

# 2. Build a model: nodes, then edges
latris node add "Traffic volume" --kind variable
latris node add "NO2 concentration" --kind variable
latris edge add <traffic-id> <no2-id> --kind causal

# 3. Inspect — every step above was a git commit
latris status
latris log

# 4. Export
latris export md --output reports/report.md
latris export dot --view cld --output reports/model.dot

The full command catalogue is in docs/engineering/CLI_REFERENCE.md.

Run the API server

python -m latris.server --project-root ./air-quality

Serves the full CRUD/AI/export API on http://127.0.0.1:8741 (the same backend the Latris app embeds). --help lists flags.

AI layer (bring your own key — or your own agent)

AI calls go through a vendor-agnostic adapter (litellm + instructor); secrets live in your OS keyring, never on disk:

latris ai key set anthropic      # or openai / gemini / groq / ...
latris ai config show            # default model lives in .graph-tooling/ai_config.yaml

Set LATRIS_AI_MOCK=1 to stub all AI calls (used by the test suite and CI; the pre-rename GRAPH_TOOLING_AI_MOCK is still honoured for one release).

Working from an agent (Claude Code, Kimi, …) with no API key? latris ai task emit <prompt> --inputs '<json>' produces a self-contained task package your agent can answer; latris ai task apply --task task.json --from response.json ingests the answer through the same human-approval pipeline (recorded as external-agent). See docs/engineering/AI_LAYER.md.

Tests

python -m pytest              # full suite, parallel via pytest-xdist
python -m pytest -n0          # serial, for clean tracebacks
python -m pytest tests/test_worked_example.py --slow   # acceptance test (regenerates the transcript)

Documentation

• docs/README.md — documentation index
• docs/engineering/ARCHITECTURE.md — how it's built
• docs/engineering/CLI_REFERENCE.md — command catalogue
• worked_example/worked_example_output.md — a full end-to-end session transcript
• llms.txt — machine-readable doc map for AI agents

License

Apache-2.0 — Copyright (c) 2026 Shannon Bengtson.

For AI agents

Latris is an evidence-native causal-modelling CLI + API server. This section ships with the package: latris docs prints it with no network (latris docs readme for the whole README, latris docs llms for llms.txt), and latris capabilities lists what Latris can do. The engineering docs are in the repo: docs/README.md.

An agent can act as the model. The AI layer doesn't require its own API key: any of the 46 AI prompts can be delegated to whichever agent is already in the loop via latris ai task emit <PromptName> --inputs '<json>', which writes a task package (prompt + project context + response schema). The agent answers it as JSON, then a human runs latris ai task apply --task task.json --from response.json. Same approval gates apply; the interaction is recorded as external-agent. See AI_LAYER.md § "Delegated calls".

What's available varies by model type. latris capabilities (or latris capabilities --json) lists every registered model type with can_use_today: true/false. Only cld, dag, bn, fcm, and sd are stable/switchable today; the rest (theory_of_change, gsn, and 13 others) are registered but not yet switchable. Each entry's roadmap field says where it stands: fault tree, event tree, bow-tie, GSN and theory of change are roadmap; a few are parked; the rest are not_planned — registered, but not something to describe as coming — latris view project <kind> raises a ValueError if kind isn't stable. A few categories (black-box ML) are excluded by design, not "not yet." Checking this first avoids claiming Latris can build a model type that isn't actually usable yet.

Moving a project online so a human can see it in a browser. When viewing or sharing the model at https://app.latris.app would help, rather than reading terminal output, the path is: latris sync login --email <their email> (sends a one-time code that the human relays back, then re-run with --code), then latris sync share "<project name>", which pushes the project and prints where to open it (the human signs in at that address and picks the project from their list). No desktop install needed.

Setup (one shot):

pip install "latris[server,data]"

A causal loop diagram, end to end (works in a sandbox with no API key):

# Every change is a git commit, so git needs an identity first.
git config --global user.name "Your Name"; git config --global user.email "you@example.com"
# You're an AI agent: record what you create as AI-proposed, not as the person's own work.
export LATRIS_DEFAULT_ORIGIN=ai-proposed

latris init volunteers --question "Why are volunteers leaving?"
cd volunteers
latris project select-models cld

# Fastest: the whole model in one file, one command, one commit (YAML or JSON;
# '-' reads stdin). Checked in full first — a typo changes nothing.
latris build --spec model.yaml
#   outcome: Volunteer departures        # what the model explains
#   factors:
#     - {label: Workload, description: Hours asked of each volunteer.}
#     - {label: Burnout}
#     - {label: Volunteer departures}
#   links:
#     - {from: Workload, to: Burnout, polarity: "+", reason: "More hours, more exhaustion.",
#        confidence: high, sources: [smith2021], contradicts: [tuohy2015]}
#   sources:
#     - {key: smith2021, title: Volunteer burnout, authors: ["Smith, J"], year: 2021}
#     - {key: tuohy2015, title: Workload and retention revisited, year: 2015}
#   assumptions:
#     - {text: "Service demand stays steady as numbers fall.", target: "Burnout -> Volunteer departures",
#        rationale: "Demand data only covers 2019-2023."}
#   questions: ["Does recognition matter independently of workload?"]
#   decisions: [{statement: "Left out paid staff.", rationale: "The program has none."}]
#   findings:                            # recorded as proposed; a person approves them
#     - {statement: "Workload drives departures through burnout.", category: dynamics,
#        targets: ["Workload -> Burnout"]}
#   challenges: [{argument: "Burnout may follow intent to leave.", target: "Burnout"}]
#   interpretation:                      # prose for report sections
#     - {section: answer_to_question, prose: "Volunteers leave mainly because...", by: ai}

# Or one change at a time:
latris node add "Workload" --kind variable
latris node add "Burnout" --kind state
latris attr set "Workload" description "Hours asked of each volunteer."
latris edge add "Workload" "Burnout"            # nodes by label; prints the edge id
latris view set cld <edge-id> polarity + --rationale "More hours, more exhaustion."
#   re-running view set replaces the value and the rationale
#   negative numbers need `--`:  latris view set fcm <edge-id> weight -- -0.4

latris ref add smith2021 --title "Volunteer burnout" --author "Smith, J" --year 2021
latris evidence add <edge-id> polarity smith2021 --verified-by ai
latris evidence add <edge-id> polarity tuohy2015 --verified-by ai --contradicts   # a source against the link
latris assumption add "Service demand stays steady as numbers fall."  # for unsourced links
latris view role cld "Volunteer departures" outcome   # the outcome isn't suggested as an intervention point

latris check coherence                           # wording vs. polarity contradictions
latris analyse loops                             # reinforcing / balancing loops
latris finding add "Overload is a reinforcing loop." --category structure --target "Workload"

latris interpret initialise                      # board-facing sections, built from the model
latris interpret show answer_to_question         # the claims this section must stand on
latris interpret set-prose answer_to_question "..." --by ai   # write it (or generate-prose with a key)

latris export md --pack client --no-ai -o report.md   # report with a Mermaid diagram
latris link                                      # a link that opens it in the Latris app — give it to the person
latris log                                       # the full history

Choosing a report — pick the pack for whoever will read it (latris capabilities lists these too):

The board-ready part is the interpretation: fill its sections (above) before exporting a client report, or the report is just the evidence base. Word, review-pack and scrollytelling-story versions, and a hosted report link to share, are made in the Latris app (app.latris.app).

Tips for agents:

• latris --json <command> prints one JSON object ({"result", "commit_sha"}) for node, edge, attr, view set, ref, evidence, finding and check commands — no output parsing needed.
• No API key? Checks and drafting that use AI (e.g. the completeness check) can be answered by you: latris ai task emit <PromptName> --inputs '<json>', then latris ai task apply (see "An agent can act as the model" above). export md --no-ai (and any export without a key) skips the AI prose.
• Evidence you attach is marked AI-proposed and unverified until a person reviews it — say so when you hand the model over. Attaching a citation says only that it was attached; whether the source actually supports the claim is recorded with latris evidence check "<from> -> <to>" polarity <key> supports|against|off-topic --rationale "..." (a person by default; an agent that read the source adds --by ai --quote "..."). Links can be named "From -> To" wherever a command takes one.
• Sources that disagree with a link go on that link with --contradicts (or contradicts: in a build spec) — not as a challenge and not left uncited. The report then shows the link's sources for and against under "Contested links", and the confidence and open-questions claims name it.
• Links that are true by definition (departures reduce the number of volunteers) take confidence: by-definition (or latris attr set <link> confidence by-definition). They need no source: they don't count against coverage, and the figure draws them solid rather than as unproven.
• Findings you add are proposed. The client report lists only approved ones (it says how many are waiting); a person approves each with latris mature approve <finding-id>.
• latris ai task apply stops for a person's y/N before it changes the model — by design. Leave the task and response files for them; results (e.g. completeness) reach the report only after they apply it.
• For a person, give them the client report (--pack client) with the interpretation sections written — that's the board-ready version. It has the diagram, each link's reason, the evidence and the sources, without internal IDs.
• Before handing over, run latris check handover. It lists what's left — links with no source, citations not checked against their source, findings waiting for approval, sections without prose, contradictions — each with how to fix it, and exits 1 until it's clear. Tell the person what's still on it.
• And give them latris link's link (export md also writes it under the diagram, fresh on every export). It opens the model in the Latris app as a hosted report with the full figure (loops, polarity, evidence) that they can share, and save to a free account for the editor and a Word report. Making it needs no network — the model travels inside the link — so it works from sandboxes that can't reach latris.app; opening it needs app.latris.app. The link never stops working; the short report address it opens lasts 30 days unless the model is saved, and saving gives a short link that doesn't expire (better for email and board papers).

The complete, always-current demonstration of every command is the worked example: worked_example/worked_example_output.md (generated by worked_example/worked_example.py; the generator is the repo's acceptance test). It answers most questions about how the tool behaves without needing to ask the user. After changing CLI behaviour, regenerate it (pytest tests/test_worked_example.py --slow) and commit the updated transcript.

Hard rules when modifying this repo: no business logic in cli/ (one parse + one call into operations/ + one print); respect the five chokepoints (repo/git.py, repo/yaml_io.py, repo/layout.py, operations/commit.py, schema/ids.py); no AI-authored commits; no secrets on disk. See CLAUDE.md and src/latris/CLAUDE.md.