Draft cash-dividend PDF reference¶
This is AGPIPE-11's offline first slice, version 0.1.0. It supplies native
DataContract examples, source annotations and a local deterministic extraction
experiment. It does not implement a native PDF pipeline, agent runtime, event
registry, approval process or publication. AGPIPE-11 remains open in
BACKLOG.md.
The workflow design defines the
broader boundary and shared AGPIPE dependencies.
Source family and scope¶
The reference selects six English, text-layer HKEX EF001 cash-dividend forms. Targets are known official PDF URLs, with expected issuer/stock code, original SHA-256, byte count and page count frozen before baseline execution. The selected source examples are historical announcements, not a current entitlement feed. The stock code remains a five-character string; this reference does not establish a permanent security identifier or infer a share class from a ticker.
| Document | Purpose | Partition | Baseline result |
|---|---|---|---|
| National Electronics, 2025 | Sub-cent final dividend | Development | Candidate extracted |
| Q Technology, 2025 | Ordinary interim dividend | Development | Candidate extracted |
| JiaXing Gas update, 2025 | Declaration/payment currency and amount differ | Development | Review: update needs event association |
| CSSC Shipping, 2025 | Entitlement dates unresolved | Development | Review: unresolved dates |
| Continental Aerospace, 2025 | Second sub-cent final dividend | Reserved validation | Candidate extracted |
| Ganfeng Lithium update, 2026 | Per-ten-share declaration and pending payment terms | Reserved validation | Review: update, share basis and unresolved terms |
Facts were manually checked by the contributing assistant against the original PDFs before running the baseline. They are not independently annotated or reviewed acceptance truth. Reserved validation is an organizational partition: all six sources were inspected while developing this reference, and their annotations/results are visible. This is not a blind or independently reviewed holdout. A second reviewer and additional, separately annotated cases are required before live qualification.
Original PDFs and full page text are not bundled. The repository retains source links, digests, factual annotations and page/field locators. Reproduction requires obtaining the originals separately. If the upstream bytes change, the experiment refuses the input instead of silently changing its reference. The annotations are authoring/test inputs, not a second runtime persistence authority.
Native contract boundary¶
Explicitly import files from
src/pycharter/data/seed/examples/corporate_action_pdf/contracts/ when needed.
They are not added to the default seed manifest. All four use namespace
corporate_action_pdf and version 0.1.0; the table lists their metadata names.
The lifecycle tests pass namespace, name and version explicitly to Store.
| Draft contract | Purpose |
|---|---|
document_target |
Frozen source bytes, expected identity and exact extraction profile |
raw_dividend |
Attempt-linked first-page cells, raw spelling and page locators |
dividend_candidate |
Normalized candidate facts with explicit field states |
baseline_profile |
Validate the declared labels, mappings and bounds used by this experiment |
These are additive DataContract examples using existing parse, Store, build
and validation APIs. They add no artifact kind, runtime step, connector, API or
mandatory dependency. SQLite, PostgreSQL and MongoDB lifecycle coverage is
required; the reference tests also cover the existing memory and Redis clients.
Only definitions pass through Store in this slice; original PDFs, observations,
attempts and publication state do not yet have managed persistence.
Candidate facts preserve declaration and default-payment amount/currency
separately. Monetary amounts are exact non-negative decimal strings, not
binary floats or integer cents; zero remains observable and requires review.
The quoted share denominator is retained, with no per-share calculation. RMB
is explicitly mapped to ISO CNY; no currency conversion or exchange-rate
calculation occurs. Holder-specific withholding tax and net entitlements are
outside the reference.
known, missing, tba, not_applicable and ambiguous are distinct. Missing
required fields cannot be omitted. Unknown dates have explicit null values;
unknown amounts have null amount, while an explicitly stated currency may
remain known. A pending payment cell without a share denominator does not acquire
one by inference. Dates are calendar-validated ISO strings. The source's stated
shareholder-approval date is a schedule fact, not proof of approval or payment.
Document identity, source digest and attempt identity are separate. An update
or withdrawn candidate requires review; this slice does not infer its prior
event, merge missing amendment fields, overwrite history or manufacture an event
key. The native contracts enforce shape and local constraints. They cannot prove
that a field is true, that its cited page supports its meaning, or that all
required events have been discovered. A test deliberately swaps declaration and
payment facts to demonstrate this limit.
Reproduce the baseline¶
From a source checkout with pycharter[extraction] installed, place each original
PDF in a local input directory as <document_id>.pdf. The exact IDs, official
URLs and digests are in corpus.json beside the contracts. Then run:
python -m examples.corporate_action_pdf --pdf-dir /path/to/original-pdfs > /tmp/dividend-reference-report.json
This example reads supplied local files and writes a JSON report to stdout. It
makes no network/provider calls and needs no vendor API key. It validates the
profile, non-empty target manifest and complete annotations first, checks bytes
before parsing, reads every page through pypdf, binds configured first-page
labels, normalizes explicit
values and compares the candidate facts with the annotations. Page/label
locators are textual references, not geometrical table-cell evidence or proof of
supporting context. A future managed parser must retain the original bytes and
sufficient surrounding/table evidence through AGPIPE-4.
Every annotated field must have exactly one typed page/label locator consistent
with its observation state; missing/extra locators and malformed review-reason
lists are rejected before PDF I/O. The draft profile fixes each field's kind and
currency/status/state meanings, including RMB → CNY and TBA distinct from
not-applicable. Its explicit English month_map makes date parsing independent
of the host's LC_TIME. Ambiguous facts require review even when the field is
optional, including an unclear stated approval date.
The local experiment caps a document at 1 MiB and eight pages. These bounds are reference settings, not qualified production resource/latency limits or a PDF parser sandbox. Missing, changed, oversized, encrypted or corrupt files and page parse failures have no usable result. Blank or missing page text, unsupported families, multiple forms and duplicate labels require review. OCR, free-form results narratives, special/scrip dividends, currency elections and share splits are not qualified here. All six frozen targets remain in the report, including failures; the tool never reduces coverage by dropping unresolved inputs.
Every report says publication: not_attempted. candidate_extracted means only
that the configured fields were extracted without the reference's listed review
reasons. It does not approve their interpretation or authorize publication.
review_required reports unresolved or unsupported facts. Exit 0 means all six
inputs were processed and matched their annotations, including expected review
cases; exit 2 means acquisition/contract failure or annotation differences. Neither
exit code is a production pipeline success projection.
Invalid or unreadable reference configuration produces a global failure report
with reference_configuration_invalid, no document results and exit 2; no PDF
is read. A missing optional PDF parser produces parser_unavailable failures for
every frozen target, also with exit 2. Missing parser package metadata is reported
as a null version rather than aborting the report. Install the extraction extra
to reproduce a successful parsing experiment.
Initial experiment and what it establishes¶
On 2026-10-16, pypdf 6.14.2 extracted all 15 configured facts from each of the
six pinned PDFs with zero differences from the single-assistant annotations.
Three documents produced candidate facts without listed review reasons; three
required review. This is a small, selected reference experiment, not an accuracy
estimate, live operational acceptance or a benchmark of broad market coverage.
No provider cost, automation-rate, throughput or latency qualification is claimed.
Direct local PDF parsing was sufficient for the selected labels. There is no measured reason to add a browser or model to these six fixed forms. Unannounced facts and unresolved event identity need source updates or attributable review; a model cannot supply missing truth. Agent interpretation may help with broader layouts or narrative associations, but must be compared with this baseline on new, independently reviewed examples before extending the native interfaces.
AGPIPE-11's remaining source families, independent review, evidence retention, revision/event semantics, shared persistence/recovery/publication and operational acceptance remain tracked in BACKLOG.md. This reference does not close that item or widen the HKTVmall milestone.