Gary Breeding Project

Purpose

The Gary Breeding Project rewrites Racing & Sports breeding and pedigree report tooling as a testable Python data layer with a Node.js document renderer. It reads the legacy rs MySQL schema, builds a structured report model, serialises that model to JSON, and renders Word and optional PDF documents.

Canonical repository: RQDG/Gary-Breeding-Project

Current status

Status as at 2026-08-08:

• The repository is established on private GitHub branch main at baseline commit 114d269.
• The meeting data-QA workstream is complete and covered by 24 selected unit tests.
• The pedigree/report workstream supports ten report types and is covered by 30 selected V3 tests.
• Sire Report V2 and Seasonal Stats have been rerun against live data and their four recorded defects are confirmed fixed.
• Six newer Group B/C reports are implemented but still require live SQL and rendered-document review.
• Foal Index/Bloodstock full live grand-total reconciliation and the presentation redesign remain open.
• Generated reports, validation folders, logs, credentials, caches, and build artifacts are intentionally excluded from Git. Golden PDFs and other original reference files remain tracked.

Scope

Workstream A: meeting data QA

Package: breeding_report/

This standalone port of source/BreedingController.cs checks meeting and runner data for missing breeding, brand, microchip, and life-number values, plus duplicate/overwrite conditions. It is not the pedigree-report engine.

Supported QA report names: meeting_info, missing_breeding, missing_brand, missing_microchip, missing_lifenumber, and overwrite_check.

Workstream B: breeding and pedigree reports

Package: breeding_report_v3/

This is the main deliverable. It ports the report logic from the legacy TrotBetAdmin PDFController.cs, including parent construction, sibling statistics, rankings, matrix lookup, scoring, chromosome data, and simpler sire/dam report queries.

Supported report names:

• dam_index
• breeding_v3
• sire_report_v2
• seasonal_stats
• sire_progeny
• order_of_foal_report
• damsire_timeform_stats
• dam_sire_report
• sire_forensic_report
• bs_breeding_report

See the Report Files and Outputs page for inputs, document contents, validation state, and examples for every report.

Architecture

CLI parameters or pedigree fixture
             |
             v
Python builders and scoring
  parent_builder / bsparent / siblings
  rankings / matrix / scoring
  orchestrator / simple_reports
             |
             v
report.json (renderer handoff contract)
             |
             v
Node renderer using the docx library
             |
             +--> output.docx
             +--> output.pdf via LibreOffice headless

The Python layer owns data access and business logic. The Node renderer reads JSON only and never connects to MySQL. Output filenames and directories are supplied by the caller.

Main components

Component	Responsibility
breeding_report_v3/db.py	MySQL query execution, including multi-statement and multi-result-set support
parent_builder.py	Port of FillRSParentV3 and related parent/race/progeny logic
bsparent.py	Port of the narrower Bloodstock BSParent logic
siblings.py	Sibling and sales information
rankings.py	Australian sire and broodmare-sire rankings
matrix.py	Matrix CSV lookup and band matching
scoring.py	Foal Index criteria and group scores
orchestrator.py	Full pedigree assembly, cross data, rankings, matrix and chromosome model
simple_reports.py	Sire, seasonal, table-style and Bloodstock Dam builders
serialize.py	Dataclass-to-JSON contract and shared-reference protection
renderer/render.js	Report-type dispatch and DOCX generation
renderer/lib/chromosome.js	Four-generation chromosome grid layout

Data and configuration

The default connection file is C:\Users\Robert\projects_config\db.json. The connection may open QDB, while report SQL explicitly qualifies legacy rs tables. Configuration can be overridden with --config, BREEDING_REPORT_CONFIG, or the documented RS_DB_* environment variables. Credentials are local-only and must never be committed or published.

For deterministic comparisons, use --stats-before 2026-02-01. The canonical validation pedigree is BRUTAL (sire ID 93686) x KISS MOON (dam ID 531529), Filly.

Development and verification

python -m pip install -r requirements.txt
python -m pytest --assert=plain -p no:cacheprovider
python -m pytest tests_v3 --assert=plain -p no:cacheprovider
node --check breeding_report_v3\renderer\render.js
node --check breeding_report_v3\renderer\lib\chromosome.js

At the repository baseline, 24 Workstream A tests and 30 Workstream B tests pass. Live integration tests are deselected by default.

Validation assets

• examples/brutal_kissmoon.json contains the canonical pedigree IDs and parameters.
• examples/golden/ contains tracked legacy/reference PDFs.
• validate_against_odin.bat regenerates Group A validation output.
• validate_group_bc_against_odin.bat regenerates Group B/C validation output.
• Generated odin_validation/ and group_bc_validation/ content is local output and is ignored by Git.

Current limitations and next actions

1. Run validate_group_bc_against_odin.bat against live rs, inspect every query result, and review the six generated DOCX files.
2. Confirm or replace the assumed Sire Forensic parameters: foal year 2021 and date range 2022-01-01 through 2026-02-01.
3. Reconcile full live Foal Index and Bloodstock totals against the canonical references.
4. Complete the redesigned Bloodstock/presentation layouts. Both full pedigree report types currently use the common pedigree renderer.
5. Implement database-driven pedigree resolution in PedigreeInput.from_horse_id(); full reports currently use explicit IDs or a fixture.
6. Keep LibreOffice installed and on PATH wherever PDF output is required.
7. Reconcile version metadata: CHANGELOG.md declares documentation version 0.5.2, HANDOVER.md declares 0.5.1, while breeding_report_v3.__version__ declares 0.4.1.

Important operational notes

• If a source edit appears not to take effect, clear stale __pycache__ directories.
• MySQL temp-table and multi-result queries must run through the application query runner.
• Sales-only sibling counts can change as the live database evolves; do not force current data to match stale golden counts.
• The original C# solution is outside this repository under the sibling Global Assests\SourceCode\AdminPanel\TrotBetAdmin tree.