sanice 1.0.7

Biblioteca fluente para Data Science ágil (ETL, AutoML e Plotting).

(Sistema Automatizado de Normalização, Inteligência Computacional e Estatística)
(System for Automated Normalization, Intelligence, Computation, and Statistics)

🇺🇸 English | 🇧🇷 Português | 🇨🇳   🇮🇳  Multi-language

---

v1.0.7: Database Integration, Smart Optimization & CLI

This massive update expands Sanice's capabilities into **Data Engineering** (SQL/NoSQL) while boosting **Performance** with smart memory management for large datasets.

Database Integration (SQL & NoSQL)

Sanice no longer lives only on CSVs. We added direct connectors for reading and writing to databases:

• SQL Reader (Sanice.from_sql): A factory method to initialize a pipeline reading directly from a SQL query.
  • Supports: PostgreSQL, MySQL, SQLite, Oracle, SQL Server (via SQLAlchemy).
• NoSQL Export (.export_mongo): Native method to send processed data directly to MongoDB collections.

Smart Optimization (Performance)

Added the smart_run=True parameter to the class constructor to solve the "Forest Problem" (High Cardinality):

• Memory Optimization: Automatically detects columns with repetitive data and converts them to category, drastically reducing RAM usage.
• Auto-Date: Scans the dataset for messy text columns that look like dates and converts them automatically.

CLI (Command Line)

The terminal command has been completely overhauled:

• Version Check: Now supports sanice --version or sanice -v.
• Language Intelligence: The command automatically detects the desired language:
  • sanice help -> Opens in English.
  • sanice ajuda -> Opens in Portuguese.
  • sanice bangzhu -> Opens in Chinese.

Installation & Fixes

• New Extras: Use pip install "sanice[db]" to install database dependencies (pymongo, psycopg2).
• Fixes: Fixed setup.py entry points to ensure the sanice executable is correctly created on Windows/Linux.

---

How to update: pip install sanice --upgrade

🇺🇸 English

Sanice is a fluent Python wrapper designed to accelerate Data Science workflows. It abstracts the complexity of Pandas, Scikit-Learn, and FastAPI into a method-chaining interface, allowing you to focus on business logic rather than syntax.

Installation

Standard Installation (Data Science Core):

pip install sanice

Full Installation (Recommended): Includes API support (FastAPI) and Database drivers (Mongo/Postgres)

pip install "sanice[api,db]"

CLI Helper

You can verify installed commands directly from your terminal without opening Python:

sanice help    # 🇺🇸 English
sanice bangzhu # 🇨🇳 Chinese
sanice madad   # 🇮🇳 Hindi

Smart Optimization (v1.0.7+)

Enable smart_run to automatically detect dates and compress memory usage by converting repetitive text to categories.

from sanice import Sanice

# Activates Auto-Date & Memory Optimization
app = Sanice("large_dataset.csv", smart_run=True)

⚡ Quick Start

How to turn a dirty CSV into a deployed AI model in minutes.

from sanice import Sanice

(Sanice("raw_data.csv")
    .fix_columns()                    # Standardize names to snake_case
    .transform("price", "money")      # Cleans money format ("$ 1,000.00" -> 1000.0)
    .drop_nulls()                     # Removes empty rows
    .create_column("total", "price * qty")
    .handle_outliers("total")         # Removes statistical anomalies (IQR)
    .auto_ml(                         # Trains Random Forest & saves model
        target="sold", 
        type="classification", 
        save_path="my_model.pkl"
    )
    .serve_api()                      # Deploys a REST API on localhost:8000
)

Snippets & Command Reference

Here is the complete list of available methods organized by category.

1. Cleaning & ETL

Command	Description
app.fix_columns()	Converts all column names to snake_case.
app.transform(col, rule)	Applies logic: 'money', 'digits', 'email', 'upper', 'lower'.
app.drop_nulls(strategy, val)	Strategy: 'drop' or 'fill'.
app.clean_text([cols])	Strips spaces and converts text to Title Case.
app.convert_date(col, fmt)	Converts a string column to datetime objects.

Use Cases:

• Standardization of data extracted from legacy systems or unformatted Excel sheets.
• Rapid conversion of currency strings to float before calculations.
• Preparation of web form data where users input dates in various formats.

Application Example:

# Cleaning a messy HR dataset
(Sanice("raw_employees.csv")
    .fix_columns()                    # "Emp Name" -> "emp_name"
    .clean_text(["emp_name", "dept"])
    .transform("salary", "money")     # "$ 2,500.00" -> 2500.0
    .convert_date("hire_date")        # String -> Datetime
)

2. Data Manipulation

Command	Description
app.create_column(name, logic)	Creates a column using a string expression or lambda.
app.filter(query)	Filters rows using SQL-like syntax (e.g., "age > 18").
app.sort(col, ascending)	Sorts the dataset by a specific column.
app.join(other_df, keys, how)	Merges two datasets (Left, Right, Inner, Outer).
app.group([cols], val, op)	Groups data and calculates sum, mean, or count.
app.pivot_table(idx, col, val)	Creates a Pivot Table from the data.

Use Cases:

• Feature Engineering (e.g., creating "average ticket" or "days since last purchase").
• Merging "Sales" and "Customers" tables to enrich the dataset (VLOOKUP/JOIN).
• Customer segmentation for specific marketing campaigns.

Application Example:

# Total Sales Analysis by Region
(Sanice("sales.csv")
    .filter("status == 'Completed'")
    .create_column("revenue", "price * quantity")
    .group(
        cols=["region", "category"], 
        value_col="revenue", 
        operation="sum"
    )
    .sort("revenue", ascending=False)
)

3. Database Integration (SQL & NoSQL) v1.0.7+

You can verify installation with pip install "sanice[db]" to enable these features.

Command	Description
Sanice.from_sql(url, query)	Factory Method: Initializes Sanice directly from a SQL query.
app.export_mongo(uri, db, col)	Exports the current dataframe to a MongoDB collection.
app.export_sql(url, table)	Exports to SQL databases (Postgres, MySQL, SQLite).

Example: Reading from Postgres and Saving to MongoDB

from sanice import Sanice

# 1. Read from SQL (PostgreSQL)
app = Sanice.from_sql(
    url_conexao="postgresql://user:pass@localhost/mydb",
    query="SELECT * FROM raw_sales"
)

# 2. Clean & Export to NoSQL (MongoDB)
(app
    .drop_nulls()
    .export_mongo(
        uri="mongodb://localhost:27017",
        database="analytics_db",
        collection="clean_sales"
    )
)

4. Analytics & Visualization

Command	Description
app.describe()	Displays mean, std, min, max, and percentiles.
app.correlation_matrix()	Plots a heatmap of correlations between numeric vars.
app.handle_outliers([cols])	Removes outliers automatically using the IQR method.
app.plot(type, x, y, hue)	Plots charts: 'bar', 'line', 'scatter', 'hist', 'box'.

Use Cases:

• Exploratory Data Analysis (EDA) to understand data profiles before modeling.
• Visual identification of variables that influence the target result (correlation).
• Detection and removal of anomalies (e.g., negative ages or exorbitant prices).

Application Example:

# Rapid Dataset Diagnosis
(Sanice("biological_data.csv")
    .describe()
    .handle_outliers(["age", "glucose"]) # Remove anomalies
    .correlation_matrix()                # Shows influence factors
    .plot("scatter", x="age", y="glucose", hue="diagnosis")
)

5. AI & Machine Learning

Command	Description
app.scale(method)	Normalizes data using 'minmax' or 'standard' scaler.
app.auto_ml(target, type, path)	AutoML pipeline: encodes, splits, trains, and saves model.
app.load_ai(path)	Loads a pre-trained .pkl model into memory.
app.predict(output_col)	Generates predictions using the loaded model.

Use Cases:

• Quick creation of baselines to validate business hypotheses.
• Churn Prediction (customers likely to cancel) or Credit Scoring.
• Demand forecasting based on sales history (Regression).

Application Example:

# Training and using a Churn prediction model
(Sanice("telecom_churn.csv")
    .scale("minmax")
    .auto_ml(target="churn", type="classification", save_path="my_ai.pkl")
)

# ... In another script, loading and predicting:
(Sanice("new_customers.csv")
    .load_ai("my_ai.pkl")
    .predict(output_col="churn_prob")
)

6. Export & Deployment

Command	Description
app.save(path)	Exports data to .csv, .xlsx, or .parquet.
app.export_sql(url, table)	Pushes the dataframe to a SQL database.
app.serve_api()	Starts a FastAPI server to serve predictions.

Use Cases:

• Exporting treated data (Bronze -> Silver) to BI tools like Power BI or Tableau.
• Instant creation of AI microservices for Mobile or Web App integration.
• Persistence of clean data into relational databases (PostgreSQL/MySQL).

Application Example:

# Final Pipeline: Clean -> Save Parquet -> Deploy API
(Sanice("raw_data.csv")
    .fix_columns()
    .auto_ml("target", "regression", "model.pkl")
    .save("clean_data.parquet")   # Data Backup
    .serve_api()                  # API Online at http://localhost:8000
)

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE for details.

---

v1.0.7: Integração com Bancos, Otimização Inteligente e CLI

Esta é uma grande atualização que expande as capacidades de **Engenharia de Dados** do Sanice (SQL/NoSQL) e foca em **Performance** para grandes volumes de dados.

Integração com Banco de Dados (SQL & NoSQL)

Agora o Sanice não vive apenas de CSV. Adicionamos métodos nativos para leitura e escrita:

• Leitura SQL (Sanice.de_sql): Método de fábrica ("Factory method") para iniciar um pipeline lendo diretamente de uma query SQL.
  • Suporta: PostgreSQL, MySQL, SQLite, Oracle, SQL Server (via SQLAlchemy).
• Exportação NoSQL (.exportar_mongo): Método nativo para enviar dados tratados diretamente para coleções do MongoDB.

Otimização Inteligente (Performance)

Adicionamos o parâmetro smart_run=True no construtor da classe para resolver gargalos de memória:

• Otimização de Memória: Detecta automaticamente colunas com alta cardinalidade (muitos dados repetidos) e as converte para category, reduzindo drasticamente o uso de RAM.
• Auto-Date: Varre o dataset em busca de colunas de texto que parecem datas e faz a conversão automática.

CLI (Linha de Comando)

O comando de terminal foi aprimorado:

• Versão: Agora suporta sanice --version ou sanice -v.
• Inteligência de Idioma: O comando detecta a língua desejada automaticamente (sanice ajuda, sanice help, sanice bangzhu).

Instalação e Correções

• Novos Extras: Use pip install "sanice[db]" para instalar as dependências de banco (pymongo, psycopg2).
• Correções: Ajuste no setup.py para garantir a criação correta do executável sanice no Windows/Linux.

---

Como atualizar: pip install sanice --upgrade

🇧🇷 Português

Sanice é um wrapper Python fluido projetado para acelerar fluxos de trabalho de Data Science. Ele abstrai a complexidade do Pandas, Scikit-Learn e FastAPI em uma interface de encadeamento de métodos (method-chaining), permitindo que você foque na lógica de negócios em vez da sintaxe.

Instalação

Instalação Padrão (Núcleo Data Science):

pip install sanice

Instalação Completa (Recomendada): Inclui suporte a API (FastAPI) e drivers de Banco de Dados (Mongo/Postgres)

pip install "sanice[api,db]"

Ajuda no Terminal (CLI)

Você pode verificar os comandos disponíveis direto do seu terminal, sem abrir o Python:

sanice ajuda   # 🇧🇷 Português

Otimização Inteligente (v1.0.7+)

Ative o smart_run para detectar datas automaticamente e comprimir o uso de memória convertendo texto repetitivo em categorias.

from sanice import Sanice

# Ativa Auto-Data e Otimização de Memória
app = Sanice("dados_gigantes.csv", smart_run=True)

⚡ Início Rápido

Como transformar um CSV sujo em um modelo de IA em produção em minutos.

from sanice import Sanice

(Sanice("raw_data.csv")
    .corrigir_colunas()               # Padroniza nomes para snake_case
    .transformar("price", "dinheiro") # Limpa formato monetário ("R$ 1.000,00" -> 1000.0)
    .remover_nulos()                  # Remove linhas vazias
    .criar_coluna("total", "price * qty")
    .tratar_outliers("total")         # Remove anomalias estatísticas (IQR)
    .auto_ml(                         # Treina Random Forest & salva modelo
        alvo="sold", 
        tipo="classificacao", 
        salvar_modelo="my_model.pkl"
    )
    .servir_api()                     # Sobe uma API REST em localhost:8000
)

Snippets e Referência de Comandos

Aqui está a lista completa de métodos disponíveis organizados por categoria.

1. Limpeza e ETL

Comando	Descrição
app.corrigir_colunas()	Converte todos os nomes de colunas para snake_case.
app.transformar(col, rule)	Aplica lógica: 'dinheiro', 'numeros', 'email', 'upper', 'lower'.
app.remover_nulos(strategy, val)	Estratégia: 'apagar' (drop) ou 'preencher' (fill).
app.limpar_texto([cols])	Remove espaços extras e converte texto para Title Case.
app.converter_data(col, fmt)	Converte uma coluna de string para objetos datetime.

Casos de Uso:

• Padronização de dados extraídos de sistemas legados ou planilhas Excel desformatadas.
• Conversão rápida de colunas de moeda brasileira (R$) para float antes de cálculos.
• Preparação de dados de formulários web onde usuários inserem datas em formatos variados.

Exemplo de Aplicação:

# Limpeza de uma base de RH desorganizada
(Sanice("funcionarios_bruto.csv")
    .corrigir_colunas()                 # "Nome Func" -> "nome_func"
    .limpar_texto(["nome_func", "setor"])
    .transformar("salario", "dinheiro") # "R$ 2.500,00" -> 2500.0
    .converter_data("data_admissao")    # String -> Datetime
)

2. Manipulação de Dados

Comando	Descrição
app.criar_coluna(name, logic)	Cria uma coluna usando expressão string ou lambda.
app.filtrar(query)	Filtra linhas usando sintaxe estilo SQL (ex: "age > 18").
app.ordenar(col, ascending)	Ordena o dataset por uma coluna específica.
app.unir(other_df, keys, how)	Une dois datasets (Left, Right, Inner, Outer).
app.agrupar([cols], val, op)	Agrupa dados e calcula soma, média ou contagem.
app.tabela_dinamica(idx, col, val)	Cria uma Tabela Dinâmica a partir dos dados.

Casos de Uso:

• Criação de Features (Feature Engineering) como "ticket médio" ou "dias desde a última compra".
• Unificação de tabelas de "Vendas" e "Clientes" para enriquecer o dataset (VLOOKUP/JOIN).
• Segmentação de base de clientes para campanhas de marketing específicas.

Exemplo de Aplicação:

# Análise de Vendas Totais por Região
(Sanice("vendas.csv")
    .filtrar("status == 'Concluido'")
    .criar_coluna("faturamento", "preco * quantidade")
    .agrupar(
        cols=["regiao", "categoria"], 
        value_col="faturamento", 
        operacao="soma"
    )
    .ordenar("faturamento", ascendente=False)
)

3. Integração com Banco de Dados (SQL & NoSQL) v1.0.7+

Instale com pip install "sanice[db]" para habilitar estas funções.

| Comando | Descrição |

| :--- | :--- |

| Sanice.de_sql(url, query) | Método Fábrica: Inicia o Sanice direto de uma consulta SQL. |

| app.exportar_mongo(uri, db, col)| Exporta o dataframe atual para uma coleção MongoDB. |

| app.exportar_sql(url, tabela) | Exporta para bancos SQL (Postgres, MySQL, SQLite). |

Exemplo: Lendo do Postgres e Salvando no MongoDB

from sanice import Sanice

# 1. Ler do SQL (PostgreSQL)
app = Sanice.de_sql(
    url_conexao="postgresql://user:senha@localhost/meubanco", 
    query="SELECT * FROM vendas_brutas"
)

# 2. Limpar e Exportar para NoSQL (MongoDB)
(app
    .remover_nulos()
    .exportar_mongo(
        uri="mongodb://localhost:27017",
        database="analytics_db",
        collection="vendas_limpas"
    )
)

4. Análise e Visualização

Comando	Descrição
app.resumo_estatistico()	Exibe média, desvio padrão, min, max e percentis.
app.matriz_correlacao()	Plota um mapa de calor das correlações entre vars numéricas.
app.tratar_outliers([cols])	Remove outliers automaticamente usando o método IQR.
app.plotar(type, x, y, hue)	Plota gráficos: 'bar', 'line', 'scatter', 'hist', 'box'.

Casos de Uso:

• Análise Exploratória de Dados (EDA) para entender o perfil dos dados antes da modelagem.
• Identificação visual de variáveis que influenciam o resultado desejado (correlação).
• Detecção e remoção de anomalias (ex: idades negativas ou preços exorbitantes).

Exemplo de Aplicação:

# Diagnóstico rápido de dataset
(Sanice("dados_biologicos.csv")
    .resumo_estatistico()
    .tratar_outliers(["idade", "glicose"]) # Remove anomalias
    .matriz_correlacao()                   # Mostra o que influencia o que
    .plotar("scatter", x="idade", y="glicose", hue="diagnostico")
)

5. IA e Machine Learning

Comando	Descrição
app.escalonar(method)	Normaliza dados usando escalonador 'minmax' ou 'standard'.
app.auto_ml(target, type, path)	Pipeline AutoML: encode, split, treino e salvamento do modelo.
app.carregar_ia(path)	Carrega um modelo .pkl pré-treinado na memória.
app.prever(output_col)	Gera previsões usando o modelo carregado.

Casos de Uso:

• Criação rápida de baselines (modelos de referência) para validar hipóteses.
• Previsão de Churn (clientes que vão cancelar) ou Score de Crédito.
• Previsão de demanda de estoque baseada em histórico de vendas.

Exemplo de Aplicação:

# Treinando e usando um modelo de previsão de Churn
(Sanice("telecom_churn.csv")
    .escalonar("minmax")
    .auto_ml(alvo="churn", tipo="classificacao", salvar_modelo="meu_ia.pkl")
)

# ... Em outro script, carregando e prevendo:
(Sanice("novos_clientes.csv")
    .carregar_ia("meu_ia.pkl")
    .prever(output_col="probabilidade_churn")
)

6. Exportação e Deploy

Comando	Descrição
app.salvar(path)	Exporta dados para .csv, .xlsx ou .parquet.
app.exportar_sql(url, table)	Envia o dataframe para um banco de dados SQL.
app.servir_api()	Inicia um servidor FastAPI para servir previsões.

Casos de Uso:

• Exportação de dados tratados para ferramentas de BI como Power BI.
• Criação instantânea de microserviços de IA para integração com Apps.
• Persistência de dados limpos em bancos relacionais (PostgreSQL/MySQL).

Exemplo de Aplicação:

# Pipeline final: Limpa -> Salva Parquet -> Vira API
(Sanice("dados_brutos.csv")
    .corrigir_colunas()
    .auto_ml("target", "regressao", "modelo.pkl")
    .salvar("dados_limpos.parquet") # Backup dos dados
    .servir_api()                   # API Online em http://localhost:8000
)

---

Multi-language Support / Suporte Multilíngue

Sanice is designed for global people. You can call methods in English, Portuguese, Chinese, or Hindi.
O Sanice foi projetado para equipes globais. Você pode chamar métodos em Inglês, Português, Chinês ou Hindi.

CLICK HERE to see the full Command Translation Table / CLIQUE AQUI para ver a Tabela de Tradução

🇧🇷 PT-BR (Original)	🇺🇸 English	🇨🇳 Chinese (中文)	🇮🇳 Hindi (Hinglish)
corrigir_colunas	fix_columns	修正列名	column_sudhare
limpar_texto	clean_text	清洗文本	text_safai
remover_nulos	remove_nulls	移除空值	null_hataye
converter_data	convert_date	转换日期	date_badlo
criar_coluna	create_column	创建列	column_banaye
filtrar	filter_data	过滤数据	filter_kare
ordenar	sort_data	排序数据	sort_kare
unir	join_data	合并数据	jode
plotar	plot_chart	绘制图表	graph_banaye
resumo_estatistico	stats_summary	统计摘要	stats_dekhe
salvar	save_file	保存文件	save_kare
auto_ml	train_automl	自动训练	automl_kare
carregar_ia	load_ai	加载模型	ai_load_kare
prever	predict	预测	bhavishya_bataye
ver	view	查看	dekhe
ajuda	help	帮助	madad
agrupar	group_by	分组	samuh_banaye
tabela_dinamica	pivot_table	透视表	pivot_table
exportar_sql	export_sql	导出SQL	sql_export
matriz_correlacao	correlation_matrix	相关矩阵	sambandh_matrix
tratar_outliers	handle_outliers	处理异常值	outliers_hataye
escalonar	scale_data	数据缩放	scale_kare
servir_api	serve_api	启动API	api_chalu_kare
transformar	transform	数据转换	badlav_kare
Sanice.de_sql	Sanice.from_sql	Sanice.从SQL	Sanice.sql_se
exportar_mongo	export_mongo	导出Mongo	mongo_bheje

Licença

Este projeto está licenciado sob a Apache License, Version 2.0. Consulte a LICENSE para obter detalhes.

⬆️ Back to Top

"Blind faith is the tool of monsters and fools. Analyze the data."

---

Desenvolvido por wSanice.