# Accuracy and limits

import { Card } from "zudoku/ui/Card";
import { ChartNoAxesCombined, Calculator, SlidersHorizontal } from "zudoku/icons";

Separate checked arithmetic from market accuracy before relying on an answer.

## What is verified

The derived arithmetic is internally consistent and deterministic: the same response produces the same derived numbers.
The maximum allowable offer reverses a flip profit calculation, and its unrounded round-trip holds to the cent.
Published amounts still follow their documented rounding rules.

The check that withholds a model estimate disagreeing with comparable sales is tested.
That path sets `model_estimate_available` to `false`.
Checking this behavior does not validate market accuracy.

## What is not verified

**There is no published back-test of predicted price against realized sale price.**
That applies to both the model estimate and the derived maximum allowable offer.
Plan your own back-test if accuracy matters to your use case.

Target margin and financing assumptions are policy figures chosen by judgment and intended to be tuned.
They are not fitted to a data set or quoted by a lender.

## Caveats to check

- **Residential only.** Large multifamily and commercial properties fall outside the model's coverage and can diverge instead of producing an error.
- **Tear-downs are unsupported.** There is no land-value estimate; analyze lot value separately.
- **Repair estimates are screening ranges, not bids.** Small homes skew high per square foot; heavy-rehab figures are the least reliable.
- **Thin model evidence needs caution.** Show `effective_sample_size` when available; it measures comparable evidence supporting the model, not sales passing a filter.
- **Missing evidence matters.** Comparable-sales bands depend on usable recorded sales; read omissions and the similar-sales fallback before relying on the range.
- **Sparse facts still produce precise-looking numbers.** Inspect `subject_property` and its sources; the number of displayed digits does not tell you how complete the inputs were.

When `max_allowable_offer.clamped` is `true`, no purchase price clears the target margin.
Do not present its amount as an offer.

## When the model does not price a property

Some properties sit outside what the pricing model prices: a very large lot, a very large
house, or a property type it does not cover. By default a property like that is refused
with 422 [unscorable-address](/errors/unscorable-address), and the charge is returned to your balance.

Set `partial_answer` to `true` with your request to `POST /v1/predict` to get the facts
instead.

When we found the property but the model does not price it, the answer is `200`.
It carries `subject_property` with the available house facts, `max_allowable_offer` as `null`, and `outside_model_range.reasons` saying why. That answer
is charged as an answer, because it describes a real property.

It carries no valuation, no
comparable sales and no `cost_stack`: those all come from the pricing model's own answer.

| Reason | What it means |
| --- | --- |
| `large-lot` | The lot is larger than the sizes the pricing model is calibrated over. |
| `large-structure` | The finished living area is larger than the sizes the model is calibrated over. |
| `property-type` | The property type is one the model does not cover well: multifamily, commercial, mixed-use or industrial. |
| `not-modelled` | We found the property, but the pricing model did not price it, and none of the three named limits applies. |

`partial_answer` is accepted on `POST /v1/predict` and `POST /v1/validate` only, and is
refused on the batch endpoint.

It must be `true` or `false`; anything else is refused
with 400 [invalid-request](/errors/invalid-request) before you are charged. An address we cannot find, and a call
that fails on our side, are refunded whether or not you send it.

## Next steps

<div className="docs-next-steps">

<Card className="docs-next-card"><a href="/scoring/valuation-and-comps"><ChartNoAxesCombined className="docs-next-icon" size={18} strokeWidth={1.5} aria-hidden="true" focusable="false" /><strong>Valuation and comparable sales</strong><span className="docs-next-description">Read the evidence behind the numbers.</span><span className="docs-next-arrow" aria-hidden="true">→</span></a></Card>

<Card className="docs-next-card"><a href="/scoring/maximum-allowable-offer"><Calculator className="docs-next-icon" size={18} strokeWidth={1.5} aria-hidden="true" focusable="false" /><strong>The maximum allowable offer</strong><span className="docs-next-description">Read the ceiling and its costs.</span><span className="docs-next-arrow" aria-hidden="true">→</span></a></Card>

<Card className="docs-next-card"><a href="/scoring/your-own-numbers"><SlidersHorizontal className="docs-next-icon" size={18} strokeWidth={1.5} aria-hidden="true" focusable="false" /><strong>Use your own numbers</strong><span className="docs-next-description">Set your repair budget and margin.</span><span className="docs-next-arrow" aria-hidden="true">→</span></a></Card>

</div>