Syl Guardian

Sanity-check a causal claim ("cause drove effect") before acting on it. Provide exactly one of ``csv`` (CSV text), ``data`` (list of row objects) or ``dataset_id`` (a dataset uploaded via ``guardian_request_upload``; use this for more than ~200 rows; single-use, deleted when reviewed) containing columns named by ``cause`` and ``effect``. Returns a verdict -- ``pass`` (act), ``caution`` (act carefully), or ``hold`` (do not act; the effect looks confounded or unsupported) -- with the naive correlational effect versus the confounder-adjusted causal effect and its confidence interval, the confounders adjusted for, a confidence score, a plain-English interpretation, and a recommended action. All numbers are deterministic statistics (never LLM-generated); only the interpretation prose may be AI-written. Args: cause: Treatment column the claim says drives the outcome (e.g. "ad_spend"). effect: Outcome column (e.g. "new_customers"). csv: Dataset as CSV text (header row required). data: Dataset as a list of row records (alternative to ``csv``). dataset_id: ID returned by ``guardian_request_upload`` after uploading the CSV (alternative to ``csv``/``data``; for datasets above ~200 rows). Single-use: the dataset is deleted when reviewed, so re-upload to retry. known_confounders: Columns to adjust for; otherwise discovered automatically. context: Free-text business context, e.g. "Q3 promo evaluation". units: Display-only unit hints by column, e.g. {"ad_spend": "USD"}. step: A concrete treatment step (e.g. 1000 for a $1,000 spend increase) to restate the effect in business terms (cost per incremental outcome, ...). time_col: Column to order rows by for time series (autocorrelation-robust standard errors and adstock). adstock: Opt-in geometric-adstock transform for a lagged/carryover treatment. se: Standard-error flavor; "auto" diagnoses autocorrelation when ``time_col`` is given. test_design: ``true`` (or an options object) also returns how many periods a spend-cut test needs to confirm the effect.

{
  "type": "object",
  "properties": {
    "cause": {
      "title": "Cause",
      "type": "string"
    },
    "effect": {
      "title": "Effect",
      "type": "string"
    },
    "csv": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Csv"
    },
    "data": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Data"
    },
    "dataset_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Dataset Id"
    },
    "known_confounders": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Known Confounders"
    },
    "context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Context"
    },
    "units": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Units"
    },
    "step": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Step"
    },
    "time_col": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Time Col"
    },
    "adstock": {
      "anyOf": [
        {
          "$ref": "#/$defs/AdstockOptions"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "se": {
      "default": "auto",
      "enum": [
        "nonrobust",
        "HC1",
        "HAC",
        "auto"
      ],
      "title": "Se",
      "type": "string"
    },
    "test_design": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "$ref": "#/$defs/TestDesignOptions"
        }
      ],
      "default": false,
      "title": "Test Design"
    }
  },
  "required": [
    "cause",
    "effect"
  ],
  "$defs": {
    "AdstockOptions": {
      "description": "Opt-in geometric-adstock transform for a lagged/carryover treatment.\n\nMirrors `syl_causal_core.adstock.AdstockSpec`; the decay search itself (when\n`decay` is omitted) is run deterministically by `syl-causal-core`, never here.",
      "properties": {
        "time_col": {
          "description": "Column to sort by before applying the adstock transform.",
          "title": "Time Col",
          "type": "string"
        },
        "decay": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fixed decay in [0, 1). Omit to grid-search it by AIC.",
          "title": "Decay"
        },
        "grid": {
          "anyOf": [
            {
              "items": {
                "type": "number"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Candidate decay values to grid-search when `decay` is omitted.",
          "title": "Grid"
        }
      },
      "required": [
        "time_col"
      ],
      "title": "AdstockOptions",
      "type": "object"
    },
    "TestDesignOptions": {
      "description": "Tuning for the opt-in spend-cut test design (`syl_causal_core.design_spend_test`).",
      "properties": {
        "cut_fraction": {
          "default": 0.5,
          "description": "Fraction of baseline spend to cut.",
          "exclusiveMinimum": 0,
          "maximum": 1,
          "title": "Cut Fraction",
          "type": "number"
        },
        "detectable_multiplier": {
          "default": 1.2,
          "description": "Size the test to detect this multiple of the fitted effect.",
          "exclusiveMinimum": 0,
          "title": "Detectable Multiplier",
          "type": "number"
        },
        "alpha": {
          "default": 0.05,
          "exclusiveMaximum": 1,
          "exclusiveMinimum": 0,
          "title": "Alpha",
          "type": "number"
        },
        "power": {
          "default": 0.8,
          "exclusiveMaximum": 1,
          "exclusiveMinimum": 0,
          "title": "Power",
          "type": "number"
        }
      },
      "title": "TestDesignOptions",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "title": "guardian_reviewArguments"
}

Get a pre-signed URL for uploading a large CSV (more than ~200 rows). Use this instead of pasting rows into ``guardian_review``. Returns ``upload_url``, ``dataset_id`` and a ready-to-run ``curl`` command: run it (replace ``data.csv`` with your file; gzip is accepted with ``Content-Encoding: gzip``), then call ``guardian_review`` with ``dataset_id`` (and no ``csv``/``data``). The URL is single-use and expires after 30 minutes; the dataset is only usable by the same API key, and is single-use too: it is deleted when ``guardian_review`` reads it (even if that review fails), so request a new upload to retry. This call does not consume review quota.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "title": "guardian_request_uploadArguments"
}