Binom.AutoML.IPCClient 1.2.3

Binom.AutoML IPC Client

Binom.AutoML.IPCClient is a high-performance .NET client designed to interact with the Binom.AutoML host via Named Pipes and MessagePack. It provides a strongly-typed, async API for managing the entire machine learning lifecycle—from experiment creation and data import to training and prediction.

Key Features

• Strongly Typed API: Full implementation of IBinomAutoML with async support.
• Fluent Configuration: Powerful Builder pattern for creating complex experiment settings easily.
• Real-time Feedback: Event-driven architecture for monitoring training progress, logs, and status changes.
• Robust Connection: Automatic connection management and contract version validation.
• High Performance: Uses PipeMethodCalls and MessagePack for efficient IPC communication.

Table of Contents

1. Installation
2. Quick Start
3. Client Configuration
4. Experiment Configuration (Fluent API)
5. Data Management
6. Training Lifecycle
7. Prediction
8. Events & Monitoring
9. Error Handling

Installation

To use the client, reference the following projects or packages in your solution:

• Binom.AutoML.IPCClient
• Binom.AutoML.Contracts

Ensure that the major versions of the Client and Contracts match the Server version to guarantee compatibility.

Quick Start

Here is a minimal example to get you connected and listing experiments.

1. Implement a Logger

The client uses IClientLogger for internal logging. You can implement a simple console logger:

using Binom.AutoML.IPCClient;

public class ConsoleLogger : IClientLogger
{
    public void LogInformation(string message, params object[] args) => 
        Console.WriteLine($"[INFO] {string.Format(message, args)}");
    public void LogWarning(string message, params object[] args) => 
        Console.WriteLine($"[WARN] {string.Format(message, args)}");
    public void LogError(Exception ex, string message, params object[] args) => 
        Console.WriteLine($"[ERROR] {string.Format(message, args)}\n{ex}");
    public void LogDebug(string message, params object[] args) => 
        Console.WriteLine($"[DEBUG] {string.Format(message, args)}");
}

2. Connect and Use

using Binom.AutoML.IPCClient;

public async Task RunQuickStartAsync()
{
    // Initialize client
    using var client = new BinomAutoMLClient(new BinomAutoMLClientOptions 
    { 
        Logger = new ConsoleLogger(),
        DiscoveryPipeName = "binom-automl-discovery" // Default
    });

    // Connect to server
    await client.ConnectAsync();
    Console.WriteLine("Connected!");

    // List experiments
    var result = await client.GetAllExperimentsAsync();
    if (result.IsSuccess)
    {
        foreach (var exp in result.Value)
        {
            Console.WriteLine($"Experiment: {exp.Name} [{exp.Status}]");
        }
    }

    // Disconnect
    await client.DisconnectAsync();
}

Client Configuration

The BinomAutoMLClient is configured via BinomAutoMLClientOptions.

var options = new BinomAutoMLClientOptions
{
    // The named pipe used to discover the active session. 
    // Must match the server's configuration.
    DiscoveryPipeName = "binom-automl-discovery", 

    // Logger implementation for client internal logs.
    Logger = new ConsoleLogger() 
};

var client = new BinomAutoMLClient(options);

Experiment Configuration (Fluent API)

The library provides a Fluent Builder API in the Binom.AutoML.IPCClient.Builders namespace. This is the recommended way to create experiment settings, as it guides you through valid configurations for different task types (Regression, Classification, etc.).

1. Initialize the Builder

Start with BaseExperimentLayoutBuilder. You need to pass an instance of IBinomAutoML (the client itself) to it, although strictly speaking for settings generation it acts as a factory entry point.

using Binom.AutoML.IPCClient.Builders;

var builder = new BaseExperimentLayoutBuilder(client)
    .SetExperimentName("My Prediction Model")
    .SetOwnerID("User123")
    .SetNormalizationMethod(NormalizationMethodDto.MinMax);

2. Configure Specific Task

Chain methods to configure the specific ML task.

Regression Example

var regressionBuilder = builder.ForRegressionTask()
    .SetOptimizationMetric(RegressionOptimizingMetricDto.RSquared)
    .WithAllowedTrainers(RegressionTrainerDto.LightGbm, RegressionTrainerDto.FastTree);
    
// You can also use a sub-builder for trainers
regressionBuilder.WithTrainers()
    .Clear()
    .Add(RegressionTrainerDto.LbfgsPoissonRegression)
    .And(); // Returns to parent builder

Binary Classification Example

var binaryBuilder = builder.ForBinaryClassificationTask()
    .SetOptimizationMetric(BinaryClassificationOptimizingMetricDto.AreaUnderRocCurve)
    .WithAllowedTrainers(BinaryClassificationTrainerDto.LightGbm);

3. Create the Experiment

Once configured, use the client to create the experiment using the settings generated by the builder. Note: The builder currently constructs the ExperimentSettingsDto. You pass this DTO to the client.

// Access the underlying settings DTO from the builder
// (Assuming the builder exposes it or you construct it based on the builder's state. 
// Based on current code analysis, the builder holds the state in _settingsDto)

// Example of creating experiment with manually constructed settings or via builder if exposed:
var settings = new ExperimentSettingsDto 
{
    ExperimentName = "Manual Config",
    ExperimentType = ExperimentTypeDto.Regression,
    // ... other properties
};

var createResult = await client.CreateExperimentAsync(settings);
string experimentId = createResult.Value.Id;

(Note: If the Build() method is not publicly exposed in the current version of builders, you may need to access the settings directly or use the builder to configure a DTO instance you provide.)

Data Management

Once an experiment is created, you need to feed it data.

Import Data

Supported formats depend on the server (typically CSV/TSV).

// Import from file path
await client.ImportDataFromFileAsync(experimentId, @"C:\Data\dataset.csv");

// Or import from byte array
byte[] data = File.ReadAllBytes("dataset.csv");
await client.ImportDataAsync(experimentId, data, "dataset.csv");

Add Single Data Point

Useful for real-time updates or streaming data.

var point = new GeneralDataPointDto 
{ 
    // ... properties mapping to your data columns
};
await client.AddDataPointAsync(experimentId, point);

Inspect Data

Check what the server understood from your data.

var info = await client.GetDataInfoAsync(experimentId);
Console.WriteLine($"Columns detected: {info.Value.Columns.Count}");

Training Lifecycle

Manage the training process asynchronously.

Start Training

var startResult = await client.StartTrainingAsync(experimentId);
if (!startResult.IsSuccess)
{
    Console.WriteLine($"Error: {startResult.ErrorMessage}");
}

Monitor Status

You can poll the status:

var status = await client.GetTrainingStatusAsync(experimentId);
Console.WriteLine($"Current Status: {status.Value.Status}");

Cancel Training

await client.CancelTrainingAsync(experimentId);

Get Results

After training completes, retrieve detailed metrics.

var results = await client.GetTrainingResultsAsync(experimentId);
Console.WriteLine($"Best Score: {results.Value.BestScore}");

Prediction

Use the best model found during training to make predictions.

Get Best Model

var modelInfo = await client.GetBestModelAsync(experimentId);
Console.WriteLine($"Best Trainer: {modelInfo.Value.TrainerName}");

Make Prediction

var inputData = new PredictionDataDto
{
    // Populate with feature values
};

var prediction = await client.PredictAsync(experimentId, inputData);

Console.WriteLine($"Predicted Value: {prediction.Value.PredictedValue}");
if (prediction.Value.Scores != null)
{
    foreach (var score in prediction.Value.Scores)
    {
        Console.WriteLine($"{score.Key}: {score.Value}");
    }
}

Events & Monitoring

The client exposes C# events that trigger when the server pushes updates. This is the best way to build reactive UIs or logs.

// Experiment Status Changes
client.OnExperimentStatusChangedEvent += async (e) => 
{
    Console.WriteLine($"Experiment {e.ExperimentId} changed to {e.NewStatus}");
};

// Real-time Training Log
client.OnTrainingLogReceivedEvent += async (expId, message) =>
{
    Console.WriteLine($"[Server Log] {message}");
};

// Training Progress (per trial)
client.OnTrainingProgressEvent += async (e) =>
{
    Console.WriteLine($"Trial {e.TrialNumber} finished. Score: {e.Score}");
};

// Training Completed
client.OnTrainingCompletedEvent += async (e) =>
{
    Console.WriteLine($"Training finished! Success: {e.IsSuccess}");
};

Error Handling

The client uses specific exceptions to indicate failure categories:

• BinomClientConnectionException: Network issues, pipe errors, or contract version mismatches.
• BinomClientException: Logical errors or server-side validation failures returned as exceptions.
• ObjectDisposedException: Attempting to use the client after Dispose().

Always check the OperationResultDto.IsSuccess property for logical failures that don't throw exceptions (e.g., "Experiment not found").

try 
{
    await client.ConnectAsync();
}
catch (BinomClientConnectionException ex)
{
    Console.WriteLine("Could not connect to AutoML server. Is it running?");
}