# Import file and text utilities
from pathlib import Path
import hashlib
import html
import json
import re
import unicodedata
import platform
import importlib.metadata
from time import perf_counter

# Import data and plotting libraries
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import joblib

# Import feature and model tools
from sklearn.model_selection import train_test_split
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.dummy import DummyClassifier
from sklearn.naive_bayes import MultinomialNB
from sklearn.linear_model import LogisticRegression

# Import evaluation tools
from sklearn.metrics import (
    accuracy_score, balanced_accuracy_score, f1_score,
    precision_score, recall_score, roc_auc_score,
    log_loss, brier_score_loss, confusion_matrix, classification_report,
    RocCurveDisplay, PrecisionRecallDisplay,
)
from sklearn.calibration import calibration_curve

# Set the data and output paths
DATA_PATH = Path('IMDB Dataset.csv')
OUTPUT_DIR = Path('artifacts')
OUTPUT_DIR.mkdir(exist_ok=True)
if not DATA_PATH.is_file():
    raise FileNotFoundError('Place IMDB Dataset.csv beside the notebook or edit DATA_PATH.')

# Set reproducible experiment choices
RANDOM_STATE = 42
TFIDF_MAX_FEATURES = 50_000
LOGISTIC_C_VALUES = [0.25, 1.0, 4.0]
BOOTSTRAP_REPEATS = 1_000
RUN_NEURAL = False
MAX_LENGTH = 256
NEURAL_VOCAB_SIZE = 15_000
NEURAL_EPOCHS = 10
NEURAL_BATCH_SIZE = 128
np.random.seed(RANDOM_STATE)

# Set a readable visual style
NAVY, SCARLET, SLATE = '#16324F', '#FF2400', '#667582'
plt.rcParams.update({
    'figure.figsize': (8, 4), 'figure.dpi': 120,
    'axes.spines.top': False, 'axes.spines.right': False,
    'axes.titleweight': 'bold', 'axes.labelcolor': NAVY,
    'text.color': NAVY, 'font.size': 10,
})
pd.set_option('display.max_colwidth', 180)

# Record the source fingerprint
source_sha256 = hashlib.sha256(DATA_PATH.read_bytes()).hexdigest()
print('Dataset SHA-256:', source_sha256)
print(f'Dataset size: {DATA_PATH.stat().st_size / 1_000_000:.2f} MB')

# Read the CSV
raw = pd.read_csv(DATA_PATH, dtype={'review': 'string', 'sentiment': 'string'})
raw.index.name = 'source_row'
print(f'Loaded {len(raw):,} rows and {raw.shape[1]} columns.')

# Check the required schema
required_columns = {'review', 'sentiment'}
if not required_columns.issubset(raw.columns):
    raise ValueError(f'Required columns: {sorted(required_columns)}')
if raw[list(required_columns)].isna().any().any():
    raise ValueError('Review or sentiment is missing; investigate before modelling.')
display(raw.dtypes.rename('dtype').to_frame())

# Validate the target labels
raw['sentiment'] = raw['sentiment'].str.strip().str.lower()
unexpected_labels = set(raw['sentiment'].unique()) - {'negative', 'positive'}
if unexpected_labels:
    raise ValueError(f'Unexpected sentiment labels: {unexpected_labels}')
display(raw['sentiment'].value_counts().rename('reviews').to_frame())

# Audit raw duplicates
raw_duplicate_rows = int(raw.duplicated(['review', 'sentiment']).sum())
raw_duplicate_texts = int(raw.duplicated('review').sum())
raw_conflicts = int(raw.groupby('review')['sentiment'].nunique().gt(1).sum())
print(f'Exact duplicate rows: {raw_duplicate_rows:,}')
print(f'Repeated raw reviews: {raw_duplicate_texts:,}; conflicting raw texts: {raw_conflicts:,}')

# Define minimal text normalisation
def normalise_text(text):
    text = unicodedata.normalize('NFKC', html.unescape(str(text)))
    text = text.replace('’', "'").lower()
    text = re.sub(r'<[^>]*>', ' ', text)
    text = re.sub(r"[^a-z0-9'\s]", ' ', text)
    return re.sub(r'\s+', ' ', text).strip()

# Build the normalised text column
data = raw.reset_index().copy()
data['text'] = data['review'].map(normalise_text)
print('Example:', data['text'].iloc[0][:180] + '…')

# Find empty and conflicting normalised reviews
empty_mask = data['text'].eq('')
conflict_texts = data.groupby('text')['sentiment'].nunique()
conflict_texts = conflict_texts[conflict_texts > 1].index
conflict_mask = data['text'].isin(conflict_texts)
normalised_duplicate_rows = int(data.duplicated('text').sum())
print(f'Empty texts: {empty_mask.sum():,}')
print(f'Conflicting text groups: {len(conflict_texts):,}; affected rows: {conflict_mask.sum():,}')
print(f'Repeated normalised texts: {normalised_duplicate_rows:,}')

# Quarantine invalid text rows
quarantine_mask = empty_mask | conflict_mask
quarantined_rows = int(quarantine_mask.sum())
eligible = data.loc[~quarantine_mask].copy()
print(f'Quarantined rows: {quarantined_rows:,}')

# Remove repeated model inputs
duplicates_removed = int(eligible.duplicated('text').sum())
clean = eligible.drop_duplicates('text', keep='first').copy()
clean = clean.reset_index(drop=True)
assert len(raw) == quarantined_rows + duplicates_removed + len(clean)
print(f'Removed {duplicates_removed:,} repeated reviews; retained {len(clean):,} unique reviews.')

# Encode the target
label_map = {'negative': 0, 'positive': 1}
clean['label'] = clean['sentiment'].map(label_map).astype('int8')
display(clean['sentiment'].value_counts().rename('unique_reviews').to_frame())

# Assign a stable review identifier
clean['review_id'] = clean['text'].map(lambda text: hashlib.sha256(text.encode()).hexdigest())
assert clean['review_id'].is_unique
print('All retained review IDs are unique.')

# Reserve the final test set
development_df, test_df = train_test_split(
    clean, test_size=0.20, random_state=RANDOM_STATE, stratify=clean['label'],
)

# Separate training and validation
train_df, val_df = train_test_split(
    development_df, test_size=0.25, random_state=RANDOM_STATE,
    stratify=development_df['label'],
)
train_df, val_df, test_df = [frame.reset_index(drop=True) for frame in (train_df, val_df, test_df)]

# Verify partition independence
train_ids, val_ids, test_ids = [set(frame['review_id']) for frame in (train_df, val_df, test_df)]
assert train_ids.isdisjoint(val_ids)
assert train_ids.isdisjoint(test_ids)
assert val_ids.isdisjoint(test_ids)
assert len(train_df) + len(val_df) + len(test_df) == len(clean)
print('No normalised review overlaps train, validation or test.')

# Report the development split
development_summary = pd.DataFrame({
    'rows': [len(train_df), len(val_df)],
    'negative': [train_df['label'].eq(0).sum(), val_df['label'].eq(0).sum()],
    'positive': [train_df['label'].eq(1).sum(), val_df['label'].eq(1).sum()],
}, index=['training', 'validation'])
display(development_summary)
print(f'Reserved test rows: {len(test_df):,}; not used for feature fitting or selection.')

# Create the target arrays
y_train = train_df['label'].to_numpy()
y_val = val_df['label'].to_numpy()
y_test = test_df['label'].to_numpy()

# Count training review lengths
train_word_count = train_df['text'].str.split().str.len()
display(train_word_count.describe(percentiles=[0.50, 0.90, 0.95]).round(1).to_frame('words'))

# Plot the training class balance
fig, ax = plt.subplots(figsize=(6, 3.5))
counts = train_df['sentiment'].value_counts().reindex(['negative', 'positive'])
ax.bar(counts.index, counts.values, color=[SCARLET, NAVY])
ax.set(title='Training reviews by sentiment', ylabel='Number of unique reviews')
ax.bar_label(ax.containers[0], fmt='%d', padding=3)
fig.tight_layout()
plt.show()

# Plot the review length distribution
fig, ax = plt.subplots()
ax.hist(train_word_count, bins=60, color=NAVY)
ax.axvline(MAX_LENGTH, color=SCARLET, label=f'Neural limit: {MAX_LENGTH} words')
ax.set(xlim=(0, 1_000), xlabel='Words after cleaning', ylabel='Training reviews',
       title='Training review lengths (view limited to 1,000 words)')
ax.legend()
fig.tight_layout()
plt.show()

# Measure the planned truncation rate
truncation_rate = float(train_word_count.gt(MAX_LENGTH).mean())
print(f'{truncation_rate:.1%} of training reviews exceed the optional {MAX_LENGTH}-word limit.')
print('Sequence models would discard later words; TF-IDF does not impose this length limit.')

# Define the TF-IDF representation
vectorizer = TfidfVectorizer(
    max_features=TFIDF_MAX_FEATURES, ngram_range=(1, 2), min_df=2,
    sublinear_tf=True, lowercase=False, stop_words=None,
    token_pattern=r"(?u)\b\w[\w']+\b", dtype=np.float32,
)

# Fit features on training reviews only
feature_start = perf_counter()
X_train = vectorizer.fit_transform(train_df['text'])
feature_fit_seconds = perf_counter() - feature_start
print(f'Training matrix: {X_train.shape}; nonzero entries: {X_train.nnz:,}')
print(f'Feature fitting took {feature_fit_seconds:.2f} seconds on this machine.')

# Transform validation reviews
X_val = vectorizer.transform(val_df['text'])
assert X_train.shape[1] == X_val.shape[1]
print('Validation matrix:', X_val.shape)

# Inspect a few vocabulary features
feature_names = vectorizer.get_feature_names_out()
display(pd.DataFrame({'example_feature': feature_names[:15]}))

# Define one consistent metric summary
def metric_summary(name, truth, positive_score):
    prediction = (np.asarray(positive_score) >= 0.5).astype(int)
    return {
        'model': name,
        'accuracy': accuracy_score(truth, prediction),
        'balanced_accuracy': balanced_accuracy_score(truth, prediction),
        'macro_f1': f1_score(truth, prediction, average='macro', zero_division=0),
        'negative_precision': precision_score(truth, prediction, pos_label=0, zero_division=0),
        'negative_recall': recall_score(truth, prediction, pos_label=0, zero_division=0),
        'roc_auc': roc_auc_score(truth, positive_score),
        'log_loss': log_loss(truth, positive_score, labels=[0, 1]),
        'brier_score': brier_score_loss(truth, positive_score),
    }

# Fit the majority baseline
majority_model = DummyClassifier(strategy='prior', random_state=RANDOM_STATE)
majority_model.fit(X_train, y_train)
majority_val_score = majority_model.predict_proba(X_val)[:, 1]
display(pd.DataFrame([metric_summary('Majority baseline', y_val, majority_val_score)]).round(4))

# Fit the Naive Bayes baseline
start = perf_counter()
nb_model = MultinomialNB(alpha=1.0).fit(X_train, y_train)
nb_fit_seconds = perf_counter() - start
nb_val_score = nb_model.predict_proba(X_val)[:, 1]
display(pd.DataFrame([metric_summary('TF-IDF + Naive Bayes', y_val, nb_val_score)]).round(4))

# Fit the declared logistic candidates
logistic_models, tuning_rows = {}, []
for c_value in LOGISTIC_C_VALUES:
    candidate = LogisticRegression(C=c_value, solver='liblinear', max_iter=300,
                                   random_state=RANDOM_STATE)
    start = perf_counter()
    candidate.fit(X_train, y_train)
    score = candidate.predict_proba(X_val)[:, 1]
    row = metric_summary(f'C={c_value}', y_val, score)
    row.update(C=c_value, fit_seconds=perf_counter() - start)
    logistic_models[c_value] = candidate
    tuning_rows.append(row)
tuning_results = pd.DataFrame(tuning_rows)

# Choose logistic regularisation on validation
tuning_results = tuning_results.sort_values(['macro_f1', 'log_loss', 'C'],
                                            ascending=[False, True, True])
best_c = float(tuning_results.iloc[0]['C'])
logistic_model = logistic_models[best_c]
logistic_val_score = logistic_model.predict_proba(X_val)[:, 1]
display(tuning_results.round(4))
print(f'Locked logistic C: {best_c:g}')

# Register the classical comparison models
core_models = {
    'Majority baseline': majority_model,
    'TF-IDF + Naive Bayes': nb_model,
    'TF-IDF + Logistic Regression': logistic_model,
}
validation_scores = {
    name: model.predict_proba(X_val)[:, 1] for name, model in core_models.items()
}
neural_models, neural_histories = {}, {}

# Report whether neural training is enabled
tf = None
if RUN_NEURAL:
    import tensorflow as tf
    tf.keras.utils.set_random_seed(RANDOM_STATE)
    print('TensorFlow version:', tf.__version__)
else:
    print('Neural experiments: NOT RUN. Core comparisons below are fully executed.')

# Create the neural text vectorizer
if RUN_NEURAL:
    neural_vectorizer = tf.keras.layers.TextVectorization(
        max_tokens=NEURAL_VOCAB_SIZE, standardize=None,
        output_mode='int', output_sequence_length=MAX_LENGTH,
    )

# Learn the neural vocabulary from training only
if RUN_NEURAL:
    vocabulary_data = tf.data.Dataset.from_tensor_slices(train_df['text'].to_numpy()).batch(256)
    neural_vectorizer.adapt(vocabulary_data)
    neural_vocab_size = len(neural_vectorizer.get_vocabulary())
    print('Neural vocabulary size, including special tokens:', neural_vocab_size)

# Encode the training sequences
if RUN_NEURAL:
    train_tokens = neural_vectorizer(train_df['text'].to_numpy()).numpy()
    print('Training token shape:', train_tokens.shape)

# Encode the validation sequences
if RUN_NEURAL:
    val_tokens = neural_vectorizer(val_df['text'].to_numpy()).numpy()
    print('Validation token shape:', val_tokens.shape)

# Prepare the neural training batches
if RUN_NEURAL:
    neural_train_data = tf.data.Dataset.from_tensor_slices((train_tokens, y_train.astype('float32')))
    neural_train_data = neural_train_data.shuffle(len(y_train), seed=RANDOM_STATE)
    neural_train_data = neural_train_data.batch(NEURAL_BATCH_SIZE).prefetch(tf.data.AUTOTUNE)
    neural_val_data = tf.data.Dataset.from_tensor_slices((val_tokens, y_val.astype('float32')))
    neural_val_data = neural_val_data.batch(NEURAL_BATCH_SIZE).prefetch(tf.data.AUTOTUNE)

# Define a fresh neural stopping rule
if RUN_NEURAL:
    def neural_callbacks():
        return [tf.keras.callbacks.EarlyStopping(
            monitor='val_loss', patience=2, restore_best_weights=True,
        )]

# Build the average-pooling network
if RUN_NEURAL:
    tf.keras.utils.set_random_seed(RANDOM_STATE)
    pool_model = tf.keras.Sequential([
        tf.keras.Input(shape=(MAX_LENGTH,), dtype='int32'),
        tf.keras.layers.Embedding(neural_vocab_size, 32, mask_zero=True),
        tf.keras.layers.GlobalAveragePooling1D(),
        tf.keras.layers.Dense(16, activation='relu'),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(1, activation='sigmoid'),
    ], name='embedding_average_pooling')
    pool_model.summary()

# Compile the pooling network
if RUN_NEURAL:
    pool_model.compile(optimizer=tf.keras.optimizers.Adam(0.001, clipnorm=1.0),
                       loss='binary_crossentropy', metrics=['accuracy'])

# Train the pooling network
if RUN_NEURAL:
    pool_history = pool_model.fit(neural_train_data, validation_data=neural_val_data,
                                  epochs=NEURAL_EPOCHS, callbacks=neural_callbacks(), verbose=2)
    neural_models['Embedding + average pooling'] = pool_model
    neural_histories['Embedding + average pooling'] = pool_history.history

# Build the SimpleRNN network
if RUN_NEURAL:
    tf.keras.utils.set_random_seed(RANDOM_STATE)
    rnn_model = tf.keras.Sequential([
        tf.keras.Input(shape=(MAX_LENGTH,), dtype='int32'),
        tf.keras.layers.Embedding(neural_vocab_size, 32, mask_zero=True),
        tf.keras.layers.SimpleRNN(32, activation='tanh'),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(1, activation='sigmoid'),
    ], name='simple_rnn')
    rnn_model.summary()

# Compile the SimpleRNN network
if RUN_NEURAL:
    rnn_model.compile(optimizer=tf.keras.optimizers.Adam(0.001, clipnorm=1.0),
                      loss='binary_crossentropy', metrics=['accuracy'])

# Train the SimpleRNN network
if RUN_NEURAL:
    rnn_history = rnn_model.fit(neural_train_data, validation_data=neural_val_data,
                                epochs=NEURAL_EPOCHS, callbacks=neural_callbacks(), verbose=2)
    neural_models['Embedding + SimpleRNN'] = rnn_model
    neural_histories['Embedding + SimpleRNN'] = rnn_history.history

# Build the LSTM network
if RUN_NEURAL:
    tf.keras.utils.set_random_seed(RANDOM_STATE)
    lstm_model = tf.keras.Sequential([
        tf.keras.Input(shape=(MAX_LENGTH,), dtype='int32'),
        tf.keras.layers.Embedding(neural_vocab_size, 32, mask_zero=True),
        tf.keras.layers.LSTM(32),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(1, activation='sigmoid'),
    ], name='lstm')
    lstm_model.summary()

# Compile the LSTM network
if RUN_NEURAL:
    lstm_model.compile(optimizer=tf.keras.optimizers.Adam(0.001, clipnorm=1.0),
                       loss='binary_crossentropy', metrics=['accuracy'])

# Train the LSTM network
if RUN_NEURAL:
    lstm_history = lstm_model.fit(neural_train_data, validation_data=neural_val_data,
                                  epochs=NEURAL_EPOCHS, callbacks=neural_callbacks(), verbose=2)
    neural_models['Embedding + LSTM'] = lstm_model
    neural_histories['Embedding + LSTM'] = lstm_history.history

# Compare neural training curves
if RUN_NEURAL:
    fig, ax = plt.subplots()
    for name, history in neural_histories.items():
        epochs = np.arange(1, len(history['loss']) + 1)
        ax.plot(epochs, history['val_loss'], label=name)
    ax.set(xlabel='Epoch', ylabel='Validation binary cross-entropy',
           title='Neural validation learning curves')
    ax.legend()
    fig.tight_layout()
    plt.show()

# Register neural validation predictions
if RUN_NEURAL:
    for name, model in neural_models.items():
        validation_scores[name] = model.predict(val_tokens, verbose=0).ravel()

# Compare all executed models on validation
validation_results = pd.DataFrame([
    metric_summary(name, y_val, score) for name, score in validation_scores.items()
]).sort_values(['macro_f1', 'log_loss', 'model'], ascending=[False, True, True])
display(validation_results.round(4))

# Lock the selected model
selected_name = str(validation_results.iloc[0]['model'])
core_ranking = validation_results[validation_results['model'].isin(core_models)]
best_core_name = str(core_ranking.iloc[0]['model'])
best_core_model = core_models[best_core_name]
print('Model selected on validation:', selected_name)
print('Best classical model:', best_core_name)

# Define the negative-feedback cost calculation
def triage_summary(truth, positive_score, threshold):
    is_negative = np.asarray(truth) == 0
    flagged = (1 - np.asarray(positive_score)) >= threshold
    caught = int((is_negative & flagged).sum())
    missed = int((is_negative & ~flagged).sum())
    false_alerts = int((~is_negative & flagged).sum())
    return {
        'threshold': float(threshold), 'flagged': int(flagged.sum()),
        'negative_recall': caught / max(int(is_negative.sum()), 1),
        'negative_precision': caught / max(int(flagged.sum()), 1),
        'missed_negatives': missed, 'false_alerts': false_alerts,
        'relative_cost_units': 5 * missed + false_alerts,
    }

# Evaluate declared thresholds on validation
threshold_grid = np.round(np.arange(0.10, 0.91, 0.05), 2)
threshold_results = pd.DataFrame([
    triage_summary(y_val, validation_scores[selected_name], threshold)
    for threshold in threshold_grid
])
display(threshold_results.round(4))

# Lock the illustrative triage threshold
threshold_results['distance_from_half'] = (threshold_results['threshold'] - 0.5).abs()
threshold_choice = threshold_results.sort_values(
    ['relative_cost_units', 'distance_from_half', 'threshold']
).iloc[0]
triage_threshold = float(threshold_choice['threshold'])
locked_plan = {'selected_model': selected_name, 'logistic_C': best_c,
               'classification_threshold_positive': 0.5,
               'triage_threshold_negative': triage_threshold,
               'missed_negative_cost_units': 5, 'false_alert_cost_units': 1}
print(json.dumps(locked_plan, indent=2))

# Plot the validation threshold trade-off
fig, ax = plt.subplots()
ax.plot(threshold_results['threshold'], threshold_results['relative_cost_units'], color=NAVY)
ax.axvline(triage_threshold, color=SCARLET, label=f'Locked threshold: {triage_threshold:.2f}')
ax.set(xlabel='Threshold for negative-review flag', ylabel='Relative error-cost units',
       title='Illustrative triage cost on validation only')
ax.legend()
fig.tight_layout()
plt.show()

# Transform the sealed test reviews
X_test = vectorizer.transform(test_df['text'])
print('Final test matrix:', X_test.shape)

# Make final classical predictions
test_scores, prediction_seconds = {}, {}
for name, model in core_models.items():
    start = perf_counter()
    test_scores[name] = model.predict_proba(X_test)[:, 1]
    prediction_seconds[name] = perf_counter() - start

# Make final neural predictions when enabled
if RUN_NEURAL:
    test_tokens = neural_vectorizer(test_df['text'].to_numpy()).numpy()
    for name, model in neural_models.items():
        start = perf_counter()
        test_scores[name] = model.predict(test_tokens, verbose=0).ravel()
        prediction_seconds[name] = perf_counter() - start

# Check prediction integrity
for name, score in test_scores.items():
    assert score.shape == y_test.shape, name
    assert np.isfinite(score).all(), name
    assert ((score >= 0) & (score <= 1)).all(), name
print('All executed models returned one valid score per held-out review.')

# Build the final comparison table
test_results = pd.DataFrame([
    metric_summary(name, y_test, score) for name, score in test_scores.items()
])
test_results['prediction_seconds_without_preprocessing'] = test_results['model'].map(prediction_seconds)
display(test_results.round(4))

# Interpret the selected result
selected_row = test_results.set_index('model').loc[selected_name]
selected_score = test_scores[selected_name]
selected_prediction = (selected_score >= 0.5).astype(int)
print(f'Validation selected {selected_name}.')
print(f'On {len(y_test):,} held-out reviews: accuracy {selected_row.accuracy:.2%}; '
      f'macro F1 {selected_row.macro_f1:.4f}.')
print(f'At the default 0.5 rule it caught {selected_row.negative_recall:.2%} of negative '
      f'reviews; negative precision was {selected_row.negative_precision:.2%}.')
print('These are local held-out results, not official benchmark or deployment scores.')

# Plot test macro F1
fig, ax = plt.subplots(figsize=(8, 4))
chart_data = test_results.set_index('model')['macro_f1'].sort_values()
ax.barh(chart_data.index, chart_data.values,
        color=[SCARLET if name == selected_name else NAVY for name in chart_data.index])
ax.set(xlim=(0, 1), xlabel='Macro F1 (0 to 1)', title='Held-out comparison at the fixed 0.5 rule')
ax.bar_label(ax.containers[0], fmt='%.3f', padding=3)
fig.tight_layout()
plt.show()

# Show the selected classification report
class_report = pd.DataFrame(classification_report(
    y_test, selected_prediction, labels=[0, 1], target_names=['negative', 'positive'],
    output_dict=True, zero_division=0,
)).T
display(class_report.round(4))

# Count the selected model’s errors
selected_cm = confusion_matrix(y_test, selected_prediction, labels=[0, 1])
display(pd.DataFrame(selected_cm, index=['actual negative', 'actual positive'],
                     columns=['predicted negative', 'predicted positive']))
assert int(selected_cm.sum()) == len(y_test)
assert np.isclose(np.trace(selected_cm) / selected_cm.sum(), selected_row.accuracy)

# Plot the confusion matrix
fig, ax = plt.subplots(figsize=(5, 4))
ax.imshow(selected_cm, cmap='Blues')
for (row, column), count in np.ndenumerate(selected_cm):
    ax.text(column, row, f'{count:,}', ha='center', va='center',
            color='white' if count > selected_cm.max() / 2 else NAVY, fontsize=13)
ax.set(xticks=[0, 1], yticks=[0, 1], xticklabels=['Negative', 'Positive'],
       yticklabels=['Negative', 'Positive'], xlabel='Predicted sentiment',
       ylabel='Actual sentiment', title='Selected model: held-out errors')
fig.tight_layout()
plt.show()

# Explain the error counts in words
true_negative, missed_negative = selected_cm[0]
false_alert, true_positive = selected_cm[1]
print(f'Default rule: {missed_negative:,} negative reviews were classified as positive.')
print(f'{false_alert:,} positive reviews would be incorrectly flagged as negative.')
print('The cost of these two mistakes can differ by organisation and use case.')

# Plot negative-class ranking quality
negative_truth = (y_test == 0).astype(int)
fig, axes = plt.subplots(1, 2, figsize=(10, 4))
RocCurveDisplay.from_predictions(negative_truth, 1 - selected_score, ax=axes[0], curve_kwargs={'color': NAVY})
PrecisionRecallDisplay.from_predictions(negative_truth, 1 - selected_score, ax=axes[1], color=SCARLET)
axes[0].set_title('Negative-review ROC curve')
axes[1].set_title('Negative-review precision–recall')
fig.tight_layout()
plt.show()

# Inspect probability calibration
fraction_positive, mean_score = calibration_curve(y_test, selected_score, n_bins=10, strategy='quantile')
fig, ax = plt.subplots(figsize=(5, 4))
ax.plot([0, 1], [0, 1], '--', color=SLATE, label='Perfect calibration')
ax.plot(mean_score, fraction_positive, 'o-', color=NAVY, label=selected_name)
ax.set(xlabel='Mean predicted positive score', ylabel='Observed positive fraction',
       title='Test calibration diagnostic', xlim=(0, 1), ylim=(0, 1))
ax.legend(fontsize=8)
fig.tight_layout()
plt.show()

# Define a bootstrap interval for a fixed model
def bootstrap_mean_interval(values, seed=RANDOM_STATE):
    values = np.asarray(values)
    rng = np.random.default_rng(seed)
    samples = rng.choice(values, size=(BOOTSTRAP_REPEATS, len(values)), replace=True)
    return np.quantile(samples.mean(axis=1), [0.025, 0.975])

# Estimate test accuracy intervals
interval_rows = []
for name, score in test_scores.items():
    correct = (score >= 0.5) == y_test
    lower, upper = bootstrap_mean_interval(correct)
    interval_rows.append({'model': name, 'accuracy': correct.mean(),
                          'bootstrap_95_lower': lower, 'bootstrap_95_upper': upper})
accuracy_intervals = pd.DataFrame(interval_rows)
display(accuracy_intervals.round(4))

# Compare accuracy with a paired bootstrap
comparison_name = ('TF-IDF + Naive Bayes' if selected_name != 'TF-IDF + Naive Bayes'
                   else 'TF-IDF + Logistic Regression')
selected_correct = ((selected_score >= 0.5) == y_test).astype('int8')
comparison_correct = ((test_scores[comparison_name] >= 0.5) == y_test).astype('int8')
accuracy_difference = selected_correct - comparison_correct
difference_interval = bootstrap_mean_interval(accuracy_difference)
print(f'Accuracy difference versus {comparison_name}: {accuracy_difference.mean():.2%}.')
print(f'Paired bootstrap 95% interval: {difference_interval[0]:.2%} to {difference_interval[1]:.2%}.')
print('The selected model remains the validation choice regardless of this test comparison.')

# Assess the locked triage rule on the test set
test_triage = pd.DataFrame([
    dict(policy='Reference negative threshold 0.50',
         **triage_summary(y_test, selected_score, 0.50)),
    dict(policy='Validation-locked illustrative triage',
         **triage_summary(y_test, selected_score, triage_threshold)),
])
display(test_triage.round(4))

# Interpret the triage trade-off
reference, triage = test_triage.iloc[0], test_triage.iloc[1]
print(f'At threshold {triage_threshold:.2f}: {int(triage.flagged):,} reviews are flagged '
      f'({triage.flagged / len(y_test):.1%} of this test set).')
print(f'Missed negatives: {int(reference.missed_negatives):,} → {int(triage.missed_negatives):,}; '
      f'false alerts: {int(reference.false_alerts):,} → {int(triage.false_alerts):,}.')
print(f'Assumed cost units: {int(reference.relative_cost_units):,} → {int(triage.relative_cost_units):,}.')
print('This is a movie-review simulation; no real service-time or revenue benefit was measured.')

# Inspect logistic-regression feature weights
coefficients = logistic_model.coef_.ravel()
positive_indices = np.argsort(coefficients)[-12:][::-1]
negative_indices = np.argsort(coefficients)[:12]
feature_weights = pd.DataFrame({
    'negative_feature': feature_names[negative_indices],
    'negative_weight': coefficients[negative_indices],
    'positive_feature': feature_names[positive_indices],
    'positive_weight': coefficients[positive_indices],
})
display(feature_weights.round(3))

# Plot interpretable term associations
indices = np.concatenate([negative_indices[:8], positive_indices[:8]])
indices = indices[np.argsort(coefficients[indices])]
fig, ax = plt.subplots(figsize=(8, 5))
ax.barh(feature_names[indices], coefficients[indices],
        color=[SCARLET if value < 0 else NAVY for value in coefficients[indices]])
ax.axvline(0, color=SLATE, linewidth=1)
ax.set(xlabel='Logistic coefficient: negative ← evidence → positive',
       title='Strong term associations in the fitted logistic model')
fig.tight_layout()
plt.show()

# Build a test-error audit table
error_audit = test_df[['review_id', 'sentiment', 'text']].copy()
error_audit['predicted_sentiment'] = np.where(selected_prediction == 1, 'positive', 'negative')
error_audit['positive_score'] = selected_score
error_audit['wrong'] = selected_prediction != y_test
error_audit['excerpt'] = error_audit['text'].str.slice(0, 180) + '…'

# Inspect confident missed negatives
missed_examples = error_audit[(error_audit['sentiment'] == 'negative') & error_audit['wrong']]
display(missed_examples.sort_values('positive_score', ascending=False)
        [['excerpt', 'positive_score', 'predicted_sentiment']].head(5).round(4))

# Inspect confident false alerts
false_alert_examples = error_audit[(error_audit['sentiment'] == 'positive') & error_audit['wrong']]
display(false_alert_examples.sort_values('positive_score')
        [['excerpt', 'positive_score', 'predicted_sentiment']].head(5).round(4))

# Define descriptive length groups
test_word_count = test_df['text'].str.split().str.len()
length_group = pd.cut(test_word_count, [0, 100, 200, 400, np.inf],
                      labels=['1–100', '101–200', '201–400', '401+'], include_lowest=True)

# Compare errors across review lengths
slice_rows = []
for group in length_group.cat.categories:
    mask = (length_group == group).to_numpy()
    if mask.sum() == 0:
        continue
    row = metric_summary(str(group), y_test[mask], selected_score[mask])
    row.update(reviews=int(mask.sum()), negative_share=float((y_test[mask] == 0).mean()))
    slice_rows.append(row)
length_results = pd.DataFrame(slice_rows).rename(columns={'model': 'words'})
display(length_results[['words', 'reviews', 'negative_share', 'accuracy', 'macro_f1']].round(4))

# Define prediction for new movie reviews
def predict_movie_reviews(reviews):
    texts = [normalise_text(review) for review in reviews]
    if not texts or any(not text for text in texts):
        raise ValueError('Supply at least one non-empty review.')
    if selected_name in core_models:
        scores = core_models[selected_name].predict_proba(vectorizer.transform(texts))[:, 1]
    else:
        tokens = neural_vectorizer(np.asarray(texts, dtype=object)).numpy()
        scores = neural_models[selected_name].predict(tokens, verbose=0).ravel()
    return pd.DataFrame({
        'input': reviews, 'positive_score': scores,
        'binary_sentiment': np.where(scores >= 0.5, 'positive', 'negative'),
        'illustrative_negative_flag': (1 - scores) >= triage_threshold,
    })

# Try clear, negated, mixed and neutral examples
demo_reviews = [
    'A wonderful film with brilliant acting. I would happily watch it again.',
    'A terrible movie. The boring story and poor acting wasted my evening.',
    'This movie was not bad at all; I enjoyed it more than I expected.',
    'I loved the visuals but hated the story.',
    'The movie was released on Friday and runs for two hours.',
]
display(predict_movie_reviews(demo_reviews).round(4))
print('Mixed and neutral statements still receive a forced binary label.')
print('A score is a model estimate, not a verified probability of a human opinion.')

# Declare an illustrative business capacity scenario
MONTHLY_TEXT_ITEMS = 10_000
MANUAL_MINUTES_PER_ITEM = 2.0
ASSUMED_REVIEW_FRACTION = 0.35
ASSISTED_MINUTES_PER_REVIEW = 1.5
MONTHLY_OVERSIGHT_HOURS = 15.0
ASSUMED_STAFF_COST_PER_HOUR_ZAR = 180.0
ASSUMED_PLATFORM_COST_PER_MONTH_ZAR = 4_500.0

# Calculate the assumed capacity value
manual_hours = MONTHLY_TEXT_ITEMS * MANUAL_MINUTES_PER_ITEM / 60
assisted_hours = (MONTHLY_TEXT_ITEMS * ASSUMED_REVIEW_FRACTION
                  * ASSISTED_MINUTES_PER_REVIEW / 60 + MONTHLY_OVERSIGHT_HOURS)
hours_freed = manual_hours - assisted_hours
capacity_value = hours_freed * ASSUMED_STAFF_COST_PER_HOUR_ZAR
display(pd.DataFrame({
    'scenario_measure': ['Manual hours', 'Assisted + oversight hours', 'Hours freed',
                         'Assigned capacity value (ZAR)', 'Platform cost assumption (ZAR)',
                         'Capacity value less platform cost (ZAR)'],
    'assumed_value': [manual_hours, assisted_hours, hours_freed, capacity_value,
                      ASSUMED_PLATFORM_COST_PER_MONTH_ZAR,
                      capacity_value - ASSUMED_PLATFORM_COST_PER_MONTH_ZAR],
}).round(2))
print('Illustrative scenario only. Replace every input with measured pilot evidence.')

# Show sensitivity to the assumed review fraction
review_fractions = np.array([0.20, 0.35, 0.50, 0.75, 1.00])
scenario_hours = (MONTHLY_TEXT_ITEMS * review_fractions * ASSISTED_MINUTES_PER_REVIEW / 60
                   + MONTHLY_OVERSIGHT_HOURS)
display(pd.DataFrame({'assumed_review_fraction': review_fractions,
                      'human_hours_required': scenario_hours,
                      'hours_freed_vs_manual': manual_hours - scenario_hours}).round(2))

# Build the data-quality reconciliation
quality_audit = pd.DataFrame({
    'measure': ['raw_rows', 'raw_exact_duplicate_rows', 'normalised_repeated_rows',
                'quarantined_rows', 'eligible_duplicates_removed', 'retained_unique_rows',
                'training_rows', 'validation_rows', 'test_rows'],
    'count': [len(raw), raw_duplicate_rows, normalised_duplicate_rows, quarantined_rows,
              duplicates_removed, len(clean), len(train_df), len(val_df), len(test_df)],
})
display(quality_audit)

# Export the score and audit tables
quality_audit.to_csv(OUTPUT_DIR / 'data_quality.csv', index=False)
tuning_results.to_csv(OUTPUT_DIR / 'logistic_validation_search.csv', index=False)
validation_results.to_csv(OUTPUT_DIR / 'validation_metrics.csv', index=False)
test_results.to_csv(OUTPUT_DIR / 'test_metrics.csv', index=False)
accuracy_intervals.to_csv(OUTPUT_DIR / 'accuracy_intervals.csv', index=False)
threshold_results.to_csv(OUTPUT_DIR / 'validation_thresholds.csv', index=False)
test_triage.to_csv(OUTPUT_DIR / 'test_triage.csv', index=False)
length_results.to_csv(OUTPUT_DIR / 'test_length_slices.csv', index=False)
feature_weights.to_csv(OUTPUT_DIR / 'logistic_feature_weights.csv', index=False)
print('Saved metric, data-quality and diagnostic tables.')

# Export partition membership
split_manifest = pd.concat([
    frame[['review_id', 'source_row', 'label']].assign(split=name)
    for name, frame in [('train', train_df), ('validation', val_df), ('test', test_df)]
], ignore_index=True)
split_manifest.to_csv(OUTPUT_DIR / 'split_manifest.csv', index=False)
assert split_manifest['review_id'].is_unique
print(f'Saved {len(split_manifest):,} partition records without review text.')

# Export final selected predictions
prediction_export = test_df[['review_id', 'source_row', 'label']].copy()
prediction_export['selected_model'] = selected_name
prediction_export['positive_score'] = selected_score
prediction_export['predicted_label_default'] = selected_prediction
prediction_export['negative_flag_locked_policy'] = (1 - selected_score) >= triage_threshold
prediction_export.to_csv(OUTPUT_DIR / 'selected_test_predictions.csv', index=False)
print(f'Saved {len(prediction_export):,} final prediction records without review text.')

# Save the strongest classical pipeline components
core_snapshot = {
    'vectorizer': vectorizer, 'classifier': best_core_model,
    'model_name': best_core_name, 'labels': label_map,
    'input_contract': 'Apply normalise_text before vectorizer.transform.',
    'source_sha256': source_sha256,
    'sklearn_version': importlib.metadata.version('scikit-learn'),
}
joblib.dump(core_snapshot, OUTPUT_DIR / 'sentiment_core.joblib', compress=3)
reloaded_core = joblib.load(OUTPUT_DIR / 'sentiment_core.joblib')
assert np.allclose(reloaded_core['classifier'].predict_proba(X_val[:5])[:, 1],
                   validation_scores[best_core_name][:5])
print('Saved sentiment_core.joblib; normalised movie-review text is required.')

# Save optional neural artifacts only after training
if RUN_NEURAL:
    for name, model in neural_models.items():
        slug = re.sub(r'[^a-z0-9]+', '_', name.lower()).strip('_')
        model.save(OUTPUT_DIR / f'{slug}.keras')
    neural_encoding = {'vocabulary': neural_vectorizer.get_vocabulary(),
                       'max_length': MAX_LENGTH, 'standardize': None}
    (OUTPUT_DIR / 'neural_encoding.json').write_text(json.dumps(neural_encoding, indent=2))

# Record the run configuration and dependency versions
versions = {name: importlib.metadata.version(name) for name in
            ['numpy', 'pandas', 'scipy', 'scikit-learn', 'matplotlib', 'joblib']}
run_manifest = {
    'author': 'Gareth Grant', 'dataset_file': DATA_PATH.name, 'dataset_sha256': source_sha256,
    'python': platform.python_version(), 'dependencies': versions, 'random_state': RANDOM_STATE,
    'raw_rows': len(raw), 'unique_rows': len(clean),
    'splits': {'train': len(train_df), 'validation': len(val_df), 'test': len(test_df)},
    'tfidf_max_features': TFIDF_MAX_FEATURES, 'logistic_candidates_C': LOGISTIC_C_VALUES,
    'locked_decisions': locked_plan, 'bootstrap_repeats': BOOTSTRAP_REPEATS,
    'bootstrap_assumption': 'Independent test rows, conditional on fixed trained models.',
    'neural_requested': RUN_NEURAL, 'neural_models_trained': list(neural_models),
    'official_stanford_split': False,
}
if RUN_NEURAL:
    run_manifest['tensorflow_version'] = tf.__version__
(OUTPUT_DIR / 'run_manifest.json').write_text(json.dumps(run_manifest, indent=2))
display(pd.Series(versions, name='version').to_frame())

# Generate the portfolio conclusion
accuracy_ci = accuracy_intervals.set_index('model').loc[selected_name]
print(f'Selected on validation: {selected_name}.')
print(f'Final accuracy: {selected_row.accuracy:.2%}; macro F1: {selected_row.macro_f1:.4f}.')
print(f'Conditional bootstrap 95% accuracy interval: '
      f'{accuracy_ci.bootstrap_95_lower:.2%}–{accuracy_ci.bootstrap_95_upper:.2%}.')
print(f'Data audit: {len(raw):,} source rows → {len(clean):,} unique valid reviews; '
      f'{duplicates_removed:,} eligible duplicates removed.')
print('The workflow demonstrates reproducible text analytics, interpretable baselines, '
      'error analysis and an explicit operational trade-off.')
print('Business, astronomy and government are adaptation proposals, not validated deployment domains.')
print('Neural experiments:', 'trained in this run' if neural_models else 'not run; no performance claim')