Hint Engine

Overview

Hint engine rules works similarly to https://ilabo.atlassian.net/wiki/spaces/LW/pages/1774420110, it allows you to fine-tune PackOS automatic data analysis for your needs. By defining a set of functions, you can teach PackOS how to spot interesting patterns in observed data and send you and your crew notifications about them.

To enter the editor, select “Hint rules” in the “Advanced” section:

And select “+” to create a new function, or select one of the functions from the list to open the editor:

Each function defines:

Name
Trigger - when the function will be executed, you can select an explicit time period like ‘end of hour’ or ‘end of day’. Or run the function when an order or shift ends. The list of currently available triggers (can be extended in the future):
- Every 10 minutes
- End of hour
- After order
- After shift
- At midnight - (defined by factory timezone)
- At end of day - (hour defined by factory setup and timezone)
- At the end of week - (end of day, before the configured ‘start of week’)
- At the end of month - (end of day, last day of month)
Script - the body of your hint function, allowed statements and examples are described below
Test execution box - allows you to execute the script and inspect the result without generating actual hints.
- Store parameters - when selected, all parameters generated by the script will be persisted in the database
- Add parameter - let’s you inject/overwrite custom parameters, just for this run

Script

The body of the script should be a C# method, following the syntax and conventions defined by this language. We recommend the official Microsoft documentation:

https://learn.microsoft.com/en-us/dotnet/csharp/

In the script, the following variables are available:

DateTime Now - current time

Library - set of predefined functions which are available out of the box, constantly extended and tuned by Ilabo team. Described below.

IOrderProvider Orders - provider of orders

public interface IOrderProvider
{
    // returns started and completed orders in the specified time period
    public Task<ICollection<Order>> GetExecutedOrders(Guid lineId, DateTime from, DateTime to);
}

public record Order(
    Guid LineId,
    string Status,
    DateTime StartDate,
    DateTime? EndDate);

IAssetProvider Assets - provider of factory assets

public interface IAssetProvider
{
    // returns all lines in the factory
    Task<ICollection<Element>> GetLines();

    // returns all machines in the factory
    Task<ICollection<Element>> GetMachines();
}

public record Element(
    Guid Id, 
    Guid? ParentId,
    string Code, 
    string Name, 
    string Path,
    string Type);

IProductionProvider Production - provider of production data

public interface IProductionProvider
{
    // Returns bucket with aggregated production, waste and time loss classes 
    Task<BucketInfo> GetBucket(string elementName, DateTime from, DateTime to);
    
    // Returns bucket with aggregated production, waste and time loss classes
    Task<BucketInfo> GetBucket(Guid elementId, DateTime from, DateTime to);

    // Returns aggregated production and waste in multiple time periods
    Task<ICollection<Production>> Get(ICollection<ProductionRequest> requests);

    // Returns aggregated production and waste in selected time period
    Task<ICollection<Production>> Get(ICollection<Guid> elementIds, string? unit, DateTime from, DateTime to);

    // Returns base units for selected elements (lines/machines)
    Task<Dictionary<Guid, string>> GetUnits(ICollection<Guid> elementIds);

    // Returns metadata about elements (lines/machines)
    Task<ICollection<ElementStatus>> GetStatus(ICollection<Guid> elementIds);
}

public record BucketInfo(
    Guid ElementId,
    string Unit,
    double Done,
    double Wasted,
    double Planned,
    DateTime From,
    DateTime To,
    TimeSpan QualityLoss,
    TimeSpan PerformanceLoss,
    TimeSpan AvailabilityLoss,
    TimeSpan UtilizationLoss,
    TimeSpan TotalTime,
    bool IsUnitConversionComplete);

public record Production(
    Guid ElementId,
    DateTime From,
    DateTime To,
    string Unit,
    double Done,
    double Wasted,
    bool IsUnitConversionComplete);

public record ElementStatus(
    Guid ElementId,
    bool IsBaseAvailability,
    bool IsBaseQuantity,
    bool IsDummy,
    bool IsAlive,
    string Kind,
    string Name,
    string Path,
    DateTime KeepAlive);

IWorkLogProvider WorkLogs - provider for data about machine states

IParameterStore ParameterStore - service which allows requesting and persisting custom parameters

You can use all of the above variables/providers/services to request data of interest, make calculations and generate hints/warnings for your crew.

The function should return a new object of class HintFunctionOutput containing a list of Hints. Each Hint is defined as:

Examples

Request work history for the 'Line1' and create a hint with a simple count

Use pre-defined library function to generate CounterMismatch hints:

Library functions

The following hints are pre-defined in the library, and can be easily executed:

`DowntimeFrequencyIncrease` - Detect an increasing number of downtimes of specific type

Calculates and stores as a parameter the ‘usual number of downtimes’ for each observed downtime type in the time period defined as ‘timeSpan’.
In essence, ‘usual number' is calculated by aggregating the number of downtimes of each type for each hour, creating a histogram, and retrieving 95th percentile.
When executing the Build command, you can choose to run it only for a specific element by providing elementPath or selecting a different percentile cutoff for the algorithm.
Creates a list of IncreasedDowntimeFrequency objects, each describing an interesting instance of increased downtime frequency. You can filter or aggregate the result, use it to generate new hints, or calculate other parameters. Each entry contains the following details:
Note that the Run function can only be executed after the Build method pre-calculating statistics. We recommend to separate this process into 2 functions:
- Build should be executed once a week/ once a month.
- Run can be executed every hour/after a shift etc.
Will add new hints to the output using a default formatter (in english)

`CounterMismatch` - Detect inconsistent production count for two different machines of the same line

Analyse production count in the defined by timeSpan time period. Production output of each machine is compared to the BaseQuantity machine. Units are converted if necessary. If the difference between counts exceeds the allowed threshold. An object MachineCounterMismatch with details is returned:
Will add new hints to the output using a default formatter (in english)

`ProductionWithoutOrder` - Detect when the line was producing without any running order

Analyse the production and orders in the provided checkDuration. This period of time is analyse in the context of orders and production. If there is some production in this period of time which is not part of any order - a new instance of ProductionWithoutOrderModel is raised with the following details:

Will add new hints to the output using a default formatter (in english)