35 Slice Commercial Intelligence

Pipeline Slice: Commercial Intelligence

Status: CONVERGED CORE VERTICAL. Fixture/live SEC filing capture, deterministic Inline XBRL extraction, exact product and filer resolution, canonical observations, reviewed summaries, query models, checks, and database acceptance tests are implemented. Denoising state: converged (noise -> rough -> sharp -> converged) Updated: 2026-07-23

Purpose

Publish source-reported commercial facts about pharmaceutical products without turning reporting conventions, currency conversions, or forecasts into hidden truth.

This slice answers:

What commercial performance did a company report for this product, in which market and period, in what currency, and where exactly was it reported?

It supports drug and organisation profiles. It does not own market forecasts, valuation, revenue projections, or company-wide financial accounting.

Boundary Decisions

Product sales are observations tied to a reporting organisation, product, period, geography, metric, and source.
Reported and normalized currency values are separate. Every conversion has a rate/source/date receipt.
Annual, quarterly, year-to-date, trailing-period, and point-in-time facts never mix without an explicit deterministic derivation.
Restated values supersede for a named use case but never erase the originally reported observation.
Brand/product identity comes from the drug/regulatory spines; organisation identity comes from the organisation slice.
Regulatory exclusivity and approval facts are owned by the regulatory approvals slice. Commercial summaries may project them but do not duplicate canonical ownership.
Forecasts and analyst estimates are separate evidence kinds and are out of the default commercial-fact contract.

Legacy Intent and Correction

Data Gov’s brand-sales models and Aero’s drug/organisation tabs establish a real requirement: show reported commercial performance beside a product and its owner. The legacy shape compressed that intent into a few US/non-US, year/quarter, USD-oriented fields and inherited validation quirks such as incomplete quarter handling.

Greenfield preserves the product question and corrects the model:

fiscal and calendar periods remain explicit;
Q4 is valid;
geography is a dimension, not a pair of hardcoded columns;
source-reported currency remains authoritative;
conversions are derived facts with receipts;
restatements and continuing/discontinued-operation context remain visible;
no reported value is silently interpreted as a forecast or vice versa.

Source Inventory

Source family	Authority / use	Capture unit
SEC EDGAR filing and Inline XBRL	filed US company facts, tables, and footnotes	immutable filing, filing facts payload, XBRL fact/context/unit
issuer annual/quarterly report	product-level tables or narrative not available as a clean XBRL concept	exact versioned report/table/footnote
regulator product/exclusivity data	approval, patent, and exclusivity context	owned by `22-slice-regulatory-approvals.md`; consumed through canonical relations
reviewed exchange-rate source	normalization to a declared currency	versioned rate observation with pair, date/period, and method
licensed commercial source	optional supplemental facts under explicit license	immutable licensed artifact with access/retention metadata

Primary references:

SEC EDGAR APIs: https://www.sec.gov/search-filings/edgar-application-programming-interfaces
SEC Inline XBRL: https://www.sec.gov/data-research/structured-data/inline-xbrl
FDA Orange Book data files: https://www.fda.gov/drugs/drug-approvals-and-databases/orange-book-data-files

Domain Model

Noun	Grain	Meaning
Commercial Metric Definition	one metric/version	Defines net sales, product revenue, units, or another reported metric and its aggregation rules.
Product Sales Observation	one source-reported metric for one product/reporting organisation/geography/period	The source-faithful commercial fact, including reported value/currency and exact filing locator.
FX Conversion Receipt	one observation + target currency + conversion policy/version	Records rate source, rate, rate date/period, method, and converted value without replacing the reported value.
Commercial Summary Selection	one product/context/use-case policy decision	Selects current comparable observations and any regulatory context for a compact profile while retaining alternatives.

Product and organisation relationships

brand_key, regulatory product key, and resolved_drug_key come from the drug and regulatory slices;
reporting_org_key identifies the organisation that made the statement;
economic_owner_org_key is a temporal relationship supplied by the organisation slice and may differ from the reporting organisation;
acquisition/licensing changes do not rewrite older observations to the current owner;
reported product labels remain available even when resolution is pending.

Observation fields

Every sales observation preserves:

source-native product label and resolved product/drug keys;
reporting organisation and source filing/report key;
metric definition and reported accounting label;
fiscal year, fiscal quarter when applicable, period start/end, and period kind;
geography/market and continuing/discontinued-operation context;
reported numeric value, currency, scale, and unit;
source-native comparative/restatement relationship;
exact table, row, column, fact/context, or paragraph locator;
effective/report/observed timestamps, assertion state, and provenance key.

Derived values carry a derivation key and never occupy the reported-value columns.

Asset Flow

filing/report artifact
  -> structured XBRL/table facts or located text claims
  -> product + organisation + metric resolution
  -> product sales observations
  -> optional FX conversion receipts
  -> selected commercial summary
  -> q_product_sales / q_product_commercial_summary

Canonical assets:

canonical.commercial_metric_definitions;
canonical.product_sales_observations;
canonical.fx_conversion_receipts;
reviewed summary selections remain curation overlays.

Regulatory approvals owns canonical.regulatory_product_protections and its direct query model. This slice may join that canonical asset into a compact commercial summary; it must not create another protection/exclusivity truth table.

Query Models

`q_product_sales`

Contract field	Required meaning
Purpose	Full-fidelity reported product sales for product and organisation analysis.
Grain	One source-reported metric for one product + reporting organisation + geography + reporting period.
Stable row key	`product_sales_observation_key`.
Required columns	product/drug/brand keys and source label; reporting and economic-owner org keys; metric; period/fiscal fields; geography; reported value/currency/scale; normalized value/currency plus FX receipt when requested; restatement/supersession; source filing/report; assertion state; provenance key.
Provenance	field/bundle provenance to the exact XBRL fact or report table/text locator, resolution receipt, and conversion receipt.
Search/indexes	product, drug, reporting/economic-owner org, period, geography, metric, currency, source filing.

`q_product_commercial_summary`

One row per product + summary profile + selected_as_of. It may expose latest annual and latest quarterly reported observations, reporting/economic-owner organisations, regions represented, and selected regulatory exclusivity context from the regulatory owner.

Every summarized value retains the selected observation key, selection policy/revision, reported period/currency, and provenance. The model must not add annual and quarterly values, annualize a quarter, or calculate a forecast.

Regulatory exclusivity surface

The regulatory approvals slice owns q_regulatory_product_protections at one regulator product + source protection-record grain. Commercial consumers join by regulator product and drug/brand keys. q_product_commercial_summary may include selected next-expiry context, but the source record remains in the regulatory model.

Deterministic and Inference Boundary

Use structured XBRL/API facts first. Deterministic compute owns period, currency, scale, context, duplicate, restatement, and conversion handling.

Inference is justified only when product-level data lives in filing tables, footnotes, or narrative that structured facts cannot represent cleanly. It must emit exact locators, source-native labels, reported periods/currencies, and structured candidate observations through the inference lifecycle. It must not guess product allocation, infer an omitted geography, or convert prose such as “grew strongly” into a numeric fact.

Curation Subjects

filing product label to brand/regulatory product/drug mapping;
reporting organisation versus economic-owner relationship correction;
commercial metric-definition mapping;
restatement/supersession relation;
preferred summary selection;
suppression of duplicated or source-erroneous observations.

Blocking Checks

shared schema_contract, referential_integrity, source_locator, source_authority, temporal_validity, and provenance_coverage gates;
commercial_observation_semantics, a slice-owned gate suite that verifies:
- period start <= period end and fiscal quarter is 1-4 when present;
- reported currency, value, and scale remain intact;
- converted values always have an FX conversion receipt and declared policy;
- annual, quarterly, YTD, and trailing-period grains do not collide;
- geography aggregations are source-compatible;
- restatement chains are acyclic and preserve originals;
- one active observation exists per source fact/context/revision;
- summaries resolve to active observations and an active selection policy;
- no forecast/estimate appears as reported actual without an explicit evidence kind.

Acceptance Scenarios

Scenario	Expected result
company reports Q4 product sales	valid quarterly observation; not rejected or treated as annual
annual and Q4 values occur in one filing	distinct observations; summary does not add them
product is reported in EUR and profile requests USD	EUR remains reported truth; USD value has a versioned FX receipt
filing restates the prior year’s value	original and restated observations remain; current selection points to restatement
product is sold globally and in the US	separate geography observations unless source explicitly reports a non-overlapping total
company acquired mid-year	historical reporting organisation and temporal owner remain correct for each period
filing only says sales increased	no numeric observation is invented
analyst forecast appears beside actual sales	forecast remains outside default `q_product_sales` or carries an explicit non-actual evidence kind in a future contract

Forecasting Boundary

This slice owns source-reported commercial facts. Downstream forecasting owns market models, growth assumptions, scenario math, valuation, and projected revenue. 28-slice-forecasting-tpp.md may consume selected source facts as inputs or readiness diagnostics without moving forecast outputs back into this slice.

Implementation Map

Responsibility	Implementation owner
SEC fixture/live filer and filing capture	`lib/sources/sec/` and `defs/sources/sec/`
Inline XBRL context/unit/fact parser	`lib/sources/sec/inline_xbrl.py`
Conservative product-sales projection	`lib/sources/sec/product_sales.py`
Normalize, evidence, and exact identity resolution	`defs/normalized/commercial.py`, `defs/evidence/commercial.py`, `defs/resolution/commercial.py`
Canonical observations, FX receipts, reviewed summaries	`defs/canonical/commercial.py` and `sql/canonical/commercial/`
Agent-facing read models and gates	`defs/query/commercial.py`, `sql/query/commercial/`, and `lib/checks/contracts_schema/commercial__*.yaml`
Parser, fixture, and Postgres acceptance tests	`tests/test_sec_source.py` and `tests/test_slice_commercial.py`

The parser retains all product-dimension numeric facts, but only known revenue concepts with a currency unit and duration context may publish automatically. Custom concepts and ambiguous product or organisation identities are parked for review; the code does not guess their meaning. The checked-in Merck document is a compact, exact Inline XBRL fixture containing the tested filing contexts and facts, not a republished full filing.

Fixture mode is the deterministic default. Live mode requires explicit official filing URLs and can be bounded for a free smoke run:

resources:
  sec_source:
    config:
      mode: live
      user_agent: "Bioloupe Data monitored-contact@example.com"
      requests_per_second: 5
      commercial_filing_urls:
        - https://www.sec.gov/Archives/edgar/data/.../filing.htm
      max_live_records: 1

The reported value remains authoritative. A converted value appears only after a source-backed, versioned row exists in canonical.fx_conversion_receipts; no implicit current-rate lookup occurs during publication.

SEC live capture requires the declared organisation/contact user agent and enforces a configured rate no higher than SEC’s 10-requests-per-second fair-access ceiling. Transient 429 and 5xx responses receive bounded backoff; persistent failures fail the source asset closed.