mud_server.services.condition_axis_service ========================================== .. py:module:: mud_server.services.condition_axis_service .. autoapi-nested-parse:: Canonical condition-axis generation service. This module centralizes all condition-axis generation behavior so API routes and internal callsites can rely on one stable adapter contract. Primary responsibilities: - Validate seed and runtime input contracts. - Resolve policy bundle metadata and reproducibility hashes. - Call the configured upstream entity generator adapter. - Normalize returned axis payloads into canonical ``axis -> score`` shape. - Map all known failures into structured, stable service errors. Attributes ---------- .. autoapisummary:: mud_server.services.condition_axis_service.SEED_MIN mud_server.services.condition_axis_service.SEED_MAX mud_server.services.condition_axis_service.logger Exceptions ---------- .. autoapisummary:: mud_server.services.condition_axis_service.ConditionAxisServiceError Classes ------- .. autoapisummary:: mud_server.services.condition_axis_service.ConditionAxisPolicyContext mud_server.services.condition_axis_service.ConditionAxisProvenance mud_server.services.condition_axis_service.ConditionAxisGenerationResult Functions --------- .. autoapisummary:: mud_server.services.condition_axis_service.generate_condition_axis mud_server.services.condition_axis_service.get_condition_axis_upstream_metrics Module Contents --------------- .. py:data:: SEED_MIN :value: 1 .. py:data:: SEED_MAX :value: 2147483647 .. py:data:: logger .. py:exception:: ConditionAxisServiceError(*, status_code, code, detail, stage = _SERVICE_STAGE) Bases: :py:obj:`RuntimeError` Typed service error carrying stable HTTP and contract metadata. .. attribute:: status_code HTTP status to be surfaced by API route handlers. .. attribute:: code Stable machine-readable error code for UI/client mapping. .. attribute:: detail Human-readable summary of the failure. .. attribute:: stage Stable processing stage key for pipeline diagnostics. Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: status_code .. py:attribute:: code .. py:attribute:: detail .. py:attribute:: stage :value: 'axis_input' .. py:method:: to_response_payload() Return canonical error payload for API responses. .. py:class:: ConditionAxisPolicyContext Resolved policy metadata for one generation request. .. attribute:: bundle_id Effective bundle id used for the generation request. .. attribute:: bundle_version Effective bundle version string. .. attribute:: policy_hash Deterministic hash of resolved policy inputs. .. attribute:: required_runtime_inputs Runtime keys required for strict validation. .. attribute:: required_axes Canonical axis key set required by active policy bundle. .. attribute:: axis_label_scores Deterministic ``axis -> label -> score`` lookup derived from policy thresholds/orderings for label-only upstream normalization. .. py:attribute:: bundle_id :type: str .. py:attribute:: bundle_version :type: str .. py:attribute:: policy_hash :type: str | None .. py:attribute:: required_runtime_inputs :type: set[str] .. py:attribute:: required_axes :type: set[str] .. py:attribute:: axis_label_scores :type: dict[str, dict[str, float]] .. py:class:: ConditionAxisProvenance Canonical provenance metadata returned to clients. .. attribute:: source Canonical owner identifier for the response contract. .. attribute:: served_via API route path that served the response. .. attribute:: generator Upstream generator system identifier. .. attribute:: generator_version Upstream generator version/capability value. .. attribute:: generator_capabilities Ordered upstream capability tokens. .. attribute:: generated_at ISO-8601 timestamp for generation completion. .. py:attribute:: source :type: str .. py:attribute:: served_via :type: str .. py:attribute:: generator :type: str .. py:attribute:: generator_version :type: str .. py:attribute:: generator_capabilities :type: tuple[str, Ellipsis] .. py:attribute:: generated_at :type: str .. py:class:: ConditionAxisGenerationResult Service result payload for canonical condition-axis generation. .. attribute:: world_id Target world id used for policy resolution. .. attribute:: bundle_id Effective bundle id used for generation. .. attribute:: bundle_version Effective bundle version string. .. attribute:: policy_hash Deterministic policy hash for reproducibility. .. attribute:: seed Deterministic generation seed. .. attribute:: axes Canonical axis map of ``axis_name -> score``. .. attribute:: provenance Canonical provenance block for diagnostics/auditability. .. attribute:: entity_state Raw upstream entity payload for internal reuse/callers. .. py:attribute:: world_id :type: str .. py:attribute:: bundle_id :type: str .. py:attribute:: bundle_version :type: str .. py:attribute:: policy_hash :type: str | None .. py:attribute:: seed :type: int .. py:attribute:: axes :type: dict[str, float] .. py:attribute:: provenance :type: ConditionAxisProvenance .. py:attribute:: entity_state :type: dict[str, Any] .. py:function:: generate_condition_axis(*, world_id, world_root, seed = None, bundle_id = None, inputs = None, strict_inputs = False) Generate canonical condition-axis values for one world. :param world_id: Canonical world identifier. :param world_root: Resolved world package root. :param seed: Optional deterministic generation seed. :param bundle_id: Optional bundle override requested by caller. :param inputs: Optional runtime input payload. :param strict_inputs: Enforce strict runtime input validation when ``True``. :returns: Canonical service result with normalized axes and provenance. :raises ConditionAxisServiceError: If input validation, policy resolution, or upstream generation fails. .. py:function:: get_condition_axis_upstream_metrics() Return an in-memory snapshot of upstream adapter metrics counters. :returns: Mapping of metric name to cumulative count since process start.