From c6f12b4d4edbf762873a99217e9e0271a8787210 Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Thu, 23 Apr 2020 15:27:01 +0100 Subject: [PATCH] Finished - for now - the chapter on Arboretum --- doc/Arboretum.md | 140 ++++++++++----- docs/codox/AgainstTruth.html | 2 +- docs/codox/Analysis.html | 2 +- docs/codox/Arboretum.html | 73 +++++--- docs/codox/Arden.html | 2 +- docs/codox/BatesonKammerer.html | 2 +- docs/codox/Bialowieza.html | 2 +- docs/codox/Errata.html | 2 +- docs/codox/Experience.html | 2 +- docs/codox/HegemonicArgument.html | 2 +- docs/codox/History.html | 2 +- docs/codox/HuxleyKropotkin.html | 2 +- docs/codox/Implementing.html | 2 +- docs/codox/JAccuse.html | 2 +- docs/codox/KnacqTools.html | 2 +- docs/codox/Manifesto.html | 2 +- docs/codox/OnHylasAndPhilonus.html | 2 +- docs/codox/PredicateSubtext.html | 2 +- docs/codox/TheProblem.html | 2 +- docs/codox/index.html | 2 +- docs/codox/intro.html | 2 +- docs/codox/wildwood.advocate.html | 2 +- docs/codox/wildwood.bialowieza.html | 2 +- docs/codox/wildwood.caesar.html | 2 +- docs/codox/wildwood.dengine.engine.html | 2 +- docs/codox/wildwood.dengine.node.html | 3 + docs/codox/wildwood.knowledge-accessor.html | 2 +- docs/codox/wildwood.schema.html | 8 +- docs/img/dtree-live-with-partner.svg | 119 +++++++++++++ docs/img/dtree-widows-allowance.svg | 178 ++++++++++++++++++++ docs/img/example-dtree.svg | 145 ++++++++++++++++ docs/img/simplest-possible-dtree.svg | 89 ++++++++++ 32 files changed, 705 insertions(+), 98 deletions(-) create mode 100644 docs/codox/wildwood.dengine.node.html create mode 100644 docs/img/dtree-live-with-partner.svg create mode 100644 docs/img/dtree-widows-allowance.svg create mode 100644 docs/img/example-dtree.svg create mode 100644 docs/img/simplest-possible-dtree.svg diff --git a/doc/Arboretum.md b/doc/Arboretum.md index 3386478..04d9b0d 100644 --- a/doc/Arboretum.md +++ b/doc/Arboretum.md @@ -100,11 +100,7 @@ downwards, and, when connecting different colours, as meaning 'unless'. Thus the most basic structure is "hypothesis is false unless condition is true": -Basic DTree - -Hypothesis - - -Condition + +![Simplest possible DTree](../img/simplest-possible-dtree.svg) fig 3: simplest possible rule Conjunctions are represented by columns of nodes, only the last of which has the colour to be returned if all are @@ -113,17 +109,7 @@ colour to be returned if any are true. These can be combined in any fashion desired, although we consider it good practise to keep individual rule structures small. This is shown in the figure below: -Example DTree - -Root Node - - -1st Conjunct - - -2nd Conjunct + - -1st Disjunct - - -2nd Disjunct - +![Example DTree](../img/example-dtree.svg) fig 4: example rule, showing syntax The rule would read: "(rootnode) is false unless (first conjunct) is true and (second conjunct) is true, in @@ -137,7 +123,7 @@ any way that affects the underlying ideas. A feature has the properties: - (methods DTreeRootnode default activeFlg) + where methods is the list of methods that the feature applies to see if it holds of the given object, @@ -156,7 +142,7 @@ just the list (DoTree Default) and describe the algorithms accordingly. A DTree for a feature is a list of nodes. A node has the properties: - (feature, colour, children, parent) + Feature points to a feature of the system, colour is either Yes or No, children point to successor nodes of @@ -244,6 +230,8 @@ did not) when that node was conceived as the only sticking node. The structure of the system itself then ensured that in the final text, the fragment would follow sensibly from the preceding one. +This is described in more detail, with worked examples, below. + We discussed and experimented with several algorithms for the recovery of explanations. The one we used worked as follows: when a search resulted in a 'no' decision (ineligible for a benefit) then we @@ -272,31 +260,11 @@ To provide a small worked example of an explanation generated by the system, which is yet large enough to give some flavour, let us assume our knowledge base contains the following rules: -DTree for Entitled to Widow's Allowance - -Entitled to Widov's Allowance - - -Satisfies conditions for Widoy's Allowance + - ->26 Yeeks Killed husband - Dead - bereaved - - -- - -in prison - Levering with - -in prison - Living Yith - -Partner - +![DTree for 'Entitled to Widows' Allowance](../img/dtree-widows-allowance.svg) fig 1: Rule for "Entitled to Widow's Allowance" -DTree for Living with Partner - -Living with Partner - - -Remarried + - -Cohabiting + +![DTree for Living with Partner](../img/dtree-live-with-partner.svg) fig 2: rule for "Living with Partner" @@ -374,15 +342,101 @@ that she had not, in fact remarried. ## Explanation: a discussion -{\*\* Write something (preferably rather a lot) here \*\*} +### Writing explanation fragments -This ability to abstract relevant information from an inference engine's +Arboretum's explanation fragments are canned text written by the knowledge +engineer in constructing the rule system. However, because of the way they +are concatenated, they are extremely easy to write. Each is basically just +a declarative sentence saying, in natural language + + is because + is true and none of + are true. + +Thus, for the `Remarried -` node referenced above, the automatically +generated canned text - had we automatically generated the text, which +we did not - would have been + +> Living with partner is true because remarried is true. + +which would probably have been good enough. However, because texts are +concatenated from the sticking nodes of the successive trees, we know that +the previous sentence will have ended with some natural language expression +of the proposition + +> Living with partner is true. + +Thus, provided we know that the tree for which we are writing the node texts +is not the top level tree in the decision system, we can avoid rewriting this +proposition. So the declarative sentence becomes simply + + is true and none of + are true. + +But in this instance there are no children of the node `Remarried +`, so this +reduces to + + is true + +The actual, manually written text used in the system, as stated above, was + +> We understand that you have remarried. + +As you can see, this sentence is a polite and understandable representation +of the proposition + + Remarried is true + +Thus, the claim I am making here - but mildly, it's not a strong claim - is +that even without hand written canned texts, the conceptual +design of the DTree engine would allow the automatic construction +of perfectly usable explanations. + +Arboretum was the first deliverable system from the Alvey DHSS Large +Demonstrator project actually to be delivered, and, I think, of the systems +the project did deliver, the most polished and most functional, if not the +most ambitious. However, it was not intended that the systems built by the +project would actually be put into front line use, and indeed none ever were. + +Nevertheless, in designing the system, we took very seriously the idea of how +an adjudication officer would use such a system in the real world. It's +important for the officer to explain clearly to a claimant why a claim has +been disallowed, in language the claimant will understand. Thus, manually +written fragments made for much less stilted English, and produced a +plausible verisimilitude of an entirely personal letter. + +As one of the problems that the DHSS was experiencing at the time was appeals +made because the claimant had not understood the reasons for a decision not +to award benefit, these very simple, clear, apparently-personal letters seemed +to us a significant feature in the potential usability of the system. + +### Relevance filtering + +This brings us to the question of how Arboretum managed relevance filtering. +The answer, as the intelligent reader will already have spotted, is that we +did not. Relevance fell fortuitously out of the process of evaluation. The +deepest sticking node on each tree on the path to the final decision +represents the 'interesting' reason to refuse, within the context of that +tree; the concatenation of the 'interesting' reason to refuse from the +successive trees along the path constructed the argument from the general +to the particular which is precisely a good explanation of a decision. + +What's interesting about this was that in our later experience with +[KnacqTools](KnacqTools.html), which was essentially a commercialised +reimplementation of Arboretum on less illustrious hardware, we found that +this explanation algorithm, designed to assist adjudication officers, provided +explanations which were welcomed as clear and understandable in domains as +diverse as industrial process control and the diagnosis of fish diseases. + +## Conclusion + +Arboretum's ability to abstract relevant information from an inference engine's backtrace represents a partial solution to the problem described in the preceding chapters. ## References: -3\. Xerox Corporation: InterLisp Reference Manual ( Xerox Corporation, +3\. Xerox Corporation: InterLisp Reference Manual (Xerox Corporation, 1985) 4\. Daniel Bobrow & Mark Stefik: The LOOPS Manual (Xerox Corporation, diff --git a/docs/codox/AgainstTruth.html b/docs/codox/AgainstTruth.html index 53f4e73..f08d291 100644 --- a/docs/codox/AgainstTruth.html +++ b/docs/codox/AgainstTruth.html @@ -1,6 +1,6 @@ -Against Truth

Project

Topics

Namespaces

Against Truth

+Against Truth

Project

Topics

Namespaces

Against Truth

Simon Brooke

“Hey, what IS truth, man?” Beeblebrox, Z, quoted in [Adams, 1978]

diff --git a/docs/codox/Analysis.html b/docs/codox/Analysis.html index a636207..a4aec03 100644 --- a/docs/codox/Analysis.html +++ b/docs/codox/Analysis.html @@ -1,6 +1,6 @@ -Analysis

Project

Topics

Namespaces

Analysis

+Analysis

Project

Topics

Namespaces

Analysis

Accounts from the Philosophy of Science

(Towards another chapter. What l want to do is: ,

    diff --git a/docs/codox/Arboretum.html b/docs/codox/Arboretum.html index 2d44c29..5b79dbb 100644 --- a/docs/codox/Arboretum.html +++ b/docs/codox/Arboretum.html @@ -1,6 +1,6 @@ -Arboretum

    Project

    Topics

    Namespaces

    Arboretum

    +Arboretum

    Project

    Topics

    Namespaces

    Arboretum

    This chapter describes briefly an inference mechanism, implemented in the Arboretum prototype; this is included here to show the results achieved in the author’s early work on explanation, on which it is hoped to build in the current work. A fuller description of this mechanism, and of the Arboretum prototype, will be found in [Mott & Brooke 87], from which this chapter is largely drawn.

    Arboretum was written in InterLisp-D[4] using LOOPS [5] object oriented facilities, to allow people to manipulate DTree structures through graphical representations: to build arbitrarily large knowledge bases, to use these to provide answers to questions about objects in domains admitting incomplete information - and to provide natural language explanations of these answers. The inference process by which answers are produced is shown as an animated graph. The user can ask the system how the value of any particular feature was arrived at, and what that value was. . It was developed for the Alvey DHSS Large Demonstrator Project, and sought to meet early perceptions of the needs of DHSS Adjudication Officers. Adjudication Officers decide claimants’ eligibility over a wide range of welfare benefits. There is a very large volume of work to be done, so they work under considerable pressure.

    The Adjudication process within the DHSS has its own levels of authority culminating in the

    @@ -14,25 +14,18 @@

    Intuitively the deeper the level, the more unlikely the situations that occupy that level. It is our suggestion that the structure of exceptions that can explicitly be recovered by the knowledge engineer in this way is what is implicitly and imperfectly represented by the certainty factors in classical expert systems.

    These trees can then be directly interpreted as rules by the DTree algorithm, the root idea of which is that a decision has always been made, there is always an answer available, but one which the system is currently trying to refute. The eventual decision is simply the last one made, the one that the system has failed to refute. At any point it tries to “change its mind”, and when it can no longer do so that is the decision it delivers. After all, if there is nothing as yet unexamined that could make you change your mind why deliberate further, while if there is how may you legitimately stop? The idea of an alternating ‘yes/no’ with decision characterised simply by its position at the end is a very old one indeed due to Thomas Hobbes (16]. The emphasis on trying to refute rather than trying to confirm is of course Popperian (passim, but see for example his [17]).

    Let us summarise how to read a DTree rule structure. The basic units are nodes and the edges between them. An edge should always be read downwards, and, when connecting different colours, as meaning ‘unless’. Thus the most basic structure is “hypothesis is false unless condition is true”:

    -

    Basic DTree

    -

    Hypothesis -

    -

    Condition +

    +

    Simplest possible DTree

    fig 3: simplest possible rule Conjunctions are represented by columns of nodes, only the last of which has the colour to be returned if all are true and disjunctions by branches, each of which terminates in the colour to be returned if any are true. These can be combined in any fashion desired, although we consider it good practise to keep individual rule structures small. This is shown in the figure below:

    -

    Example DTree

    -

    Root Node -

    -

    1st Conjunct -

    -

    2nd Conjunct +

    -

    1st Disjunct -

    -

    2nd Disjunct -

    +

    Example DTree

    fig 4: example rule, showing syntax The rule would read: “(rootnode) is false unless (first conjunct) is true and (second conjunct) is true, in which case it is true unless either (first disjunct) or (second disjunct) is true”.

    A DTree system contains at any time a number of features, objects and nodes. In a LISP implementation these are litatoms equipped with property lists; the LOOPS implementation is rather different but not in any way that affects the underlying ideas.

    A feature has the properties:

    -
    (methods DTreeRootnode default activeFlg)
+
    <methods DTreeRootnode default activeFlg>
 
    
 
    where methods is the list of methods that the feature applies to see if it holds of the given object, DTreeRootnode holds a pointer to a DTree node if the feature is equipped with one (else NIL), default holds the default value of the feature, and activeFlg is simply a semaphore to prevent DTrees calling themselves.
    
 
    A word more about the methods property. This may in principle hold a list of any functions that are to be applied (in the order found) with standard arguments by the feature when it is called. A feature may thus be seen as a local “expert” whose task is to decide whether it holds of a given object by applying the list of methods it has been supplied with (this picture was suggested by Lenat [18]). However, for the sake of simplicity, we shall henceforth assume, that the methods property is just the list (DoTree Default) and describe the algorithms accordingly.
    
 
    A DTree for a feature is a list of nodes. A node has the properties:
    
-
    (feature, colour, children, parent)
+
    <feature, colour, children, parent>
 
    
 
    Feature points to a feature of the system, colour is either Yes or No, children point to successor nodes of the node (if any) and parent to the unique predescessor node (NIL for the origin of the DTree).
    
 
    An object is just a litatom. The system updates the property list of the object.
    
@@ -47,23 +40,14 @@
 
    The explanation system depended on and exploited the fact that DTrees are structured through exceptions from the very general to the more abstruse and particular; and that, in consequence, any path through a rule structure follows a line of coherent argument, again from the general to the particular. Thus a sticking node on the DTree for a feature both records a decision and, by its position in the DTree, implies an explanation of why that decision was made.
    
 
    Consequently, we attached to each node in the system a text fragment to explain the consequence for the feature whose rule the node was in, if that node were a sticking node. This explanation fragment was a piece of canned text, written by the knowledge engineer.
    
 
    When writing fragments, the knowledge engineer did not need to look beyond the DTree that was being edited. The task was simply to consider a node and attach text saying why the feature of the DTree obtained (or did not) when that node was conceived as the only sticking node. The structure of the system itself then ensured that in the final text, the fragment would follow sensibly from the preceding one.
    
+
    This is described in more detail, with worked examples, below.
    
 
    We discussed and experimented with several algorithms for the recovery of explanations. The one we used worked as follows: when a search resulted in a ‘no’ decision (ineligible for a benefit) then we concatenated the explanation fragments from the deepest sticking node in each succesive tree on the search path. The reason was that this represents the “nearest” that the claimant got to succeeding in the claim. This follows from the structure of the DTree, the deeper nodes represent more abstruse conditions: to reach them at all more general requirements for eligibility must have been met.
    
 
    Furthermore, the information given in this explanation should be sufficient to assist in the preparation of an appeal, if the claimant felt there were further relevant facts which hadn’t been considered - and this was, indeed, precisely our intention. It is, we think, part of the notion of relevance that it is the “nearest miss” that should be described in such cases.
    
 
    In the case of a ‘yes’ decision we chose the opposite approach and selected the shallowest sticking node available. This was partly because the claimant who succeeds is less concerned about why, but mostly because it is not relevant to describe how a long and tortuous inference path finally delivered ‘yes’ when a much shorter less involved one did so too. Again this seems in accord with ordinary ideas of relevance.
    
 
    To provide a small worked example of an explanation generated by the system, which is yet large enough to give some flavour, let us assume our knowledge base contains the following rules:
    
-
    DTree for Entitled to Widow’s Allowance
    
-
    Entitled to Widov’s Allowance -
    
-
    Satisfies conditions for Widoy’s Allowance +
    
-
    >26 Yeeks Killed husband - Dead - bereaved -
    
-
    -
    
-
    in prison - Levering with
    
-
    in prison - Living Yith
    
-
    Partner -
    
+
    DTree for ‘Entitled to Widows’ Allowance
    
 
    fig 1: Rule for “Entitled to Widow’s Allowance”
    
-
    DTree for Living with Partner
    
-
    Living with Partner -
    
-
    Remarried +
    
-
    Cohabiting +
    
+
    DTree for Living with Partner
    
 
    fig 2: rule for “Living with Partner”
    
 
    which, together, partially encode the following legislation fragment, from the Social Security Act 1975 [6], chapter 14, section 24, as amended by the Social Security (Miscellaneous Provisions) Act 1977, chapter 5, .section 22(2). This reads:
    
 
    24.-(1) A woman who has been widowed shall be entitled to widow's
@@ -103,10 +87,45 @@ man to whom she is not married are living together as man and wife.
 
    There are a number of points to notice. Firstly, we could easily have written far more friendly and less formal fragments; for example, We could have written “we wish you all the best in your new marriage”. The formality here is simply to help in understanding the mechanical nature of the concatenation process.
    
 
    Much more significantly, note that although the inference engine must have known or discovered, for example, that her previous husband had indeed been regular and conscientious about his national insurance contributions for it to have reached its conclusions, this information has been ’included out of the explanation. It is irrelevant. It is clear that, if our claimant wished to make an appeal, her grounds for doing so would have to be that the information provided had been incorrect, and that she had not, in fact remarried.
    
 
    Explanation: a discussion
    
-
    {** Write something (preferably rather a lot) here **}
    
-
    This ability to abstract relevant information from an inference engine’s backtrace represents a partial solution to the problem described in the preceding chapters.
    
+
    Writing explanation fragments
    
+
    Arboretum’s explanation fragments are canned text written by the knowledge engineer in constructing the rule system. However, because of the way they are concatenated, they are extremely easy to write. Each is basically just a declarative sentence saying, in natural language
    
+
    <name of feature at root node> is <colour of this node> because
+<name of feature at this node> is true and none of
+<names of features of children of this node> are true.
+
    
+
    Thus, for the Remarried - node referenced above, the automatically generated canned text - had we automatically generated the text, which we did not - would have been
    
+
    
+  
    Living with partner is true because remarried is true.
    
+
    
+
    which would probably have been good enough. However, because texts are concatenated from the sticking nodes of the successive trees, we know that the previous sentence will have ended with some natural language expression of the proposition
    
+
    
+  
    Living with partner is true.
    
+
    
+
    Thus, provided we know that the tree for which we are writing the node texts is not the top level tree in the decision system, we can avoid rewriting this proposition. So the declarative sentence becomes simply
    
+
    <name of feature at this node> is true and none of
+<names of features of children of this node> are true.
+
    
+
    But in this instance there are no children of the node Remarried +, so this reduces to
    
+
    <name of feature at this node> is true
+
    
+
    The actual, manually written text used in the system, as stated above, was
    
+
    
+  
    We understand that you have remarried.
    
+
    
+
    As you can see, this sentence is a polite and understandable representation of the proposition
    
+
    Remarried is true
+
    
+
    Thus, the claim I am making here - but mildly, it’s not a strong claim - is that even without hand written canned texts, the conceptual design of the DTree engine would allow the automatic construction of perfectly usable explanations.
    
+
    Arboretum was the first deliverable system from the Alvey DHSS Large Demonstrator project actually to be delivered, and, I think, of the systems the project did deliver, the most polished and most functional, if not the most ambitious. However, it was not intended that the systems built by the project would actually be put into front line use, and indeed none ever were.
    
+
    Nevertheless, in designing the system, we took very seriously the idea of how an adjudication officer would use such a system in the real world. It’s important for the officer to explain clearly to a claimant why a claim has been disallowed, in language the claimant will understand. Thus, manually written fragments made for much less stilted English, and produced a plausible verisimilitude of an entirely personal letter.
    
+
    As one of the problems that the DHSS was experiencing at the time was appeals made because the claimant had not understood the reasons for a decision not to award benefit, these very simple, clear, apparently-personal letters seemed to us a significant feature in the potential usability of the system.
    
+
    Relevance filtering
    
+
    This brings us to the question of how Arboretum managed relevance filtering. The answer, as the intelligent reader will already have spotted, is that we did not. Relevance fell fortuitously out of the process of evaluation. The deepest sticking node on each tree on the path to the final decision represents the ‘interesting’ reason to refuse, within the context of that tree; the concatenation of the ‘interesting’ reason to refuse from the successive trees along the path constructed the argument from the general to the particular which is precisely a good explanation of a decision.
    
+
    What’s interesting about this was that in our later experience with KnacqTools, which was essentially a commercialised reimplementation of Arboretum on less illustrious hardware, we found that this explanation algorithm, designed to assist adjudication officers, provided explanations which were welcomed as clear and understandable in domains as diverse as industrial process control and the diagnosis of fish diseases.
    
+
    Conclusion
    
+
    Arboretum’s ability to abstract relevant information from an inference engine’s backtrace represents a partial solution to the problem described in the preceding chapters.
    
 
    References:
    
-
    3. Xerox Corporation: InterLisp Reference Manual ( Xerox Corporation, 1985)
    
+
    3. Xerox Corporation: InterLisp Reference Manual (Xerox Corporation, 1985)
    
 
    4. Daniel Bobrow & Mark Stefik: The LOOPS Manual (Xerox Corporation, 1983)
    
 
    5. Mark Richer & William Clancey: “Guidon Watch: A Graphic Interface for Viewing a knowledge-Based System” IEEE Computer Gaphics and Applications vol 5 no 11,1985
    
 
    6. Social Security Act 1975: Her Majesty’s Stationery Office, London, 1975 Social Security (Miscellanous Provisions) Act 1977: Her Majesty’s Stationery Office, London, 1977
    
diff --git a/docs/codox/Arden.html b/docs/codox/Arden.html
index e0e1316..9c00ea0 100644
--- a/docs/codox/Arden.html
+++ b/docs/codox/Arden.html
@@ -1,6 +1,6 @@
 
-Arden
    Project
    Topics
    Namespaces
    Arden
    
+Arden
    Project
    Topics
    Namespaces
    Arden
    
 
    Why Arden?
    
 
    It was something of tradition in the InterLisp-D community to give successive versions of a project codenames with successive alphabetical initials. So the first version would have a name starting ‘A’, the second ‘B’, and so on. The first prototype for Wildwood was called ‘Arden’, because it starts with an ‘A’, and because it is a fantastical dream-like forest depicted in Shakespeare’s play ‘As You Like It’, which if I recall correctly was performed as a promenade performance by the Duke’s Theatre in Lancaster in that year. While Arboretum - that carefully tended garden of trees - had been, as I’ve said, largely Peter’s in concept, Wildwood would be mine.
    
 
    Background
    
diff --git a/docs/codox/BatesonKammerer.html b/docs/codox/BatesonKammerer.html
index f3442ed..6a588d8 100644
--- a/docs/codox/BatesonKammerer.html
+++ b/docs/codox/BatesonKammerer.html
@@ -1,4 +1,4 @@
 
-The Bateson / Kammerer debate
    Project
    Topics
    Namespaces
    The Bateson / Kammerer debate
    
+The Bateson / Kammerer debate
    Project
    Topics
    Namespaces
    The Bateson / Kammerer debate
    
 
    { TODO: analyse the style and motivations of the Bateson / Kammerer debate, drawing out the use of polemic and rhetoric to achieve hegemony }
    
\ No newline at end of file
diff --git a/docs/codox/Bialowieza.html b/docs/codox/Bialowieza.html
index 5e46015..30e1afa 100644
--- a/docs/codox/Bialowieza.html
+++ b/docs/codox/Bialowieza.html
@@ -1,6 +1,6 @@
 
-Bialowieza
    Project
    Topics
    Namespaces
    Bialowieza
    
+Bialowieza
    Project
    Topics
    Namespaces
    Bialowieza
    
 
    { this chapter is in active development; quite a lot of the technical detail in this chapter at present will probably end up in Implementing, while additional high level and conceptual design, as it develops, will be here. }
    
 
    Why Bialowieza?
    
 
    Bialowieza is the second iteration of the Wildwood engine, and this following convention its name should start with ‘B’. Białowieża is Europe’s last great wild wood, and it is currently under threat.
    
diff --git a/docs/codox/Errata.html b/docs/codox/Errata.html
index 8681c93..7173161 100644
--- a/docs/codox/Errata.html
+++ b/docs/codox/Errata.html
@@ -1,6 +1,6 @@
 
-Errata
    Project
    Topics
    Namespaces
    Errata
    
+Errata
    Project
    Topics
    Namespaces
    Errata
    
 
      
   
    1. On title page: the claim that Zaphod Beeblebrox is quoted as saying ‘Hey, what IS truth, man?’ in the printed text of Douglas Adams ‘Hitchhikers Guide to the Galaxy’ is false.
      2. 
 
    
\ No newline at end of file
diff --git a/docs/codox/Experience.html b/docs/codox/Experience.html
index 1fd834f..27b6eef 100644
--- a/docs/codox/Experience.html
+++ b/docs/codox/Experience.html
@@ -1,4 +1,4 @@
 
-Experience
    Project
    Topics
    Namespaces
    Experience
    
+Experience
    Project
    Topics
    Namespaces
    Experience
    
 
    {Not yet written. To cover an evaluation of the Clojure Wildwood library, when it works, and what I can learn from it going forward}
    
\ No newline at end of file
diff --git a/docs/codox/HegemonicArgument.html b/docs/codox/HegemonicArgument.html
index 4bd86f4..8b3348e 100644
--- a/docs/codox/HegemonicArgument.html
+++ b/docs/codox/HegemonicArgument.html
@@ -1,4 +1,4 @@
 
-Hegemonic Argument
    Project
    Topics
    Namespaces
    Hegemonic Argument
    
+Hegemonic Argument
    Project
    Topics
    Namespaces
    Hegemonic Argument
    
 
    { new chapter, beginning a sequence which argues that the purpose of argument is to achieve hegemony, not find truth. In this chapter we’ll cover the sources we’ve used already, and show that the philosophers of science, whatever they claim about the purpose of argument, actually argue in a highly polemical, persuasive manner, seeking to achieve widespread belief of their chosen position - that is, to achieve hegemony; and further, even those who make strong claims to the value of candour are frequently not candid in their own argument }
    
\ No newline at end of file
diff --git a/docs/codox/History.html b/docs/codox/History.html
index 8362c58..6b8e177 100644
--- a/docs/codox/History.html
+++ b/docs/codox/History.html
@@ -1,6 +1,6 @@
 
-History
    Project
    Topics
    Namespaces
    History
    
+History
    Project
    Topics
    Namespaces
    History
    
 
    History: Introduction
    
 
    The object of this chapter is to describe and discuss the development of Expert System explanations from the beginning’ to the most recent systems. The argument which I will try to advance is that development has been continuously driven by the perceived inadequacy of the explanations given; and that, while many ad hoc, and some principled, approaches have been tried, no really adequate explanation system has emerged. Further, I will claim that, as some of the later and more principled explanation systems accurately model the accounts of explanation advanced in current philosophy, the philosophical understanding of explanation is itself inadequate.
    
 
    {I ought to add to this chapter to give some overview of what’s happened since 1990, and look at explanations of neural network decisions, because that will help in later parts/chapters of Part One}
    
diff --git a/docs/codox/HuxleyKropotkin.html b/docs/codox/HuxleyKropotkin.html
index 76be802..6e91493 100644
--- a/docs/codox/HuxleyKropotkin.html
+++ b/docs/codox/HuxleyKropotkin.html
@@ -1,4 +1,4 @@
 
-The Huxley / Kropotkin debate
    Project
    Topics
    Namespaces
    The Huxley / Kropotkin debate
    
+The Huxley / Kropotkin debate
    Project
    Topics
    Namespaces
    The Huxley / Kropotkin debate
    
 
    { TODO: analyse the style and motivations of the Huxley / Kropotkin debate, drawing out the use of polemic and rhetoric to achieve hegemony }
    
\ No newline at end of file
diff --git a/docs/codox/Implementing.html b/docs/codox/Implementing.html
index 3e3f9fe..b2e1047 100644
--- a/docs/codox/Implementing.html
+++ b/docs/codox/Implementing.html
@@ -1,4 +1,4 @@
 
-Implementing
    Project
    Topics
    Namespaces
    Implementing
    
+Implementing
    Project
    Topics
    Namespaces
    Implementing
    
 
    {not yet written. To cover the actual structure of the Clojure Wildwood library, as I do it}
    
\ No newline at end of file
diff --git a/docs/codox/JAccuse.html b/docs/codox/JAccuse.html
index c260194..573ddda 100644
--- a/docs/codox/JAccuse.html
+++ b/docs/codox/JAccuse.html
@@ -1,6 +1,6 @@
 
-J'Accuse
    Project
    Topics
    Namespaces
    J’Accuse
    
+J'Accuse
    Project
    Topics
    Namespaces
    J’Accuse
    
 
    { Conclusion of the thesis.
    
 
    title of this chapter may change, but it needs to be confrontational and polemical.
    
 
    Draw together all that has been learned in parts one and two into a single, closely argued polemic, in best academic style. }
    
\ No newline at end of file
diff --git a/docs/codox/KnacqTools.html b/docs/codox/KnacqTools.html
index 431b068..66641e9 100644
--- a/docs/codox/KnacqTools.html
+++ b/docs/codox/KnacqTools.html
@@ -1,6 +1,6 @@
 
-KnacqTools
    Project
    Topics
    Namespaces
    KnacqTools
    
+KnacqTools
    Project
    Topics
    Namespaces
    KnacqTools
    
 
    Background
    
 
    KnacqTools (’Knowledge Acquisition Toolkit") was essentially a productisation of the ideas developed in Arboretum. It was written in C, originally for Acorn’s RISC OS operating system, and later ported to UNIX. The only major innovation of KnacqTools was that it was able to transform DTree knowledge structures into the rule languages of a number of contemporary ‘expert system’ inference engines.
    
 
    Thus the expected use of KnacqTools was not to run an inference process itself (although of course it could do this), but to allow a knowledge engineer, using Peter Mott’s ‘elicitation by exception’ technique, which I and others had polished in the field, to enter DTrees elicited from domain experts, compile these DTrees into production rules, and export those prodution rules to the selected expert system package for deployment.
    
diff --git a/docs/codox/Manifesto.html b/docs/codox/Manifesto.html
index 9aa9fab..a4525b8 100644
--- a/docs/codox/Manifesto.html
+++ b/docs/codox/Manifesto.html
@@ -1,6 +1,6 @@
 
-Manifesto
    Project
    Topics
    Namespaces
    Manifesto
    
+Manifesto
    Project
    Topics
    Namespaces
    Manifesto
    
 
    Machine inference – automated reasoning, the core of what gets called Artificial Intellegence – has ab initio been based on the assumption that the purpose of reasoning was to preserve truth. It is because this assumption is false that the project has thus far failed to bear fruit, that Allan Turing’s eponymous test has yet to be passed.
    
 
    Clockwork minds
    
 
    Of course it is possible to build machines which, within the constraints of finite store, can accurately compute theora of first order predicate calculus ad nauseam but such machines do not display behaviour which is convincingly intelligent. They are cold and mechanical; we do not recognise ourselves in them. Like the Girl in the Fireplace’s beautiful clocks, they are precisely inhuman.
    
diff --git a/docs/codox/OnHylasAndPhilonus.html b/docs/codox/OnHylasAndPhilonus.html
index b26bca7..c9fe731 100644
--- a/docs/codox/OnHylasAndPhilonus.html
+++ b/docs/codox/OnHylasAndPhilonus.html
@@ -1,6 +1,6 @@
 
-On the First Dialogue of Hylas and Philonous
    Project
    Topics
    Namespaces
    On the First Dialogue of Hylas and Philonous
    
+On the First Dialogue of Hylas and Philonous
    Project
    Topics
    Namespaces
    On the First Dialogue of Hylas and Philonous
    
 
    The argument that our perception of a ‘real world’ does not prove its existence is not new, of course. Here is a classic statement of a similar argument from BerkeIey’s First Dialogue of Hylas and Philonous:
    
 
    
   
    Hyl.: Do we not perceive the stars and moon, for example, to be a A great way off? Is not this, I say, manifest to the senses? I
    
diff --git a/docs/codox/PredicateSubtext.html b/docs/codox/PredicateSubtext.html
index 9b5d320..8277857 100644
--- a/docs/codox/PredicateSubtext.html
+++ b/docs/codox/PredicateSubtext.html
@@ -1,6 +1,6 @@
 
-On the subtext of a predicate
    Project
    Topics
    Namespaces
    On the subtext of a predicate
    
+On the subtext of a predicate
    Project
    Topics
    Namespaces
    On the subtext of a predicate
    
 
    Predicates are not atomic. They do not come single spies, but freighted with battalions of inferable subtexts. Suppose Anthony says
    
 
    Brutus killed Caesar in Rome during the ides of March
 
    
diff --git a/docs/codox/TheProblem.html b/docs/codox/TheProblem.html
index 6d365b2..42bcfda 100644
--- a/docs/codox/TheProblem.html
+++ b/docs/codox/TheProblem.html
@@ -1,6 +1,6 @@
 
-The  Problem
    Project
    Topics
    Namespaces
    The Problem
    
+The  Problem
    Project
    Topics
    Namespaces
    The Problem
    
 
    In this chapter talk about the perceived need for expert system explanations. Advance:
    
 
    the arguments used by expert systems designers, saying why explanations are needed;
    
 
    the arguments used by critics which claim that the explanations given are not good enough.
    
diff --git a/docs/codox/index.html b/docs/codox/index.html
index b3fbab8..5b7c5d0 100644
--- a/docs/codox/index.html
+++ b/docs/codox/index.html
@@ -1,3 +1,3 @@
 
-Wildwood 0.1.0-SNAPSHOT
    Project
    Topics
    Namespaces
    Wildwood 0.1.0-SNAPSHOT
    Released under the EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0
    A general inference library using a game theoretic inference mechanism.
    Installation
    To install, add the following dependency to your project or build file:
    [wildwood "0.1.0-SNAPSHOT"]
    Topics
    Namespaces
    wildwood.advocate
    An agent capable of playing the explanation game.
    Public variables and functions:
    wildwood.bialowieza
    The second iteration of the core inference engine for Wildwood
    Public variables and functions:
    wildwood.caesar
    A dummy set of advocates and knowledge accessors with knowledge about the death of Julius Caesar.
    Public variables and functions:
    wildwood.dengine.engine
    An implementation of the DTree engine adapted to wildwood.schema propositions.
    Public variables and functions:
    wildwood.dengine.engine
    An implementation of the DTree engine adapted to wildwood.schema propositions.
    Public variables and functions:
    wildwood.knowledge-accessor
    The key point of building Bialowieza as a library rather than a complete application is that it should be possible to hook it up to multiple sources of knowledge. Thus we must design a protocol through which knowledge can be accessed, and a schema in which it will be returned. Note that the accessor must be able to add knowledge to the knowledge base, as well as retrieve it.
    Public variables and functions:
    wildwood.schema
    The knowledge representation. This probably ends up looking a bit like a Toulmin schema, where claims are represented as propositions. There also need to be rules or predicates, things which can test whether a given proposition has a given value. There may be other stuff in here.
    Public variables and functions:
    
\ No newline at end of file
+Wildwood 0.1.0-SNAPSHOT
    Project
    Topics
    Namespaces
    Wildwood 0.1.0-SNAPSHOT
    Released under the EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0
    A general inference library using a game theoretic inference mechanism.
    Installation
    To install, add the following dependency to your project or build file:
    [wildwood "0.1.0-SNAPSHOT"]
    Topics
    Namespaces
    wildwood.advocate
    An agent capable of playing the explanation game.
    Public variables and functions:
    wildwood.bialowieza
    The second iteration of the core inference engine for Wildwood
    Public variables and functions:
    wildwood.caesar
    A dummy set of advocates and knowledge accessors with knowledge about the death of Julius Caesar.
    Public variables and functions:
    wildwood.dengine.engine
    An implementation of the DTree engine adapted to wildwood.schema propositions.
    Public variables and functions:
    wildwood.dengine.node
    A dtree node.
    Public variables and functions:
    wildwood.knowledge-accessor
    The key point of building Bialowieza as a library rather than a complete application is that it should be possible to hook it up to multiple sources of knowledge. Thus we must design a protocol through which knowledge can be accessed, and a schema in which it will be returned. Note that the accessor must be able to add knowledge to the knowledge base, as well as retrieve it.
    Public variables and functions:
    wildwood.schema
    The knowledge representation. This probably ends up looking a bit like a Toulmin schema, where claims are represented as propositions. There also need to be rules or predicates, things which can test whether a given proposition has a given value. There may be other stuff in here.
    Public variables and functions:
    
\ No newline at end of file
diff --git a/docs/codox/intro.html b/docs/codox/intro.html
index 42ae7d2..b2eb986 100644
--- a/docs/codox/intro.html
+++ b/docs/codox/intro.html
@@ -1,6 +1,6 @@
 
-Introduction to Wildwood
    Project
    Topics
    Namespaces
    Introduction to Wildwood
    
+Introduction to Wildwood
    Project
    Topics
    Namespaces
    Introduction to Wildwood
    
 
    I started building Wildwood nearly forty years ago on InterLisp-D workstations. Then, because of changing academic projects, I lost access to those machines, and the project was effectively abandoned. But, I’ve kept thinking about it; it has cool ideas.
    
 
    Explicable inference
    
 
    Wildwood was a follow on from ideas developed in Arboretum, an inference system based on a novel propositional logic using defaults. Arboretum was documented in our paper
    
diff --git a/docs/codox/wildwood.advocate.html b/docs/codox/wildwood.advocate.html
index b3e6a19..e0ad8af 100644
--- a/docs/codox/wildwood.advocate.html
+++ b/docs/codox/wildwood.advocate.html
@@ -1,6 +1,6 @@
 
-wildwood.advocate documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.advocate
    An agent capable of playing the explanation game.
    
+wildwood.advocate documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.advocate
    An agent capable of playing the explanation game.
    
 
    An advocate must have its own knowledge accessor. Different advocates within a game may be accessing different knowledge bases, or different subsets of the same knowledge base with different - potentially competing - knowledge. It also needs to know the schema in which knowledge will be presented.
    
 
    Since the mechanism by which the application will communicate with the library must include a way for users to interact with the game, and since the role of the user in the came is just as a participant, advocate must be defined as a protocol, in order that it may be extended by code within the application which is passed in to the game when the game is started. Indeed, multiple agents - the user(s) and potentially non-player characters - may be passed in.
    
 
    In this conception, nothing within a default advocate has to be able to produce or consume natural language. It is sufficient for the API exposed by wildwood.advocate to receive and return wildwood.schema objects.
    
diff --git a/docs/codox/wildwood.bialowieza.html b/docs/codox/wildwood.bialowieza.html
index 1e031bf..c2f0ca6 100644
--- a/docs/codox/wildwood.bialowieza.html
+++ b/docs/codox/wildwood.bialowieza.html
@@ -1,6 +1,6 @@
 
-wildwood.bialowieza documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.bialowieza
    The second iteration of the core inference engine for Wildwood
    decide
    (decide proposition & agents)
    Decide the truth value of this proposition by convening a game between these advocate agents. Iterate the game until all agents PASS; then finally offer each agent’s record method the proposition together with the decided truth value (true or false), before returning that value.
    
+wildwood.bialowieza documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.bialowieza
    The second iteration of the core inference engine for Wildwood
    decide
    (decide proposition & agents)
    Decide the truth value of this proposition by convening a game between these advocate agents. Iterate the game until all agents PASS; then finally offer each agent’s record method the proposition together with the decided truth value (true or false), before returning that value.
    
 
    The proposition is a proposition as defined in the wildwood.schema; that is to say, the predicate wildwood.schema/predicate? returns true of it. If the proposition isn’t a predicate, throw an exception.
    
 
    Each of agents should be an object implementing the wildwood.advocate/Advocate protocol. If an agent isn’t an Advocate, throw an exception.
    
 
    Do not throw an exception under any other circumstances.
    
diff --git a/docs/codox/wildwood.caesar.html b/docs/codox/wildwood.caesar.html
index 1866fbd..366c156 100644
--- a/docs/codox/wildwood.caesar.html
+++ b/docs/codox/wildwood.caesar.html
@@ -1,3 +1,3 @@
 
-wildwood.caesar documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.caesar
    A dummy set of advocates and knowledge accessors with knowledge about the death of Julius Caesar.
    april
    The month of April, 44BC, as a range.
    view source
    drusila-kb
    Drusila knows that Longus killed Caesar in the forum. She keys it on all three, for efficiency of retrieval.
    view source
    faldo-db
    Falco knows that Caesar has been killed, but doesn’t know by whom or when.
    view source
    gaius-db
    Gaius knows that Brutus killed Caesar, but believes it happened in April.
    view source
    ides-of-march
    16th March, 44BC
    view source
    marc-anthony-kb
    Mark Antony knows that Brutus is honourable.
    view source
    march
    The month of March, 44BC, as a range.
    view source
    
\ No newline at end of file
+wildwood.caesar documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.caesar
    A dummy set of advocates and knowledge accessors with knowledge about the death of Julius Caesar.
    april
    The month of April, 44BC, as a range.
    view source
    drusila-kb
    Drusila knows that Longus killed Caesar in the forum. She keys it on all three, for efficiency of retrieval.
    view source
    faldo-db
    Falco knows that Caesar has been killed, but doesn’t know by whom or when.
    view source
    gaius-db
    Gaius knows that Brutus killed Caesar, but believes it happened in April.
    view source
    ides-of-march
    16th March, 44BC
    view source
    marc-anthony-kb
    Mark Antony knows that Brutus is honourable.
    view source
    march
    The month of March, 44BC, as a range.
    view source
    
\ No newline at end of file
diff --git a/docs/codox/wildwood.dengine.engine.html b/docs/codox/wildwood.dengine.engine.html
index ae4ee31..5b57e17 100644
--- a/docs/codox/wildwood.dengine.engine.html
+++ b/docs/codox/wildwood.dengine.engine.html
@@ -1,3 +1,3 @@
 
-wildwood.dengine.engine documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.dengine.engine
    An implementation of the DTree engine adapted to wildwood.schema propositions.
    decide
    (decide proposition node accessor)
    Decide the truth value of this proposition, using the dtree rooted at this node and knowledge provided by this accessor.
    view source
    
\ No newline at end of file
+wildwood.dengine.engine documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.dengine.engine
    An implementation of the DTree engine adapted to wildwood.schema propositions.
    decide
    (decide proposition node accessor)
    Decide the truth value of this proposition, using the dtree rooted at this node and knowledge provided by this accessor.
    view source
    
\ No newline at end of file
diff --git a/docs/codox/wildwood.dengine.node.html b/docs/codox/wildwood.dengine.node.html
new file mode 100644
index 0000000..765d0a1
--- /dev/null
+++ b/docs/codox/wildwood.dengine.node.html
@@ -0,0 +1,3 @@
+
+wildwood.dengine.node documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.dengine.node
    A dtree node.
    colour
    (colour node)
    If this node is a valid dtree node, return its colour.
    view source
    node?
    (node? o)
    Return true if this o is recognisable as a dtree node, else false.
    view source
    
\ No newline at end of file
diff --git a/docs/codox/wildwood.knowledge-accessor.html b/docs/codox/wildwood.knowledge-accessor.html
index 3995ba5..6e124b5 100644
--- a/docs/codox/wildwood.knowledge-accessor.html
+++ b/docs/codox/wildwood.knowledge-accessor.html
@@ -1,3 +1,3 @@
 
-wildwood.knowledge-accessor documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.knowledge-accessor
    The key point of building Bialowieza as a library rather than a complete application is that it should be possible to hook it up to multiple sources of knowledge. Thus we must design a protocol through which knowledge can be accessed, and a schema in which it will be returned. Note that the accessor must be able to add knowledge to the knowledge base, as well as retrieve it.
    Accessor
    protocol
    members
    fetch
    (fetch self id)
    Fetch all the knowledge I have about the object identified by this id value, as a map whose :id key has this id value.
    store
    (store self id proposition)
    Add this proposition to the knowledge I hold about the object identified by this id value.
    view source
    
\ No newline at end of file
+wildwood.knowledge-accessor documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.knowledge-accessor
    The key point of building Bialowieza as a library rather than a complete application is that it should be possible to hook it up to multiple sources of knowledge. Thus we must design a protocol through which knowledge can be accessed, and a schema in which it will be returned. Note that the accessor must be able to add knowledge to the knowledge base, as well as retrieve it.
    Accessor
    protocol
    members
    fetch
    (fetch self id)
    Fetch all the knowledge I have about the object identified by this id value, as a map whose :id key has this id value.
    store
    (store self id proposition)
    Add this proposition to the knowledge I hold about the object identified by this id value.
    view source
    
\ No newline at end of file
diff --git a/docs/codox/wildwood.schema.html b/docs/codox/wildwood.schema.html
index d420064..8d30e2d 100644
--- a/docs/codox/wildwood.schema.html
+++ b/docs/codox/wildwood.schema.html
@@ -1,7 +1,7 @@
 
-wildwood.schema documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.schema
    The knowledge representation. This probably ends up looking a bit like a Toulmin schema, where claims are represented as propositions. There also need to be rules or predicates, things which can test whether a given proposition has a given value. There may be other stuff in here.
    
+wildwood.schema documentation
    Project
    Topics
    Namespaces
    Public Vars
    wildwood.schema
    The knowledge representation. This probably ends up looking a bit like a Toulmin schema, where claims are represented as propositions. There also need to be rules or predicates, things which can test whether a given proposition has a given value. There may be other stuff in here.
    
 
    Internal representation of most of this will be as Clojure maps.
    argument-keys
    Every argument is a proposition, which additionally has these keys.
    view source
    argument?
    (argument? o)
    True if o qualifies as an argument structure.
    
-
    An argument structure is a (potentially rich proposition which, in addition, should have values for :confidence and :authority. A value for :data may, and probably will, also be present but is not required.
    view source
    consensual-keys
    Every proposition which has these keys, in a given decision process, must have the same semantics and types for their values. The exact representations used for the values of these keys does not matter, it is consensual between all participating advocates in a decision process.
    view source
    minimise
    (minimise o)
    Expecting that o is a (potentially rich) proposition, return a map identical to o save that for each value v of key k in o, if v is a map and k is not a member of argument-keys, then the returned map shall substitute the value of (:id v).
    
-
    see also wildwood.knowledge-access/maximise.
    view source
    proposition?
    (proposition? o)(proposition? o minimised)
    True if o qualifies as a proposition. A proposition is probably a map with some privileged keys, and may look something like a minimised the-great-game.gossip.news-items item.
    
-
    If minimised is passed and is true, then the proposition must be minimised - that is to say, the values of keys in a proposition map may not themselves be keys. Where the value of a key represents an object in the world, that value must be simply the id of the object, not a richer representation.
    view source
    required-keys
    Every proposition is expected to have values for these keys.
    view source
    rule?
    (rule? o)
    True if o qualifies as a rule. A rule is a structure which comprises * an id and * a function of two arguments, a proposition and a knowledge accessor, and which should (if this can simply be checked) return an argument structure.
    view source
    truth
    (truth p)
    If p is a proposition, return whether the value asserted by that proposition is true. If the :truth key is missing, true is assumed.
    view source
    
\ No newline at end of file
+
    An argument structure is a (potentially rich) proposition which, in addition, should have values for :confidence and :authority. A value for :data may, and probably will, also be present but is not required. The value of :confidence must be a number in the range -1 to 1.
    view source
    consensual-keys
    Every proposition which has these keys, in a given decision process, must have the same semantics and types for their values. The exact representations used for the values of these keys does not matter, it is consensual between all participating advocates in a decision process.
    view source
    minimise
    (minimise o)
    Expecting that o is a (potentially rich) proposition, return a map identical to o save that for each value v of key k in o, if v is a map and k is not a member of argument-keys, then the returned map shall substitute the value of (:id v).
    
+
    see also wildwood.knowledge-access/maximise.
    view source
    proposition?
    (proposition? o)(proposition? o minimised)
    True if o qualifies as a proposition. A proposition is probably a map with some privileged keys, and may look something like a minimised the-great-game.gossip.news-items item.
    
+
    If minimised is passed and is true, then the proposition must be minimised - that is to say, the values of keys in a proposition map may not themselves be keys. Where the value of a key represents an object in the world, that value must be simply the id of the object, not a richer representation.
    view source
    required-keys
    Every proposition is expected to have values for these keys.
    view source
    rule?
    (rule? o)
    True if o qualifies as a rule. A rule is a structure which comprises * an id and * a function of two arguments, a proposition and a knowledge accessor, and which should (if this can simply be checked) return an argument structure.
    view source
    truth
    (truth p)
    If p is a proposition, return whether the value asserted by that proposition is true. If the :truth key is missing, true is assumed.
    view source
    
\ No newline at end of file
diff --git a/docs/img/dtree-live-with-partner.svg b/docs/img/dtree-live-with-partner.svg
new file mode 100644
index 0000000..731691a
--- /dev/null
+++ b/docs/img/dtree-live-with-partner.svg
@@ -0,0 +1,119 @@
+
+
+
+
+  
+  
+    
+  
+  
+    
+      
+        image/svg+xml
+        
+        
+      
+    
+  
+  
+    
+      Living with Partner -
+      
+        Remarried +
+        Cohabiting +
+      
+            
+    
+  
+
diff --git a/docs/img/dtree-widows-allowance.svg b/docs/img/dtree-widows-allowance.svg
new file mode 100644
index 0000000..55bf6d6
--- /dev/null
+++ b/docs/img/dtree-widows-allowance.svg
@@ -0,0 +1,178 @@
+
+
+
+
+  
+  
+    
+  
+  
+    
+      
+        image/svg+xml
+        
+        
+      
+    
+  
+  
+    
+      Entitled to Widows' Allowance -
+      Satisfies conditions for Widows' Allowance +
+      
+        > 26 weeks bereaved -
+        Killed husband -
+        Dead -
+        In prison -
+        Living with partner -
+      
+            
+      
+      
+      
+    
+  
+
diff --git a/docs/img/example-dtree.svg b/docs/img/example-dtree.svg
new file mode 100644
index 0000000..1d2571d
--- /dev/null
+++ b/docs/img/example-dtree.svg
@@ -0,0 +1,145 @@
+
+
+
+
+  
+  
+    
+  
+  
+    
+      
+        image/svg+xml
+        
+        
+      
+    
+  
+  
+    
+      Root Node -
+      1st Conjunct -
+      2nd Conjunct +
+      
+        1st Disjunct -
+        2nd Disjunct -
+      
+      
+      
+      
+      
+    
+  
+
diff --git a/docs/img/simplest-possible-dtree.svg b/docs/img/simplest-possible-dtree.svg
new file mode 100644
index 0000000..d4d6efd
--- /dev/null
+++ b/docs/img/simplest-possible-dtree.svg
@@ -0,0 +1,89 @@
+
+
+
+
+  
+  
+    
+  
+  
+    
+      
+        image/svg+xml
+        
+        
+      
+    
+  
+  
+    Hypothesis -
+    Condition +
+    
+  
+