cfa-kernel 0.1.0__py3-none-any.whl

cfa/behavior/llm.py

@@ -0,0 +1,244 @@
+"""
+CFA LLM Systematizer
+====================
+Optional LLM-backed plugin for behavior specification.
+
+Transforms natural-language governance descriptions into BehaviorSpecs
+that feed the deterministic Systematizer. The LLM is used only for the
+"understanding" step — all rules are still generated deterministically.
+
+Usage:
+    from cfa.behavior.llm import OpenAISystematizerBackend
+    from cfa.behavior import Systematizer
+
+    backend = OpenAISystematizerBackend(model="gpt-4o-mini")
+    taxonomy, rules = Systematizer().systematize_from_nl(
+        "Pipeline must protect PII, enforce merge keys, and stay within budget.",
+        backend=backend,
+    )
+
+Architecture:
+    NL description → LLM → BehaviorSpec (JSON) → Systematizer → (Taxonomy, Rules)
+                   ↑ optional              ↑ deterministic
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .spec import BehaviorSpec
+
+_SYSTEMATIZER_SYSTEM_PROMPT = """\
+You are a data governance specification expert. Given a description of a data \
+pipeline's requirements, constraints, and context, produce a structured \
+behavior specification in JSON format.
+
+For each potential failure mode, classify it using ONE of these condition types:
+{pii_in_protected_layer, missing_merge_key, missing_partition, schema_mismatch,
+ cost_budget_exceeded, sensitive_without_partition, enforce_types_disabled,
+ pii_without_policy, unauthorized_gold_write, custom}
+
+Condition type meanings:
+- pii_in_protected_layer: PII exposed in Silver/Gold without anonymization
+- missing_merge_key: Write to Silver/Gold without merge_key enforcement
+- missing_partition: High-volume or sensitive dataset processed without partition filter
+- schema_mismatch: Output schema differs from contract
+- cost_budget_exceeded: Estimated cost exceeds configured ceiling
+- sensitive_without_partition: Sensitive dataset without partition declaration
+- enforce_types_disabled: Type enforcement disabled on protected layer write
+- pii_without_policy: PII present without no_pii_raw constraint
+- unauthorized_gold_write: Unauthorized write to Gold layer
+- custom: Any other custom governance condition
+
+Output ONLY valid JSON. No markdown fences, no explanation outside the JSON.
+
+JSON schema:
+{
+  "behavior": {
+    "name": "<snake_case_name>",
+    "description": "<markdown_description_of_governance_rules>",
+    "failure_modes": [
+      {
+        "code": "<unique_snake_case_code>",
+        "label": "<Short human-readable label>",
+        "description": "<When this failure occurs and why it matters>",
+        "condition": "<condition_type>",
+        "severity": "<critical|high|medium|warning|info>",
+        "action": "<replan|block>",
+        "target_layer": "<bronze|silver|gold>",
+        "remediation": ["<actionable step 1>", "<actionable step 2>"]
+      }
+    ]
+  }
+}
+
+Rules:
+- Generate at least 2 failure modes covering the most important constraints.
+- Use "action": "replan" for automatically fixable issues, "action": "block" for
+  issues that require human review (e.g., PII in Gold without anonymization).
+- Severity: "critical" for PII/security, "high" for data quality, "medium" for
+  cost/performance, "warning" for informational.
+- Remediation steps must be actionable and specific.
+"""
+
+_SYSTEMATIZER_USER_TEMPLATE = """\
+Pipeline description:
+{description}
+
+Context:
+{context}
+"""
+
+
+class LLMSystematizerBackend(ABC):
+    """Backend for LLM-assisted behavior specification.
+
+    Implement this to use any LLM provider (OpenAI, Anthropic, Azure, local).
+    """
+
+    @abstractmethod
+    def complete(self, system_prompt: str, user_message: str) -> str:
+        """Send prompts to the LLM and return the completion text."""
+        ...
+
+
+class OpenAISystematizerBackend(LLMSystematizerBackend):
+    """OpenAI-compatible backend for NL → BehaviorSpec.
+
+    Requires: pip install openai
+
+    Args:
+        model: Model name (default: gpt-4o-mini).
+        temperature: Sampling temperature (default: 0.0 for deterministic output).
+        api_key: OpenAI API key. If None, reads from OPENAI_API_KEY env var.
+        base_url: Custom API base URL (for Azure, local models, etc.).
+        max_tokens: Maximum completion tokens.
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        temperature: float = 0.0,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_tokens: int = 2048,
+    ) -> None:
+        self.model = model
+        self.temperature = temperature
+        self.api_key = api_key
+        self.base_url = base_url
+        self.max_tokens = max_tokens
+
+    def complete(self, system_prompt: str, user_message: str) -> str:
+        try:
+            from openai import OpenAI
+        except ImportError:
+            raise ImportError(
+                "openai package is required for OpenAISystematizerBackend. "
+                "Install it with: pip install openai"
+            )
+
+        client_kwargs: dict[str, Any] = {}
+        if self.api_key:
+            client_kwargs["api_key"] = self.api_key
+        if self.base_url:
+            client_kwargs["base_url"] = self.base_url
+
+        client = OpenAI(**client_kwargs)
+
+        response = client.chat.completions.create(
+            model=self.model,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_message},
+            ],
+        )
+        return response.choices[0].message.content or ""
+
+
+class LLMSystematizer:
+    """Transforms NL descriptions into BehaviorSpecs via an LLM backend.
+
+    This is the "Phase 6" plugin — adds NL understanding on top of the
+    deterministic Systematizer. Without a backend, falls back gracefully.
+
+    Usage:
+        backend = OpenAISystematizerBackend()
+        spec = LLMSystematizer().systematize_nl(
+            "Pipeline must protect PII and enforce merge keys.",
+            backend=backend,
+        )
+        # spec is a BehaviorSpec ready for Systematizer
+    """
+
+    def systematize_nl(
+        self,
+        description: str,
+        *,
+        backend: LLMSystematizerBackend,
+        context: str = "",
+    ) -> BehaviorSpec:
+        """Transform a natural language description into a BehaviorSpec.
+
+        Args:
+            description: Natural language description of governance requirements.
+            backend: LLM backend implementation.
+            context: Optional context about the target system.
+
+        Returns:
+            A BehaviorSpec ready for Systematizer.systematize().
+
+        Raises:
+            ValueError: If the LLM response cannot be parsed.
+        """
+        user_message = _SYSTEMATIZER_USER_TEMPLATE.format(
+            description=description, context=context or "No additional context provided."
+        )
+
+        raw = backend.complete(_SYSTEMATIZER_SYSTEM_PROMPT, user_message)
+
+        if not raw.strip():
+            raise ValueError("LLM returned empty response.")
+
+        data = self._parse_llm_response(raw)
+        return BehaviorSpec.from_dict(data)
+
+    def _parse_llm_response(self, raw: str) -> dict[str, Any]:
+        raw = raw.strip()
+        # Remove markdown code fences if present
+        if raw.startswith("```"):
+            lines = raw.split("\n")
+            if lines[0].startswith("```"):
+                lines = lines[1:]
+            if lines and lines[-1].strip() == "```":
+                lines = lines[:-1]
+            raw = "\n".join(lines)
+
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            # Try to find JSON object in the text
+            start = raw.find("{")
+            end = raw.rfind("}")
+            if start >= 0 and end > start:
+                try:
+                    data = json.loads(raw[start : end + 1])
+                except json.JSONDecodeError:
+                    raise ValueError(
+                        f"LLM response is not valid JSON. Raw response:\n{raw[:500]}"
+                    )
+            else:
+                raise ValueError(
+                    f"LLM response does not contain JSON. Raw response:\n{raw[:500]}"
+                )
+
+        if "behavior" not in data:
+            raise ValueError(
+                f"LLM response missing 'behavior' key. Got keys: {list(data.keys())}"
+            )
+
+        return data

cfa/behavior/spec.py

@@ -0,0 +1,235 @@
+"""
+CFA Behavior Spec
+=================
+Structured specification of allowed and prohibited behaviors.
+
+A BehaviorSpec bridges the gap between human-written governance policies
+(in natural language or YAML) and executable CFA policy rules.
+
+Inspired by ASSERT's systematization: BehaviorSpec → BehaviorTaxonomy → PolicyRules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class ConditionType(StrEnum):
+    """Condition types that map to CFA constraint checks."""
+
+    PII_IN_PROTECTED_LAYER = "pii_in_protected_layer"
+    MISSING_MERGE_KEY = "missing_merge_key"
+    SCHEMA_MISMATCH = "schema_mismatch"
+    SHUFFLE_BUDGET_EXCEEDED = "shuffle_budget_exceeded"
+    MISSING_PARTITION = "missing_partition"
+    COST_BUDGET_EXCEEDED = "cost_budget_exceeded"
+    UNAUTHORIZED_GOLD_WRITE = "unauthorized_gold_write"
+    ENFORCE_TYPES_DISABLED = "enforce_types_disabled"
+    PII_WITHOUT_POLICY = "pii_without_policy"
+    SENSITIVE_WITHOUT_PARTITION = "sensitive_without_partition"
+    CUSTOM = "custom"
+
+
+@dataclass
+class BehaviorCategory:
+    """A single behavior category in the taxonomy.
+
+    Attributes:
+        code: Unique identifier, e.g. "raw_pii_exposure".
+        label: Human-readable label, e.g. "Raw PII in Silver/Gold".
+        description: Detailed description of the behavior.
+        allowed: True if this behavior is permitted, False if prohibited.
+        condition_type: The CFA ConditionType that detects this behavior.
+        severity: Fault severity when this behavior is detected.
+        remediation: Ordered list of remediation actions.
+        metadata: Custom key-value pairs for condition refinements.
+    """
+
+    code: str
+    label: str
+    description: str
+    allowed: bool = True
+    condition_type: ConditionType = ConditionType.CUSTOM
+    severity: str = "high"
+    remediation: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class BehaviorTaxonomy:
+    """Complete taxonomy of behaviors for a governance domain.
+
+    Separates behaviors into allowed (permissible) and not_allowed (prohibited)
+    categories, with metadata for traceability.
+    """
+
+    name: str
+    description: str = ""
+    context: str = ""
+
+    allowed: list[BehaviorCategory] = field(default_factory=list)
+    not_allowed: list[BehaviorCategory] = field(default_factory=list)
+
+    spec_version: str = "v1.0"
+    source_yaml: str = ""
+
+    @property
+    def categories(self) -> list[BehaviorCategory]:
+        return self.allowed + self.not_allowed
+
+    @property
+    def category_count(self) -> int:
+        return len(self.categories)
+
+    def generate_test_intents(self, count: int = 3) -> list[str]:
+        """Generate test intent strings for each behavior category.
+
+        Used for automated test case generation in CI.
+        """
+        intents: list[str] = []
+        template_map = {
+            ConditionType.PII_IN_PROTECTED_LAYER: (
+                "Join {datasets} with PII columns and persist to {layer}"
+            ),
+            ConditionType.MISSING_MERGE_KEY: (
+                "Write {datasets} directly to {layer} without merge key"
+            ),
+            ConditionType.MISSING_PARTITION: (
+                "Scan full {datasets} without partition filter"
+            ),
+            ConditionType.SCHEMA_MISMATCH: (
+                "Write {datasets} to {layer} with modified schema"
+            ),
+            ConditionType.SHUFFLE_BUDGET_EXCEEDED: (
+                "Join massive {datasets} with cross join"
+            ),
+            ConditionType.COST_BUDGET_EXCEEDED: (
+                "Process full {datasets} without budget limit"
+            ),
+        }
+        for cat in self.not_allowed:
+            template = template_map.get(
+                cat.condition_type,
+                "Process {datasets} in {layer} layer",
+            )
+            for i in range(min(count, 3)):
+                intents.append(
+                    template.format(
+                        datasets=cat.code.replace("_", " "),
+                        layer=cat.metadata.get("target_layer", "Silver"),
+                    )
+                    + f" #{cat.code}#{i}"
+                )
+        return intents
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "context": self.context,
+            "allowed": [
+                {
+                    "code": c.code,
+                    "label": c.label,
+                    "description": c.description,
+                    "condition_type": c.condition_type.value,
+                }
+                for c in self.allowed
+            ],
+            "not_allowed": [
+                {
+                    "code": c.code,
+                    "label": c.label,
+                    "description": c.description,
+                    "condition_type": c.condition_type.value,
+                    "severity": c.severity,
+                    "remediation": c.remediation,
+                }
+                for c in self.not_allowed
+            ],
+            "spec_version": self.spec_version,
+        }
+
+
+@dataclass
+class BehaviorSpec:
+    """Top-level behavior specification, typically loaded from YAML.
+
+    Schema:
+        behavior:
+          name: fiscal_reconciliation
+          description: |
+            # Fiscal Data Reconciliation Governance
+            ...
+          failure_modes:
+            - code: raw_pii_exposure
+              ...
+        context: |
+          Target is a PySpark ETL pipeline...
+        generate:
+          taxonomy: true
+          test_cases: true
+    """
+
+    name: str
+    description: str = ""
+    context: str = ""
+    failure_modes: list[dict[str, Any]] = field(default_factory=list)
+    target_layer: str = "silver"
+    backend: str = "pyspark"
+    auto_generate_rules: bool = True
+    generate_test_cases: bool = True
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> BehaviorSpec:
+        """Parse a BehaviorSpec from a YAML file.
+
+        Requires PyYAML. Falls back gracefully with a clear message if not installed.
+        """
+        p = Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"Behavior spec file not found: {path}")
+
+        try:
+            import yaml
+        except ImportError:
+            raise ImportError(
+                "PyYAML is required to load BehaviorSpec from YAML. "
+                "Install it with: pip install pyyaml"
+            )
+
+        raw = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+        behavior = raw.get("behavior", raw)
+        pipeline = raw.get("pipeline", raw.get("generate", {}))
+
+        return cls(
+            name=behavior.get("name", "unnamed"),
+            description=behavior.get("description", ""),
+            context=raw.get("context", ""),
+            failure_modes=behavior.get("failure_modes", []),
+            target_layer=behavior.get("target_layer", raw.get("default_model", {}).get("target_layer", "silver")),
+            backend=behavior.get("backend", raw.get("default_model", {}).get("backend", "pyspark")),
+            auto_generate_rules=pipeline.get("policy", {}).get("auto_generate_rules", True),
+            generate_test_cases=pipeline.get("generate", {}).get("test_cases", True),
+        )
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BehaviorSpec:
+        """Build from a dictionary (e.g. loaded from JSON or programmatic)."""
+        behavior = data.get("behavior", data)
+        pipeline = data.get("pipeline", {})
+        generate = pipeline.get("generate", data.get("generate", {}))
+
+        return cls(
+            name=behavior.get("name", "unnamed"),
+            description=behavior.get("description", ""),
+            context=data.get("context", ""),
+            failure_modes=behavior.get("failure_modes", []),
+            target_layer=behavior.get("target_layer", data.get("default_model", {}).get("target_layer", "silver")),
+            backend=behavior.get("backend", data.get("default_model", {}).get("backend", "pyspark")),
+            auto_generate_rules=pipeline.get("policy", {}).get("auto_generate_rules", True),
+            generate_test_cases=generate.get("test_cases", True),
+        )

cfa/behavior/systematizer.py

@@ -0,0 +1,222 @@
+"""
+CFA Systematizer
+================
+Transforms a BehaviorSpec into a BehaviorTaxonomy and optionally
+auto-generates PolicyRules for the CFA Policy Engine.
+
+This is the systematization step: bridge between human-written
+governance intent and executable rules.
+
+Supports two modes:
+- Template-based (MVP, no LLM): maps failure_modes → PolicyRules via conditions
+- LLM-assisted (Phase 6): NL description → behavior spec (future)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cfa.core.conditions import build_condition
+from cfa.policy.engine import PolicyRule
+from cfa.types import (
+    FaultFamily,
+    FaultSeverity,
+    PolicyAction,
+)
+
+from .spec import (
+    BehaviorCategory,
+    BehaviorSpec,
+    BehaviorTaxonomy,
+    ConditionType,
+)
+
+# Re-export for convenience
+try:
+    from .llm import LLMSystematizer, LLMSystematizerBackend  # noqa: F401
+    _HAS_LLM = True
+except ImportError:
+    _HAS_LLM = False
+
+# Map ConditionType enum values to ConditionRegistry names
+_CONDITION_TYPE_MAP: dict[ConditionType, str] = {
+    ConditionType.PII_IN_PROTECTED_LAYER: "pii_in_protected_layer",
+    ConditionType.MISSING_MERGE_KEY: "missing_merge_key",
+    ConditionType.MISSING_PARTITION: "missing_partition",
+    ConditionType.ENFORCE_TYPES_DISABLED: "enforce_types_disabled",
+    ConditionType.PII_WITHOUT_POLICY: "pii_without_policy",
+    ConditionType.SENSITIVE_WITHOUT_PARTITION: "sensitive_without_partition",
+    ConditionType.COST_BUDGET_EXCEEDED: "cost_budget_exceeded",
+    ConditionType.SCHEMA_MISMATCH: "schema_mismatch",
+    ConditionType.SHUFFLE_BUDGET_EXCEEDED: "shuffle_budget_exceeded",
+    ConditionType.UNAUTHORIZED_GOLD_WRITE: "unauthorized_gold_write",
+}
+
+_SEVERITY_MAP: dict[str, FaultSeverity] = {
+    "info": FaultSeverity.INFO,
+    "warning": FaultSeverity.WARNING,
+    "high": FaultSeverity.HIGH,
+    "critical": FaultSeverity.CRITICAL,
+}
+
+_ACTION_MAP: dict[str, PolicyAction] = {
+    "block": PolicyAction.BLOCK,
+    "replan": PolicyAction.REPLAN,
+    "approve": PolicyAction.APPROVE,
+}
+
+
+class Systematizer:
+    """Transforms a BehaviorSpec into a BehaviorTaxonomy and PolicyRules."""
+
+    def systematize(
+        self, spec: BehaviorSpec
+    ) -> tuple[BehaviorTaxonomy, list[PolicyRule]]:
+        """Main entry point: spec → (taxonomy, rules).
+
+        Args:
+            spec: Parsed BehaviorSpec from YAML or programmatic construction.
+
+        Returns:
+            Tuple of (BehaviorTaxonomy, list of PolicyRules).
+        """
+        taxonomy = self._build_taxonomy(spec)
+        rules: list[PolicyRule] = []
+
+        if spec.auto_generate_rules:
+            rules = self._generate_rules(spec, taxonomy)
+
+        return taxonomy, rules
+
+    def systematize_from_nl(
+        self,
+        description: str,
+        *,
+        backend: Any = None,
+        context: str = "",
+        target_layer: str = "silver",
+    ) -> tuple[BehaviorTaxonomy, list[PolicyRule]]:
+        """Natural language → BehaviorTaxonomy + PolicyRules via LLM.
+
+        Requires an LLM backend implementing LLMSystematizerBackend.
+
+        Args:
+            description: NL description of governance requirements.
+            backend: LLM backend instance (e.g. OpenAISystematizerBackend).
+            context: Optional context about the target system.
+            target_layer: Default target layer for generated rules.
+
+        Returns:
+            Tuple of (BehaviorTaxonomy, list of PolicyRules).
+        """
+        from .llm import LLMSystematizer
+
+        llm = LLMSystematizer()
+        spec = llm.systematize_nl(description, backend=backend, context=context)
+        spec.target_layer = target_layer
+        return self.systematize(spec)
+
+    def _build_taxonomy(self, spec: BehaviorSpec) -> BehaviorTaxonomy:
+        allowed: list[BehaviorCategory] = []
+        not_allowed: list[BehaviorCategory] = []
+
+        for mode in spec.failure_modes:
+            code = mode.get("code", "unnamed")
+            label = mode.get("label", code.replace("_", " ").title())
+            description = mode.get("description", "")
+            severity = mode.get("severity", "high")
+
+            condition_str = mode.get("condition", "custom")
+            try:
+                condition_type = ConditionType(condition_str)
+            except ValueError:
+                condition_type = ConditionType.CUSTOM
+
+            category = BehaviorCategory(
+                code=code,
+                label=label,
+                description=description,
+                allowed=False,
+                condition_type=condition_type,
+                severity=severity,
+                remediation=mode.get("remediation", []),
+                metadata={
+                    "target_layer": mode.get("target_layer", spec.target_layer),
+                    "max_dbu": mode.get("max_dbu"),
+                    "min_size_gb": mode.get("min_size_gb", 1.0),
+                    **mode.get("metadata", {}),
+                },
+            )
+            not_allowed.append(category)
+
+        # Implicit allowed behaviors (the inverse of what we test for)
+        # This would be enriched by an LLM in Phase 6
+        allowed.append(
+            BehaviorCategory(
+                code="valid_governed_processing",
+                label="Valid Governed Processing",
+                description=(
+                    "All pipeline operations that respect PII, schema, budget, "
+                    "and partition constraints."
+                ),
+                allowed=True,
+                condition_type=ConditionType.CUSTOM,
+            )
+        )
+
+        return BehaviorTaxonomy(
+            name=spec.name,
+            description=spec.description,
+            context=spec.context,
+            allowed=allowed,
+            not_allowed=not_allowed,
+        )
+
+    def _generate_rules(
+        self, spec: BehaviorSpec, taxonomy: BehaviorTaxonomy
+    ) -> list[PolicyRule]:
+        """Auto-generate PolicyRules from the taxonomy's not_allowed categories."""
+
+        rules: list[PolicyRule] = []
+
+        for category in taxonomy.not_allowed:
+            condition_name = _CONDITION_TYPE_MAP.get(category.condition_type)
+            if condition_name is None:
+                continue
+
+            try:
+                condition_fn = build_condition(condition_name, category.metadata)
+            except KeyError:
+                continue
+
+            severity_enum = _SEVERITY_MAP.get(category.severity, FaultSeverity.HIGH)
+            action_enum = _ACTION_MAP.get(
+                category.metadata.get("action", "replan"), PolicyAction.REPLAN
+            )
+
+            rules.append(
+                PolicyRule(
+                    name=f"behavior_spec_{category.code}",
+                    condition=condition_fn,
+                    action=action_enum,
+                    fault_code=f"BEHAVIOR_{category.code.upper()}",
+                    fault_family=FaultFamily.SEMANTIC,
+                    severity=severity_enum,
+                    message=f"{category.label}: {category.description}",
+                    remediation=tuple(category.remediation),
+                )
+            )
+
+        return rules
+
+    def generate_test_intents(
+        self, spec: BehaviorSpec, count: int = 3
+    ) -> list[str]:
+        """Generate test intent strings that exercise each failure mode.
+
+        Useful for automated governance testing in CI.
+        """
+        taxonomy, _ = self.systematize(spec)
+        if spec.generate_test_cases:
+            return taxonomy.generate_test_intents(count)
+        return []