amd-node-scraper 0.0.1__py3-none-any.whl

nodescraper/models/event.py

@@ -0,0 +1,158 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+import datetime
+import logging
+import re
+import uuid
+from enum import Enum
+from typing import Optional, Union
+
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+from nodescraper.enums import EventPriority
+
+LOG_LEVEL_MAP = {
+    logging.INFO: EventPriority.INFO,
+    logging.WARNING: EventPriority.WARNING,
+    logging.ERROR: EventPriority.ERROR,
+    logging.CRITICAL: EventPriority.CRITICAL,
+    logging.FATAL: EventPriority.CRITICAL,
+}
+
+
+class Event(BaseModel):
+    """Base event class"""
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    timestamp: datetime.datetime = Field(
+        default_factory=lambda: datetime.datetime.now(datetime.timezone.utc)
+    )
+    reporter: str = "NODE_SCRAPER"
+    category: str
+    description: str
+    data: dict = Field(default_factory=dict)
+    priority: EventPriority
+    system_id: Optional[str] = None
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp(cls, timestamp: datetime.datetime) -> datetime.datetime:
+        """validate timestamp, will convert to utc timezone as long as input is timezone aware
+        Args:
+            timestamp (datetime): datetime object
+        Raises:
+            ValueError: if value is not a datetime object
+            ValueError: if value is not timezone aware
+        Returns:
+            datetime: validated datetime
+        """
+
+        if timestamp.tzinfo is None or timestamp.tzinfo.utcoffset(timestamp) is None:
+            raise ValueError("datetime must be timezone aware")
+
+        utc_offset = timestamp.utcoffset()
+        if utc_offset is not None and utc_offset.total_seconds() != 0:
+            timestamp = timestamp.astimezone(datetime.timezone.utc)
+
+        return timestamp
+
+    @field_validator("category", mode="before")
+    @classmethod
+    def validate_category(cls, category: Optional[Union[str, Enum]]) -> str:
+        """ensure category is has consistent formatting
+        Args:
+            category (str | Enum): category string
+        Returns:
+            str: formatted category string
+        """
+        if isinstance(category, Enum):
+            category = category.value
+
+        category = str(category).strip().upper()
+        category = re.sub(r"[\s-]", "_", category)
+        return category
+
+    @field_validator("priority", mode="before")
+    @classmethod
+    def validate_priority(cls, priority: Union[str, EventPriority]) -> EventPriority:
+        """Allow priority to be set via string priority name
+        Args:
+            priority (Union[str, EventPriority]): event priority string or enum
+        Raises:
+            ValueError: if priority string is an invalid value
+        Returns:
+            EventPriority: priority enum
+        """
+        if isinstance(priority, str):
+            try:
+                return getattr(EventPriority, priority.upper())
+            except AttributeError as e:
+                raise ValueError(
+                    f"priority must be one of {[p.name for p in EventPriority]}"
+                ) from e
+        if isinstance(priority, EventPriority):
+            return priority
+        raise ValueError("priority must be an EventPriority or its name as a string")
+
+    @field_serializer("priority")
+    def serialize_priority(self, priority: EventPriority, _info) -> str:
+        """Use priority name when serializing events
+        Args:
+            priority (EventPriority): priority enum
+        Returns:
+            str: priority name string
+        """
+        return priority.name
+
+    @field_validator("data")
+    @classmethod
+    def validate_data(cls, data: dict) -> dict:
+        """Ensure data is below 100KB
+        Args:
+            data (dict): data input
+        Raises:
+            ValueError: When data is above 100KB in size
+        Returns:
+            dict: data output
+        """
+        if len(str(data).encode("utf-8")) >= (1024 * 100):
+            raise ValueError("Data must be below 100KB in size")
+        return data
+
+    @field_validator("description")
+    @classmethod
+    def validate_description(cls, desc: str) -> str:
+        """Ensure description is below 2KB
+        Args:
+            desc (str): description input
+        Raises:
+            ValueError: When desc is above 2KB in size
+        Returns:
+            str: desc output
+        """
+        if len(desc.encode("utf-8")) >= 1024 * 2:
+            raise ValueError("Description must be below 2KB in size")
+        return desc

nodescraper/models/pluginconfig.py

@@ -0,0 +1,38 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PluginConfig(BaseModel):
+    """Model for preset configuration of plugins and result collators"""
+
+    global_args: dict = Field(default_factory=dict)
+    plugins: dict[str, dict] = Field(default_factory=dict)
+    result_collators: dict[str, dict] = Field(default_factory=dict)
+    name: Optional[str] = None
+    desc: Optional[str] = None

nodescraper/models/pluginresult.py

@@ -0,0 +1,39 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+from typing import Optional, Union
+
+from pydantic import BaseModel
+
+from nodescraper.enums import ExecutionStatus
+
+
+class PluginResult(BaseModel):
+    """Object for result of a plugin"""
+
+    status: ExecutionStatus
+    source: str
+    message: Optional[str] = None
+    result_data: Optional[Union[dict, BaseModel]] = None

nodescraper/models/systeminfo.py

@@ -0,0 +1,44 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+
+import platform
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from nodescraper.enums import OSFamily, SystemLocation
+
+
+class SystemInfo(BaseModel):
+    """System object used to store data about System"""
+
+    name: str = platform.node()
+    os_family: OSFamily = OSFamily.UNKNOWN
+    sku: Optional[str] = None
+    platform: Optional[str] = None
+    metadata: Optional[dict] = Field(default_factory=dict)
+    location: Optional[SystemLocation] = SystemLocation.LOCAL
+    vendorid_ep: int = 0x1002

nodescraper/models/taskresult.py

@@ -0,0 +1,185 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+import datetime
+import logging
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_serializer, field_validator
+
+from nodescraper.enums import EventPriority, ExecutionStatus
+
+from .event import Event
+
+STATUS_LOG_LEVEL_MAP = {
+    ExecutionStatus.UNSET: logging.INFO,
+    ExecutionStatus.NOT_RAN: logging.INFO,
+    ExecutionStatus.OK: logging.INFO,
+    ExecutionStatus.WARNING: logging.WARNING,
+    ExecutionStatus.ERROR: logging.ERROR,
+    ExecutionStatus.EXECUTION_FAILURE: logging.CRITICAL,
+}
+
+
+class TaskResult(BaseModel):
+    """Object for result of a task"""
+
+    status: ExecutionStatus = ExecutionStatus.UNSET
+    message: str = ""
+    task: Optional[str] = None
+    parent: Optional[str] = None
+    artifacts: list[BaseModel] = Field(default_factory=list)
+    events: list[Event] = Field(default_factory=list)
+    start_time: datetime.datetime = Field(default_factory=datetime.datetime.now)
+    end_time: datetime.datetime = Field(default_factory=datetime.datetime.now)
+
+    @field_serializer("status")
+    def serialize_status(self, status: ExecutionStatus, _info) -> str:
+        """Use status name when serializing result
+        Args:
+            status (ExecutionStatus): status enum
+        Returns:
+            str: status name string
+        """
+        return status.name
+
+    @field_validator("status", mode="before")
+    @classmethod
+    def validate_status(cls, v: Any):
+        """Validator to ensure `status` is a valid ExecutionStatus enum.
+
+        Args:
+            v (Any): The input value to validate (can be str or ExecutionStatus).
+
+        Returns:
+            ExecutionStatus: The validated enum value.
+
+        Raises:
+            ValueError: If the string is not a valid enum name.
+        """
+        if isinstance(v, ExecutionStatus):
+            return v
+        if isinstance(v, str):
+            try:
+                return ExecutionStatus[v]
+            except KeyError as err:
+                raise ValueError(f"Unknown status name: {v!r}") from err
+        return v
+
+    @property
+    def duration(self) -> Optional[str]:
+        """return duration of time as a string
+
+        Returns:
+            str: duration string
+        """
+        if self.start_time and self.end_time:
+            duration = str((self.end_time - self.start_time))
+        else:
+            duration = None
+
+        return duration
+
+    def _get_event_summary(self) -> str:
+        """Get summary string for events
+
+        Returns:
+            str: event summary with counts and descriptions
+        """
+        error_msg_counts: dict[str, int] = {}
+        warning_msg_counts: dict[str, int] = {}
+
+        for event in self.events:
+            if event.priority == EventPriority.WARNING:
+                warning_msg_counts[event.description] = (
+                    warning_msg_counts.get(event.description, 0) + 1
+                )
+            elif event.priority >= EventPriority.ERROR:
+                error_msg_counts[event.description] = error_msg_counts.get(event.description, 0) + 1
+
+        summary_parts = []
+
+        if warning_msg_counts:
+            total_warnings = sum(warning_msg_counts.values())
+            warning_details = [
+                f"{msg} (x{count})" if count > 1 else msg
+                for msg, count in warning_msg_counts.items()
+            ]
+            summary_parts.append(f"{total_warnings} warnings: {', '.join(warning_details)}")
+
+        if error_msg_counts:
+            total_errors = sum(error_msg_counts.values())
+            error_details = [
+                f"{msg} (x{count})" if count > 1 else msg for msg, count in error_msg_counts.items()
+            ]
+            summary_parts.append(f"{total_errors} errors: {', '.join(error_details)}")
+
+        return "; ".join(summary_parts)
+
+    def _update_status(self) -> None:
+        """Update overall status based on event priority"""
+        self.status = ExecutionStatus.OK
+        for event in self.events:
+            if event.priority >= EventPriority.ERROR:
+                self.status = ExecutionStatus.ERROR
+                break
+            elif event.priority == EventPriority.WARNING:
+                self.status = ExecutionStatus.WARNING
+
+    def finalize(self, logger: Optional[logging.Logger] = None) -> None:
+        """Finalize the task result by setting end time, updating status, and logging
+        the result.
+
+        Args:
+            logger (Optional[logging.Logger], optional): python logger instance. Defaults to None.
+        """
+        self.end_time = datetime.datetime.now()
+
+        if self.status == ExecutionStatus.UNSET:
+            self._update_status()
+
+        if not self.message:
+            if self.status == ExecutionStatus.OK:
+                self.message = "task completed successfully"
+            elif self.status == ExecutionStatus.WARNING:
+                self.message = "task completed with warnings"
+            elif self.status == ExecutionStatus.NOT_RAN:
+                self.message = "task skipped"
+            elif self.status == ExecutionStatus.EXECUTION_FAILURE:
+                self.message = "task failed to run"
+            elif self.status == ExecutionStatus.ERROR:
+                self.message = "task detected errors"
+
+        event_summary = self._get_event_summary()
+        if event_summary:
+            self.message += f" ({event_summary})"
+
+        if logger:
+            logger.log(
+                STATUS_LOG_LEVEL_MAP.get(self.status, logging.INFO),
+                "(%s) %s",
+                self.parent,
+                self.message,
+            )

nodescraper/models/timerangeargs.py

@@ -0,0 +1,38 @@
+###############################################################################
+#
+# MIT License
+#
+# Copyright (c) 2025 Advanced Micro Devices, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+###############################################################################
+import datetime
+from typing import Optional
+
+from nodescraper.models import AnalyzerArgs
+
+
+class TimeRangeAnalysisArgs(AnalyzerArgs):
+    """
+    Model for time range analysis arguments.
+    """
+
+    analysis_range_start: Optional[datetime.datetime] = None
+    analysis_range_end: Optional[datetime.datetime] = None