CLI Components¶

def parse_args() -> argparse.Namespace:
    """
    Parse command line arguments for the anime/manga search and training system.

    This function sets up the argument parser with two main subcommands:

    1. 'search': For finding anime/manga using natural language descriptions
    2. 'train': For training custom cross-encoder models on the datasets

    Each subcommand has its own set of options and arguments. The function handles
    backward compatibility by defaulting to 'search' if no command is provided.

    Returns:
        argparse.Namespace: The parsed and validated command line arguments.
            Contains all the options and arguments specified by the user,
            or their default values if not explicitly provided.

    Notes:
        - For backward compatibility, if no command is provided, 'search' is assumed
        - The 'search' command supports interactive and batch modes
        - The 'train' command has extensive options for model training
        - All arguments are validated by calling validate_args() internally

    Argument Structure:

    ### Common Arguments:
        --type: Dataset type ('anime' or 'manga')
        --model: Model name or path
        --batch-size: Batch size for processing
        --list-models: List available pre-trained models
        --list-fine-tuned: List available fine-tuned models

    ### Search Command Arguments:
        --query: Description to search for
        --results: Number of results to return
        --interactive (-i): Enter interactive mode
        --include-light-novels: Include light novels in manga results

    ### Train Command Arguments:
        --epochs: Number of training epochs
        --eval-steps: Steps between evaluations
        --learning-rate: Learning rate for training
        --max-samples: Maximum number of training samples
        --labeled-data: Path to labeled data CSV
        --create-labeled-data: Create synthetic labeled data
        --seed: Random seed for reproducibility
        --loss: Loss function for training
        --scheduler: Learning rate scheduler

    Example:
        ```python
        # Parse arguments and use them
        args = parse_args()

        if args.command == 'search':
            # Handle search command
            if args.interactive:
                # Run interactive mode
                pass
            else:
                # Run single query search
                pass

        elif args.command == 'train':
            # Handle train command
            pass
        ```
    """
    parser = argparse.ArgumentParser(
        description="Anime/Manga Description Search Model using Cross-Encoders"
    )

    # Add subparsers for search and train commands
    subparsers = parser.add_subparsers(dest="command", help="Command to run")

    # Create the parser for the "search" command
    search_parser = subparsers.add_parser(
        "search", help="Search for anime/manga by description"
    )
    search_parser.add_argument(
        "--type",
        type=str,
        choices=["anime", "manga"],
        required=False,
        help="Type of dataset to search ('anime' or 'manga')",
    )
    search_parser.add_argument(
        "--query", type=str, help="Description query to search for"
    )
    search_parser.add_argument(
        "--model",
        type=str,
        default=MODEL_NAME,
        help=f"Name of the model to use (default: {MODEL_NAME})",
    )
    search_parser.add_argument(
        "--results",
        type=int,
        default=NUM_RESULTS,
        help=f"Number of results to return (default: {NUM_RESULTS})",
    )
    search_parser.add_argument(
        "--batch-size",
        type=int,
        default=DEFAULT_BATCH_SIZE,
        help=f"Batch size for processing (default: {DEFAULT_BATCH_SIZE})",
    )
    search_parser.add_argument(
        "--interactive",
        "-i",
        action="store_true",
        help="Enter interactive mode for continuous queries",
    )
    search_parser.add_argument(
        "--list-models",
        action="store_true",
        help="List available pre-trained cross-encoder models and exit",
    )
    search_parser.add_argument(
        "--list-fine-tuned",
        action="store_true",
        help="List available fine-tuned along with pre-trained models and exit",
    )
    search_parser.add_argument(
        "--include-light-novels",
        action="store_true",
        help="Include light novels in manga search results (manga only)",
    )

    # Create the parser for the "train" command
    train_parser = subparsers.add_parser(
        "train", help="Train a custom cross-encoder model"
    )
    train_parser.add_argument(
        "--type",
        type=str,
        choices=["anime", "manga"],
        required=False,
        help="Type of dataset to train on ('anime' or 'manga')",
    )
    train_parser.add_argument(
        "--model",
        type=str,
        default=MODEL_NAME,
        help=f"Base cross-encoder model to fine-tune (default: {MODEL_NAME})",
    )
    train_parser.add_argument(
        "--epochs",
        type=int,
        default=3,
        help="Number of training epochs (default: 3)",
    )
    train_parser.add_argument(
        "--batch-size",
        type=int,
        default=16,
        help="Training batch size (default: 16)",
    )
    train_parser.add_argument(
        "--eval-steps",
        type=int,
        default=500,
        help="Steps between evaluations (default: 500)",
    )
    train_parser.add_argument(
        "--learning-rate",
        type=float,
        default=2e-6,
        help="Learning rate (default: 2e-6)",
    )
    train_parser.add_argument(
        "--max-samples",
        type=int,
        default=10000,
        help="Maximum number of training samples (default: 10000)",
    )
    train_parser.add_argument(
        "--labeled-data", type=str, help="Path to labeled data CSV file (if available)"
    )
    train_parser.add_argument(
        "--create-labeled-data",
        type=str,
        help="Create and save synthetic labeled data to the specified CSV path",
    )
    train_parser.add_argument(
        "--seed",
        type=int,
        default=42,
        help="Random seed for reproducibility (default: 42)",
    )
    train_parser.add_argument(
        "--list-models",
        action="store_true",
        help="List available base models for fine-tuning",
    )
    train_parser.add_argument(
        "--list-fine-tuned",
        action="store_true",
        help="List available fine-tuned along with pre-trained models and exit",
    )
    train_parser.add_argument(
        "--loss",
        type=str,
        choices=[
            "binary_cross_entropy",
            "cross_entropy",
            "lambda",
            "list_mle",
            "p_list_mle",
            "list_net",
            "multiple_negatives_ranking",
            "cached_multiple_negatives_ranking",
            "mse",
            "margin_mse",
            "rank_net",
        ],
        default="mse",
        help="Loss function to use for training",
    )
    train_parser.add_argument(
        "--scheduler",
        type=str,
        choices=[
            "linear",
            "cosine",
            "cosine_with_restarts",
            "polynomial",
            "constant",
            "constant_with_warmup",
            "inverse_sqrt",
            "reduce_lr_on_plateau",
            "cosine_with_min_lr",
            "warmup_stable_decay",
        ],
        default="linear",
        help="Learning rate scheduler",
    )
    train_parser.add_argument(
        "--include-light-novels",
        action="store_true",
        default=True,
        help="Include light novels in manga training data (manga only)",
    )

    # Set default command to "search" for backward compatibility
    if len(sys.argv) == 1 or (len(sys.argv) > 1 and sys.argv[1][0] == "-"):
        sys.argv.insert(1, "search")

    args = parser.parse_args()
    return validate_args(args)

def validate_args(args: argparse.Namespace) -> argparse.Namespace:
    """
    Validate command line arguments for consistency and correctness.

    This function ensures that argument combinations are valid and compatible.
    It performs checks such as:

    1. Ensuring the 'type' argument is provided when required
    2. Validating that certain arguments are only used with appropriate dataset types
       (e.g., --include-light-novels only with manga datasets)

    Args:
        args: The parsed command line arguments to validate.
            This is typically the output from argparse.ArgumentParser.parse_args().

    Returns:
        argparse.Namespace: The validated arguments, unchanged if validation passes.

    Raises:
        SystemExit: If validation fails, the program exits with an error message.
            The error message is printed to stderr before exiting.

    Notes:
        - This function is called automatically by parse_args()
        - Some validation rules are specific to certain commands or dataset types
        - The function provides user-friendly error messages to help diagnose issues

    Example:
        ```python
        parser = argparse.ArgumentParser()
        # Add arguments...
        args = parser.parse_args()
        validated_args = validate_args(args)
        # Use validated_args safely...
        ```
    """
    # Check if type is required but missing
    if not (hasattr(args, "list_models") and args.list_models) and not (
        hasattr(args, "list_fine_tuned") and args.list_fine_tuned
    ):
        if not hasattr(args, "type") or not args.type:
            print(
                "Error: --type is required when not listing models",
                file=sys.stderr,
            )
            sys.exit(1)

    # Validate that --include-light-novels is only used with manga dataset type
    if (
        hasattr(args, "include_light_novels")
        and args.include_light_novels
        and hasattr(args, "type")
        and args.type
        and args.type.lower() != "manga"
    ):
        print(
            "Error: --include-light-novels can only be used with --type manga",
            file=sys.stderr,
        )
        sys.exit(1)

    return args

def interactive_mode(
    search_model: BaseSearchModel,
    num_results: int,
    batch_size: int,
) -> None:
    """
    Run the search model in an interactive command-line session.

    This function starts an interactive search session where users can repeatedly
    enter queries and see results until they choose to exit. It handles the input
    loop, input validation, search execution, and session termination.

    The interactive session continues until the user types 'exit' or 'quit'.
    Each valid query is processed by the search_and_display_results function,
    which executes the search and formats the output.

    Args:
        search_model: An initialized search model instance that will perform the searches.
            This determines whether anime or manga content will be searched.
        num_results: The maximum number of results to return for each query.
            This value is passed to search_and_display_results for each search.
        batch_size: The batch size to use when processing search pairs with the model.
            This value is passed to search_and_display_results for each search.

    Returns:
        None: This function runs an interactive session but doesn't return any values.

    Example:
        ```python
        from src.models.anime_search_model import AnimeSearchModel

        # Initialize a search model
        model = AnimeSearchModel()

        # Start interactive mode with 5 results per query
        interactive_mode(model, num_results=5, batch_size=32)
        ```

    Notes:
        - Empty queries are validated and rejected with a message
        - The function displays which type of dataset is being searched (anime/manga)
        - Error handling for the search process is managed by search_and_display_results
    """
    print(
        f"\nAnime/Manga Search Model - Interactive Mode ({search_model.dataset_type})"
    )
    print("Type 'exit' or 'quit' to end the session\n")

    while True:
        query = input("\nEnter a description to search for: ")
        if query.lower() in ["exit", "quit"]:
            break

        if not query.strip():
            print("Please enter a valid description")
            continue

        search_and_display_results(search_model, query, num_results, batch_size)

@handle_exceptions(cli_mode=True, reraise=False)
def search_and_display_results(
    search_model: BaseSearchModel,
    query: str,
    num_results: int,
    batch_size: int,
) -> None:
    """
    Execute a search query and display formatted results to the console.

    This function performs a semantic search using the provided search model and
    displays the results in a user-friendly format. It formats each result with
    a title, ID, normalized score, and synopsis excerpt.

    The function is decorated with error handling to gracefully handle any exceptions
    that might occur during the search process or result formatting.

    Args:
        search_model: An initialized search model instance that will perform the search.
            This can be any class that extends BaseSearchModel (like AnimeSearchModel
            or MangaSearchModel).
        query: The text description or query to search for. This should be a natural
            language description of the content the user is looking for.
        num_results: The maximum number of results to return and display.
            This determines how many top matches will be shown to the user.
        batch_size: The batch size to use when processing search pairs with the model.
            Larger batch sizes can improve performance but require more memory.

    Returns:
        None: This function prints results to the console but does not return any values.

    Notes:
        - The function truncates synopsis excerpts to 200 characters for display
        - Scores are formatted differently based on the model type using the format_score utility
        - Results are numbered starting from 1 for user-friendly display
        - Error handling is provided by the @handle_exceptions decorator
    """
    results = search_model.search(
        query,
        num_results=num_results,
        batch_size=batch_size,
    )

    print("\nTop matches:")
    for i, result in enumerate(results):
        synopsis_excerpt = (
            result["synopsis"][:200] + "..."
            if len(result["synopsis"]) > 200
            else result["synopsis"]
        )
        score_display = format_score(
            result["score"],
            search_model.normalize_scores,
            search_model.model_name,
        )
        print(f"\n{i + 1}. {result['title']} ({score_display})")
        print(f"   ID: {result['id']}")
        print(f"   Synopsis excerpt: {synopsis_excerpt}")