Gnomon API

Ask a business question with numbers. Gnomon plays it out a million times and answers in plain words.

curl https://gnomon-api.deskwithnova.com/v1/models/job_profit \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"price": 28000, "target_margin": 0.1, "hourly_cost": 65, "overheads": 8200,
                  "materials": {"low": 6800, "likely": 7400, "high": 9200},
                  "hours": {"low": 90, "likely": 118, "high": 150}}}'

{
  "tell_the_person": "Gnomon played this out 1,000,000 times and it worked out in 19,896 of 1,000,000 futures (2.0%).",
  "plan": "a quote of $28,000 incl. GST",
  "succeeded": 19896,
  "success_ratio": 0.0199,
  "seconds": 0.068,
  "drivers": [{ "label": "hours the job takes", "direction": "high" }, { "label": "materials", "direction": "high" }],
  "answer": "A quote of $28,000 incl. GST: works out in 19,896 of 1,000,000 futures ..."
}

Only 2 in 100 futures make the margin, and the hours are the main risk. Ask /v1/models/job_profit/best-plan and Gnomon tries prices and returns the lowest one that makes the margin safely enough: $32,200, which works in 931,708 of 1,000,000. To have an AI do this for you, connect it.

POST /v1/decision checks a decision before your AI acts on it. Every layer is optional: send the ones that fit.

The answer:

{
  "action": "stop",
  "confidence": 0.0682,
  "reasons": ["1 of 2 facts match their sources.", "0 of 1 rules pass.",
              "1,000,000 scenarios in 0.068 s: works out in 36.8%.",
              "Main risk: labour_hours running high, and the odds turn at about 113.5."],
  "fixes": ["Use 72 for Tiling labour rate (October price list).",
            "Change the decision so it meets: Margin at least 25%."],
  "how": ["Start at 36.8%: 368,160 of 1,000,000 scenarios worked out (36.8%).",
          "-15 points: Tiling labour rate is 65, but October price list says 72.",
          "-15 points: Margin at least 25%: fails, margin is 0.22."]
}

How the confidence is worked out (version 1, beta): it starts at the share of scenarios that worked out (or 100% with no simulation), then loses 15 points for each wrong fact or failed must rule, 5 for each failed should rule and 10 for each fact in the text that no source backs. go needs the threshold and nothing wrong, stop comes below 50% or when a must rule fails, and anything else is review. Every step is in how. The score is not yet calibrated against real outcomes.

Most business questions are one of a few shapes, so Gnomon has them ready. Send plain numbers to POST /v1/models/{name} and the model runs a million times, answers in plain words and names every default it assumed. GET /v1/models lists every model and its inputs, with no key needed. See them work on the dashboard.

{
  "inputs": {
    "cash_now": 12000, "monthly_costs": 39000, "salary_per_year": 65000,
    "days_per_week": 3, "full_time_from_month": 11,
    "monthly_sales": [49700, 56200, 54000, 50800, 45400, 41000,
                      37800, 35600, 36700, 38900, 42100, 46400]
  },
  "detail": true
}

The answer starts with tell_the_person, one sentence with the count for the AI to pass on, then has answer in plain words (“works out in 949,625 of 1,000,000 futures”), succeeded, success_ratio, the outcomes that matter, the main risks in drivers and every default in assumptions. With detail, a histogram and, for monthly models, each month’s range. A range is a number or {low, likely, high}. Give sales_history (6 or more past months) and the model learns the business’s real variation, trend and season; POST /v1/history shows what it learned.

POST /v1/models/{name}/best-plan tries the choices and returns the plan that is safe enough and does the most good: the lowest price that still makes the margin for a quote, the order size that earns the most for stock. Every option is screened on the same 100,000 futures, so they are compared fairly, and the leading three are run a million times each. Options are ranked by their average (expected) outcome, with min_success guarding the risk.

{
  "inputs": { ...the same inputs as the model... },
  "choices": {"price": [28000, 30000, 31000, 32200, 34000]},
  "goal": "best",
  "min_success": 0.9
}

Leave out choices and Gnomon tries sensible ones for the model. goal is best or safest. The answer lists every option with its share of futures that work out, and the pick in best. Up to 48 options at once; units are charged for the futures run (16 options are about 4.6 million futures, 19 units, a few seconds).

PUT /v1/profile saves a business’s numbers and rules once, so the AI does not send them every time. Models fill any input they are not given from the saved values, and decision checks add the saved rules. Only named numbers, lists of numbers and rules are kept, never text, and each key sees only its own.

{
  "values": {"cash_now": 12000, "monthly_costs": 39000},
  "rules": [{"name": "Margin at least 25%", "check": "margin >= 0.25"}],
  "forget": []
}

GET /v1/profile shows what is saved and DELETE /v1/profile removes it all. In the connector the same are the remember and recall tools, which need a key.

Add "receipt": true to a model, best-plan or decision call to get a signed receipt: the inputs, the result and the seed, for the business’s records. Gnomon keeps nothing. Anyone can run the same check again for the same numbers, and POST /v1/receipts/verify (no key needed) confirms a receipt is unchanged.

POST /v1/simulate plays out a plan up to a million times with the uncertain numbers changed each time, and counts how often it works out. A million scenarios take well under a second.

{
  "variables": {
    "materials":    {"dist": "triangular", "low": 6800, "mode": 7400, "high": 9200},
    "labour_hours": {"dist": "normal", "mean": 118, "sd": 14, "min": 80},
    "rain":         {"dist": "chance", "p": 0.3},
    "price": 31000, "rate": 72, "overheads": 8200
  },
  "outcomes": {"cost": "materials + labour_hours * rate + rain * 900 + overheads",
               "profit": "price / 1.15 - cost"},
  "success": "profit > 0",
  "runs": 1000000
}

The same inputs always give the same answer. Scenarios show how likely an outcome is, not a promise.

Gnomon is also an MCP connector, the standard way AI apps use outside tools. Connected, your AI can call run_model, find_best_plan, check_decision, simulate, learn_from_history, remember, recall, check_text and repair_text by itself.

{"type": "mcp", "server_label": "gnomon",
 "server_url": "https://gnomon-api.deskwithnova.com/mcp",
 "headers": {"Authorization": "Bearer $NOVA_API_KEY"}}

Signed-in connectors for the Claude and ChatGPT apps, with your own facts and rules, are planned for the paid plans. Until then the apps use the demo address.

Use it without being asked. Gnomon’s tools already tell the AI to call them for decisions with money or risk in them, but each app decides when to use a tool. To make it a rule, add this to the AI’s settings (Claude: Settings, General, personal preferences; ChatGPT: Personalization, custom instructions):

When I ask about, or you are about to recommend, any business decision with money or risk in it (cash flow, prices, quotes, stock orders, loans, payments, plans), check it with the Gnomon connector first without my asking, and tell me how many of the 1,000,000 futures worked out.

Gnomon also checks the work of AI coding tools like Claude Code. This part runs on your own computer, because it runs your code; nothing is sent anywhere. Install it once, then add it to Claude Code in each project:

pip install -e <path to the nova-gnomon repository>   # beta partners get access
claude mcp add gnomon-local -- gnomon-local

Automatic checks. A Claude Code Stop hook runs Gnomon whenever Claude finishes a turn: every typed Python function changed since the last commit runs against its git version on 100,000 inputs, and a change in behaviour stops Claude until it explains or fixes it. Functions that may reach networks, files, databases, email or payments are listed, never run, and the code runs with keys and passwords removed from its environment.

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "python",
                           "args": ["-m", "gnomon_local.hook"], "timeout": 300 }] }]
  }
}

Generated inputs find many breakages, but agreeing on 100,000 of them is strong evidence, not proof. Functions need type hints, or a short description of their inputs.

A key is shown once, when it is created. NOVA stores only a hash of it. Keep keys on your server, never in a browser or app.

Gnomon also checks rewrites of text: when your AI rewrites an email or a reply, it lists every fact that changed.

POST /v1/check compares an original text with an edited version. Every request field except the two texts is optional.

The response:

One rule sets severity: a changed or lost value is high, a weakened promise or a dropped condition is medium, a change of form only is low. All of these run as rules, without an AI model, in milliseconds.

Facts that only moved, or are written differently with the same value, are not reported in standard mode. A fact found only in the edit is reported as added: an invented price is as risky as a changed one.

Placeholders, code, link targets such as [pricing](/pricing), and HTML tags are checked whole and kept out of the other checks, so the digits in {item1} are not a number and “if not ready” inside code is not a negation.

Add rules to a check to hold the edited text to your own wording. Every part is optional.

{
  "original": "...",
  "edited": "...",
  "rules": {
    "banned": ["risk-free"],
    "required": ["Terms and conditions apply."],
    "packs": ["nz_fair_trading"],
    "style": { "no_em_dash": true, "spelling": "en-NZ" }
  }
}

Packs point at claims worth a second look. They are not legal advice.

Every finding has a category and a risk from 0 to 100: its severity plus how much harm that kind of change can do. The words around a finding decide safety and legal, so a changed number next to “tablets” ranks above a changed price, and a changed price above a dropped “today”.

fix_prompt turns the findings into numbered instructions, most risky first. Send it to the AI that wrote the edit, then check the new version again.

Revise your last text. Keep everything else exactly as it is, and make only these changes:
1. Change "Sarah" back to "{first_name}".
2. Put back "{order_id}" from the original.
3. Change "Tuesday" back to "Monday".
4. Put back "except" where it was.

POST /v1/repair takes the same body as /v1/check and puts the original words back wherever the edit replaced them: amounts, dates, days, names, links, quotes, placeholders, comparisons, promises, tax wording and accents. The rest of the edit is kept, and the repaired text is checked again.

{
  "text": "Your refund of $1,200 will arrive by 3 November.",
  "verdict": "pass",
  "verdict_before": "fail",
  "applied": [
    { "type": "money", "edited": { "text": "$1,500", "start": 15, "end": 21 },
      "replacement": "$1,200" }
  ],
  "unresolved": [],
  "fix_prompt": null
}

A dropped “not”, list item or fact has no safe place to go back to, so it stays in unresolved with a fix_prompt for your AI. When repair cannot be sure where words belong, it leaves them alone.

POST /v1/check/answer checks that an answer really answers the question, and that it is backed by the sources it was based on. Send at least one of sources or reference, or leave the AI judge on.

The response adds answers_question (yes, partly, no), reason, judged and confidence. If the judge cannot run, the rules still do, and the verdict is at most review: Gnomon never claims a clean pass it did not check. The judge reads your texts as data and never follows instructions written inside them.

curl https://gnomon-api.deskwithnova.com/v1/check/answer \
  -H "Authorization: Bearer $NOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How long do refunds take?",
       "answer": "Refunds are paid within 10 business days.",
       "sources": ["Refunds are paid within 5 business days."]}'

POST /v1/check/batch runs up to 50 checks in one call. defaults takes any field except the texts; fields in an item override it. Results come back in the same order, and one bad item returns its own error without failing the batch. Items that error are not charged.

{
  "defaults": { "locale": "en-NZ" },
  "items": [
    { "original": "...", "edited": "...", "metadata": { "ticket": "4812" } },
    { "original": "...", "edited": "...", "protected_terms": ["SKU-99"] }
  ]
}

Every error has one shape, is never charged, and never contains your text:

{ "error": { "code": "rate_limited", "message": "Too many requests. Retry after 2 seconds.",
             "retryable": true, "request_id": "req_..." } }

Beta keys get 60 requests a minute and 5 at once. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Ask us if you need more.

Send an Idempotency-Key header (up to 64 characters) to make retries safe: the same key and body within 24 hours returns the first result and is not charged again. Retry only when retryable is true, with backoff from 1 second, at most 3 times.

GET /v1/usage returns the calls and units for your key today and this month (UTC), and your limits. It is free and not rate limited, so a dashboard can read it.

{
  "key_id": "key_1a2b3c4d5e6f",
  "mode": "live",
  "today": { "date": "2026-10-24", "calls": 212, "units": 240 },
  "this_month": { "month": "2026-10", "calls": 3904, "units": 4410 },
  "limits": { "per_minute": 60, "concurrency": 5 }
}

During the beta, counts reset when the API restarts. Saved usage arrives with billing.

Gnomon keeps no text by default. Texts are checked in memory and dropped when the response is sent. Each call keeps only its id, time, key, size, verdict, finding counts and timing.

Your texts are never used to train NOVA models unless you agree to that in writing. During the beta the AI judge of the answer check will run on OpenAI with storage turned off, once it is switched on; it is off today. The rules never leave NOVA.

import os, requests

def check(original: str, edited: str) -> dict:
    r = requests.post(
        "https://gnomon-api.deskwithnova.com/v1/check",
        headers={"Authorization": f"Bearer {os.environ['NOVA_API_KEY']}"},
        json={"original": original, "edited": edited, "locale": "en-NZ"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

result = check(customer_reply, llm_rewrite)
send(customer_reply if result["verdict"] == "fail" else llm_rewrite)

const res = await fetch("https://gnomon-api.deskwithnova.com/v1/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOVA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ original: draft, edited: rewrite }),
});
const { verdict, findings } = await res.json();
for (const f of findings) {
  if (f.edited) editor.underline(f.edited.start, f.edited.end, f.message);
}

Ready to try it in your product? Ask for a beta key. Tell us what your AI writes and roughly how many checks a month you expect.