breakpilot-core/control-pipeline/services/applicability_engine.py

"""
Applicability Engine -- filters controls based on company profile + scope answers.

Deterministic, no LLM needed. Implements Scoped Control Applicability (Phase C2).

Filtering logic:
  - Controls with NULL applicability fields are INCLUDED (apply to everyone).
  - Controls with '["all"]' match all queries.
  - Industry: control applies if its applicable_industries contains the requested
    industry OR contains "all" OR is NULL.
  - Company size: control applies if its applicable_company_size contains the
    requested size OR contains "all" OR is NULL.
  - Scope signals: control applies if it has NO scope_conditions, or the company
    has at least one of the required signals (requires_any logic).
"""

from __future__ import annotations

import json
import logging
from typing import Any, Optional

from sqlalchemy import text

from db.session import SessionLocal

logger = logging.getLogger(__name__)

# Valid company sizes (ordered smallest to largest)
VALID_SIZES = ("micro", "small", "medium", "large", "enterprise")


def _parse_json_text(value: Any) -> Any:
    """Parse a TEXT column that stores JSON. Returns None if unparseable."""
    if value is None:
        return None
    if isinstance(value, (list, dict)):
        return value
    if isinstance(value, str):
        try:
            return json.loads(value)
        except (json.JSONDecodeError, ValueError):
            return None
    return None


def _matches_industry(applicable_industries_raw: Any, industry: str) -> bool:
    """Check if a control's applicable_industries matches the requested industry."""
    industries = _parse_json_text(applicable_industries_raw)
    if industries is None:
        return True  # NULL = applies to everyone
    if not isinstance(industries, list):
        return True  # malformed = include
    if "all" in industries:
        return True
    return industry in industries


def _matches_company_size(applicable_company_size_raw: Any, company_size: str) -> bool:
    """Check if a control's applicable_company_size matches the requested size."""
    sizes = _parse_json_text(applicable_company_size_raw)
    if sizes is None:
        return True  # NULL = applies to everyone
    if not isinstance(sizes, list):
        return True  # malformed = include
    if "all" in sizes:
        return True
    return company_size in sizes


def _matches_scope_signals(
    scope_conditions_raw: Any, scope_signals: list[str]
) -> bool:
    """Check if a control's scope_conditions are satisfied by the given signals.

    A control with scope_conditions = {"requires_any": ["uses_ai", "processes_health_data"]}
    matches if the company has at least one of those signals.
    A control with NULL or empty scope_conditions always matches.
    """
    conditions = _parse_json_text(scope_conditions_raw)
    if conditions is None:
        return True  # no conditions = applies to everyone
    if not isinstance(conditions, dict):
        return True  # malformed = include

    requires_any = conditions.get("requires_any", [])
    if not requires_any:
        return True  # no required signals = applies to everyone

    # Company must have at least one of the required signals
    return bool(set(requires_any) & set(scope_signals))


def get_applicable_controls(
    db,
    industry: Optional[str] = None,
    company_size: Optional[str] = None,
    scope_signals: Optional[list[str]] = None,
    limit: int = 100,
    offset: int = 0,
) -> dict[str, Any]:
    """
    Returns controls applicable to the given company profile.

    Uses SQL pre-filtering with LIKE for performance, then Python post-filtering
    for precise JSON matching (since columns are TEXT, not JSONB).

    Args:
        db: SQLAlchemy session
        industry: e.g. "Telekommunikation", "Energie", "Gesundheitswesen"
        company_size: e.g. "medium", "large", "enterprise"
        scope_signals: e.g. ["uses_ai", "third_country_transfer"]
        limit: max results to return (applied after filtering)
        offset: pagination offset (applied after filtering)

    Returns:
        dict with total_applicable count, paginated controls, and breakdown stats
    """
    if scope_signals is None:
        scope_signals = []

    # SQL pre-filter: broad match to reduce Python-side filtering
    query = """
        SELECT id, framework_id, control_id, title, objective, rationale,
               scope, requirements, test_procedure, evidence,
               severity, risk_score, implementation_effort,
               evidence_confidence, open_anchors, release_state, tags,
               license_rule, source_original_text, source_citation,
               customer_visible, verification_method, category, evidence_type,
               target_audience, generation_metadata, generation_strategy,
               applicable_industries, applicable_company_size, scope_conditions,
               parent_control_uuid, decomposition_method, pipeline_version,
               created_at, updated_at
        FROM canonical_controls
        WHERE release_state NOT IN ('duplicate', 'deprecated', 'rejected')
    """
    params: dict[str, Any] = {}

    # SQL-level pre-filtering (broad, may include false positives)
    if industry:
        query += """ AND (applicable_industries IS NULL
            OR applicable_industries LIKE '%"all"%'
            OR applicable_industries LIKE '%' || :industry || '%')"""
        params["industry"] = industry

    if company_size:
        query += """ AND (applicable_company_size IS NULL
            OR applicable_company_size LIKE '%"all"%'
            OR applicable_company_size LIKE '%' || :company_size || '%')"""
        params["company_size"] = company_size

    # For scope_signals we cannot do precise SQL filtering on requires_any,
    # but we can at least exclude controls whose scope_conditions text
    # does not contain any of the requested signals (if only 1 signal).
    # With multiple signals we skip SQL pre-filter and do it in Python.
    if scope_signals and len(scope_signals) == 1:
        query += """ AND (scope_conditions IS NULL
            OR scope_conditions LIKE '%' || :scope_sig || '%')"""
        params["scope_sig"] = scope_signals[0]

    query += " ORDER BY control_id"

    rows = db.execute(text(query), params).fetchall()

    # Python-level precise filtering
    applicable = []
    for r in rows:
        if industry and not _matches_industry(r.applicable_industries, industry):
            continue
        if company_size and not _matches_company_size(
            r.applicable_company_size, company_size
        ):
            continue
        if scope_signals and not _matches_scope_signals(
            r.scope_conditions, scope_signals
        ):
            continue
        applicable.append(r)

    total_applicable = len(applicable)

    # Apply pagination
    paginated = applicable[offset : offset + limit]

    # Build domain breakdown
    domain_counts: dict[str, int] = {}
    for r in applicable:
        domain = r.control_id.split("-")[0].upper() if r.control_id else "UNKNOWN"
        domain_counts[domain] = domain_counts.get(domain, 0) + 1

    # Build severity breakdown
    severity_counts: dict[str, int] = {}
    for r in applicable:
        sev = r.severity or "unknown"
        severity_counts[sev] = severity_counts.get(sev, 0) + 1

    # Build industry breakdown (from matched controls)
    industry_counts: dict[str, int] = {}
    for r in applicable:
        industries = _parse_json_text(r.applicable_industries)
        if isinstance(industries, list):
            for ind in industries:
                industry_counts[ind] = industry_counts.get(ind, 0) + 1
        else:
            industry_counts["unclassified"] = (
                industry_counts.get("unclassified", 0) + 1
            )

    return {
        "total_applicable": total_applicable,
        "limit": limit,
        "offset": offset,
        "controls": [_row_to_control(r) for r in paginated],
        "breakdown": {
            "by_domain": domain_counts,
            "by_severity": severity_counts,
            "by_industry": industry_counts,
        },
    }


def _row_to_control(r) -> dict[str, Any]:
    """Convert a DB row to a control dict for API response."""
    return {
        "id": str(r.id),
        "framework_id": str(r.framework_id),
        "control_id": r.control_id,
        "title": r.title,
        "objective": r.objective,
        "rationale": r.rationale,
        "severity": r.severity,
        "category": r.category,
        "verification_method": r.verification_method,
        "evidence_type": getattr(r, "evidence_type", None),
        "target_audience": r.target_audience,
        "applicable_industries": r.applicable_industries,
        "applicable_company_size": r.applicable_company_size,
        "scope_conditions": r.scope_conditions,
        "release_state": r.release_state,
        "control_id_domain": (
            r.control_id.split("-")[0].upper() if r.control_id else None
        ),
        "created_at": r.created_at.isoformat() if r.created_at else None,
        "updated_at": r.updated_at.isoformat() if r.updated_at else None,
    }