{ "components": { "schemas": { "BatchEffectRequest": { "properties": { "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ], "description": "Graph shared by every query." }, "observations": { "anyOf": [ { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "description": "Sample shared by every query.", "title": "Observations" }, "queries": { "items": { "$ref": "#/components/schemas/EffectRequest" }, "title": "Queries", "type": "array" } }, "required": [ "queries" ], "title": "BatchEffectRequest", "type": "object" }, "BatchEffectResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/EffectResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "BatchEffectResponse", "type": "object" }, "BatchInterventionRequest": { "properties": { "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ] }, "interventions": { "items": { "additionalProperties": { "type": "number" }, "type": "object" }, "title": "Interventions", "type": "array" }, "observations": { "anyOf": [ { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Observations" }, "samples": { "anyOf": [ { "maximum": 4096.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "title": "Samples" } }, "required": [ "interventions" ], "title": "BatchInterventionRequest", "type": "object" }, "BatchInterventionResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/InterventionResult" }, "title": "Results", "type": "array" } }, "required": [ "results" ], "title": "BatchInterventionResponse", "type": "object" }, "CounterfactualRequest": { "properties": { "factual": { "additionalProperties": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "number" } ] }, "description": "A complete assignment for the individuals of interest; every variable in the graph must appear.", "title": "Factual", "type": "object" }, "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ] }, "interventions": { "additionalProperties": { "type": "number" }, "title": "Interventions", "type": "object" }, "observations": { "anyOf": [ { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Observations" }, "targets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Targets" } }, "required": [ "factual", "interventions" ], "title": "CounterfactualRequest", "type": "object" }, "CounterfactualResult": { "properties": { "assumptions": { "items": { "type": "string" }, "title": "Assumptions", "type": "array" }, "counterfactual": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "title": "Counterfactual", "type": "object" }, "delta": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "description": "Counterfactual minus factual.", "title": "Delta", "type": "object" }, "factual": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "title": "Factual", "type": "object" }, "identification": { "additionalProperties": { "type": "string" }, "title": "Identification", "type": "object" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "uncertainty": { "additionalProperties": { "type": "number" }, "title": "Uncertainty", "type": "object" } }, "required": [ "factual", "counterfactual", "delta", "uncertainty", "identification", "assumptions", "provenance" ], "title": "CounterfactualResult", "type": "object" }, "DiscoverRequest": { "properties": { "observations": { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "title": "Observations", "type": "array" }, "threshold": { "default": 0.5, "description": "Edge probability cut-off.", "maximum": 1.0, "minimum": 0.0, "title": "Threshold", "type": "number" }, "variables": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Variable names, in column order.", "title": "Variables" } }, "required": [ "observations" ], "title": "DiscoverRequest", "type": "object" }, "DiscoverResult": { "properties": { "assumptions": { "items": { "type": "string" }, "title": "Assumptions", "type": "array" }, "edge_probabilities": { "items": { "items": { "type": "number" }, "type": "array" }, "title": "Edge Probabilities", "type": "array" }, "edges": { "items": { "additionalProperties": true, "type": "object" }, "title": "Edges", "type": "array" }, "graph": { "additionalProperties": true, "description": "The discovered DAG, serialised.", "title": "Graph", "type": "object" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "uncertainty": { "title": "Uncertainty", "type": "number" } }, "required": [ "graph", "edges", "edge_probabilities", "uncertainty", "assumptions", "provenance" ], "title": "DiscoverResult", "type": "object" }, "EdgePayload": { "properties": { "edge_type": { "default": "causal", "description": "causal or latent.", "title": "Edge Type", "type": "string" }, "source": { "title": "Source", "type": "string" }, "strength": { "default": 1.0, "title": "Strength", "type": "number" }, "target": { "title": "Target", "type": "string" } }, "required": [ "source", "target" ], "title": "EdgePayload", "type": "object" }, "EffectRequest": { "properties": { "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ] }, "observations": { "anyOf": [ { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Observations" }, "outcome": { "examples": [ "y" ], "title": "Outcome", "type": "string" }, "treatment": { "examples": [ "x" ], "title": "Treatment", "type": "string" }, "x0": { "description": "Baseline treatment value.", "examples": [ -1.0 ], "title": "X0", "type": "number" }, "x1": { "description": "Comparison treatment value.", "examples": [ 1.0 ], "title": "X1", "type": "number" } }, "required": [ "treatment", "outcome", "x0", "x1" ], "title": "EffectRequest", "type": "object" }, "EffectResult": { "properties": { "adjustment_set": { "items": { "type": "string" }, "title": "Adjustment Set", "type": "array" }, "assumptions": { "items": { "type": "string" }, "title": "Assumptions", "type": "array" }, "causal_paths": { "items": { "items": { "type": "string" }, "type": "array" }, "title": "Causal Paths", "type": "array" }, "confidence": { "description": "Zero when the effect is not identified from the graph.", "maximum": 1.0, "minimum": 0.0, "title": "Confidence", "type": "number" }, "effect": { "description": "E[Y | do(T=x1)] - E[Y | do(T=x0)].", "title": "Effect", "type": "number" }, "identification": { "description": "no_causal_path, no_backdoor_path, backdoor_adjustment or not_identified.", "title": "Identification", "type": "string" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "uncertainty": { "description": "Calibrated standard deviation of the estimate.", "title": "Uncertainty", "type": "number" } }, "required": [ "effect", "uncertainty", "confidence", "identification", "adjustment_set", "causal_paths", "assumptions", "provenance" ], "title": "EffectResult", "type": "object" }, "ErrorResponse": { "properties": { "detail": { "title": "Detail", "type": "string" } }, "required": [ "detail" ], "title": "ErrorResponse", "type": "object" }, "ExplainRequest": { "properties": { "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ] }, "outcome": { "title": "Outcome", "type": "string" }, "treatment": { "title": "Treatment", "type": "string" } }, "required": [ "treatment", "outcome" ], "title": "ExplainRequest", "type": "object" }, "ExplainResult": { "properties": { "adjustment_set": { "items": { "type": "string" }, "title": "Adjustment Set", "type": "array" }, "assumptions": { "items": { "type": "string" }, "title": "Assumptions", "type": "array" }, "causal_paths": { "items": { "items": { "type": "string" }, "type": "array" }, "title": "Causal Paths", "type": "array" }, "confounders": { "items": { "type": "string" }, "title": "Confounders", "type": "array" }, "identified": { "title": "Identified", "type": "boolean" }, "mediators": { "items": { "type": "string" }, "title": "Mediators", "type": "array" }, "open_backdoor_paths": { "items": { "items": { "type": "string" }, "type": "array" }, "title": "Open Backdoor Paths", "type": "array" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "reason": { "title": "Reason", "type": "string" }, "strategy": { "title": "Strategy", "type": "string" }, "unobserved_confounders": { "items": { "type": "string" }, "title": "Unobserved Confounders", "type": "array" } }, "required": [ "identified", "strategy", "reason", "adjustment_set", "causal_paths", "open_backdoor_paths", "mediators", "confounders", "unobserved_confounders", "assumptions", "provenance" ], "title": "ExplainResult", "type": "object" }, "GraphPayload": { "properties": { "edges": { "items": { "$ref": "#/components/schemas/EdgePayload" }, "title": "Edges", "type": "array" }, "variables": { "items": { "$ref": "#/components/schemas/VariablePayload" }, "title": "Variables", "type": "array" } }, "required": [ "variables", "edges" ], "title": "GraphPayload", "type": "object" }, "HealthResponse": { "properties": { "deterministic": { "title": "Deterministic", "type": "boolean" }, "max_variables": { "description": "Largest graph the model accepts.", "title": "Max Variables", "type": "integer" }, "model_version": { "title": "Model Version", "type": "string" }, "parameters": { "description": "Total trainable parameters.", "title": "Parameters", "type": "integer" }, "requires_llm": { "description": "Always false: inference is structural simulation.", "title": "Requires Llm", "type": "boolean" }, "requires_observations": { "description": "Always true for interventional and counterfactual queries.", "title": "Requires Observations", "type": "boolean" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "model_version", "parameters", "max_variables", "deterministic", "requires_llm", "requires_observations" ], "title": "HealthResponse", "type": "object" }, "InterventionRequest": { "properties": { "graph": { "anyOf": [ { "$ref": "#/components/schemas/GraphPayload" }, { "type": "null" } ] }, "interventions": { "additionalProperties": { "type": "number" }, "description": "Variable name to the value it is held at.", "examples": [ { "x": 1.0 } ], "title": "Interventions", "type": "object" }, "observations": { "anyOf": [ { "description": "Observational sample: one row per observation, columns in the order of the graph's variables.", "examples": [ [ [ 0.4, -1.2, 0.9 ], [ -0.7, 0.3, -0.1 ] ] ], "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Observations" }, "samples": { "anyOf": [ { "maximum": 4096.0, "minimum": 1.0, "type": "integer" }, { "type": "null" } ], "description": "Number of simulated individuals.", "title": "Samples" }, "targets": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "description": "Restrict the response to these variables.", "title": "Targets" } }, "required": [ "interventions" ], "title": "InterventionRequest", "type": "object" }, "InterventionResult": { "properties": { "assumptions": { "items": { "type": "string" }, "title": "Assumptions", "type": "array" }, "provenance": { "additionalProperties": true, "title": "Provenance", "type": "object" }, "samples": { "additionalProperties": { "items": { "type": "number" }, "type": "array" }, "title": "Samples", "type": "object" }, "std": { "additionalProperties": { "type": "number" }, "title": "Std", "type": "object" }, "values": { "additionalProperties": { "type": "number" }, "description": "Mean of each variable under do().", "title": "Values", "type": "object" } }, "required": [ "values", "std", "samples", "assumptions", "provenance" ], "title": "InterventionResult", "type": "object" }, "VariablePayload": { "properties": { "cardinality": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of categories for a discrete variable.", "title": "Cardinality" }, "name": { "title": "Name", "type": "string" }, "observed": { "default": true, "description": "An unobserved variable induces confounding that no adjustment set can block.", "title": "Observed", "type": "boolean" }, "selection": { "default": false, "description": "A variable the observational regime conditions on.", "title": "Selection", "type": "boolean" }, "variable_type": { "default": "continuous", "description": "One of continuous, binary or categorical.", "title": "Variable Type", "type": "string" } }, "required": [ "name" ], "title": "VariablePayload", "type": "object" } } }, "info": { "description": "Interventional and counterfactual inference over structural causal models.\n\nNo language model is involved. Answers come from explicit structural\nsimulation: mechanisms are evaluated in topological order, an intervention pins\nits variable and its equation is skipped, and counterfactuals run abduction,\naction and prediction over recovered exogenous terms.\n\n**Observational data is required** for `/effect`, `/intervene` and\n`/counterfactual`. A DAG says which structural equations exist, not what they\nare, and two systems sharing a graph can have opposite effects, so the service\ninfers each system's mechanisms from its own sample. Requests without a sample\nare rejected with `422` rather than answered with an invented mechanism.\n\n`/discover` needs only data, and `/explain` needs only a graph.", "title": "Causal Model", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/batch/effect": { "post": { "operationId": "batch_effect_batch_effect_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchEffectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchEffectResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Many effect queries against one system", "tags": [ "inference" ] } }, "/batch/intervene": { "post": { "operationId": "batch_intervene_batch_intervene_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInterventionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInterventionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Several do-queries against one system", "tags": [ "inference" ] } }, "/counterfactual": { "post": { "operationId": "counterfactual_counterfactual_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterfactualRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterfactualResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Unit-level counterfactuals by abduction, action and prediction", "tags": [ "inference" ] } }, "/discover": { "post": { "operationId": "discover_discover_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Infer a DAG from observational data alone", "tags": [ "structure" ] } }, "/effect": { "post": { "operationId": "effect_effect_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Average treatment effect with calibrated uncertainty", "tags": [ "inference" ] } }, "/explain": { "post": { "operationId": "explain_explain_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "How an effect would be identified, and through which paths", "tags": [ "structure" ] } }, "/health": { "get": { "operationId": "health_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "Successful Response" } }, "summary": "Service liveness and model metadata", "tags": [ "service" ] } }, "/intervene": { "post": { "operationId": "intervene_intervene_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterventionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterventionResult" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Malformed or incomplete query." } }, "summary": "Sample the interventional distribution P(V | do(...))", "tags": [ "inference" ] } } }, "tags": [ { "description": "Liveness and model metadata.", "name": "service" }, { "description": "Interventional, counterfactual and effect queries.", "name": "inference" }, { "description": "Graph discovery and identification analysis.", "name": "structure" } ] }