vaelii.client — com.vaelii/vaelii 0.13.0

A thin EDN-over-HTTP client for the vaelii daemon (vaelii.serve). Runs no engine: it POSTs {:op :args} and reads the result back, over JDK java.net.http (no dependency — JDK 21 ships it).

Every call threads an explicit connection handle as its first argument — (query conn '(dog ?x) 'Ctx) — the network mirror of vaelii.core's explicit-kb API. A conn from client holds a reusable HttpClient; no socket opens until a call. A daemon reply of {:ok false} becomes an ex-info carrying the daemon's :error and :type, so a remote naming or disjointness refusal surfaces like a local one.

A daemon with VAELII_API_TOKEN set answers 401 (:unauthorized) to a call that presents no bearer token; the conn reads the same variable, so a client in the daemon's environment carries it with nothing said.

Public because a client is a thing applications write against; the implementation is vaelii.impl.client, which is free to change. Result shapes are vaelii.core's: a sentex comes back as a plain map (the daemon projects the record), a solution as a binding map.

Every op the daemon serves has a wrapper here, spelled as vaelii.core spells the fn — bare or !-marked exactly as it does — and at its arities, with kb replaced by conn. The ones below are written out; the rest are generated from the daemon's op table by lein regen-client, which is also what makes the claim checkable rather than aspirational (client_surface_test). call still reaches any op directly, which is what a caller wants for serve/feed-ops and for an op newer than this build.

abduce clj

(abduce conn goal)

(abduce conn goal context)

(abduce conn goal context opts)

What would have to be true for goal to be provable in context.

abduce-discard! clj

(abduce-discard! conn result)

Discard an abduction's scratch context — every hypothesis in it, and everything they licensed.

add-provenance clj

(add-provenance conn handle m)

Merge m into handle's provenance map (creating it if absent), returning the merged map.

argue clj

(argue conn asent context)

(argue conn asent context opts)

Four-valued epistemic status of a ground assertion.

ask clj

(ask conn goal)

(ask conn goal context)

(ask conn goal context opts)

The first solution for goal, or nil. opts is the wall clock vaelii.core/ask takes — {:max-ms n}, held under the daemon's ceiling, and given the ceiling's when absent.

ask-within clj

(ask-within conn goal budget)

(ask-within conn goal context budget)

Anytime ask: answer goal in context, but bounded by budget — a map of any of {:max-ms n :max-results n :max-cost <tier>}.

ask? clj

(ask? conn goal)

(ask? conn goal context)

(ask? conn goal context opts)

Whether goal has any solution. Same opts as ask.

assert clj

(assert conn sentence)

(assert conn sentence context)

(assert conn sentence context opts)

Assert sentence in context (optional opts) — returns the handle(s). Bare — no ! — for vaelii.core/assert's reason: additive, and retract! takes it back. With no context it is CxUniverse, as in process.

assert-many clj

(assert-many conn sentences context)

(assert-many conn sentences context opts)

Assert every sentence in sentences into context, as one call.

assert-rule clj

(assert-rule conn antecedents consequent)

(assert-rule conn antecedents consequent context)

(assert-rule conn antecedents consequent context opts)

Assert a rule from antecedents to consequent in context — returns the handle(s); a conjunctive consequent yields one handle per conjunct. With no context it is CxUniverse, as in process.

belief-status clj

(belief-status conn handle context)

Storage, raw IN, exception forest, inheritance path, belief, and visibility for handle as viewed from context.

believed clj

(believed conn handles)

The subset of handles raw structural JTMS IN, as a set — in? asked of many handles at once.

believed? clj

(believed? conn handle context)

Whether handle is JTMS IN after exceptions visible from context, before assertion-context inheritance.

blocked-justifications clj

(blocked-justifications conn)

The ids of the justifications a rule exception currently blocks — every antecedent IN and supporting nothing. The one justification property belief does not report.

caches clj

(caches conn)

What this process is holding beside the stores — every derived structure the engine caches, ranked by entries.

calculi clj

(calculi conn)

The shipped qualitative calculi as data — one map apiece, naming the calculus, the base relations it distinguishes (jointly exhaustive and pairwise disjoint, so exactly one holds of any two terms), the identity it puts on the diagonal, and the predicates it claims.

call clj

(call conn op args)

(call conn op args opts)

POST {:op op :args args} and return the :result, or throw ex-info on an {:ok false} reply. The low-level entry the wrappers below use; reach for it for an op with no wrapper yet — vaelii.serve/op-names is the reachable set. opts is {:timeout-ms n} for this call alone, which the long poll below is what needs.

canonical-sentex clj

(canonical-sentex conn sentence context)

The canonical sentex for sentence in context, without storing it — the un-stored counterpart of sentex.

chain-report clj

(chain-report conn)

Per forward rule, what forward chaining did with it — how many firings it placed, how many it refused and why, or whether it did nothing at all.

chain-stats clj

(chain-stats conn)

Chaining-run instrumentation: {:runs n :last {:derived n :truncated? bool}}.

check clj

(check conn sentence)

(check conn sentence context)

(check conn sentence context opts)

Would (assert kb sentence context opts) succeed, and if not, why? Returns a vector of problems — empty when the sentence is admissible — and stores nothing: no sentex, no index entry, no taxonomy edge, no chaining, no settle.

check-edit clj

(check-edit conn batch)

check over a whole edit batch — {:add [[sentence context opts?] …] :remove [handle …]}, the shape edit takes — storing nothing.

clear-caches clj

(clear-caches conn)

(clear-caches conn opts)

Drop every cache that offers a clear, and say what went: {:cleared [{:cache :label :entries}…] :entries total}.

client clj

(client host port)

(client host port opts)

A connection handle to a daemon at host:port (opts: :timeout-ms, default 30000; :token, the bearer token every call presents — VAELII_API_TOKEN when the key is absent, and an explicit nil to send no Authorization header at all). Holds a reusable HttpClient; no network happens until a call.

compare-tacticians clj

(compare-tacticians conn goal)

(compare-tacticians conn goal context)

(compare-tacticians conn goal context opts)

Run goal in context under several tacticians — the node engine's search orderings — each to completion, and return one row per tactician: the search it ran, its wall-clock, and its answer set.

conflicts clj

(conflicts conn)

The KB's current conflicts.

context-down clj

(context-down conn c)

The contexts that inherit from c, reflexively — c plus every context that sees it.

context-up clj

(context-up conn c)

The contexts c inherits from, reflexively — c plus everything it sees via genlCx.

contexts clj

(contexts conn)

Every context the KB holds.

contexts-of clj

(contexts-of conn sentence)

The contexts in which sentence is asserted.

contradictions clj

(contradictions conn)

The coexisting P/¬P dilemmas.

count-in-context clj

(count-in-context conn context)

How many sentexes are stored in context — one set-size read, O(1), nothing fetched.

count-with-arg clj

(count-with-arg conn pos term)

How many fact sentexes hold term at argument position pos, as stored — cheap, one O(1) set-size read per predicate declaring an argument at that slot.

count-with-functor clj

(count-with-functor conn pred)

How many fact sentexes with functor pred are stored — one set-size read, O(1).

defeat-class clj

(defeat-class conn handle)

The current defeat-class of a believed handle (:monotonic / :default), or nil when it is OUT — the effective strength of the belief after settling.

dependent-justifications clj

(dependent-justifications conn handle)

Justifications that use handle as an antecedent — what rests on it, which is what an impact analysis before a retract! asks for.

deprecated? clj

(deprecated? conn term)

(deprecated? conn term context)

Did a believed rewriteOf name term the dispreferred side? False for a sameAs or equals member: those merge without retiring either name.

describe clj

(describe conn term)

(describe conn term context)

(describe conn term context opts)

Everything the KB holds about one term, as one map, keyed by the term's own role (term-role) — the read behind "what can I ask about X?".

disjoint-metatypes clj

(disjoint-metatypes conn)

The declared disjoint metatypes — each a type whose member types are pairwise disjoint by (disjointMetatype M).

disjoint? clj

(disjoint? conn a b)

(disjoint? conn a b context)

Are types a and b provably disjoint (via disjoint declarations, closed under genl)? With a context, only declarations and genl edges visible from it count — the vantage every definitional check now judges from.

edit! clj

(edit! conn batch)

Apply a batch of assertions and retractions in one settle.

edit-with-consequences! clj

(edit-with-consequences! conn batch)

(edit-with-consequences! conn batch opts)

edit, plus what the batch turned out to mean — the belief it added and the belief it took away, in preview's entry shapes.

equiv-class clj

(equiv-class conn term)

(equiv-class conn term context)

Every term known equal to term, itself included.

escalate clj

(escalate conn goal)

(escalate conn goal context)

(escalate conn goal context floor)

The cheapest level that answers goal — climb the stack from floor and stop at the first level with results.

explain-levels clj

(explain-levels conn goal)

(explain-levels conn goal context)

What every level yields for goal: a seq of {:level :name :count}.

export! clj

(export! conn dir)

(export! conn dir opts)

Write kb out as a portable export dump in dir and return a summary:

exposed-clashes clj

(exposed-clashes conn)

Every disjointness clash the KB currently makes jointly visible: a term holding two types some context can see as disjoint, where each membership was admissible where it was written.

find-sentexes clj

(find-sentexes conn term)

Every sentex containing term.

find-terms clj

(find-terms conn q)

(find-terms conn q opts)

The vocabulary terms whose name matches q, sorted by name.

forward-chain clj

(forward-chain conn)

(forward-chain conn opts)

Run forward chaining to a fixpoint over every believed sentex, then settle belief (resolve contradictions).

genl? clj

(genl? conn sub super)

(genl? conn sub super context)

Is sub a (reflexive-transitive) subtype of super? Types, not individuals — for an individual's type membership use isa?.

genls clj

(genls conn t)

(genls conn t context)

The types t is a subtype of, transitively. With a context, only the genl edges visible from it count.

handle-of clj

(handle-of conn sentence context)

The handle for sentence in context, or nil.

handles clj

(handles conn)

Every live sentex handle in the KB — premises and anything forward-derived alike, read straight off the record store.

has-prop? clj

(has-prop? conn kind pred)

(has-prop? conn kind pred context)

Does pred carry the metadata property kind — one of :transitive, :symmetric, :asymmetric, :reflexive, :functional, :decontextualized, :forced-decontextualized, :abducible, :reifiable, :unreifiable? Declared by the corresponding sentex, e.g. (symmetric siblingOf).

health clj

(health conn)

The daemon's liveness reply, {:ok true} — a GET, so it needs no op.

in? clj

(in? conn handle)

Whether the sentex handle names is raw JTMS IN.

inverse-of clj

(inverse-of conn pred)

(inverse-of conn pred context)

The predicate declared inverse to pred by an (inverse P Q) sentex, or nil.

isa? clj

(isa? conn x t)

(isa? conn x t context)

Whether individual x is of type t, through the genl closure.

justification clj

(justification conn jid)

The justification for an id, or nil — nil in, nil out; a non-id is refused (:bad-handle).

kb-diff clj

(kb-diff conn b)

What two KBs disagree about, as content: {:added :removed :moved :belief-changed}.

kb-quality clj

(kb-quality conn)

(kb-quality conn opts)

Seven readings about the knowledge — one map, seven keys, each a distribution rather than a number:

levels clj

(levels conn)

The stack as data: {:level :name :below :adds} per level.

lookup clj

(lookup conn level goal)

(lookup conn level goal context)

Answer goal in context using exactly the machinery of level:

metatype-members clj

(metatype-members conn m)

The member types of disjoint metatype m — the set whose every pair disjoint? holds of, closed under genl.

poll clj

(poll conn token cursor)

(poll conn token cursor opts)

Read a subscription forward from cursor — {:events [...] :cursor n :lagged k}. Each event is {:believed-added [...] :believed-removed [...]} in preview's entry shapes, one per settle, oldest first.

opts is {:wait-ms n}: the daemon holds the request open that long waiting for the first event, and this client extends its read timeout to cover it.

:lagged is on every reply and is the one field a caller must read. Non-zero, the daemon's ring dropped that many events before this poll reached them, and the caller is behind rather than current — re-read what it cares about rather than trusting the events it did get to be the whole story.

possible-relations clj

(possible-relations conn calculus context a b)

The base relations calculus still allows between a and b, given everything believed in context — the set ask checks a goal against, exposed directly.

premise? clj

(premise? conn handle)

Is the sentex at handle a premise — asserted in its own right rather than derived? A premise rests on nothing, so no justification names it as a conclusion and retracting its supports cannot take it OUT; a derived sentex is the other case, and supporting-justifications is what shows why.

preview clj

(preview conn batch)

(preview conn batch opts)

What would this batch do to the KB — without leaving it done.

props clj

(props conn kind)

The set of predicates carrying metadata property kind (see has-prop?).

provable? clj

(provable? conn goal)

(provable? conn goal context)

(provable? conn goal context opts)

Whether goal is provable. Same opts as prove.

prove clj

(prove conn goal)

(prove conn goal context)

(prove conn goal context opts)

A proof tree for goal, as data. opts is vaelii.core/prove's bound — {:max-ms n :max-depth n}, both held under the daemon's ceilings.

prove-within clj

(prove-within conn goal budget)

(prove-within conn goal context budget)

Anytime prove: run the depth-first backward chainer over goal (a sentence or a conjunction vector, as prove) in context, bounded by budget — a map of any of {:max-ms n :max-results n :max-depth n :max-term-growth n}.

provenance clj

(provenance conn handle)

The provenance map recorded for handle — {:creator … :created … …} — or nil if none.

qualitative-network clj

(qualitative-network conn calculus context)

The constraint network calculus computes over everything believed and visible in context: every pair of terms its predicates relate, tightened by path consistency to the base relations still possible between them.

qualitative-scenario clj

(qualitative-scenario conn calculus context)

One concrete arrangement consistent with everything believed in context — {[a b] → relation}, one base relation per pair — or nil when the believed facts are unsatisfiable.

qualitative-scenarios clj

(qualitative-scenarios conn calculus context limit)

Up to limit distinct arrangements, as qualitative-scenario renders one.

quality-report clj

(quality-report conn quality)

A kb-quality map as Markdown — the counts first and the capped lists after.

query clj

(query conn goal)

(query conn goal context)

(query conn goal context opts)

Solutions for goal as binding maps — ({?x Muffet}).

query-plan clj

(query-plan conn goal)

(query-plan conn goal context)

How a goal would be answered, at whichever of the two scales the goal has.

query? clj

(query? conn goal)

(query? conn goal context)

(query? conn goal context opts)

Is goal answerable under opts? query, asked for one answer.

readable-sentence clj

(readable-sentence conn sx)

A sentex's sentence with the author's variable names restored — pass a sentex map (from sentex / sentexes-matching).

representative clj

(representative conn term)

(representative conn term context)

The term standing for term's equivalence class — term itself when nothing has merged it, so this is total and never nil.

retract! clj

(retract! conn handle)

Retract the sentex handle names, tearing down what it solely supported.

same-class? clj

(same-class? conn a b)

(same-class? conn a b context)

Do a and b denote the same thing? The complement of a provable (different a b): distinct symbols denote distinct individuals until an equality sentex says otherwise.

search-tree clj

(search-tree conn goal)

(search-tree conn goal context)

(search-tree conn goal context opts)

The backward search for goal in context, as data — every node the frontier reached, not only the path that answered.

sees? clj

(sees? conn k y)

Does context k see assertions made in context y? True iff y is in k's genlCx up-closure (reflexively, so a context sees itself).

sentex clj

(sentex conn handle)

The sentex handle names, as a map.

sentex-count clj

(sentex-count conn)

How many sentexes the KB holds, in total — the count the count-aware trie keeps at its root, so O(1) and nothing fetched.

sentexes-in-context clj

(sentexes-in-context conn context)

(sentexes-in-context conn context opts)

Every stored sentex asserted in context (its extent, rules included) — a defeated or unsupported one included.

sentexes-matching clj

(sentexes-matching conn sentence)

(sentexes-matching conn sentence context)

The believed sentexes matching sentence (a pattern may carry ?vars), as maps.

sentexes-with-arg clj

(sentexes-with-arg conn pos term)

(sentexes-with-arg conn pos term opts)

Every stored fact sentex holding term at 1-based argument position pos — a defeated or unsupported one included.

sentexes-with-functor clj

(sentexes-with-functor conn pred)

(sentexes-with-functor conn pred opts)

Every stored fact sentex whose functor is pred, any arity, either polarity — a defeated or unsupported one included.

settle-stats clj

(settle-stats conn)

Instrumentation for the exceptWhen fixpoint in settle.

specs clj

(specs conn t)

(specs conn t context)

The types that are subtypes of t, transitively. Scoped by context like genls.

supporting-justifications clj

(supporting-justifications conn handle)

Justifications that conclude handle (its supporting justifications), in content order — the informant's own sentence, then the antecedent sentences (kb/justification-content-key).

term-count clj

(term-count conn)

How many distinct terms the KB's vocabulary holds — one set-size read, O(1), nothing fetched.

term-expression clj

(term-expression conn term)

The functional expression a reified term denotes — (FruitFn AppleTree) for the constant minted from it — or nil for an ordinary term, and for a reified one whose (termOfUnit K E) map is not believed.

terms clj

(terms conn)

Every term the index is keyed by — the KB's vocabulary: each predicate, individual, type, and context name mentioned by a stored sentex, at any nesting depth.

types clj

(types conn)

Every type currently in the genl hierarchy — the nodes of the closure, i.e. every type named by some believed genl edge.

types-of clj

(types-of conn x)

(types-of conn x context)

The types individual x belongs to.

unwatch clj

(unwatch conn token)

Drop subscription token; true if there was one. Idempotent.

violations clj

(violations conn)

The recorded definitional violations.

vocabulary-audit clj

(vocabulary-audit conn)

Every term CxCore declares in kb, classified — {:enforced [[term why] …] :inert [[term why] …] :unclassified [term …] :retired [term …] :contradicted [term …]}.

watch clj

(watch conn)

(watch conn goal context)

Open a change-feed subscription and return {:token t :cursor 0 :max-events n}.

In process vaelii.core/watch takes a callback; a callback does not cross an EDN wire, so what a remote caller holds is a subscription the daemon keeps and this client reads forward with a cursor. With no goal it is every belief change; with one it is the same standing query, and a goal that cannot be answered from a moved region is refused with the same :not-watchable it is refused with in process.

(let [{:keys [token cursor]} (watch conn)]
  (loop [c cursor]
    (let [{:keys [events cursor lagged]} (poll conn token c {:wait-ms 20000})]
      (when (pos? lagged) (resync!))
      (run! render! events)
      (recur cursor))))

watchers clj

(watchers conn)

What the daemon is holding open: one entry per subscription with its goal, how many events it has been :delivered, and how many are still :pending on its ring. Neither is the reader's own position — that lives here, not there.

why clj

(why conn handle)

(why conn handle opts)

Why the sentex handle names is believed — its supporting justifications, as data. opts is core/why's {:max-depth n}, which is how a {:truncated? true} branch is re-asked whole.

why-not clj

(why-not conn handle)

(why-not conn sentence context)

(why-not conn sentence context opts)

Why a sentence is not believed, by handle or by sentence and context; opts takes {:nearest n} to name the rule that came closest and what it is missing.