Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 23 additions & 11 deletions .github/workflows/clojure.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,35 @@ on:
branches:
- '**'

env:
CLOJURE_CLI_VERSION: '1.12.5.1664'

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Tools setup
uses: jdx/mise-action@v4
uses: actions/checkout@v7
- name: Setup GraalVM
uses: graalvm/setup-graalvm@v1
with:
install: true
cache: true
- name: Tools config
run: |
echo "JAVA_HOME=$(mise where java)" >> $GITHUB_ENV
echo "GRAALVM_HOME=$(mise where java)" >> $GITHUB_ENV
echo "$(mise where java)/bin" >> $GITHUB_PATH
gu install native-image
version: '22.3.1'
java-version: '11'
components: 'native-image'
github-token: ${{secrets.GITHUB_TOKEN}}
- name: Setup Clojure
uses: DeLaGuardo/setup-clojure@13.6.1
with:
cli: ${{env.CLOJURE_CLI_VERSION}}
- name: Cache Clojure dependencies
uses: actions/cache@v4
with:
path: |
~/.m2/repository
~/.gitlibs
~/.deps.clj
key: cljdeps-${{runner.os}}-${{hashFiles('deps.edn')}}
restore-keys: cljdeps-${{runner.os}}-
- name: Run tests
run: make test
- name: Run coverage tests
Expand Down
4 changes: 1 addition & 3 deletions .mise.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
[tool_alias]
clojure = "https://github.com/asdf-community/asdf-clojure.git"
[tools]
"asdf:https://github.com/asdf-community/asdf-clojure.git" = "1.12"
java = "graalvm-22.3.1+java11"
clojure = "1.11"
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
This is a history of changes to gateless/clara-rules.

# 1.7.0
* Add opt-in caching of rule right-hand-side (RHS) output across sessions. A rule opts in with a `:cache` prop; the caller passes a cache atom (any `clojure.core.cache/CacheProtocol`) as the `:activation-cache` option to `fire-rules`/`fire-rules-async`. On a cache hit the stored RHS output is replayed and the RHS is skipped; on a miss the RHS runs and its output is recorded. Firing without a cache is unchanged. Cache policy (TTL, eviction, hit/miss metrics) is the caller's responsibility.
* Add a `:activation-cache-key-fn` option to `fire-rules`/`fire-rules-async` that overrides the default activation cache key (`clara.rules.activation-cache.core/build-cache-key`). It receives the activation map (`{:node :token}`) and returns the key, or nil to skip caching for that activation (the RHS runs uncached). Only consulted when `:activation-cache` is supplied and the rule opted in; choosing a sound key is the caller's responsibility.
* `fire-rules-async` now runs synchronous RHS bodies on the async executor rather than the calling thread (previously only asynchronous results were deferred). Dynamic bindings are conveyed, so behavior is unchanged for RHS bodies that do not depend on running on the calling thread specifically.
* Add a `:default-rule-props` option to `mk-session`/`defsession`: a map of rule properties merged into every rule (productions with an `:rhs`; queries are unaffected), beneath each rule's own props. Precedence is session-default < namespace-level < rule-level, so a rule can override or opt out (e.g. `{:cache false}`). For example, `:default-rule-props {:cache true}` enables activation caching for all rules by default.
* Mark activation cache hits in listener events: on a hit, the activation passed to `fire-activation!` has `:cache true`, so it also shows in the `:activation` of the `clara.tools.tracing` `:fire-activation` trace event. A live (uncached) activation has no `:cache` key, so its events are unchanged.
* `:compiler-cache false` in `mk-session` now disables caching of compiled expressions. Previously `false` fell through to the default compiler cache. The `:cache` and `:compiler-cache` options now share the same semantics: nil or true selects the default cache, false disables caching, and any other value is used as the cache.
* Upgrade futurama to 1.5.1, ham-fisted to 3.034, Clojure to 1.12.6, core.cache to 1.2.999, and schema to 1.4.2. With futurama 1.5.1, an RHS whose result value is a `Throwable` (returned, not thrown) now throws when the result is read.

# 1.6.8
* Rule-level properties now take precedence over namespace-level properties when both define the same key (previously namespace properties overrode rule-level properties).
* Add `:cache` to the default set of allowed namespace-level rule properties (now `:author :cache :no-loop :salience`).
Expand Down
8 changes: 7 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: repl test clean compile-main-java compile-test-java deploy install format-check format-fix
.PHONY: repl test clean compile-main-java compile-test-java deploy install format-check format-fix deps-check deps-upgrade

SHELL := /bin/bash

Expand Down Expand Up @@ -34,6 +34,12 @@ lint: compile-test-java
clojure -M:dev:test:app:clj-kondo --copy-configs --dependencies --parallel --lint "$(shell clojure -A:dev:test -Spath)"
clojure -M:dev:test:app:clj-kondo --lint "src/main:src/test" --fail-level "error"

deps-check:
clojure -M:dev:test:deps-antq

deps-upgrade:
clojure -M:dev:test:deps-antq --upgrade

build: compile-main-java
clojure -X:jar :sync-pom true :jar "build/clara-rules.jar"

Expand Down
44 changes: 22 additions & 22 deletions deps.edn
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,56 @@
:deps/prep-lib {:alias :build
:fn compile-main-java
:ensure "target/main/classes"}
:deps {org.clojure/clojure {:mvn/version "1.12.5"}
org.clojure/core.cache {:mvn/version "1.2.263"}
com.github.gateless/futurama {:mvn/version "1.4.6"}
com.cnuernber/ham-fisted {:mvn/version "3.029"}
prismatic/schema {:mvn/version "1.4.1"}
:deps {org.clojure/clojure {:mvn/version "1.12.6"}
org.clojure/core.cache {:mvn/version "1.2.999"}
com.github.gateless/futurama {:mvn/version "1.5.1"}
com.cnuernber/ham-fisted {:mvn/version "3.034"}
prismatic/schema {:mvn/version "1.4.2"}
org.clojure/data.fressian {:mvn/version "1.1.1"}}

;for more examples of aliases see: https://github.com/seancorfield/dot-clojure
:aliases
{:build {:paths ["tool"]
:deps {io.github.clojure/tools.build {:mvn/version "0.10.9"}}
:deps {io.github.clojure/tools.build {:mvn/version "0.10.14"}}
:ns-default build}
:dev {:extra-paths ["dev"]
:extra-deps {reloaded.repl/reloaded.repl {:mvn/version "0.2.4"}
org.slf4j/slf4j-api {:mvn/version "2.0.17"}
org.slf4j/slf4j-simple {:mvn/version "2.0.17"}
org.clojure/math.combinatorics {:mvn/version "0.3.0"}
djblue/portal {:mvn/version "0.59.1"}
org.slf4j/slf4j-api {:mvn/version "2.0.20"}
org.slf4j/slf4j-simple {:mvn/version "2.0.20"}
org.clojure/math.combinatorics {:mvn/version "0.3.2"}
djblue/portal {:mvn/version "0.67.2"}
criterium/criterium {:mvn/version "0.4.6"}}}

:app {:extra-paths ["app"]
:extra-deps {com.github.clj-easy/graal-build-time {:mvn/version "1.0.5"}}}
:extra-deps {com.github.clj-easy/graal-build-time {:mvn/version "1.0.6"}}}

:clj-kondo {:extra-deps {clj-kondo/clj-kondo {:mvn/version "2025.06.05"}}
:clj-kondo {:extra-deps {clj-kondo/clj-kondo {:mvn/version "2026.08.04"}}
:main-opts ["-m" "clj-kondo.main"]}

:outdated {:deps {com.github.liquidz/antq {:mvn/version "2.11.1276"}}
:main-opts ["-m" "antq.core"]}

:test {:extra-paths ["src/test/clojure" "target/test/classes"]
:extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}
lambdaisland/kaocha-junit-xml {:mvn/version "1.17.101"}
lambdaisland/kaocha-cloverage {:mvn/version "1.1.89"}
org.clojure/test.check {:mvn/version "1.1.1"}
org.clojure/test.check {:mvn/version "1.1.3"}
pjstadig/humane-test-output {:mvn/version "0.11.0"}}}

:runner {:main-opts ["-e" "(println \"warn-on-reflection =\" (set! *warn-on-reflection* true))"
"-m" "kaocha.runner"]
:exec-fn kaocha.runner/exec-fn}

:repl {:extra-deps {nrepl/nrepl {:mvn/version "1.3.1"}
cider/cider-nrepl {:mvn/version "0.56.0"}}
:repl {:extra-deps {nrepl/nrepl {:mvn/version "1.7.0"}
cider/cider-nrepl {:mvn/version "0.62.2"}}
:main-opts ["-e" "(println \"warn-on-reflection =\" (set! *warn-on-reflection* true))"
"-m" "nrepl.cmdline" "--interactive"
"--middleware" "[\"cider.nrepl/cider-middleware\"]"]}

:format-fix {:extra-deps {cljfmt/cljfmt {:mvn/version "0.9.2"}}
:deps-antq {:extra-deps {com.github.liquidz/antq {:mvn/version "2.11.1276"}}
:main-opts ["-m" "antq.core"]}

:format-fix {:extra-deps {dev.weavejester/cljfmt {:mvn/version "0.16.5"}}
:main-opts ["-m" "cljfmt.main" "fix" "src" "dev"]}

:format-check {:extra-deps {cljfmt/cljfmt {:mvn/version "0.9.2"}}
:format-check {:extra-deps {dev.weavejester/cljfmt {:mvn/version "0.16.5"}}
:main-opts ["-m" "cljfmt.main" "check" "src" "dev"]}

:jar {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.1.303"}}
Expand All @@ -63,12 +63,12 @@
:aliases [:app]
:main-class clara.main}}

:install-maven {:extra-deps {slipset/deps-deploy {:mvn/version "0.2.2"}}
:install-maven {:extra-deps {slipset/deps-deploy {:mvn/version "0.2.5"}}
:exec-fn deps-deploy.deps-deploy/deploy
:exec-args {:installer :local
:artifact "build/clara-rules.jar"}}

:deploy-maven {:replace-deps {slipset/deps-deploy {:mvn/version "0.2.2"}}
:deploy-maven {:replace-deps {slipset/deps-deploy {:mvn/version "0.2.5"}}
:exec-fn deps-deploy.deps-deploy/deploy
:exec-args {:installer :remote
:artifact "build/clara-rules.jar"}}}
Expand Down
14 changes: 7 additions & 7 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
<groupId>com.github.gateless</groupId>
<artifactId>clara-rules</artifactId>
<name>clara-rules</name>
<version>1.6.8</version>
<version>1.7.0</version>
<scm>
<tag>1.6.8</tag>
<tag>1.7.0</tag>
<url>https://github.com/gateless/clara-rules</url>
<connection>scm:git:git://github.com/gateless/clara-rules.git</connection>
<developerConnection>scm:git:ssh://git@github.com/gateless/clara-rules.git</developerConnection>
Expand All @@ -22,17 +22,17 @@
<dependency>
<groupId>org.clojure</groupId>
<artifactId>clojure</artifactId>
<version>1.12.5</version>
<version>1.12.6</version>
</dependency>
<dependency>
<groupId>com.cnuernber</groupId>
<artifactId>ham-fisted</artifactId>
<version>3.029</version>
<version>3.034</version>
</dependency>
<dependency>
<groupId>com.github.gateless</groupId>
<artifactId>futurama</artifactId>
<version>1.4.6</version>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>org.clojure</groupId>
Expand All @@ -42,12 +42,12 @@
<dependency>
<groupId>prismatic</groupId>
<artifactId>schema</artifactId>
<version>1.4.1</version>
<version>1.4.2</version>
</dependency>
<dependency>
<groupId>org.clojure</groupId>
<artifactId>core.cache</artifactId>
<version>1.2.263</version>
<version>1.2.999</version>
</dependency>
</dependencies>
<build>
Expand Down
37 changes: 35 additions & 2 deletions src/main/clojure/clara/rules.clj
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,21 @@
other out and avoid operations deeper in the rules network. The behavior of unconditional insertions and RHS (right-hand side) retractions
is undefined when this option is enabled and this option should not be used when calling fire-rules can result in these operations.
Note that this is purely a performance optimization and no guarantees are made at this time on whether a given rule's RHS will be called.
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions."
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions.

:activation-cache <atom> (NEW, subject to change/updates in the future):
An atom wrapping a clojure.core.cache/CacheProtocol implementation, used to cache rule right-hand-side (RHS) output across sessions.
A rule opts in via its own :cache prop (see clara.rules.activation-cache.core). On a cache hit the stored RHS output is replayed and the
RHS is skipped; on a miss the RHS runs and its output is recorded under the activation's key. Firing without a cache is unchanged;
the value must be a valid cache atom, and supplying anything else is unsupported and may throw. Cache policy (TTL, eviction, hit/miss metrics)
is the responsibility of the caller's cache implementation.

:activation-cache-key-fn <fn> (NEW, subject to change/updates in the future):
A function used to derive the cache key for a cacheable activation, overriding the default
(clara.rules.activation-cache.core/build-cache-key). It receives the activation map ({:node :token}) and returns a key,
or nil to skip caching for that activation (the RHS then runs uncached). Equal activations must yield equal keys.
Only consulted when :activation-cache is also supplied and the rule opted in via its :cache prop;
choosing a sound key is the responsibility of the caller."
([session] (eng/fire-rules session {}))
([session opts] (eng/fire-rules session opts)))

Expand All @@ -58,7 +72,21 @@
other out and avoid operations deeper in the rules network. The behavior of unconditional insertions and RHS (right-hand side) retractions
is undefined when this option is enabled and this option should not be used when calling fire-rules can result in these operations.
Note that this is purely a performance optimization and no guarantees are made at this time on whether a given rule's RHS will be called.
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions."
When this option is used rule RHS code that is executed shouldn't do anything that impacts state other than perform logical insertions.

:activation-cache <atom> (NEW, subject to change/updates in the future):
An atom wrapping a clojure.core.cache/CacheProtocol implementation, used to cache rule right-hand-side (RHS) output across sessions.
A rule opts in via its own :cache prop (see clara.rules.activation-cache.core). On a cache hit the stored RHS output is replayed and the
RHS is skipped; on a miss the RHS runs and its output is recorded under the activation's key. Firing without a cache is unchanged;
the value must be a valid cache atom, and supplying anything else is unsupported and may throw. Cache policy (TTL, eviction, hit/miss metrics)
is the responsibility of the caller's cache implementation.

:activation-cache-key-fn <fn> (NEW, subject to change/updates in the future):
A function used to derive the cache key for a cacheable activation, overriding the default
(clara.rules.activation-cache.core/build-cache-key). It receives the activation map ({:node :token}) and returns a key,
or nil to skip caching for that activation (the RHS then runs uncached). Equal activations must yield equal keys.
Only consulted when :activation-cache is also supplied and the rule opted in via its :cache prop;
choosing a sound key is the responsibility of the caller."
([session] (eng/fire-rules-async session {}))
([session opts] (eng/fire-rules-async session opts)))

Expand Down Expand Up @@ -214,6 +242,11 @@
information might prove useful for debugging compilation errors within the rulebase, eg. rulebase serialization
(ie. via Clara's durability support).
Defaults to true, see clara.rules.compiler/omit-compile-ctx-default for more information.
* :default-rule-props - A map of rule properties merged into every rule (productions with an :rhs); queries are unaffected.
The defaults sit beneath each rule's own props, so precedence is session-default < namespace-level < rule-level; a rule
can override or opt out of a default (eg. a rule with {:cache false} stays false even when :default-rule-props is {:cache true}).
For example, :default-rule-props {:cache true} enables activation caching (see the :cache prop) for all rules by default.
This option also applies to defsession, which delegates to the same session creation.

This is not supported in ClojureScript, since it requires eval to dynamically build a session. ClojureScript
users must use pre-defined rule sessions using defsession."
Expand Down
35 changes: 35 additions & 0 deletions src/main/clojure/clara/rules/activation_cache/core.clj
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
(ns clara.rules.activation-cache.core
"Support for caching the output of rule right-hand-side (RHS) activations
so it can be replayed across rules sessions instead of recomputed.

The engine consults a cache the caller supplies via the `:activation-cache`
fire-rules option: an atom wrapping any `clojure.core.cache/CacheProtocol` implementation.
A rule opts in via its own `:cache` prop. This namespace provides
`build-cache-key`, which derives the key an activation is cached under (callers
can override it per fire with the `:activation-cache-key-fn` fire-rules option). Any
policy beyond basic lookup/hit/miss — TTL, tracking which entries were
consulted, sweeping at the end of a run — is the responsibility of the caller's
cache implementation.")

(defn build-cache-key
Comment thread
k13gomez marked this conversation as resolved.
Resolved
"Builds an activation cache key for the given activation (a map with `:node` and
`:token`).

The key is the data the RHS output depends on: the rule's name, conditions
(`:lhs`), right-hand side (`:rhs`), environment, and props, plus the matched
facts and the bindings it fired on. Because the rule logic (`:lhs`/`:rhs`) and
the caller-supplied `:name`/`:props` are part of the key, it changes exactly
when the rule logic or its inputs change. The full bindings are stored (not a
hash) so a deserialized key compares `=` to a freshly-computed one with no
chance of collision."
[{:keys [node token]}]
(let [{:keys [production]} node
{:keys [matches bindings]} token
{:keys [name env lhs rhs props]} production]
{:name name
:lhs lhs
:rhs rhs
:env env
:props props
:matches (mapv first matches)
:bindings bindings}))
Loading
Loading