Analyze supported textual accounting records with the pinned deterministic Writeoff engine and create a private, encrypted audit run owned by the caller. Accepted filenames end in .txt, .md, .text, .eml, .csv, .ofx, .qfx, or .qif. Returns estimates for review only: it does not file taxes, move money, or send data to an external accounting service.
Send prepared rows, not raw document text. Pasting the output of a PDF-to-text converter does not fail loudly. Read verbatim as .txt, .text or .md, the whole paste collapses to exactly ONE entry, and that entry's figure can be a real number from the page that is not a charge at all: a statement with no footer total books its running BALANCE as spend. Stripping the page headers and the balance column does not change that; a genuinely empty paste raises instead. Convert each document into canonical CSV first: a Date,Description,Amount header, then one row per economic event. The Description column carrying the merchant name alone is the cleanest form, and prose is not merely untidy -- it CHANGES the answer. The matcher runs over the whole description against a vocabulary that holds ordinary words as well as vendor names: paper, printer, ink, notebook, legal, consulting, subscription, hosting and domain each classify alone with no vendor present, and contact lens or reading glasses classify as a MEDICAL deduction. A memo line saying what was bought can therefore create a deduction the vendor name alone would not. Send the merchant, not a description of the purchase. Not every phrase matches -- weekly grocery run, haircut and banana all stay unclassified -- but plain English is not inert. Classification is separately gated by context_text, but that gate is PARTIAL, not an off switch. Leaving it empty suppresses only the rules that need a business to exist: business, meals, vehicle and home-office. The personal rules stay live whatever you send -- a bare contact lens still classifies with context_text empty, under the category name fsa_hsa rather than anything called medical, and donation and tuition classify the same way. An empty context is NOT a way to stop deductions being proposed. The business gate is a bare substring test, not a reading of what you wrote: it opens on a keyword anywhere in the text, so I do not own a business and This is a personal return, not a business each switch the business rules ON rather than off. Negation is not detected. Suppress those rules with an EMPTY context, never with a denial. Booking is independent of all of it -- a row books its amount whether or not it classifies, and classification decides only whether the row becomes a deduction candidate.
State the direction of every row. A .csv is routed as a statement, so each row has to say whether money went out or came in. Send exactly Date,Description,Amount,Type -- the amount column named Amount, and a Type of Purchase for money out or Refund for money in.
Separate the fields with COMMAS. The delimiter is sniffed from the header row, and a semicolon additionally switches the amount parser to the European convention where the comma is the decimal point and the dot is a thousands separator. In a semicolon-delimited file an ordinary -20.00 is therefore read as 2000.00 and -1234.56 as 123456.00 -- silently, with no error, a hundred times the real figure. Tab and pipe keep the dot decimal.
Send only these four columns, each once. Order among the four does not matter -- all 24 arrangements of Date,Description,Amount,Type measured identical -- but each once is load-bearing, because a repeated header resolves to the LAST copy. A second Amount REPLACES the figure, so it can under-book as easily as over-book; a second Type can make a file of refunds BOOK as spend just as easily as it can drop the whole file, and on three rows written Type=Refund,Purchase the last copy wins and all three book; and a second Date silently rewrites every date while the row count and the total stay exactly right. A literal Amount now protects the figures from same-direction ancillary debit- or credit-looking columns. A literal Amount beats one or more same-direction ancillary columns in either order, whether those cells are populated or blank. Those ancillary values are not silently substituted. Opposite-direction ancillary columns together form a complete pair and fail closed beside Amount.
Schema arbitration happens before row direction; Type cannot rescue an ambiguous schema. After arbitration selects one money representation, row direction uses a recognized Type first. Only when Type is absent or unrecognized does a trailing CR or DR marker decide. Only when both are absent does the selected money heading or sign decide. Thus Purchase and Refund outrank a conflicting marker on an otherwise unambiguous schema; notably, Payment is unrecognized and preserves the fallback.
Conflicting money representations fail closed instead of being chosen by header order. Distinct equal-ranked amount aliases, multiple equally ranked same-direction money headers without a literal Amount, an amount alias beside a separate debit/credit representation, a literal Amount beside a complete pair, and a third amount candidate beside a pair each produce a named ambiguous-money error. A complete Debit/Credit pair remains supported, but a row with both pair cells nonzero fails closed. On a row with neither recognized Type nor CR/DR marker, a negative debit is a reversal and remains credit, while a negative credit is never promoted to spend. Within one role vocabulary, exact matches still beat partial matches.
Column roles remain isolated. Description prefers an ordinary non-role heading. If none exists, exactly one releasable semantic-directional heading such as Charge Description or Payment Memo may serve, but only when an independent money representation survives without it. Outside that semantic-directional exception, suppressed lower-tier money, date and type candidates remain reserved and cannot become Description merely because a stronger sibling won their original role. Structural composites such as Amount Details, Transaction Type Description and Debit Details, or multiple competing semantic candidates, cannot serve as Description; when only those remain, the file fails closed rather than poaching merchant text.
Identical duplicate headers remain a separate hazard: DictReader uses the LAST copy. A second Amount REPLACES the figure, a second Type can make refunds book as spend or purchases drop, and a second Date silently rewrites every date. That residual duplicate-heading behavior is not an ACC-045 fix, so send the four canonical columns once each.
Type is matched against a fixed vocabulary, not read as free text. purchase, debit, charge, withdrawal and dr mean money out; refund, credit, deposit, return and cr mean money in. All eight spelled-out words resolve in the plural as well, but the two abbreviations do not: drs and crs are unrecognised and fall through to the amount CELL, so a crs row written negative books as SPEND, not as money in. Anything else -- notably Payment, money in on a card but out on a checking account -- counts as unstated, and the direction then falls to the amount CELL rather than to the sign alone.
Write the amount as a plain signed number, with nothing else in the cell. A trailing DR or CR and accounting parentheses are not decoration, and what they do depends on the column holding them and on the parser the CONTENT selected -- NOT on the file suffix.
Two separate things happen to such a cell, and BOTH are confined to the statement path -- the fan-out described under Routing below. First, in every statement format and every column, the figure is given a sign: parentheses negate, DR negates, and CR does nothing at all. DR is a SIGN; CR is only a label. On the single-receipt path no marker is a sign at all: a total written 20.00 books 20.00, and that same total written 20.00 DR, (20.00) or 20.00 CR books 0.00 -- there the marker makes the amount UNREADABLE rather than negative. Second, when the content parses as CSV and schema arbitration has selected one money representation, row direction reads recognized Type first and then any marker on the selected money cell. A marker never overrides recognized Type; with Type absent or unrecognized it outranks the selected heading or sign.
On a bare Date,Description,Amount file, 20.00 DR and (20.00) are both money OUT, and even -20.00 CR is money IN. A recognized Purchase or Refund still outranks either marker. A cell carrying no marker falls back to the SIGN, under the bank convention where money out is NEGATIVE, so a plain POSITIVE amount reads as money coming in and is dropped as non-deductible. On three rows totalling 137.19: written plain and positive they record nothing, and those same positives written 20.00 DR or (20.00) record all three.
This CSV marker reading applies to the selected single money column or the selected nonzero cell of a complete pair. With Type absent or unrecognized, 20.00 CR is credit and 20.00 DR is debit under Amount, Charges or Payments. With neither recognized Type nor marker, heading/sign fallback remains: positive Charges is spend, negative Charges is a reversal, and a lone Payments column is credit. Beside literal Amount, even a blank Payments column is ancillary and cannot void honest figures.
A money column whose name is in NEITHER vocabulary is a third way to record nothing. Purchases, Spend, Cost and Total were each measured doing it -- they are examples, not a list to check yours against -- and a file whose only figures sit under such a name returns zero rows at BOTH signs, with no error. Recognition is by name against a closed list, so the remedy is not a clearer word of your own but the four columns named at the top of this contract.
Native OFX and QIF content behaves like a plain AMOUNT column and NOT like a money-out column, on all six markers, under .ofx, .qfx and .qif alike: the sign left by the first step decides, so -20.00 CR is money OUT, and so is (20.00 CR); 20.00 DR is money OUT because DR negated it; and a plain positive 20.00 is money IN and dropped. TRNTYPE is never consulted -- DEBIT with a positive TRNAMT still drops. Because the parser follows the CONTENT, a .qfx holding canonical CSV runs the CSV rules above instead, markers and all.
Dropped rows are silent, and nothing in the result marks a row as dropped. A run does fail when it analyzed nothing at all across the whole submission, and separately on transport, input and engine errors -- but no failure mode reports a PARTIAL loss. If even one row anywhere survives, the run completes and the rest vanish with no notice, so a completed run is NOT evidence every row was read. A three-row file with one negative amount and two positive ones returns one row, no error, and a total indistinguishable from an honest one.
The one loss that IS named is a document that contributed nothing at all. When a submitted file appears in no catalog channel -- no item, no unclassified row, no notice, no error -- and it held at least two non-empty lines, catalog.notices carries a source_left_no_trace entry naming that file. That covers whole-file loss: a statement whose rows use a different delimiter than its header, and a body of unreadable bytes under a valid header, both otherwise return the same empty success as a file that genuinely held nothing. A header-only export stays silent by design -- it has no body to lose. This does not narrow the PARTIAL case above: a file that recorded even one row counts as read, so rows dropped beside it remain silent.
Routing is by filename suffix, not by content, against a CLOSED allowlist -- and the allowlist is assembled from two constants that DISAGREE. SUPPORTED_SUFFIXES in web/accounting_engine.py admits eight: .csv, .ofx, .qfx, .qif, .txt, .text, .md and .eml. STATEMENT_SUFFIXES in writeoff/batch.py names the five that fan out into one row per line, and one of those five is .xlsx, which the engine refuses before any parser sees it. What fans out is the INTERSECTION -- .csv, .ofx, .qfx and .qif. The other four -- .txt, .text, .md and .eml -- are read as a single receipt. Of those, .txt, .text and .md are read VERBATIM and behave identically to each other; .eml is NOT one of them. An .eml is parsed as an email FIRST -- headers dropped, transfer-encoding decoded, an HTML body flattened into lines at its block tags -- so every rule below applies to THOSE lines and not to the file's, and the same bytes can book a different figure, name a different merchant, or record a load error and contribute no entry at all. Statement rows sent that way collapse to ONE entry, and what that entry books turns on the PRICE pattern below: a file that LOADS and in which NO line ends in a price books 0.00, silently and with no error. An .eml with no extractable body -- an attachment-only mail -- never reaches that stage: it contributes NO entry and records an EmailIngestError in the run's errors, while still being listed among its sources. Its merchant is NOT the file's first line: it is the first line that neither ends in a price nor is a bare date, so a file led by a CSV header books that header text as the merchant, and a file whose every line ends in a PRICE books an EMPTY merchant. Ending in a bare number is not enough: a Closing balance 900 line is itself booked as the merchant. The winning figure is chosen by matching against the WHOLE lower-cased LINE, description included, so a purchase from TOTAL WINE AND MORE reads as the file's total. A label is only ever read on a line that ENDS in a price, and a price means EXACTLY TWO DECIMAL PLACES: a whole-dollar Total 137 is not a price, and neither are 137.1, 137.190 or a trailing 137. -- none of their labels are ever read. The pattern is anchored at the END only, so what stands in FRONT of the figure is unrestricted: Total USD 137.19 and even Total about 137.19 both read as totals, and a leading dollar sign is merely one case of that. After the digits it admits an optional minus and at MOST ONE trailing letter, and those letters are UPPERCASE ONLY -- T, N, X, F, E or an asterisk, while a lowercase t, n, x, f or e leaves the line with no price at all. So a line reading Total 137.19 USD, Total 137.19 (USD) or Total 137.19 EA carries no price at all, its label is never read, and the file falls through to its largest amount -- and a payable line behaves the same way, so an Amount Due 137.19 USD is not a payable line either. That property, not the marker, is why a Total 137.19 CR is not read as a total: CR is two letters, so the line has no price. Otherwise any line containing total is a total line and the LAST one wins -- not the first, not the largest -- so that wine row REPLACES an honest footer standing above it. Excluded are subtotal and sub total, though the near-miss sub-total is not excluded and does win, and any total line also holding saving, save, discount, coupon or reward as a bare substring; that is the entire exclusion list in the pinned dependency today. Those exclusions are the dangerous half: an excluded line is read as NO total rather than as a smaller one, and the search moves past it to the payable stage below, with no zero total present, and only then to the largest amount. Rows of 4812.00 and 12.34 under a Total Rewards Earned of 42.10 book 4812.00 -- a hundredfold over-book off a line the file itself labels a total. Give that same file an Amount Due of 42.10 and the payable stage rescues it. A ZERO is not an exclusion and does not chain that way. A total line reading 0.00 WINS its stage and sets the total to zero, and a zero total SUPPRESSES the payable stage, so the file drops to its LARGEST amount in EITHER order: an Amount Due of 42.10 standing above or below a Total of 0.00 does not rescue it. A paid-in-full invoice reading Total Due 0.00 books its largest line item. Last-wins covers zeros too, so a Total of 0.00 below a real Total of 42.10 WIPES it. The payable stage does not behave that way -- it takes the last payable line whose figure is NON-ZERO, so a trailing Amount Due of 0.00 leaves an earlier Amount Due of 42.10 standing. With no total line surviving, a line reading amount due, balance due, amount payable or please pay is used instead, last-wins again and only when its figure is non-zero. Those four are matched as LITERAL text, so the doubled-space spellings Amount Due and Balance Due, and likewise Amount-Due and AmountDue, are NOT payable lines at all; a file whose only payable label is spelled one of those ways skips to its LARGEST amount, which is the direction that over-books. A trailing colon in Amount Due: still matches. Failing every stage, the largest amount anywhere in the file. One hazard, though, is NOT confined to that last stage. The price read is END-anchored on the LINE, not on a column, so it reaches back across commas and swallows text belonging to the field BEFORE it. It takes the line's final cents pair and walks LEFT across each comma-separated group of EXACTLY three digits, then swallows up to three trailing digits of whatever text precedes the first such comma -- an amount's cents, a check or invoice number, a card last-4, a units or store-number column; money or not, decimal point or not. A group of one, two, or four-or-more digits terminates the walk. So a row of -12.34,887.66 yields 34,887.66 -- a figure that appears in NO cell of the document, even though those characters occur across the comma between two cells in the raw text. That splicing happens while the price is being READ, which is before any label is tested, so a spliced figure is what a total line or a payable line CARRIES INTO its own stage: a footer reading Total,-60.34,887.66 books 34,887.66 rather than 60.34, and an Amount Due,-12.34,887.66 books 34,887.66 the same way. Holding an explicit Total line is therefore NOT a way out of this. The field on the LEFT need not be money and need not carry a decimal point: a check register whose amount is the LAST column books 140,732.19 from a row reading 2029-06-02,8140,732.19, and an Amount Due,INV 4522,887.66 books 522,887.66. There is no ceiling on the RIGHT either -- -31.20 beside 412,880.55 books 20,412,880.55, because 412 and 880 are each groups of exactly three. What stops the walk is GROUP WIDTH alone, so a right-hand 1000.00, 4,887.66 or 12,345.67 is read whole, and the total line then books THAT figure rather than its own. A spliced figure is usually in no cell of the document, but not always: when the digits swallowed are all ZEROS -- an amount's 00 cents, or a round 1000 -- it lands exactly on the right-hand figure, so agreeing with a real cell is not evidence of a clean read. No error is raised in any of these cases. Send that file as .csv instead, where the splice does not occur. Rows of 200.00 and 12.34 under a Total of 137.19 book 137.19; delete that total line and the same file books 200.00. The winning line's own minus sign is DISCARDED at either stage, so a Total of -137.19 and an Amount Due of -137.19 both book 137.19. The entry books 0.00 whenever NO line in the file ends in a price, and a DR, CR or parenthesis marker on every amount is only ONE way to reach that state: whole-dollar amounts, a trailing currency code and a trailing period each book 0.00 with no marker anywhere in the file. Where a marker IS the cause, leaving the winning line unmarked makes it book in full, whether the winner is a total or a payable line. Every rule in this paragraph is measured on the LINES the loader hands the parser: for .txt, .text and .md those are the file's own lines, and for .eml they are the extracted body's. Anything outside the eight is REFUSED outright with an unsupported-file-type error rather than silently mis-read, so .pdf and .xlsx never reach the parser. Because the second set lives in a pinned dependency, treat the four as measured today, not as a promise. That split is by suffix; WITHIN those four the parser is chosen by CONTENT, so a .qfx holding canonical CSV runs the CSV column contract above in full. One row per economic event. An invoice and the receipt that pays it are one event; submit both and BOTH are counted, doubling the deduction. Same-day duplicates raise a possible_duplicate notice, but rows dated days apart -- the usual invoice-to-receipt gap -- raise nothing at all, so the total is silently twice the truth. Collapse duplicates before submitting.
Scope each run to one entity and one tax year, and name it that way -- totals spanning entities or years match no filing. Book each event on the date money moved (cash basis) unless the entity files accrual, and never mix bases in one run. Submit runs one at a time: one ingest is active per owner at a time.
The returned total counts classified spend only. Charges whose merchant matches no deterministic rule are excluded from it, so do not present it as total spend. Use preview_accounting_ticket_sync to turn those residuals into reviewable work. Never submit a figure you cannot find verbatim in the source document, and never adjust a merchant name to make a row classify: Description is what the engine matches on, so renaming an unrecognised vendor to a recognised one raises the deduction while every figure stays verbatim. An unclassified row is the engine declining to assert a rule it does not have. Leave it, and report the count.