semantic/reason/model.go

package reason

import (
	"fmt"
	"time"

	"github.com/hanzoai/semantic"
	"github.com/hanzoai/semantic/prov"
)

// Model is what a run closed to: the facts it was given and the facts they
// entail, each with its derivation. Order is the order things arrived —
// given facts first, then derived facts round by round — so two runs over
// the same input read the same.
type Model struct {
	facts []Fact
	at    map[string]int   // key to position in facts
	pred  map[string][]int // predicate to positions, in order
	given int              // facts[:given] were given, not derived
	start time.Time
	end   time.Time
}

// seed builds a model from the facts a caller gave. A triple missing a
// subject, predicate or object states nothing and is dropped; so is a repeat
// of a claim already present.
func seed(facts []semantic.Triple) *Model {
	m := &Model{at: make(map[string]int, len(facts)), pred: map[string][]int{}}
	for _, t := range facts {
		m.add(Fact{Triple: t})
	}
	m.given = len(m.facts)
	return m
}

// add records a fact, unless it says nothing or says what is already known.
// Dropping the repeat is what stops a cycle: x part_of y and y part_of x
// close after one round instead of forever.
func (m *Model) add(f Fact) {
	if blank(f.Subject) || blank(f.Predicate) || blank(f.Object) {
		return
	}
	key := f.Key()
	if _, seen := m.at[key]; seen {
		return
	}
	m.at[key] = len(m.facts)
	m.pred[f.Predicate] = append(m.pred[f.Predicate], len(m.facts))
	m.facts = append(m.facts, f)
}

// All returns every fact in the model, given first, then derived.
func (m *Model) All() []Fact { return m.facts[:len(m.facts):len(m.facts)] }

// Given returns the facts the model started from, as they were accepted:
// deduplicated, and without any that stated nothing.
func (m *Model) Given() []Fact { return m.facts[:m.given:m.given] }

// Derived returns only what the run added, in the order it was derived.
func (m *Model) Derived() []Fact { return m.facts[m.given:len(m.facts):len(m.facts)] }

// Triples returns the derived facts as triples, ready to fold into a graph.
// The derivation stays behind in the model: a triple carries no room for it.
func (m *Model) Triples() []semantic.Triple {
	out := make([]semantic.Triple, 0, len(m.facts)-m.given)
	for _, f := range m.Derived() {
		out = append(out, f.Triple)
	}
	return out
}

// Fact returns the fact a key names.
func (m *Model) Fact(key string) (Fact, bool) {
	i, ok := m.at[key]
	if !ok {
		return Fact{}, false
	}
	return m.facts[i], true
}

// Has reports whether the model holds a claim, given or derived.
func (m *Model) Has(t semantic.Triple) bool {
	_, ok := m.at[Key(t)]
	return ok
}

// Match returns one binding per fact the pattern matches, in model order.
// It is how a question is asked of the closure: leave a variable where the
// answer goes.
func (m *Model) Match(p Pattern) []Bind {
	var out []Bind
	for _, i := range m.candidates(p, 0, len(m.facts)) {
		b, ok := p.Match(m.facts[i].Triple, nil)
		if !ok {
			continue
		}
		if b == nil { // a pattern with no variables binds nothing
			b = Bind{}
		}
		out = append(out, b)
	}
	return out
}

// Why returns the derivation of a fact: everything it rests on, leaves
// first, ending with the fact itself. A given fact rests on nothing and so
// explains itself in one line. Each fact appears once however many
// derivations reached it.
func (m *Model) Why(key string) ([]Fact, error) {
	var out []Fact
	seen := map[string]bool{}
	var walk func(string) error
	walk = func(k string) error {
		if seen[k] {
			return nil
		}
		seen[k] = true
		f, ok := m.Fact(k)
		if !ok {
			return fmt.Errorf("%w: %q", ErrMissing, k)
		}
		for _, p := range f.Premises {
			if err := walk(p); err != nil {
				return err
			}
		}
		out = append(out, f)
		return nil
	}
	if err := walk(key); err != nil {
		return nil, err
	}
	return out, nil
}

// Prov renders the model in PROV-O terms: every fact is an Entity named by
// its Key, and every derived fact was generated by an Activity whose kind is
// the rule that fired and which used the premises. Given facts have no
// activity, because this run did not derive them. The agent is the caller's
// to name and to declare; the record joins whatever prov.Log it is written
// to without translation.
func (m *Model) Prov(agent string) ([]prov.Entity, []prov.Activity) {
	entities := make([]prov.Entity, 0, len(m.facts))
	var activities []prov.Activity
	for _, f := range m.facts {
		e := prov.Entity{ID: f.Key()}
		if f.Rule != "" {
			a := prov.Activity{
				ID:    "derive" + sep + f.Key(),
				Kind:  f.Rule,
				Agent: agent,
				Start: m.start,
				End:   m.end,
				Used:  f.Premises,
			}
			e.GeneratedBy = a.ID
			e.DerivedFrom = f.Premises
			activities = append(activities, a)
		}
		entities = append(entities, e)
	}
	return entities, activities
}