Source code for transparentmeta.entity.metadata

# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (c) 2025 Transparent Audio
# Author: Valerio Velardo - valerio@transparentaudio.ai

"""
This module defines `Metadata`, the Pydantic model used to represent metadata
in TransparentMeta. It serves as the core entity of the transparentmeta
library. It captures all relevant metadata required for compliance with AI
transparency laws, specifically for generative AI audio companies.
"""

from datetime import datetime
from enum import Enum
from typing import Dict, Optional

from pydantic import BaseModel, Field




class AIUsageLevel(str, Enum):
    """
    Enum representing levels of AI involvement in audio generation.

    Attributes:
        AI_GENERATED: Fully generated by AI with little or no human input.
        AI_ASSISTED: AI/human collaboration, but humans played a significant
            creative role.
        HUMAN_CREATED: Entirely human-made without AI involvement.
    """

    AI_GENERATED = "ai_generated"
    AI_ASSISTED = "ai_assisted"
    HUMAN_CREATED = "human_created"





class Metadata(BaseModel):
    """
    Pydantic model representing metadata for AI-generated audio content.

    This contains the metadata fields necessary to be compliant with AI
    transparency law.

    Attributes:
        company (str): The company responsible for generating the content.
        model (str): The name/version of the AI model used.
        created_at (datetime): Timestamp of content creation.
        ai_usage_level (AIUsageLevel): Degree of AI involvement.
        content_id (str): Unique identifier for the content.
        user_id (str): Identifier for the user who initiated generation.
        private_key_id (str): ID of the private key used to sign the metadata.
        additional_info (Optional[Dict]): Optional dictionary for extended
            metadata. For example:
            {
                "attribution": {
                    "lyrics": "John Doe",
                    "composer": "Jane Smith",
                    "singer": "HAL 9000",
                    ...
                }
            }
    """

    company: str = Field(..., min_length=2, max_length=50)
    model: str = Field(..., min_length=2, max_length=50)
    created_at: datetime
    ai_usage_level: AIUsageLevel
    content_id: str = Field(..., min_length=2, max_length=50)
    user_id: str = Field(..., min_length=2, max_length=50)
    private_key_id: str = Field(..., min_length=2, max_length=50)
    additional_info: Optional[Dict] = None