Entities¶

def __repr__(self) -> str:
    """String representation of the conversation."""
    return (
        f"<Conversation(id={self.id}, name='{self.name}', " f"messages={self.message_count})>"
    )

@hybrid_property
def last_message_time(self) -> Optional[datetime]:
    """Get timestamp of most recent message.

    Returns:
        Last message timestamp, or conversation created_at if no messages.
    """
    if self.messages:
        return max(msg.timestamp for msg in self.messages)
    return self.created_at

@hybrid_property
def message_count(self) -> int:
    """Get total number of messages in this conversation.

    Returns:
        Message count (user + assistant messages).
    """
    return len(self.messages)

@validates("compaction_threshold")
def validate_compaction_threshold(self, key: str, compaction_threshold: int) -> int:
    """Validate the compaction threshold is a whole percent on the scale.

    Args:
        key: Column name ("compaction_threshold").
        compaction_threshold: Percentage to validate.

    Returns:
        Validated percentage.

    Raises:
        ValueError: If it is not an int in COMPACTION_THRESHOLDS (50-90,
            step 5); a bool, a float or a string is rejected.
    """
    if not is_compaction_threshold(compaction_threshold):
        raise ValueError(f"Compaction threshold must be one of {COMPACTION_THRESHOLDS}")
    return compaction_threshold

@validates("max_tokens")
def validate_max_tokens(self, key: str, max_tokens: int) -> int:
    """Validate max_tokens parameter is within allowed range.

    Args:
        key: Column name ("max_tokens").
        max_tokens: Max_tokens value to validate.

    Returns:
        Validated max_tokens value.

    Raises:
        ValueError: If max_tokens not in range [1, 32768].
    """
    if not 1 <= max_tokens <= 32768:
        raise ValueError("Max tokens must be between 1 and 32768")
    return max_tokens

@validates("reasoning_effort")
def validate_reasoning_effort(self, key: str, reasoning_effort: str) -> str:
    """Validate the reasoning effort is one of the five levels.

    Args:
        key: Column name ("reasoning_effort").
        reasoning_effort: Level to validate.

    Returns:
        Validated level.

    Raises:
        ValueError: If the level is not in REASONING_EFFORT_LEVELS.
    """
    if reasoning_effort not in REASONING_EFFORT_LEVELS:
        raise ValueError(f"Reasoning effort must be one of {REASONING_EFFORT_LEVELS}")
    return reasoning_effort

@validates("temperature")
def validate_temperature(self, key: str, temperature: float) -> float:
    """Validate temperature parameter is within allowed range.

    Args:
        key: Column name ("temperature").
        temperature: Temperature value to validate.

    Returns:
        Validated temperature value.

    Raises:
        ValueError: If temperature not in range [0.0, 2.0].
    """
    if not 0.0 <= temperature <= 2.0:
        raise ValueError("Temperature must be between 0.0 and 2.0")
    return temperature

@validates("top_p")
def validate_top_p(self, key: str, top_p: float) -> float:
    """Validate top_p parameter is within allowed range.

    Args:
        key: Column name ("top_p").
        top_p: Top_p value to validate.

    Returns:
        Validated top_p value.

    Raises:
        ValueError: If top_p not in range [0.0, 1.0].
    """
    if not 0.0 <= top_p <= 1.0:
        raise ValueError("Top_p must be between 0.0 and 1.0")
    return top_p

@validates("total_bytes", "total_time_elapsed", "time_left")
def validate_non_negative(self, key, value):
    """Ensure numeric fields are non-negative.

    Args:
        key: Column name being validated (one of: total_bytes, total_time_elapsed, time_left).
        value: Proposed numeric value.

    Returns:
        float: The validated non-negative value.

    Raises:
        ValueError: If value is negative.
    """
    if value < 0:
        raise ValueError(f"{key} must be non-negative, got {value}")
    return value

@validates("remote_model_id", "remote_model_link")
def validate_not_empty(self, key, value):
    """Ensure required string fields are not empty.

    Args:
        key: Column name being validated (one of: remote_model_id, remote_model_link).
        value: Proposed string value.

    Returns:
        str: The validated stripped string value.

    Raises:
        ValueError: If value is empty or whitespace-only.
    """
    if not value or not value.strip():
        raise ValueError(f"{key} cannot be empty")
    return value.strip() if isinstance(value, str) else value

@validates("progress")
def validate_progress(self, key, value):
    """Ensure progress is between 0.0 and 100.0.

    Args:
        key: Column name being validated ('progress').
        value: Proposed float value for download progress percentage.

    Returns:
        float: The validated progress value.

    Raises:
        ValueError: If progress is outside 0.0-100.0 range.
    """
    if not (0.0 <= value <= 100.0):
        raise ValueError(f"Progress must be between 0.0 and 100.0, got {value}")
    return value

@validates("status")
def validate_status(self, key, value):
    """Ensure status is one of the allowed values.

    Args:
        key: Column name being validated ('status').
        value: Proposed string value for job status.

    Returns:
        str: The validated status value.

    Raises:
        ValueError: If status is not in allowed list.
    """
    allowed = ["pending", "running", "completed", "failed", "cancelled"]
    if value not in allowed:
        raise ValueError(f"Invalid status: {value}. Must be one of {allowed}")
    return value

@validates("status")
def validate_status(self, key, value):
    """Ensure status is one of the allowed ingestion states."""
    if value not in ALLOWED_STATUSES:
        raise ValueError(f"Invalid status: {value}. Must be one of {list(ALLOWED_STATUSES)}")
    return value

@validates("artifact_size_bytes")
def validate_artifact_size_bytes(self, key, value):
    """A known artifact size is a positive byte count; None means unknown.

    Zero or negative is never a measurement (an empty directory walk, a
    listing without sizes) and must not masquerade as one -- callers store
    None in that case so the UI keeps its estimate.
    """
    if value is None:
        return None
    if value <= 0:
        raise ValueError(f"artifact_size_bytes must be positive, got {value}")
    return int(value)

@validates("local")
def validate_local(self, key, value):
    """Ensure local is 0 (remote), 1 (ready), or 2 (downloading).

    Args:
        key: Column name being validated ('local').
        value: Proposed integer value for download state.

    Returns:
        int: The validated local state value.

    Raises:
        ValueError: If value is not 0, 1, or 2.
    """
    if value not in [0, 1, 2]:
        raise ValueError(
            f"Invalid local state: {value}. Must be 0 (remote), 1 (ready), or 2 (downloading)"
        )
    return value

@validates("name")
def validate_name(self, key, value):
    """Ensure name is not empty.

    Args:
        key: Column name being validated ('name').
        value: Proposed value for the name field.

    Returns:
        str: Stripped name value if valid.

    Raises:
        ValueError: If name is empty or whitespace-only.
    """
    if not value or not value.strip():
        raise ValueError("LLM name cannot be empty")
    return value.strip()

@validates("param_size")
def validate_param_size(self, key, value):
    """Ensure a known param_size is positive; allow None for unknown (#201).

    Args:
        key: Column name being validated ('param_size').
        value: Proposed float value for parameter size in billions, or None
            when the size could not be measured.

    Returns:
        Optional[float]: The validated parameter size, or None.

    Raises:
        ValueError: If a non-null param_size is zero or negative.
    """
    if value is None:
        return None
    if value <= 0:
        raise ValueError(f"param_size must be positive, got {value}")
    return value

@validates("type")
def validate_type(self, key, value):
    """Ensure type is not empty.

    Args:
        key: Column name being validated ('type').
        value: Proposed string value for model family type.

    Returns:
        str: Stripped type value if valid.

    Raises:
        ValueError: If type is empty or whitespace-only.
    """
    if not value or not value.strip():
        raise ValueError("LLM type cannot be empty")
    return value.strip()

def __repr__(self) -> str:
    """String representation of the message."""
    return (
        f"<Message(id={self.id}, sender='{self.sender}', "
        f"content='{self.content[:50]}...', starred={self.starred})>"
    )

@validates("content")
def validate_content(self, key: str, content: str) -> str:
    """Validate content is non-empty.

    Args:
        key: Column name ("content").
        content: Content value to validate.

    Returns:
        Validated content value.

    Raises:
        ValueError: If content is empty or whitespace-only.
    """
    if not content or len(content.strip()) == 0:
        raise ValueError("Message content cannot be empty")
    return content

@validates("sender")
def validate_sender(self, key: str, sender: str) -> str:
    """Validate sender is either 'user' or 'llm'.

    Args:
        key: Column name ("sender").
        sender: Sender value to validate.

    Returns:
        Validated sender value.

    Raises:
        ValueError: If sender not in ['user', 'llm'].
    """
    if sender not in ["user", "llm"]:
        raise ValueError("Sender must be either 'user' or 'llm'")
    return sender

@validates("welcome_popup_has_already_displayed", "models_seeded", "offline_mode")
def validate_boolean_flags(self, key, value):
    """Ensure boolean flags are actually Boolean type.

    Args:
        key: Column name being validated.
        value: Proposed Boolean value.

    Returns:
        bool: The validated Boolean value.

    Raises:
        ValueError: If value is not a Boolean.

    Example:
        >>> vars.models_seeded = True  # Valid
        >>> vars.models_seeded = "yes"  # Raises ValueError
    """
    if not isinstance(value, bool):
        raise ValueError(f"{key} must be a Boolean, got {type(value)}")
    return value

@validates("web_search_enabled", "auto_update_enabled")
def validate_boolean_flags(self, key, value):
    """Ensure boolean flags are actually Boolean type.

    Args:
        key: Column name being validated.
        value: Proposed Boolean value.

    Returns:
        bool: The validated Boolean value.

    Raises:
        ValueError: If value is not a Boolean.
    """
    if not isinstance(value, bool):
        raise ValueError(f"{key} must be a Boolean, got {type(value)}")
    return value

@validates("default_compaction_threshold")
def validate_default_compaction_threshold(self, key, value):
    """Ensure the global compaction threshold is a whole percent on the scale.

    Raises:
        ValueError: If value is not an int in COMPACTION_THRESHOLDS (a
            bool, a float or a string is rejected).
    """
    if not is_compaction_threshold(value):
        raise ValueError(f"{key} must be one of {COMPACTION_THRESHOLDS}, got {value!r}")
    return value

@validates("default_reasoning_effort")
def validate_default_reasoning_effort(self, key, value):
    """Ensure the global reasoning effort is one of the five levels.

    Raises:
        ValueError: If value is not in REASONING_EFFORT_LEVELS.
    """
    if value not in REASONING_EFFORT_LEVELS:
        raise ValueError(f"{key} must be one of {REASONING_EFFORT_LEVELS}, got {value!r}")
    return value

@validates("inference_backend")
def validate_inference_backend(self, key, value):
    """Ensure the inference backend is one of the supported values.

    Raises:
        ValueError: If value is not in INFERENCE_BACKENDS.
    """
    if value not in INFERENCE_BACKENDS:
        raise ValueError(f"{key} must be one of {INFERENCE_BACKENDS}, got {value!r}")
    return value

@validates("language")
def validate_language(self, key, value):
    """Ensure the language is one of the supported interface languages.

    Raises:
        ValueError: If value is not in SUPPORTED_LANGUAGES.
    """
    if value not in SUPPORTED_LANGUAGES:
        raise ValueError(f"{key} must be one of {SUPPORTED_LANGUAGES}, got {value!r}")
    return value