LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
"""Routing a `table` extractor entry to the table executor.
The wire format is extractor-scoped (§7.0): `extractors: [{name, keys, options}]`.
v1 accepts exactly one entry, but WHICH one is now a choice, so the job row has
to record it -- status and result used to key everything under the hardcoded
`kv` name, which would have filed a table job's output under the wrong
extractor.
"""
import json
import os
import uuid
from unittest import mock
import django
from django.apps import apps
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "backend.settings.test")
if not apps.ready:
django.setup()
from agent_kv.constants import ( # noqa: E402
EXTRACTOR_ROUTES,
STAGE_NAMES_BY_EXTRACTOR,
TABLE_EXTRACTOR_NAME,
V1_EXTRACTOR_NAME,
)
from agent_kv.execution_serializers import ( # noqa: E402
_OPTIONS_SERIALIZERS,
SUPPORTED_EXTRACTORS,
ExtractorSerializer,
)
from agent_kv.models import AgentKVJob, JobStatus # noqa: E402
def test_table_is_the_only_supported_extractor():
"""`kv` is out of EXTRACTOR_ROUTES because this deployment ships no
`agentic_kv` plugin, so nothing drains `celery_executor_agentic_kv`.
SUPPORTED_EXTRACTORS is derived from that table, so the omission is what
turns a `kv` submit into a 400 rather than a 202 for a job that never runs.
"""
assert set(SUPPORTED_EXTRACTORS) == {TABLE_EXTRACTOR_NAME}
assert V1_EXTRACTOR_NAME not in EXTRACTOR_ROUTES
def test_every_supported_extractor_has_a_route_stage_list_and_options_serializer():
"""A supported extractor with no route dispatches nowhere; with no stage
list its progress is recorded and then filtered out of the status
document; with no options serializer, a submit for it raises an
uncaught KeyError at `_OPTIONS_SERIALIZERS[data["name"]]` instead of a
validation error -- `validate_name` already passed it, since
`SUPPORTED_EXTRACTORS` is derived from `EXTRACTOR_ROUTES`.
"""
for name in SUPPORTED_EXTRACTORS:
assert name in EXTRACTOR_ROUTES, name
assert name in STAGE_NAMES_BY_EXTRACTOR, name
assert name in _OPTIONS_SERIALIZERS, name
def test_the_table_route_targets_the_existing_executor():
"""R1: the queue is derived from the executor name, and
celery_executor_agentic_table is already wired. A new executor name here
would be accepted, dispatch silently, and never drain.
"""
executor, operation = EXTRACTOR_ROUTES[TABLE_EXTRACTOR_NAME]
assert executor == "agentic_table"
assert operation == "table_extract_api"
def test_a_table_entry_validates_with_its_own_options():
data = {
"name": "table",
"keys": {"target_table": "Rent rolls"},
"options": {"instructions": "skip totals rows"},
}
s = ExtractorSerializer(data=data)
assert s.is_valid(), s.errors
assert s.validated_data["options"]["instructions"] == "skip totals rows"
def test_a_table_entry_requires_a_target_table():
s = ExtractorSerializer(data={"name": "table", "keys": {}, "options": {}})
assert not s.is_valid()
assert "target_table" in json.dumps(s.errors)
def test_kv_options_are_rejected_on_a_table_entry():
"""The whole point of per-extractor options: an option aimed at the wrong
extractor must not be silently dropped.
"""
s = ExtractorSerializer(
data={"name": "table", "keys": {"target_table": "T"}, "options": {"qa": True}}
)
assert not s.is_valid()
assert "qa" in json.dumps(s.errors)
def test_a_kv_entry_is_refused_by_name():
"""Options scoping is moot for `kv` here: `validate_name` refuses the entry
before any options validator runs. What matters is that the refusal names
the extractor, so a caller sending a KV payload to this deployment learns
why rather than seeing a schema complaint.
"""
s = ExtractorSerializer(
data={
"name": "kv",
"keys": {"total": {"description": "d"}},
"options": {"qa": False},
}
)
assert not s.is_valid()
assert "unknown extractor" in json.dumps(s.errors)
assert "kv" in json.dumps(s.errors)
def _job(extractor=TABLE_EXTRACTOR_NAME, **overrides):
"""An unsaved job with an unsaved org -- this suite's established pattern.
`test_dispatch.py` builds jobs exactly this way and the whole `agent_kv`
suite touches no database (there is no `django_db` marker anywhere in it).
Assigning an unsaved `Organization` with an explicit PK caches it on the
job, so `job.organization` never hits the DB, and the slug is deliberately
different from the PK so a test can tell which one the code reached for.
"""
from account_v2.models import Organization
job = AgentKVJob(id=uuid.uuid4(), input_ref="org/o/agent_kv/j/input.pdf")
job.organization = Organization(id=7, organization_id="org_slug_1")
job.extractor = extractor
job.pages_total = 3
for key, value in overrides.items():
setattr(job, key, value)
return job
def test_the_kv_route_constants_survive_for_re_enablement():
"""`kv` is unroutable, not deleted. The executor/operation pair, the stage
list and the options serializer all stay so the branch carrying the engine
re-enables the extractor by restoring one dict entry -- not by merging
content back into the files it rewrites most.
"""
from agent_kv.constants import (
EXECUTOR_NAME,
OPERATION_KV_EXTRACT,
STAGE_NAMES_BY_EXTRACTOR,
)
from agent_kv.execution_serializers import _OPTIONS_SERIALIZERS
assert EXECUTOR_NAME == "agentic_kv"
assert OPERATION_KV_EXTRACT == "kv_extract"
assert V1_EXTRACTOR_NAME in STAGE_NAMES_BY_EXTRACTOR
assert V1_EXTRACTOR_NAME in _OPTIONS_SERIALIZERS
def test_the_status_document_keys_stages_by_the_extractor_that_ran():
from agent_kv.execution_views import _status_document
job = _job(
stage="table_extraction",
stages={"table_extraction": {"status": "done", "seconds": 12.5}},
)
doc = _status_document(job)
assert TABLE_EXTRACTOR_NAME in doc["extractors"]
assert V1_EXTRACTOR_NAME not in doc["extractors"]
# R7: recorded AND visible. StageReportView persists any stage name the
# executor sends, but _status_document filters through the extractor's own
# list -- with the KV list this array would come back empty.
assert doc["extractors"][TABLE_EXTRACTOR_NAME]["stages"] == [
{"name": "table_extraction", "status": "done", "seconds": 12.5}
]
def test_a_kv_job_still_reports_its_kv_stages():
from agent_kv.execution_views import _status_document
job = _job(
extractor=V1_EXTRACTOR_NAME,
stage="extraction",
stages={
"document_processing": {"status": "done"},
"extraction": {"status": "running"},
},
)
doc = _status_document(job)
names = [s["name"] for s in doc["extractors"][V1_EXTRACTOR_NAME]["stages"]]
assert names == ["document_processing", "extraction"]
def test_the_result_payload_keys_by_the_extractor_that_ran():
from agent_kv.execution_views_result import result_payload
job = _job(
status=JobStatus.COMPLETED,
result_ref="ref.json",
usage_summary={"pages": 3},
)
with mock.patch(
"agent_kv.execution_views_result.read_result",
return_value={"tables": [{"unit": "A1"}]},
):
payload = result_payload(job)
assert payload["success"] is True
assert payload["status"] == "completed"
assert payload["extractors"][TABLE_EXTRACTOR_NAME] == {"tables": [{"unit": "A1"}]}
assert payload["usage_summary"]["by_extractor"][TABLE_EXTRACTOR_NAME] == {"pages": 3}
assert V1_EXTRACTOR_NAME not in payload["extractors"]
def test_the_extractor_column_has_no_default():
"""Was `test_the_extractor_column_defaults_to_kv`, asserting `== "kv"`.
It pinned the defect as the contract. The default WAS the historical truth
when migration 0002 added the column -- the API accepted exactly one
extractor and it was always `kv` -- and it became a mis-filing trap the
moment `table` existed: `kv` is a valid key in `STAGE_NAMES_BY_EXTRACTOR`,
so a table job filed under it gets the KV stage list and
`table_extraction` is silently dropped from every status response, with
nothing logged because nothing looks wrong to the filter.
`""` matches no route, so an omission now fails the dispatch visibly. The
row-level truth 0002 back-filled is untouched: existing `kv` rows keep
saying `kv`, which is what `test_a_job_whose_extractor_has_no_stage_list_
reports_no_stages` below depends on.
"""
assert AgentKVJob().extractor == ""
assert V1_EXTRACTOR_NAME in {
value for value, _ in AgentKVJob._meta.get_field("extractor").choices
}, "a pre-carve-out row must still be a legal value to READ back"
def test_a_job_whose_extractor_has_no_stage_list_reports_no_stages(caplog):
"""A retired extractor name with surviving rows must not 500 `GET status`.
`_status_document` used to subscript `STAGE_NAMES_BY_EXTRACTOR`, so such a
row raised `KeyError` on status while `GET result` kept working -- the
result payload keys by `job.extractor` without consulting that table. An
empty stage array is the honest answer for an extractor this build no
longer knows how to describe.
"""
from agent_kv.execution_views import _status_document
job = _job(
extractor="retired_extractor",
stage="something",
stages={"something": {"status": "done"}},
)
with caplog.at_level("WARNING", logger="agent_kv.execution_views"):
doc = _status_document(job)
assert doc["extractors"]["retired_extractor"]["stages"] == []
assert doc["status"] == job.status.lower()
assert "retired_extractor" in caplog.text
# ---------------------------------------------------------------------------
# `ValidateView` is part of the carve-out: the class stays in the tree and the
# route does not. Both halves are asserted here, including that the class says
# so itself -- a reader of `execution_views.py` sees a complete, decorated,
# live-looking endpoint, and the only thing that decided otherwise was a file
# they may never open.
# ---------------------------------------------------------------------------
def test_validate_is_not_a_public_route_on_this_deployment():
from agent_kv import execution_urls
names = {p.name for p in execution_urls.urlpatterns}
assert names == {
"agent_kv_submit",
"agent_kv_status",
"agent_kv_result",
"agent_kv_cancel",
}, (
"the public route set changed; `/validate` compiles a `kv` schema and "
"`kv` is the one extractor this build refuses, so routing it would "
"advertise validation for an extractor every submit 400s"
)
def test_validate_view_documents_that_it_is_unrouted():
from agent_kv.execution_views import ValidateView
doc = ValidateView.__doc__ or ""
assert "NOT ROUTED" in doc, (
"ValidateView is a complete, decorated, live-looking endpoint that "
"nothing reaches. Say so on the class, not only in execution_urls.py"
)