# Neumann

> Neumann is an agent-accessible **Monte Carlo simulation service**. Give it a
> graph of probabilistic root nodes (each sampling from a distribution) and
> calculated nodes (formulas over their inputs); it runs thousands of trials and
> returns the resulting distribution as summary statistics. REST + MCP, built for
> AI agents and humans.

Neumann supports agent-to-agent cold start: any agent can POST to
`/api/v1/accounts` to create an account, receive an API key, and immediately run
simulations using starter credits — no human in the loop.

> **Base URL (important for cold-start agents):** this document was served from
> `https://neumann.krobar.ai`. Use that as your base URL. Every path below is host-relative —
> prepend `https://neumann.krobar.ai`. An account created on one environment (localhost /
> staging / prod) is not valid on another; don't mix them.

## Cold-start quickstart (3 steps)

**Step 1 — Create an account.** No request body. Returns
`{account_id, api_key, credit_balance, created_at}`. Save the `api_key` — it is
shown only once.

```
curl -X POST https://neumann.krobar.ai/api/v1/accounts
```

**Step 2 — Run a simulation.** Two equivalent surfaces:

- **MCP** (for MCP-native clients): connect to `https://neumann.krobar.ai/mcp` over the
  Streamable-HTTP transport, then call the `run_simulation` tool. Authenticate by
  passing your `api_key` as a tool argument, OR send an
  `Authorization: Bearer nmn_oat_<token>` header. Omit both to run anonymously
  (free, no credit accounting).
- **REST** (plain HTTP): POST the same arguments to `https://neumann.krobar.ai/api/v1/runs`, or
  invoke any tool directly at `https://neumann.krobar.ai/mcp/tools/run_simulation`. Send your key
  as the `X-API-Key` header (or the `api_key` body field).

Copy-pasteable example — a tiny business case (`revenue = units_sold *
price_per_unit`, two probabilistic root nodes feeding one calc node):

```
curl -X POST https://neumann.krobar.ai/mcp/tools/run_simulation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your api_key>" \
  -d '{
  "graph": {
    "contract_version": "1.0",
    "root_nodes": [
      {
        "id": "units_sold",
        "name": "Units sold per month",
        "distribution_type": "normal",
        "distribution_params": {
          "mean": 1000.0,
          "std": 150.0
        }
      },
      {
        "id": "price_per_unit",
        "name": "Price per unit (USD)",
        "distribution_type": "triangle",
        "distribution_params": {
          "min_val": 18.0,
          "mode_val": 25.0,
          "max_val": 40.0
        }
      }
    ],
    "calc_nodes": [
      {
        "id": "revenue",
        "name": "Monthly revenue (USD)",
        "formula": "{e_units} * {e_price}"
      }
    ],
    "edges": [
      {
        "id": "e_units",
        "source": "units_sold",
        "target": "revenue"
      },
      {
        "id": "e_price",
        "source": "price_per_unit",
        "target": "revenue"
      }
    ],
    "run_params": {
      "trials": 5000,
      "time_periods": 1
    }
  },
  "seed": 42
}'
```

**Step 3 — Read the result.** A small run returns the summarised
`SimulationResult` inline:

```json
{
  "run_id": "…",
  "status": "completed",
  "tier": "small",
  "total_trials": 5000,
  "credits_debited": 1,
  "result": {
    "contract_version": "1.0",
    "trials": 5000,
    "time_periods": 1,
    "summary_statistics": [
      {
        "time_period": 0,
        "nodes": {
          "revenue": {
            "percentiles": {"p10": "…", "p50": "…", "p90": "…"},
            "basic_stats": {"mean": "…", "std": "…", "min": "…", "max": "…"}
          }
        },
        "edges": { "…": "…" }
      }
    ]
  }
}
```

Large runs (trials × nodes × periods over the threshold) return a `run_id` with
`status: "accepted"` and `result: null` — stream live progress as Server-Sent
Events from `POST https://neumann.krobar.ai/api/v1/runs` (set `stream: true`), or poll
`get_results(run_id)`.

## Tools

- `run_simulation` — Run a Monte Carlo simulation on a supplied graph. Small runs return the full summarised result inline; large runs return a run_id to stream (POST /api/v1/runs SSE) or poll (get_results). Debits credits per run for authenticated callers.
- `oat_sensitivity` — Run a one-at-a-time (OAT) tornado sensitivity analysis: for each scalar root node, sweep it over a set of quantiles (others held at baseline) and measure the target node's response. Returns a tornado-ranked list (response_curve, elasticity, rank). Debits one credit per analysis for authenticated callers.
- `validate_graph` — Validate a graph with the engine's ModularGraphValidator and return a structured list of issues (rule, severity, affected elements).
- `estimate` — Pre-flight runtime/memory estimate for a graph without running it: estimated peak memory, complexity, the tier it would run as, and the credit cost.
- `solve_distribution_parameters` — Solve distribution parameters from a target min/max range and confidence so a human-style estimate becomes engine-ready distribution_params.
- `get_results` — Fetch the status and summary for a previously-submitted run.

These tools are reachable three ways and cannot drift: as MCP tools at
`https://neumann.krobar.ai/mcp`, as REST twins at `https://neumann.krobar.ai/mcp/tools/<name>`, and (for runs)
as `POST https://neumann.krobar.ai/api/v1/runs`. List them with `GET https://neumann.krobar.ai/mcp/tools`.

## The graph contract

- **root_nodes** — sample from a distribution each period. Valid
  `distribution_type` values: `bernoulli`, `beta`, `binomial`, `categorical`, `constant`, `constant_array`, `dirichlet`, `discrete_gamma`, `discrete_lognormal`, `discrete_normal`, `exponential`, `gamma`, `log_normal`, `normal`, `poisson`, `triangle`, `uniform`. See `GET https://neumann.krobar.ai/api/v1/contract` for
  each distribution's parameters.
- **calc_nodes** — computed from incoming edges. `formula` is an expression over
  incoming edge ids, e.g. `"{e_units} * {e_price}"`; `null` sums all inputs.
- **edges** — directed `source` → `target` connections (carry a node's value).
- **run_params** — `trials`, `time_periods`, and an optional `output_request`.

Pre-flight a graph for free with the `validate_graph` and `estimate` tools before
spending credits on a run. Turn a human "between X and Y" estimate into
distribution params with `solve_distribution_parameters`.

## Credit model

- New accounts get starter credits on signup (`POST /api/v1/accounts`).
- A **small** run costs 1 credit; a **large** run costs more. `estimate` tells you
  the tier and exact `credit_cost` before you run.
- Anonymous callers run free (no signup), but get no credit accounting.
- Out of credits → `402` with `error.code = "insufficient_credits"`. Read your
  balance and ledger at `GET https://neumann.krobar.ai/api/v1/accounts/me/ledger`.

## Links

All paths are host-relative — prepend `https://neumann.krobar.ai`.

- [`/agents.md`](https://neumann.krobar.ai/agents.md) — longer, fully self-contained quickstart
- [`/.well-known/mcp.json`](https://neumann.krobar.ai/.well-known/mcp.json) — machine-readable MCP descriptor
- [`/server.json`](https://neumann.krobar.ai/server.json) — MCP-registry manifest
- [`/api/v1/contract`](https://neumann.krobar.ai/api/v1/contract) — contract version + distribution catalog
- [`/mcp/tools`](https://neumann.krobar.ai/mcp/tools) — list the agent tools (REST)
- [`/docs`](https://neumann.krobar.ai/docs) — Swagger UI (interactive)
- [`/openapi.json`](https://neumann.krobar.ai/openapi.json) — machine-readable OpenAPI schema