File size: 16,389 Bytes
ad474c9
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
"""Agentic MCP tools held *inside* HDC storage.

A tool is a record, not a row in a database:

    record = bundle([
        bind(role("name"),  hvc("tool/hdc.bind")),
        bind(role("cap"),   capability_vector("hdc/bind/construct")),
        bind(role("arity"), hvc("arity/2")),
    ])

The record is written to storage as the cell ``toolreg/<name>``.  Registration,
discovery and dispatch therefore all run on the same content-addressable
machinery as programs and data: a tool is found by *resembling* the query.

Dispatch has three tiers, each reporting its confidence:

1. exact name — confidence 1.0;
2. character-superposition similarity, so a misspelled or truncated tool name
   (``hdc.bundl``) still finds ``hdc.bundle`` rather than failing;
3. capability path similarity, so ``hdc.memory.search`` reaches
   ``hdc.recall`` because both carry ``hdc`` + ``memory`` atoms.

Tier 2 uses the standard HDC string codec: each character becomes an atom and
its position is bound in by permutation, so two strings that match in most
positions have highly similar vectors.  That is what makes fuzzy dispatch a
cleanup operation instead of an edit-distance algorithm.

The registry is what the ``TOOL`` instruction calls, and what
:mod:`hdc.mcp_server` advertises to an outside agent, so a program running
inside HDC and an MCP client reach the same tools by the same path.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Callable, Sequence

from .hypervec import (
    DEFAULT_DIM,
    bind,
    bundle,
    hvc,
    hv_to_int,
    int_to_hv,
    permute,
    popcount,
    sim,
)
from .memory import HDCStorage

#: Minimum fuzzy similarity accepted for a non-exact tool name.
FUZZY_FLOOR = 0.55
#: Fuzzy matches must beat the runner-up by this much to be trusted.
FUZZY_MARGIN = 0.04

_CAP_CACHE: dict[tuple[str, int], int] = {}
_STR_CACHE: dict[tuple[str, int], int] = {}


def capability_vector(capability: str, d: int = DEFAULT_DIM) -> int:
    """Superpose the path atoms of a capability (``hdc/bind/construct``)."""
    key = (capability, d)
    hit = _CAP_CACHE.get(key)
    if hit is not None:
        return hit
    atoms = [hvc("cap/" + part, d) for part in capability.replace(".", "/").split("/") if part]
    vec = bundle(atoms, d) if atoms else hvc("cap/unknown", d)
    _CAP_CACHE[key] = vec
    return vec


def string_vector(text: str, d: int = DEFAULT_DIM) -> int:
    """Character-superposition codec: order-sensitive, near-orthogonal, fuzzy.

    Each character is bound to its position by permutation and the results are
    bundled, so ``sim(string_vector("hdc.bundle"), string_vector("hdc.bundl"))``
    is high while unrelated strings stay near the noise floor.
    """
    key = (text, d)
    hit = _STR_CACHE.get(key)
    if hit is not None:
        return hit
    if not text:
        vec = 0
    else:
        vec = bundle(
            [permute(hvc("char/" + ch, d), i, d) for i, ch in enumerate(text)], d
        )
    _STR_CACHE[key] = vec
    return vec


def _json_type(kind: str) -> str:
    return "integer" if kind in ("int", "hv") else "string"


@dataclass
class ToolSpec:
    """One agentic tool.

    ``returns`` matters because a hypervector and a scalar are both Python
    ``int``s: the machine has to know whether to *encode* a result (scalar) or
    store it as a vector in its own right.  Without this the two are
    indistinguishable at the call site.
    """

    name: str
    capability: str
    params: tuple[tuple[str, str], ...]
    doc: str
    fn: Callable[..., object]
    returns: str = "int"
    calls: int = 0

    @property
    def kinds(self) -> tuple[str, ...]:
        return tuple(kind for _, kind in self.params)

    def record(self, d: int) -> int:
        """The hypervector record that represents this tool in storage."""
        parts = [
            bind(self._role("name", d), hvc("tool/" + self.name, d), d),
            bind(self._role("cap", d), capability_vector(self.capability, d), d),
            bind(self._role("arity", d), hvc("arity/%d" % len(self.params), d), d),
        ]
        return bundle(parts, d)

    @staticmethod
    def _role(name: str, d: int) -> int:
        from .hypervec import role

        return role(name, d)

    def input_schema(self) -> dict:
        """MCP ``inputSchema`` built from the declared parameter kinds."""
        props = {}
        for pname, kind in self.params:
            props[pname] = {
                "type": _json_type(kind),
                "description": (
                    "hypervector: pass the integer, or a hex string like 0x1f3a"
                    if kind == "hv"
                    else "scalar integer"
                ),
            }
        return {
            "type": "object",
            "properties": props,
            "required": [pname for pname, _ in self.params],
            "additionalProperties": False,
        }


class ToolRegistry:
    """Tool records in HDC storage, plus the dispatcher that reads them."""

    def __init__(self, storage: HDCStorage | None = None, d: int = DEFAULT_DIM):
        self.d = d
        self.storage = storage if storage is not None else HDCStorage(d=d, label="tools")
        self.specs: dict[str, ToolSpec] = {}
        self._records: dict[str, int] = {}
        self.last_machine = None
        self.install_builtins()

    # ---------------------------------------------------------- registration
    def register(
        self,
        name: str,
        capability: str,
        params: Sequence[tuple[str, str]],
        doc: str,
        fn: Callable[..., object],
        returns: str = "int",
        store: bool = True,
    ) -> ToolSpec:
        """Add a tool and write its record into HDC storage."""
        spec = ToolSpec(name, capability, tuple(params), doc, fn, returns=returns)
        self.specs[name] = spec
        rec = spec.record(self.d)
        self._records[name] = rec
        if store:
            self.storage.write("toolreg/" + name, rec, symbol=True)
        return spec

    def unregister(self, name: str) -> None:
        self.specs.pop(name, None)
        self._records.pop(name, None)
        if "toolreg/" + name in self.storage:
            self.storage.cells.pop("toolreg/" + name, None)
            self.storage.order.remove("toolreg/" + name)

    # -------------------------------------------------------------- lookup
    def get(self, name: str) -> ToolSpec | None:
        return self.specs.get(name)

    def params_for(self, name: str) -> tuple[str, ...]:
        spec, _ = self.resolve(name)
        if spec is None:
            raise ToolError("unknown tool: %r" % (name,))
        return spec.kinds

    def returns_for(self, name: str) -> str:
        spec, _ = self.resolve(name)
        if spec is None:
            raise ToolError("unknown tool: %r" % (name,))
        return spec.returns

    def resolve(self, query: str | int) -> tuple[ToolSpec | None, float]:
        """Find a tool by name, by fuzzy name, or by capability resemblance."""
        if isinstance(query, int):
            best_name, best = "", -2.0
            for name, rec in self._records.items():
                s = sim(rec, query, self.d)
                if s > best:
                    best_name, best = name, s
            return (self.specs.get(best_name), best) if best >= 0.3 else (None, best)

        if query in self.specs:
            return self.specs[query], 1.0

        probe = string_vector(query, self.d)
        scored = sorted(
            ((name, sim(probe, string_vector(name, self.d), self.d)) for name in self.specs),
            key=lambda t: t[1],
            reverse=True,
        )
        if scored and scored[0][1] >= FUZZY_FLOOR:
            margin = scored[0][1] - (scored[1][1] if len(scored) > 1 else 0.0)
            if margin >= FUZZY_MARGIN or len(scored) == 1:
                return self.specs[scored[0][0]], scored[0][1]

        cap_probe = capability_vector(query, self.d)
        scored = sorted(
            (
                (name, sim(cap_probe, capability_vector(s.capability, self.d), self.d))
                for name, s in self.specs.items()
            ),
            key=lambda t: t[1],
            reverse=True,
        )
        if scored and scored[0][1] >= 0.30:
            return self.specs[scored[0][0]], scored[0][1]
        return None, (scored[0][1] if scored else 0.0)

    # --------------------------------------------------------------- calling
    def call(self, name: str, args: Sequence[object], machine=None) -> object:
        """Invoke a tool.  Raises ``ToolError`` for an unresolvable tool."""
        spec, confidence = self.resolve(name)
        if spec is None:
            raise ToolError(
                "no tool resembling %r (best similarity %.3f)" % (name, confidence)
            )
        if len(args) != len(spec.params):
            raise ToolError(
                "tool %s takes %d argument(s), got %d"
                % (spec.name, len(spec.params), len(args))
            )
        self.last_machine = machine
        spec.calls += 1
        return spec.fn(*args)

    def call_named(self, name: str, arguments: dict, machine=None) -> object:
        """Invoke a tool with named arguments (the MCP calling convention)."""
        spec, confidence = self.resolve(name)
        if spec is None:
            raise ToolError("unknown tool %r (%.3f)" % (name, confidence))
        args = []
        for pname, kind in spec.params:
            if pname not in arguments:
                raise ToolError("missing argument %r for %s" % (pname, spec.name))
            value = arguments[pname]
            if kind in ("int", "hv") and isinstance(value, str):
                value = int(value, 0)
            if kind == "int":
                value = int(value)
            elif kind == "hv":
                value = int(value)
            args.append(value)
        return self.call(spec.name, args, machine=machine)

    # ---------------------------------------------------------------- views
    def list_tools(self) -> list[dict]:
        """MCP ``tools/list`` payload."""
        out = []
        for name in sorted(self.specs):
            spec = self.specs[name]
            out.append(
                {
                    "name": spec.name,
                    "description": spec.doc,
                    "inputSchema": spec.input_schema(),
                    "annotations": {"hdc_capability": spec.capability},
                }
            )
        return out

    def specs_text(self) -> str:
        rows = ["%-16s %-26s %-5s %s" % ("TOOL", "CAPABILITY", "ARGS", "DESCRIPTION")]
        rows.append("-" * 96)
        for name in sorted(self.specs):
            s = self.specs[name]
            rows.append(
                "%-16s %-26s %-5d %s"
                % (s.name, s.capability, len(s.params), s.doc)
            )
        return "\n".join(rows)

    def memory_report(self) -> str:
        """Show the tool records as they sit in storage."""
        rows = ["tool records in %r (d=%d)" % (self.storage.label, self.d)]
        for name in sorted(self.specs):
            cell = "toolreg/" + name
            present = cell in self.storage
            hv = self.storage.read(cell, default=0)
            rows.append(
                "  %-16s cell=%-18s pop=%-5d %s"
                % (name, cell, popcount(hv), "stored" if present else "MISSING")
            )
        return "\n".join(rows)

    # ------------------------------------------------------------- builtins
    def install_builtins(self) -> None:
        """Register the built-in HDC / bit-logic / BitNet tools."""
        d = self.d
        store = self.storage

        def hdc_similarity(a: int, b: int) -> int:
            return int(round(sim(a, b, d) * 1000))

        def hdc_bind(a: int, b: int) -> int:
            return bind(a, b, d)

        def hdc_bundle(a: int, b: int) -> int:
            return bundle([a, b], d)

        def hdc_permute(v: int, k: int) -> int:
            return permute(v, k, d)

        def hdc_cleanup(v: int) -> int:
            hits = store.nearest_symbol(v, k=1)
            if not hits:
                return -1
            syms = store.symbols()
            return syms.index(hits[0][0]) if hits[0][0] in syms else -1

        def hdc_recall(v: int, k: int) -> int:
            hits = store.recall(v, k=max(1, k))
            if not hits:
                return -1
            return store.order.index(hits[0][0]) if hits[0][0] in store.order else -1

        def hdc_encode_int(n: int) -> int:
            return int_to_hv(n, d)

        def hdc_decode_int(v: int) -> int:
            return hv_to_int(v, d)

        def bit_popcount(v: int) -> int:
            return popcount(v)

        def bit_hamming(a: int, b: int) -> int:
            return (a ^ b).bit_count()

        def net_dot1bit(a: int, b: int) -> int:
            # A 1-bit dot product is bind-then-count: agree - disagree.
            return d - 2 * (a ^ b).bit_count()

        def mem_stat() -> int:
            return int(store.stat()["cells_used"])

        # HDC-native arithmetic, exposed to agents: a ripple-carry circuit over
        # bit atoms rather than a decode-and-add.
        from .adder import HyperAdder

        adder = HyperAdder(d=d)

        def hdc_add(a: int, b: int) -> int:
            return adder.add_hv(a, b)

        def hdc_sub(a: int, b: int) -> int:
            return adder.sub_hv(a, b)

        def agent_echo(n: int) -> int:
            return int(n)

        self.register("hdc.similarity", "hdc/bind/similarity", (("a", "hv"), ("b", "hv")),
                      "Similarity of two hypervectors, scaled to milli-units.", hdc_similarity)
        self.register("hdc.bind", "hdc/bind/construct", (("a", "hv"), ("b", "hv")),
                      "XOR-bind two hypervectors.", hdc_bind, returns="hv")
        self.register("hdc.unbind", "hdc/bind/invert", (("a", "hv"), ("b", "hv")),
                      "Unbind: XOR is self-inverse, so this is bind.", hdc_bind, returns="hv")
        self.register("hdc.bundle", "hdc/bundle/construct", (("a", "hv"), ("b", "hv")),
                      "Majority-bundle two hypervectors.", hdc_bundle, returns="hv")
        self.register("hdc.permute", "hdc/order/rotate", (("v", "hv"), ("k", "int")),
                      "Rotate a hypervector by k bits.", hdc_permute, returns="hv")
        self.register("hdc.cleanup", "hdc/memory/cleanup", (("v", "hv"),),
                      "Index of the stored symbol nearest to a hypervector.", hdc_cleanup)
        self.register("hdc.recall", "hdc/memory/search", (("v", "hv"), ("k", "int")),
                      "Index of the stored cell most similar to a hypervector.", hdc_recall)
        self.register("hdc.encode_int", "hdc/codec/encode", (("n", "int"),),
                      "Encode an integer as a hypervector.", hdc_encode_int, returns="hv")
        self.register("hdc.decode_int", "hdc/codec/decode", (("v", "hv"),),
                      "Decode an integer hypervector.", hdc_decode_int)
        self.register("bit.popcount", "bit/logic/count", (("v", "hv"),),
                      "Population count of a hypervector.", bit_popcount)
        self.register("bit.hamming", "bit/logic/distance", (("a", "hv"), ("b", "hv")),
                      "Hamming distance between two hypervectors.", bit_hamming)
        self.register("net.dot1bit", "bitnet/inference/dot", (("a", "hv"), ("b", "hv")),
                      "1-bit dot product as agreement minus disagreement.", net_dot1bit)
        self.register("mem.stat", "storage/memory/stats", (),
                      "Number of occupied HDC cells.", mem_stat)
        self.register("hdc.add", "hdc/arithmetic/add", (("a", "hv"), ("b", "hv")),
                      "Add two integer hypervectors with a ripple-carry HDC circuit.",
                      hdc_add, returns="hv")
        self.register("hdc.sub", "hdc/arithmetic/subtract", (("a", "hv"), ("b", "hv")),
                      "Subtract two integer hypervectors (two's complement, HDC circuit).",
                      hdc_sub, returns="hv")
        self.register("agent.echo", "agent/plumbing/echo", (("n", "int"),),
                      "Return the argument unchanged; useful for wiring tests.", agent_echo)


class ToolError(Exception):
    """A tool could not be resolved or invoked."""