🎯 What is AxiomCore?

AxiomCore is a production-ready ML optimization framework that brings enterprise-grade hyperparameter tuning and explainable AI to your local machine. Built for data scientists who need fast, reliable, and interpretable model optimization without the complexity of cloud infrastructure.

Why AxiomCore?

• 🚀 Blazing Fast: Parallel trial execution with intelligent early stopping
• 🎨 Beautiful TUI: Real-time progress tracking with Rich terminal interface
• 🌐 Web Dashboard: Modern Flask-based UI for monitoring and visualization
• 🔍 Explainable AI: Built-in SHAP integration for model interpretability
• ⚙️ Zero Config: Sensible defaults that just work out of the box
• 🐳 Production Ready: Docker support, CI/CD pipelines, and deployment configs

✨ Features

Core Capabilities

• Intelligent Hyperparameter Optimization

  • Random search with adaptive sampling
  • Bayesian optimization support
  • Early stopping with patience-based convergence
  • Parallel trial execution for maximum throughput

• Explainable AI (XAI)

  • SHAP value computation for feature importance
  • Permutation importance analysis
  • Automated insight generation
  • Visual explanations for model decisions

• Real-Time Monitoring

  • Live terminal UI with progress bars
  • Web dashboard with interactive charts
  • Trial history and performance tracking
  • Resource utilization monitoring

• Production Features

  • YAML-based configuration
  • Comprehensive logging
  • Model persistence
  • REST API for integration
  • Docker containerization

📦 Installation

Quick Install

pip install axiomcore-ml

From Source

git clone https://github.com/pizenkov13-boop/AxiomCore.git
cd AxiomCore
pip install -e .

With Optional Dependencies

# Install with XAI support
pip install axiomcore-ml[xai]

# Install with development tools
pip install axiomcore-ml[dev]

# Install everything
pip install axiomcore-ml[xai,dev]

Docker

docker pull ghcr.io/pizenkov13-boop/axiomcore:latest
docker run -p 5000:5000 ghcr.io/pizenkov13-boop/axiomcore:latest

🚀 Quick Start

1. Create Configuration

axiomcore init

This creates a config.yaml with sensible defaults:

task: classification
target_column: target

model:
  name: random_forest
  params:
    n_estimators: 100

hpo:
  strategy: random
  n_trials: 24
  parallel_trials: 4
  enable_early_stop: true
  cv_folds: 5
  scoring: accuracy

xai:
  use_shap: true
  top_k_features: 10

2. Run Optimization

# Basic usage
axiomcore run data.csv

# With web dashboard
axiomcore run data.csv --web

# Custom config
axiomcore run data.csv -c custom_config.yaml

3. Python API

from axiomcore import AxiomCore

# Load configuration
core = AxiomCore.from_yaml('config.yaml')

# Run optimization
result = core.run('data.csv')

# Access results
print(f"Best Score: {result['best_cv_score']:.4f}")
print(f"Best Params: {result['best_params']}")
print(f"Insights: {result['insights']}")

4. Web Dashboard

# Start web server
axiomcore web

# Or run with optimization
axiomcore run data.csv --web

Visit http://localhost:5000 to see the dashboard.

📊 Performance Benchmarks

Speed Comparison

Accuracy Results

Resource Efficiency

Benchmarks run on: Intel i7-9700K, 16GB RAM, Python 3.10

📖 Documentation

Configuration Options

task: classification  # or 'regression'
target_column: target
test_size: 0.2
random_state: 42

model:
  name: random_forest  # xgboost, lightgbm, logistic_regression, etc.
  params:
    n_estimators: 100
    max_depth: 10
    min_samples_split: 2

hpo:
  strategy: random  # or 'bayesian'
  n_trials: 50
  parallel_trials: 4
  enable_early_stop: true
  patience: 5
  min_delta: 0.001
  cv_folds: 5
  scoring: accuracy  # or 'f1', 'roc_auc', 'r2', etc.

xai:
  use_shap: true
  shap_sample_size: 100
  top_k_features: 10
  permutation_repeats: 10

CLI Commands

# Initialize new project
axiomcore init

# Run optimization
axiomcore run <data.csv> [options]

# Start web dashboard
axiomcore web [--port 5000] [--host 0.0.0.0]

# Show version
axiomcore version

Python API

from axiomcore import AxiomCore

# Create from config
core = AxiomCore.from_yaml('config.yaml')

# Or create programmatically
core = AxiomCore(
    task='classification',
    model_name='random_forest',
    n_trials=50,
    parallel_trials=4
)

# Run optimization
result = core.run('data.csv')

# Access components
optimizer = core.optimizer
explainer = core.explainer

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     AxiomCore                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   CLI/API    │  │  Web Server  │  │   REST API   │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
│         │                 │                  │         │
│  ┌──────▼─────────────────▼──────────────────▼──────┐ │
│  │           Core Optimization Engine                │ │
│  │  • HPO Manager  • Model Registry  • Config Mgr   │ │
│  └──────┬─────────────────┬──────────────────┬──────┘ │
│         │                 │                  │         │
│  ┌──────▼──────┐   ┌──────▼──────┐   ┌──────▼──────┐ │
│  │ Hyperparameter│   │   Model     │   │  Explainer  │ │
│  │  Optimizer    │   │  Trainer    │   │   (XAI)     │ │
│  └───────────────┘   └─────────────┘   └─────────────┘ │
│                                                         │
└─────────────────────────────────────────────────────────┘

🤝 Contributing

We love contributions! Here's how you can help:

Getting Started

1. Fork the repository

   git clone https://github.com/pizenkov13-boop/AxiomCore.git
   cd AxiomCore
   

2. Create a virtual environment

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

3. Install development dependencies

   pip install -e ".[dev]"
   

4. Create a feature branch

   git checkout -b feature/amazing-feature
   

5. Make your changes and test

   pytest tests/
   black axiomcore.py
   mypy axiomcore.py
   

6. Commit and push

   git commit -m "Add amazing feature"
   git push origin feature/amazing-feature
   

7. Open a Pull Request

Development Guidelines

• Code Style: We use Black for formatting
• Type Hints: Add type annotations for all functions
• Tests: Write tests for new features (pytest)
• Documentation: Update docs for API changes
• Commits: Use clear, descriptive commit messages

Areas We Need Help

• 🐛 Bug fixes and issue resolution
• 📚 Documentation improvements
• ✨ New optimization strategies
• 🎨 UI/UX enhancements
• 🧪 Additional test coverage
• 🌍 Internationalization

📝 Examples

Classification Example

from axiomcore import AxiomCore
import pandas as pd

# Load data
df = pd.read_csv('iris.csv')

# Configure and run
core = AxiomCore(
    task='classification',
    model_name='random_forest',
    n_trials=30,
    parallel_trials=4
)

result = core.run(df)
print(f"Accuracy: {result['best_cv_score']:.3f}")

Regression Example

from axiomcore import AxiomCore

# Load from config
core = AxiomCore.from_yaml('regression_config.yaml')

# Run with custom scoring
result = core.run('housing.csv')
print(f"R² Score: {result['best_cv_score']:.3f}")

Web Integration

from flask import Flask, jsonify
from axiomcore import AxiomCore

app = Flask(__name__)

@app.route('/optimize', methods=['POST'])
def optimize():
    core = AxiomCore.from_yaml('config.yaml')
    result = core.run('data.csv')
    return jsonify(result)

if __name__ == '__main__':
    app.run(debug=True)

🔧 Deployment

Docker Deployment

FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install axiomcore-ml
CMD ["axiomcore", "web", "--host", "0.0.0.0"]

Railway Deployment

# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway login
railway init
railway up

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: axiomcore
spec:
  replicas: 3
  selector:
    matchLabels:
      app: axiomcore
  template:
    metadata:
      labels:
        app: axiomcore
    spec:
      containers:
      - name: axiomcore
        image: ghcr.io/pizenkov13-boop/axiomcore:latest
        ports:
        - containerPort: 5000

📄 License

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

🙏 Acknowledgments

• Built with scikit-learn for ML algorithms
• Powered by SHAP for explainability
• UI powered by Rich and Flask
• Inspired by Optuna and FastAPI

📞 Support

• 📧 Email: support@axiomcore.dev
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation

🌟 Star History