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.

	Open-source library (pip install "latris[data,quant]")	Latris app (app.latris.app — free account, nothing to install)
What it is	The engine and CLI: every analysis, a Markdown report with a Mermaid sketch, latris link	The hosted interactive report (typeset figure, result charts, interpretation — what a board reads), the visual editor, Word reports, review packs reviewers fill in, the scrollytelling story, saved models with short links

A latris link link is the shareable report: it opens the interactive report in the app. Send it as it is — no wrapper page or separate document.

• 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: causal loop diagrams and DAGs; fuzzy cognitive maps; a discrete Bayesian network engine (per-cell provenance, exact inference with hard and soft evidence, the most likely explanation, learning from data, sensitivity and Monte Carlo over the tables); and system dynamics (unit-checked equations, delays, scenarios, Monte Carlo bands, sensitivity and loop dominance). A causal loop diagram and an SD model can share one project: its loops include feedback through stocks.

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:

Extra	Brings in	For
server	FastAPI, uvicorn, pandas, scipy, pgmpy	The API server (python -m latris.server)
data	pandas, scipy	Dataset wrangling and statistics
quant	pgmpy	Quantitative inference (also in server)
dev	pytest, xdist, ruff, build	Running the test suite

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.

---

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗