equity-aggregator 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

equity_aggregator/domain/pipeline/transforms/group.py

@@ -0,0 +1,48 @@
+# transforms/group.py
+
+import logging
+from collections.abc import AsyncIterable
+from itertools import groupby
+
+from equity_aggregator.schemas.raw import RawEquity
+
+logger = logging.getLogger(__name__)
+
+
+async def group(
+    raw_equities: AsyncIterable[RawEquity],
+) -> AsyncIterable[list[RawEquity]]:
+    """
+    Group equities by share_class_figi, preserving all source data points.
+
+    Groups equities sharing the same share_class_figi identifier into lists,
+    preserving all discovery feed sources. This allows the enrichment stage
+    to compute median identifiers and perform a single merge of all sources
+    (discovery + enrichment) for optimal data quality.
+
+    Args:
+        raw_equities: Async iterable of RawEquity records to group.
+
+    Yields:
+        list[RawEquity]: Groups of equities with the same share_class_figi.
+    """
+    aggregated_raw_equities = [raw_equity async for raw_equity in raw_equities]
+
+    total = len(aggregated_raw_equities)
+    unique = len({equity.share_class_figi for equity in aggregated_raw_equities})
+    duplicates = total - unique
+
+    logger.info(
+        "Grouped %d raw equities with %d duplicates into %d unique groups",
+        total,
+        duplicates,
+        unique,
+    )
+
+    aggregated_raw_equities.sort(key=lambda equity: equity.share_class_figi)
+
+    for _, equity_group in groupby(
+        aggregated_raw_equities,
+        key=lambda equity: equity.share_class_figi,
+    ):
+        yield list(equity_group)

equity_aggregator/logging_config.py

@@ -27,7 +27,10 @@ LOGGING = {
     },
     "formatters": {
         "standard": {
-            "format": "%(asctime)s | %(module)-20s | %(levelname)-5s | %(message)s",
+            "format": (
+                "%(asctime)s | %(module)-20s | %(levelname)-5s | "
+                "%(taskName)-12s | %(message)s"
+            ),
             "datefmt": "%Y-%m-%dT%H:%M:%S",
         },
     },

equity_aggregator/schemas/__init__.py

@@ -2,9 +2,12 @@
 
 from .canonical import CanonicalEquity, EquityFinancials, EquityIdentity
 from .feeds import (
-    EuronextFeedData,
-    LseFeedData,
+    GleifFeedData,
+    IntrinioFeedData,
+    LsegFeedData,
     SecFeedData,
+    StockAnalysisFeedData,
+    TradingViewFeedData,
     XetraFeedData,
     YFinanceFeedData,
 )
@@ -14,11 +17,14 @@ __all__ = [
     "EquityFinancials",
     "EquityIdentity",
     "CanonicalEquity",
-    # authoritative feeds
-    "EuronextFeedData",
-    "LseFeedData",
+    # discovery feeds
+    "IntrinioFeedData",
+    "LsegFeedData",
     "SecFeedData",
+    "StockAnalysisFeedData",
+    "TradingViewFeedData",
     "XetraFeedData",
     # enrichment feeds
+    "GleifFeedData",
     "YFinanceFeedData",
 ]

equity_aggregator/schemas/canonical.py

@@ -14,6 +14,7 @@ from .types import (
     CUSIPStrOpt,
     FIGIStrReq,
     ISINStrOpt,
+    LEIStrOpt,
     MICListOpt,
     SignedDecOpt,
     UnsignedDecOpt,
@@ -27,8 +28,9 @@ class EquityIdentity(BaseModel):
     """
     Globally unique identity metadata for a single equity record.
 
-    The authoritative identifier is `share_class_figi`, which uniquely distinguishes
-    the equity. Other local identifiers such as ISIN, CUSIP or CIK may also be present.
+    The definitive identifier is `share_class_figi`, which uniquely distinguishes
+    the equity. Other local identifiers such as ISIN, CUSIP, CIK or LEI may also
+    be present.
 
     Attributes:
         name (UpperStrReq): Full name of the equity.
@@ -37,14 +39,16 @@ class EquityIdentity(BaseModel):
         isin (ISINStrOpt): Optional International Securities Identification Number.
         cusip (CUSIPStrOpt): Optional CUSIP identifier.
         cik (CIKStrOpt): Optional Central Index Key for SEC filings.
+        lei (LEIStrOpt): Optional Legal Entity Identifier (ISO 17442).
 
     Args:
         name (UpperStrReq): Full name of the equity, required.
         symbol (UpperStrReq): Trading symbol, required.
-        share_class_figi (FIGIStrReq): Authoritative OpenFIGI identifier, required.
+        share_class_figi (FIGIStrReq): Definitive OpenFIGI identifier, required.
         isin (ISINStrOpt): ISIN code, if available.
         cusip (CUSIPStrOpt): CUSIP code, if available.
         cik (CIKStrOpt): CIK code, if available.
+        lei (LEIStrOpt): LEI code, if available.
 
     Returns:
         EquityIdentity: Immutable identity record for the equity.
@@ -56,7 +60,7 @@ class EquityIdentity(BaseModel):
     name: UpperStrReq = Field(..., description="Equity name, required.")
     symbol: UpperStrReq = Field(..., description="Equity symbol, required.")
 
-    # required share_class_figi is the authoritative id uniquely identifying an equity.
+    # required share_class_figi is the definitive id uniquely identifying an equity.
     share_class_figi: FIGIStrReq = Field(
         ...,
         description="Equity share class FIGI, required.",
@@ -66,6 +70,7 @@ class EquityIdentity(BaseModel):
     isin: ISINStrOpt = None
     cusip: CUSIPStrOpt = None
     cik: CIKStrOpt = None
+    lei: LEIStrOpt = None
 
 
 # ─────────────────────── Supplementary financial data ──────────────────────
@@ -104,7 +109,7 @@ class EquityFinancials(BaseModel):
     short_interest: UnsignedDecOpt = None
     share_float: UnsignedDecOpt = None
     shares_outstanding: UnsignedDecOpt = None
-    revenue_per_share: UnsignedDecOpt = None
+    revenue_per_share: SignedDecOpt = None
     profit_margin: SignedDecOpt = None
     gross_margin: SignedDecOpt = None
     operating_margin: SignedDecOpt = None
@@ -114,7 +119,7 @@ class EquityFinancials(BaseModel):
     return_on_assets: SignedDecOpt = None
     performance_1_year: SignedDecOpt = None
     total_debt: UnsignedDecOpt = None
-    revenue: UnsignedDecOpt = None
+    revenue: SignedDecOpt = None
     ebitda: SignedDecOpt = None
     trailing_pe: SignedDecOpt = None
     price_to_book: SignedDecOpt = None

equity_aggregator/schemas/feeds/__init__.py

@@ -1,17 +1,23 @@
 # feeds/__init__.py
 
-from .euronext_feed_data import EuronextFeedData
-from .lse_feed_data import LseFeedData
+from .gleif_feed_data import GleifFeedData
+from .intrinio_feed_data import IntrinioFeedData
+from .lseg_feed_data import LsegFeedData
 from .sec_feed_data import SecFeedData
+from .stock_analysis_feed_data import StockAnalysisFeedData
+from .tradingview_feed_data import TradingViewFeedData
 from .xetra_feed_data import XetraFeedData
 from .yfinance_feed_data import YFinanceFeedData
 
 __all__ = [
-    # authoritative feeds
-    "EuronextFeedData",
-    "LseFeedData",
+    # discovery feeds
+    "IntrinioFeedData",
+    "LsegFeedData",
     "SecFeedData",
+    "StockAnalysisFeedData",
+    "TradingViewFeedData",
     "XetraFeedData",
     # enrichment feeds
+    "GleifFeedData",
     "YFinanceFeedData",
 ]

equity_aggregator/schemas/feeds/gleif_feed_data.py

@@ -0,0 +1,35 @@
+# feeds/gleif_feed_data.py
+
+from pydantic import BaseModel, ConfigDict
+
+from .feed_validators import required
+
+
+@required("name", "symbol")
+class GleifFeedData(BaseModel):
+    """
+    GleifFeedData represents a single record from the GLEIF ISIN->LEI mapping feed.
+
+    This is a minimal enrichment feed that provides LEI (Legal Entity Identifier)
+    data based on ISIN lookups. The name and symbol fields are passed through from
+    the source equity to satisfy RawEquity requirements.
+
+    Args:
+        name (str): The equity name (passed through from source).
+        symbol (str): The equity symbol (passed through from source).
+        isin (str | None): The ISIN used for the LEI lookup.
+        lei (str | None): The Legal Entity Identifier from GLEIF mapping.
+    """
+
+    # Fields exactly match RawEquity's signature
+    name: str
+    symbol: str
+    isin: str | None = None
+    lei: str | None = None
+
+    model_config = ConfigDict(
+        # ignore extra fields in incoming GLEIF raw data feed
+        extra="ignore",
+        # defer strict type validation to RawEquity
+        strict=False,
+    )

equity_aggregator/schemas/feeds/intrinio_feed_data.py

@@ -0,0 +1,142 @@
+# feeds/intrinio_feed_data.py
+
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from .feed_validators import required
+
+
+@required("name", "symbol")
+class IntrinioFeedData(BaseModel):
+    """
+    Represents a single Intrinio feed record, transforming and normalising
+    incoming fields to match the RawEquity model's expected attributes.
+
+    Combines company metadata from the /companies endpoint, security identifiers from
+    the /companies/{ticker}/securities endpoint, and quote data from the
+    /securities/{share_class_figi}/quote endpoint.
+
+    Args:
+        name (str): Company name.
+        symbol (str): Equity symbol, mapped from security "ticker".
+        cik (str | None): Central Index Key (10-digit zero-padded string from API).
+        lei (str | None): Legal Entity Identifier from company data.
+        share_class_figi (str | None): Share class FIGI identifier.
+        mics (list[str] | None): Market Identifier Codes from exchange_mic.
+        currency (str | None): The trading currency.
+        last_price (str | float | Decimal | None): Last traded price.
+        fifty_two_week_min (str | float | Decimal | None): 52-week low price.
+        fifty_two_week_max (str | float | Decimal | None): 52-week high price.
+        market_volume (str | float | Decimal | None): Latest trading volume.
+        dividend_yield (str | float | Decimal | None): Annual dividend yield.
+        market_cap (str | float | Decimal | None): Market capitalisation.
+        performance_1_year (str | float | Decimal | None): 1-year performance.
+
+    Returns:
+        IntrinioFeedData: An instance with fields normalised for RawEquity
+            validation.
+    """
+
+    # Fields match RawEquity's signature
+    name: str
+    symbol: str
+    cik: str | None = None
+    lei: str | None = None
+    share_class_figi: str | None = None
+    mics: list[str] | None = None
+    currency: str | None = None
+    last_price: str | float | Decimal | None = None
+    fifty_two_week_min: str | float | Decimal | None = None
+    fifty_two_week_max: str | float | Decimal | None = None
+    market_volume: str | float | Decimal | None = None
+    dividend_yield: str | float | Decimal | None = None
+    market_cap: str | float | Decimal | None = None
+    performance_1_year: str | float | Decimal | None = None
+
+    @model_validator(mode="before")
+    def _normalise_fields(self: dict[str, object]) -> dict[str, object]:
+        """
+        Normalise a raw Intrinio feed record into the flat schema expected
+        by RawEquity.
+
+        Combines company data, security data, and quote data, mapping fields to
+        RawEquity attributes.
+
+        Args:
+            self (dict[str, object]): Raw payload containing Intrinio feed
+                data with quote data.
+
+        Returns:
+            dict[str, object]: A new dictionary with renamed keys suitable for the
+                RawEquity schema.
+        """
+        # Extract quote data if present
+        quote = self.get("quote", {}) or {}
+
+        # Build MICs list from exchange_mic if present
+        exchange_mic = self.get("exchange_mic")
+        mics = [exchange_mic] if exchange_mic else None
+
+        return {
+            # name → RawEquity.name
+            "name": self.get("name"),
+            # cik → RawEquity.cik
+            "cik": self.get("cik"),
+            # lei → RawEquity.lei
+            "lei": self.get("lei"),
+            # ticker → RawEquity.symbol
+            "symbol": self.get("ticker"),
+            # share_class_figi → RawEquity.share_class_figi
+            "share_class_figi": self.get("share_class_figi"),
+            # exchange_mic → RawEquity.mics
+            "mics": mics,
+            # security.currency → RawEquity.currency
+            "currency": self.get("currency"),
+            # last → RawEquity.last_price
+            "last_price": quote.get("last"),
+            # eod_fifty_two_week_low → RawEquity.fifty_two_week_min
+            "fifty_two_week_min": quote.get("eod_fifty_two_week_low"),
+            # eod_fifty_two_week_high → RawEquity.fifty_two_week_max
+            "fifty_two_week_max": quote.get("eod_fifty_two_week_high"),
+            # market_volume → RawEquity.market_volume
+            "market_volume": quote.get("market_volume"),
+            # dividendyield → RawEquity.dividend_yield
+            "dividend_yield": quote.get("dividendyield"),
+            # marketcap → RawEquity.market_cap
+            "market_cap": quote.get("marketcap"),
+            # change_percent_365_days → RawEquity.performance_1_year
+            # Convert from percentage (e.g., 14.6572) to decimal (0.146572)
+            "performance_1_year": _percent_to_decimal(
+                quote.get("change_percent_365_days"),
+            ),
+        }
+
+    model_config = ConfigDict(
+        # ignore extra fields in incoming Intrinio raw data feed
+        extra="ignore",
+        # defer strict type validation to RawEquity
+        strict=False,
+    )
+
+
+def _percent_to_decimal(percent: str | float | None) -> Decimal | None:
+    """
+    Convert a percentage value to decimal format.
+
+    Converts percentage values (e.g., 14.6572 representing 14.6572%) to decimal
+    format (0.146572) for consistency with RawEquity's performance_1_year field.
+
+    Args:
+        percent (str | float | None): The percentage value to convert.
+
+    Returns:
+        Decimal | None: The decimal value, or None if input is None or invalid.
+    """
+    if percent is None:
+        return None
+
+    try:
+        return Decimal(str(percent)) / Decimal("100")
+    except (ValueError, TypeError):
+        return None

equity_aggregator/schemas/feeds/{lse_feed_data.py → lseg_feed_data.py}

@@ -1,4 +1,4 @@
-# feeds/lse_feed_data.py
+# feeds/lseg_feed_data.py
 
 import re
 from decimal import Decimal
@@ -9,27 +9,30 @@ from .feed_validators import required
 
 
 @required("name", "symbol")
-class LseFeedData(BaseModel):
+class LsegFeedData(BaseModel):
     """
-    Represents a single LSE feed record, transforming and normalising incoming fields
-    to match the RawEquity model's expected attributes. If the currency is "GBX",
+    Represents single LSEG feed record, transforming and normalising incoming
+    fields to match the RawEquity model's expected attributes. If the currency is "GBX",
     price fields such as "last_price" are automatically converted from pence to
     pounds (GBP) for consistency.
 
     Args:
         name (str): The issuer's full name, mapped from "issuername".
-        symbol (str): The tradable instrument mnemonic, mapped from "tidm".
+        symbol (str): The tradable instrument symbol, mapped from "tidm".
         isin (str | None): The ISIN identifier, if available.
-        mics (list[str]): List of MIC codes for trading venues; defaults to ["XLON"].
         currency (str | None): The trading currency code, with "GBX" converted to
             "GBP" if applicable.
         last_price (str | float | int | Decimal | None): Last traded price, mapped
             from "lastprice" and converted from pence to pounds if currency is "GBX".
-        market_cap (str | float | int | Decimal | None): Market capitalisation, mapped
-            from "marketcapitalization".
+        market_cap (str | float | int | Decimal | None): Market capitalisation,
+            mapped from "marketcapitalization".
+        fifty_two_week_min (str | float | int | Decimal | None): 52-week low,
+            mapped from "fiftyTwoWeeksMin" (converted from pence to GBP if needed).
+        fifty_two_week_max (str | float | int | Decimal | None): 52-week high,
+            mapped from "fiftyTwoWeeksMax" (converted from pence to GBP if needed).
 
     Returns:
-        LseFeedData: An instance with fields normalised for RawEquity validation,
+        LsegFeedData: An instance with fields normalised for RawEquity validation,
             including automatic GBX to GBP conversion where relevant.
     """
 
@@ -37,61 +40,97 @@ class LseFeedData(BaseModel):
     name: str
     symbol: str
     isin: str | None
-    mics: list[str]
     currency: str | None
     last_price: str | float | int | Decimal | None
     market_cap: str | float | int | Decimal | None
-    fifty_two_week_min: str | float | int | Decimal | None = None
-    fifty_two_week_max: str | float | int | Decimal | None = None
+    fifty_two_week_min: str | float | int | Decimal | None
+    fifty_two_week_max: str | float | int | Decimal | None
 
     @model_validator(mode="before")
     def _normalise_fields(self: dict[str, object]) -> dict[str, object]:
         """
-        Normalise a raw LSE feed record into the flat schema expected by RawEquity.
+        Normalise raw LSEG feed record into the flat schema expected by RawEquity.
 
         Extracts and renames nested fields to match the RawEquity signature. If the
         currency is "GBX", automatically converts price fields from pence to pounds
-        (GBP) using the convert_gbx_to_gbp helper.
+        (GBP) using the convert_gbx_to_gbp helper. Treats 0 as None for monetary
+        fields since LSEG API uses 0 to represent missing data for certain fields.
 
         Args:
-            self (dict[str, object]): Raw payload containing raw LSE feed data.
+            self (dict[str, object]): Raw payload containing raw LSEG feed data.
 
         Returns:
             dict[str, object]: A new dictionary with renamed keys and, if applicable,
             price and currency fields converted from GBX to GBP, suitable for the
             RawEquity schema.
         """
-        # convert GBX to GBP
-        raw = convert_gbx_to_gbp(self)
+
+        # convert GBX to GBP and sanitise zero monetary values
+        raw = _convert_gbx_to_gbp(self)
+        raw = _sanitise_zero_monetary_values(raw)
+
         return {
-            # issuername → maps to RawEquity.name
             "name": raw.get("issuername"),
-            # tidm → maps to RawEquity.symbol
             "symbol": raw.get("tidm"),
             "isin": raw.get("isin"),
-            # no CUSIP, CIK or FIGI in LSE feed, so omitting from model
-            # default to XLON if mic not provided
-            "mics": raw.get("mics") or ["XLON"],
+            # no CUSIP, CIK or FIGI in LSEG feed, so omitting from model
             "currency": raw.get("currency"),
-            # lastprice → maps to RawEquity.last_price
             "last_price": raw.get("lastprice"),
-            # marketcapitalization → maps to RawEquity.market_cap
             "market_cap": raw.get("marketcapitalization"),
-            # fiftyTwoWeeksMin → maps to RawEquity.fifty_two_week_min
             "fifty_two_week_min": raw.get("fiftyTwoWeeksMin"),
-            # fiftyTwoWeeksMax → maps to RawEquity.fifty_two_week_max
             "fifty_two_week_max": raw.get("fiftyTwoWeeksMax"),
-            # no additional fields in LSE feed, so omitting from model
+            # no additional fields in LSEG feed, so omitting from model
         }
 
     model_config = ConfigDict(
-        # ignore extra fields in incoming LSE raw data feed
+        # ignore extra fields in incoming LSEG raw data feed
         extra="ignore",
         # defer strict type validation to RawEquity
         strict=False,
     )
 
 
+def _convert_gbx_to_gbp(raw: dict) -> dict:
+    """
+    Convert price and currency fields from GBX (pence) to GBP (pounds).
+
+    If the input dictionary has a "currency" field set to "GBX", this function
+    divides all price fields (lastprice, fiftyTwoWeeksMin, fiftyTwoWeeksMax)
+    by 100 to convert from pence to pounds, sets the "currency" field to "GBP",
+    and returns a new dictionary with these updates. All other fields remain
+    unchanged. If the currency is not "GBX", the original dictionary is returned
+    unmodified.
+
+    Args:
+        raw (dict): A dictionary containing at least a "currency" field, and
+            optionally price fields representing values in pence.
+
+    Returns:
+        dict: A new dictionary with price fields converted to pounds and
+        "currency" set to "GBP" if original currency was "GBX". Otherwise,
+        returns original dict.
+    """
+    if raw.get("currency") != "GBX":
+        return raw
+
+    updates = {"currency": "GBP"}
+
+    # Convert lastprice
+    lastprice = _gbx_to_decimal(raw.get("lastprice"))
+    updates["lastprice"] = lastprice / Decimal("100") if lastprice else None
+
+    # Convert fiftyTwoWeeksMin
+    min_price = _gbx_to_decimal(raw.get("fiftyTwoWeeksMin"))
+    updates["fiftyTwoWeeksMin"] = min_price / Decimal("100") if min_price else None
+
+    # Convert fiftyTwoWeeksMax
+    max_price = _gbx_to_decimal(raw.get("fiftyTwoWeeksMax"))
+    updates["fiftyTwoWeeksMax"] = max_price / Decimal("100") if max_price else None
+
+    # return a new dict rather than mutating in place
+    return {**raw, **updates}
+
+
 def _gbx_to_decimal(pence: str | None) -> Decimal | None:
     """
     Convert a pence string (e.g., "150", "1,50") to a Decimal value.
@@ -122,36 +161,30 @@ def _gbx_to_decimal(pence: str | None) -> Decimal | None:
     return Decimal(s)
 
 
-def convert_gbx_to_gbp(raw: dict) -> dict:
+def _sanitise_zero_monetary_values(raw: dict) -> dict:
     """
-    Converts price and currency fields from GBX (pence) to GBP (pounds) if applicable.
+    Treat 0 as None for LSEG monetary fields.
 
-    If the input dictionary has a "currency" field set to "GBX", this function divides
-    the "lastprice" value by 100 to convert from pence to pounds, sets the "currency"
-    field to "GBP", and returns a new dictionary with these updates. All other fields
-    remain unchanged. If the currency is not "GBX", the original dictionary is returned
-    unmodified.
+    LSEG API returns 0 for missing monetary data. Since 0 is not a valid
+    price or market cap, we treat it as None to allow enrichment feeds
+    to provide valid data downstream.
 
     Args:
-        raw (dict): A dictionary containing at least a "currency" field, and optionally
-            a "lastprice" field representing the price in pence.
+        raw: Dictionary containing LSEG API fields.
 
     Returns:
-        dict: A new dictionary with "lastprice" converted to pounds and "currency" set
-        to "GBP" if original currency was "GBX". Otherwise, returns original dict.
+        A new dictionary with 0 values converted to None for monetary fields.
     """
-    if raw.get("currency") != "GBX":
-        return raw
-
-    pence = raw.get("lastprice")
-    amount = _gbx_to_decimal(pence)
+    monetary_fields = [
+        "lastprice",
+        "marketcapitalization",
+        "fiftyTwoWeeksMin",
+        "fiftyTwoWeeksMax",
+    ]
+
+    updates = {
+        field: None if raw.get(field) == 0 else raw.get(field)
+        for field in monetary_fields
+    }
 
-    updates = {"currency": "GBP"}
-    if amount is None:
-        updates["lastprice"] = None
-    else:
-        # convert pence to pounds
-        updates["lastprice"] = amount / Decimal("100")
-
-    # return a new dict rather than mutating in place
     return {**raw, **updates}

equity_aggregator/schemas/feeds/sec_feed_data.py

@@ -14,13 +14,15 @@ class SecFeedData(BaseModel):
     Args:
         name (str): Company name, mapped from "name".
         symbol (str): Equity symbol, mapped from "symbol".
+        cik (str): Central Index Key, converted from int to 10-digit zero-padded string.
         mics (list[str]): List of MIC codes; defaults to an empty list if missing.
 
     Returns:
-        EuronextFeedData: An instance with fields normalised for RawEquity validation.
+        SecFeedData: An instance with fields normalised for RawEquity validation.
     """
 
-    # Fields exactly match RawEquity’s signature
+    # Fields exactly match RawEquity's signature
+    cik: str
     name: str
     symbol: str
     mics: list[str]
@@ -37,12 +39,15 @@ class SecFeedData(BaseModel):
             dict[str, object]: A new dictionary with renamed keys suitable for the
                 RawEquity schema.
         """
+        # convert int CIK to string
+        raw = convert_cik_to_str(self)
+
         return {
-            "name": self.get("name"),
-            "symbol": self.get("symbol"),
-            "cik": self.get("cik"),
+            "cik": raw.get("cik"),
+            "name": raw.get("name"),
+            "symbol": raw.get("symbol"),
             # no CUSIP, ISIN or FIGI in SEC feed, so omitting from model
-            "mics": self.get("mics"),
+            "mics": raw.get("mics"),
             # no currency or last_price in SEC feed, so omitting from model
             # no more additional fields in SEC feed, so omitting from model
         }
@@ -53,3 +58,28 @@ class SecFeedData(BaseModel):
         # defer strict type validation to RawEquity
         strict=False,
     )
+
+
+def convert_cik_to_str(raw: dict) -> dict:
+    """
+    Normalise SEC CIK integer value to ensure compatibility with RawEquity schema.
+
+    The SEC API returns CIK values as integers, but the RawEquity schema expects
+    10-digit zero-padded string values for all CIK fields. This function converts
+    integer CIK values to properly formatted strings while preserving all other
+    fields unchanged.
+
+    Args:
+        raw (dict): A dictionary containing raw SEC feed data with potentially
+            integer CIK values.
+
+    Returns:
+        dict: A new dictionary with CIK converted to 10-digit zero-padded string
+            if present and not None. All other fields remain unchanged.
+    """
+    # Convert integer CIK to 10-digit zero-padded string
+    cik_value = raw.get("cik")
+    updates = {"cik": str(cik_value).zfill(10)}
+
+    # Return new dict rather than mutating in place
+    return {**raw, **updates}