solvi.worldmap¶
A map of an environment an agent builds by acting: claims with provenance.
A map of an environment that an agent builds by acting — claims with provenance, not a given.
An agent that works in the same environment again and again — a site, an internal tool, a command line, a file tree —
re-discovers its structure on every task unless it keeps a map. A WorldMap is that map, written as the agent goes:
from solvi.worldmap import WorldMap
m = WorldMap("console.map.json") # loaded when the file exists; m.save() writes it
m.see(page, "Billing", to="/billing") # an action on offer here; `to` when the environment shows it (a link)
m.arrive(page, "Billing", "/billing") # the action was taken: the claim is confirmed — or refuted
m.next(page, {"/billing/refunds"}) # the action to take towards a target over what is known, or None
m.explore(page) # ... or towards the nearest claim nobody has checked yet
Every edge is a claim "(state, action) leads to state" with a status — hypothesis, confirmed — a source — seen (the
environment showed where it leads), observed (the agent went), told (a document, a sign), human — and its evidence
(the steps, a quote). Whoever made a claim, the next observation can refute it: a person's correction or a line of an
outdated document is a hypothesis like any other, and arrive records the refutation with what was believed and by
whom. Every write is a journal entry in a hash chain (verify()), so the map as it was at any step can be rebuilt
(rebuild(upto=n)); a saved map is loaded by replaying its journal, so an edge edited in the file changes nothing.
What the map knows is what it was told through these calls: it does not know what a page or a directory is. The
adapter — list the actions of a state, take one — is yours. snapshot(state, targets) gives a decision the part of
the map it needs as a plain fact (the known way, what is unexplored here), so decisions that use it replay.
Where it helps: the gain is the map carried from one task to the next, in an environment that is deep and met again (a command tree, a file tree, a documentation site several clicks deep) — later tasks take fewer steps than the first. It does not make a first exploration shorter, it gives nothing where everything is one step away, and it does not tell which state a task needs — only how to get to one that is named.
WorldMap ¶
See the module docstring. path: a JSON file the map is loaded from when it exists (save() writes it).
hypothesis_cost: how many confirmed steps an unchecked claim with a destination counts as in distances.
A state or an action is a string, a number or a tuple of those; save / load keep them as they are.
verify ¶
Is the journal's hash chain whole (nothing edited, removed or reordered), and is the map what the journal says — every claim (and, for a map whose visits are journaled, every state) the one its entries give?
rebuild ¶
The map as its journal gives it — a new WorldMap made by applying the entries in order (upto: only the first
upto of them: the map as it was at that step). ValueError when the entries do not give this journal back (an
entry that could not have been written in its place).
visit ¶
The agent is in this state (facts: what it noticed here — a title, a service; kept on the state).
see ¶
An action is on offer in this state. to: where it leads when the environment shows that before acting (a
link's address, a directory entry) — then a hypothesis with a destination, source "seen"; else the destination
is unknown until someone takes it. A confirmed claim is not touched.
told ¶
Someone says where an action leads — a document, a sign (source="told"), a person (source="human"): a
hypothesis with a destination and the quote. It replaces an unchecked claim; a confirmed one stands until an
observation refutes it — use arrive for what was observed.
human ¶
A person's correction: told(..., source="human").
arrive ¶
The action was taken in state and led to to: the claim is confirmed. → True when this refuted what was
believed (another destination, whoever claimed it); the refutation is in the journal.
distances ¶
state → (cost to the nearest target, the first action to take): over confirmed claims (1 each) and, unless confirmed_only, unchecked claims with a destination (hypothesis_cost each). Targets map to (0, None).
next ¶
The action to take in state on the cheapest known way to a target; None when no way is known (or the
state is a target).
path ¶
The actions of the cheapest known way from state to a target → [(state, action)], [] when none.
frontier ¶
What acting can still teach: the (state, action) pairs never taken — unknown destinations and claims nobody has checked.
explore ¶
The action to take in state towards the nearest untaken action (an untaken action here first); None when
the map has nothing left to check from here.
snapshot ¶
The part of the map a decision needs, as a plain fact: the known way to a target, what is on offer here and what of it is unchecked. Give it to a decision as a given fact; the decision then replays.
to_dict ¶
The map as JSON data. States that are all strings are written as an object (as before); otherwise as a list of {"state", "visits", "facts"}, since a JSON object's keys are strings only.
load ¶
Read a saved map. The journal is the stored truth: its hash chain is checked and the claims are rebuilt from
it — the file's own edges are not trusted (an edge edited there changes nothing) — and so are the states of a
map whose visits are journaled; a file written before that keeps its states as stored. ValueError when the
journal's chain is broken or its entries do not replay.