@lmmslab/harness 0.0.0-stage → 0.81.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +124 -2
- package/bin/harness.js +71 -0
- package/package.json +34 -4
- package/python/harness/README.md +72 -0
- package/python/harness/__init__.py +8 -0
- package/python/harness/__main__.py +3 -0
- package/python/harness/bench.py +124 -0
- package/python/harness/builtin/benches/README.md +5 -0
- package/python/harness/builtin/benches/none/bench.toml +6 -0
- package/python/harness/builtin/configs/README.md +26 -0
- package/python/harness/builtin/configs/assistant.toml +11 -0
- package/python/harness/builtin/configs/default.toml +33 -0
- package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
- package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
- package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
- package/python/harness/builtin/configs/models/grok-low.toml +8 -0
- package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
- package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
- package/python/harness/builtin/environment/README.md +53 -0
- package/python/harness/builtin/environment/constraints.txt +31 -0
- package/python/harness/builtin/model-settings.js +143 -0
- package/python/harness/builtin/prompts/conversation/core.md +5 -0
- package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
- package/python/harness/builtin/prompts/core/core.md +88 -0
- package/python/harness/builtin/prompts/core/pack.toml +9 -0
- package/python/harness/builtin/prompts/reflect/core.md +45 -0
- package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
- package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
- package/python/harness/builtin/prompts/shared/agents.md +14 -0
- package/python/harness/builtin/prompts/shared/checklist.md +21 -0
- package/python/harness/builtin/prompts/shared/entries.md +86 -0
- package/python/harness/builtin/prompts/shared/environments.md +21 -0
- package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
- package/python/harness/builtin/prompts/shared/learning.md +27 -0
- package/python/harness/builtin/prompts/shared/mcp.md +9 -0
- package/python/harness/builtin/prompts/shared/world.md +1 -0
- package/python/harness/builtin/skills/README.md +10 -0
- package/python/harness/builtin/skills/agents/__init__.py +88 -0
- package/python/harness/builtin/skills/agents/skill.toml +11 -0
- package/python/harness/builtin/skills/checklist/__init__.py +32 -0
- package/python/harness/builtin/skills/checklist/skill.toml +9 -0
- package/python/harness/builtin/skills/conversation/__init__.py +23 -0
- package/python/harness/builtin/skills/conversation/skill.toml +8 -0
- package/python/harness/builtin/skills/entries/__init__.py +62 -0
- package/python/harness/builtin/skills/entries/skill.toml +8 -0
- package/python/harness/builtin/skills/environments/__init__.py +69 -0
- package/python/harness/builtin/skills/environments/skill.toml +9 -0
- package/python/harness/builtin/skills/experience/__init__.py +27 -0
- package/python/harness/builtin/skills/experience/skill.toml +9 -0
- package/python/harness/builtin/skills/instructions/__init__.py +29 -0
- package/python/harness/builtin/skills/instructions/skill.toml +9 -0
- package/python/harness/builtin/skills/learning/__init__.py +189 -0
- package/python/harness/builtin/skills/learning/skill.toml +7 -0
- package/python/harness/builtin/skills/mcp/__init__.py +54 -0
- package/python/harness/builtin/skills/mcp/skill.toml +10 -0
- package/python/harness/builtin/skills/memory/__init__.py +130 -0
- package/python/harness/builtin/skills/memory/skill.toml +13 -0
- package/python/harness/builtin/skills/verify/__init__.py +31 -0
- package/python/harness/builtin/skills/verify/skill.toml +7 -0
- package/python/harness/builtin/third_party/sources.toml +40 -0
- package/python/harness/cli.py +1182 -0
- package/python/harness/config/__init__.py +224 -0
- package/python/harness/config/agent.py +777 -0
- package/python/harness/core/__init__.py +52 -0
- package/python/harness/core/artifacts.py +46 -0
- package/python/harness/core/codec.py +160 -0
- package/python/harness/core/contracts.py +75 -0
- package/python/harness/core/episodes.py +150 -0
- package/python/harness/core/format.py +51 -0
- package/python/harness/core/http.py +124 -0
- package/python/harness/core/lanes.py +324 -0
- package/python/harness/core/linux_sandbox.py +55 -0
- package/python/harness/core/media.py +96 -0
- package/python/harness/core/memory.py +147 -0
- package/python/harness/core/ports.py +63 -0
- package/python/harness/core/procs.py +227 -0
- package/python/harness/core/remote.py +102 -0
- package/python/harness/core/spans.py +166 -0
- package/python/harness/core/trace.py +139 -0
- package/python/harness/core/wait.py +12 -0
- package/python/harness/core/worker.py +388 -0
- package/python/harness/core/worker_pipe.py +119 -0
- package/python/harness/embodiments.py +217 -0
- package/python/harness/extensions.py +112 -0
- package/python/harness/host/__init__.py +397 -0
- package/python/harness/host/client.py +201 -0
- package/python/harness/host/http.py +720 -0
- package/python/harness/host/listing.py +68 -0
- package/python/harness/host/server.py +189 -0
- package/python/harness/host/sessions.py +406 -0
- package/python/harness/host/tasks.py +1308 -0
- package/python/harness/host/workers.py +257 -0
- package/python/harness/host/workspaces.py +256 -0
- package/python/harness/model_list.py +117 -0
- package/python/harness/packages/__init__.py +73 -0
- package/python/harness/packages/addons.py +121 -0
- package/python/harness/packages/archive.py +122 -0
- package/python/harness/packages/describe.py +46 -0
- package/python/harness/packages/environments.py +448 -0
- package/python/harness/packages/fetch.py +57 -0
- package/python/harness/packages/manager.py +587 -0
- package/python/harness/packages/manifest.py +221 -0
- package/python/harness/packages/migrate.py +68 -0
- package/python/harness/packages/provision.py +38 -0
- package/python/harness/packages/registry.py +275 -0
- package/python/harness/packages/resolve.py +89 -0
- package/python/harness/packages/sources.py +141 -0
- package/python/harness/packages/state.py +213 -0
- package/python/harness/packages/versions.py +112 -0
- package/python/harness/paths.py +218 -0
- package/python/harness/providers.py +303 -0
- package/python/harness/runtime/__init__.py +8 -0
- package/python/harness/runtime/decision/__init__.py +1 -0
- package/python/harness/runtime/decision/loop.py +198 -0
- package/python/harness/runtime/decision/messages.py +271 -0
- package/python/harness/runtime/decision/model.py +424 -0
- package/python/harness/runtime/decision/prompts.py +248 -0
- package/python/harness/runtime/decision/protocol.py +169 -0
- package/python/harness/runtime/decision/thoughts.py +199 -0
- package/python/harness/runtime/events.py +213 -0
- package/python/harness/runtime/execution/__init__.py +1 -0
- package/python/harness/runtime/execution/attached.py +96 -0
- package/python/harness/runtime/execution/control.py +211 -0
- package/python/harness/runtime/execution/entries.py +665 -0
- package/python/harness/runtime/execution/kernel.py +811 -0
- package/python/harness/runtime/execution/noenv.py +84 -0
- package/python/harness/runtime/execution/results.py +40 -0
- package/python/harness/runtime/execution/session.py +871 -0
- package/python/harness/runtime/execution/skills.py +436 -0
- package/python/harness/runtime/learning/__init__.py +1 -0
- package/python/harness/runtime/learning/active.py +314 -0
- package/python/harness/runtime/learning/experience.py +48 -0
- package/python/harness/runtime/learning/fixtures.py +167 -0
- package/python/harness/runtime/learning/learner.py +651 -0
- package/python/harness/runtime/learning/library.py +504 -0
- package/python/harness/runtime/learning/reflect.py +151 -0
- package/python/harness/runtime/learning/usage.py +30 -0
- package/python/harness/runtime/learning/views.py +89 -0
- package/python/harness/runtime/reactive/__init__.py +1 -0
- package/python/harness/runtime/reactive/rules.py +549 -0
- package/python/harness/runtime/safety/__init__.py +1 -0
- package/python/harness/runtime/safety/approval.py +131 -0
- package/python/harness/runtime/safety/input.py +62 -0
- package/python/harness/runtime/safety/isolation.py +419 -0
- package/python/harness/runtime/safety/shield.py +129 -0
- package/python/harness/runtime/status.py +23 -0
- package/python/harness/runtime/task/__init__.py +7 -0
- package/python/harness/runtime/task/context.py +431 -0
- package/python/harness/runtime/task/delegation.py +468 -0
- package/python/harness/runtime/task/environments.py +268 -0
- package/python/harness/runtime/task/run.py +2878 -0
- package/python/harness/runtime/tick.py +909 -0
- package/python/harness/sdk/__init__.py +281 -0
- package/python/harness/services/__init__.py +6 -0
- package/python/harness/services/broker.py +35 -0
- package/python/harness/services/connectors.py +88 -0
- package/python/harness/services/mcp.py +298 -0
- package/python/harness/services/mcp_stdio.py +131 -0
- package/python/harness/services/placement.py +82 -0
- package/python/harness/services/registry.py +156 -0
- package/python/harness/settings.py +536 -0
- package/python/harness/terminal.py +79 -0
- package/python/harness/transcript.py +297 -0
- package/python/harness/tui/__init__.py +68 -0
- package/python/harness/tui/chat.py +1181 -0
- package/python/harness/tui/pty.py +81 -0
- package/python/harness/tui/renderer.py +45 -0
- package/python/harness/tui/timeline_rows.py +58 -0
- package/python/harness/tui/views.py +434 -0
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
"""A fixed, non-learned check on every command before it takes effect.
|
|
2
|
+
|
|
3
|
+
The shield runs in the environment worker, outside the process that executes
|
|
4
|
+
model-written code, so programs cannot modify it, and nothing learned reaches it. Every
|
|
5
|
+
embodiment's shield has the same interface, the core's (CommandShield):
|
|
6
|
+
it judges one command against the measured state, and the command passes unchanged or is
|
|
7
|
+
rejected with the reasons; it never shortens, clamps or otherwise alters a command, since
|
|
8
|
+
a program whose command was quietly changed does not learn it was wrong. A tick's
|
|
9
|
+
`shield` field is its ShieldResult. The shields of the robot, a computer and a game are
|
|
10
|
+
described here; each is in the package of its embodiment.
|
|
11
|
+
|
|
12
|
+
Shield (the robot package, harness_robot/shield.py) is the robot's. It sees absolute
|
|
13
|
+
joint position commands and, when the worker supplies forward kinematics, the
|
|
14
|
+
end-effector positions those commands imply. It catches commands that are bugs, and
|
|
15
|
+
nothing else. Rejected are:
|
|
16
|
+
|
|
17
|
+
- a malformed command (wrong length, a value that is not finite);
|
|
18
|
+
- a joint outside its limits, or an end effector outside the workspace box,
|
|
19
|
+
further than the robot already is (contact can push a measured joint or hand
|
|
20
|
+
slightly out; holding there or moving back in is not a bug);
|
|
21
|
+
- a jump: an arm's joints more than max_joint_jump_rad, or its end effector more
|
|
22
|
+
than max_cartesian_jump_m, from both the previous accepted command and the
|
|
23
|
+
measured state. One control tick of a real motion moves far less; a jump is an
|
|
24
|
+
IK solution on another branch, a target in the wrong frame, a controller that
|
|
25
|
+
diverged. A smooth sequence is never rejected for running ahead of an arm that
|
|
26
|
+
lags behind it, and a command from where the arm is (a hold, the next skill's
|
|
27
|
+
first waypoint, a retreat) is never rejected for where the last one went.
|
|
28
|
+
|
|
29
|
+
Speed and acceleration are not the shield's: the skills time their own motions,
|
|
30
|
+
and a physical robot's controller enforces its own rate limits.
|
|
31
|
+
|
|
32
|
+
DesktopShield (the computer package, harness_computer/shield.py) is a computer's. It
|
|
33
|
+
sees one input step (DESKTOP_COMMANDS) and rejects an unknown command, field or key, a
|
|
34
|
+
point off the screen, text the keyboard cannot type, and a scroll, wait or drag out of
|
|
35
|
+
its bounds. A step into one window (its `window` field) has its points in that window's
|
|
36
|
+
picture, which the worker checks; an element action (act) names an element id and one of
|
|
37
|
+
its actions. Where several agents share a computer it also rejects a step into a window
|
|
38
|
+
another agent owns (owner(): the machine-wide ownership of the computer package's
|
|
39
|
+
coordination.py), and claims an unowned one for the agent.
|
|
40
|
+
|
|
41
|
+
GameShield (the game package, harness_game/shield.py) is a game's. It sees one generic
|
|
42
|
+
input (GAME_COMMANDS: those of GameScientist's action protocol, in screen pixels) and
|
|
43
|
+
rejects what that protocol would: an unknown command, field, key or button, a point off
|
|
44
|
+
the screen, a duration, wait, relative motion or scroll out of its bounds, too many or
|
|
45
|
+
repeated keys. An embodiment may also block keys a game's rules forbid (its `blocked`
|
|
46
|
+
table: the key and the rule, such as Minecraft's chat and pause keys during a speedrun).
|
|
47
|
+
A game that declares channels (its [channels]: who holds which keys, buttons, pointer
|
|
48
|
+
use and wheel at a time) also takes a state input, the one its kernel's tick merges
|
|
49
|
+
every period from what each entry holds (runtime/tick.py), checked channel by channel.
|
|
50
|
+
The fairness caps ([shield.fairness], graded: FAIRNESS) bound what a person could match:
|
|
51
|
+
button presses a second, the view's turn a period, keys down together. Text typed into a
|
|
52
|
+
text field (a text input, or a state's `text` on the channel that types) passes only
|
|
53
|
+
with the game's [shield.text]: its characters, its length, the screen read now among its
|
|
54
|
+
screens (Minecraft: the recipe book's search, where a letter is the field's, never a key
|
|
55
|
+
such as the blocked T), and alone: no key pressed, or let go, in the same input.
|
|
56
|
+
|
|
57
|
+
The checks every shield shares are here, one rule each: finite (a finite number, never a
|
|
58
|
+
bool), in_screen (a point of the picture: 0 <= x < width, 0 <= y < height), bounded (a
|
|
59
|
+
finite number in [low, high], an int where the field counts) and reject."""
|
|
60
|
+
|
|
61
|
+
from dataclasses import dataclass, field
|
|
62
|
+
import math
|
|
63
|
+
import re
|
|
64
|
+
import time
|
|
65
|
+
from typing import Any, Callable, Protocol
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
PASS = "pass"
|
|
69
|
+
REJECTED = "rejected"
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class ShieldResult:
|
|
74
|
+
"""The verdict on one command: "pass" with the command unchanged, or "rejected" with
|
|
75
|
+
no command and the reason (the failed check and the values it compared). The command
|
|
76
|
+
is the embodiment's: a robot's joint vector."""
|
|
77
|
+
|
|
78
|
+
verdict: str
|
|
79
|
+
command: Any
|
|
80
|
+
reasons: list[dict] = field(default_factory=list)
|
|
81
|
+
|
|
82
|
+
def to_dict(self) -> dict:
|
|
83
|
+
"""The result as a plain dict, as a tick's `shield` field."""
|
|
84
|
+
return {"verdict": self.verdict, "command": self.command, "reasons": self.reasons}
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class CommandShield(Protocol):
|
|
88
|
+
"""The shield of one worker, whatever the embodiment: a fixed check of every command
|
|
89
|
+
against the measured state (`current`) and what else the worker knows (`context`, such
|
|
90
|
+
as a robot's forward kinematics), passing it unchanged or rejecting it with reasons."""
|
|
91
|
+
|
|
92
|
+
def reset(self) -> None:
|
|
93
|
+
"""Forget what earlier commands of the episode established."""
|
|
94
|
+
|
|
95
|
+
def check(self, command, current, **context) -> ShieldResult:
|
|
96
|
+
"""The verdict on `command`."""
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def finite(*values) -> bool:
|
|
100
|
+
"""Whether every value is a finite number (a bool is not one)."""
|
|
101
|
+
return all(isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v) for v in values)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def in_screen(x, y, screen=None) -> dict | None:
|
|
105
|
+
"""The reason (x, y) is no point of the picture `screen` ([width, height]), or None. A
|
|
106
|
+
point is two finite numbers with 0 <= x < width and 0 <= y < height (pixel x covers
|
|
107
|
+
[x, x + 1)); without `screen` only the numbers are checked (a window's picture, which
|
|
108
|
+
the worker knows)."""
|
|
109
|
+
if not finite(x, y):
|
|
110
|
+
return {"check": "point", "reason": "x and y must be finite numbers (pixels)", "x": x, "y": y}
|
|
111
|
+
if screen is not None:
|
|
112
|
+
width, height = screen
|
|
113
|
+
if not (0 <= x < width and 0 <= y < height):
|
|
114
|
+
return {"check": "screen", "x": x, "y": y, "screen": [width, height]}
|
|
115
|
+
return None
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def bounded(name, value, low, high, *, integer=False) -> dict | None:
|
|
119
|
+
"""The reason `value` is out of its bounds, or None: the one bounds rule of every shield,
|
|
120
|
+
a finite number (an int when the field counts something: `integer`) with
|
|
121
|
+
low <= value <= high."""
|
|
122
|
+
if not finite(value) or (integer and not isinstance(value, int)) or not low <= value <= high:
|
|
123
|
+
return {"check": name, "got": value, "limit": [low, high]}
|
|
124
|
+
return None
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def reject(reason: dict) -> ShieldResult:
|
|
128
|
+
"""A rejection for `reason` (no command passes)."""
|
|
129
|
+
return ShieldResult(REJECTED, None, [reason])
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""The conversation lifecycle shared by Runtime and its clients."""
|
|
2
|
+
|
|
3
|
+
IDLE = "IDLE"
|
|
4
|
+
RUNNING = "RUNNING"
|
|
5
|
+
PAUSED = "PAUSED"
|
|
6
|
+
WAITING_FOR_CONFIRMATION = "WAITING_FOR_CONFIRMATION"
|
|
7
|
+
WAITING_FOR_INPUT = "WAITING_FOR_INPUT"
|
|
8
|
+
FINISHED = "FINISHED"
|
|
9
|
+
ERROR = "ERROR"
|
|
10
|
+
# IDLE: waiting for the user's next message (interactive only); FINISHED: the episode is
|
|
11
|
+
# over (its summary says why); ERROR: it ended in an error.
|
|
12
|
+
LIVE = (IDLE, RUNNING, PAUSED, WAITING_FOR_CONFIRMATION, WAITING_FOR_INPUT)
|
|
13
|
+
ENDED = (FINISHED, ERROR, "INTERRUPTED")
|
|
14
|
+
STATUSES = (*LIVE, FINISHED, ERROR)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def live(status) -> bool:
|
|
18
|
+
"""Whether an agent in this status still runs or waits."""
|
|
19
|
+
return status not in ENDED
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class Closed(Exception):
|
|
23
|
+
"""The user closed the conversation while it waited."""
|
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
"""Task-local working memory and its common entry representation.
|
|
2
|
+
|
|
3
|
+
The store belongs to one bounded task. Sharing is explicit; it is not a persistent
|
|
4
|
+
agent identity. Library projections live in runtime.learning.views, usage accounting
|
|
5
|
+
in runtime.learning.usage, and historical reconstruction in core.memory.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import math
|
|
9
|
+
import re
|
|
10
|
+
import threading
|
|
11
|
+
import time
|
|
12
|
+
import uuid
|
|
13
|
+
from collections import deque
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
DEFAULT_MERGE = 3.0
|
|
18
|
+
DEFAULT_FRESH = 600.0
|
|
19
|
+
LIMIT = 2000
|
|
20
|
+
TEXT_CHARS = 32768
|
|
21
|
+
SEEN_EVERY = 5.0 # a thing seen again is recorded at most this often
|
|
22
|
+
SURE = 0.5 # the least confidence the summary mentions
|
|
23
|
+
SUMMARY_CHARS = 160 # an entry's text in the summary, at most (recall() gives it whole)
|
|
24
|
+
SEEN = "seen" # a run's entry's evidence, below EVIDENCE
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True)
|
|
28
|
+
class Kind:
|
|
29
|
+
name: str
|
|
30
|
+
about: str = ""
|
|
31
|
+
merge: float = DEFAULT_MERGE # sightings of it this close are the same thing
|
|
32
|
+
fresh: float = DEFAULT_FRESH # seconds a sighting stays worth mentioning
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def family(kind: str) -> str:
|
|
36
|
+
return str(kind).split(":", 1)[0]
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _position(where):
|
|
40
|
+
"""`where` as a position (a tuple of finite numbers), or None for a named place."""
|
|
41
|
+
if where is None or isinstance(where, str):
|
|
42
|
+
return None
|
|
43
|
+
position = tuple(float(v) for v in where)
|
|
44
|
+
if not 2 <= len(position) <= 3 or not all(math.isfinite(v) for v in position):
|
|
45
|
+
raise ValueError(f"a position is two or three finite numbers, got {list(where)}")
|
|
46
|
+
return position
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _words(text) -> set:
|
|
50
|
+
return set(re.findall(r"[a-z0-9]{2,}", str(text).lower()))
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _score(query, *texts) -> float:
|
|
54
|
+
have = _words(" ".join(str(text).replace("_", " ") for text in texts))
|
|
55
|
+
overlap = len(_words(query) & have)
|
|
56
|
+
return round(overlap / math.sqrt(len(have)), 4) if overlap else 0.0
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class WorkingMemory:
|
|
60
|
+
"""What a run saw and where (see the module docstring)."""
|
|
61
|
+
|
|
62
|
+
def __init__(self, kinds=(), clock=time.monotonic, limit=LIMIT):
|
|
63
|
+
self.kinds = {kind.name: kind for kind in kinds}
|
|
64
|
+
self.compass, self.up = None, 1
|
|
65
|
+
self.items = {}
|
|
66
|
+
self.clock = clock
|
|
67
|
+
self.start = clock()
|
|
68
|
+
self.limit = limit
|
|
69
|
+
self.observation_limit = limit
|
|
70
|
+
self._changes = deque(maxlen=4096)
|
|
71
|
+
self.library = [] # the library's memory entries as the run started, and those it admits
|
|
72
|
+
self.version = 0
|
|
73
|
+
self._slots = {}
|
|
74
|
+
self._expires = {}
|
|
75
|
+
self._frames = {}
|
|
76
|
+
self._lock = threading.RLock()
|
|
77
|
+
|
|
78
|
+
def declare(self, world: dict | None, record=None) -> None:
|
|
79
|
+
"""An embodiment's kinds and direction words (its profile's `world`); with `record`,
|
|
80
|
+
each entry the store already holds is recorded as carried into the run."""
|
|
81
|
+
world = world or {}
|
|
82
|
+
for item in list(self.items.values()) if record else ():
|
|
83
|
+
record(action="carried", **self._fields(item))
|
|
84
|
+
for kind in world.get("kinds") or ():
|
|
85
|
+
self.kinds[kind["name"]] = Kind(kind["name"], kind.get("about", ""), float(kind.get("merge", DEFAULT_MERGE)),
|
|
86
|
+
float(kind.get("fresh", DEFAULT_FRESH)))
|
|
87
|
+
if world.get("compass"):
|
|
88
|
+
self.compass = list(world["compass"])
|
|
89
|
+
self.up = int(world.get("up", self.up))
|
|
90
|
+
self.observation_limit = max(self.limit, min(200000, int(world.get("observation_limit", self.limit))))
|
|
91
|
+
|
|
92
|
+
def remember(self, kind, text="", where=None, name=None, confidence=0.5, source="main", space=None,
|
|
93
|
+
record=None, *, slot=None, ttl=None, stale_after=None, ident=None) -> dict:
|
|
94
|
+
"""Note a thing (see the module docstring): its entry."""
|
|
95
|
+
if not isinstance(kind, str) or not kind:
|
|
96
|
+
raise ValueError("kind is a name such as \"tree\", \"window\" or \"ore:iron\"")
|
|
97
|
+
record = record or (lambda **fields: None)
|
|
98
|
+
position = _position(where)
|
|
99
|
+
confidence = min(1.0, max(0.0, float(confidence)))
|
|
100
|
+
text, name = str(text or ""), None if name is None else str(name)
|
|
101
|
+
if len(text) > TEXT_CHARS:
|
|
102
|
+
raise ValueError(f"a working memory entry is at most {TEXT_CHARS} characters")
|
|
103
|
+
with self._lock:
|
|
104
|
+
now = round(self.clock() - self.start, 2)
|
|
105
|
+
self._expire(now, record)
|
|
106
|
+
known = (self.items.get(self._slots.get((space, slot))) if slot is not None
|
|
107
|
+
else self.items.get(ident) or self._same(kind, position, where, name, text, space))
|
|
108
|
+
if known is not None and slot is not None:
|
|
109
|
+
if (confidence < known["confidence"] and kind != known["kind"]
|
|
110
|
+
and (stale_after is None or now - known["last"] < stale_after)):
|
|
111
|
+
return entry(known)
|
|
112
|
+
if (kind, position or where, confidence) == (known["kind"], known["where"], known["confidence"]):
|
|
113
|
+
if ttl is not None:
|
|
114
|
+
self._expires[known["id"]] = now + float(ttl)
|
|
115
|
+
if confidence == 1:
|
|
116
|
+
known["last"] = now
|
|
117
|
+
return entry(known)
|
|
118
|
+
self.version += 1
|
|
119
|
+
known.update(kind=kind, where=position or where, confidence=confidence, last=now,
|
|
120
|
+
version=self.version, seen=known["seen"] + 1)
|
|
121
|
+
self._changes.append((self.version, space, slot, known["id"]))
|
|
122
|
+
record(action="seen", **self._fields(known))
|
|
123
|
+
return entry(known)
|
|
124
|
+
self.version += 1
|
|
125
|
+
if known is not None:
|
|
126
|
+
if ttl is not None:
|
|
127
|
+
self._expires[known["id"]] = now + float(ttl)
|
|
128
|
+
weight = known["confidence"] / (known["confidence"] + confidence) if known["confidence"] + confidence else 0.5
|
|
129
|
+
if position is not None and ttl is not None:
|
|
130
|
+
known["where"] = position
|
|
131
|
+
elif position is not None:
|
|
132
|
+
known["where"] = tuple(round(a * weight + b * (1 - weight), 2) for a, b in zip(known["where"], position))
|
|
133
|
+
known["confidence"] = round(1 - (1 - known["confidence"]) * (1 - confidence), 3)
|
|
134
|
+
known["last"], known["seen"], known["version"] = now, known["seen"] + 1, self.version
|
|
135
|
+
replacement = text if text or (name is not None and where is None) else known["text"]
|
|
136
|
+
changed = replacement != known["text"]
|
|
137
|
+
known["text"] = replacement
|
|
138
|
+
if str(source) not in known["source"].split("+"):
|
|
139
|
+
known["source"] = known["source"] + "+" + str(source)
|
|
140
|
+
# A thing in view is seen again every look: recorded at most every SEEN_EVERY s
|
|
141
|
+
# (a new text at once).
|
|
142
|
+
if changed or ttl is not None or now - known.get("recorded", -SEEN_EVERY) >= SEEN_EVERY:
|
|
143
|
+
known["recorded"] = now
|
|
144
|
+
record(action="seen", **self._fields(known))
|
|
145
|
+
return entry(known)
|
|
146
|
+
ident = ident or f"memory/{uuid.uuid4().hex}.md"
|
|
147
|
+
item = self.items[ident] = {
|
|
148
|
+
"id": ident, "kind": kind, "name": name, "text": text,
|
|
149
|
+
"where": tuple(round(v, 2) for v in position) if position is not None else where,
|
|
150
|
+
"space": space, "confidence": round(confidence, 3), "source": str(source), "first": now, "last": now,
|
|
151
|
+
"seen": 1, "recorded": now, "version": self.version}
|
|
152
|
+
if slot is not None:
|
|
153
|
+
self._slots[space, slot] = ident
|
|
154
|
+
item["slot"] = slot
|
|
155
|
+
self._changes.append((self.version, space, slot, ident))
|
|
156
|
+
if ttl is not None:
|
|
157
|
+
item["tracked"] = True
|
|
158
|
+
self._expires[ident] = now + float(ttl)
|
|
159
|
+
record(action="remember", **self._fields(item))
|
|
160
|
+
ordinary_count = len(self.items) - len(self._slots) - len(self._expires)
|
|
161
|
+
if slot is None and ttl is None and ordinary_count > self.limit:
|
|
162
|
+
ordinary = (each for each in self.items.values() if "slot" not in each and not each.get("tracked"))
|
|
163
|
+
ranked = sorted(ordinary, key=lambda each: (each["last"], each["confidence"]))
|
|
164
|
+
for old in ranked[:ordinary_count - self.limit]:
|
|
165
|
+
self._drop(old["id"], record, reason="capacity")
|
|
166
|
+
return entry(item)
|
|
167
|
+
|
|
168
|
+
def recall(self, query=None, k=5, kind=None, near=None, radius=None, space=None, *, library=(), record=None) -> list[dict]:
|
|
169
|
+
"""Entries of `kind` (a name or a family), in `space` when given: nearest to `near`
|
|
170
|
+
first (with "distance"; within `radius`), then, without a radius, those that have
|
|
171
|
+
no position, newest first; else best for `query` (with "score"), else newest
|
|
172
|
+
first; at most k (0: all)."""
|
|
173
|
+
near = _position(near)
|
|
174
|
+
found, placeless = [], []
|
|
175
|
+
with self._lock:
|
|
176
|
+
self._expire(self.clock() - self.start, record)
|
|
177
|
+
items = {item["id"]: item for item in library}
|
|
178
|
+
for ident, item in self.items.items():
|
|
179
|
+
if self._in_space(item, space):
|
|
180
|
+
stored = items.get(ident)
|
|
181
|
+
items[ident] = {**item, "scope": "library", "evidence": stored["evidence"]} if stored else dict(item)
|
|
182
|
+
items = list(items.values())
|
|
183
|
+
for item in items:
|
|
184
|
+
if kind is not None and item["kind"] != kind and family(item["kind"]) != kind:
|
|
185
|
+
if item["kind"] != "memory" or not _score(kind, item["name"], item.get("summary") or ""):
|
|
186
|
+
continue
|
|
187
|
+
if not self._in_space(item, space):
|
|
188
|
+
continue
|
|
189
|
+
shown = entry(item, item.get("scope", "run"))
|
|
190
|
+
if query:
|
|
191
|
+
shown["score"] = _score(query, item["kind"], item["name"] or "", item["text"],
|
|
192
|
+
item["where"] if isinstance(item["where"], str) else "", item.get("summary") or "")
|
|
193
|
+
if not shown["score"]:
|
|
194
|
+
continue
|
|
195
|
+
if near is not None:
|
|
196
|
+
position = _position(item["where"]) if not isinstance(item["where"], str) else None
|
|
197
|
+
if position is None or len(position) != len(near):
|
|
198
|
+
if radius is None:
|
|
199
|
+
placeless.append(shown)
|
|
200
|
+
continue
|
|
201
|
+
shown["distance"] = round(math.dist(position, near), 1)
|
|
202
|
+
if radius is not None and shown["distance"] > float(radius):
|
|
203
|
+
continue
|
|
204
|
+
found.append(shown)
|
|
205
|
+
if near is not None:
|
|
206
|
+
found.sort(key=lambda e: (e["distance"], -(e["last"] or 0)))
|
|
207
|
+
found += sorted(placeless, key=lambda e: -(e["last"] or 0))
|
|
208
|
+
elif query:
|
|
209
|
+
found.sort(key=lambda e: (-e["score"], -(e["last"] or 0)))
|
|
210
|
+
else:
|
|
211
|
+
found.sort(key=lambda e: -(e["last"] or 0))
|
|
212
|
+
return found[:int(k)] if k else found
|
|
213
|
+
|
|
214
|
+
@staticmethod
|
|
215
|
+
def _in_space(item, space):
|
|
216
|
+
if space is None or item.get("space") is None:
|
|
217
|
+
return True
|
|
218
|
+
own = tuple(item["space"]) if isinstance(item["space"], list) else item["space"]
|
|
219
|
+
if item.get("where") is None and isinstance(space, tuple) and isinstance(own, tuple):
|
|
220
|
+
return own[0] == space[0]
|
|
221
|
+
return own == space
|
|
222
|
+
|
|
223
|
+
def _drop(self, ident, record, **detail):
|
|
224
|
+
item = self.items.pop(ident, None)
|
|
225
|
+
if item is not None:
|
|
226
|
+
self.version += 1
|
|
227
|
+
self._expires.pop(ident, None)
|
|
228
|
+
if "slot" in item:
|
|
229
|
+
self._slots.pop((item["space"], item["slot"]), None)
|
|
230
|
+
self._changes.append((self.version, item["space"], item["slot"], None))
|
|
231
|
+
if record is not None:
|
|
232
|
+
record(action="forget", id=ident, kind=item["kind"], **detail)
|
|
233
|
+
return item is not None
|
|
234
|
+
|
|
235
|
+
def _expire(self, now, record):
|
|
236
|
+
for ident, expiry in list(self._expires.items()):
|
|
237
|
+
if expiry <= now:
|
|
238
|
+
self._drop(ident, record, reason="expired")
|
|
239
|
+
|
|
240
|
+
def forget(self, ident, record=None, *, space=None) -> bool:
|
|
241
|
+
"""Drop a visible working entry by its ID."""
|
|
242
|
+
with self._lock:
|
|
243
|
+
ident = int(ident) if str(ident).isdigit() else ident
|
|
244
|
+
item = self.items.get(ident)
|
|
245
|
+
return bool(item is not None and self._in_space(item, space) and self._drop(ident, record))
|
|
246
|
+
|
|
247
|
+
def summary(self, near=None, space=None, limit=8, sure=SURE) -> str:
|
|
248
|
+
"""A few lines for the model after each program: the notes without a position (the
|
|
249
|
+
newest first, however old), then the places nearest to `near` (else the newest)
|
|
250
|
+
still fresh and at least `sure` confident, where they are and how long ago; at most
|
|
251
|
+
`limit` in all."""
|
|
252
|
+
now = self.clock() - self.start
|
|
253
|
+
near = _position(near)
|
|
254
|
+
entries = self.recall(k=0, space=space)
|
|
255
|
+
notes = [item for item in entries if item["where"] is None]
|
|
256
|
+
places = [item for item in entries if item["where"] is not None and item["confidence"] >= sure
|
|
257
|
+
and now - item["last"] <= self.kinds.get(item["kind"], Kind(item["kind"])).fresh]
|
|
258
|
+
if near is not None:
|
|
259
|
+
def distance(item):
|
|
260
|
+
position = _position(item["where"]) if not isinstance(item["where"], str) else None
|
|
261
|
+
return math.dist(position, near) if position is not None and len(position) == len(near) else math.inf
|
|
262
|
+
places.sort(key=distance)
|
|
263
|
+
leading = notes[:max(1, limit // 2)] if places and limit else notes[:limit]
|
|
264
|
+
lines = []
|
|
265
|
+
for item in leading + places[:max(0, limit - len(leading))]:
|
|
266
|
+
what = item["kind"] + (f" {item['name']}" if item["name"] else "") + (f" ({_clip(item['text'])})" if item["text"] else "")
|
|
267
|
+
where = self._where(item, near)
|
|
268
|
+
lines.append(f"- {what}{' ' + where if where else ''}, seen {_ago(now - item['last'])} ago"
|
|
269
|
+
f"{' x%d' % item['seen'] if item['seen'] > 1 else ''} [#{item['id']}, {item['source']}]")
|
|
270
|
+
more = len(notes) + len(places) - len(lines)
|
|
271
|
+
if more > 0:
|
|
272
|
+
lines.append(f"- and {more} more (recall())")
|
|
273
|
+
return "\n".join(lines)
|
|
274
|
+
|
|
275
|
+
# -- the host's side of the skill ------------------------------------------------------
|
|
276
|
+
|
|
277
|
+
def handle(self, request: dict, *, record=None, source="main", space=None, library=None, persist=None):
|
|
278
|
+
"""A program's request (skills/memory): remember, recall (this run's entries and the
|
|
279
|
+
library's as the run holds them), forget, summary. An entry's kind and id may come
|
|
280
|
+
as "of" and "entry" (a kernel note's own fields are "kind" and "id"). `space`: the
|
|
281
|
+
writer's own, when it works in a world of its own (a sub-agent's workspace)."""
|
|
282
|
+
request = {{"of": "kind", "entry": "id"}.get(key, key): value for key, value in request.items()}
|
|
283
|
+
record = record or (lambda **fields: None)
|
|
284
|
+
action = request.get("action")
|
|
285
|
+
requested_space = request.get("space")
|
|
286
|
+
if space is not None:
|
|
287
|
+
requested_space = (space, requested_space)
|
|
288
|
+
holdings = self.library if library is None else library
|
|
289
|
+
if action == "remember":
|
|
290
|
+
if request.get("keep") and persist is None:
|
|
291
|
+
raise ValueError("this run cannot keep memory in the library")
|
|
292
|
+
existing = next((item for item in holdings if request.get("keep") and request.get("name") is not None
|
|
293
|
+
and item["name"] == request["name"] and item["kind"] == request["kind"]
|
|
294
|
+
and item["where"] == request.get("where") and self._in_space(item, requested_space)), None)
|
|
295
|
+
found = self.remember(request["kind"], request.get("text", ""), request.get("where"), request.get("name"),
|
|
296
|
+
request.get("confidence", 0.5), request.get("source") or source,
|
|
297
|
+
requested_space, record, ident=existing["id"] if existing else None)
|
|
298
|
+
return persist(found) if request.get("keep") else found
|
|
299
|
+
if action == "observe":
|
|
300
|
+
with self._lock:
|
|
301
|
+
frame = request.get("frame")
|
|
302
|
+
stream = (space, request.get("stream"))
|
|
303
|
+
if frame is not None:
|
|
304
|
+
if frame <= self._frames.get(stream, -1):
|
|
305
|
+
return self.version
|
|
306
|
+
self._frames[stream] = frame
|
|
307
|
+
for observation in request["observations"]:
|
|
308
|
+
if observation.get("kind") is None:
|
|
309
|
+
ident = self._slots.get((requested_space, observation["slot"]))
|
|
310
|
+
if ident is not None:
|
|
311
|
+
self._drop(ident, record)
|
|
312
|
+
else:
|
|
313
|
+
self.remember(observation["kind"], where=observation["where"], space=requested_space,
|
|
314
|
+
confidence=observation.get("confidence", 1), source=request.get("source") or source,
|
|
315
|
+
record=record, slot=observation.get("slot"), ttl=observation.get("ttl"),
|
|
316
|
+
stale_after=observation.get("stale_after"))
|
|
317
|
+
overflow = len(self._slots) + len(self._expires) - self.observation_limit
|
|
318
|
+
if overflow > 0:
|
|
319
|
+
observed = (item for item in self.items.values() if "slot" in item or item.get("tracked"))
|
|
320
|
+
oldest = sorted(observed, key=lambda item: (item["last"], item["confidence"]))
|
|
321
|
+
for item in oldest[:overflow + self.observation_limit // 20]:
|
|
322
|
+
self._drop(item["id"], record, reason="capacity")
|
|
323
|
+
return self.version
|
|
324
|
+
if action in ("recall", "observations"):
|
|
325
|
+
if request.get("radius") is not None and request.get("near") is None:
|
|
326
|
+
raise ValueError("recall() needs a position for a radius: give near or use a worker that reports here")
|
|
327
|
+
if action == "observations":
|
|
328
|
+
with self._lock:
|
|
329
|
+
self._expire(self.clock() - self.start, record)
|
|
330
|
+
version = request.get("version")
|
|
331
|
+
if request.get("cells") and version is not None and self._changes and version >= self._changes[0][0]:
|
|
332
|
+
changed = {slot: ident for changed_at, own_space, slot, ident in self._changes
|
|
333
|
+
if changed_at > version and own_space == requested_space}
|
|
334
|
+
return {"version": self.version, "delta": True,
|
|
335
|
+
"entries": [entry(self.items[ident]) for ident in changed.values() if ident is not None],
|
|
336
|
+
"removed": [slot for slot, ident in changed.items() if ident is None]}
|
|
337
|
+
return {"version": self.version, "entries": (
|
|
338
|
+
[entry(item) for item in self.items.values()
|
|
339
|
+
if ("slot" in item or item.get("tracked") and not request.get("cells"))
|
|
340
|
+
and self._in_space(item, requested_space)]
|
|
341
|
+
if version != self.version else None)}
|
|
342
|
+
k = int(request.get("k", 5))
|
|
343
|
+
found = self.recall(request.get("query"), k, request.get("kind"), request.get("near"),
|
|
344
|
+
request.get("radius"), requested_space, library=holdings, record=record)
|
|
345
|
+
record(action="recall", **{key: request[key] for key in ("query", "kind", "near", "radius")
|
|
346
|
+
if request.get(key) is not None}, found=[item["id"] for item in found],
|
|
347
|
+
results=found, k=k, space=requested_space)
|
|
348
|
+
return found
|
|
349
|
+
if action == "forget":
|
|
350
|
+
ident = request["id"]
|
|
351
|
+
kept = next((item for item in holdings if item["id"] == ident and self._in_space(item, requested_space)), None)
|
|
352
|
+
if kept is not None:
|
|
353
|
+
if persist is None:
|
|
354
|
+
raise ValueError("this run cannot forget memory in the library")
|
|
355
|
+
persist(kept, forgotten=True)
|
|
356
|
+
return self.forget(ident, record, space=requested_space) or kept is not None
|
|
357
|
+
if action == "summary":
|
|
358
|
+
return self.summary(request.get("near"), requested_space, int(request.get("limit", 8)))
|
|
359
|
+
raise ValueError(f"memory: unknown request {action!r}")
|
|
360
|
+
|
|
361
|
+
def kept(self, item):
|
|
362
|
+
"""Keep an admitted entry in the standalone kernel's memory."""
|
|
363
|
+
with self._lock:
|
|
364
|
+
self.library[:] = [old for old in self.library if old["id"] != item["id"]] + [item]
|
|
365
|
+
|
|
366
|
+
# -- inside ----------------------------------------------------------------------------
|
|
367
|
+
|
|
368
|
+
def _same(self, kind, position, where, name, text, space):
|
|
369
|
+
best, nearest = None, self.kinds.get(kind, Kind(kind)).merge
|
|
370
|
+
for item in self.items.values():
|
|
371
|
+
if "slot" in item or item["kind"] != kind or item["space"] != space:
|
|
372
|
+
continue
|
|
373
|
+
if position is not None:
|
|
374
|
+
mine = _position(item["where"]) if not isinstance(item["where"], str) else None
|
|
375
|
+
if mine is not None and len(mine) == len(position) and math.dist(mine, position) <= nearest:
|
|
376
|
+
best, nearest = item, math.dist(mine, position)
|
|
377
|
+
elif where is not None:
|
|
378
|
+
if item["where"] == where and (name is None or item["name"] == name):
|
|
379
|
+
return item
|
|
380
|
+
elif item["where"] is None and (item["name"] == name if name is not None else item["text"] == text):
|
|
381
|
+
return item
|
|
382
|
+
return best
|
|
383
|
+
|
|
384
|
+
@staticmethod
|
|
385
|
+
def _fields(item) -> dict:
|
|
386
|
+
"""A change as its `world` record says it (enough to rebuild the entry, from_records()):
|
|
387
|
+
the writer as `by`, since a record's `source` is where it comes from."""
|
|
388
|
+
return {{"source": "by"}.get(key, key): list(value) if key == "where" and isinstance(value, tuple) else value
|
|
389
|
+
for key, value in item.items() if key not in ("recorded", "first", "last") and value is not None}
|
|
390
|
+
|
|
391
|
+
def _where(self, item, near):
|
|
392
|
+
where = item["where"]
|
|
393
|
+
if where is None:
|
|
394
|
+
return ""
|
|
395
|
+
if isinstance(where, str):
|
|
396
|
+
return f"at {where}"
|
|
397
|
+
if near is None or len(where) != len(near) or len(where) != 3:
|
|
398
|
+
return "at " + " ".join(f"{v:.0f}" for v in where)
|
|
399
|
+
delta = [a - b for a, b in zip(where, near)]
|
|
400
|
+
dy = delta.pop(self.up)
|
|
401
|
+
(da, db), direction = delta, ""
|
|
402
|
+
if self.compass:
|
|
403
|
+
yaw = math.degrees(math.atan2(-da, db))
|
|
404
|
+
step = 360.0 / len(self.compass)
|
|
405
|
+
direction = " " + self.compass[int(((yaw + step / 2) % 360) // step)]
|
|
406
|
+
height = f", {abs(dy):.0f} {'up' if dy > 0 else 'down'}" if abs(dy) >= 2 else ""
|
|
407
|
+
return f"{math.hypot(da, db):.0f} away{direction}{height}"
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
def _clip(text, chars=SUMMARY_CHARS):
|
|
411
|
+
text = " ".join(str(text).split())
|
|
412
|
+
return text if len(text) <= chars else text[:chars - 3] + "..."
|
|
413
|
+
|
|
414
|
+
|
|
415
|
+
def _ago(seconds):
|
|
416
|
+
if seconds < 90:
|
|
417
|
+
return f"{seconds:.0f} s"
|
|
418
|
+
if seconds < 5400:
|
|
419
|
+
return f"{seconds / 60:.0f} min"
|
|
420
|
+
return f"{seconds / 3600:.1f} h"
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def entry(item: dict, scope="run") -> dict:
|
|
424
|
+
"""An entry in the one format (see the module docstring)."""
|
|
425
|
+
where = item.get("where")
|
|
426
|
+
return {"id": item["id"], "scope": scope, "kind": item["kind"], "name": item.get("name"), "text": item.get("text", ""),
|
|
427
|
+
"where": list(where) if isinstance(where, tuple) else where, "space": item.get("space"),
|
|
428
|
+
"evidence": item.get("evidence", SEEN), "confidence": item.get("confidence"), "source": item.get("source"),
|
|
429
|
+
"seen": item.get("seen"), "first": item.get("first"), "last": item.get("last"), "version": item.get("version"),
|
|
430
|
+
"summary": item.get("summary"), "history": item.get("history"), "rate": item.get("rate"),
|
|
431
|
+
**({"slot": item["slot"]} if "slot" in item else {})}
|