The highest tagged major version is
README
¶
Package esg is the emergent stochastic generator, where tokens are generated stochastically according to rules defining the contingencies and probabilities. It can be used for generating sentences (sg as well).
Rules
There are 5 types of rules, based on how the items within the rule are selected:
- Uniform random and random with specified probabilities.
- Conditional items that depend on a logical expression -- use the
?before{to mark. - Sequential and permuted order items that iterate through the list -- use
|or$respectively.
Unconditional items are chosen at random, optionally with specified probabilities:
RuleName {
%50 Rule2 Rule4
%30 'token1' 'token2'
...
}
where Items on separate lines within each rule are orthogonal options, chosen at uniform random unless otherwise specified with a leading %pct. %pct can add up to < 100 in which case nothing is an alternative output.
Multiple elements in an item (on the same line) are resolved and emitted in order. Terminal literals are 'quoted' -- otherwise refers to another rule: error message will flag missing rules during Validate().
Conditional items are specified by the ? after the rule name:
RuleName ? {
Rule2 || Rule3 {
Item1
Item2
...
}
Rule5 && Rule6 {
...
}
...
}
The expression before the opening bracket for each item is a standard logical expression using || (or), && (and), and ! (not), along with parens, where the elements are rules that could have been generated earlier in the pass -- they evaluate to true if so, and false if not.
If the whole expression evaluates to true, then it is among items chosen at random (typically only one for conditionals but could be any number).
If just one item per rule it can be put all on one line.
States
Each Rule or Item can have an optional State expression associated with it, which will update a States map in the overall Rules if that Rule or Item fires. The States map is a simple map[string]string and is reset for every Gen pass. It is useful for annotating the underlying state of the world implied by the generated sentence, using various role-filler values, such as those given by the modifiers below. Although the Fired map can be used to recover this information, the States map and expressions can be designed to make a clean, direct state map with no ambiguity.
In the rules text file, an = prefix indicates a state-setting expression -- it can either be a full expression or get the value automatically:
=Name=Value-- directly sets state Name to Value=Name-- sets state Name to value of Item or Rule that it is associated with. Only non-conditional Items can be used to set the value, which is the first element in the item expression -- conditionals with sub-rules must set the value explicitly.
Expressions at the start of a rule (or sub-rule), on a separate line, are associated with the rule and activate when that rule is fired (and the implicit value is the name of the rule). Expressions at the end of an Item line are associated with the Item. Put single-line sub-rule state expressions at end just before }. Any number of state expressions can be added.
Std Modifiers
Conventional modifiers, used for defining sub-rules:
- A = Agent
- Ao = CoAgent
- V = Verb
- P = Patient,
- Pi = Instrument
- Pc = CoPatient
- L = Location
- R = Adverb
See testdata/testrules.txt and sg CCN sim for example usage.
Documentation
¶
Overview ¶
Package esg is the emergent stochastic generator, where tokens are generated stochastically according to rules defining the contingencies and probabilities. It can be used for generating sentences (sg as well).
Rules:
There are two types of rules: * unconditional random items * conditional items.
Unconditional items are chosen at random, optionally with specified probabilities:
RuleName {
%50 Rule2 Rule4
%30 'token1' 'token2'
...
}
where Items on separate lines within each rule are orthogonal options, chosen at uniform random unless otherwise specified with a leading %pct. %pct can add up to < 100 in which case *nothing* is an alternative output.
Multiple elements in an item (on the same line) are resolved and emitted in order. Terminal literals are 'quoted' -- otherwise refers to another rule: error message will flag missing rules.
Conditional items are specified by the ? after the rule name:
RuleName ? {
Rule2 || Rule3 {
Item1
Item2
...
}
Rule5 && Rule6 {
...
}
...
}
The expression before the opening bracket for each item is a standard logical expression using || (or), && (and), and ! (not), along with parens, where the elements are rules that could have been generated earlier in the pass -- they evaluate to true if so, and false if not.
If the whole expression evaluates to true, then it is among items chosen at random (typically only one for conditionals but could be any number).
If just one item per rule it can be put all on one line.
States:
Each Rule or Item can have an optional State expression associated with it, which will update a `States` map in the overall Rules if that Rule or Item fires. The `States` map is a simple `map[string]string` and is reset for every Gen pass. It is useful for annotating the underlying state of the world implied by the generated sentence, using various role-filler values, such as those given by the modifiers below. Although the Fired map can be used to recover this information, the States map and expressions can be designed to make a clean, direct state map with no ambiguity.
In the rules text file, an `=` prefix indicates a state-setting expression -- it can either be a full expression or get the value automatically:
- `=Name=Value` -- directly sets state Name to Value
- `=Name` -- sets state Name to value of Item or Rule that it is associated with. Only non-conditional Items can be used to set the value, which is the first element in the item expression -- conditionals with sub-rules must set the value explicitly.
Expressions at the start of a rule (or sub-rule), on a separate line, are associated with the rule and activate when that rule is fired (and the implicit value is the name of the rule). Expressions at the end of an Item line are associated with the Item. Put single-line sub-rule state expressions at end just before }.
Std Modifiers:
Conventional modifiers, used for defining sub-rules: A = Agent
Ao = Co-Agent
V = Verb P = Patient,
Pi = Instrument Pc = Co-Patient
L = Location R = adverb
Index ¶
- Variables
- type Cond
- type CondEls
- type Conds
- type Elem
- type Elements
- type Item
- type Rule
- type RuleTypes
- type Rules
- func (rls *Rules) Add(rl *Rule)
- func (rls *Rules) Gen() []string
- func (rls *Rules) HasFired(name string) bool
- func (rls *Rules) Init()
- func (rls *Rules) OpenRules(fname string) []error
- func (rls *Rules) ParseAddItem(rstack []*Rule, errs *[]error, sp []string) (*Rule, *Item)
- func (rls *Rules) ParseConds(cds []string, errs *[]error) Conds
- func (rls *Rules) ParseCurRule(rstack []*Rule, errs *[]error, sp []string) *Rule
- func (rls *Rules) ParseElems(rl *Rule, it *Item, els []string, errs *[]error)
- func (rls *Rules) ParseState(ststr string, state *State, errs *[]error)
- func (rls *Rules) ReadRules(r io.Reader) []error
- func (rls *Rules) Rule(name string) *Rule
- func (rls *Rules) RuleTry(name string) (*Rule, error)
- func (rls *Rules) SetFired(name string)
- func (rls *Rules) String() string
- func (rls *Rules) Validate() []error
- type State
Constants ¶
This section is empty.
Variables ¶
var KiT_CondEls = kit.Enums.AddEnum(CondElsN, kit.NotBitFlag, nil)
var KiT_Elements = kit.Enums.AddEnum(ElementsN, kit.NotBitFlag, nil)
var KiT_RuleTypes = kit.Enums.AddEnum(RuleTypesN, kit.NotBitFlag, nil)
Functions ¶
This section is empty.
Types ¶
type Cond ¶
type Cond struct {
El CondEls `desc:"what type of conditional element is this"`
Rule string `desc:"name of rule to evaluate for CRule"`
Conds Conds `desc:"sub-conditions for SubCond"`
}
Cond is one element of a conditional
type CondEls ¶
type CondEls int32
CondEls are different types of conditional elements
func (*CondEls) FromString ¶
func (CondEls) MarshalJSON ¶
func (*CondEls) UnmarshalJSON ¶
type Conds ¶
type Conds []*Cond
Conds are conditionals
type Elem ¶
type Elem struct {
El Elements `desc:"type of element: Rule, Token, or SubItems"`
Value string `desc:"value of the token: name of Rule or Token"`
}
Elem is one elemenent in a concrete Item: either rule or token
type Elements ¶
type Elements int32
Elements are different types of elements
func (*Elements) FromString ¶
func (Elements) MarshalJSON ¶
func (*Elements) UnmarshalJSON ¶
type Item ¶
type Item struct {
Prob float32 `desc:"probability for choosing this item -- 0 if uniform random"`
Elems []Elem `desc:"elements of the rule -- for non-Cond rules"`
Cond Conds `desc:"conditions for this item -- specified by ?"`
SubRule *Rule `desc:"for conditional, this is the sub-rule that is run with sub-items"`
State State `desc:"state update name=value to set for rule"`
}
Item is one item within a rule
type Rule ¶
type Rule struct {
Name string `desc:"name of rule"`
Desc string `desc:"description / notes on rule"`
Type RuleTypes `desc:"type of rule -- how to choose the items"`
Items []*Item `desc:"items in rule"`
State State `desc:"state update for rule"`
CurIdx int `desc:"current index in Items, if sequential or permuted"`
Order []int `desc:"permuted order if doing that"`
}
Rule is one rule containing some number of items
func (*Rule) Init ¶
func (rl *Rule) Init()
Init initializes the rules -- only relevant for ordered rules (restarts at start)
type RuleTypes ¶
type RuleTypes int32
RuleTypes are different types of rules (i.e., how the items are selected)
const ( // UniformItems is the default mutually exclusive items chosen at uniform random UniformItems RuleTypes = iota // ProbItems has specific probabilities for each item ProbItems // CondItems has conditionals for each item, indicated by ? CondItems // SequentialItems progresses through items in sequential order, indicated by | SequentialItems // PermutedItems progresses through items in permuted order, indicated by $ PermutedItems RuleTypesN )
func (*RuleTypes) FromString ¶
func (RuleTypes) MarshalJSON ¶
func (*RuleTypes) UnmarshalJSON ¶
type Rules ¶
type Rules struct {
Name string `desc:"name of this rule collection"`
Desc string `desc:"description of this rule collection"`
Trace bool `desc:"if true, will print out a trace during generation"`
Top *Rule `desc:"top-level rule -- this is where to start generating"`
Map map[string]*Rule `desc:"map of each rule"`
Fired map[string]struct{} `desc:"map of names of all the rules that have fired"`
States State `desc:"user-defined state map optionally created during generation"`
}
Rules is a collection of rules
func (*Rules) ParseAddItem ¶
func (*Rules) ParseCurRule ¶
func (*Rules) ParseElems ¶
type State ¶
State holds the name=value state settings associated with rule or item as a string, string map
func (*State) Set ¶
Set sets state in rules States map, using given value for any items that have empty values
func (*State) TrimQualifiers ¶
func (ss *State) TrimQualifiers()
TrimQualifiers removes any :X qualifiers after state values
Source Files