001  (ns wildwood.advocate
002    "An agent capable of playing the explanation game.
003  
004    An advocate must have its own knowledge accessor. Different advocates
005    within a game may be accessing different knowledge bases, or different
006    subsets of the same knowledge base with different - potentially competing
007    - knowledge. It also needs to know the schema in which knowledge will be
008    presented.
009  
010    Since the mechanism by which the application will communicate with the
011    library must include a way for users to interact with the game, and
012    since the role of the user in the came is just as a participant,
013    advocate must be defined as a protocol, in order that it may be extended
014    by code within the application which is passed in to the game when the
015    game is started. Indeed, multiple agents - the user(s) and potentially
016    non-player characters - may be passed in.
017  
018    In this conception, nothing within a default advocate has to be able to
019    produce or consume natural language. It is sufficient for the API exposed
020    by wildwood.advocate to receive and return wildwood.schema objects.
021  
022    Obviously to show a user interface anything similar to Arden's, or for
023    what I intend for The Great Game, the advocates passed must 'at their
024    other end' - that is, on the application side rather than the library
025    side - be able to consume and emit natural language, but that functionality
026    does not need to be part of the wildwood library, and certainly does
027    not need to be part of the default advocate as specified here."
028    (:require [wildwood.knowledge-accessor :refer [Accessor]]
029              [wildwood.schema :refer [proposition? argument?]]))
030  
031  (defprotocol Advocate
032    (record [self proposition value]
033            "Pass a `proposition` with a determined `value` to me, in order that
034            advocates can, if desired, record the determined value in their
035            knowledge base. The API does not require that the advocate records
036            the decision, only that it has the opportunity to do so. Return the
037            value.")
038    (id [self] "Return a value which uniquely identifies this agent.")
039    (decide [self proposition argument]
040            "Return `true`, `false` or `nil` as the value of this `proposition`,
041            given this `argument`. The value of `proposition` should be a
042            proposition as defined by `wildwood.schema/proposition?`;
043            the value of `argument` should satisfy `wildwood.schema/argument?`.")
044    (move [self proposition argument]
045          "Return a new argument structure representing the result of applying my
046          `decide` method to this `proposition` and `argument`, specifying in
047          some way not yet determined what sort of move I have made."))