Zaria.AI 1.0.5

Zaria.AI

This framework provides a simple, attribute-driven, low-code API for building text based interactive dialogs. It Can be used to build AI BOTs, CLIs, general command processing and much more!

Release 1.0.5 Notes

Added wildcard placeholders that can be used similar to standard placeholders. In the sample below, a wildcard placeholder that will take the name my_placeholder is specified.

*my_placeholder

There can only be 1 wildcard placeholder in a pattern. It must also be the last placeholder in any pattern string so:

• copy *files (works)
• copy *files now (throws error)
• *files (ignored)

wildcard placeholders are usefull in scenarios where the string that needs to be parsed requires different word boundaries for each segment. Take the example read @book @chapter : @verse. The input string read john 3 : 16 would satisfy it but any of the following would not.

• john 3:16
• john 3: 16
• john 3 :16

we can resolve this by applying different parsing rules to the "book" part and the "chapter/verse part" of the pattern. The following sample illustrates using a workflow, storing and retrieving pipeline variables and using wildcard placeholders to solve this problem

[Pattern("read @book *chapter_verse")]
public bool Bible(string book, string chapter_verse, CommandContext ctx)
{
    ctx.WriteResponse($"this is a warning\n", MessageTypeCode.Warning);
    ctx.WriteResponse($"this is an error\n", MessageTypeCode.Error);
    ctx.WriteResponse($"this is information\n", MessageTypeCode.Information);

    ctx.Pipeline.Store("book", book);
    ctx.Processor.ExecuteChildCommand($"at {chapter_verse}", ":");
    return true;
}

[Pattern("at @chapter : @verse")]
public bool Bible2(int chapter, int verse, CommandContext ctx)
{
    var book = ctx.Pipeline.Get("book");
    if (book.Exists)
        ctx.WriteResponse($"Now reading {book.Value} {chapter}:{verse}\n");
    return true;
}

As can be seen here, we use the command context to call the processor again, this time passing in the colon as a word boundary

Release 1.0.4 Notes

Added wildcard placeholders that can be used similar to standard placeholders. In the sample below, a wildcard placeholder that will take the name my_placeholder is specified. Included in this release is built-in support for using Zaria.AI in AspNetCore web applications. Added helper funcitons to IApplicationBuilder and IServiceCollection. With these Zaria.AI can be used in WebApi applications in the same manner as console. To leverage Zaria.AI add the following calls during application statup.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddZaria();

 //other boilerplate web api stuff would go here

 app.UseZaria();
 app.Run();

The UseZaria method can optionally accept a string representing the root path that will trigger Zaria functionality (by default this is /zaria). So zaria would be triggered for

http://some host/zaria/echo "hello world"

which would show in the address bar as:

http://some host/zaria/echo%20"hello%20world"

If app.UseZaria("sampler") is used then the correct url to trigger it would be:

http://some host/sampler/echo "hello world"

AddZaria can optionally accept a delegate that allows you to configure the processor as needed. The following sample illustrtes loading remote patterns into the processor.

 // Add services to the container.
builder.Services.AddZaria(processor =>
{
    processor.ScanReferencedAssembly<MyAssemblyIdentifier>();
    processor.LoadRemotePatternRepository("""
                {
                "Patterns": [
                {
                    "Pattern": "you dey craze1",
                    "HandlerURI": "http://localhost:5227/zaria/echo 888",
                    "Method": "get"
                },
                {
                    "Pattern": "you dey mad2",
                    "HandlerURI": "http://localhost:5227/zaria/echo 999",
                    "Method": "get"
                }
                ]
            }
            """);
});

Order of precedence for configured rules.

1. Rules configured at runtime are always processed first. As such they will supercede any rules defined anywhere else. If no hanlder is found matching the pattern then the processor will move to the next set
2. Rules configured statically in the assembly/target type are processed next.
3. If there are remote patterns configured and no patterns were matched in any other approach then rules defined in the patterns json file are used. The patterns json file takes the format:

{
  "Patterns": [
    {
      "Pattern": "<pattern>",
      "HandlerURI": "<URL to call>",
      "Method": "<http method to use>"
    },
    {
      "Pattern": "<pattern>",
      "HandlerURI": "<URL to call>",
      "Method": "<http method to use>"
    }
  ]
}

Any remote handlers must return a json object the follows the format

{
    "MessageType":"<Information | Warning | Error>",
    "Message": "<the message that was sent>"
}

With this version, state management is no longer handled within the framework. Rather, a set of delegates can be injected into the framework that will be called when read, write, and delete operations are called. The signature for Initialize has been updated to account for this new capability. The follwowing snipet illustrates how the handles can be used to add state management to a console application. In a web based clustered scenario one might use a database or session state to store, retrievea, and delete state.

Dictionary<string, object> state = new Dictionary<string, object>();
 var processor = CommandProcessor.Initialize(new InitializationSettings
{
    StateManagement = new PipelineStateManager
    {
        StoreHandler = (a, b) =>
        {
            state[a] = b;
        },
        RetrieveHandler = (x) =>
        {
            if (!state.ContainsKey(x))
                return (false, null);
            return (true, state[x]);
        },
        RemoveHandler = (x) => state.Remove(x)
    },

});

Added response handler delegate as an optional argument to all execute methods. The object passed into this delegate is of type HandlerResponse and contains the response message as well as an indicator of the kind of message it is (Error, Warning, or Informational). This ensures that each unique host can be provided with a host appropriate way to display responses to commands. The ideal way to display messages sent back to the application hosting zaria is now to provide the display code directly in this delegate. This allows different hosts to processes the response message from command handlers in a manner suitable to themselves. Ostensibly allowing the same handler to be used in multiple hosting applications without the need to recode (assuming there are no otehr significant differences). The following code shows how a console application might display results from handler.

while (true)
{
    Console.Write("> ");
    var command = Console.ReadLine();
    if (!processor.Execute(command, handler => Console.WriteLine(handler.Message)))
    {
        break;
    }
}

A web application might handle responsed from handlers as follows:

processor.Execute(input_command, async message =>
{
    await context.Response.WriteAsync(message);
});

The following code shows the updated execute method.

public bool Execute(string input_instructions, Action<string> response_handler = null)

Added WriteResponse(string) method to CommandContext. This method is used to return responses from command handlers in a host agnostic manner. The hosting application must process these calls by passing a delegate into the Execute method that renders the response message in a host appropriate manner.

Types that can be used as parameters in a handler method have been locked down to:

• int

• string

• bool

• guid

• double

• CommandContext

  Any other type used as a parameter in a handler method will cause that method to be ignored.

Reference variables directly in input commands. To reference a variable use the $ sumbol before it. So if there was a variable set in code context.Pipeline.Store("age", 25); then it could be referenced when the user is inputing commands as follows Set age to $age. This value will be replaced by the value of the variable (25) so that the resulting input string will be Set age to 25. It is important to note that this is what will be processed, not the original string.

Changed CommandContext.Pipeline.Get to return a tuple (bool Exists, object Value) where the boolean value indicates whether there was a key found in the pipeline state. This change was made to remove ambiguity as to the meaning of a default value such as null getting returned (since a default value can mean both that the variable does not exist or that the value does exist but is null). Using this approach retrieving state can be accomplished as follows:

[Pattern("display @var")]
bool Display(string var, CommandContext context)
{
    var value1 = context.Pipeline.Get<int>(var);
    if (value1.Exists)
        context.WriteResponse($"Your answer is {value1.Value}");
    else
        context.WriteResponse("Variable does not exist");
    return true;
}

Added File property to Pattern. You can specify a fully qualified path to a .pidgin file. This is simply a text file with command seperated into individual lines. This approach supports all the same capabilities as all other approaches to declaring patterns however this does not work with injected patterns. The sample below creates a handler that gets its patterns from a file called arithmetic-commands.pidgin

[Pattern(File = @"C:\CommandTestHarness\arithmetic-commands.pidgin")]
bool ProcessPatternsFromFile(int x, int y)
{
    int answer = 0;
    string operand = "";
    switch (_context.InputTokens[0].Text)
    {
        case "add":
            operand = "+";
            answer = x + y;
            break;
        case "subtract":
            operand = "-";
            answer = y - x;
            break;
    }
    context.WriteResponse($"{x} {operand} {y} = {answer}");
    return true;
}

Added URL property to Pattern. You can specify a url to an endpoint that returns a string with command seperated into individual lines.
The command processor will use an HTTP Get to attempt to retrieve the pattern data. This approach supports all the same capabilities as all other approaches to declaring patterns however this does not work with injected patterns. The following sample gets its patterns from a uri on the cloud. The endpoint must return the patterns as plain text with one pattern on each line.

[Pattern(URL = @"http://<some service>/api/Function1")]
bool ProcessPatternsFromURL(int x, int y)
{
    int answer = 0;
    string operand = "";
    switch (_context.InputTokens[0].Text)
    {
        case "multiply":
            operand = "*";
            answer = x * y;
            break;
        case "divide":
            operand = "/";
            answer = x / y;
            break;
    }
    context.WriteResponse($"{x} {operand} {y} = {answer}");
    return true;
}

Added Provider property to Pattern. Any public type that derives from IPatternProvider can be used as a value for this property. The type exposes a function which can be used to retrive or generate patterns that will be associated with the given hander declaring the attribute.

public class TestPatternProvider : IPatternProvider
{
    public List<string> GetPatterns()
    {
        //go to database and retrieve value
        return new List<string>
        {
            "sample1",
            "sample2",
        };
    }
}

The provider is declared as follows:

[Pattern(Provider = typeof(TestPatternProvider))]
bool Test(CommandContext context)
{
    context.WriteResponse(context.InputTokens[0].Text);
    return true;
}

Added Pipeline state to process. Pipeline state allows the user to store state to the context such that it can be used by future commands down the pipe. This is for scenarios where multiple commands need to be processed in order to complete a given task (and the state needs to be passed between the command handlers. The command processor provides the state but all management must be handled by consumers of this library. This state does not persist beyond a given instance of the command processor. The actual management of the state is routed to the delegates you inject during processor initialization. The following sample illustrates:

[Pattern("var @name =  @value")]
bool SetVariable(string name, int value, CommandContext context)
{
    context.Pipeline.Store(name, value);
    return true;
}

This can be used in a subsequent example as follows:

[Pattern("display @var")]
bool Display(string var, CommandContext context)
{
    var value1 = context.Pipeline.Get<int>(var);
    context.WriteResponse($"Your answer is {value1}");
    return true;
}

This command handler basically prints the given pipeline variable to the console.

You can build a very simple calculator by combining these two command patterns with another for the actual arithmetic work as shown below.

[Pattern("calc @name1 @operand @name2 into @var")]
bool Calculate(string name1, string name2, string operand, string var, CommandContext context)
{
    var x = context.Pipeline.Get<int>(name1);
    var y = context.Pipeline.Get<int>(name2);
    int answer = 0;
            

    switch (operand)
    {
        case "+":                    
            answer = x + y;
            break;
        case "-":
            answer = x - y;
            break;
        case "*":
            answer = x * y;
            break;
        case "/":
            answer = x / y;
            break;
    }

    context.Pipeline.Store(var, answer);
    return true;
}

Quotes are now processed verbatim so case is maintained for them. Everything else is case insensitive

Both versions of Execute now return bool. This is done to help with the transition from single use to CLI. If args are passed the default behavior is to return false (as the expectation is that this is a single run). It is up to the user and designer of the command interface to decide.

Usage

Creating patterns

For any given class -

1. For each command pattern you want to process add static method with a bool return type. Each of these will serve as a handler for when the user's input matches the pattern this method will advertise.
2. Now decorate the method with PatternAttribute attribute.
3. As a catch-all for any input that does not match a pattern you advertise you can optionally provide another method (with a similar signature as described above) and decorate this one with NotFoundAttribute instead. Note that only 1 method, the first encountered with the proper attribute, will be used for the fallback route even if you decorate multiple methods with it.

PatternAttribute accepts a string as an argument. This string represents the pattern that must be matched for the method to be called. This string can contain any sequence of characters except those with special meaning listed below:

Some points to note:

The parsing system does a token (word) for token match on the input string using the pattern defined in the PatternAttribute as a psuedo-schema. By default, word positions are respected when matching in this way. This approach is somewhat rigid from a users perspective however; forcing them to enter commands in an exact order can be challenging. To address this, Pidgin also includes a mechanism to that allows for sections of the overall pattern to be entered without respect to position. While position is still maintained within the section, the resulting sections as a whole can be keyed-in in any order.

• To indicate that a section of the pattern is not tied to a position, encase that section in square brackets ([]).
• Note that you cannot start a pattern with square brackets (the first part of your pattern maintain its position).
• Note that you cannot start any part of your pattern with placeholders. Additionally, in all scenarios placeholders must come after static text. This is also true for all sections of the pattern; meaning if you elect to break the pattern up into sections then those sections will also need text before placeholders.
• You cannot put sections inside of sections. This means you can't place square brackets inside of a block enclosed by square brackets. This will cause a runtime error.
• The parsing process is sensitive to white spaces, if the user's intent is to pass in a parameter with white spaces they must use double quotes (") to surround that text. This means a pattern like hello @message can be triggered with the text hello john but can also be triggered with hello "john the baptist"
• Be careful where you put placeholders in the pattern. A good rule of thumb is to have static text between your variables and any ] character.

A pattern like The [quick @fox_color fox jumped] @jump_direction over the lazy dog will produce three sections.

• The
• quick @fox_color fox jumped
• @jump_direction over the lazy dog

A pattern like the [@quick @fox_color fox jumped] jump_direction over the lazy dog will also produce three sections.

• The
• @quick @fox_color fox jumped
• jump_direction over the lazy dog

As can be seen, during pattern evaluation sections of the Pidgin may get resolve as starting with a variable. To prevent this, never put a placeholder directly after a partitioned block.

Types

CommandProcessor

Provides functions that can be used to initiaize the processor and execute commands on it. Also contains properties that can be used to inspect the input string/array that is being executed

PipelineContext

Represents the context of the overarching process flow driving the commands entered by the user. All state management is controlled through this type.

PatternAttribute

Use this attribute to decorate any methods you want to be used to process a command pattern.

NotFound

Use this attribute to decorate the method you want to be called when there is no command pattern found

InputToken

Represents a token (word) in the input string/array that is passed into the processor.

PatternRepository

Collection where dynamic commands are stored. Dynamic commands are the commands that are injected into the CommandLineProcessor as opposed to getting discovered through the initialization process.

CommandContext

Context of an executing command. This class can be passed into any command handler (including in NotFound scenarios). Provides a view into the parameters that were passed in. You can use the type to walk back and forth through the text that was passed into your tool token (word) by token. Note that quoted text is treated as one token

CommandPatternException

Represents an exception that occurs while parsing the input text

IPatternProvider

Classes that implement this interface can be used to provide patterns to a given PatternAttribute. The following illustrates a sample of this:

ZariaMiddlewareExtensions

Provides helper functions for injecting Zaria.AI pattern recognition into AspNetCore web applications

public class TestPatternProvider : IPatternProvider
{
    public List<string> GetPatterns()
    {
        //go to database and retrieve value
        return new List<string>
        {
            "sample1",
            "sample2",
        };
    }
}

The provider is declared as follows:

[Pattern(Provider = typeof(TestPatternProvider))]
bool Test(CommandContext context)
{
    context.WriteResponse(context.InputTokens[0].Text);
    return true;
}

Examples

In the following example a command pattern handler is created

[Pattern("say [-what @something] [-to @someone]")]
static bool SaySomething(string something, string someone, int i)
{
    context.WriteResponse($"You said {something} to {someone}");
    return true;
}

This method will be invoked whenever the following pattern is passed to the interpreter say -what [...] -to [...] . Any placeholders in the pattern must match the parameter names on the method that it decorates (similar to Web API).
If placeholders are provided but the method does not have paramters (or they dont match) then the parameters will hold their default value when the method is run. This is also true in the reverse scenario; if no placeholders are included the method will be called with the default values of any parameters that exist. The return value is not used by the processor; rather, it is meant to be used in REPL scenarios to indicate whether the loop should continue. THe convension is to return true to continue the program and false to exit it.

In the following example we pass the following into a command-line that has the code above deployed:

say -what "hello world" -to "the man next door"

Note: Quotes are required when spaces exist between your placeholder tokens (if not displayed in your browser)

The result of this would be:

You said hello world to the man next door

A single method may be decorated with more than one command pattern (thus allowing it to handle multiple scenarios). In the following example the same SayHello method is used to handle three different patterns.

[Pattern("test @arg")]
[Pattern("test")]
[Pattern("hello there")]
static bool SayHello(string arg)
{
    Console.WriteLine($"Calling hello there command with {arg}");
    return true;
}

Note that this sample is based on hosting Zaria.AI in a console application. For other hosting scenarios it is recommended that a CommandContext be declared as a parameter on the hander method (the runtime will pass that value in automatically when the parameter is detected) and then use the WriteResponse method to pass a response message back to the host. The host can then decide how to display that message. This approach allows for the handler to be host agnostic.

This method will be invoked if any of the following patterns is passed into the processor.

• test
• test 123
• hello there

You can also represent these different patterns on a given handler by using 1 Pattern attribute with multiple patterns as follows

[Pattern("test","test @arg","hello there")]
static bool SayHello(string arg)
{
    Console.WriteLine($"Calling hello there command with {arg}");
    return true;
}

Running the Processor

To initialize the processor use the following code:

CommandProcessor.Initialize();

This will traverse the current assembly and any referenced assemblies and identify all the command patterns that have been specified. A command pattern is declared by creating a method with a boolean return type and decorating it with the PatternAttribute attribute. Initialize must always be called first, and must be called again each time a new assembly is added to the AppDomain it was initially called in. To limit the commands patterns used to a smaller scope you can use Initialize with a type parameter representing the class who's methods will be inspected for command patterns. In the following case we are limiting the call to only initialize methods in the SamplePatternHost class.

CommandProcessor.Initialize<SamplePatternHost>();

The processor can be used as follows:

processor.Execute(string[]);

This version of the execute method accepts an array of strings. This can be the arguments passed into the console itself (but it really could be anything). No special processing is performed on the array other than turning it into a space-delimited string. So if the array: [hello,world,i,like,to,code] it would be converted to hello world i like to code. This version of the method returns void.

For creating something like a REPL (Read-evaluate-print loop), or for use in generic command processing, the other version of the method is more ideal.

processor.Execute(string);

This version of the method takes the entire string as input and processes it with no additional manipulation. This version also returns a bool that can be used to determine whether it should be called again.

The following shows how a simple console REPL might look.

static void Main(string[] args)
{
    Console.WriteLine("Pidgin REPL Sample");

    //call initialization
    var processor = CommandProcessor.Initialize();

    while (true)
    {
        Console.Write("> ");
        var command_line = Console.ReadLine();
        var continue_to_run = processor.Execute(command_line, message=>Console.WriteLine(message));

        if (!continue_to_run)
            break;
    }

}

As can be seen from the sample, the Execute method returns a boolean value that is then used to determine whether the loop continues to run. The alternate method does not have a return type.

static void Main(string[] args)
{
    var input_pattern = //pattern from args array...
    var processor = CommandProcessor.Initialize();
    processor.Execute(input_pattern);
}

There will be scenarios where a procedural approach is more advanageous to you. For instance, if a quick and easy command is needed, it might not make sense to create an entire method for it. In those situations you can use the Pattern property of CommandProcessor. It allows you to inject pattern evaluators directly into the CommandLineProcessor without having to create a class method.

processor.Pattern["reset @parameter"] = (placeholders, context) =>
{
    foreach(var placeholder in placeholders.Keys)
        context.WriteResponse($"{placeholder} = {placeholders[placeholder]}");
    return true;
};

One key difference between the two approaches is that with this, the placeholders are not automatically converted and mapped to the method's parameters. With this approach a dictionary(of string) is passed into the lambda. If multiple patterns need to be mapped to one lambda they can be passed comma separated. An example of multiple dynamic patterns using the same lamda is shown below.

processor.Pattern
[
    "run @code_name [override? @role]",
    "stop @application"
] = (placeholders, context) =>
{
    var is_run = context.HasToken("run");
    if (is_run)
    {
        var allow_override = context.HasToken("override");
        if (allow_override)
        {
            context.WriteResponse($"*** Running {placeholders["code_name"]} with [{placeholders["role"]}] access ***");
        }
        else
            context.WriteResponse($"Running {placeholders["code_name"]} with normal access");
    }
    else
    {
        context.WriteResponse($"Stopping {placeholders["application"]}");
    }

    return true;
};

Please note that this collection Cannot be updated or iterated through. This is mainly a mechanism for injecting additional patterns with their associated handlers into the processor. Also note that patterns declared here will be processed before any patterns statically declared (declared with method and attribute notation). In this way they can override the intended functionality of a given pattern so be careful with them.