samovar-py 0.6__tar.gz

samovar-py-0.6/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.1
+Name: samovar-py
+Version: 0.6
+Summary: Samovar: model worlds using propositions and run simulations in them
+Author-email: Chris Pressey <packages@catseye.tc>
+License: This is free and unencumbered software released into the public domain.
+        
+        Anyone is free to copy, modify, publish, use, compile, sell, or
+        distribute this software, either in source code form or as a compiled
+        binary, for any purpose, commercial or non-commercial, and by any
+        means.
+        
+        In jurisdictions that recognize copyright laws, the author or authors
+        of this software dedicate any and all copyright interest in the
+        software to the public domain. We make this dedication for the benefit
+        of the public at large and to the detriment of our heirs and
+        successors. We intend this dedication to be an overt act of
+        relinquishment in perpetuity of all present and future rights to this
+        software under copyright law.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+        OTHER DEALINGS IN THE SOFTWARE.
+        
+        For more information, please refer to <http://unlicense.org/>
+        
+Project-URL: website, https://catseye.tc/node/Samovar
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Python: >=2.7,>=3.5
+Description-Content-Type: text/markdown
+
+Samovar
+=======
+
+Version 0.6 | _Entry_ [@ catseye.tc](https://catseye.tc/node/Samovar)
+| _See also:_ [The League of Extraordinarily Dull Gentlemen](https://github.com/catseye/NaNoGenMo-Entries-2018/tree/master/league#readme)
+∘ [The Swallows](https://github.com/catseye/The-Swallows#readme)
+
+- - - -
+
+**Samovar** is a domain-specific language (DSL) for modelling a world using
+propositions (facts), and possible events that can occur based on those facts,
+changing them.
+
+Here is a short example of a Samovar description:
+
+    scenario IgnatzWithBrick {
+      
+        [actor(?A),item(?I),~holding(?A,?I)]  ?A picks up the ?I.   [holding(?A,?I)]
+        [actor(?A),item(?I),holding(?A,?I)]   ?A puts down the ?I.  [~holding(?A,?I)]
+    
+        actor(Ignatz).
+        item(brick).
+    
+        goal [].
+    }
+
+And an implementation of Samovar could take this scenario and use it to,
+among other things, generate textual descriptions of chains of events like
+
+    Ignatz picks up the brick. Ignatz puts down the brick.
+
+Of course, this is a very simple example.  (It doesn't even prevent two
+actors from picking up the same item at the same time!)  For more complex
+examples, and a fuller description of the language, see
+[doc/Samovar.md](doc/Samovar.md), which also serves as a test suite.
+
+### Implementation
+
+The reference implementation of Samovar, `samovar`, is written in Python.
+It can run under either Python 2.7 or Python 3.x (tested with 3.5 or higher.)
+
+### Discussion
+
+This looks like logic programming but the internals are actually much simpler,
+and what it's doing is not logical inference.
+
+The internals are far simpler than an inference engine or a theorem
+prover: there are no logical rules in the database, only propositions, so
+they can be selected by simple pattern-matching rather than full unification.
+
+I originally described it as an "assertion-retraction engine", which could
+be thought of as a highly stylized form of Prolog programming.  Alternately,
+it could be thought of as assigning preconditions and postconditions, like
+in [Hoare logic][], to actions in a world-model.  Instead of constructing a
+proof, though, we simply chain actions together, by selecting any next one
+whose preconditions hold, and altering the world so that its postconditions hold.
+
+In (I think) autumn 2019, I came across the concept of a [production system][],
+and I realized that is basically what Samovar implements.  Researching it
+further, I discovered [CLIPS][], a production system built in 1985,
+and I realized that Samovar is not essentially different from an
+inefficiently-implemented, stripped-down version of CLIPS.
+
+The main innovation in Samovar is the ability to "narrate" the choices the
+production system makes, with human-readable text.
+
+This isn't too surprising, since my goal with Samovar was to make an expressive
+language, a syntax in which the author could write a story generator without
+the undue effort of switching context between prose and code.  Picking logical
+propositions for the "code" and placing them before and after each fragment of
+prose was a reasonably "ergonomic" choice, and happens to coincide with the
+structure of a production system.
+
+[Hoare logic]: https://en.wikipedia.org/wiki/Hoare_logic
+[production system]: https://en.wikipedia.org/wiki/Production_system_(computer_science)
+[CLIPS]: https://en.wikipedia.org/wiki/CLIPS
+
+### TODO
+
+*   Maybe allow variables to be notated so that they can bind reflexively,
+    e.g. `?*A looks at ?*B` can bind both variables to Alice.
+*   Make `?_` work such that you can say `¬holding(?_, club)` to mean
+    "if no one is holding the club".

samovar-py-0.6/README.md

@@ -0,0 +1,83 @@
+Samovar
+=======
+
+Version 0.6 | _Entry_ [@ catseye.tc](https://catseye.tc/node/Samovar)
+| _See also:_ [The League of Extraordinarily Dull Gentlemen](https://github.com/catseye/NaNoGenMo-Entries-2018/tree/master/league#readme)
+∘ [The Swallows](https://github.com/catseye/The-Swallows#readme)
+
+- - - -
+
+**Samovar** is a domain-specific language (DSL) for modelling a world using
+propositions (facts), and possible events that can occur based on those facts,
+changing them.
+
+Here is a short example of a Samovar description:
+
+    scenario IgnatzWithBrick {
+      
+        [actor(?A),item(?I),~holding(?A,?I)]  ?A picks up the ?I.   [holding(?A,?I)]
+        [actor(?A),item(?I),holding(?A,?I)]   ?A puts down the ?I.  [~holding(?A,?I)]
+    
+        actor(Ignatz).
+        item(brick).
+    
+        goal [].
+    }
+
+And an implementation of Samovar could take this scenario and use it to,
+among other things, generate textual descriptions of chains of events like
+
+    Ignatz picks up the brick. Ignatz puts down the brick.
+
+Of course, this is a very simple example.  (It doesn't even prevent two
+actors from picking up the same item at the same time!)  For more complex
+examples, and a fuller description of the language, see
+[doc/Samovar.md](doc/Samovar.md), which also serves as a test suite.
+
+### Implementation
+
+The reference implementation of Samovar, `samovar`, is written in Python.
+It can run under either Python 2.7 or Python 3.x (tested with 3.5 or higher.)
+
+### Discussion
+
+This looks like logic programming but the internals are actually much simpler,
+and what it's doing is not logical inference.
+
+The internals are far simpler than an inference engine or a theorem
+prover: there are no logical rules in the database, only propositions, so
+they can be selected by simple pattern-matching rather than full unification.
+
+I originally described it as an "assertion-retraction engine", which could
+be thought of as a highly stylized form of Prolog programming.  Alternately,
+it could be thought of as assigning preconditions and postconditions, like
+in [Hoare logic][], to actions in a world-model.  Instead of constructing a
+proof, though, we simply chain actions together, by selecting any next one
+whose preconditions hold, and altering the world so that its postconditions hold.
+
+In (I think) autumn 2019, I came across the concept of a [production system][],
+and I realized that is basically what Samovar implements.  Researching it
+further, I discovered [CLIPS][], a production system built in 1985,
+and I realized that Samovar is not essentially different from an
+inefficiently-implemented, stripped-down version of CLIPS.
+
+The main innovation in Samovar is the ability to "narrate" the choices the
+production system makes, with human-readable text.
+
+This isn't too surprising, since my goal with Samovar was to make an expressive
+language, a syntax in which the author could write a story generator without
+the undue effort of switching context between prose and code.  Picking logical
+propositions for the "code" and placing them before and after each fragment of
+prose was a reasonably "ergonomic" choice, and happens to coincide with the
+structure of a production system.
+
+[Hoare logic]: https://en.wikipedia.org/wiki/Hoare_logic
+[production system]: https://en.wikipedia.org/wiki/Production_system_(computer_science)
+[CLIPS]: https://en.wikipedia.org/wiki/CLIPS
+
+### TODO
+
+*   Maybe allow variables to be notated so that they can bind reflexively,
+    e.g. `?*A looks at ?*B` can bind both variables to Alice.
+*   Make `?_` work such that you can say `¬holding(?_, club)` to mean
+    "if no one is holding the club".

samovar-py-0.6/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

samovar-py-0.6/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "samovar-py"
+version = "0.6"
+authors = [
+    { name="Chris Pressey", email="packages@catseye.tc" },
+]
+urls = { website="https://catseye.tc/node/Samovar" }
+description = "Samovar: model worlds using propositions and run simulations in them"
+readme = "README.md"
+license = { file="UNLICENSE" }
+classifiers = [
+    "License :: OSI Approved :: The Unlicense (Unlicense)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 2.7",
+    "Programming Language :: Python :: 3",
+    "Topic :: Artistic Software",
+    "Topic :: Games/Entertainment :: Simulation",
+]
+requires-python = ">=2.7, >=3.5"
+
+[project.scripts]
+samovar = "samovar.main:sys_main"

samovar-py-0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

samovar-py-0.6/src/samovar/ast.py

@@ -0,0 +1,56 @@
+# encoding: UTF-8
+
+from collections import namedtuple
+
+
+# Python 2/3
+try:
+    unicode = unicode
+except NameError:
+    unicode = str
+
+
+World = namedtuple('World', ['scenarios'])
+
+
+class Rule(namedtuple('Rule', ['pre', 'words', 'post'])):
+    __slots__ = ()
+
+    def format(self, unifier):
+        return join_sentence_parts([unicode(t.subst(unifier)) for t in self.words])
+
+    def to_json(self):
+        return join_sentence_parts([unicode(t) for t in self.words])
+
+
+Scenario = namedtuple('Scenario', ['name', 'propositions', 'rules', 'goal'])
+Cond = namedtuple('Cond', ['exprs', 'bindings'])
+Assert = namedtuple('Assert', ['term'])
+Retract = namedtuple('Retract', ['term'])
+
+
+def join_sentence_parts(parts):
+    acc = u''
+    quote_open = False
+    for part in parts:
+        last = '' if not acc else acc[-1]
+        if last == '':
+            acc += part
+        elif last == '"' and quote_open:
+            acc += part
+        elif last == '"' and not quote_open:
+            if part in (u'.', u',', u'!', u'?'):
+                acc += part
+            else:
+                acc += ' ' + part
+        elif last == ',' and part == u'"' and not quote_open:
+            acc += ' ' + part
+        elif last in (u'.', u',', u'!', u'?', u"'") and part == u'"' and not quote_open:
+            acc += part
+        elif part in (u'.', u',', u'!', u'?', u"'", u'"'):
+            acc += part
+        else:
+            acc += u' ' + part
+        if part == '"':
+            quote_open = not quote_open
+    return acc

samovar-py-0.6/src/samovar/database.py

@@ -0,0 +1,74 @@
+from samovar.ast import Assert, Retract
+
+
+class Database(object):
+    """A database is a set of things true at some point in time in a world."""
+
+    def __init__(self, propositions, sorted_search=True):
+        """Create a new Database object with the given propositions.
+
+        While the construction and iteration of the underlying set in Python 2 seems to be
+        stable, when running under Python 3, we get an unpredictable order when iterating
+        over the set.  The `sorted_search` option controls whether we sort the iterable
+        before making matches, so that we can accumulate them in a predictable order.
+        This is valuable for tests, but can be turned off to improve performance.
+
+        """
+        self.sorted_search = sorted_search
+        self.contents = set()
+        for term in propositions:
+            self.contents.add(term)
+
+    def clone(self):
+        return Database(self.contents, sorted_search=self.sorted_search)
+
+    def add(self, term):
+        self.contents.add(term)
+
+    def remove(self, term):
+        self.contents.remove(term)
+
+    def match_all(self, patterns, env):
+        """Find all matches for the given patterns in the database, and return a list of unifiers.
+
+        `database` is an iterable of `Term`s.
+        `patterns` is a list of `Assert`s and `Retract`s.
+        `env` is a dict mapping `Var` names to `Term`s (a previous unifier.)
+
+        """
+        if not patterns:
+            return [env]
+        envs = []
+        pattern = patterns[0]
+
+        if isinstance(pattern, Assert):
+            for proposition in (sorted(self.contents) if self.sorted_search else self.contents):
+                unifier = pattern.term.match(proposition, env, unique_binding=True)
+                if unifier is None:
+                    continue
+                envs.extend(self.match_all(patterns[1:], unifier))
+
+        elif isinstance(pattern, Retract):
+            expanded_pattern = pattern.term.subst(env)
+
+            # To test a negative match, we require that there are
+            # no free variables remaining in our pattern.  If there are,
+            # it will simply not match.  TODO add a flag to turn this
+            # check on to support better debugging.
+
+            # free_vars = set()
+            # expanded_pattern.collect_variables(free_vars)
+            # if free_vars:
+            #     # TODO: better exception than this
+            #     raise NotImplementedError
+
+            # now we simply check if the term exists in the database.
+            # if it does not, we recurse down to the next clause in the pattern.
+
+            if not (expanded_pattern in self.contents):
+                envs.extend(self.match_all(patterns[1:], env))
+
+        else:
+            raise NotImplementedError
+
+        return envs

samovar-py-0.6/src/samovar/generators/base.py

@@ -0,0 +1,64 @@
+# encoding: UTF-8
+
+import sys
+
+from samovar.ast import Assert, Retract
+
+
+# Python 2/3
+try:
+    xrange = xrange
+except NameError:
+    xrange = range
+
+# Python 2/3
+try:
+    unicode = unicode
+except NameError:
+    unicode = str
+
+
+class Event(object):
+    def __init__(self, rule, unifier):
+        self.rule = rule
+        self.unifier = unifier
+
+    def to_json(self):
+        u = dict([(unicode(k), unicode(v)) for k, v in self.unifier.items()])
+        return [self.rule.to_json(), u]
+
+    def __str__(self):
+        return self.rule.format(self.unifier)
+
+
+class BaseGenerator(object):
+    def __init__(self, world, scenario, **kwargs):
+        self.world = world
+        self.scenario = scenario
+
+    def goal_is_met(self, state):
+        matches = state.match_all(self.scenario.goal.exprs, self.scenario.goal.bindings)
+        return len(matches) > 0
+
+    def candidate_rules(self, state, require_change=False):
+        """A generator."""
+        for rule in self.scenario.rules:
+            for unifier in state.match_all(rule.pre.exprs, rule.pre.bindings):
+                if require_change and not rule.post.exprs:
+                    # Rules that don't change the state of the world are not worth considering.
+                    continue
+                yield (rule, unifier)
+
+    def update_state(self, state, env, rule):
+        for expr in rule.post.exprs:
+            term = expr.term.subst(env)
+            if isinstance(expr, Assert):
+                state.add(term)
+            elif isinstance(expr, Retract):
+                state.remove(term)
+
+    def debug_state(self, state, label):
+        sys.stderr.write(":::: {} State [\n".format(label))
+        for term in sorted(state.contents):
+            sys.stderr.write("::::   {}\n".format(term))
+        sys.stderr.write(":::: ]\n")

samovar-py-0.6/src/samovar/generators/breadthfirst.py

@@ -0,0 +1,57 @@
+# encoding: UTF-8
+
+"""A breadth-first searching Generator that finds the
+shortest path of events that leads to the goal state
+(if any such path exists).
+"""
+
+import sys
+import time
+
+from samovar.ast import Assert, Retract
+from samovar.database import Database
+
+from .base import Event, BaseGenerator
+
+
+class BreadthFirstGenerator(BaseGenerator):
+    def __init__(self, world, scenario, verbosity=0, sorted_search=True, randomness=None):
+        self.world = world
+        self.scenario = scenario
+        self.verbosity = verbosity
+        self.sorted_search = sorted_search
+        self.random = randomness
+
+    def generate_events(self, **kwargs):
+        situations = [
+            ([], Database(self.scenario.propositions, sorted_search=self.sorted_search))
+        ]
+
+        seen_states = set()
+
+        while True:
+            new_situations = []
+            if self.verbosity >= 1:
+                sys.stderr.write("Considering {} situations\n".format(len(situations)))
+                start_time = time.time()
+            for (events, state) in situations:
+                for rule, unifier in self.candidate_rules(state, require_change=True):
+                    new_event = Event(rule, unifier)
+                    new_state = state.clone()
+                    self.update_state(new_state, unifier, rule)
+                    froz = frozenset(new_state.contents)
+                    if froz in seen_states:
+                        continue
+                    seen_states.add(froz)
+                    new_events = events + [new_event]
+                    if self.goal_is_met(new_state):
+                        return new_events
+                    new_situations.append(
+                        (new_events, new_state)
+                    )
+            if self.verbosity >= 1:
+                end_time = time.time()
+                duration = end_time - start_time
+                sys.stderr.write("Considered {} situations in {} seconds ({} situations / second)\n".format(len(situations), duration, float(len(situations))/duration))
+                sys.stderr.write("Installing {} new situations\n".format(len(new_situations)))
+            situations = new_situations

samovar-py-0.6/src/samovar/generators/depthfirst.py

@@ -0,0 +1,73 @@
+# encoding: UTF-8
+
+# FIXME: just a sketch for now
+
+import sys
+import time
+
+from samovar.ast import Assert, Retract
+from samovar.database import Database
+
+from .base import Event, BaseGenerator
+
+
+class DepthFirstGenerator(BaseGenerator):
+    def __init__(self, world, scenario, verbosity=0, sorted_search=True, randomness=None):
+        self.world = world
+        self.scenario = scenario
+        self.verbosity = verbosity
+        self.sorted_search = sorted_search
+        self.random = randomness
+        self.seen_states = set()
+
+    def generate_events(self, **kwargs):
+        self.seen_states = set()
+
+        # Create initial stacks.
+        state = Database(self.scenario.propositions, sorted_search=self.sorted_search)
+        candidate_rules = list(self.candidate_rules(state, require_change=True))
+        stack = [
+            [None, state, candidate_rules, 0]
+        ]
+
+        # Loop, doing work at the top of the stack.
+        done = False
+        counter = 0
+        while not done:
+            counter += 1
+            [last_event, state, candidate_rules, cr_index] = stack[-1]
+            if self.verbosity >= 1 and counter % 1000 == 0:
+                sys.stderr.write("Stack depth {}, candidate count {}, index {}\n".format(
+                    len(stack), len(candidate_rules), cr_index
+                ))
+            if cr_index > (len(candidate_rules) - 1):
+                # we've exhausted all the candidates on this level.  backtrack.
+                if self.verbosity >= 1:
+                    sys.stderr.write("*** Backtracking\n")
+                stack.pop()
+                continue
+
+            # otherwise, try to make a match.
+            rule, unifier = candidate_rules[cr_index]
+
+            new_event = Event(rule, unifier)
+            new_state = state.clone()
+            self.update_state(new_state, unifier, rule)
+            if self.verbosity >= 2:
+                self.debug_state(new_state, "Intermediate")
+            if self.goal_is_met(new_state):
+                return [e[0] for e in stack if e[0] is not None] + [new_event]
+
+            froz = frozenset(new_state.contents)
+            if froz in self.seen_states:
+                stack[-1][3] += 1   # inc cr_index. TODO this is so ugly
+                continue
+            self.seen_states.add(froz)
+
+            # otherwise, descend to try to extend the sequence of events we've got.
+            new_candidate_rules = list(self.candidate_rules(new_state, require_change=True))
+            stack.append(
+                [new_event, new_state, new_candidate_rules, 0]
+            )
+
+        return None

samovar-py-0.6/src/samovar/generators/stochastic.py

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+
+import sys
+
+from samovar.database import Database
+
+from .base import xrange, Event, BaseGenerator
+
+
+class StochasticGenerator(BaseGenerator):
+    def __init__(self, world, scenario, verbosity=0, sorted_search=True, randomness=None):
+        self.world = world
+        self.scenario = scenario
+        self.verbosity = verbosity
+        self.sorted_search = sorted_search
+        self.random = randomness
+        self.reset_state()
+
+    def reset_state(self):
+        self.state = Database(self.scenario.propositions, sorted_search=self.sorted_search)
+
+    def generate_events(self, min_count=0, max_count=100, lengthen_factor=1.5):
+        acceptable = False
+        count = min_count
+        while not acceptable:
+            if self.verbosity >= 1:
+                sys.stderr.write("Generating {} events\n".format(count))
+            self.reset_state()
+            if self.verbosity >= 2:
+                self.debug_state(self.state, "Initial")
+            events = []
+            for i in xrange(0, count):
+                event = self.generate_event()
+                if event is None:
+                    break
+                events.append(event)
+            if self.verbosity >= 2:
+                self.debug_state(self.state, "Final")
+            acceptable = self.goal_is_met(self.state)
+            if not acceptable:
+                count = int(float(count) * lengthen_factor)
+            if count > max_count:
+                raise ValueError("{}: count exceeds maximum".format(self.scenario.name))
+        return events
+
+    def generate_event(self):
+        candidates = list(self.candidate_rules(self.state))
+
+        if self.verbosity >= 3:
+            sys.stderr.write("Candidate rules:\n")
+            for rule, unifiers in candidates:
+                sys.stderr.write("-> " + rule.to_json() + "\n")
+                sys.stderr.write("---> {}\n".format(unifiers))
+            sys.stderr.write("")
+
+        if not candidates:
+            return None
+        rule, unifier = self.random.choice(candidates)
+        self.update_state(self.state, unifier, rule)
+        if self.verbosity >= 3:
+            self.debug_state(self.state, "Intermediate")
+        return Event(rule, unifier)