# Sortia

> Sortia is a decision-science toolkit. It ships as a Google Sheets add-on (Monte Carlo simulation, optimization, decision trees, goal seek, data tables, statistical tests, distribution fitting, regression, forecasting) and as a headless Node engine, @sortia/engine, driven by a versioned JSON spec, plus sortia-mcp, a local MCP server that exposes the engine to AI agents. Determinism contract: the same spec plus the same seed produces bit-identical results.

Package status: @sortia/engine 0.1.0 and sortia-mcp 0.1.0 are coming to npm and are available in the Sortia source repository today. Contact: hello@sortia.io.

In-sheet custom functions: none. The add-on has no in-cell spreadsheet formulas. The tools run from the Sortia sidebar in Google Sheets; every tool panel includes a Guide section with a worked example, and the template gallery covers every tool with models you can load and run. Headless use goes through @sortia/engine and sortia-mcp.

## Model spec v1 (condensed)

- A spec is one JSON document. Required: specVersion (always 1) and kind.
- kind selects the tool family: simulation, optimization, riskOptimization, decisionTree, goalSeek, dataTable, statTest, fit, regression, forecast.
- All references use declared names, never spreadsheet cell addresses. Formulas are Excel-style expressions over those names, e.g. "IF(burn <= mrr, 60, cash / (burn - mrr))".
- simulation requires: model (named formulas), inputs (36 distribution families: normal, uniform, triangular, pert, lognormal, beta, discrete, metalog, resample, exponential, weibull, pareto, gumbel, logistic, geometric, gamma, studentt, poisson, binomial, negbinomial, bernoulli, intuniform, cumulative, rayleigh, laplace, cauchy, chisquare, erlang, loglogistic, minextreme, hypergeo, loguniform, invgauss, invgamma, fratio, compound), outputs, seed. Optional: trials (default 10000), sampling (lhs or mc), correlations (Spearman rank targets), percentiles.
- optimization requires: model, objective ({name, goal: max|min|value}), variables, engine (lp, nonlinear, or evolutionary; evolutionary also requires seed). Optional: constraints ({lhs, op: <=|>=|=, rhs}).
- riskOptimization requires: model, decisions, inputs, output, goal ({direction, statistic}), seed.
- decisionTree requires: nodes (decision, chance, or end; branch values are incremental along the path; chance branch probabilities sum to 1).
- goalSeek requires: model, setName, targetValue, changingName.
- Seed rules: seed (integer 0 to 4294967295) is required in the spec for simulation, riskOptimization, and evolutionary optimization. All other kinds consume no randomness and need no seed. There is no run-time seed override.
- validate(spec) reports every problem at once with stable error codes (E_PARAM_UNKNOWN, E_CIRCULAR, E_UNKNOWN_NAME, ...), JSON Pointer paths, and fix hints. Call describeCapabilities() for the full accepted vocabulary before authoring complex specs.
- Unknown fields and unknown parameters are rejected, never silently ignored.

## MCP tools (sortia-mcp, stdio, runs locally, no network calls)

- run_simulation: Monte Carlo over named formulas; returns summary stats, percentile ladder, tornado sensitivity per output.
- optimize: constrained optimization (simplex, Nelder-Mead, or differential evolution); returns status, objective, variable values, constraint report.
- evaluate_decision_tree: expected-value rollback; returns EV, optimal policy, risk profile.
- goal_seek: solve one constant so a formula hits a target value.
- fit_distribution: fit candidate distributions to data, ranked by Kolmogorov-Smirnov; each fit includes a run_simulation-ready input fragment.
- run_stat_test: t, z, F, ANOVA, chi-square, Mann-Whitney, Wilcoxon, Kruskal-Wallis, two-proportion A/B test.
- describe_capabilities: the engine's full accepted vocabulary and limits.

## Links

- [Start here](https://www.sortia.io/start): a walkthrough for someone who has barely used Google Sheets, from an empty browser tab to a first answer.
- [Tell someone about Sortia](https://www.sortia.io/share): a ready-to-send message, no referral code and no tracking link.
- [Developer documentation](https://www.sortia.io/developers): the engine, the spec, a worked example, the determinism contract, MCP quickstart.
- [Privacy policy](https://www.sortia.io/privacy)
- [Terms of service](https://www.sortia.io/terms)

<!-- generated below this line by scripts/build-templates.js -->
## Worked example: draft, validate, open

The loop an AI assistant runs with sortia-mcp on the user's machine. Nothing here calls a network;
the model runs in the user's own Google Sheet once they paste it in.

1. Draft. Turn the user's words into a spec. "Our launch costs somewhere between 40,000 and 60,000, the
   first-year revenue is about 90,000 give or take, and I want to know the odds we clear 20,000." becomes:

   {
     "specVersion": 1,
     "kind": "simulation",
     "name": "Launch: do we clear 20,000?",
     "seed": 20260926,
     "trials": 10000,
     "inputs": [
       { "name": "launch_cost", "dist": "uniform", "params": { "min": 40000, "max": 60000 } },
       { "name": "first_year_revenue", "dist": "pert", "params": { "min": 67500, "mode": 90000, "max": 112500 } }
     ],
     "model": [ { "name": "result", "formula": "first_year_revenue - launch_cost" } ],
     "outputs": [ "result" ]
   }

   A range the user gives ("between 40,000 and 60,000") is a uniform. A best guess ("about 90,000") is a
   pert at plus or minus 25 percent around the guess. Three percentiles (P10 / P50 / P90) fit a normal when
   they are symmetric and a triangular when they are not. Names are lowercase with underscores, and every
   name in a formula must be declared. The seed is required and any whole number will do.

2. Validate. Call describe_capabilities once for the vocabulary, then run_simulation, which validates before
   it runs and returns the refusal list unchanged if the spec fails (the same validate() the @sortia/engine
   package exports). A refusal is a list of { code, path, message }: E_UNKNOWN_NAME at /model/0/formula means
   a name in the formula is not declared; E_NAME_DUPLICATE at /inputs/1/name means two entries share a name;
   E_SEED_REQUIRED at /seed means the seed is missing; E_PARAM_ORDER at /inputs/1/params means min, mode and
   max are out of order. Fix exactly what the path points at and validate again. Do not hand the user a spec
   that has not passed.

3. Open. Give the user the JSON. In Google Sheets they open the Sortia sidebar, the Risk Analysis panel,
   then "Save or load this model as a file", paste it, and press "Preview this model". Sortia checks it
   again, lists every cell it will write on a new tab, and writes nothing until they confirm. The model then
   opens with their numbers in place; the first run carries its receipt (seed, trials, sampler, build, and a
   hash of the model and of the result) so the result can be reproduced exactly. Users with the experimental "Describe your decision" flow can build
   the same spec from four plain questions inside the sidebar, with the same validator in the way.

## Method guides

One page per Pro engine: what the method is, the questions it answers,
when it is not needed, and a worked example whose numbers are computed by
the shipped engine.

- [Monte Carlo Simulation Guide](https://www.sortia.io/monte-carlo-simulation)
- [Decision Tree Analysis Calculator](https://www.sortia.io/decision-tree-analysis)
- [Schedule Risk Analysis (Monte Carlo CPM)](https://www.sortia.io/schedule-risk-analysis)
- [Critical Chain Project Management in Google Sheets](https://www.sortia.io/critical-chain-project-management)
- [Optimization Under Uncertainty](https://www.sortia.io/optimization-under-uncertainty)

## Tool hubs

One page per tool family, covering what is in it and what each tool is for.

- [Statistics Toolkit (38 Tools)](https://www.sortia.io/statistics-in-google-sheets)
- [Machine Learning in Google Sheets](https://www.sortia.io/machine-learning-in-google-sheets)
- [Forecasting in Google Sheets](https://www.sortia.io/forecasting-in-google-sheets)
- [Linear Programming (LP) Optimization](https://www.sortia.io/optimization-in-google-sheets)
- [What-If Analysis in Google Sheets](https://www.sortia.io/what-if-analysis-google-sheets)

## Answers to specific questions

Hand-written pages that answer one question directly, with worked numbers.

- [Which Statistical Test Should I Use](https://www.sortia.io/which-statistical-test): Answer two questions, how many groups you are comparing and whether the rows are paired, to find the right statistical test, worked through real examples.
- [How to Run a T-Test in Google Sheets: Pick the Right One](https://www.sortia.io/t-test-in-google-sheets): Paired, pooled or Welch? T.TEST's fourth argument decides which test you ran, and on one real pair of columns it moves the p-value about 400 times.
- [One-Way ANOVA Calculator](https://www.sortia.io/anova-in-google-sheets): Run a one-way ANOVA in Google Sheets step by step, then the pairwise t-tests it leaves undone. Full worked example with every report row explained.
- [How to Make a Histogram in Google Sheets](https://www.sortia.io/histogram-in-google-sheets): Two ways: the built-in chart for a picture, and a bin table for a number you can quote. The same 24 wait times binned twice, and why the shape changes.
- [Normal Distribution Check (Distribution Fitting)](https://www.sortia.io/is-my-data-normal): See when a bell-curve assumption is safe and when it costs you, using distribution fitting on real task-duration data. No black-box verdict, just the math.
- [Data Analysis Toolpak Alternative](https://www.sortia.io/data-analysis-in-google-sheets): There is no built-in data analysis toolpak in Sheets. See all 38 statistical analyses: which a formula does, which take setup, which it cannot do.
- [Monte Carlo Simulation in Google Sheets Without an Add-on](https://www.sortia.io/monte-carlo-without-an-add-on): Run a Monte Carlo simulation in Google Sheets with formulas alone. The whole build, the numbers it produces, and the five things it cannot give you.
- [What a Google Sheets Add-on Can See](https://www.sortia.io/what-add-ons-can-see): A plain guide to add-on permissions: what each scope grants, what a short scope list still can't promise, and real network traffic shown byte for byte.
- [Simplex Pricing Rule Benchmark (Steepest-Edge)](https://www.sortia.io/simplex-pricing-measured): We benchmarked steepest-edge pricing against the alternative in our own simplex solver on nineteen instances and measured which one actually wins.
- [Validation and Accuracy Testing](https://www.sortia.io/validation): How Sortia checks its answers: published textbook values, published critical values, independent reference implementations and seeded golden results.

## Template library

379 worked models, each a real spreadsheet you can load and run.
Every one names the tool it uses and the question it answers.

- [All 379 templates](https://www.sortia.io/templates): the full gallery, filterable by topic, level and tool

## Experimental

- [Live estimate cells (experimental, off by default)](https://www.sortia.io/live-cells): the EST and ODDS named-function kit, the setup words and two worked examples; the template workbook link is coming

Sitemap: https://www.sortia.io/sitemap.xml