COAT / Causal Representation Assistant
You have reviews and ratings, or images and diagnoses. COAT helps identify attributes to measure so you can analyze more than the variables already in your table.
Language models propose and measure candidate factors. Statistical feedback guides further discovery, causal-structure analysis and effect estimation.
The Python package provides text-based discovery interfaces. The paper also studies images and tool-based measurements.
“Very sweet apples, a rich aroma, but rather small.”
Define what each attribute means, then apply the rule to every review.
Examples
A factor is an attribute with a definition and measurement rule. Here sweetness has three levels: 0 for not sweet, 1 for mildly sweet and 2 for very sweet. Each review receives a value under the same rule.
Preset teaching example
A rich apple aroma, very sweet taste, and small apples that fit in my lunch box.
Sweetness explicitly described in a review.
The highlighted passage supports this level under the displayed rule.
Select a value to inspect its observation and rule. Try R03, then select Aroma: the review says nothing about aroma, so its value is missing rather than zero.
| Sample | Sweetness | Aroma | Size |
|---|---|---|---|
| R01 | |||
| R02 | |||
| R03 |
A visual attribute in a specified observation region.
Image crops come from the paper. Boxes and assignments are teaching cues, not segmentation, automated localization or clinical labels.
Select a value to inspect its observation and rule.
| Sample | Local brightness | Shape difference |
|---|---|---|
| M01 | ||
| M02 |
The company announced a new cloud technology platform and described its research team's work.
Distinguish routine maintenance from a new technical development.
The highlighted passage supports this level under the displayed rule.
Select a value to inspect its observation and rule.
| Sample | Technical progress | Market expansion |
|---|---|---|
| N01 | ||
| N02 |
A tool-based factor specifies what to read, where to read it and how to aggregate it. The code defines measurement; the model does not guess a temperature.
field = archive["air_temperature"].sel(
latitude=slice(-5, 5),
longitude=slice(210, 270),
)
factor = field.mean(("latitude", "longitude"))| Jan | Feb | Mar | Apr | May | Jun |
|---|---|---|---|---|---|
| 26.8 | 27.2 | 27.9 | 28.2 | 27.7 | 27.4 |
Preset teaching values, not live reanalysis. The code is illustrative, not a coatlearn database API. Real measurements need the data product's weighting and quality controls.
These teaching tables use selected levels to explain encoding. In the package, score values are probability-weighted averages of the declared levels; probabilities and confidence are separate metadata.
Teaching examples with preset values. Text highlights and image boxes are hand-authored observation cues, not evidence returned by the package. No model runs in this page. The paper explores text, images and tool-based measurements. The ready-to-use Python discovery interfaces take text columns; the image and climate examples illustrate the broader framework.
How COAT works
Knowing how to measure a factor does not tell you which factors you are missing. COAT links model-generated candidates with statistical analysis in a feedback loop.
A chat model reads selected observations and defines candidate factors.
An annotation model applies the same definitions across observations.
Conditional-independence tests ask what information remains after other variables are considered.
Statistical feedback directs the next proposal toward information the current factors leave unexplained.
“Similar measured attributes. Different ratings. What are we missing?”
Models interpret and measure. Statistical methods assess structure under assumptions.
Analysis goals
These are different goals. A useful predictor is not necessarily a cause, and an association is not the effect of taking an action.
A set that leaves other candidates with no extra target information once the set is given. Useful for later prediction and investigation; it can include effects as well as causes.
A graph representing structures that share conditional independencies. Adding factors can refine its endpoints; circles retain unresolved directions.
Seek variables that permit covariate adjustment under the graph and assumptions, then estimate the average treatment effect with inverse probability weighting.
Already know the factors? Annotate them directly. Already have measurements and a graph? Analyze them without another model call.
Get started
The supplied MB task uses Score and Review, allows five discovery rounds and records factor definitions with the selected set. Begin by inspecting its local configuration.
Use Python 3.11 or newer and install from PyPI. The installation guide prepares a small example directory with configuration and data; no repository clone or local GPU is needed for hosted models.
Installation and configuration setuppython -m pip install coatlearn
python -m coatlearn --helpInstallation starts no models. Follow the installation guide to download config/ and data/ into coat-example, then inspect the MB task without --run before execution.
Run from the prepared coat-example directory. This uses DeepSeek Flash to propose factors and hosted Jev to annotate and check definitions. Prepare DEEPSEEK_API_KEY and TYPESAFE_API_KEY first. Text is sent to those providers and calls may incur charges. Local Kev is an alternative.
Prepare model credentialspython -m coatlearn mb --config config/mb.toml --decision-model jev \
--run --output-dir runs/apple-mbimport json
from pathlib import Path
result = json.loads(
Path("runs/apple-mb/result.json").read_text()
)
print(result["diagnostics"]["final_blanket"])The list also includes the target Score. Factor definitions, settings and assumptions are saved with the result.
Follow the full tutorialMB and PAG share 1,000 synthetic apple reviews. ADJ uses 2,000 synthetic customer posts in a confounded email/visit study, not the original randomized Hillstrom table.
Available on PyPI as coatlearn. Software: Apache-2.0. The two example CSV files: CC BY 4.0, with attribution. Source repository
Research cases
The paper explores how new measured factors can sharpen a research question. These studies use additional domain-specific setups, not one-click package demos.
Climate / ENSO
A tool-using model defines regional measurements in NOAA reanalysis data. The study elicits 13 factors, recovers literature-consistent relationships and proposes a soil-temperature hypothesis for further investigation.
News / Microsoft
The study separates innovation, product, legal and strategic information. Factors discovered in the first 200 trading days are examined with strategies on the following 400 days, in one historical stock setting.
Causal conclusions depend on measurement, data and method assumptions. A completed run does not establish those assumptions; a missing estimate is not a zero effect.
The published work
Journal of Machine Learning Research
27(229):1–95, 2026
The journal extension adds COAT-PAG, COAT-ADJ and their identifiability analysis to the NeurIPS 2024 framework.
@article{JMLR:v27:25-2137,
author = {Chenxi Liu and Yongqiang Chen and Tongliang Liu and Mingming Gong and James Cheng and Bo Han and Kun Zhang},
title = {Discovering and Reasoning of Causality in the Hidden World with Large Language Models},
journal = {Journal of Machine Learning Research},
year = {2026},
volume = {27},
number = {229},
pages = {1--95},
url = {http://jmlr.org/papers/v27/25-2137.html}
}