Smart fields
What this page is — the capability that runs your organisation's own extraction rules against a document and returns one value per rule, each backed by an exact quote and a confidence score.
What it is for — so "what is the notice period on this?" is a question you configure once and answer on every document, instead of asking a person each time.
The problem it solves — the same question about every contract is answered by hand, differently each time, with nothing to show where the answer came from.
Route: /org/papers/documents/<document>/ai → Transform → Smart fields ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_smart_field · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
Smart Fields are extraction rules you define, once, under Papers settings → Smart fields. Each is a fixed name plus a plain-language instruction saying what to pull out.
| Name | Instruction |
|---|---|
Notice period (days) | "Extract the termination notice period, in days." |
Renewal type | "State whether the term auto-renews or is fixed." |
This capability runs every active Smart Field that matches the document's family and returns exactly one value per definition — in the same order, with the name copied back verbatim.
Three rules govern the values, and together they are what make the output trustworthy:
- It extracts only what the document actually states.
- A definition never overrides the text. An instruction saying "the notice period is 30 days" does not make it 30 days.
- Where the document is silent, the value comes back empty rather than guessed.
It is the only capability in the Transform group, and the only one whose question set is yours:
| Returns | Who decides what is extracted | |
|---|---|---|
| Smart fields | One value per your definition, with evidence | You, in settings |
| Extract key terms | A fixed shape — parties, dates, value, obligations | The product |
| Compliance & policy check | Rule breaches against text you paste at run time | You, per run |
2. Why you would use it
Every organisation has three or four facts it needs off every contract, and they are never the same three or four as the next organisation's. A fixed extraction shape cannot serve that; a configurable one can.
- It turns an ad-hoc question into a standing one. Define "Notice period (days)" once and every document of that family answers it, without anyone being asked.
evidenceis the field that makes it usable. The shortest exact quote supporting the value — so a wrong extraction is caught in seconds, and a right one is provable. Extraction without evidence is a number you have to trust.confidencelets you automate the easy majority. Accept above a threshold, review below it. That is what makes bulk extraction practical.- Empty means silent, not failed. An empty value is a positive finding: the document does not say. Distinguishing that from "we could not find it" is the difference between data and noise.
- The definitions are portfolio-wide. Add a field today and it applies to everything you run it against thereafter.
3. What you provide
Nothing at run time — but the capability does nothing until you have configured the definitions.
| Provided | When | Where |
|---|---|---|
| Smart Field definitions — name + instruction | Once, before running | Papers settings → Smart fields |
| — | At run time | Nothing to type |
The extractor honours only your active definitions that match the document's family.
If no definition matches the document's family, the extractor has nothing to run and returns nothing. That is the most common reason this capability appears not to work, and it is a configuration state rather than an error.
Before running it on a new kind of document, define the fields you want for that family first.
A tight instruction yields a higher-confidence value and a cleaner supporting quote. "Extract the termination notice period, in days" is a good instruction. "Extract the termination terms" is not — it names several things, so the value becomes a paragraph and the evidence quote stops being pinpointable.
4. What it reads automatically
| Read | From | Used for |
|---|---|---|
| Document text — the full rendered body | The document | The extraction |
| Title & family | The document | Decides which definitions apply |
| Parties — everyone named | The document | Resolving party-relative instructions |
| Key field values | The document | The filled schema fields |
| Smart field definitions | Papers settings | Your active definitions matching this family |
5. What you get back
fields[] — exactly one entry per definition, in the same order.
| Field | Type | Values | Means |
|---|---|---|---|
name | string | — | Your definition's name, copied verbatim |
value | string | empty when the document does not contain it | The extracted value. Dates as YYYY-MM-DD, amounts with their currency |
confidence | number | 0–1, 0 when the value is empty | How sure it is |
evidence | string | up to 200 characters, empty when there is no value | The shortest exact quote from the document supporting the value |
The one-entry-per-definition guarantee is what lets you treat the output as a record: a definition that found nothing still returns a row, with an empty value and zero confidence, rather than disappearing.
6. Worked example
An organisation has defined two Smart Fields for its agreement family. A reviewer runs the extractor on an inbound services agreement.
Input: none at run time. The definitions are the two in §1.
One entry from fields[]:
name: "Notice period (days)" value: "30" confidence:
0.96evidence: "...either party may terminate on thirty (30) days' written notice."
What the reviewer does with it. The value is 30, not "thirty (30) days' written notice" — a
clean number that can go into a system. The evidence quote proves it in one glance, so the reviewer
does not open the document to confirm.
At 0.96 this sits well above the organisation's review threshold and is accepted automatically.
The second definition, Renewal type, returned value: "" with confidence: 0. That is not a
failure — the agreement genuinely says nothing about renewal, which is itself worth knowing and is
now recorded as a row rather than as an absence.
7. Running it
- Define your Smart Fields first at Papers settings → Smart fields — each a name plus an extraction instruction.
- Open a document of the matching family in Orbit Papers.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Smart fields under Transform.
- One value per matching definition appears in a result tab and is saved to the document.
Re-run after the document changes, or after you add or change a definition — a cached result reflects the definitions that existed when it ran, not the ones that exist now.
Available for auto-run from the type's AI Config tab, where it is among the most useful: every document of the type answers your standing questions on submit or finalize without anyone pressing anything. See AI configuration.
8. The admin contract
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | The AI Assistant button does not appear |
The papers_smart_field utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Transform, with no error. Note the Transform group has only this member, so the whole group vanishes |
papers.ai_monthly_credit_cap not yet reached | System Config | "monthly AI credit cap reached: n of n credits used this month" |
| Smart Field definitions exist for the document's family | Papers settings → Smart fields | Nothing is extracted. No error — there is simply nothing to run (§3) |
| The definitions are marked active | Same | An inactive definition is skipped silently |
| Smart fields is unlocked for the project | Override locks | The project inherits the organisation's definitions and cannot keep its own |
That last row is a Papers-specific one: smart-field configuration is among the five surfaces that can be delegated per project, and locked is the default.
For a confidential document, auto-run is default-denied — a platform administrator must set
papers.ai_confidential_cloud to the literal allow, and the block appears only in the server log.
A manual press still works, and where a local model key is configured the run is forced on-prem and
audited on the timeline as ai_local_routed.
9. Don't confuse this with…
| Papers settings → Smart fields | Where definitions are created. This runs them |
| The field schema | The form fields a person fills in. Smart Fields are extracted from the finished text |
| Extract key terms | A fixed shape decided by the product, and it writes obligations. This is your shape, and writes nothing |
| Zonal extraction | Reads fixed positions on a scanned page. This reads meaning from prose |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| Nothing was extracted | No Smart Field definitions match the document's family (§3) |
| A definition I created was skipped | It is inactive, or its family does not match this document |
| The value is a paragraph, not a value | The instruction names several things. Rewrite it to name one (§3) |
value is empty but the document says it | The wording is far from the instruction's phrasing, or the text is in an unrendered attachment |
confidence is 0 | The value is empty — confidence is always 0 in that case (§5) |
evidence is empty | There is no value, so there is nothing to quote |
| A date came back in an odd format | It should be YYYY-MM-DD. A value that is not is usually a relative period the document never resolves |
| Results do not reflect a definition I just added | The result is cached from before the change. Re-run (§7) |
| The whole Transform group is missing | This is its only member — the utility is off for your organisation (§8) |