`gj FdZddlZddlZddlZddlZ ddlZdZeje Z dejzZ ddZdded edd fd ZddZd dZd!dZd d d d defdZdded edd fdZddedeed edd fdZdd defdZdedd fdZd ededefdZy#e$rdZYwxYw)"uHolographic Reduced Representations (HRR) with phase encoding. HRRs are a vector symbolic architecture for encoding compositional structure into fixed-width distributed representations. This module uses *phase vectors*: each concept is a vector of angles in [0, 2π). The algebraic operations are: bind — circular convolution (phase addition) — associates two concepts unbind — circular correlation (phase subtraction) — retrieves a bound value bundle — superposition (circular mean) — merges multiple concepts Phase encoding is numerically stable, avoids the magnitude collapse of traditional complex-number HRRs, and maps cleanly to cosine similarity. Atoms are generated deterministically from SHA-256 so representations are identical across processes, machines, and language versions. References: Plate (1995) — Holographic Reduced Representations Gayler (2004) — Vector Symbolic Architectures answer Jackendoff's challenges NTF@returnc&ts tdy)Nz,numpy is required for holographic operations) _HAS_NUMPY RuntimeErrorY/root/.hermes/venv/lib/python3.12/site-packages/plugins/memory/holographic/holographic.py_require_numpyr &s IJJ r worddim np.ndarrayctd}tj||z }g}t|D]]}t j |d|j j}|jtjd|_tj|d|tjtdz z}|S)uDeterministic phase vector via SHA-256 counter blocks. Uses hashlib (not numpy RNG) for cross-platform reproducibility. Algorithm: - Generate enough SHA-256 blocks by hashing f"{word}:{i}" for i=0,1,2,... - Concatenate digests, interpret as uint16 values via struct.unpack - Scale to [0, 2π): phases = values * (2π / 65536) - Truncate to dim elements - Returns np.float64 array of shape (dim,) :z<16HNdtypeg@)r mathceilrangehashlibsha256encodedigestextendstructunpacknparrayfloat64_TWO_PI)r r values_per_block blocks_needed uint16_valuesirphasess r encode_atomr'+sIIc$445M!M = !<4&! 4 4 67>>@V]]66:;<XXmDS) <'@Q RF Mr abc.t||ztzS)zCircular convolution = element-wise phase addition. Binding associates two concepts into a single composite vector. The result is dissimilar to both inputs (quasi-orthogonal). r r!r(r)s r bindr-Fs  EW r c.t||z tzS)uCircular correlation = element-wise phase subtraction. Unbinding retrieves the value associated with a key from a memory vector. unbind(bind(a, b), a) ≈ b (up to superposition noise) r+)memorykeys r unbindr1Ps  SLG ##r c ttj|Dcgc]}tjd|zc}d}tj|t zScc}w)zSuperposition via circular mean of complex exponentials. Bundling merges multiple vectors into one that is similar to each input. The result can hold O(sqrt(dim)) items before similarity degrades. y?r)axis)r rsumexpangler!)vectorsv complex_sums r bundler:ZsJ &&':Q"&&a.:CK 88K 7 **;sA"c~tttjtj||z S)zPhase cosine similarity. Range [-1, 1]. Returns 1.0 for identical vectors, near 0.0 for random (unrelated) vectors, and -1.0 for perfectly anti-correlated vectors. )r floatrmeancosr,s r similarityr?es*  A' ((r textc*t|jjDcgc]}|jd}}|Dcgc]}|s| }}|s t d|S|Dcgc]}t ||}}t |Scc}wcc}wcc}w)a7Bag-of-words: bundle of atom vectors for each token. Tokenizes by lowercasing, splitting on whitespace, and stripping leading/trailing punctuation from each token. Returns bundle of all token atom vectors. If text is empty or produces no tokens, returns encode_atom("__hrr_empty__", dim). z.,!?;:"'()[]{} __hrr_empty__)r lowersplitstripr'r:)r@r tokentokenst atom_vectorss r encode_textrJosZZ\'')   %&F %A1a %F % ?C009?@Ks+@L@ <  & AsB B B )Bcontententitiesc ttd|}td|}tt|||g}|D]5}|j tt|j ||7t |S)uStructured encoding: content bound to ROLE_CONTENT, each entity bound to ROLE_ENTITY, all bundled. Role vectors are reserved atoms: "__hrr_role_content__", "__hrr_role_entity__" Components: 1. bind(encode_text(content, dim), encode_atom("__hrr_role_content__", dim)) 2. For each entity: bind(encode_atom(entity.lower(), dim), encode_atom("__hrr_role_entity__", dim)) 3. bundle all components together This enables algebraic extraction: unbind(fact, bind(entity, ROLE_ENTITY)) ≈ content_vector __hrr_role_content____hrr_role_entity__)r r'r-rJappendrCr:)rKrLr role_content role_entity componentsentitys r encode_factrUs5s;L3S9K [# & 5$JO${6<<>3?MNO : r r&c6t|jS)uFSerialize phase vector to bytes. float64 tobytes — 8 KB at dim=1024.)r tobytes)r&s r phases_to_bytesrXs >> r datac|ttj|tjj S)zDeserialize bytes back to phase vector. Inverse of phases_to_bytes. The .copy() call is required because frombuffer returns a read-only view backed by the bytes object; callers expect a mutable array. r)r r frombufferr copy)rYs r bytes_to_phasesr]s(  ==RZZ 0 5 5 77r n_itemsct|dkr tdStj||z }|dkrtj d||||S)aSignal-to-noise ratio estimate for holographic storage. SNR = sqrt(dim / n_items) when n_items > 0, else inf. The SNR falls below 2.0 when n_items > dim / 4, meaning retrieval errors become likely. Logs a warning when this threshold is crossed. rinfrzHRR storage near capacity: SNR=%.2f (dim=%d, n_items=%d). Retrieval accuracy may degrade. Consider increasing dim or reducing stored items.)r r<rsqrtloggerwarning)r r^snrs r snr_estimateresV!|U| ))C'M "C Sy `      Jr )rN)i)r(rr)rrr)r/rr0rrr)r7rrr)__doc__rloggingrrnumpyrr ImportError getLogger__name__rbpir!r strintr'r-r1r:r<r?rJlistrUbytesrXr]rerr r rqs%* J   8 $ -K c|6$+),)<)E)!c!!|!0S |8LU 8%8L8cCEkJsBB B