howler-api 3.0.0.dev374__py3-none-any.whl

howler/actions/__init__.py

@@ -0,0 +1,168 @@
+import importlib
+import os
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from howler.common.logging import get_logger
+from howler.odm.models.user import User
+from howler.plugins import get_plugins
+
+logger = get_logger(__file__)
+
+PLUGIN_PATH = Path(os.environ.get("HWL_PLUGIN_DIRECTORY", "/etc/howler/plugins"))
+
+
+def __sanitize_specification(spec: dict[str, Any]) -> dict[str, Any]:
+    """Adapt the specification for use in the UI
+
+    Args:
+        spec (dict[str, Any]): The raw specification
+
+    Returns:
+        dict[str, Any]: The sanitized specification for use in the UI
+    """
+    return {
+        **spec,
+        "description": {
+            **spec["description"],
+            "long": re.sub(r"\n +(request_id|query).+", "", spec["description"]["long"])
+            .replace("\n    ", "\n")
+            .replace("Args:", "Args:\n"),
+        },
+        "steps": [{**step, "args": {k: list(v) for k, v in step["args"].items()}} for step in spec.get("steps", [])],
+    }
+
+
+def __sanitize_report(report: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Deduplicate identical entries with different queries
+
+    Args:
+        report (list[dict[str, Any]]): The unsanitized, verbose report
+
+    Returns:
+        list[dict[str, Any]]: The sanitized, concise report
+    """
+    by_message: dict[str, Any] = {}
+
+    for entry in report:
+        # if these three keys match, we should merge the queries that use them both. For example, when multiple hits
+        # fail to transition for the same reason.
+        key = f"{entry['title']}==={entry['message']}==={entry['outcome']}"
+
+        if key in by_message:
+            by_message[key].append(f'({entry["query"]})')
+        else:
+            by_message[key] = [f'({entry["query"]})']
+
+    sanitized: list[dict[str, Any]] = []
+    for key, queries in by_message.items():
+        (title, message, outcome) = key.split("===")
+
+        sanitized.append(
+            {
+                "query": " OR ".join(queries),
+                "outcome": outcome,
+                "title": title,
+                "message": message,
+            }
+        )
+
+    return sanitized
+
+
+def execute(
+    operation_id: str,
+    query: str,
+    user: User | None,
+    request_id: Optional[str] = None,
+    **kwargs,
+) -> list[dict[str, Any]]:
+    """Execute a specification
+
+    Args:
+        operation_id (str): The id of the operation to run
+        query (str): The query to run this action on
+        user (dict[str, Any]): The user running this action
+        request_id (str, None): A user-provided ID, can be used to track the progress of their excecution via websockets
+
+    Returns:
+        list[dict[str, Any]]: A report on the execution
+    """
+    operation = None
+    try:
+        operation = importlib.import_module(f"howler.actions.{operation_id}")
+    except ImportError:
+        pass
+
+    if not operation:
+        for plugin in get_plugins():
+            if not plugin.modules.operations:
+                continue
+
+            operation = next(
+                (operation for operation in plugin.modules.operations if operation.OPERATION_ID == operation_id), None
+            )
+
+            if operation:
+                break
+
+    if not operation:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Unknown Action",
+                "message": f"The operation ID provided ({operation_id}) does not match any enabled operations.",
+            }
+        ]
+
+    user_roles: set[str] = set(user["type"] if user else [])
+    missing_roles = set(operation.specification()["roles"]) - user_roles
+    if missing_roles:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Insufficient permissions",
+                "message": (
+                    f"The operation ID provided ({operation_id}) requires permissions you do not have "
+                    f"({', '.join(missing_roles)}). Contact HOWLER Support for more information."
+                ),
+            }
+        ]
+
+    report = operation.execute(query=query, request_id=request_id, user=user, **kwargs)
+
+    return __sanitize_report(report)
+
+
+def specifications() -> list[dict[str, Any]]:
+    """A list of specifications for the available operations
+
+    Returns:
+        list[dict[str, Any]]: A list of specifications
+    """
+    specifications = []
+
+    for module in (
+        _file
+        for _file in Path(__file__).parent.iterdir()
+        if _file.suffix == ".py" and _file.name not in ["__init__.py", "example_plugin.py"]
+    ):
+        try:
+            operation = importlib.import_module(f"howler.actions.{module.stem}")
+
+            specifications.append(__sanitize_specification(operation.specification()))
+
+        except Exception:  # pragma: no cover
+            logger.exception("Error when initializing %s", module)
+
+    for plugin in get_plugins():
+        if not plugin.modules.operations:
+            continue
+
+        for operation in plugin.modules.operations:
+            specifications.append(__sanitize_specification(operation.specification()))
+
+    return specifications

howler/actions/add_label.py

@@ -0,0 +1,111 @@
+from typing import Optional
+
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.odm.models.howler_data import Label
+from howler.utils.str_utils import sanitize_lucene_query
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "add_label"
+
+CATEGORIES = list(Label.fields().keys())
+
+
+def execute(query: str, category: str = "generic", label: Optional[str] = None, **kwargs):
+    """Add a label to a hit.
+
+    Args:
+        query (str): The query on which to apply this automation.
+        category (str, optional): The category of label to add. Defaults to "generic".
+        label (str): The label content. Defaults to None.
+    """
+    if category not in CATEGORIES:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Category",
+                "message": f"'{category}' is not a valid category.",
+            }
+        ]
+
+    if not label:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Label",
+                "message": "Label cannot be empty.",
+            }
+        ]
+
+    report = []
+
+    ds = datastore()
+
+    skipped_hits = ds.hit.search(
+        f"({query}) AND howler.labels.{category}:{sanitize_lucene_query((label))}",
+        fl="howler.id",
+    )["items"]
+
+    if len(skipped_hits) > 0:
+        report.append(
+            {
+                "query": f"howler.id:({' OR '.join(h.howler.id for h in skipped_hits)})",
+                "outcome": "skipped",
+                "title": "Skipped Hit with Label",
+                "message": f"These hits already have the label {label}.",
+            }
+        )
+
+    try:
+        ds.hit.update_by_query(
+            query,
+            [hit_helper.list_add(f"howler.labels.{category}", label, if_missing=True)],
+        )
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Label '{label}' added to category '{category}' for all matching hits.",
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": f"Unknown exception occurred: {str(e)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Add Label",
+        "priority": 8,
+        "i18nKey": "operations.add_label",
+        "description": {
+            "short": "Add a label to a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"category": [], "label": []},
+                "options": {"category": CATEGORIES},
+                "validation": {"warn": {"query": "howler.labels.$category:$label"}},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

howler/actions/add_to_bundle.py

@@ -0,0 +1,159 @@
+from typing import Optional
+
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.services import hit_service
+from howler.utils.str_utils import sanitize_lucene_query
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "add_to_bundle"
+
+
+def execute(query: str, bundle_id: Optional[str] = None, **kwargs):
+    """Add a set of hits matching the query to the specified bundle.
+
+    Args:
+        query (str): The query containing the matching hits
+        bundle_id (str): The `howler.id` of the bundle to add the hits to.
+    """
+    report = []
+
+    if not bundle_id:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Bundle ID",
+                "message": "Bundle ID cannot be empty.",
+            }
+        ]
+
+    try:
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        if not bundle_hit or not bundle_hit.howler.is_bundle:
+            report.append(
+                {
+                    "query": query,
+                    "outcome": "error",
+                    "title": "Invalid Bundle",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it is not a bundle.",
+                }
+            )
+            return report
+
+        ds = datastore()
+
+        skipped_hits_bundles = ds.hit.search(
+            f"({query}) AND howler.is_bundle:true",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits_bundles) > 0:
+            report.append(
+                {
+                    "query": f"({query}) AND howler.is_bundle:true",
+                    "outcome": "skipped",
+                    "title": "Skipped Bundles",
+                    "message": "Bundles cannot be added to a bundle.",
+                }
+            )
+
+        skipped_hits_already_added = ds.hit.search(
+            f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits_already_added) > 0:
+            report.append(
+                {
+                    "query": f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
+                    "outcome": "skipped",
+                    "title": "Skipped Hits",
+                    "message": "These hits have already been added to the specified bundle.",
+                }
+            )
+
+        safe_query = f"({query}) AND (-howler.bundles:({sanitize_lucene_query(bundle_id)}) AND howler.is_bundle:false)"
+        matching_hits = ds.hit.search(safe_query)["items"]
+        if len(matching_hits) < 1:
+            report.append(
+                {
+                    "query": safe_query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
+                }
+            )
+            return report
+
+        ds.hit.update_by_query(
+            safe_query,
+            [hit_helper.list_add("howler.bundles", sanitize_lucene_query(bundle_id), if_missing=True)],
+        )
+
+        operations = [
+            hit_helper.list_add(
+                "howler.hits",
+                hit["howler"]["id"],
+                if_missing=True,
+            )
+            for hit in matching_hits
+        ]
+
+        operations.append(hit_helper.update("howler.bundle_size", len(operations)))
+        hit_service.update_hit(
+            bundle_id,
+            operations,
+        )
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        report.append(
+            {
+                "query": safe_query.replace("-howler.bundles", "howler.bundles"),
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": "The specified bundle has had all matching hits added.",
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": f"Unknown exception occurred: {str(e)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Add to Bundle",
+        "priority": 6,
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Add a set of hits to a bundle",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"bundle_id": []},
+                "options": {},
+                "validation": {
+                    "warn": {"query": "howler.bundles:($bundle_id) OR howler.is_bundle:true"},
+                    "error": {
+                        "query": "howler.id:$bundle_id AND howler.is_bundle:false",
+                        "message": "The bundle id given must be a bundle.",
+                    },
+                },
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

howler/actions/change_field.py

@@ -0,0 +1,76 @@
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+
+hit_helper = OdmHelper(Hit)
+
+OPERATION_ID = "change_field"
+
+
+def execute(query: str, field: str, value: str, **kwargs):
+    """Change one of the fields of a hit
+
+    Args:
+        query (str): The query to run this action on
+        field (str): The field to update.
+        value (str): The value to set it to. Must be a string.
+    """
+    if field not in Hit.flat_fields():
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid field",
+                "message": (f"Field '{field}' does not exist. You must pick a valid entry from the howler index."),
+            }
+        ]
+
+    report = []
+
+    try:
+        datastore().hit.update_by_query(
+            query,
+            [hit_helper.update(field, value)],
+        )
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Field '{field}' updated to value '{value}' for all matching hits.",
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": str(e),
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Change Field",
+        "i18nKey": f"operations.{OPERATION_ID}",
+        "description": {
+            "short": "Change one of the fields of a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_advanced", "admin"],
+        "steps": [
+            {
+                "args": {"field": [], "value": []},
+                "options": {"field": list(Hit.flat_fields().keys())},
+            }
+        ],
+        "triggers": VALID_TRIGGERS,
+    }

howler/actions/demote.py

@@ -0,0 +1,160 @@
+from typing import Optional
+
+import howler.helper.hit as hit_helper
+from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
+from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
+from howler.odm.models.howler_data import (
+    Assessment,
+    AssessmentEscalationMap,
+    Escalation,
+    HitStatus,
+)
+from howler.odm.models.user import User
+from howler.utils.str_utils import sanitize_lucene_query
+
+OPERATION_ID = "demote"
+
+ESCALATIONS = [esc for esc in Escalation.list() if esc != Escalation.EVIDENCE]
+
+odm_helper = OdmHelper(Hit)
+
+
+def execute(
+    query: str,
+    escalation: Escalation = Escalation.HIT,
+    assessment: Optional[str] = None,
+    rationale: Optional[str] = None,
+    user: Optional[User] = None,
+    **kwargs,
+):
+    """Demote a hit.
+
+    Args:
+        query (str): The query on which to apply this automation.
+        escalation (str, optional): The escalation to demote to. Defaults to "hit".
+        assessment (str, optional): The assessment to apply if demoting to miss. Required if escalation is "miss".
+        rationale (str, optional): The optional rationale to apply if demoting to miss.
+    """
+    if escalation not in ESCALATIONS:
+        return [
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Invalid Escalation",
+                "message": f"'{escalation}' is not a valid escalation.",
+            }
+        ]
+
+    report = []
+
+    ds = datastore()
+
+    skipped_hits = ds.hit.search(
+        f"({query}) AND howler.escalation:{sanitize_lucene_query(escalation)}",
+        fl="howler.id",
+    )["items"]
+
+    if len(skipped_hits) > 0:
+        report.append(
+            {
+                "query": f"howler.id:({' OR '.join(h.howler.id for h in skipped_hits)})",
+                "outcome": "skipped",
+                "title": "Skipped Hit with Escalation",
+                "message": f"These hits already have the escalation {escalation}.",
+            }
+        )
+
+    try:
+        if escalation in [Escalation.HIT, Escalation.ALERT]:
+            ds.hit.update_by_query(
+                query,
+                [
+                    *hit_helper.demote_hit(escalation=escalation),
+                    odm_helper.update("howler.assessment", None),
+                    odm_helper.update("howler.rationale", None),
+                ],
+            )
+        else:
+            if not assessment:
+                report.append(
+                    {
+                        "query": query,
+                        "outcome": "error",
+                        "title": "Missing assessment",
+                        "message": "You must provide as assessment value when demoting to miss.",
+                    }
+                )
+                return report
+
+            ds.hit.update_by_query(
+                query,
+                [
+                    *hit_helper.assess_hit(assessment, rationale),
+                    odm_helper.update(
+                        "howler.assignment",
+                        user.get("uname", "automation") if user else "automation",
+                    ),
+                    odm_helper.update("howler.status", HitStatus.RESOLVED),
+                ],
+            )
+
+        report.append(
+            {
+                "query": query,
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": f"Demoted to '{escalation}' for all matching hits.",
+            }
+        )
+    except Exception as e:
+        report.append(
+            {
+                "query": query,
+                "outcome": "error",
+                "title": "Failed to Execute",
+                "message": f"Unknown exception occurred: {str(e)}",
+            }
+        )
+
+    return report
+
+
+def specification():
+    """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
+    return {
+        "id": OPERATION_ID,
+        "title": "Demote Hit",
+        "i18nKey": "operations.demote",
+        "description": {
+            "short": "Demote a hit",
+            "long": execute.__doc__,
+        },
+        "roles": ["automation_basic"],
+        "steps": [
+            {
+                "args": {"escalation": []},
+                "options": {"escalation": ESCALATIONS},
+                "validation": {"warn": {"query": "howler.escalation:$escalation"}},
+            },
+            {
+                "args": {
+                    "assessment": ["escalation:miss"],
+                    "rationale": ["escalation:miss"],
+                },
+                "options": {
+                    "assessment": {
+                        "escalation:miss": [
+                            assessment
+                            for assessment in Assessment.list()
+                            if AssessmentEscalationMap[assessment] == Escalation.MISS
+                        ],
+                        "escalation:alert": [],
+                        "escalation:hit": [],
+                    }
+                },
+            },
+        ],
+        "triggers": VALID_TRIGGERS,
+    }