fix: fixed linting and commenting issues.

Signed-off-by: Teryl Taylor <terylt@ibm.com>

Author: terylt

cpex/framework/cmf/message.py

@@ -19,7 +19,7 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Annotated, Iterator, Literal, TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Annotated, Any, Iterator, Literal, Union
 
 # Third-Party
 from pydantic import BaseModel, ConfigDict, Discriminator, Field, Tag, model_validator
@@ -263,6 +263,14 @@ class Resource(BaseModel):
 
     @model_validator(mode="after")
     def _check_content_blob_exclusion(self) -> Resource:
+        """Ensure content and blob are mutually exclusive.
+
+        Returns:
+            The validated Resource instance.
+
+        Raises:
+            ValueError: If both content and blob are set.
+        """
         if self.content is not None and self.blob is not None:
             raise ValueError("Resource cannot have both 'content' and 'blob' set")
         return self
@@ -309,6 +317,14 @@ class ResourceReference(BaseModel):
 
     @model_validator(mode="after")
     def _check_range_consistency(self) -> ResourceReference:
+        """Ensure range_end is not less than range_start.
+
+        Returns:
+            The validated ResourceReference instance.
+
+        Raises:
+            ValueError: If range_end < range_start.
+        """
         if self.range_start is not None and self.range_end is not None:
             if self.range_end < self.range_start:
                 raise ValueError(f"range_end ({self.range_end}) must be >= range_start ({self.range_start})")

cpex/framework/extensions/__init__.py

@@ -13,6 +13,7 @@
 # First-Party
 from cpex.framework.extensions.agent import AgentExtension, ConversationContext
 from cpex.framework.extensions.completion import CompletionExtension, StopReason, TokenUsage
+from cpex.framework.extensions.constants import SlotName
 from cpex.framework.extensions.extensions import Extensions
 from cpex.framework.extensions.framework import FrameworkExtension
 from cpex.framework.extensions.http import HttpExtension
@@ -33,7 +34,6 @@
     SubjectExtension,
     SubjectType,
 )
-from cpex.framework.extensions.constants import SlotName
 from cpex.framework.extensions.tiers import (
     AccessPolicy,
     Capability,

cpex/framework/extensions/constants.py

@@ -30,6 +30,14 @@ class SlotName(str, Enum):
     """
 
     def __str__(self) -> str:
+        """Return the enum value as a plain string.
+
+        Overrides the default ``StrEnum.__str__`` which renders as
+        ``ClassName.MEMBER`` in Python 3.11+.
+
+        Returns:
+            The raw string value of the enum member.
+        """
         return self.value
 
     REQUEST = "request"

cpex/framework/extensions/tiers.py

@@ -388,11 +388,19 @@ def __init__(
         tier: MutabilityTier,
         detail: str,
     ) -> None:
+        """Initialise a tier violation error.
+
+        Args:
+            plugin_name: Name of the offending plugin.
+            slot: The extension slot that was violated.
+            tier: The mutability tier of the slot.
+            detail: Description of the violation.
+        """
         self.plugin_name = plugin_name
         self.slot = slot
         self.tier = tier
         self.detail = detail
-        super().__init__(f"Plugin '{plugin_name}' violated {tier.value} tier on " f"'{slot}': {detail}")
+        super().__init__(f"Plugin '{plugin_name}' violated {tier.value} tier on '{slot}': {detail}")
 
 
 def _resolve_slot(ext: Extensions | None, dot_path: str) -> Any:

cpex/framework/manager.py

@@ -40,6 +40,8 @@
 from cpex.framework.base import HookRef, Plugin
 from cpex.framework.constants import EXTERNAL_PLUGIN_TYPE
 from cpex.framework.errors import PluginError, PluginViolationError, convert_exception_to_error
+from cpex.framework.extensions.extensions import Extensions
+from cpex.framework.extensions.tiers import filter_extensions
 from cpex.framework.hooks.policies import DefaultHookPolicy, HookPayloadPolicy, apply_policy
 from cpex.framework.loader.config import ConfigLoader
 from cpex.framework.loader.plugin import PluginLoader
@@ -55,8 +57,6 @@
     PluginPayload,
     PluginResult,
 )
-from cpex.framework.extensions.extensions import Extensions
-from cpex.framework.extensions.tiers import filter_extensions
 from cpex.framework.observability import ObservabilityProvider, current_trace_id
 from cpex.framework.registry import PluginInstanceRegistry
 from cpex.framework.settings import settings
@@ -650,7 +650,11 @@ def _build_halt_result(
     ) -> tuple[PluginResult, dict]:
         """Schedule fire-and-forget tasks and build a pipeline-halting result."""
         self._fire_and_forget_tasks(
-            fire_and_forget_refs, payload, global_context, res_local_contexts, fire_and_forget_semaphore,
+            fire_and_forget_refs,
+            payload,
+            global_context,
+            res_local_contexts,
+            fire_and_forget_semaphore,
             extensions=extensions,
         )
         if hook_type == HTTP_AUTH_CHECK_PERMISSION_HOOK and decision_plugin_name:

cpex/framework/models.py

@@ -1241,6 +1241,17 @@ def _migrate_legacy_modes(cls, data: Any) -> Any:
     @field_validator("capabilities", mode="before")
     @classmethod
     def _validate_capabilities(cls, v: Any) -> frozenset[str]:
+        """Validate that all declared capabilities are known.
+
+        Args:
+            v: Raw capabilities value from the config.
+
+        Returns:
+            A validated frozenset of capability strings.
+
+        Raises:
+            ValueError: If an unknown capability is declared.
+        """
         # First-Party
         from cpex.framework.extensions.tiers import Capability  # pylint: disable=import-outside-toplevel