# Tesora Compute API

> A free, unauthenticated REST service over the Tesora spreadsheet compute
> engine. It runs pure Excel-formula calculations — a workbook of cells and
> formulas with inputs and outputs — including a large actuarial function
> library (CHAINLADDER, ACTUAR, CASDATASETS, ACTUAFLOW). No database, no auth,
> no state beyond optional saved operations. It is also the backend for the
> Tesora Excel add-in.

## How to use it

- Evaluate one formula: `POST /v1/evaluate` with `{"formula":"=1+2*3"}` -> `{"value":7}`.
- Run a workbook: `POST /v1/run` with a `template` (sheets of cells/formulas), `outputs` (name -> cell), and optional `data`/`inputs` -> `{"output":{...}}`.
- Run a `.tsra` program: `POST /v1/run-tsra` with `source` (or a `files` bundle) and `data` -> `{"output":{...}}`. TSRA (Traceable Spreadsheet Reproducible Artifact) is a small language of `input`/`let`/`output`/`func` that compiles to a workbook.
- Discover functions: `GET /v1/functions` (filter with `?nameContains=` or `?category=`).
- Save & re-run a named calculation: the `/v1/operations` CRUD + `/v1/operations/:slug/run`.
- Hit a problem: `POST /v1/feedback` with a `summary` (and ideally `details`) tells the maintainers, from inside the session that hit it. Use it instead of silently working around a bug. The report leaves this service, so `details` carries the shape of the failure (formula, column names, range, row count) and never cell values or identifiers from an uploaded file.
- Compute over a large dataset: upload a CSV/Parquet to the ephemeral store (`POST /v1/files`, or mint a streaming PUT via `POST /v1/files/upload-urls`), then bind a column into a `/v1/run` range input as `"file.<fileId>.<column>"`. Files expire after 24 HOURS; large columns stream through the engine's off-grid columnar path (beyond the ~100k-row grid limit).

## Conventions

- Formulas are Excel syntax. A leading `=` is optional for `/v1/evaluate`.
- Cell references are `Sheet!A1`. A template sheet is `{ "name": ..., "data": [[rowCells...]] }` (row-major; a formula is a string starting with `=`).
- Errors say what to fix: a formula error names the cell, its Excel code, and the remedy; a malformed field returns `invalid request: <field>: <reason>`; a request-validation 400 adds a `details` array. Only the internal step wrapper, stack frames, and internal locators (filesystem paths, URLs, and `node_modules` references, redacted to `<path>`) are stripped.

## More

- Full reference: `GET /llms-full.txt`
- Interactive docs (Swagger UI): `GET /docs`; OpenAPI spec: `GET /openapi.json`
- Health: `GET /healthz`
- Live function catalog: `GET /v1/functions`

## Open source attribution

Tesora Compute is built on open source work by others. The actuarial
function libraries it exposes are:

- **chainladder-python** (`CHAINLADDER.*`), by John Bogaardt and
  contributors, maintained by the Casualty Actuarial Society
  Open-Source Projects Working Group. Mozilla Public License 2.0.
  https://github.com/casact/chainladder-python

- **ActuaFlow** (`ACTUAFLOW.*`), by Michael Watson.
  Copyright (c) 2026-present Michael Watson.
  Mozilla Public License 2.0.
  https://github.com/WattyAI/actuaflow
  Cite as: Watson, M. (2025). ActuaFlow: Modern Actuarial Pricing
  Library. https://github.com/WattyAI/actuaflow

- **actuar** (`ACTUAR.*`), by Vincent Goulet and contributors.
  GNU General Public License, version 2 or later.
  https://cran.r-project.org/package=actuar

- **CASdatasets** (`CASDATASETS.*`), by Christophe Dutang and Arthur
  Charpentier, originally assembled for *Computational Actuarial
  Science with R*. GNU General Public License, version 2 or later.
  https://dutangc.github.io/CASdatasets/
  Cite as: Dutang, C. and Charpentier, A. (2026). CASdatasets:
  Insurance datasets, R package version 1.2-1. DOI 10.57745/P0KHAG

These rest in turn on the wider scientific Python and R ecosystems,
including NumPy, pandas, SciPy, statsmodels, scikit-learn, polars and
patsy. We are grateful to everyone who maintains them.

Tesora Compute is a separate work that calls these libraries. It is
not affiliated with, endorsed by, or a product of the Casualty
Actuarial Society, the R Foundation, or any author named above. Each
library remains under its own license and nothing here alters those
terms. Corrections to this notice are welcome at support@tesora.ai.