@lmmslab/harness 0.0.0-stage → 0.81.1

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.
Files changed (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1356 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +232 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. 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,7 @@
1
+ """One bounded task, its context, budget and child executions."""
2
+
3
+ def __getattr__(name):
4
+ if name == "TaskRun":
5
+ from .run import TaskRun
6
+ return TaskRun
7
+ raise AttributeError(name)
@@ -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 {})}