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

equity_aggregator/domain/pipeline/transforms/enrich.py

@@ -3,422 +3,465 @@
 import asyncio
 import logging
 from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 from typing import NamedTuple
 
-from equity_aggregator.adapters import open_yfinance_feed
-from equity_aggregator.domain._utils import get_usd_converter, merge
+from equity_aggregator.adapters import open_gleif_feed, open_yfinance_feed
+from equity_aggregator.domain._utils import (
+    EquityIdentifiers,
+    extract_identifiers,
+    get_usd_converter,
+    merge,
+)
+from equity_aggregator.schemas import GleifFeedData, YFinanceFeedData
 from equity_aggregator.schemas.raw import RawEquity
-from equity_aggregator.schemas import YFinanceFeedData
 
 logger = logging.getLogger(__name__)
 
 # Type alias for an async function that fetches enrichment data for an equity
-type FetchFunc = Callable[..., Awaitable[dict[str, object]]]
+type FetchFunc = Callable[..., Awaitable[dict[str, object] | None]]
 
-# Type alias for a factory that creates an async feed context manager
-type FeedFactory = Callable[[], AsyncIterator[object]]
 
-# Type alias for a tuple describing a feed: (factory, model, concurrency limit)
-type FeedSpec = tuple[FeedFactory, type, int]
+class FeedSpec(NamedTuple):
+    """
+    Static specification for an enrichment feed.
 
-# Type alias for a function that validates and converts feed data to RawEquity
-type ValidatorFunc = Callable[[dict[str, object], RawEquity], RawEquity]
+    Attributes:
+        factory: Async context manager factory that yields a feed instance.
+        model: Pydantic model for validating feed data.
+        limit: Maximum number of concurrent requests to this feed.
+    """
 
-# List of enrichment feeds to use, each with its factory, model, and concurrency limit
-feed_specs: list[FeedSpec] = [
-    (
-        open_yfinance_feed,  # factory for creating YFinance feed context
-        YFinanceFeedData,  # data model for YFinance feed data
-        10,  # concurrency limit (max simultaneous YFinance requests)
-    ),
-]
+    factory: Callable
+    model: type
+    limit: int
 
 
 class EnrichmentFeed(NamedTuple):
     """
-    Represents a feed for enrichment in a data pipeline.
+    Runtime instance of an enrichment feed with rate limiting applied.
 
-    Args:
-        fetch (FetchFunc): A callable responsible for fetching enrichment data.
-        model (type): The type of model to use for enrichment.
-        semaphore (asyncio.Semaphore): Semaphore to control concurrency for fetch.
-
-    Returns:
-        EnrichmentFeed: A named tuple containing fetch, model, and semaphore.
+    Attributes:
+        fetch: Rate-limited async function to fetch enrichment data.
+        model: Pydantic model for validating feed data.
     """
 
     fetch: FetchFunc
     model: type
-    semaphore: asyncio.Semaphore
+
+
+# Specification for all enrichment feeds
+enrichment_feed_specs: tuple[FeedSpec, ...] = (
+    FeedSpec(open_yfinance_feed, YFinanceFeedData, 20),
+    FeedSpec(open_gleif_feed, GleifFeedData, 100),
+)
 
 
 async def enrich(
-    raw_equities: AsyncIterable[RawEquity],
+    equity_groups: AsyncIterable[list[RawEquity]],
 ) -> AsyncIterable[RawEquity]:
     """
-    Enrich a stream of RawEquity objects concurrently using configured feeds.
+    Enrich equity groups and merge all sources (discovery + enrichment).
 
-    Each RawEquity is scheduled for enrichment and yielded as soon as its
-    enrichment completes. Enrichment is performed concurrently, respecting
-    per-feed concurrency limits.
+    For each group of discovery feed equities, computes median identifiers,
+    queries enrichment feeds, then performs a single merge of all sources
+    for optimal data quality.
 
     Args:
-        raw_equities (AsyncIterable[RawEquity]):
-            Async iterable stream of RawEquity objects to enrich.
+        equity_groups: Stream of equity groups (discovery feed sources).
 
-    Returns:
-        AsyncIterable[RawEquity]: Yields each enriched RawEquity as soon as
-        enrichment finishes.
+    Yields:
+        RawEquity: Fully merged and enriched equities.
     """
-    async with AsyncExitStack() as stack:
-        feeds: list[EnrichmentFeed] = [
-            EnrichmentFeed(
-                fetch=(await stack.enter_async_context(factory())).fetch_equity,
-                model=model,
-                semaphore=asyncio.Semaphore(limit),
-            )
-            for factory, model, limit in feed_specs
-        ]
+    async with _open_feeds(enrichment_feed_specs) as feeds:
+        async for enriched in _process_stream(equity_groups, feeds):
+            yield enriched
+
 
-        # launch enrichment tasks and yield results as they complete
-        async with asyncio.TaskGroup() as enrich_tasks:
-            tasks: list[asyncio.Task[RawEquity]] = []
-            async for equity in raw_equities:
-                tasks.append(
-                    enrich_tasks.create_task(_enrich_equity(equity, feeds)),
-                )
+@asynccontextmanager
+async def _open_feeds(
+    specs: tuple[FeedSpec, ...],
+) -> AsyncIterator[tuple[EnrichmentFeed, ...]]:
+    """
+    Open and initialise all enrichment feeds with lifecycle management.
+
+    Creates an async context that initialises each feed with rate-limited fetch
+    functions, manages their lifecycle through AsyncExitStack, and logs completion
+    when the context exits. All feeds are initialised sequentially to ensure
+    proper resource allocation.
 
-            for completed in asyncio.as_completed(tasks):
-                enriched = await completed
-                yield enriched
+    Args:
+        specs: Tuple of feed specifications to initialise.
+
+    Yields:
+        tuple[EnrichmentFeed, ...]: Initialised feeds with rate limiting applied,
+            ready for concurrent enrichment operations.
+    """
+    async with AsyncExitStack() as stack:
+        feeds = tuple([await _init_feed(spec, stack) for spec in specs])
+        yield feeds
 
     logger.info(
-        "Enrichment finished for %d equities using enrichment feeds: %s",
-        len(tasks),
-        ", ".join(feed.model.__name__.removesuffix("FeedData") for feed in feeds),
+        "Enrichment finished using feeds: %s",
+        ", ".join(_feed_name(f.model) for f in feeds),
     )
 
 
-async def _enrich_equity(
-    source: RawEquity,
-    feeds: list[EnrichmentFeed],
-) -> RawEquity:
+async def _init_feed(spec: FeedSpec, stack: AsyncExitStack) -> EnrichmentFeed:
     """
-    Enrich a RawEquity instance concurrently using all configured enrichment feeds.
+    Initialise a single enrichment feed with rate limiting and lifecycle management.
 
-    For each feed, fetch and validate data for the given equity. Merge results with
-    the source, preferring non-None fields from the source.
+    Opens the feed using its factory, registers it with the provided AsyncExitStack
+    for automatic cleanup, wraps the fetch function with semaphore-based rate
+    limiting, and returns a ready-to-use EnrichmentFeed instance.
 
     Args:
-        source (RawEquity): The RawEquity object to enrich (assumed USD-denominated).
-        feeds (list[EnrichmentFeed]): List of enrichment feeds to use.
+        spec: Feed specification containing factory, model, and concurrency limit.
+        stack: AsyncExitStack to manage the feed's async context lifecycle.
 
     Returns:
-        RawEquity: The enriched RawEquity with missing fields filled where possible.
+        EnrichmentFeed: Initialised feed with rate-limited fetch function and
+            validation model.
     """
+    feed_instance = await stack.enter_async_context(spec.factory())
 
-    async def run(feed: EnrichmentFeed) -> RawEquity:
-        """
-        Enrich a RawEquity using a single feed, respecting the feed's concurrency
-        limit.
+    return EnrichmentFeed(
+        fetch=_rate_limited(feed_instance.fetch_equity, asyncio.Semaphore(spec.limit)),
+        model=spec.model,
+    )
 
-        Args:
-            feed (EnrichmentFeed): The enrichment feed containing the fetch function,
-                model, and semaphore for concurrency control.
 
-        Returns:
-            RawEquity: The enriched RawEquity instance, or the original if enrichment
-                fails.
-        """
-        async with feed.semaphore:
-            return await _enrich_with_feed(source, feed.fetch, feed.model)
+def _rate_limited(
+    fn: FetchFunc,
+    semaphore: asyncio.Semaphore,
+    *,
+    timeout: float = 300.0,
+) -> FetchFunc:
+    """
+    Wrap an async fetch function with semaphore-based rate limiting and timeout.
 
-    enriched_equities = await asyncio.gather(*(run(feed) for feed in feeds))
+    The timeout applies only to the actual fetch operation, not the semaphore
+    wait time. This ensures tasks waiting in the queue don't timeout before
+    they get their turn to execute.
 
-    # merge all feed‐enriched RawEquity instances into one
-    merged_from_feeds = merge(enriched_equities)
+    Args:
+        fn: Async function to wrap.
+        semaphore: Semaphore to control concurrent calls.
+        timeout: Maximum time in seconds for the fetch operation (default: 300s).
 
-    # replace only the none‐fields in source with values from merged_from_feeds
-    return _replace_none_with_enriched(source, merged_from_feeds)
+    Returns:
+        FetchFunc: Wrapped function that acquires semaphore before calling fn
+            with timeout protection.
+    """
 
+    async def wrapper(*args: object, **kwargs: object) -> object:
+        async with semaphore:
+            return await asyncio.wait_for(fn(*args, **kwargs), timeout=timeout)
 
-async def _enrich_with_feed(
-    source: RawEquity,
-    fetch_func: FetchFunc,
-    feed_model: type,
-) -> RawEquity:
-    """
-    Enrich a RawEquity using a feed: fetch, validate, and convert to USD.
+    return wrapper
 
-    If the source has no missing fields, returns it unchanged. Otherwise, fetches
-    data from the feed, validates it, and converts to USD. If any step fails,
-    returns the original source.
+
+def _feed_name(model: type) -> str:
+    """
+    Extract a concise feed name from a model class.
 
     Args:
-        source (RawEquity): The equity to enrich, possibly with missing fields.
-        fetch_func (FetchFunc): Async function to fetch enrichment data.
-        feed_model (type): Pydantic model class for validating feed data.
+        model: The Pydantic model class (e.g., YFinanceFeedData).
 
     Returns:
-        RawEquity: The enriched RawEquity in USD, or the original source if
-        enrichment fails or is unnecessary.
+        str: The feed name (e.g., "YFinance").
     """
-    # if source has no missing fields, skip enrichment
-    if not _has_missing_fields(source):
-        return source
+    return model.__name__.removesuffix("FeedData")
 
-    # derive a concise feed name for logging (e.g. "YFinance" from "YFinanceFeedData")
-    feed_name = feed_model.__name__.removesuffix("FeedData")
 
-    # fetch the raw data, with timeout and exception handling
-    fetched_raw_data = await _safe_fetch(source, fetch_func, feed_name)
+async def _process_stream(
+    equity_groups: AsyncIterable[list[RawEquity]],
+    feeds: tuple[EnrichmentFeed, ...],
+) -> AsyncIterable[RawEquity]:
+    """
+    Schedule enrichment for each equity group and yield merged results.
 
-    # if no data was fetched, fall back to source
-    if not fetched_raw_data:
-        return source
+    Creates an enrichment task for each group in the input stream, then
+    yields enriched equities as their tasks complete (potentially out of
+    original order).
 
-    # validate the fetched data against the feed model
-    validated = _make_validator(feed_model)(fetched_raw_data, source)
+    Args:
+        equity_groups: Stream of equity groups to enrich.
+        feeds: Active feeds to use for enrichment.
 
-    # always convert the validated feed‐record to USD or else fall back to source
-    return await _convert_to_usd_or_fallback(validated, source, feed_name)
+    Yields:
+        RawEquity: Merged equities from all sources (discovery + enrichment).
+    """
+    async with asyncio.TaskGroup() as tg:
+        tasks = [
+            tg.create_task(_enrich_equity_group(group, feeds))
+            async for group in equity_groups
+        ]
+        for coro in asyncio.as_completed(tasks):
+            yield await coro
 
 
-async def _safe_fetch(
-    source: RawEquity,
-    fetcher: FetchFunc,
-    feed_name: str,
-    *,
-    wait_timeout: float = 180.0,
-) -> dict[str, object] | None:
+async def _enrich_equity_group(
+    discovery_sources: list[RawEquity],
+    feeds: tuple[EnrichmentFeed, ...],
+) -> RawEquity:
     """
-    Safely fetch raw data for a RawEquity from an enrichment feed, handling
-    timeouts and errors.
+    Enrich an equity group and merge all sources.
 
-    Note:
-        The CIK (Central Index Key) is intentionally omitted as an identifier
-        for enrichment feeds, as it lacks broad support.
+    Extracts representative identifiers from discovery sources, queries
+    enrichment feeds with those identifiers, then performs a single merge
+    of all data points (discovery + enrichment).
 
     Args:
-        source (RawEquity): The RawEquity instance to fetch data for.
-        fetcher (FetchFunc): The async fetch function for the enrichment feed.
-        feed_name (str): The name of the enrichment feed for logging context.
-        wait_timeout (float, optional): Maximum time to wait for the fetch, in
-            seconds.
+        discovery_sources: Discovery feed equities for this group.
+        feeds: Active enrichment feeds.
 
     Returns:
-        dict[str, object] | None: The fetched data as a dictionary, or None if an
-        exception occurs or the data is empty.
+        RawEquity: Merged equity from all available sources.
     """
-    data: dict[str, object] | None = None
+    # Extract representative identifiers for enrichment queries
+    identifiers = extract_identifiers(discovery_sources)
 
-    try:
-        data = await asyncio.wait_for(
-            fetcher(
-                symbol=source.symbol,
-                name=source.name,
-                isin=source.isin,
-                cusip=source.cusip,
-            ),
-            timeout=wait_timeout,
-        )
+    # Fetch enrichment data using identifiers
+    enrichment_results = await asyncio.gather(
+        *(_enrich_from_feed(identifiers, feed) for feed in feeds),
+    )
 
-    except LookupError as error:
-        _log_no_feed_data(
-            feed_name,
-            source,
-            error,
-        )
+    # Filter out None results (failed enrichment attempts)
+    enrichment_sources = [r for r in enrichment_results if r is not None]
 
-    except TimeoutError:
-        logger.error(
-            "Timed out after %.0f s while fetching from %s.",
-            wait_timeout,
-            feed_name,
-        )
+    # Single merge of all sources: discovery + enrichment
+    all_sources = discovery_sources + enrichment_sources
+    return merge(all_sources)
 
-    except Exception as error:
-        logger.error(
-            "Error fetching from %s: %s",
-            feed_name,
-            error,
-        )
-
-    return data
 
-
-def _make_validator(
-    feed_model: type,
-) -> ValidatorFunc:
+async def _enrich_from_feed(
+    identifiers: EquityIdentifiers,
+    feed: EnrichmentFeed,
+) -> RawEquity | None:
     """
-    Create a validator function for a given feed model to validate and coerce records.
+    Fetch, validate, and convert enrichment data from a single feed.
+
+    Uses representative identifiers to query the feed, validates the response,
+    converts to USD (if monetary data present), and returns the enriched equity.
+    Returns None on any failure.
 
     Args:
-        feed_model (type): The Pydantic model class used to validate and coerce
-            input records. The model should define the expected schema for the feed
-            data.
+        identifiers: Representative identifiers for querying the feed.
+        feed: Active feed to use.
 
     Returns:
-        ValidatorFunc: A function that takes a record dictionary and a RawEquity
-            source, validates and coerces the record using the feed model, and
-            returns a RawEquity instance if successful. If validation fails, log
-            and returns the original source.
+        RawEquity | None: Enriched equity in USD, or None if enrichment fails.
     """
-    feed_name = feed_model.__name__.removesuffix("FeedData")
+    feed_name = _feed_name(feed.model)
 
-    def validate(record: dict[str, object], source: RawEquity) -> RawEquity:
-        """
-        Validate and coerce a record using the feed model, returning a RawEquity.
+    fetched = await _safe_fetch(identifiers, feed.fetch, feed_name)
 
-        Args:
-            record (dict[str, object]): The raw record to validate and coerce.
-            source (RawEquity): The original RawEquity to return on failure.
-
-        Returns:
-            RawEquity: The validated RawEquity, or the original source if
-                validation fails.
-        """
-        try:
-            # validate the record against the feed model, coercing types as needed
-            coerced = feed_model.model_validate(record).model_dump()
-
-            # convert the coerced data to a RawEquity instance
-            return RawEquity.model_validate(coerced)
+    validated = (
+        _validate(fetched, feed.model, feed_name, identifiers) if fetched else None
+    )
 
-        except Exception as error:
-            if hasattr(error, "errors"):
-                fields = {err["loc"][0] for err in error.errors()}
-                summary = f"invalid {', '.join(sorted(fields))}"
-            else:
-                summary = str(error)
+    if validated is None:
+        return None
 
-                _log_no_feed_data(
-                    feed_name,
-                    source,
-                    summary,
-                )
-            return source
+    # Non-monetary feeds (e.g. GLEIF) have no currency - skip conversion
+    if validated.currency is None:
+        _log_success(feed_name, identifiers, validated)
+        return validated
 
-    return validate
+    return await _to_usd(validated, feed_name, identifiers)
 
 
-def _has_missing_fields(equity: RawEquity) -> bool:
+async def _safe_fetch(
+    identifiers: EquityIdentifiers,
+    fetch: FetchFunc,
+    feed_name: str,
+) -> dict[str, object] | None:
     """
-    Checks if any field in a RawEquity instance is missing (i.e., set to None).
+    Safely fetch raw data using identifiers from an enrichment feed.
+
+    Handles errors, returning None on failure. Logs all errors with
+    appropriate context. Timeout is handled by the _rate_limited wrapper.
 
     Args:
-        equity (RawEquity): The RawEquity instance to check for missing fields.
+        identifiers: Representative identifiers for the equity.
+        fetch: Async fetch function for the enrichment feed (already
+            wrapped with timeout protection via _rate_limited).
+        feed_name: Feed name for logging context.
 
     Returns:
-        bool: True if any field is None, indicating a missing value; False otherwise.
+        dict[str, object] | None: Fetched data as dictionary, or None on failure.
     """
-    return any(value is None for value in equity.model_dump().values())
+    try:
+        return await fetch(
+            symbol=identifiers.symbol,
+            name=identifiers.name,
+            isin=identifiers.isin,
+            cusip=identifiers.cusip,
+            cik=identifiers.cik,
+            lei=identifiers.lei,
+            share_class_figi=identifiers.share_class_figi,
+        )
 
+    except LookupError as e:
+        _log_failure(feed_name, identifiers, e)
 
-def _replace_none_with_enriched(
-    source: RawEquity,
-    enriched: RawEquity,
-) -> RawEquity:
+    except TimeoutError:
+        logger.error(
+            "Timed out fetching from %s for symbol=%s (isin=%s, cusip=%s, lei=%s). "
+            "Request exceeded timeout waiting for response.",
+            feed_name,
+            identifiers.symbol,
+            identifiers.isin or "<none>",
+            identifiers.cusip or "<none>",
+            identifiers.lei or "<none>",
+        )
+
+    except Exception as e:
+        logger.error(
+            "Error fetching from %s for symbol=%s: %s: %s",
+            feed_name,
+            identifiers.symbol,
+            type(e).__name__,
+            e or "<empty>",
+        )
+
+    return None
+
+
+def _validate(
+    record: dict[str, object],
+    model: type,
+    feed_name: str,
+    identifiers: EquityIdentifiers,
+) -> RawEquity | None:
     """
-    Return new RawEquity instance with missing fields from `source` filled in from
-    `enriched`.
+    Validate record against model schema and convert to RawEquity.
 
-    For each field, if `source` has a non-None value, it is kept. If `source` has None,
-    the value from `enriched` is used, but only if it is not None. None values in
-    `enriched` never overwrite any value in `source`.
+    Validates the fetched record using the feed's Pydantic model, then
+    converts the validated data to a RawEquity instance. Only injects
+    share_class_figi from discovery sources if the enrichment feed didn't
+    provide one. Returns None on validation failure.
 
     Args:
-        source (RawEquity): The original RawEquity instance, possibly with missing
-            fields.
-        enriched (RawEquity): The RawEquity instance to use for filling missing fields.
+        record: Raw record to validate.
+        model: Pydantic model class for validating feed data.
+        feed_name: Feed name for logging context.
+        identifiers: Representative ids for logging context and share_class_figi.
 
     Returns:
-        RawEquity: A new RawEquity instance with missing fields filled from `enriched`.
+        RawEquity | None: Validated equity, with share_class_figi from discovery
+            sources if enrichment feed didn't provide one, or None on failure.
     """
-    # dump enriched, don’t include any None values
-    enriched_data = enriched.model_dump(exclude_none=True)
+    try:
+        coerced = model.model_validate(record).model_dump()
 
-    # pick only the keys where source is None
-    to_update = {
-        field: value
-        for field, value in enriched_data.items()
-        if getattr(source, field) is None
-    }
+        # Only inject share_class_figi if enrichment feed didn't provide one
+        if "share_class_figi" not in coerced or coerced["share_class_figi"] is None:
+            coerced["share_class_figi"] = identifiers.share_class_figi
 
-    # return a copy of source with just those missing fields filled in
-    return source.model_copy(update=to_update)
+        return RawEquity.model_validate(coerced)
+
+    except Exception as e:
+        summary = (
+            f"invalid {', '.join(sorted(err['loc'][0] for err in e.errors()))}"
+            if hasattr(e, "errors")
+            else str(e)
+        )
+        _log_failure(feed_name, identifiers, summary)
+        return None
 
 
-async def _convert_to_usd_or_fallback(
+async def _to_usd(
     validated: RawEquity,
-    source: RawEquity,
     feed_name: str,
-) -> RawEquity:
+    identifiers: EquityIdentifiers,
+) -> RawEquity | None:
     """
-    Attempt to convert a validated RawEquity instance to USD. If conversion fails
-    due to a missing FX rate (ValueError), log and return the original
-    source RawEquity.
+    Convert a validated RawEquity instance to USD.
+
+    Applies currency conversion using the global USD converter. Returns
+    None on conversion failure. Only called for feeds that provide
+    monetary data (currency is not None).
 
     Args:
-        validated (RawEquity): The RawEquity instance to convert to USD.
-        source (RawEquity): The original RawEquity to return on conversion failure.
-        feed_name (str): The name of the enrichment feed for logging context.
+        validated: RawEquity instance to convert to USD.
+        feed_name: Feed name for logging context.
+        identifiers: Representative identifiers for logging context.
 
     Returns:
-        RawEquity: The USD-converted RawEquity if successful, otherwise the original
-        source RawEquity.
+        RawEquity | None: USD-converted equity or None on failure.
     """
     converter = await get_usd_converter()
 
     try:
         converted = converter(validated)
 
-        if converted is None:
-            raise ValueError("USD conversion failed")
+        if converted is None or converted.currency != "USD":
+            raise ValueError(
+                f"USD conversion failed: {converted.currency if converted else None}",
+            )
+
+        _log_success(feed_name, identifiers, converted)
         return converted
 
-    except Exception as error:
-        _log_no_feed_data(
-            feed_name,
-            source,
-            error,
-        )
-        return source
+    except Exception as e:
+        _log_failure(feed_name, identifiers, e)
+        return None
 
 
-def _log_no_feed_data(
+def _log_success(
     feed_name: str,
-    source: RawEquity,
-    error: object,
-    *,
-    level: int = logging.DEBUG,
+    identifiers: EquityIdentifiers,
+    result: RawEquity,
 ) -> None:
     """
-    Log a standardised message for missing or failed enrichment feed data.
-
-    This logs details about the equity and the error context when no data is
-    available from a feed, or when enrichment fails.
+    Log successful enrichment with representative identifiers.
 
     Args:
-        feed_name (str): Name of the enrichment feed.
-        source (RawEquity): Equity instance with identifying fields.
-        error (object): Error or context for the missing data.
-        level (int, optional): Logging level (default: logging.DEBUG).
+        feed_name: Name of the enrichment feed.
+        identifiers: Representative identifiers from discovery sources.
+        result: The enriched RawEquity returned by the feed.
+    """
+    prefix = f"[{feed_name}:{identifiers.symbol}]"
+
+    msg = (
+        f"{prefix:<24} SUCCESS: {feed_name} feed for symbol={identifiers.symbol}, "
+        f"name={identifiers.name} "
+        f"(share_class_figi={identifiers.share_class_figi or '<none>'}, "
+        f"isin={identifiers.isin or result.isin or '<none>'}, "
+        f"cusip={identifiers.cusip or result.cusip or '<none>'}, "
+        f"cik={identifiers.cik or result.cik or '<none>'}, "
+        f"lei={identifiers.lei or result.lei or '<none>'})"
+    )
 
-    Returns:
-        None
+    logger.debug(msg)
+
+
+def _log_failure(
+    feed_name: str,
+    identifiers: EquityIdentifiers,
+    error: object,
+) -> None:
+    """
+    Log failed enrichment with the input identifiers that were attempted.
+
+    Args:
+        feed_name: Name of the enrichment feed.
+        identifiers: Representative identifiers that were used for the lookup.
+        error: Error or context describing why the lookup failed.
     """
-    logger.log(
-        level,
-        "No %s feed data for symbol=%s, name=%s "
-        "(isin=%s, cusip=%s, cik=%s, share_class_figi=%s). %s",
-        feed_name,
-        source.symbol,
-        source.name,
-        source.isin or "<none>",
-        source.cusip or "<none>",
-        source.cik or "<none>",
-        source.share_class_figi or "<none>",
-        error,
+    prefix = f"[{feed_name}:{identifiers.symbol}]"
+
+    msg = (
+        f"{prefix:<24} FAILURE: {feed_name} feed for symbol={identifiers.symbol}, "
+        f"name={identifiers.name} "
+        f"(share_class_figi={identifiers.share_class_figi or '<none>'}, "
+        f"isin={identifiers.isin or '<none>'}, "
+        f"cusip={identifiers.cusip or '<none>'}, "
+        f"cik={identifiers.cik or '<none>'}, "
+        f"lei={identifiers.lei or '<none>'}). "
+        f"{error}"
     )
+
+    logger.debug(msg)