Files

T

geometrybase 993d7b26fa Backfill first HKEX IPO document batch

Request:
Start progressively filling detailed information for recent HK IPO targets.

Changes:
- Add scripts/archive_hkex_documents.py to map tickers to HKEXnews stock IDs, select official prospectus and allotment-results PDFs, archive them under data/raw/{ticker}, parse high-confidence T0/T1 facts, export snapshots, and refresh sync state.
- Document the small-batch HKEX document backfill workflow in README.md and the archivist skill.
- Archive prospectus and allotment-results PDFs for 00901, 01081, 01779, 02290, 02553, and 03388.
- Fill T0 details including application dates, expected allotment date, board lot, minimum subscription amount, and offer-share counts for the six tickers.
- Fill T1 allotment-demand details including valid/successful applications, public subscription level, international placees, international subscription level, and final offer-share allocations.
- Refresh source_refs, ipo_master, offering_terms, ipo_demand, ticker_sync_state, and sync_tasks snapshots.

Verification:
- Ran archive_hkex_documents.py in a first small batch and re-ran corrected tickers after parser hardening.
- Parsed project Python scripts with ast.parse.
- Checked SQLite integrity and DB-to-snapshot row counts.
- Verified source_refs paths are repo-relative, source files exist, and SHA-256 hashes match.
- Confirmed batch field completeness for the six processed tickers.
- Ran git diff --check and git diff --cached --check.
- Checked for Python cache and SQLite transient files.

Next useful context:
- This batch added about 55MB of official HKEXnews PDFs.
- Sync state now has 16 complete stages, 1993 pending_due stages, and 42 pending_not_due stages.
- Continue with small --limit batches because HKEXnews title search can include historical or postponed offering documents for the same stock code.

2026-06-15 07:07:46 +00:00

5.1 KiB

Raw Blame History

HK IPO

HK IPO is a project for building a repeatable, auditable research workflow for Hong Kong new listing subscription decisions.

The project is designed around a feedback loop:

Archive IPO facts and source documents.
Freeze the analysis that was possible at each decision stage.
Compare predictions with post-listing outcomes.
Improve the scoring rules only from reviewed evidence.

Goals

Maintain a local, Git-tracked history of Hong Kong IPO data.
Separate factual archiving from investment judgment.
Keep every subscription decision tied to the information available at that time.
Review actual IPO outcomes against prior predictions.
Build a better IPO scoring process through structured error attribution.

Workflow

Each IPO is evaluated by stage:

T0_prospectus: prospectus and offer terms only.
T1_allotment: allotment results, public subscription, placing, allocation, and final pricing.
T2_grey_market: grey-market result and immediate pre-listing context.
D1, D5, D20, D60: post-listing review checkpoints.

The key discipline is to avoid hindsight leakage. A T0 prediction should only use T0 information, even after the IPO has listed.

Project Skills

This repository includes project-local Codex skills under .codex/skills/.

`archivist`

Owns facts and source control:

archive prospectuses, allotment results, listing facts, and market data;
record source URLs, as-of timestamps, repo-relative paths, and file hashes;
update the embedded SQLite database;
export Git-friendly CSV snapshots.

It does not make investment recommendations.

`analyst`

Owns IPO judgment and review:

produce T0/T1/T2 prediction cards;
score IPO candidates;
compare multiple IPOs;
write research memos and review cards;
classify forecast errors;
recommend scoring-rule updates.

It should use archived facts when available and keep prediction cards append-only.

Storage Model

The project is intended to be self-contained and portable across machines. Durable paths should always be relative to the repository root.

Expected layout:

data/
  hk_ipo.sqlite
  raw/
  snapshots/
memos/
reports/
rules/
schema/
scripts/
references/

Path rules:

store paths like data/raw/06658/prospectus.pdf;
do not store absolute paths;
do not store paths with a leading ./;
use POSIX / separators;
store file hashes for archived source documents when practical.

SQLite is the embedded source of structured facts. CSV snapshots provide readable Git diffs. Markdown memos preserve the reasoning at each decision point.

PDF Text Extraction

Archived PDFs can be converted into searchable text files:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/extract_pdf_text.py

The extractor reads PDF paths from data/hk_ipo.sqlite, writes derived text files under data/extracted_text/, and exports data/snapshots/extracted_text_manifest.csv with page counts, text hashes, and extraction status.

Recent IPO Target Refresh

Use HKEXnews annual new listing reports to seed recent subscription-relevant IPO targets:

.venv/bin/python scripts/update_recent_ipo_list.py --start-date 2023-06-15 --end-date 2026-06-15 --as-of 2026-06-15T07:30:00Z

The updater archives the HKEXnews XLSX reports under data/raw/hkex_new_listing_reports/, records report-backed source references, writes new_listing_report_entries, updates ipo_master and missing offering_terms fields, exports CSV snapshots, and refreshes sync_tasks.

Rows without an IPO offer price, such as transfers of listing, introductions, or de-SPAC transactions, are skipped by default because they are not ordinary public subscription targets.

HKEX Document Backfill

Use the HKEX document archiver to progressively fill detailed T0/T1 facts for open sync tasks:

.venv/bin/python scripts/archive_hkex_documents.py --limit 5 --as-of 2026-06-15T08:30:00Z

The archiver maps stock codes to HKEXnews title-search stock IDs, downloads the selected prospectus and allotment-results PDFs under data/raw/{ticker}/, records source_refs, parses high-confidence T0/T1 fields into ipo_master, offering_terms, and ipo_demand, exports snapshots, and refreshes sync_tasks.

Run in small batches because prospectus PDFs are large and title-search results can contain historical or postponed-offering documents.

Incremental Archive Sync

The archivist keeps a per-ticker sync ledger so repeated updates can focus on missing stages:

python3 scripts/update_sync_state.py

This writes ticker_sync_state and sync_tasks into data/hk_ipo.sqlite, then exports data/snapshots/ticker_sync_state.csv, data/snapshots/sync_tasks.csv, and data/snapshots/sync_runs.csv.

Use sync_tasks as the next-sync queue. Tasks marked open are due now; tasks marked waiting_until_due are known future updates.

Git Discipline

The repository uses automatic focused commits for completed project changes.

Before committing, check that unrelated dirty files are not included and that generated durable files use repo-relative paths.

5.1 KiB Raw Blame History