Chrematai 📊

A comprehensive Python library for financial risk and return analysis, featuring advanced AI-powered insights and calculations.

Chrematai empowers financial professionals, researchers, and developers with robust tools for quantitative finance and risk management.

---

🚀 Features

• 📈 Financial Risk Metrics: Calculate Value at Risk (VaR), Expected Shortfall, Sharpe Ratio, and more
• 🔍 Return Analysis: Comprehensive return analysis with statistical measures
• 🤖 AI-Powered Insights: Integration with multiple AI providers (OpenAI, DeepSeek, Grok)
• 📊 Financial Statement Analysis: Automated analysis of financial statements
• 📋 Report Generation: Professional financial reports with insights
• 📁 Multiple Data Sources: Support for various data formats (CSV, Excel, JSON, APIs)
• ⚡ High Performance: Optimized calculations using NumPy and Pandas
• 🧪 Well Tested: Comprehensive test suite with high coverage

📦 Installation

Stable Release

pip install chrematai

Development Installation

git clone https://github.com/artaasd95/chrematai.git
cd chrematai
pip install -e ".[dev]"

🏃‍♂️ Quick Start

from chrematai import FinancialAnalyzer
from chrematai.services.ai import AIService

# Initialize the analyzer
analyzer = FinancialAnalyzer()

# Load financial data
data = analyzer.load_data("portfolio_data.csv")

# Calculate risk metrics
risk_metrics = analyzer.calculate_risk_metrics(data)
print(f"Portfolio VaR (95%): {risk_metrics.var_95:.2%}")
print(f"Sharpe Ratio: {risk_metrics.sharpe_ratio:.2f}")

# Generate AI-powered insights
ai_service = AIService(provider="openai")  # or "deepseek", "grok"
insights = ai_service.analyze_financials(data)
print(f"AI Insights: {insights.summary}")

# Generate comprehensive report
report = analyzer.generate_report(data, risk_metrics, insights)
report.save_to_pdf("financial_analysis_report.pdf")

📚 Documentation

Full documentation is available at https://artaasd95.github.io/chrematai/

• Getting Started Guide
• API Reference
• Examples & Tutorials
• User Guide

🏗️ Project Structure

chrematai/
├── 📁 chrematai/           # Main package
│   ├── 📁 services/        # Service layer implementations
│   │   ├── 📁 ai/         # AI service providers
│   │   └── 📁 analysis/   # Financial analysis services
│   ├── 📁 calculations/    # Core financial calculations
│   ├── 📁 data_loader/    # Data loading and processing
│   └── 📄 analyzer.py     # Main analyzer class
├── 📁 tests/              # Comprehensive test suite
├── 📁 docs/               # Documentation source
├── 📁 examples/           # Usage examples
└── 📄 requirements.txt    # Dependencies

🔧 Configuration

Environment Variables

Create a .env file in your project root:

# AI Service API Keys
OPENAI_API_KEY=your_openai_api_key
DEEPSEEK_API_KEY=your_deepseek_api_key
GROK_API_KEY=your_grok_api_key

# Data Sources
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key
QUANDL_API_KEY=your_quandl_key

Basic Configuration

from chrematai.config import Config

config = Config()
config.set_ai_provider("openai")
config.set_risk_level(0.05)  # 5% risk level for VaR calculations
config.set_default_currency("USD")

🧪 Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=chrematai --cov-report=html

# Run specific test file
pytest tests/test_analyzer.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository:

   git clone https://github.com/artaasd95/chrematai.git
   cd chrematai

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install development dependencies:

   pip install -e ".[dev]"

4. Run pre-commit hooks:

   pre-commit install

Code Style

This project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

📊 Performance

Chrematai is optimized for performance with:

• Vectorized operations using NumPy
• Efficient data structures with Pandas
• Caching mechanisms for repeated calculations
• Parallel processing for large datasets

🛣️ Roadmap

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NumPy and Pandas for numerical computing
• OpenAI, DeepSeek, and Grok for AI capabilities
• SciPy for statistical functions
• The open-source financial community

📞 Support

• Documentation: https://artaasd95.github.io/chrematai/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ If you find Chrematai helpful, please give it a star on GitHub! ⭐