corvix.enrichment
=================

.. py:module:: corvix.enrichment

.. autoapi-nested-parse::

   Notification enrichment package.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/corvix/enrichment/base/index
   /autoapi/corvix/enrichment/engine/index
   /autoapi/corvix/enrichment/providers/index


Classes
-------

.. autoapisummary::

   corvix.enrichment.EnrichmentContext
   corvix.enrichment.EnrichmentProvider
   corvix.enrichment.JsonFetchClient
   corvix.enrichment.EnrichmentEngine
   corvix.enrichment.EnrichmentRunResult
   corvix.enrichment.GitHubLatestCommentProvider
   corvix.enrichment.GitHubPRStateProvider


Package Contents
----------------

.. py:class:: EnrichmentContext

   Per-cycle provider context with request budget and URL cache.


   .. py:attribute:: max_requests_per_cycle
      :type:  int


   .. py:attribute:: url_cache
      :type:  dict[str, corvix.types.JsonValue]


   .. py:attribute:: request_count
      :type:  int
      :value: 0



   .. py:method:: get_json(client: JsonFetchClient, url: str, timeout_seconds: float) -> corvix.types.JsonValue

      Fetch and cache a JSON payload for this cycle.



.. py:class:: EnrichmentProvider

   Bases: :py:obj:`Protocol`


   Protocol implemented by enrichment providers.


   .. py:attribute:: name
      :type:  str


   .. py:method:: enrich(notification: corvix.domain.Notification, client: JsonFetchClient, ctx: EnrichmentContext) -> dict[str, object]


.. py:class:: JsonFetchClient

   Bases: :py:obj:`Protocol`


   Client capability required by enrichment providers.


   .. py:method:: fetch_json_url(url: str, timeout_seconds: float = 30.0) -> corvix.types.JsonValue

      Fetch JSON from a fully-qualified API URL.



.. py:class:: EnrichmentEngine

   Runs configured enrichment providers over notifications.


   .. py:attribute:: config
      :type:  corvix.config.EnrichmentConfig


   .. py:attribute:: providers
      :type:  list[corvix.enrichment.base.EnrichmentProvider]


   .. py:method:: run(notifications: list[corvix.domain.Notification], client: corvix.enrichment.base.JsonFetchClient, clients_by_account: dict[str, corvix.enrichment.base.JsonFetchClient] | None = None) -> EnrichmentRunResult

      Run enabled providers for all notifications in one cycle.



.. py:class:: EnrichmentRunResult

   Result of enriching one poll cycle.


   .. py:attribute:: contexts_by_notification_key
      :type:  dict[str, dict[str, object]]


   .. py:attribute:: errors
      :type:  list[str]
      :value: []



   .. py:property:: contexts_by_thread_id
      :type: dict[str, dict[str, object]]


      Backward-compatible thread-keyed view of contexts.



.. py:class:: GitHubLatestCommentProvider

   Enriches comment notifications with the latest comment metadata.


   .. py:attribute:: timeout_seconds
      :type:  float
      :value: 10.0



   .. py:attribute:: name
      :type:  str
      :value: 'github.latest_comment'



   .. py:method:: enrich(notification: corvix.domain.Notification, client: corvix.enrichment.base.JsonFetchClient, ctx: corvix.enrichment.base.EnrichmentContext) -> dict[str, object]

      Return latest comment metadata under the provider namespace.



.. py:class:: GitHubPRStateProvider

   Enriches pull-request notifications with state metadata.


   .. py:attribute:: timeout_seconds
      :type:  float
      :value: 10.0



   .. py:attribute:: name
      :type:  str
      :value: 'github.pr_state'



   .. py:method:: enrich(notification: corvix.domain.Notification, client: corvix.enrichment.base.JsonFetchClient, ctx: corvix.enrichment.base.EnrichmentContext) -> dict[str, object]

      Return pull-request state metadata under the provider namespace.