askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
test_document_intake.py · 16.8 KB · 431 lines
| 1 | """Document intake: a machine reads, a person decides. |
| 2 | |
| 3 | The property this whole package exists to hold is that nothing an |
| 4 | extractor produces ever reaches the books on its own. Everything else -- |
| 5 | dedup, engine choice, confidence -- is in service of that, and most of |
| 6 | these tests are checking that a BAD reading is merely inconvenient rather |
| 7 | than wrong. |
| 8 | """ |
| 9 | |
| 10 | import base64 |
| 11 | import json |
| 12 | import pathlib |
| 13 | |
| 14 | from conftest import stage_collection |
| 15 | |
| 16 | import object_execution |
| 17 | import object_intake |
| 18 | import object_records |
| 19 | import python_object_runtime |
| 20 | |
| 21 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 22 | PACKAGES = REPO_ROOT / "packages" |
| 23 | INTAKE_OBJECTS = PACKAGES / "app-intake" / "objects" |
| 24 | RUNTIME = python_object_runtime.PythonObjectRuntime() |
| 25 | |
| 26 | RECEIPT = """BLUE BOTTLE COFFEE |
| 27 | 1234 Market St |
| 28 | 06/15/2026 |
| 29 | |
| 30 | Latte 4.50 |
| 31 | Croissant 3.75 |
| 32 | Subtotal 8.25 |
| 33 | Tax 0.74 |
| 34 | TOTAL 8.99 |
| 35 | |
| 36 | Suggested tip 20% 1.80 |
| 37 | """ |
| 38 | |
| 39 | |
| 40 | def setup_env(tmp_path, monkeypatch, *, settings=()): |
| 41 | data_dir = tmp_path / "data" |
| 42 | for pkg, name in (("app-intake", "scans"), ("app-finance", "expenses"), |
| 43 | ("app-projects", "projects")): |
| 44 | stage_collection(data_dir, pkg, name) |
| 45 | rows = "".join(f"s{i}\t{k}\t{v}\t\n" for i, (k, v) in enumerate(settings)) |
| 46 | stage_collection(data_dir, "app-settings", "app_settings", rows=rows) |
| 47 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 48 | return data_dir |
| 49 | |
| 50 | |
| 51 | def run(object_id, payload=None, *, roots=None): |
| 52 | return object_execution.execute_object( |
| 53 | RUNTIME, |
| 54 | object_execution.ObjectExecutionRequest( |
| 55 | object_id, method="POST", payload=payload or {}), |
| 56 | roots=roots or [INTAKE_OBJECTS]).result |
| 57 | |
| 58 | |
| 59 | def ingest(text=RECEIPT, **fields): |
| 60 | payload = {"text": text, "owner_id": "dana", "filename": "coffee.txt"} |
| 61 | payload.update(fields) |
| 62 | return run("action_scan_ingest", payload) |
| 63 | |
| 64 | |
| 65 | def ingest_bytes(content=b"\x89PNG fake image", **fields): |
| 66 | payload = {"content_base64": base64.b64encode(content).decode(), |
| 67 | "owner_id": "dana", "filename": "receipt.png"} |
| 68 | payload.update(fields) |
| 69 | return run("action_scan_ingest", payload) |
| 70 | |
| 71 | |
| 72 | def scan(data_dir, scan_id): |
| 73 | return object_records.get_collection_record("scans", scan_id, base_dir=data_dir) |
| 74 | |
| 75 | |
| 76 | def expenses(data_dir): |
| 77 | return object_records.read_collection_records("expenses", base_dir=data_dir) |
| 78 | |
| 79 | |
| 80 | def hook(record, *, existing=None, changes=None, action="create"): |
| 81 | return object_execution.execute_object( |
| 82 | RUNTIME, |
| 83 | object_execution.ObjectExecutionRequest( |
| 84 | "hook_scans", method="BEFORE_WRITE", |
| 85 | payload={"action": action, "collection": "scans", "record": record, |
| 86 | "existing": existing, |
| 87 | "changes": changes if changes is not None else dict(record), |
| 88 | "subject": {"user_id": "dana", "roles": []}}), |
| 89 | roots=[INTAKE_OBJECTS]).result |
| 90 | |
| 91 | |
| 92 | # --- reading, with no model and no key ------------------------------------- |
| 93 | |
| 94 | def test_the_total_is_chosen_by_its_label_not_its_size(): |
| 95 | """Taking the biggest number on the page is how an intake system |
| 96 | bills a client for the suggested-tip line.""" |
| 97 | assert object_intake.find_total_cents(RECEIPT) == 899 |
| 98 | |
| 99 | |
| 100 | def test_a_date_and_a_vendor_come_off_the_page(): |
| 101 | assert object_intake.find_date(RECEIPT) == "2026-06-15" |
| 102 | assert object_intake.find_vendor(RECEIPT) == "BLUE BOTTLE COFFEE" |
| 103 | |
| 104 | |
| 105 | def test_confidence_reflects_what_was_found_not_what_was_claimed(): |
| 106 | full = object_intake.guess_from_text(RECEIPT) |
| 107 | empty = object_intake.guess_from_text("") |
| 108 | assert full["confidence"] > empty["confidence"] == 0.0 |
| 109 | assert full["total_cents"] == 899 |
| 110 | |
| 111 | |
| 112 | def test_an_unreadable_page_yields_an_empty_suggestion_not_a_crash(): |
| 113 | """Nothing found has to be an answer, because it is the answer a free |
| 114 | extractor gives most often.""" |
| 115 | guess = object_intake.guess_from_text("~~~ 8||| ~~~") |
| 116 | assert guess["total_cents"] == 0 and guess["confidence"] == 0.0 |
| 117 | |
| 118 | |
| 119 | def test_a_models_loose_json_is_clamped_into_the_same_shape(): |
| 120 | normalized = object_intake.normalize_extraction( |
| 121 | '{"kind": "RECEIPT", "vendor": "Blue Bottle", "total": "$8.99",' |
| 122 | ' "confidence": 87, "line_items": [{"description": "Latte",' |
| 123 | ' "amount": "4.50"}]}', engine="ai_vision") |
| 124 | assert normalized["kind"] == "receipt" |
| 125 | assert normalized["total_cents"] == 899 |
| 126 | assert normalized["confidence"] == 0.87 # percent understood as a ratio |
| 127 | assert normalized["line_items"][0]["amount_cents"] == 450 |
| 128 | |
| 129 | |
| 130 | def test_an_extractor_having_a_bad_day_returns_nothing_usable(tmp_path): |
| 131 | """It must leave a scan waiting for a human, never break the pass |
| 132 | reading a hundred other documents.""" |
| 133 | for junk in ("not json at all", None, 42, "[1,2,3]"): |
| 134 | normalized = object_intake.normalize_extraction(junk) |
| 135 | assert normalized["total_cents"] == 0 and normalized["confidence"] == 0.0 |
| 136 | |
| 137 | |
| 138 | # --- ingest ------------------------------------------------------------------- |
| 139 | |
| 140 | def test_ingest_stores_and_returns_without_reading_anything(tmp_path, monkeypatch): |
| 141 | """Capture happens at a till with a phone; anything slower is a |
| 142 | receipt that ends up in a coat pocket.""" |
| 143 | data_dir = setup_env(tmp_path, monkeypatch) |
| 144 | result = ingest() |
| 145 | assert result["ok"] and result["status_of_scan"] == "pending" |
| 146 | |
| 147 | row = scan(data_dir, result["scan_id"]) |
| 148 | assert row["status"] == "pending" |
| 149 | assert row["extracted"] == "" # nothing read yet, deliberately |
| 150 | assert row["content_sha256"] |
| 151 | |
| 152 | |
| 153 | def test_the_same_receipt_photographed_twice_is_one_scan(tmp_path, monkeypatch): |
| 154 | """The second photo of a crumpled receipt is the normal case.""" |
| 155 | data_dir = setup_env(tmp_path, monkeypatch) |
| 156 | first = ingest() |
| 157 | again = ingest() |
| 158 | assert again["duplicate"] is True |
| 159 | assert again["scan_id"] == first["scan_id"] |
| 160 | assert len(object_records.read_collection_records("scans", base_dir=data_dir)) == 1 |
| 161 | |
| 162 | |
| 163 | def test_the_hook_refuses_a_duplicate_written_any_other_way(tmp_path, monkeypatch): |
| 164 | data_dir = setup_env(tmp_path, monkeypatch) |
| 165 | result = ingest() |
| 166 | digest = scan(data_dir, result["scan_id"])["content_sha256"] |
| 167 | verdict = hook({"content_sha256": digest, "owner_id": "dana"}) |
| 168 | assert verdict["status"] == 409 and "two expenses" in verdict["error"] |
| 169 | |
| 170 | |
| 171 | def test_two_businesses_may_receive_the_same_document(tmp_path, monkeypatch): |
| 172 | """The same invoice PDF reaching two companies is two genuine facts.""" |
| 173 | setup_env(tmp_path, monkeypatch) |
| 174 | ingest() |
| 175 | other = ingest(owner_id="sam") |
| 176 | assert other["ok"] and not other.get("duplicate") |
| 177 | |
| 178 | |
| 179 | def test_ingest_needs_an_owner_and_some_content(tmp_path, monkeypatch): |
| 180 | setup_env(tmp_path, monkeypatch) |
| 181 | assert run("action_scan_ingest", {"text": "x"})["status"] == 401 |
| 182 | assert run("action_scan_ingest", {"owner_id": "dana"})["status"] == 400 |
| 183 | assert run("action_scan_ingest", |
| 184 | {"owner_id": "dana", "content_base64": "!!not base64!!"})["status"] == 400 |
| 185 | |
| 186 | |
| 187 | # --- the reading pass ----------------------------------------------------------- |
| 188 | |
| 189 | def test_the_free_engine_reads_text_that_arrived_as_text(tmp_path, monkeypatch): |
| 190 | data_dir = setup_env(tmp_path, monkeypatch) |
| 191 | scan_id = ingest()["scan_id"] |
| 192 | result = run("system_scan_processor") |
| 193 | assert result["extracted"] == 1 and result["engine"] == "text_rules" |
| 194 | |
| 195 | row = scan(data_dir, scan_id) |
| 196 | assert row["status"] == "extracted" |
| 197 | assert json.loads(row["extracted"])["total_cents"] == 899 |
| 198 | assert row["confirmed_record"] == "" # read, not posted |
| 199 | |
| 200 | |
| 201 | def test_an_image_with_no_ocr_engine_still_becomes_confirmable(tmp_path, monkeypatch): |
| 202 | """The honest free path: no text found, image attached, type the |
| 203 | total. Never a wrong number.""" |
| 204 | data_dir = setup_env(tmp_path, monkeypatch) |
| 205 | scan_id = ingest_bytes()["scan_id"] |
| 206 | run("system_scan_processor") |
| 207 | |
| 208 | row = scan(data_dir, scan_id) |
| 209 | assert row["status"] == "extracted" |
| 210 | assert json.loads(row["extracted"])["total_cents"] == 0 |
| 211 | |
| 212 | |
| 213 | def test_a_missing_host_engine_leaves_the_document_pending(tmp_path, monkeypatch): |
| 214 | """A host that is not set up is an operator's problem to fix, not a |
| 215 | document to give up on -- so it stays pending and the backlog drains |
| 216 | the moment the engine appears.""" |
| 217 | data_dir = setup_env(tmp_path, monkeypatch, |
| 218 | settings=(("intake.ocr_engine", "ai_vision"),)) |
| 219 | scan_id = ingest_bytes()["scan_id"] |
| 220 | result = run("system_scan_processor") |
| 221 | |
| 222 | row = scan(data_dir, scan_id) |
| 223 | assert result["failed"] == 1 |
| 224 | assert row["status"] == "pending" # retried when the host is fixed |
| 225 | assert "ai_vision" in row["error"] |
| 226 | |
| 227 | |
| 228 | def test_a_document_that_keeps_failing_stops_being_retried(tmp_path, monkeypatch): |
| 229 | """Churning a paid extractor forever against a corrupt file is how an |
| 230 | intake queue silently spends money.""" |
| 231 | data_dir = setup_env(tmp_path, monkeypatch) |
| 232 | scan_id = ingest_bytes()["scan_id"] |
| 233 | object_records.update_collection_record( |
| 234 | "scans", scan_id, {"status": "error", "attempts": "3"}, |
| 235 | base_dir=data_dir, actor="test") |
| 236 | result = run("system_scan_processor") |
| 237 | assert result["considered"] == 0 |
| 238 | assert scan_id in result["needing_a_human"] |
| 239 | |
| 240 | |
| 241 | def test_reading_twice_does_not_re_read(tmp_path, monkeypatch): |
| 242 | setup_env(tmp_path, monkeypatch) |
| 243 | ingest() |
| 244 | run("system_scan_processor") |
| 245 | assert run("system_scan_processor")["extracted"] == 0 |
| 246 | |
| 247 | |
| 248 | def test_intake_absent_is_a_graceful_skip(tmp_path, monkeypatch): |
| 249 | data_dir = tmp_path / "data" |
| 250 | data_dir.mkdir() |
| 251 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 252 | assert run("system_scan_processor")["skipped"].startswith("intake not installed") |
| 253 | |
| 254 | |
| 255 | # --- confirmation ---------------------------------------------------------------- |
| 256 | |
| 257 | def test_confirming_creates_a_draft_expense_with_its_provenance( |
| 258 | tmp_path, monkeypatch): |
| 259 | data_dir = setup_env(tmp_path, monkeypatch) |
| 260 | scan_id = ingest()["scan_id"] |
| 261 | run("system_scan_processor") |
| 262 | |
| 263 | result = run("action_confirm_scan", {"scan_id": scan_id, "project_id": ""}) |
| 264 | assert result["ok"] and result["status_of_expense"] == "draft" |
| 265 | |
| 266 | row = expenses(data_dir)[0] |
| 267 | assert row["description"] == "BLUE BOTTLE COFFEE" |
| 268 | assert row["incurred_on"] == "2026-06-15" |
| 269 | assert row["amount_cents"] == "899" |
| 270 | assert row["receipt_ref"] == f"scans/{scan_id}" |
| 271 | assert row["status"] == "draft" # still faces the approval gate |
| 272 | assert scan(data_dir, scan_id)["confirmed_record"] == f"expenses/{row['id']}" |
| 273 | |
| 274 | |
| 275 | def test_one_scan_one_record_however_many_clicks(tmp_path, monkeypatch): |
| 276 | data_dir = setup_env(tmp_path, monkeypatch) |
| 277 | scan_id = ingest()["scan_id"] |
| 278 | run("system_scan_processor") |
| 279 | run("action_confirm_scan", {"scan_id": scan_id}) |
| 280 | again = run("action_confirm_scan", {"scan_id": scan_id}) |
| 281 | assert again["duplicate"] is True |
| 282 | assert len(expenses(data_dir)) == 1 |
| 283 | |
| 284 | |
| 285 | def test_what_a_person_types_beats_what_the_machine_read(tmp_path, monkeypatch): |
| 286 | """The point of confirmation is that somebody is looking at the image |
| 287 | while they do it.""" |
| 288 | data_dir = setup_env(tmp_path, monkeypatch) |
| 289 | scan_id = ingest()["scan_id"] |
| 290 | run("system_scan_processor") |
| 291 | run("action_confirm_scan", {"scan_id": scan_id, "amount_cents": "1079", |
| 292 | "description": "Coffee with the Acme team"}) |
| 293 | |
| 294 | row = expenses(data_dir)[0] |
| 295 | assert row["amount_cents"] == "1079" |
| 296 | assert row["description"] == "Coffee with the Acme team" |
| 297 | |
| 298 | |
| 299 | def test_an_unread_document_asks_for_the_amount_rather_than_posting_zero( |
| 300 | tmp_path, monkeypatch): |
| 301 | data_dir = setup_env(tmp_path, monkeypatch) |
| 302 | scan_id = ingest_bytes()["scan_id"] |
| 303 | run("system_scan_processor") |
| 304 | |
| 305 | result = run("action_confirm_scan", {"scan_id": scan_id}) |
| 306 | assert result["status"] == 400 and "type it in from the image" in result["error"] |
| 307 | assert expenses(data_dir) == [] |
| 308 | |
| 309 | |
| 310 | def test_preview_shows_the_draft_without_writing_it(tmp_path, monkeypatch): |
| 311 | data_dir = setup_env(tmp_path, monkeypatch) |
| 312 | scan_id = ingest()["scan_id"] |
| 313 | run("system_scan_processor") |
| 314 | |
| 315 | result = run("action_confirm_scan", {"scan_id": scan_id, "preview": "true"}) |
| 316 | assert result["would_create"]["amount_cents"] == "899" |
| 317 | assert expenses(data_dir) == [] |
| 318 | assert scan(data_dir, scan_id)["status"] == "extracted" |
| 319 | |
| 320 | |
| 321 | def test_confirmed_evidence_is_closed(tmp_path, monkeypatch): |
| 322 | """Correct the expense, not the record of what arrived.""" |
| 323 | data_dir = setup_env(tmp_path, monkeypatch) |
| 324 | scan_id = ingest()["scan_id"] |
| 325 | run("system_scan_processor") |
| 326 | run("action_confirm_scan", {"scan_id": scan_id}) |
| 327 | |
| 328 | existing = scan(data_dir, scan_id) |
| 329 | verdict = hook({"ocr_text": "something else"}, existing=existing, |
| 330 | changes={"ocr_text": "something else"}, action="update") |
| 331 | assert verdict["status"] == 409 and "not the evidence" in verdict["error"] |
| 332 | |
| 333 | |
| 334 | def test_confirming_a_scan_that_does_not_exist_says_so(tmp_path, monkeypatch): |
| 335 | setup_env(tmp_path, monkeypatch) |
| 336 | assert run("action_confirm_scan", {"scan_id": "nope"})["status"] == 404 |
| 337 | assert run("action_confirm_scan", {})["status"] == 400 |
| 338 | |
| 339 | |
| 340 | # --- the door (0.3.0) -------------------------------------------------------- |
| 341 | # |
| 342 | # system_scan_processor has returned a key called `needing_a_human` since |
| 343 | # the day it was written, and 0.2.0 finally put that number on the home |
| 344 | # page -- pointing at /scans?status=extracted, which nothing on the box |
| 345 | # served. The most valuable queue here was a dead link for a whole |
| 346 | # version. These tests are about the page, not the reading: that the |
| 347 | # count opens something, that what it opens lists scans, and that the |
| 348 | # page makes no promise the generic renderer cannot keep. |
| 349 | |
| 350 | import csv # noqa: E402 (structural tests below; the behavior tests above need none) |
| 351 | |
| 352 | import object_packages # noqa: E402 |
| 353 | import object_site_routes # noqa: E402 |
| 354 | |
| 355 | APP_INTAKE_DIR = PACKAGES / "app-intake" |
| 356 | |
| 357 | |
| 358 | def _intake_seed_rows(name): |
| 359 | with open(APP_INTAKE_DIR / "seed" / f"{name}.tsv", newline="") as handle: |
| 360 | return list(csv.DictReader(handle, delimiter="\t")) |
| 361 | |
| 362 | |
| 363 | def test_the_scans_index_is_a_seeded_view_and_not_a_page_object(): |
| 364 | package = object_packages.get_package("app-intake", root=PACKAGES) |
| 365 | |
| 366 | assert [entry["id"] for entry in package["objects"] |
| 367 | if entry["id"].startswith("site_")] == [] |
| 368 | assert {entry["collection"] for entry in package["seed"]} == { |
| 369 | "scans", "views", "site_routes"} |
| 370 | # Rows seeded into app-views' shared collections need app-views' schema |
| 371 | # to have landed first -- a real install-order dependency. |
| 372 | assert "app-views" in {entry["id"] for entry in package["dependencies"]} |
| 373 | |
| 374 | |
| 375 | def test_the_index_lists_scans_and_offers_no_form_that_could_not_work(): |
| 376 | rows = [row for row in _intake_seed_rows("views") if row["id"] == "view_scans"] |
| 377 | assert len(rows) == 1 |
| 378 | view = rows[0] |
| 379 | assert view["route"] == "/scans" |
| 380 | blocks = json.loads(view["blocks"]) |
| 381 | assert len(blocks) == 1 |
| 382 | block = blocks[0] |
| 383 | assert block["kind"] == "list" |
| 384 | assert block["collection"] == "scans" |
| 385 | # No Add button: a scan is bytes plus a hash raised by action_scan_ingest. |
| 386 | # A form that let somebody type a filename would create a row with no |
| 387 | # document behind it, which the processor would then try to read. |
| 388 | assert "add" not in block |
| 389 | # No /scans/{id} permalink is seeded, so a row must not behave like a link |
| 390 | # to one. |
| 391 | assert block["link"] is False |
| 392 | |
| 393 | |
| 394 | def test_the_index_route_resolves_to_the_generic_renderer(): |
| 395 | rows = _intake_seed_rows("site_routes") |
| 396 | assert len(rows) == 1 |
| 397 | assert rows[0]["pattern"] == "/scans" |
| 398 | assert rows[0]["object_id"] == "site_view_render" |
| 399 | # Convention routing wins over seeded records, so a site_scans object |
| 400 | # would silently shadow this page. There isn't one, and this is where |
| 401 | # somebody finds out if that changes. |
| 402 | assert object_site_routes.convention_object_id("/scans") == "site_scans" |
| 403 | |
| 404 | |
| 405 | def test_the_receipts_queue_now_has_a_door_of_its_own(): |
| 406 | """The manifest used to say, in as many words, that this package ships |
| 407 | no door and the count files under Money anyway. It ships one now.""" |
| 408 | package = object_packages.get_package("app-intake", root=PACKAGES) |
| 409 | entry = package["nav"][0] |
| 410 | |
| 411 | assert entry["id"] == "scans" |
| 412 | assert entry["path"] == "/scans" |
| 413 | assert entry["group"] == "Money" |
| 414 | assert entry["surface"] == "member" |
| 415 | assert entry["blurb"] |
| 416 | |
| 417 | |
| 418 | def test_the_count_opens_the_index_rather_than_a_filter_nothing_honours(): |
| 419 | package = object_packages.get_package("app-intake", root=PACKAGES) |
| 420 | source = package["attention"][0] |
| 421 | |
| 422 | assert source["path"] == "/scans" |
| 423 | assert "?" not in source["path"] |
| 424 | assert source["nav_id"] == "scans" |
| 425 | # The status filter is real, it just lives on the page: the generic list |
| 426 | # builds its filter bar from the schema, and `extracted` -- the exact |
| 427 | # status the provider counts -- is one pick away in it. |
| 428 | schema = json.loads((APP_INTAKE_DIR / "schemas" / "scans.json").read_text()) |
| 429 | assert "status" in schema["views"]["filter_fields"] |
| 430 | scan_attention = (APP_INTAKE_DIR / "objects" / "system" / "scan_attention.py").read_text() |
| 431 | assert 'WAITING_STATUS = "extracted"' in scan_attention |