flip_api.private_services.receive_cohort_results
================================================

.. py:module:: flip_api.private_services.receive_cohort_results


Attributes
----------

.. autoapisummary::

   flip_api.private_services.receive_cohort_results.router
   flip_api.private_services.receive_cohort_results._ALLOWED_TRUST_ERROR_CATEGORIES


Functions
---------

.. autoapisummary::

   flip_api.private_services.receive_cohort_results._redact_trust_error
   flip_api.private_services.receive_cohort_results._save_individual_result
   flip_api.private_services.receive_cohort_results._aggregate_and_save_results
   flip_api.private_services.receive_cohort_results.receive_cohort_results_endpoint


Module Contents
---------------

.. py:data:: router

.. py:data:: _ALLOWED_TRUST_ERROR_CATEGORIES
   :type:  frozenset[str]

.. py:function:: _redact_trust_error(raw: str | None) -> str

   Collapse a trust-side error string to a safe enum category.

   :param raw: The error string the trust reported on the failed
               cohort task, if any.
   :type raw: str | None

   :returns: One of ``_ALLOWED_TRUST_ERROR_CATEGORIES``. ``internal_error``
             is the default for anything unrecognised — including ``None``, raw
             psycopg traceback fragments, and wrapped ``"500: ..."`` strings the
             trust-api gateway constructs from upstream HTTPException bodies.
   :rtype: str


.. py:function:: _save_individual_result(db: sqlmodel.Session, cohort_results: flip_api.domain.schemas.private.OmopCohortResults) -> None

   Saves the individual cohort results from a single trust for a specific query.

   :param db: Database session.
   :type db: Session
   :param cohort_results: The cohort results to save.
   :type cohort_results: OmopCohortResults

   :returns: None

   :raises HTTPException: If there is an error while saving the cohort results to the database.


.. py:function:: _aggregate_and_save_results(db: sqlmodel.Session, query_id: uuid.UUID) -> None

   Aggregates cohort results for a specific query_id across all trusts and saves the aggregated statistics.

   :param db: Database session.
   :type db: Session
   :param query_id: The ID of the query to aggregate results for.
   :type query_id: UUID

   :returns: None

   :raises HTTPException: If there is an error during aggregation or saving the aggregated stats to the database.


.. py:function:: receive_cohort_results_endpoint(cohort_results: flip_api.domain.schemas.private.OmopCohortResults, db: sqlmodel.Session = Depends(get_session), authenticated_trust: flip_api.db.models.main_models.Trust = Depends(authenticate_trust)) -> dict[str, str]

   Receives cohort query results from a single trust, saves them,
   then re-aggregates and saves the overall statistics for the query.

   :param cohort_results: The cohort results sent by the trust.
   :type cohort_results: OmopCohortResults
   :param db: Database session.
   :type db: Session
   :param authenticated_trust: Trust resolved from the API key by the dependency.
   :type authenticated_trust: Trust

   :returns: A message indicating successful processing of cohort results.
   :rtype: dict[str, str]

   :raises HTTPException: If there is an error during processing, saving individual results, or aggregating results.