README

Version: 2.0.0 (formerly Nexus\Intelligence)
Status: Production Ready

A framework-agnostic machine learning orchestration engine providing:

Anomaly Detection via external AI providers (OpenAI, Anthropic, Gemini)
Local Model Inference via PyTorch, ONNX, remote serving (MLflow, TensorFlow Serving)
MLflow Integration for model registry and experiment tracking
Provider Strategy Pattern for flexible AI/ML backend selection

Purpose

The MachineLearning package enables domain packages (Receivable, Payable, Procurement, etc.) to:

Detect Anomalies using external AI services or local ML models
Load and Execute Models from MLflow registry or filesystem
Track Experiments with automated metric logging
Manage Feature Schemas with versioning and compatibility checking
Optimize Costs by selecting appropriate AI providers per domain

Key Features

v2.0 New Capabilities

Provider Strategy Pattern:

Configure AI provider per domain (receivable, payable, procurement, etc.)
Fallback chains for resilience (OpenAI → Anthropic → Rule-Based)
Per-tenant API key configuration via settings

External AI Providers:

OpenAI Provider: GPT-4 with fine-tuning support
Anthropic Provider: Claude 3.5 Sonnet
Google Gemini Provider: Gemini Pro
Rule-Based Provider: Statistical fallback (Z-score anomaly detection)

Inference Engines:

PyTorch Engine: Execute .pth/.pt models via Python subprocess
ONNX Engine: Cross-platform .onnx models via onnxruntime
Remote API Engine: MLflow Serving, TensorFlow Serving, TorchServe

MLflow Integration:

Load models from MLflow model registry
Automatic model versioning (production, staging, archived stages)
Experiment tracking (metrics, parameters, artifacts)
Model format auto-detection (PyTorch, ONNX, TensorFlow)

Core Capabilities (v1.x + v2.0)

Anomaly Detection: Synchronous evaluation (<200ms SLA) for real-time intervention
Feature Extraction: Standardized interface for domain-specific features
Feature Versioning: Schema-based compatibility checking
Usage Tracking: Per-domain, per-tenant cost and token monitoring
Audit Logging: Complete decision trail for compliance (GDPR Article 22)

Layer 1 AI Runtime Contracts

The package now exposes provider-neutral runtime contracts for application layers that need to render, monitor, or probe AI availability without binding to a specific vendor.

AI mode parsing: off, provider, deterministic, plus legacy llm compatibility
Global health states: disabled, healthy, degraded, unavailable
Endpoint groups: document, normalization, sourcing_recommendation, comparison_award, insight, governance
Capability groups: document, normalization, sourcing recommendation, comparison, award, insight, and governance intelligence
Endpoint health snapshots: operator-safe diagnostics for endpoint-group status
Capability status snapshots: typed runtime status entries with stable serialization order
Runtime snapshots: serializable arrays for API and WEB consumers

Architecture

Package Structure (v2.0)

packages/MachineLearning/
├── src/
│   ├── Contracts/              # Public API (23 interfaces)
│   │   ├── AnomalyDetectionServiceInterface.php
│   │   ├── FeatureExtractorInterface.php
│   │   ├── FeatureVersionManagerInterface.php
│   │   ├── ProviderStrategyInterface.php
│   │   ├── HttpClientInterface.php
│   │   ├── ModelLoaderInterface.php
│   │   ├── InferenceEngineInterface.php
│   │   ├── ModelCacheInterface.php
│   │   ├── MLflowClientInterface.php
│   │   └── ...
│   ├── Core/                   # Internal engine
│   │   ├── Providers/          # AI Provider implementations
│   │   │   ├── OpenAIProvider.php
│   │   │   ├── AnthropicProvider.php
│   │   │   ├── GeminiProvider.php
│   │   │   └── RuleBasedProvider.php
│   │   └── Engines/            # Inference engines
│   │       ├── PyTorchInferenceEngine.php
│   │       ├── ONNXInferenceEngine.php
│   │       └── RemoteAPIInferenceEngine.php
│   ├── Services/               # Orchestrators
│   │   ├── MLModelManager.php
│   │   ├── FeatureVersionManager.php
│   │   ├── DomainProviderStrategy.php
│   │   ├── MLflowClient.php
│   │   └── MLflowModelLoader.php
│   ├── ValueObjects/           # Immutable DTOs
│   │   ├── FeatureSet.php
│   │   ├── AnomalyResult.php
│   │   ├── UsageMetrics.php
│   │   ├── ProviderConfig.php
│   │   └── Model.php
│   ├── Enums/                  # PHP 8.3 native enums
│   │   ├── TaskType.php
│   │   ├── SeverityLevel.php
│   │   └── ModelProvider.php

Installation

composer require azaharizaman/nexus-machinelearning:"^2.0"

Requirements:

PHP 8.3+
For local inference: Python 3.8+, PyTorch or ONNX Runtime
For MLflow: MLflow server accessible via HTTP

Quick Start

1. Configure Provider Strategy

// In your Laravel/Symfony service provider
use Nexus\MachineLearning\Contracts\ProviderStrategyInterface;
use Nexus\MachineLearning\Services\DomainProviderStrategy;
use Nexus\MachineLearning\Contracts\SettingsManagerInterface;

$this->app->singleton(ProviderStrategyInterface::class, function ($app) {
    return new DomainProviderStrategy(
        $app->make(SettingsManagerInterface::class)
    );
});

// Configure via settings
$settings->set('machinelearning.providers.receivable', [
    'primary' => 'openai',
    'fallback' => ['anthropic', 'rule_based'],
    'api_keys' => [
        'openai' => env('OPENAI_API_KEY'),
        'anthropic' => env('ANTHROPIC_API_KEY'),
    ],
    'parameters' => [
        'openai' => ['model' => 'gpt-4', 'temperature' => 0.1],
    ],
]);

2. Define Feature Extractor (in Domain Package)

// In packages/Receivable/src/MachineLearning/InvoiceAnomalyExtractor.php
use Nexus\MachineLearning\Contracts\FeatureExtractorInterface;
use Nexus\MachineLearning\ValueObjects\FeatureSet;

final readonly class InvoiceAnomalyExtractor implements FeatureExtractorInterface
{
    public function __construct(
        private HistoricalDataRepositoryInterface $historicalRepo
    ) {}

    public function extract(object $invoice): FeatureSet
    {
        $avgAmount = $this->historicalRepo->getAverageInvoiceAmount(
            $invoice->getCustomerId()
        );
        
        return new FeatureSet(
            features: [
                'amount' => (float) $invoice->getAmount()->getValue(),
                'historical_avg_amount' => (float) $avgAmount,
                'amount_ratio' => $invoice->getAmount()->getValue() / max(1, $avgAmount),
                'days_until_due' => $invoice->getDueDate()->diff(new \DateTimeImmutable())->days,
            ],
            schemaVersion: '1.0',
            metadata: ['customer_id' => $invoice->getCustomerId()]
        );
    }

    public function getFeatureKeys(): array
    {
        return ['amount', 'historical_avg_amount', 'amount_ratio', 'days_until_due'];
    }

    public function getSchemaVersion(): string
    {
        return '1.0';
    }
}

3. Use in Event Listener

// In packages/Receivable/src/Listeners/InvoiceCreatingListener.php
use Nexus\MachineLearning\Contracts\AnomalyDetectionServiceInterface;
use Nexus\MachineLearning\Exceptions\AllProvidersUnavailableException;

final readonly class InvoiceCreatingListener
{
    public function __construct(
        private AnomalyDetectionServiceInterface $mlService,
        private InvoiceAnomalyExtractor $extractor
    ) {}

    public function handle(InvoiceCreatingEvent $event): void
    {
        try {
            $features = $this->extractor->extract($event->invoice);
            $result = $this->mlService->detectAnomalies('receivable', $features);
            
            if ($result->isAnomaly() && $result->getConfidence() >= 0.85) {
                throw new AnomalyDetectedException(
                    "Invoice blocked: {$result->getReason()}. " .
                    "Confidence: {$result->getConfidence()}"
                );
            }
        } catch (AllProvidersUnavailableException $e) {
            // Fail gracefully - allow invoice creation
            Log::warning('ML providers unavailable, skipping anomaly check');
        }
    }
}

Usage Examples

Using External AI Providers

use Nexus\MachineLearning\Contracts\AnomalyDetectionServiceInterface;

$mlService = app(AnomalyDetectionServiceInterface::class);

// Detect anomalies using configured provider (OpenAI, Anthropic, etc.)
$result = $mlService->detectAnomalies('receivable', $features);

if ($result->isAnomaly()) {
    echo "Anomaly detected: " . $result->getReason();
    echo "\nConfidence: " . $result->getConfidence();
    echo "\nSeverity: " . $result->getSeverity()->value;
}

Using Local ML Models with MLflow

use Nexus\MachineLearning\Contracts\ModelLoaderInterface;
use Nexus\MachineLearning\Contracts\InferenceEngineInterface;

$loader = app(ModelLoaderInterface::class);
$engine = app(InferenceEngineInterface::class);

// Load model from MLflow registry (production stage)
$model = $loader->load('invoice_anomaly_detector', version: null, stage: 'production');

// Run inference
$prediction = $engine->predict($model, [
    'amount' => 10000.0,
    'historical_avg_amount' => 5000.0,
    'amount_ratio' => 2.0,
    'days_until_due' => 30,
]);

// Batch predictions
$predictions = $engine->batchPredict($model, $batchData);

Fine-Tuning OpenAI Models

use Nexus\MachineLearning\Core\Providers\OpenAIProvider;
use Nexus\MachineLearning\ValueObjects\ProviderConfig;

$provider = new OpenAIProvider(
    httpClient: $httpClient,
    config: ProviderConfig::create(
        name: 'openai',
        apiKey: env('OPENAI_API_KEY'),
        parameters: ['model' => 'gpt-4']
    ),
    logger: $logger
);

// Submit fine-tuning job
$jobId = $provider->submitFineTuningJob(
    trainingFileId: 'file-xyz123',
    modelName: 'gpt-4',
    suffix: 'receivable-anomaly'
);

Managing Feature Schemas

use Nexus\MachineLearning\Contracts\FeatureVersionManagerInterface;

$versionManager = app(FeatureVersionManagerInterface::class);

// Register feature schema
$versionManager->registerSchema('1.0', [
    'amount' => 'float',
    'historical_avg_amount' => 'float',
    'amount_ratio' => 'float',
    'days_until_due' => 'int',
]);

// Validate compatibility
if (!$versionManager->isCompatible('1.0', $features->getFeatureKeys())) {
    throw new FeatureVersionMismatchException('Feature schema incompatible');
}

Configuration

Provider Configuration (via Settings)

// Configure OpenAI provider for receivable domain
$settings->set('machinelearning.providers.receivable', [
    'primary' => 'openai',
    'fallback' => ['anthropic', 'gemini', 'rule_based'],
    'api_keys' => [
        'openai' => env('OPENAI_API_KEY'),
        'anthropic' => env('ANTHROPIC_API_KEY'),
        'gemini' => env('GEMINI_API_KEY'),
    ],
    'parameters' => [
        'openai' => [
            'model' => 'gpt-4',
            'temperature' => 0.1,
            'max_tokens' => 1000,
        ],
        'anthropic' => [
            'model' => 'claude-3-5-sonnet-20241022',
            'max_tokens' => 1000,
        ],
        'gemini' => [
            'model' => 'gemini-pro',
            'temperature' => 0.1,
        ],
    ],
]);

// MLflow configuration
$settings->set('machinelearning.mlflow.tracking_uri', 'http://localhost:5000');
$settings->set('machinelearning.inference.timeout', 30);

// Feature schema storage
$settings->set('machinelearning.feature_schema.v1', [
    'amount' => 'float',
    'historical_avg_amount' => 'float',
    'amount_ratio' => 'float',
    'days_until_due' => 'int',
]);

Integration with Nexus Packages

Dependencies

Nexus\Setting: Configuration and feature schema storage
Nexus\AuditLogger: Decision audit trail (GDPR compliance)
Nexus\Storage: Model artifact storage (for MLflow downloads)
Nexus\Crypto (optional): API key encryption
Nexus\Telemetry (optional): Metrics tracking

Domain Package Integration

Nexus\Receivable: Invoice anomaly detection (InvoiceAnomalyExtractor)
Nexus\Payable: Vendor bill validation (VendorBillExtractor)
Nexus\Procurement: PO quantity anomaly detection (ProcurementPOQtyExtractor)
Nexus\Sales: Sales forecast prediction (SalesOpportunityExtractor)
Nexus\Inventory: Stock level anomaly detection (StockLevelExtractor)

Migration from v1.x

See: docs/MIGRATION_INTELLIGENCE_TO_MACHINELEARNING.md

Summary of Breaking Changes:

Package namespace: Nexus\Intelligence → Nexus\MachineLearning
Composer package: azaharizaman/nexus-intelligence → azaharizaman/nexus-machinelearning
Service names: IntelligenceManager → MLModelManager, SchemaVersionManager → FeatureVersionManager
Configuration keys: intelligence.schema.* → machinelearning.feature_schema.*

Migration effort: Medium (namespace updates, service bindings, configuration migration)

Testing

# Run package tests
./vendor/bin/phpunit packages/MachineLearning/tests

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage packages/MachineLearning/tests

License

MIT License - See LICENSE file for details.

Package Version: 2.0.0
Last Updated: November 2025
Maintainer: Nexus Architecture Team

Get review queue

Security & Compliance

GDPR Article 22 Compliance

All AI decisions logged to Nexus\AuditLogger
Feature hash stored for reproducibility
Human review option for contestation
Training data collection requires explicit consent

Data Retention

Training data respects tenant-specific retention policies
Automatic cleanup via scheduled command
Anonymization options for sensitive features

Adversarial Protection

Quarterly robustness testing
Real-time adversarial input detection
Automatic blocking on detection

Performance

Synchronous Anomaly Detection

SLA: <200ms response time
Fallback: Rule-based engine on circuit breaker open
Resilience: Circuit breaker, retry, rate limiting via Nexus\Connector

Asynchronous Prediction

Execution: Laravel queue jobs
Tracking: Job ID for status polling
Results: Stored in intelligence_predictions table

Cost Management

Granular Tracking

Per-tenant cost tracking
Per-model cost tracking
Per-domain context tracking
Monthly aggregation for chargeback

Optimization

Automated recommendations for cheaper models
Accuracy impact analysis
Manual approval workflow

Model Lifecycle

Training & Fine-Tuning

Collect training data (requires consent)
Validate minimum 1000 examples
Submit fine-tuning job to provider
Store custom endpoint per tenant
Automatic usage on subsequent requests

Versioning & Deployment

Create new model version
Deploy via blue-green strategy
Monitor accuracy for 24 hours
Auto-rollback if accuracy drops >10%
Promote to active if successful

Health Monitoring

Daily health check
30-day rolling accuracy calculation
Drift detection (>15% threshold)
Automatic retraining request creation
Manual approval workflow

📖 Documentation

Comprehensive documentation is available in the docs/ folder:

Getting Started

Getting Started Guide - Quick start, prerequisites, basic configuration
Migration from v1.x - Upgrade guide for existing users

Technical Reference

API Reference - Complete interface and method documentation
Integration Guide - Laravel and Symfony integration examples
Requirements - Detailed requirements specification (52 requirements)

Code Examples

Basic Usage - Simple anomaly detection examples
Advanced Usage - MLflow, custom providers, batch processing

Project Documentation

Implementation Summary - Development progress, metrics, decisions
Test Suite Summary - Test coverage, results, strategy
Valuation Matrix - Package value assessment and ROI analysis

License

MIT License - see LICENSE file for details.

Author

Azahari Zaman

azaharizaman / nexus-machine-learning

Maintainers

Package info

Statistics

Security

README

Purpose

Key Features

v2.0 New Capabilities

Core Capabilities (v1.x + v2.0)

Layer 1 AI Runtime Contracts

Architecture

Package Structure (v2.0)

Installation

Quick Start

1. Configure Provider Strategy

2. Define Feature Extractor (in Domain Package)

3. Use in Event Listener

Usage Examples

Using External AI Providers

Using Local ML Models with MLflow

Fine-Tuning OpenAI Models

Managing Feature Schemas

Configuration

Provider Configuration (via Settings)

Integration with Nexus Packages

Dependencies

Domain Package Integration

Migration from v1.x

Testing

License

Get review queue

Security & Compliance

GDPR Article 22 Compliance

Data Retention

Adversarial Protection

Performance

Synchronous Anomaly Detection

Asynchronous Prediction

Cost Management

Granular Tracking

Optimization

Model Lifecycle

Training & Fine-Tuning

Versioning & Deployment

Health Monitoring

📖 Documentation

Getting Started

Technical Reference

Code Examples

Project Documentation

License

Author