Metadata-Version: 2.4
Name: finomaly
Version: 0.1.5
Summary: A rule-based and machine learning-based anomaly detection library for financial transactions.
Author: Barisaksel
Project-URL: Source, https://github.com/Barisaksel/finomaly
Project-URL: PyPI, https://pypi.org/project/finomaly/
Keywords: anomaly detection,financial,machine learning,rule-based,fraud,outlier,python,data science,fintech,unsupervised learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scikit-learn
Requires-Dist: numpy
Requires-Dist: fpdf
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: pandas
Requires-Dist: xgboost
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# Finomaly
## PyPI & Source Code

**PyPI:** https://pypi.org/project/finomaly/

**Source Code:** https://github.com/Barisaksel/finomaly



Finomaly is a modular, open-source Python library for anomaly detection in financial transactions. It supports both rule-based and machine learning-based detection, multi-language reporting, and professional reporting formats.

## 🆕 NLP Modules & Language-Aware Message Management


### TextEmbeddingAnomalyDetector
Provides text anomaly detection using TF-IDF vectorization and IsolationForest. All error and user messages are centrally managed and support multiple languages.

**Usage:**
```python
from finomaly.nlp.embeddings import TextEmbeddingAnomalyDetector

# You can provide a list of texts, or an Excel file path and column name.
texts = ["Money transfer completed", "Credit card purchase", "Suspicious transaction"]
detector = TextEmbeddingAnomalyDetector(lang='en')
detector.fit(texts)
anomalies = detector.predict(["Very large amount transfer"])
print(anomalies)

# Or load texts directly from an Excel file:
# detector.fit('transactions.xlsx', column='Description')
# anomalies = detector.predict('new_transactions.xlsx', column='Description')
```


### TransactionDescriptionClassifier
Categorizes transaction descriptions using TF-IDF and Logistic Regression. All messages are centrally managed and support multiple languages.

**Usage:**
```python
from finomaly.nlp.text_classifier import TransactionDescriptionClassifier

# You can provide lists, or load from Excel file with text and label columns.
texts = ["Grocery shopping", "Bill payment", "ATM withdrawal"]
labels = ["Shopping", "Bill", "Cash"]
clf = TransactionDescriptionClassifier(lang='en')
clf.fit(texts, labels)
pred = clf.predict(["Electricity bill"])
print(pred)

# Or load texts and labels from Excel:
# import pandas as pd
# df = pd.read_excel('train.xlsx')
# clf.fit(df['Description'], df['Category'])
# pred = clf.predict(['Electricity bill'])
```

### Multi-Language Support & Message Management
- All error and user messages are centrally managed in `finomaly/core/messages_config.json` according to the selected language.
- If a message key or language is missing, the system automatically returns the default English message without raising an error.

### Requirements
- scikit-learn, pandas, numpy
- (For NLP) openpyxl (Excel support), language file: messages_config.json

## Features
- Rule-based anomaly detection (JSON-configurable, customer-specific rules)
- Machine learning models: IsolationForest, RandomForest, XGBoost
- NLP modules: TextEmbeddingAnomalyDetector (text anomaly), TransactionDescriptionClassifier (text classification)
- Profile-based analysis (behavioral deviation, unusual time, etc.)
- Multi-language support (TR/EN) for all messages and reports
- Centralized message and rule management (with fallback to default language)
- Professional reporting: Excel, HTML, PDF (with optional charts)
- Visual analytics: anomaly distribution, scatter plots
- Easy integration, clean API, and extensible modular structure

## Installation
```bash
pip install finomaly
```

## Quick Start
```python
import pandas as pd
from finomaly.core.anomaly_system import CorporateAnomalySystem

# Load your data
train_df = pd.read_excel('train.xlsx')
predict_df = pd.read_excel('predict.xlsx')

# Define features and rules
features = ['Tutar', 'Saat']
rules_path = 'rules.json'

# Initialize system
system = CorporateAnomalySystem(features, rules_path=rules_path, ml_method='isolation_forest', lang='en')

# Train model
system.fit('train.xlsx', customer_col='MusteriID', amount_col='Tutar')

# Predict anomalies
output_path = system.predict('predict.xlsx', customer_col='MusteriID', amount_col='Tutar')
result = pd.read_excel(output_path)
print(result.head())
```

## Reporting & Visualization
```python
from finomaly.report.visualizer import Visualizer
from finomaly.report.pdf_reporter import PDFReporter

visualizer = Visualizer()
visualizer.plot_anomaly_distribution(result, amount_col='Tutar', anomaly_col='ML_Anomaly')

pdf_reporter = PDFReporter()
pdf_reporter.generate_pdf_report(result, 'report.pdf')
```

## Project Structure
- `core/` : Rule engine, model management, utilities
- `ml/` : ML models (IsolationForest, RandomForest, XGBoost)
- `profile/` : Profile-based analysis (behavioral, time-based)
- `report/` : Reporting and visualization (Excel, HTML, PDF, charts)

## Contributing
Finomaly is open-source and welcomes contributions. Please open issues or pull requests for improvements, bug fixes, or new features.

## License
MIT License

## Author
Barış
