notionhelper 0.3.1__tar.gz → 0.3.2__tar.gz

notionhelper-0.3.2/ML_DEMO_README.md

@@ -0,0 +1,315 @@
+# NotionHelper ML Demo Guide
+
+## Overview
+
+`ml_demo.py` is a comprehensive demonstration of how to use **NotionHelper** to track machine learning experiments. It showcases a complete workflow from model training to Notion integration.
+
+## Features
+
+✨ **Complete ML Pipeline**
+- Logistic Regression on sklearn's breast cancer dataset
+- Train/test split with stratification
+- Feature scaling
+- Comprehensive metrics calculation
+
+📊 **Metrics Tracked**
+- Accuracy
+- Precision
+- Recall
+- F1 Score
+- ROC AUC
+- Training/Test sample sizes
+
+📈 **Visualizations**
+- Confusion Matrix (heatmap)
+- ROC Curve with AUC score
+- Feature Importance (when scaling is disabled)
+
+💾 **Artifacts**
+- Predictions CSV with probabilities
+- Classification report
+- All generated plots
+
+## Quick Start
+
+### 1. Run the Demo (without Notion)
+
+```bash
+python ml_demo.py
+```
+
+This will:
+- Train the model
+- Generate all metrics and plots
+- Save artifacts to disk
+- Show instructions for Notion integration
+
+### 2. Set Up Notion Integration
+
+#### A. Get Your Notion API Token
+
+1. Go to [Notion Integrations](https://www.notion.so/my-integrations)
+2. Create a new integration
+3. Copy the "Internal Integration Token"
+4. Set it as an environment variable:
+
+```bash
+export NOTION_TOKEN='secret_your_token_here'
+```
+
+#### B. Create a Parent Page
+
+1. Create a new page in Notion (this will hold your ML experiment databases)
+2. Share the page with your integration
+3. Copy the page ID from the URL:
+   - URL: `https://www.notion.so/My-ML-Experiments-abc123def456...`
+   - Page ID: `abc123def456...`
+
+#### C. Create the Database (First Time Only)
+
+1. Open `ml_demo.py`
+2. Find the "STEP 4A" section
+3. Uncomment the database creation code
+4. Set `PARENT_PAGE_ID = "your_page_id_here"`
+5. Run the script:
+
+```bash
+python ml_demo.py
+```
+
+6. **IMPORTANT**: Copy the `data_source_id` from the output!
+
+Example output:
+```
+✓ Database created! Data Source ID: 2d2fdfd6-8a97-80ba-bdd6-000b787993a4
+💡 Save this ID for future experiment logging!
+```
+
+#### D. Log Experiments
+
+1. Comment out the database creation code (STEP 4A)
+2. Set `DATA_SOURCE_ID = "your_data_source_id_from_step_C"`
+3. Run experiments:
+
+```bash
+python ml_demo.py
+```
+
+Each run will:
+- Create a new row in your Notion database
+- Upload confusion matrix and ROC curve plots
+- Attach CSV artifacts
+- Compare metrics with previous runs
+- Show 🏆 if it's a new best score!
+
+## Customization
+
+### Hyperparameters
+
+Modify the `config` dictionary in the `main()` function:
+
+```python
+config = {
+    "Experiment_Name": "Your Experiment",
+    "Model": "Logistic Regression",
+    "C_Regularization": 10.0,        # Change this
+    "Max_Iterations": 2000,          # Or this
+    "Solver": "saga",                # Try different solvers
+    "Penalty": "l1",                 # L1 or L2 regularization
+    "Feature_Scaling": True          # Enable/disable scaling
+}
+```
+
+### Target Metric
+
+Change which metric to optimize in the `log_ml_experiment()` call:
+
+```python
+page_id = nh.log_ml_experiment(
+    ...
+    target_metric="Accuracy",     # Or "Precision", "Recall", "F1_Score"
+    higher_is_better=True,        # Higher scores are better
+    ...
+)
+```
+
+## Example Workflow
+
+### Experiment 1: Baseline
+```python
+config = {
+    "C_Regularization": 1.0,
+    "Penalty": "l2",
+    "Solver": "lbfgs"
+}
+# Results: F1 Score = 98.61%
+```
+
+### Experiment 2: Stronger Regularization
+```python
+config = {
+    "C_Regularization": 0.1,  # Stronger regularization
+    "Penalty": "l2",
+    "Solver": "lbfgs"
+}
+# Run to see if it improves performance
+```
+
+### Experiment 3: L1 Regularization
+```python
+config = {
+    "C_Regularization": 1.0,
+    "Penalty": "l1",          # Switch to L1
+    "Solver": "saga"          # L1 requires saga or liblinear
+}
+# L1 can perform feature selection
+```
+
+## Generated Files
+
+After running the demo, you'll find:
+
+```
+├── confusion_matrix.png           # Confusion matrix heatmap
+├── roc_curve.png                  # ROC curve with AUC
+├── feature_importance.png         # Feature coefficients (if no scaling)
+├── predictions.csv                # Test set predictions
+└── classification_report.csv      # Detailed metrics per class
+```
+
+## Notion Database Schema
+
+The created database will have columns for:
+
+**Config Fields:**
+- Experiment_Name (Title)
+- Model
+- Dataset
+- Test_Size
+- Random_State
+- C_Regularization (Number)
+- Max_Iterations (Number)
+- Solver
+- Penalty
+- Feature_Scaling (Checkbox) ✅
+
+**Metric Fields:**
+- Accuracy (Number)
+- Precision (Number)
+- Recall (Number)
+- F1_Score (Number)
+- ROC_AUC (Number)
+- Train_Samples (Number)
+- Test_Samples (Number)
+- Run Status (shows 🏆 for new best)
+
+**Artifacts:**
+- Plots (embedded in page body)
+- Artifacts (attached CSV files)
+
+## Troubleshooting
+
+### Boolean Properties Showing as Numbers
+
+If you see boolean values (like `Feature_Scaling`) appearing as numbers in Notion:
+
+1. Check the debug output in the console
+2. Ensure you're passing Python `bool` types (not 0/1 integers)
+3. The `dict_to_notion_schema()` includes debug prints to help diagnose
+
+### Notion API Errors
+
+Common issues:
+- **401 Unauthorized**: Check your NOTION_TOKEN
+- **404 Not Found**: Verify your PARENT_PAGE_ID or DATA_SOURCE_ID
+- **400 Bad Request**: Make sure the page is shared with your integration
+
+### Missing Plots
+
+Ensure matplotlib and seaborn are installed:
+```bash
+pip install matplotlib seaborn
+```
+
+## Advanced Usage
+
+### Use Your Own Dataset
+
+Replace the data loading section:
+
+```python
+# Replace this:
+data = load_breast_cancer()
+X = pd.DataFrame(data.data, columns=data.feature_names)
+y = pd.Series(data.target, name='target')
+
+# With your own data:
+df = pd.read_csv('your_data.csv')
+X = df.drop('target_column', axis=1)
+y = df['target_column']
+```
+
+### Add More Metrics
+
+Calculate additional metrics:
+
+```python
+from sklearn.metrics import matthews_corrcoef, balanced_accuracy_score
+
+metrics = {
+    ...
+    "MCC": round(matthews_corrcoef(y_test, y_pred), 4),
+    "Balanced_Accuracy": round(balanced_accuracy_score(y_test, y_pred) * 100, 2)
+}
+```
+
+### Grid Search Integration
+
+Combine with sklearn's GridSearchCV:
+
+```python
+from sklearn.model_selection import GridSearchCV
+
+param_grid = {
+    'C': [0.1, 1.0, 10.0],
+    'penalty': ['l1', 'l2']
+}
+
+grid = GridSearchCV(LogisticRegression(), param_grid, cv=5)
+grid.fit(X_train, y_train)
+
+# Log each configuration
+for params, mean_score in zip(grid.cv_results_['params'],
+                               grid.cv_results_['mean_test_score']):
+    config.update(params)
+    metrics['CV_Score'] = mean_score
+    nh.log_ml_experiment(...)
+```
+
+## Benefits of Using NotionHelper
+
+✅ **Centralized Tracking**: All experiments in one place
+✅ **Visual Comparison**: See which hyperparameters work best
+✅ **Automatic Leaderboard**: Highlights new best scores
+✅ **File Attachments**: Keep plots and CSVs with experiments
+✅ **Team Collaboration**: Share results with your team
+✅ **Reproducibility**: Track all hyperparameters and seeds
+
+## Next Steps
+
+1. **Run the demo** to familiarize yourself with the workflow
+2. **Create your Notion database** following the setup guide
+3. **Customize for your project** - replace with your ML model
+4. **Run multiple experiments** with different hyperparameters
+5. **Review results in Notion** - compare and analyze performance
+
+## Support
+
+For issues or questions:
+- Check the [NotionHelper documentation](carecast/notionhelper.py)
+- Review the [Notion API docs](https://developers.notion.com/)
+- Examine the debug output for type checking issues
+
+---
+
+**Happy Experimenting! 🚀**

{notionhelper-0.3.1 → notionhelper-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: notionhelper
-Version: 0.3.1
+Version: 0.3.2
 Summary: NotionHelper is a Python library that simplifies interactions with the Notion API, enabling easy management of databases, pages, and files within Notion workspaces.
 Author-email: Jan du Plessis <drjanduplessis@icloud.com>
 Requires-Python: >=3.10

notionhelper-0.3.2/examples/ml_demo.py

@@ -0,0 +1,391 @@
+"""
+NotionHelper ML Demo: Logistic Regression with sklearn
+=======================================================
+This demo showcases how to use NotionHelper to track ML experiments.
+
+Features:
+- Logistic regression on sklearn's breast cancer dataset
+- Complete metrics tracking (accuracy, precision, recall, F1)
+- Hyperparameter configuration
+- Automatic Notion database creation
+- Experiment logging with plots and artifacts
+"""
+
+import os
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import (
+    accuracy_score,
+    precision_score,
+    recall_score,
+    f1_score,
+    confusion_matrix,
+    classification_report,
+    roc_curve,
+    roc_auc_score
+)
+from sklearn.preprocessing import StandardScaler
+
+from carecast.notionhelper import NotionHelper
+
+
+def train_logistic_regression(
+    test_size=0.2,
+    random_state=42,
+    C=1.0,
+    max_iter=1000,
+    solver='lbfgs',
+    penalty='l2',
+    scale_features=True
+):
+    """
+    Train a logistic regression model on breast cancer dataset.
+
+    Parameters:
+    -----------
+    test_size : float
+        Proportion of dataset to use for testing
+    random_state : int
+        Random seed for reproducibility
+    C : float
+        Inverse of regularization strength
+    max_iter : int
+        Maximum iterations for solver
+    solver : str
+        Algorithm to use in optimization
+    penalty : str
+        Regularization penalty type
+    scale_features : bool
+        Whether to standardize features
+
+    Returns:
+    --------
+    metrics : dict
+        Dictionary containing all evaluation metrics
+    plot_paths : list
+        List of paths to generated plots
+    artifacts : list
+        List of paths to saved artifacts
+    """
+
+    print("\n" + "="*60)
+    print("🔬 NOTIONHELPER ML DEMO: Logistic Regression")
+    print("="*60 + "\n")
+
+    # 1. Load Dataset
+    print("📊 Loading breast cancer dataset...")
+    data = load_breast_cancer()
+    X = pd.DataFrame(data.data, columns=data.feature_names)
+    y = pd.Series(data.target, name='target')
+
+    print(f"   Dataset shape: {X.shape}")
+    print(f"   Classes: {data.target_names}")
+    print(f"   Features: {X.shape[1]}")
+
+    # 2. Split Data
+    print("\n🔀 Splitting data...")
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=test_size, random_state=random_state, stratify=y
+    )
+    print(f"   Training set: {X_train.shape[0]} samples")
+    print(f"   Test set: {X_test.shape[0]} samples")
+
+    # 3. Feature Scaling (optional but recommended)
+    if scale_features:
+        print("\n⚖️  Scaling features...")
+        scaler = StandardScaler()
+        X_train = scaler.fit_transform(X_train)
+        X_test = scaler.transform(X_test)
+
+    # 4. Train Model
+    print("\n🤖 Training Logistic Regression model...")
+    model = LogisticRegression(
+        C=C,
+        max_iter=max_iter,
+        solver=solver,
+        penalty=penalty,
+        random_state=random_state
+    )
+    model.fit(X_train, y_train)
+    print("   ✓ Model trained successfully")
+
+    # 5. Make Predictions
+    print("\n🎯 Making predictions...")
+    y_pred = model.predict(X_test)
+    y_pred_proba = model.predict_proba(X_test)[:, 1]
+
+    # 6. Calculate Metrics
+    print("\n📈 Calculating metrics...")
+    accuracy = accuracy_score(y_test, y_pred)
+    precision = precision_score(y_test, y_pred)
+    recall = recall_score(y_test, y_pred)
+    f1 = f1_score(y_test, y_pred)
+    roc_auc = roc_auc_score(y_test, y_pred_proba)
+
+    metrics = {
+        "Accuracy": round(accuracy * 100, 2),
+        "Precision": round(precision * 100, 2),
+        "Recall": round(recall * 100, 2),
+        "F1_Score": round(f1 * 100, 2),
+        "ROC_AUC": round(roc_auc * 100, 2),
+        "Train_Samples": int(X_train.shape[0]),
+        "Test_Samples": int(X_test.shape[0])
+    }
+
+    # Print metrics
+    print("\n" + "="*60)
+    print("📊 MODEL PERFORMANCE METRICS")
+    print("-" * 60)
+    print(f"Accuracy  : {metrics['Accuracy']:.2f}%")
+    print(f"Precision : {metrics['Precision']:.2f}%")
+    print(f"Recall    : {metrics['Recall']:.2f}%")
+    print(f"F1 Score  : {metrics['F1_Score']:.2f}%")
+    print(f"ROC AUC   : {metrics['ROC_AUC']:.2f}%")
+    print("="*60 + "\n")
+
+    # 7. Generate Visualizations
+    print("📊 Generating visualizations...")
+    plot_paths = []
+
+    # Confusion Matrix
+    cm = confusion_matrix(y_test, y_pred)
+    plt.figure(figsize=(8, 6))
+    sns.heatmap(cm, annot=True, fmt='d', cmap='Blues',
+                xticklabels=data.target_names,
+                yticklabels=data.target_names)
+    plt.title('Confusion Matrix', fontsize=14, fontweight='bold')
+    plt.ylabel('True Label')
+    plt.xlabel('Predicted Label')
+    plt.tight_layout()
+    cm_path = 'confusion_matrix.png'
+    plt.savefig(cm_path, dpi=150)
+    plot_paths.append(cm_path)
+    plt.close()
+    print(f"   ✓ Saved: {cm_path}")
+
+    # ROC Curve
+    fpr, tpr, _ = roc_curve(y_test, y_pred_proba)
+    plt.figure(figsize=(8, 6))
+    plt.plot(fpr, tpr, color='#1f77b4', lw=2,
+             label=f'ROC curve (AUC = {roc_auc:.3f})')
+    plt.plot([0, 1], [0, 1], color='gray', lw=1, linestyle='--',
+             label='Random Classifier')
+    plt.xlim([0.0, 1.0])
+    plt.ylim([0.0, 1.05])
+    plt.xlabel('False Positive Rate', fontsize=12)
+    plt.ylabel('True Positive Rate', fontsize=12)
+    plt.title('ROC Curve', fontsize=14, fontweight='bold')
+    plt.legend(loc="lower right")
+    plt.grid(alpha=0.3)
+    plt.tight_layout()
+    roc_path = 'roc_curve.png'
+    plt.savefig(roc_path, dpi=150)
+    plot_paths.append(roc_path)
+    plt.close()
+    print(f"   ✓ Saved: {roc_path}")
+
+    # Feature Importance (Coefficients)
+    if not scale_features:
+        feature_importance = pd.DataFrame({
+            'Feature': data.feature_names,
+            'Coefficient': model.coef_[0]
+        }).sort_values('Coefficient', key=abs, ascending=False).head(15)
+
+        plt.figure(figsize=(10, 6))
+        colors = ['#d62728' if x < 0 else '#2ca02c' for x in feature_importance['Coefficient']]
+        plt.barh(feature_importance['Feature'], feature_importance['Coefficient'], color=colors)
+        plt.xlabel('Coefficient Value', fontsize=12)
+        plt.title('Top 15 Feature Importance (Logistic Regression Coefficients)',
+                  fontsize=14, fontweight='bold')
+        plt.grid(axis='x', alpha=0.3)
+        plt.tight_layout()
+        feat_path = 'feature_importance.png'
+        plt.savefig(feat_path, dpi=150)
+        plot_paths.append(feat_path)
+        plt.close()
+        print(f"   ✓ Saved: {feat_path}")
+
+    # 8. Save Artifacts
+    print("\n💾 Saving artifacts...")
+    artifacts = []
+
+    # Save predictions
+    predictions_df = pd.DataFrame({
+        'True_Label': y_test.values,
+        'Predicted_Label': y_pred,
+        'Probability_Malignant': y_pred_proba,
+        'Correct': (y_test.values == y_pred).astype(int)
+    })
+    pred_path = 'predictions.csv'
+    predictions_df.to_csv(pred_path, index=False)
+    artifacts.append(pred_path)
+    print(f"   ✓ Saved: {pred_path}")
+
+    # Save classification report
+    report = classification_report(y_test, y_pred,
+                                   target_names=data.target_names,
+                                   output_dict=True)
+    report_df = pd.DataFrame(report).transpose()
+    report_path = 'classification_report.csv'
+    report_df.to_csv(report_path)
+    artifacts.append(report_path)
+    print(f"   ✓ Saved: {report_path}")
+
+    # Combine plot paths and artifacts
+    all_artifacts = plot_paths + artifacts
+
+    return metrics, plot_paths, all_artifacts
+
+
+def main():
+    """
+    Main function to demonstrate NotionHelper integration.
+    """
+
+    # ============================================================
+    # STEP 1: Define Hyperparameters Configuration
+    # ============================================================
+    config = {
+        "Experiment_Name": "Logistic Regression Demo",
+        "Model": "Logistic Regression",
+        "Dataset": "Breast Cancer (sklearn)",
+        "Test_Size": 0.2,
+        "Random_State": 42,
+        "C_Regularization": 1.0,
+        "Max_Iterations": 2,
+        "Solver": "lbfgs",
+        "Penalty": "l2",
+        "Feature_Scaling": True
+    }
+
+    # ============================================================
+    # STEP 2: Train Model and Calculate Metrics
+    # ============================================================
+    metrics, plot_paths, artifacts = train_logistic_regression(
+        test_size=config["Test_Size"],
+        random_state=config["Random_State"],
+        C=config["C_Regularization"],
+        max_iter=config["Max_Iterations"],
+        solver=config["Solver"],
+        penalty=config["Penalty"],
+        scale_features=config["Feature_Scaling"]
+    )
+
+    # ============================================================
+    # STEP 3: Initialize NotionHelper
+    # ============================================================
+    print("\n" + "="*60)
+    print("📝 NOTION INTEGRATION")
+    print("="*60 + "\n")
+
+    # IMPORTANT: Replace with your Notion API token
+    NOTION_TOKEN = os.getenv("NOTION_TOKEN", "your_notion_token_here")
+
+    if NOTION_TOKEN == "your_notion_token_here":
+        print("⚠️  WARNING: Please set your NOTION_TOKEN environment variable")
+        print("   Example: export NOTION_TOKEN='secret_...'")
+        print("\n✅ Demo completed successfully (without Notion logging)")
+        print(f"\n📁 Generated files:")
+        for artifact in artifacts:
+            print(f"   • {artifact}")
+        return
+
+    try:
+        nh = NotionHelper(NOTION_TOKEN)
+        print("✓ NotionHelper initialized successfully")
+
+        # ============================================================
+        # STEP 4A: Create New Database (First time only)
+        # ============================================================
+        # Set CREATE_NEW_DB to True on first run, then set to False
+        CREATE_NEW_DB = False  # Force creation for this run
+        PARENT_PAGE_ID = "your page id here"
+
+        if CREATE_NEW_DB:
+            print("\n🗄️  Creating new Notion database...")
+            data_source_id = nh.create_ml_database(
+                parent_page_id=PARENT_PAGE_ID,
+                db_title="ML Experiments - Logistic Regression Demo",
+                config=config,
+                metrics=metrics,
+                file_property_name="Artifacts"
+            )
+            print(f"\n✅ Database created successfully!")
+            print(f"📝 Data Source ID: {data_source_id}")
+            print("\n" + "="*60)
+            print("⚠️  CRITICAL: Complete these steps NOW!")
+            print("="*60)
+            print("\n1️⃣  Go to Notion and find the new database:")
+            print("   'ML Experiments - Logistic Regression Demo'")
+            print("\n2️⃣  Click '...' (top right) → Add connections")
+            print("   → Select your integration")
+            print("\n3️⃣  Save this Data Source ID:")
+            print(f"   DATA_SOURCE_ID = \"{data_source_id}\"")
+            print("\n4️⃣  Set CREATE_NEW_DB = False in this script")
+            print("\n5️⃣  Run the script again to log experiments")
+            print("="*60 + "\n")
+
+            print("⏸️  Skipping experiment logging for this run.")
+            print("   Complete steps above, then run again.")
+            return  # Exit after database creation
+
+        # This else block will only be reached if CREATE_NEW_DB was initially False
+        # and the user has already provided a DATA_SOURCE_ID.
+        else:
+            # Replace with your actual data source ID after creating the database
+            DATA_SOURCE_ID = "your_data_source_id_here" # This should be updated by the user
+
+
+        if DATA_SOURCE_ID == "your_data_source_id_here":
+            print("\n💡 To log experiments:")
+            print("   1. Ensure CREATE_NEW_DB is False and DATA_SOURCE_ID is set.")
+            print("   2. Make sure the database is shared with your integration.")
+        else:
+            print("\n� Logging experiment to Notion...")
+            page_id = nh.log_ml_experiment(
+                data_source_id=DATA_SOURCE_ID,
+                config=config,
+                metrics=metrics,
+                plots=plot_paths,
+                target_metric="F1_Score",
+                higher_is_better=True,
+                file_paths=artifacts,
+                file_property_name="Artifacts"
+            )
+
+            if page_id:
+                print(f"✓ Experiment logged successfully!")
+                print(f"  Page ID: {page_id}")
+            else:
+                print("❌ Failed to log experiment")
+
+    except Exception as e:
+        print(f"❌ Notion API Error: {e}")
+        print("   Continuing without Notion logging...")
+
+    # ============================================================
+    # FINAL SUMMARY
+    # ============================================================
+    print("\n" + "="*60)
+    print("✅ DEMO COMPLETED SUCCESSFULLY")
+    print("="*60)
+    print(f"\n📁 Generated files:")
+    for artifact in artifacts:
+        print(f"   • {artifact}")
+
+    print("\n📊 Key Metrics:")
+    print(f"   • Accuracy:  {metrics['Accuracy']:.2f}%")
+    print(f"   • F1 Score:  {metrics['F1_Score']:.2f}%")
+    print(f"   • ROC AUC:   {metrics['ROC_AUC']:.2f}%")
+
+    print("\n🎉 Thank you for trying NotionHelper!")
+    print("="*60 + "\n")
+
+
+if __name__ == "__main__":
+    main()

{notionhelper-0.3.1 → notionhelper-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "notionhelper"
-version = "0.3.1"
+version = "0.3.2"
 description = "NotionHelper is a Python library that simplifies interactions with the Notion API, enabling easy management of databases, pages, and files within Notion workspaces."
 readme = "README.md"
 authors = [

{notionhelper-0.3.1 → notionhelper-0.3.2}/uv.lock

@@ -1279,7 +1279,7 @@ wheels = [
 
 [[package]]
 name = "notionhelper"
-version = "0.2.1"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "mimetype" },