Metadata-Version: 2.4
Name: coremlflow
Version: 0.0.2
Summary: Coreflow - Abstração de Funções para MLFlow não oficial.
Author: Willian Marchi
Author-email: willian.m.marchi@gmail.com
License: MIT License
Keywords: coremlflow mlflow core
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: mlflow
Provides-Extra: sklearn
Requires-Dist: scikit-learn; extra == "sklearn"
Provides-Extra: prophet
Requires-Dist: prophet; extra == "prophet"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# Guia de Desenvolvimento: Modelos e InferÃªncia no coremlflow

Este guia explica como criar scripts de **Treinamento (`train.py`)** e **PrediÃ§Ã£o/InferÃªncia (`predict.py`)** utilizando o framework base da biblioteca `coremlflow`.

A arquitetura orientada a objetos obriga a implementaÃ§Ã£o de mÃ©todos especÃ­ficos para padronizar o ciclo de vida do modelo e a integraÃ§Ã£o automÃ¡tica com o MLflow.

---

## ðŸš€ 1. Criando um Modelo de Treinamento (`train.py`)

Com o `coremlflow`, vocÃª tem a opÃ§Ã£o de herdar da classe base genÃ©rica ou utilizar as **abstraÃ§Ãµes especÃ­ficas** construÃ­das para os principais frameworks de Data Science.

### A. Utilizando as Classes Especializadas (Recomendado)

O pacote `coremlflow.models` provÃª classes preparadas que jÃ¡ implementam automaticamente a melhor forma de salvar o seu modelo (ex: usando `mlflow.sklearn` ou `mlflow.prophet`).

#### Exemplo: Random Forest
Para Random Forest ou Isolation Forest, herde das classes em `coremlflow.models.sklearn`:

```python
import pandas as pd
from typing import Dict, Any
from sklearn.ensemble import RandomForestClassifier
from coremlflow.models.sklearn import RandomForestMLFlowModel

class MeuModeloRF(RandomForestMLFlowModel):
    def __init__(self, experiment_name: str, data_path: str, tracking_uri: str = None):
        super().__init__(experiment_name, tracking_uri)
        self.data_path = data_path 
    
    def load_data(self) -> Dict[str, Any]:
        # Exemplo carregando dados de Treino/Teste
        return {"X_train": [...], "y_train": [...], "X_test": [...], "y_test": [...]}

    def train(self, data: Dict[str, Any], params: Dict[str, Any]) -> Any:
        model = RandomForestClassifier(**params)
        model.fit(data["X_train"], data["y_train"])
        return model

    def evaluate(self, model: Any, data: Dict[str, Any]) -> Dict[str, float]:
        # Calcule e retorne suas mÃ©tricas
        score = model.score(data["X_test"], data["y_test"])
        return {"accuracy": score}

    def get_signature_data(self, model: Any, data: Dict[str, Any]) -> tuple:
        return (data["X_train"], data["y_train"])
```
*Note que nÃ£o foi necessÃ¡rio implementar o mÃ©todo `save_model()`, pois ele jÃ¡ foi abstraÃ­do pela classe mÃ£e `RandomForestMLFlowModel`.*

#### Outros modelos suportados nativamente:
- `IsolationForestMLFlowModel` (em `coremlflow.models.sklearn`)
- `ProphetMLFlowModel` (em `coremlflow.models.prophet`)

### B. Utilizando a Classe Base GenÃ©rica

Se vocÃª estiver treinando um modelo Keras, PyTorch, ou outro ainda nÃ£o mapeado nas classes filhas nativas, basta herdar nativamente da `MLFlowModelBase` e definir seu `.save_model()`.

```python
from coremlflow.base import MLFlowModelBase
import mlflow.keras

class MeuModeloGenerico(MLFlowModelBase):
    # ... defina load(), train(), evaluate(), get_signature_data() ...
    
    def save_model(self, model, signature) -> None:
        # [ObrigatÃ³rio na Base]
        mlflow.keras.log_model(model, artifact_path="model", signature=signature)
```

### Executando o Treinamento

Para rodar, instancie a sua classe e chame o mÃ©todo genÃ©rico `run(params)`. Ele vai orquestrar todas as chamadas garantindo o log correto no MLflow.

```python
if __name__ == "__main__":
    predictor = MeuModeloRF(experiment_name="Projeto_Churn", data_path="dados.csv")
    params = {"n_estimators": 100, "max_depth": 5}
    
    modelo = predictor.run(params=params)
```

---

## ðŸ”® 2. Consumindo um Modelo em ProduÃ§Ã£o (`predict.py`)

Ao fazer a inferÃªncia, importe o `MLFlowPredictorBase`.

Essa classe cuida internamente do carregamento do modelo a partir do Registry do MLflow. Se o Tracking Server do MLflow estiver fora do ar, vocÃª ainda pode fornecer um `local_model_path` como *fallback*.

### Estrutura da Classe de PrediÃ§Ã£o

Opcionalmente, vocÃª pode sobrescrever o mÃ©todo `predict`, mas por base, a classe jÃ¡ traz o comportamento chamando recursivamente o modelo baixado no formato `pyfunc`.

```python
from coremlflow.predictor import MLFlowPredictorBase

# VocÃª pode usar a classe base diretamente:
servico_ia = MLFlowPredictorBase(
    internal_alias="CHURN_PROD",
    internal_alias_map_path="./mlflow_aliases.json",
    local_model_path="./modelos_backup/rf_model_v1" # Fallback opcional offline
)

# Os resultados dependerÃ£o da natureza do modelo treinado.
resultados = servico_ia.predict(dados_de_entrada)
```

Ou, caso vocÃª precise criar um fluxo complexo de tratamento de dados de entrada antes / depois de passar pelo `.predict()`:

```python
class SeuPredictorService(MLFlowPredictorBase):
    def predict(self, input_data):
        # 1. Trata input_data (ex: limpeza, feature engineering)
        dados_tratados = limpar(input_data)
        
        # 2. Chama a prediÃ§Ã£o da classe base
        resultado = super().predict(dados_tratados)
        
        # 3. PÃ³s Processa
        return formatar(resultado)
```

Exemplo de arquivo `./mlflow_aliases.json` (apelido interno -> run_id):

```json
{
  "CHURN_PROD": "a1b2c3d4e5f6g7h8i9j0",
  "FORECAST_PROD": { "run_id": "ffffeeee111122223333444455556666", "artifact_path": "model" }
}
```
