"""
Pydantic schemas for Principle model JSONFields.

These schemas validate the JSONFields on principle-related models:
- PrincipleDomain.keywords
- Principle.keywords

Usage:
    from lightwave.schema.pydantic.models.principles import (
        KeywordsSchema,
    )

Note: The keywords fields are simple list[str] JSONFields.
This module provides validation and documentation for them.
"""

from pydantic import Field, field_validator

from lightwave.schema.pydantic.core.base import JSONFieldSchema


class KeywordsSchema(JSONFieldSchema):
    """
    Schema for PrincipleDomain.keywords and Principle.keywords JSONFields.

    Keywords for matching user queries to domains/principles.
    Used by v_guru for context matching and search.

    The actual JSONField stores a flat list of strings,
    but this schema provides validation and structure.

    Example:
        ["testing", "tdd", "test-driven", "unit tests", "integration tests"]
    """

    keywords: list[str] = Field(
        default_factory=list,
        description="List of keywords for search and matching",
    )

    @field_validator("keywords")
    @classmethod
    def validate_keywords(cls, v: list[str]) -> list[str]:
        """Ensure keywords are lowercase and stripped."""
        return [kw.lower().strip() for kw in v if kw.strip()]

    @classmethod
    def from_list(cls, keywords: list[str]) -> "KeywordsSchema":
        """Create schema from a flat list of keywords."""
        return cls(keywords=keywords)

    def to_list(self) -> list[str]:
        """Convert back to flat list for JSONField storage."""
        return self.keywords


def validate_keywords_list(keywords: list[str] | None) -> list[str]:
    """
    Validate a keywords list without using the full schema.

    Useful for quick validation in model clean() methods.

    Args:
        keywords: List of keyword strings

    Returns:
        Validated and normalized keyword list
    """
    if not keywords:
        return []
    return [kw.lower().strip() for kw in keywords if isinstance(kw, str) and kw.strip()]
