solvi.solutions.knowledge¶
solvi.Knowledge: the knowledge store, the agenda, the action model and the failure memory behind one object that
solvi.build, solvi.Guard and solvi.Agent share. See Using solvi: agents and knowledge.
Knowledge: what a system learned, from whom, and what rests on it — one object a decision system, a guard and an environment agent share.
import solvi
km = solvi.Knowledge("knowledge.jsonl", vocabulary={"here": lambda s, a: s["here"]})
km.tell({"s": "c17", "r": "tier", "o": "vip"}, source="person", by="crm") # a fact, with its source
km.goal("wood", done=lambda s: s["wood"] > 0) # an agenda goal: done is code
km.agenda.gate("tool_first", lambda s: s["pickaxe"], blocks=["collect_stone"]) # a gate: a hard check
km.observe(state, "collect_wood", outcome) # an environment step: action model, map facts, agenda, skills
km.retract(item_id, why="wrong label") # with everything derived from it
km.report()
A facade over the low level (solvi.core.knowledge): store is the KnowledgeStore (the hash-chained journal: facts,
rules, skills, actions, episodes, with provenance, disputes to a person and the exact retraction cascade), agenda the
Agenda (goals with done checks in code, gates, order — in the same journal), actions the action model
(ConservativeActionModel over vocabulary, or one of your own with actions=, or None), failures the failure memory
(FailureMemory, with failures=True or its settings as a dict; None by default).
Who reads it: solvi.build(..., knowledge=km) gives every decision km.snapshot() as the fact "knowledge" (a rule
reads it with Knowledge.value(knowledge, s, r)); solvi.Guard(..., knowledge=km) turns the action model's refusals
and the agenda's gates into hard checks on tool calls; solvi.Agent(env, knowledge=km) acts on it in an environment
and writes what it observes back. Knowledge never comes from the system's own unverified answers: the store's source
check refuses them (sources "person", "outcome", "spec", or "verified" with the stored decision it comes from).
Map facts. observe(..., at=, to=, map=) writes what an environment showed as facts scoped to one map: "leads_to
at, the action led to the key to) and "accepts
Knowledge ¶
Knowledge(path=None, *, vocabulary=None, write_gate=None, actions=None, failures=None, severity=1.0)
See the module docstring.
path: where the journal is kept — None (in memory), a path (.jsonl, .db, ...) or a TraceStorage (the decisions'
store, so knowledge and decisions share one hash chain); an existing journal is replayed (the action model too, when
it is built from a vocabulary). vocabulary: a Vocabulary or {name: predicate(state, args)} — the conditions the
action model may learn from (None: no action model unless actions= gives one). write_gate: a WriteGate (or a list)
run after the built-in source and consistency gates. actions: an ActionModel of your own (instead of vocabulary=).
failures: True or FailureMemory settings ({"window", "unit", "max_blocked", "min_open"}) — a failure memory whose
blocks are hard checks of the agent (None: off). severity: the action model's harm of a refused action (a number or
{action: number}).
tell ¶
Write a fact — {"s", "r", "o"} or (s, r, o) — from a person, an outcome, a written spec, or a verified System 2
answer (of= its stored decision). It goes through the source check and the write gates; a contradiction of
equal rank becomes a person question (store.disputes()). → the item's id, or None when a gate refused it (the
journal says why).
retract ¶
Take an item back with everything derived from it (nothing is deleted: the journal keeps it). → {"status":
{id: (before, after)}, "answer_changes", "justification_only"} — the last two (with storage=, the decisions'
TraceStorage, and decide=, a System or a function init → answers) list the stored decisions that rested on
it, re-run on the snapshot rebuilt without it: the answer changes (for a reviewer) or only the justification.
goal ¶
An agenda goal: done(state) → bool is its check in code (never a model's claim); requires: goals done first;
gates: gates (declared with km.agenda.gate(name, check, blocks=)) that must pass for it to be open. → self.
observe ¶
One environment step: action taken in state gave outcome (an Outcome, or True / False: accepted or
refused). Updates the action model (and journals its prediction against what happened), the failure memory,
the agenda (done checks on the new state) and the skills (a goal done right after this action); with at
(the key of state), to (the key reached) and map (the map's name), the map facts — the first
contradiction of a fact carried from an earlier episode flags the map (see the module docstring).
→ {"prediction": the action model's prediction before the step (dict) or None, "surprise", "drift": the flag's
id or None, "goals_done": goals whose done check turned true, "skills": skill item ids written}.
accepted_at ¶
What the map says about taking akey at at: True / False (a usable fact), or None.
snapshot ¶
What a decision is given: KnowledgeStore.snapshot(**query) (default: the facts and rules) — the active items as facts, the hints with why, the ids they rest on, the store's fingerprint and journal position.
value
staticmethod
¶
The value of the active fact (s, r) in a snapshot (the fact "knowledge" a rule reads), or default.
report ¶
What was learned and from whom (the store's report), the agenda (done, open, blocked), the action model (per action: allowed values, refusal signatures, transitions — for the built-in model), the skills, the failure memory's blocks, and the map facts per map.
action_key ¶
An environment's action as the knowledge names it: a string as it is, anything else as its JSON form.
split_action ¶
An action → (name, args) for an action model and the agenda's gates: "name" → (name, {}); ("name", x, ...) → (name, {"args": [x, ...]}); {"name": n, ...} → (n, the other keys); anything else → (its JSON form, {}).