zenmodel

The connection between Neurons is called a Link, and Link is directional, having a source and a destination. Typically, both the source and the destination specify a Neuron. The method to add a regular Link is as follows:

// add Link, return link ID
// bp := zenmodel.NewBrainPrint()
id, err := bp.AddLink("src_neuron", "dest_neuron")

Entry Link

You can also add an Entry Link, this kind of Link does not have a source Neuron, and only specifies a destination Neuron; its source is the user.

// add Entry Link, return link ID
id, err := bp.AddEntryLink("dest_neuron")

End Link

Additionally, you can add an End Link. This type of Link only specifies a source Neuron and cannot specify a destination Neuron, automatically directing to the End Neuron. Adding an End Link will also create a unique End Neuron for the entire Brain (creating one if it does not exist) and set the Link's destination to the End Neuron. This is the sole method to create an End Neuron; it cannot be individually created without connecting it.

// add End Link, return link ID
id, err := bp.AddEndLink("src_neuron")

A Neuron is a neural cell in the Brain, which can be understood as a processing unit. It executes processing logic and can read from or write to the Brain's Memory. Memory, as the context of the Brain, can be shared by all Neurons.

Processor

When adding a Neuron, you need to specify its processing logic, either by directly specifying a process function (ProcessFn) or by assigning a custom Processor.

// add Neuron with process function
bp.AddNeuron("neuron_id", processFn)

// add Neuron with custom processor
bp.AddNeuronWithProcessor("neuron_id", processor)

The function signature for ProcessFn is as follows, where BrainRuntime is mainly used for reading and writing to the Brain's Memory, details of which are introduced in the BrainRuntime section.

// processFn signature
func(runtime BrainRuntime) error

The interface definition for a Processor is:

type Processor interface {
    Process(brain BrainRuntime) error
    DeepCopy() Processor
}

End Neuron

End Neuron is a special Neuron with no processing logic, serving only as the unique exit for the entire Brain. Each Brain has only one End Neuron, and when it is triggered, the Brain will put all Neurons to sleep, and the Brain itself will enter a Sleeping state.

An End Neuron is not mandatory. Without it, the Brain can still enter a Sleeping state when there are no active Neurons and Links.

CastGroupSelectFunc

CastGroupSelectFunc is a propagation selection function used to determine which CastGroup a Neuron will propagate to, essentially, branch selection. Each CastGroup contains a set of outward links (out-link). Typically, binding a CastGroupSelectFunc is used together with adding (dividing) a CastGroup.

// bind cast group select function for neuron
err := bp.BindCastGroupSelectFunc("neuron_id", selectFn)

CastGroup

A CastGroup is a propagation group used to define the downstream branches of a Neuron. It divides the Neuron's outward links (out-link). By default, all of a Neuron's outward links (out-link) belong to the same Default CastGroup, and the propagation selection function (CastGroupSelectFunc), if unspecified by default, will choose to propagate to the Default CastGroup.

This means that by default, after the execution of a Neuron, all of its outward links (out-link) are triggered in parallel (note: this does not imply that downstream Neurons will be activated; it depends on the configuration of the downstream Neurons' TriggerGroup).

If branch selection is required, you need to add a CastGroup and bind a CastGroupSelectFunc. All outward links (out-link) of the selected CastGroup will be triggered in parallel (the same applies here, whether downstream Neurons are activated depends on the downstream Neurons' TriggerGroup settings).

// AddLinkToCastGroup add links to a specific named cast group.
// if the group does not exist, create the group. Groups that allow empty links.
// The specified link will be removed from the default group if it originally belonged to the default group.
err := bp.AddLinkToCastGroup("neuron_id", "group_A", linkID1, linkID2)

TriggerGroup

A TriggerGroup is a trigger group used to define which of a Neuron's inward links (in-link) must be triggered to activate the Neuron. It divides the Neuron's inward links (in-link).

When any one TriggerGroup of a Neuron is triggered (a TriggerGroup is considered triggered only when all inward links (in-link) within it are triggered), the Neuron is activated. Inspiration is taken from neurotransmitters, which must accumulate to a certain threshold before opening channels for electrical signal transmission.

By default, each of a Neuron's inward links (in-link) belongs to its own separate TriggerGroup, meaning that, by default, the Neuron gets activated if any of its inward links (in-link) are triggered.

If you need to wait for multiple upstream Neurons to finish in parallel before activating this Neuron, you need to add a TriggerGroup.

// AddTriggerGroup by default, a single in-link is a group of its own. AddTriggerGroup adds the specified in-link to the same trigger group.
// it also creates the trigger group. If the added trigger group contains the existing trigger group, the existing trigger group will be removed. This can also be deduplicated at the same time(you add an exist named group, the existing group will be removed first).
// add trigger group with links
err := bp.AddTriggerGroup("neuron_id", "group_B", linkID1, linkID2)

Brainprint is an abbreviation for Brain Blueprint, defining the graph topology structure of the Brain, as well as all Neurons and Links, in addition to the Brain's operational parameters. A runnable Brain can be built from the Brainprint. Optionally, specific build configuration parameters can also be defined during construction, such as the size of Memory, the number of concurrent Workers for the Brain runtime, etc.

brain := bp.Build(zenmodel.WithWorkerNum(3), )

Brain is an instance that can be triggered for execution. Based on the triggered Links, it conducts signals to various Neurons, each executing its own logic and reading from or writing to Memory.

The operation of the Brain is asynchronous, and it does not block the program waiting for an output of a result after being triggered because zenmodel does not define what is considered an expected outcome, all aiming to bring novel imagination to the users.

Users or developers can wait for certain Memory to reach the expected value, or wait for all Neurons to have executed and for the Brain to enter Sleeping, then read Memory to retrieve results. Alternatively, they can keep the Brain running, continually generating outputs.

Memory

Memory is the runtime context of the Brain. It remains intact after the Brain goes to sleep and will not be cleared unless ClearMemory() is called. Users can read from and write to Memory during Brain operation via Neuron Processing functions, preset Memory before operation, or read and write Memory from outside (as opposed to within the Neuron Process function) during or after operation.

BrainRuntime

The ProcessFn and CastGroupSelectFunc functions both include the BrainRuntime as part of their parameters. The BrainRuntime encapsulates some information about the Brain's runtime, such as the Memory at the time the current Neuron is running, the ID of the Neuron currently being executed. These pieces of information are commonly used in the logic of function execution, and often involve writing to Memory. There are also cases where it is necessary to maintain the operation of the current Neuron while triggering downstream Neurons. The BrainRuntime interface is as follows:

type BrainRuntime interface {
    // SetMemory sets memories for the brain, one key-value pair is one memory.
    // Memory will lazily initialize until `SetMemory` or any link is triggered
    SetMemory(keysAndValues ...interface{}) error
    // GetMemory retrieves memory by key
    GetMemory(key interface{}) interface{}
    // ExistMemory indicates whether there is a memory in the brain
    ExistMemory(key interface{}) bool
    // DeleteMemory deletes a single memory by key
    DeleteMemory(key interface{})
    // ClearMemory clears all memories
    ClearMemory()
    // GetCurrentNeuronID gets the current neuron's ID
    GetCurrentNeuronID() string
    // ContinueCast keeps the current process running, and continues casting
    ContinueCast()
}

• TrigLinks() or Entry() are for parallel triggering of links
• Links in a Cast group are also triggered in parallel after a Neuron is completed
• A Neuron begins its execution only after all the specified upstream Neurons have been completed. This is defined by setting up a trigger group to denote which upstream completions are to be awaited.

See the complete example here: examples/flow-topology/parallel

var (
    entryInput, entryPoetry, entryJoke string
)

func main() {
    bp := zenmodel.NewBrainPrint()
    bp.AddNeuron("input", inputFn)
    bp.AddNeuron("poetry-template", poetryFn)
    bp.AddNeuron("joke-template", jokeFn)
    bp.AddNeuron("generate", genFn)

    inputIn, _ := bp.AddLink("input", "generate")
    poetryIn, _ := bp.AddLink("poetry-template", "generate")
    jokeIn, _ := bp.AddLink("joke-template", "generate")

    entryInput, _ = bp.AddEntryLink("input")
    entryPoetry, _ = bp.AddEntryLink("poetry-template")
    entryJoke, _ = bp.AddEntryLink("joke-template")

    _ = bp.AddTriggerGroup("generate", inputIn, poetryIn)
    _ = bp.AddTriggerGroup("generate", inputIn, jokeIn)

    brain := bp.Build()

    // case 1: entry poetry and input
    // expect: generate poetry
    _ = brain.TrigLinks(entryPoetry)
    _ = brain.TrigLinks(entryInput)

    // case 2:entry joke and input
    // expect: generate joke
    //_ = brain.TrigLinks(entryJoke)
    //_ = brain.TrigLinks(entryInput)

    // case 3: entry poetry and joke
    // expect: keep blocking and waiting for any trigger group triggered
    //_ = brain.TrigLinks(entryPoetry)
    //_ = brain.TrigLinks(entryJoke)

    // case 4: entry only poetry
    // expect: keep blocking and waiting for any trigger group triggered
    //_ = brain.TrigLinks(entryPoetry)

    // case 5: entry all
    // expect: The first done trigger group triggered activates the generated Neuron,
    // and the trigger group triggered later does not activate the generated Neuron again.
    //_ = brain.Entry()

    brain.Wait()
}

func inputFn(b zenmodel.BrainRuntime) error {
    _ = b.SetMemory("input", "orange")
    return nil
}

func poetryFn(b zenmodel.BrainRuntime) error {
    _ = b.SetMemory("template", "poetry")
    return nil
}

func jokeFn(b zenmodel.BrainRuntime) error {
    _ = b.SetMemory("template", "joke")
    return nil
}

func genFn(b zenmodel.BrainRuntime) error {
    input := b.GetMemory("input").(string)
    tpl := b.GetMemory("template").(string)
    fmt.Printf("Generating %s for %s\n", tpl, input)
    return nil
}

See the complete example here: examples/flow-topology/branch

func main() {
    bp := zenmodel.NewBrainPrint()
    bp.AddNeuron("condition", func(runtime zenmodel.BrainRuntime) error {
        return nil // do nothing
    })
    bp.AddNeuron("cell-phone", func(runtime zenmodel.BrainRuntime) error {
        fmt.Printf("Run here: Cell Phone\n")
        return nil
    })
    bp.AddNeuron("laptop", func(runtime zenmodel.BrainRuntime) error {
        fmt.Printf("Run here: Laptop\n")
        return nil
    })
    bp.AddNeuron("ps5", func(runtime zenmodel.BrainRuntime) error {
        fmt.Printf("Run here: PS5\n")
        return nil
    })
    bp.AddNeuron("tv", func(runtime zenmodel.BrainRuntime) error {
        fmt.Printf("Run here: TV\n")
        return nil
    })
    bp.AddNeuron("printer", func(runtime zenmodel.BrainRuntime) error {
        fmt.Printf("Run here: Printer\n")
        return nil
    })

    cellPhone, _ := bp.AddLink("condition", "cell-phone")
    laptop, _ := bp.AddLink("condition", "laptop")
    ps5, _ := bp.AddLink("condition", "ps5")
    tv, _ := bp.AddLink("condition", "tv")
    printer, _ := bp.AddLink("condition", "printer")
    // add entry link
    _, _ = bp.AddEntryLink("condition")

    /*
       Category 1: Electronics
       - Cell Phone
       - Laptop
       - PS5

       Category 2: Entertainment Devices
       - Cell Phone
       - PS5
       - TV

       Category 3: Office Devices
       - Laptop
       - Printer
       - Cell Phone
    */
    _ = bp.AddLinkToCastGroup("condition", "electronics",
        cellPhone, laptop, ps5)
    _ = bp.AddLinkToCastGroup("condition",
        "entertainment-devices",
        cellPhone, ps5, tv)
    _ = bp.AddLinkToCastGroup(
        "condition", "office-devices",
        laptop, printer, cellPhone)

    _ = bp.BindCastGroupSelectFunc("condition", func(brain zenmodel.BrainRuntime) string {
        return brain.GetMemory("category").(string)
    })

    brain := bp.Build()

    _ = brain.EntryWithMemory("category", "electronics")
    //_ = brain.EntryWithMemory("category", "entertainment-devices")
    //_ = brain.EntryWithMemory("category", "office-devices")
    //_ = brain.EntryWithMemory("category", "NOT-Defined")

    brain.Wait()
}

You can refer to the agent neuron in plan-and-excute, which is a nested brain: openai_tool_agent

You can also refer to the example nested as follows:

func main() {
    bp := zenmodel.NewBrainPrint()
    bp.AddNeuron("nested", nestedBrain)
    _, _ = bp.AddEntryLink("nested")

    brain := bp.Build()
    _ = brain.Entry()
    brain.Wait()

    fmt.Printf("nested result: %s\n", brain.GetMemory("nested_result").(string))
    
    // nested result: run here neuron: nested.run
}

func nestedBrain(outerBrain zenmodel.BrainRuntime) error {
    bp := zenmodel.NewBrainPrint()
    bp.AddNeuron("run", func(curBrain zenmodel.BrainRuntime) error {
        _ = curBrain.SetMemory("result", fmt.Sprintf("run here neuron: %s.%s", outerBrain.GetCurrentNeuronID(), curBrain.GetCurrentNeuronID()))
        return nil
    })
    _, _ = bp.AddEntryLink("run")

    brain := bp.Build()

    // run nested brain
    _ = brain.Entry()
    brain.Wait()
    // get nested brain result
    result := brain.GetMemory("result").(string)
    // pass nested brain result to outer brain
    _ = outerBrain.SetMemory("nested_result", result)

    return nil
}

The zenmodel-contrib community offers many full-featured Processors, or your project's code may have implemented other Processors. Sometimes you need to utilize the functionalities of these Processors, use a combination of multiple Processors, or add extra functionality to existing Processors. In these cases, you can reuse other Processors within your current Processor or ProcessFn by simply passing the BrainRuntime of your current Processor or ProcessFn as a parameter to the other Processor or ProcessFn.

For example, in the QAProcess function of multi-agent/agent-supervisor, it reuses the GoCodeTestProcessor from the zenmodel-contrib community and adds extra functionality after reusing the Processor.

func QAProcess(b zenmodel.BrainRuntime) error {
    p := go_code_tester.NewProcessor().WithTestCodeKeep(true)
    if err := p.Process(b); err != nil {
        return err
    }

    if err := b.SetMemory(memKeyFeedback, b.GetCurrentNeuronID()); err != nil {
        return err
    }

    return nil
}