vaelii.host.cli — com.vaelii/vaelii 0.20.0

A command-line driver for a KB — the shell dual of the in-process API, launched with lein run -m vaelii.host.cli <cmd> <args…>. It runs the engine in-process (no daemon); to talk to a running daemon use vaelii.host.client instead.

lein run -m vaelii.host.cli assert '(dog Muffet)' CxNaturalWorld --dir /tmp/kb lein run -m vaelii.host.cli query '(dog ?x)' CxNaturalWorld --dir /tmp/kb lein run -m vaelii.host.cli why 3 --dir /tmp/kb lein run -m vaelii.host.cli export /tmp/dump --dir /tmp/kb lein run -m vaelii.host.cli repl --starter # interactive, starter schema lein cli help # every command and what it takes

help is a word rather than only a flag because Leiningen answers lein cli --help itself, printing the alias expansion — the flag never reaches this namespace through the alias, though it does through the full lein run -m vaelii.host.cli --help.

Backend. --dir <path> opens the store there under the backend its files were written by (v/store-backend), or a new durable :disk-log store when it holds none — recovered on open, so a fact asserted in one invocation is there in the next. upgrade opens a store, brings its reasoning image and index image up to this build, and closes it (upgrade!); --verify recovers anyway and compares the two images. With no --dir the KB is in-memory and lives only for the process — useful for repl or a single compound session, pointless across one-shot commands. --starter loads the shipped schema (types, contexts, relation rules) so you can explore the ontology. --strength monotonic marks an assert or assert-rule known-true. export takes --variant records|records+index and --compression gzip|xz|none.

A flag belongs to the commands that read it (command-flags), and one carried by a command that does not is refused rather than dropped — those three are the driver's and go anywhere, the rest do not.

One writer. A --dir KB takes the single-writer file lock (docs/storage.md), so the CLI and a daemon cannot own the same directory at once — by design.

-main clj

(-main & argv)

Parse argv, open the KB, run the command, and print the result. With repl (or no command) it drops into the interactive loop.

check-arity! clj

(check-arity! cmd args)

Refuse a command line with the wrong number of operands, naming what the command takes and what it got.

Without this the short line reaches dispatch, whose nth raises IndexOutOfBoundsException — caught and printed, so lein cli assert '(dog Rex)' answers error: IndexOutOfBoundsException: a true statement about a vector, and no help at all to someone who left off a context. A long line is refused too, since the extra operand is otherwise dropped in silence — and a dropped context is a fact stored somewhere other than where it was meant to go.

check-flags! clj

(check-flags! cmd opts)

Refuse a flag cmd does not read, naming what it does read.

-main calls this rather than dispatch, and that placement is the whole of it: the REPL reuses one option map for every line it runs, so a session opened --strength monotonic must not have a later match line refused for carrying the session's flag. The line naming repl is checked against the union instead, and the lines inside it against nothing.

An unknown command word is left alone, as check-arity! leaves it — -main reports that as :unknown-command, which says more than a flag complaint about a command that does not exist.

command-table clj

Every command word, in the order --help prints it: [min max operands gloss].

max is nil for a command whose last operand is optional. One table rather than two, because the arity a command takes and the arity --help advertises going out of step is how a usage message starts lying — and dispatch reaches into args with nth, so an unchecked short line raises IndexOutOfBoundsException, whose message is the class name and names neither the command nor the argument.

commands clj

The command words dispatch knows, for the usage message and unknown command.

dispatch clj

(dispatch kb cmd args opts)

Run one command against kb and return its result (a handle, a seq of sentences / solutions, a proof tree, …). args are data; opts is the parsed option map.

A command that answers a set answers it sorted (in-content-order): match, query and ask alongside types and contexts, so one KB prints the same output however its knowledge arrived. prove keeps the DFS's order, which is a reading rather than an artifact.

open-kb-from clj

(open-kb-from {:keys [dir starter memory] :as _opts})

Build the KB a run operates on from the parsed opts: :dir → durable disk (recovered), else in-memory — which :memory also names explicitly, so --memory --dir <path> is a contradiction and is refused rather than resolved by a guess. :starter loads the shipped schema.

parse-opts clj

(parse-opts args)

Split raw args into [positionals opts]. --k v becomes {:k v}, a bare flag (bare-flags) becomes {:flag true}; everything else is a positional, in order.

A value-taking flag with no value is refused (:unknown-option) rather than bound nil: assert … --strength with nothing after it would otherwise store at :default — the exact class the flag was written to escape — and --dir at the end of a line would open the in-memory KB, gone at process exit. A flag the roster does not name is refused the same way.

read-arg clj

(read-arg s)

One argv string as data: the EDN it reads as — a sentence, a context symbol, a handle — and the raw string when it reads as none.

That last case is what a filesystem path is. /var/lib/vaelii is not a symbol (two slashes), so a command taking a path (export, load) would otherwise fail in the reader, before the command it belongs to had been looked at.

read-forms clj

(read-forms s)

Every EDN form in s, in order — how a REPL line's args ((dog ?x) CxMy) are parsed into data.

upgrade! clj

(upgrade! dir)

(upgrade! dir {:keys [verify]})

Bring the store in dir up to this build, and report what that took. Opens the store under the backend its files were written by, with :recover? :auto: a reasoning image this build can install is installed, and one written under another image layout, other engine source or other policies is declined, belief is recovered from the records, and the recover writes a new image. Closing the store then writes the index image a rebuilt index leaves due. Returns

{:dir :backend :reasoning :current | :rebuilt | :written | :no-image :image {:format :network :written-at :source} ; the stamp now on disk, :source cut to 12 :index :current | :rewritten | :no-image :verify …} ; with :verify only

:current is an image the open installed and left as it was; :rebuilt is one the open declined and replaced; :written is the first image of a store that held none; :no-image is a backend that keeps none (:disk-log, :disk-columnar). The records are read and never rewritten.

One option changes what happens to an image written under other engine source:

• :verify moves the image to reasoning.prev/ before the open, so the open recovers from the records and writes a new image. Then it compares the two (reasoning-image/compare-images) and deletes the old one. :verify in the result is {:against source :labels :network :state}, or one keyword when the two cannot be compared: :no-previous-image, :no-image, :layout-changed or :records-moved. When the open writes no image, the old one is moved back.

A directory holding no store is refused (:unknown-source) rather than creating an empty one there. ! because the image it replaces cannot be read back.

usage clj

(usage)

The --help text: every command, its operands and a one-line gloss.