Basically the same issue as oracle-samples/clara-examples#8

I propose removing the existing durability documentation and replacing it once we have documentation of the new API.

At http://www.clara-rules.org/docs/firststeps/, the instructions for adding Clara to a project list [com.cerner/clara-rules "0.12.0"] as the artifact, but that doesn't exist anywhere.

Updating to 13.0-RC4, however, isn't easily done because as far as I can tell, those API docs aren't available at http://www.clara-rules.org/apidocs/*

I'd recommend either publishing the given artifact, or updating the API docs to 13.0-RC4.

The behavior of boolean conditions that are reflected in the compiled Rete network
(i.e. that use the keyword boolean operators) has been a source of confusion on our team.
For example, to reuse an example from clara-site,

 [:or [Customer (= status :vip)]
     [Promotion (= type :discount-month)]]

this is not a short-circuiting Clojure or and will result in a rule activation for a satisfying Promotion
regardless of whether a satisfying Customer is also in the session. Conversely, something like

[Customer (or (= status :vip) (= type :long-term-customer))]

will not fire twice for a single Customer that meets both conditions.

I think it would be helpful to have some more elaboration in clara-site on this point, possibly
in a more detailed subpage on boolean expressions than is present at http://www.clara-rules.org/docs/expressions/ currently
as well as some usage of them in the clara-examples project. I currently only see usage of the not operator. (I'm willing to add this doc if this sounds like something you agree should be added.)

Currently several significant subjects on performance optimization require knowledge of the Rete algorithm and/or Clara's internals to understand. Examples include

• The benefit of using hash-based joins versus Cartesian joins. This came up recently on the mailing list at https://groups.google.com/forum/#!topic/clara-rules/SbiZA4_3s1U
• The benefit of inserting facts in a batch all at once, rather than one at a time, particularly when using accumulators. I've seen a case where large numbers of facts that were all fed to the same accumulators were inserted one at a time, leading to significant performance penalties, and the problems with this approach aren't obvious IMO if one is not familiar with Clara's implementation.
• The ability to use a custom fact-type-fn to gain constant-time dispatch on particular fields of a fact that are hotspots.

I'd like to make this knowledge more accessible in some way. I'm currently leaning toward adding a "Performance Optimization" page under the Advanced Topics section in the right sidebar and linking to pages on these and other relevant topics from that page but I'm open to suggestions.

This page seems to be the most reasonable location to add documentation on how users can use explicit destructuring within rules. As it logically makes sense to have destructuring when using custom-fact-types as clara cannot apply some of the syntactic sugar that it does for native records or Pojos.

The performance differences between the following queries came up on the Google Groups mailing list on this thread.

(defquery cold-query-1 [] [Cold (= ?t temperature)])
(defquery cold-query-2 [:?t] [Cold (= ?t temperature)])

The existing queries page discusses how to use the params on queries but not the performance benefits to them. We should document such benefits, probably as a new subpage to the performance optimization page.

The docs currently indicate the functions that need to be supplied to create a custom accumulator, and there are example in that the Clara codebase has accumulators created in the same way. However, I think the docs could benefit from an annotated concrete example of how to write a custom accumulator. This is something we might want to link to from the main accumulator page rather than putting it there in order to avoid clutter on the main page and keep it focused on the majority use-cases. The current docs:

Writing Accumulators
Clara provides a rich set of built-in accumulators, but advanced use cases may require customized accumulators over a collection of facts. Accumulator authors use the accum function in the clara.rules.accumulators namespace, and must provide these parts:

reduce-fn - A reduce function, in the style of clojure.core.reducers, which reduces a collection of values into a single output.
combine-fn - A combine function, in the style of clojure.core.reducers, which combines the outputs of two reduce-fn operations into a new, single output.
initial-value - An optional parameter that will be passed to the reduce-fn if provided. If all bindings are bound by other conditions in the rule or query then a non-nil initial value will be used as the result even if there are no matching facts to accumulate on.
retract-fn - An optional function that accepts a previously reduced output and a fact, and returns a new reduced output with the given fact retracted.
convert-return-fn - an operation that performs some conversion on the reduce/combine value before returning it to the caller

The subtitle for the Github repo shows "Clara Web Site (In Progress)". Is it ok to remove "(In Progress)" at this point?

1. Once oracle-samples/clara-examples#12 is merged I suggest that the truth maintenance page link to that example.
2. I propose that we add a sentence to the end of the second to last paragraph so it would be like

"Truth maintenance is transitive. So if any rules used the PremierCustomer fact to infer further knowledge, that inference would also be retracted. As a result we can treat rules that consistently use truth maintenance as purely declarative statements."

3. I believe that the Truth Maintenance page link should be moved from the "Advanced Topics" guide to the "Developer Guide" section. The other subjects in "Advanced Topics" are something of niche subjects and it is very possible to write rules without understanding of them, but the idea that rules are logical relationships rather than procedural code is very much a foundational idea of rules engines in my opinion and in my experience it isn't obvious to many people learning about rules engines for the first time.

• https://github.com/cerner/clara-rules/blob/0.17.0/src/main/clojure/clara/rules/listener.cljc
• https://github.com/cerner/clara-rules/blob/0.17.0/src/main/clojure/clara/tools/tracing.cljc

Also see oracle-samples/clara-rules#369

We made some minor changes to the session inspection API for oracle-samples/clara-rules#386 The docs here should be updated to reflect that, although changes should not be merged to master until after a new version of Clara with the changes is released.

As discussed on the Slack channel with @mrrodriguez (see log) users are not required to define rules and queries with defrule and defquery. They can instead create rule data structures themselves at runtime and pass those data structures to mk-session, and they will then be compiled into a rules session. This should be more clearly documented.

Assigning to myself unless someone else has been working on this or has plans to.

From the google group (https://groups.google.com/g/clara-rules/c/F5ZC-uiIfa0/m/KPPUWbrwBAAJ):

This is a bit of an oddity that I believe i have seen before. The issue seems to be with how clara resolves the fact type of the rule. Looking at the compiler code when generating the alpha nodes, if the fact-type is a symbol then it will be converted to a class otherwise it will remain as what ever was provided. This is to facilitate the default usage, ie. type as the default fact-type-fn.

In the example you provided, this would mean that the fact type of rule1 would match on [`IdHolder "A"] and not [IdHolder "A"], the former being a vector composed of a symbol/string combo and the latter being a class/string combo.

Im a bit torn here on what should be expected of clara in this situation, I feel its not very transparent that in one case the symbol would be replaced by a class but on the other hand it might be dangerous for clara to try and traverse the fact-type and replace symbols.

All of that being said, to answer the question, to get the example to function as expected:

(fn [fact]
  (cond
    (instance? IdHolder fact) [IdHolder (:id fact)]
    :else (type fact)))

would simply need updated to:

(fn [fact]
  (cond
    (instance? IdHolder fact) [`IdHolder (:id fact)]
    :else (type fact)))

Hope this helps,
Ethan

Colin pointed out this example is not valid Clara syntax:
https://github.com/cerner/clara-site/blob/07b1a4dd963e097e85b1d28e84f4a444c98e3eb5/_docs/usingaccumulators.md#L28

Should be [?temp <- Temperature (= ?location location)]. With the square brackets it throws an "extraneous brackets" error.

Curious if there's any interest in switching to this:
https://docusaurus.io/