Cuadernos Python

Integración con Jupyter Notebook

Integra cuadernos Jupyter para enriquecimientos personalizados, análisis de datos y flujos de trabajo de machine learning.

Obtener detalles del cuaderno

GET /api/{tenantId}/{projectId}/notebook/{notebookId}

Recupera información completa sobre un cuaderno Jupyter, incluyendo sus celdas, estado de ejecución y parámetros de integración.

Parámetros

Parámetro	Tipo	Ubicación	Descripción
tenantId	GUID	Ruta	El identificador del tenant
projectId	GUID	Ruta	El identificador del proyecto
notebookId	GUID	Ruta	El identificador del cuaderno

Respuesta

{
  "notebookId": "aa0e8400-e29b-41d4-a716-446655440000",
  "projectId": "660e8400-e29b-41d4-a716-446655440000",
  "notebookName": "Análisis de Minería de Procesos",
  "notebookDescription": "Análisis personalizado para la optimización del recorrido del cliente",
  "notebookVersion": "1.3.2",
  "kernelType": "python3",
  "status": "Ready",
  "integration": {
    "enrichmentMode": true,
    "datasetBinding": "880e8400-e29b-41d4-a716-446655440000",
    "outputFormat": "enriched_dataframe",
    "autoExecution": false
  },
  "cells": [
    {
      "cellId": "cell-001",
      "cellType": "code",
      "executionCount": 15,
      "hasOutput": true,
      "lastExecuted": "2024-01-20T10:30:00Z",
      "executionStatus": "Success"
    },
    {
      "cellId": "cell-002",
      "cellType": "markdown",
      "lastModified": "2024-01-19T14:20:00Z"
    }
  ],
  "environment": {
    "pythonVersion": "3.9.18",
    "packages": ["pandas", "numpy", "scikit-learn", "mindzie-sdk"],
    "customLibraries": ["process_mining_utils", "customer_analytics"]
  },
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateModified": "2024-01-20T10:30:00Z",
  "createdBy": "user123",
  "lastExecutionDate": "2024-01-20T10:30:00Z",
  "executionCount": 47
}

Listar todos los cuadernos

GET /api/{tenantId}/{projectId}/notebooks

Recupera una lista de todos los cuadernos Jupyter en el proyecto con metadatos básicos y estado de ejecución.

Parámetros de consulta

Parámetro	Tipo	Descripción
status	string	Filtrar por estado: Ready, Running, Error, Kernel_Dead
kernelType	string	Filtrar por tipo de kernel: python3, r, scala
enrichmentMode	boolean	Filtrar cuadernos configurados para enriquecimiento de datos
page	integer	Número de página para paginación (por defecto: 1)
pageSize	integer	Número de elementos por página (por defecto: 20, máximo: 100)

Respuesta

{
  "notebooks": [
    {
      "notebookId": "aa0e8400-e29b-41d4-a716-446655440000",
      "notebookName": "Análisis de Minería de Procesos",
      "kernelType": "python3",
      "status": "Ready",
      "enrichmentMode": true,
      "cellCount": 12,
      "lastExecutionDate": "2024-01-20T10:30:00Z",
      "dateCreated": "2024-01-15T10:30:00Z"
    }
  ],
  "totalCount": 8,
  "page": 1,
  "pageSize": 20,
  "hasNextPage": false
}

Crear nuevo cuaderno

POST /api/{tenantId}/{projectId}/notebook

Crea un nuevo cuaderno Jupyter con configuración especificada y plantilla opcional. El cuaderno se configura automáticamente para integración de datos mindzie.

Cuerpo de la solicitud

{
  "notebookName": "Análisis Avanzado de Clientes",
  "notebookDescription": "Modelos de machine learning para predicción del comportamiento del cliente",
  "kernelType": "python3",
  "template": "process_mining_starter",
  "integration": {
    "enrichmentMode": true,
    "datasetBinding": "880e8400-e29b-41d4-a716-446655440000",
    "outputFormat": "enriched_dataframe",
    "autoExecution": false
  },
  "environment": {
    "packages": ["pandas", "numpy", "scikit-learn", "matplotlib", "seaborn"],
    "customLibraries": ["process_mining_utils"]
  },
  "initialCells": [
    {
      "cellType": "markdown",
      "content": "# Cuaderno de Análisis de Clientes\n\nEste cuaderno analiza datos del recorrido del cliente usando técnicas de minería de procesos."
    },
    {
      "cellType": "code",
      "content": "import pandas as pd\nimport numpy as np\nfrom mindzie_sdk import ProcessMiningClient\n\n# Inicializar cliente mindzie\nclient = ProcessMiningClient()"
    }
  ]
}

Respuesta

Devuelve 201 Created con el objeto completo del cuaderno incluyendo ID generado y la información inicial de sesión.

Ejecutar cuaderno

POST /api/{tenantId}/{projectId}/notebook/{notebookId}/execute

Ejecuta todas las celdas del cuaderno o un rango especificado de celdas. La ejecución se realiza de forma asíncrona y los resultados se almacenan para su recuperación.

Cuerpo de la solicitud

{
  "executionMode": "all",
  "cellRange": {
    "startCell": "cell-001",
    "endCell": "cell-010"
  },
  "parameters": {
    "dataset_id": "880e8400-e29b-41d4-a716-446655440000",
    "analysis_period": "2024-01",
    "include_weekends": false
  },
  "outputOptions": {
    "captureOutputs": true,
    "saveIntermediateResults": true,
    "generateReport": true
  },
  "timeout": 1800,
  "priority": "Normal"
}

Respuesta

{
  "executionId": "bb0e8400-e29b-41d4-a716-446655440000",
  "notebookId": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "Running",
  "startTime": "2024-01-20T10:30:00Z",
  "estimatedDuration": "15-20 minutes",
  "currentCell": "cell-003",
  "progress": {
    "totalCells": 12,
    "completedCells": 2,
    "currentCellIndex": 3,
    "percentComplete": 17
  },
  "parameters": {
    "dataset_id": "880e8400-e29b-41d4-a716-446655440000",
    "analysis_period": "2024-01",
    "include_weekends": false
  }
}

Obtener estado de la ejecución

GET /api/{tenantId}/{projectId}/notebook/{notebookId}/execution/{executionId}

Obtiene el estado actual y progreso de la ejecución de un cuaderno, incluyendo detalles celda por celda y cualquier error.

Respuesta

{
  "executionId": "bb0e8400-e29b-41d4-a716-446655440000",
  "notebookId": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "Completed",
  "startTime": "2024-01-20T10:30:00Z",
  "endTime": "2024-01-20T10:47:00Z",
  "totalDuration": "17 minutes",
  "progress": {
    "totalCells": 12,
    "completedCells": 12,
    "successfulCells": 11,
    "failedCells": 1,
    "percentComplete": 100
  },
  "cellResults": [
    {
      "cellId": "cell-001",
      "status": "Success",
      "executionTime": "0.5 seconds",
      "hasOutput": false
    },
    {
      "cellId": "cell-002",
      "status": "Success",
      "executionTime": "3.2 seconds",
      "hasOutput": true,
      "outputType": "display_data"
    },
    {
      "cellId": "cell-003",
      "status": "Error",
      "executionTime": "1.1 seconds",
      "errorType": "KeyError",
      "errorMessage": "Columna 'customer_id' no encontrada en el conjunto de datos"
    }
  ],
  "outputs": {
    "dataFrames": 3,
    "plots": 5,
    "models": 2,
    "enrichedData": {
      "recordCount": 15420,
      "newColumns": ["customer_segment", "journey_score", "anomaly_flag"]
    }
  },
  "resources": {
    "peakMemoryUsage": "2.3 GB",
    "cpuTime": "8.5 minutes",
    "diskUsage": "450 MB"
  }
}

Obtener resultados de la ejecución

GET /api/{tenantId}/{projectId}/notebook/{notebookId}/execution/{executionId}/results

Obtiene las salidas y resultados de una ejecución de cuaderno completada, incluyendo datos generados, gráficos y conjuntos de datos enriquecidos.

Parámetros de consulta

Parámetro	Tipo	Descripción
outputType	string	Filtrar por tipo de salida: all, data, plots, models, reports
format	string	Formato de la respuesta: summary, detailed, download
cellId	string	Obtener resultados solo de una celda específica

Respuesta

{
  "executionId": "bb0e8400-e29b-41d4-a716-446655440000",
  "status": "Completed",
  "outputs": [
    {
      "cellId": "cell-002",
      "outputType": "display_data",
      "contentType": "text/html",
      "title": "Resumen del Conjunto de Datos",
      "content": "<div>El conjunto de datos contiene 15,420 registros...</div>",
      "downloadUrl": "https://api.mindzie.com/downloads/cell-002-bb0e8400.html"
    },
    {
      "cellId": "cell-005",
      "outputType": "image/png",
      "title": "Gráfico de Flujo del Recorrido del Cliente",
      "dimensions": {"width": 800, "height": 600},
      "downloadUrl": "https://api.mindzie.com/downloads/cell-005-bb0e8400.png"
    },
    {
      "cellId": "cell-008",
      "outputType": "application/json",
      "title": "Métricas de Minería de Procesos",
      "content": {
        "avgCycleTime": "4.2 horas",
        "bottleneckActivities": ["Revisión de Aplicación", "Aprobación del Gerente"],
        "processEfficiency": 78.5,
        "customerSatisfactionScore": 8.2
      },
      "downloadUrl": "https://api.mindzie.com/downloads/cell-008-bb0e8400.json"
    }
  ],
  "enrichedDatasets": [
    {
      "name": "customer_journey_enhanced",
      "recordCount": 15420,
      "newColumns": ["customer_segment", "journey_score", "anomaly_flag"],
      "format": "pandas_dataframe",
      "downloadUrl": "https://api.mindzie.com/downloads/enriched-bb0e8400.csv"
    }
  ],
  "models": [
    {
      "name": "prediccion_desercion_cliente",
      "modelType": "RandomForestClassifier",
      "accuracy": 0.87,
      "features": ["journey_score", "cycle_time", "touchpoint_count"],
      "downloadUrl": "https://api.mindzie.com/downloads/model-bb0e8400.pkl"
    }
  ],
  "reports": [
    {
      "name": "Resumen de Análisis de Clientes",
      "format": "html",
      "downloadUrl": "https://api.mindzie.com/downloads/report-bb0e8400.html"
    }
  ]
}

Actualizar cuaderno

PUT /api/{tenantId}/{projectId}/notebook/{notebookId}

Actualiza la configuración del cuaderno, las celdas o la configuración de integración. Los cambios en las celdas generarán una nueva versión del cuaderno.

Cuerpo de la solicitud

{
  "notebookName": "Análisis Avanzado de Clientes v2",
  "notebookDescription": "Modelos ML mejorados con capacidades de predicción en tiempo real",
  "integration": {
    "enrichmentMode": true,
    "datasetBinding": "880e8400-e29b-41d4-a716-446655440000",
    "outputFormat": "enriched_dataframe",
    "autoExecution": true,
    "scheduleExecution": "0 2 * * *"
  },
  "environment": {
    "packages": ["pandas", "numpy", "scikit-learn", "tensorflow", "matplotlib"],
    "customLibraries": ["process_mining_utils", "ml_models"]
  }
}

Respuesta

Devuelve el objeto del cuaderno actualizado con número de versión incrementado y marcas de tiempo de modificación.

Eliminar cuaderno

DELETE /api/{tenantId}/{projectId}/notebook/{notebookId}

Elimina permanentemente un cuaderno y todo su historial de ejecuciones. Esta operación no puede deshacerse y detendrá cualquier ejecución en curso.

Códigos de respuesta

• 204 No Content - Cuaderno eliminado exitosamente
• 404 Not Found - Cuaderno no encontrado o acceso denegado
• 409 Conflict - El cuaderno está en ejecución y no puede ser eliminado

Subir cuaderno existente

POST /api/{tenantId}/{projectId}/notebook/upload

Sube un cuaderno Jupyter existente (.ipynb) y lo configura para la integración mindzie. El cuaderno será analizado y sus celdas validadas.

Solicitud (Multipart Form Data)

Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="analysis.ipynb"
Content-Type: application/json

{contenido del cuaderno}
--boundary
Content-Disposition: form-data; name="notebookName"

Análisis del Recorrido del Cliente
--boundary
Content-Disposition: form-data; name="enrichmentMode"

true
--boundary
Content-Disposition: form-data; name="datasetBinding"

880e8400-e29b-41d4-a716-446655440000
--boundary--

Respuesta

Devuelve 201 Created con el objeto del cuaderno subido incluyendo resultados del análisis y cualquier advertencia de validación.

Ejemplo: Flujo completo de cuaderno

Este ejemplo demuestra cómo crear, ejecutar y recuperar resultados de un cuaderno Jupyter:

// 1. Crear un nuevo cuaderno
const createNotebook = async () => {
  const response = await fetch('/api/{tenantId}/{projectId}/notebook', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      notebookName: 'Análisis de Minería de Procesos',
      notebookDescription: 'Análisis avanzado para optimización de procesos',
      kernelType: 'python3',
      template: 'process_mining_starter',
      integration: {
        enrichmentMode: true,
        datasetBinding: '880e8400-e29b-41d4-a716-446655440000',
        outputFormat: 'enriched_dataframe',
        autoExecution: false
      },
      environment: {
        packages: ['pandas', 'numpy', 'scikit-learn', 'matplotlib'],
        customLibraries: ['process_mining_utils']
      },
      initialCells: [
        {
          cellType: 'markdown',
          content: '# Análisis de Minería de Procesos\n\nAnalizando eficiencia de procesos y cuellos de botella.'
        },
        {
          cellType: 'code',
          content: 'import pandas as pd\nfrom mindzie_sdk import ProcessMiningClient\n\nclient = ProcessMiningClient()'
        }
      ]
    })
  });

  return await response.json();
};

// 2. Ejecutar el cuaderno
const executeNotebook = async (notebookId) => {
  const response = await fetch(`/api/{tenantId}/{projectId}/notebook/${notebookId}/execute`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      executionMode: 'all',
      parameters: {
        dataset_id: '880e8400-e29b-41d4-a716-446655440000',
        analysis_period: '2024-01',
        include_weekends: false
      },
      outputOptions: {
        captureOutputs: true,
        saveIntermediateResults: true,
        generateReport: true
      },
      timeout: 1800,
      priority: 'High'
    })
  });

  return await response.json();
};

// 3. Monitorear progreso de ejecución
const monitorNotebookExecution = async (notebookId, executionId) => {
  const checkStatus = async () => {
    const response = await fetch(`/api/{tenantId}/{projectId}/notebook/${notebookId}/execution/${executionId}`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });

    const execution = await response.json();
    console.log(`Estado: ${execution.status}, Progreso: ${execution.progress.percentComplete}%`);

    if (execution.status === 'Running') {
      setTimeout(() => checkStatus(), 15000);
    } else if (execution.status === 'Completed') {
      console.log('¡Ejecución del cuaderno completada!');
      await getNotebookResults(notebookId, executionId);
    } else if (execution.status === 'Error') {
      console.log('Error en la ejecución:', execution.cellResults.filter(c => c.status === 'Error'));
    }
  };

  await checkStatus();
};

// 4. Obtener resultados de la ejecución
const getNotebookResults = async (notebookId, executionId) => {
  const response = await fetch(`/api/{tenantId}/{projectId}/notebook/${notebookId}/execution/${executionId}/results?format=detailed`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  const results = await response.json();
  console.log('Resultados de la Ejecución:', results);
  console.log('Conjuntos de Datos Enriquecidos:', results.enrichedDatasets);
  console.log('Modelos Generados:', results.models);

  return results;
};

// Ejecutar el flujo de trabajo
createNotebook()
  .then(notebook => {
    console.log(`Cuaderno creado: ${notebook.notebookId}`);
    return executeNotebook(notebook.notebookId);
  })
  .then(execution => {
    console.log(`Ejecución iniciada: ${execution.executionId}`);
    return monitorNotebookExecution(execution.notebookId, execution.executionId);
  })
  .catch(error => console.error('Error en el flujo de cuaderno:', error));

Ejemplo en Python

import requests
import time
import json
from pathlib import Path

class NotebookManager:
    def __init__(self, base_url, tenant_id, project_id, token):
        self.base_url = base_url
        self.tenant_id = tenant_id
        self.project_id = project_id
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def create_notebook(self, name, description, kernel_type="python3", template=None, integration=None):
        """Crear un nuevo cuaderno Jupyter"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebook"
        payload = {
            'notebookName': name,
            'notebookDescription': description,
            'kernelType': kernel_type,
            'template': template,
            'integration': integration or {
                'enrichmentMode': True,
                'outputFormat': 'enriched_dataframe',
                'autoExecution': False
            }
        }
        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def upload_notebook(self, file_path, name, dataset_binding=None):
        """Subir un archivo de cuaderno existente"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebook/upload"

        with open(file_path, 'rb') as file:
            files = {'file': (Path(file_path).name, file, 'application/json')}
            data = {
                'notebookName': name,
                'enrichmentMode': 'true',
                'datasetBinding': dataset_binding or ''
            }
            # Eliminar header Content-Type para subida multipart
            headers = {k: v for k, v in self.headers.items() if k != 'Content-Type'}
            response = requests.post(url, files=files, data=data, headers=headers)

        return response.json()

    def execute_notebook(self, notebook_id, parameters=None, timeout=1800):
        """Ejecutar todas las celdas en un cuaderno"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebook/{notebook_id}/execute"
        payload = {
            'executionMode': 'all',
            'parameters': parameters or {},
            'outputOptions': {
                'captureOutputs': True,
                'saveIntermediateResults': True,
                'generateReport': True
            },
            'timeout': timeout,
            'priority': 'Normal'
        }
        response = requests.post(url, json=payload, headers=self.headers)
        return response.json()

    def get_execution_status(self, notebook_id, execution_id):
        """Obtener estado de ejecución del cuaderno"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebook/{notebook_id}/execution/{execution_id}"
        response = requests.get(url, headers=self.headers)
        return response.json()

    def wait_for_completion(self, notebook_id, execution_id, poll_interval=15, timeout=3600):
        """Esperar a que la ejecución del cuaderno complete"""
        start_time = time.time()

        while time.time() - start_time < timeout:
            status = self.get_execution_status(notebook_id, execution_id)
            print(f"Cuaderno {notebook_id}: {status['status']} ({status['progress']['percentComplete']}%)")

            if status['status'] in ['Completed', 'Error', 'Cancelled']:
                return status

            time.sleep(poll_interval)

        raise TimeoutError(f"La ejecución del cuaderno {execution_id} no terminó en {timeout} segundos")

    def get_execution_results(self, notebook_id, execution_id, output_type="all", format_type="detailed"):
        """Obtener resultados de la ejecución del cuaderno"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebook/{notebook_id}/execution/{execution_id}/results"
        params = {
            'outputType': output_type,
            'format': format_type
        }
        response = requests.get(url, params=params, headers=self.headers)
        return response.json()

    def list_notebooks(self, status=None, enrichment_mode=None, page=1, page_size=20):
        """Listar todos los cuadernos con filtrado opcional"""
        url = f"{self.base_url}/api/{self.tenant_id}/{self.project_id}/notebooks"
        params = {'page': page, 'pageSize': page_size}

        if status:
            params['status'] = status
        if enrichment_mode is not None:
            params['enrichmentMode'] = str(enrichment_mode).lower()

        response = requests.get(url, params=params, headers=self.headers)
        return response.json()

# Ejemplo de uso
manager = NotebookManager(
    'https://your-mindzie-instance.com',
    'tenant-guid',
    'project-guid',
    'your-auth-token'
)

try:
    # Crear un cuaderno de minería de procesos
    notebook = manager.create_notebook(
        'Análisis Avanzado de Procesos',
        'Análisis de procesos basado en machine learning con detección de anomalías',
        'python3',
        'process_mining_starter',
        {
            'enrichmentMode': True,
            'datasetBinding': 'dataset-guid',
            'outputFormat': 'enriched_dataframe',
            'autoExecution': False
        }
    )

    print(f"Cuaderno creado: {notebook['notebookId']}")

    # Ejecutar con parámetros personalizados
    execution_params = {
        'dataset_id': 'dataset-guid',
        'analysis_type': 'full_analysis',
        'time_window': '30_days',
        'ml_models': ['anomaly_detection', 'process_prediction'],
        'generate_visualizations': True
    }

    execution = manager.execute_notebook(
        notebook['notebookId'],
        execution_params,
        timeout=2400  # 40 minutos
    )

    print(f"Ejecución iniciada: {execution['executionId']}")
    print(f"Duración estimada: {execution['estimatedDuration']}")

    # Esperar a que termine
    final_status = manager.wait_for_completion(
        notebook['notebookId'],
        execution['executionId']
    )

    if final_status['status'] == 'Completed':
        # Obtener resultados detallados
        results = manager.get_execution_results(
            notebook['notebookId'],
            execution['executionId'],
            'all',
            'detailed'
        )

        print("¡Ejecución del cuaderno completada exitosamente!")
        print(f"Salidas generadas: {len(results['outputs'])}")
        print(f"Conjuntos de datos enriquecidos: {len(results['enrichedDatasets'])}")
        print(f"Modelos ML creados: {len(results['models'])}")

        # Descargar datos enriquecidos
        for dataset in results['enrichedDatasets']:
            print(f"Descargar datos enriquecidos: {dataset['downloadUrl']}")

        # Descargar modelos
        for model in results['models']:
            print(f"Descargar modelo '{model['name']}': {model['downloadUrl']}")

    else:
        print(f"Ejecución del cuaderno falló con estado: {final_status['status']}")
        failed_cells = [cell for cell in final_status['cellResults'] if cell['status'] == 'Error']
        for cell in failed_cells:
            print(f"Falló la celda {cell['cellId']}: {cell['errorMessage']}")

except Exception as e:
    print(f"Error en el flujo de trabajo del cuaderno: {e}")