entity-ent 0.1.0__py3-none-any.whl

architecture/categorical_attention.py

@@ -0,0 +1,29 @@
+"""Categorical attention: type-aware attention biases.
+
+Encodes entity-type relationships as additive query+key biases per type.
+O(seq²) memory (one (batch, 1, seq, seq) tensor) but computed via fast
+broadcast add — no gather or outer-product overhead.
+"""
+
+import torch
+import torch.nn as nn
+
+
+class CategoricalAttentionBias(nn.Module):
+    def __init__(self, num_heads: int, num_types: int = 32):
+        super().__init__()
+        self.q_bias = nn.Embedding(num_types, 1)
+        self.k_bias = nn.Embedding(num_types, 1)
+
+    def forward(
+        self,
+        token_types: torch.LongTensor,
+        attention_mask: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        q = self.q_bias(token_types).squeeze(-1)  # (batch, seq)
+        k = self.k_bias(token_types).squeeze(-1)  # (batch, seq)
+        bias = q.unsqueeze(-1) + k.unsqueeze(-2)  # (batch, seq, seq) broadcast-add
+        bias = bias.unsqueeze(1)                   # (batch, 1, seq, seq)
+        if attention_mask is not None:
+            bias = bias.masked_fill(~attention_mask.bool().unsqueeze(1), float("-inf"))
+        return bias

architecture/entity_decoder.py

@@ -0,0 +1,64 @@
+"""baseline — hash-based entity decoder.
+
+Maps compact entity hashes through a learned decoder that jointly predicts
+type, class, and scope — the model discovers categorical structure itself
+rather than relying on hand-crafted semantic token strings.
+
+Contrast with semantic CEIDs (robot.recon.w11.a = 4+ tokens):
+  - Hash-based: single compact ID → learned structured representation
+  - Supports categorical attention by providing type/class/scope predictions
+  - Trainable end-to-end: the decoder IS the functor
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class EntityDecoder(nn.Module):
+    def __init__(
+        self,
+        num_entities: int = 131072,
+        hidden_dim: int = 896,
+        num_types: int = 32,
+        num_classes: int = 64,
+        num_scopes: int = 128,
+    ):
+        super().__init__()
+        self.entity_embed = nn.Embedding(num_entities, hidden_dim)
+        self.type_head = nn.Linear(hidden_dim, num_types)
+        self.class_head = nn.Linear(hidden_dim, num_classes)
+        self.scope_head = nn.Linear(hidden_dim, num_scopes)
+        self.num_types = num_types
+        self.num_classes = num_classes
+        self.num_scopes = num_scopes
+
+    def forward(
+        self, entity_ids: torch.LongTensor
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+        e = self.entity_embed(entity_ids)
+        type_logits = self.type_head(e)
+        class_logits = self.class_head(e)
+        scope_logits = self.scope_head(e)
+        return e, type_logits, class_logits, scope_logits
+
+    def compute_structural_loss(
+        self,
+        type_logits: torch.Tensor,
+        class_logits: torch.Tensor,
+        scope_logits: torch.Tensor,
+        type_labels: torch.LongTensor,
+        class_labels: torch.LongTensor,
+        scope_labels: torch.LongTensor,
+        entity_mask: torch.Tensor,
+    ) -> torch.Tensor:
+        type_loss = F.cross_entropy(
+            type_logits[entity_mask], type_labels[entity_mask]
+        )
+        class_loss = F.cross_entropy(
+            class_logits[entity_mask], class_labels[entity_mask]
+        )
+        scope_loss = F.cross_entropy(
+            scope_logits[entity_mask], scope_labels[entity_mask]
+        )
+        return type_loss + class_loss + scope_loss

architecture/entity_hash.py

@@ -0,0 +1,73 @@
+"""Schema-based entity hash encoding.
+
+17-bit layout (131072 entities):
+  [16:12] type    (5 bits, 0-31)
+  [11:6]  class   (6 bits, 0-63)
+  [5:3]   scope   (3 bits, 0-7)
+  [2]     arity   (1 bit,  low=0 high=1)
+  [1]     role    (1 bit,  caller=0 callee=1)
+  [0]     morphism (1 bit, static=0 dynamic=1)
+"""
+
+import torch
+
+SHIFT_TYPE = 12
+SHIFT_CLASS = 6
+SHIFT_SCOPE = 3
+SHIFT_ARITY = 2
+SHIFT_ROLE = 1
+SHIFT_MORPHISM = 0
+
+MASK_TYPE = 0x1F
+MASK_CLASS = 0x3F
+MASK_SCOPE = 0x7
+MASK_ARITY = 0x1
+MASK_ROLE = 0x1
+MASK_MORPHISM = 0x1
+
+NUM_ENTITIES = 1 << 17
+NUM_TYPES = 1 << 5
+NUM_CLASSES = 1 << 6
+NUM_SCOPES = 1 << 3
+
+
+def encode(
+    type_id: int,
+    class_id: int,
+    scope_id: int,
+    arity: int,
+    role: int,
+    morphism: int,
+) -> int:
+    return (
+        (type_id << SHIFT_TYPE)
+        | (class_id << SHIFT_CLASS)
+        | (scope_id << SHIFT_SCOPE)
+        | (arity << SHIFT_ARITY)
+        | (role << SHIFT_ROLE)
+        | morphism
+    )
+
+
+def get_type(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_TYPE) & MASK_TYPE
+
+
+def get_class(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_CLASS) & MASK_CLASS
+
+
+def get_scope(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_SCOPE) & MASK_SCOPE
+
+
+def get_arity(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_ARITY) & MASK_ARITY
+
+
+def get_role(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_ROLE) & MASK_ROLE
+
+
+def get_morphism(entity_hash: torch.Tensor) -> torch.Tensor:
+    return (entity_hash >> SHIFT_MORPHISM) & MASK_MORPHISM

architecture/murmuration_router.py

@@ -0,0 +1,60 @@
+"""Murmuration router: lightweight functor routing.
+
+Routes tokens to specialized functor modules based on content and
+CEID scope (local interaction rules rather than global learned gating).
+
+Enabled in Phase 3 — disabled during Phase 1 pretraining.
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class MurmurationRouter(nn.Module):
+    def __init__(
+        self,
+        hidden_size: int,
+        routing_dim: int = 512,
+        num_functors: int = 8,
+        top_k: int = 2,
+        num_scopes: int = 8,
+    ):
+        super().__init__()
+        self.hidden_size = hidden_size
+        self.num_functors = num_functors
+        self.top_k = top_k
+        self.gate = nn.Sequential(
+            nn.Linear(hidden_size, routing_dim),
+            nn.SiLU(),
+            nn.Linear(routing_dim, num_functors),
+        )
+        self.scope_bias = nn.Embedding(num_scopes, num_functors)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        scope_ids: torch.LongTensor | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        logits = self.gate(hidden_states)
+        if scope_ids is not None:
+            logits = logits + self.scope_bias(scope_ids)
+        routing_weights = F.softmax(logits, dim=-1)
+        top_k_weights, top_k_indices = torch.topk(routing_weights, self.top_k, dim=-1)
+        top_k_weights = top_k_weights / top_k_weights.sum(dim=-1, keepdim=True)
+        return top_k_weights, top_k_indices
+
+
+class FunctorModule(nn.Module):
+    """A single functor — a small FFN specialized for one morphism class."""
+
+    def __init__(self, hidden_size: int, intermediate_mult: int = 1):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(hidden_size, hidden_size * intermediate_mult),
+            nn.GELU(),
+            nn.Linear(hidden_size * intermediate_mult, hidden_size),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.net(x)

ent/__init__.py

@@ -0,0 +1,65 @@
+"""ent — entity-conditioned language models with category-theoretic reasoning.
+
+Key components:
+  category  — EntityCategory, EntityMorphism, EntityFunctor, Subcategory
+  store     — EntityStore (entity decoder weights, fast lookups)
+  reasoner  — EntityReasoner (symbolic queries over entity graphs)
+  decoder   — EntityConditionedDecoder (small LM for text generation)
+  inference — EntInferenceEngine (abstraction, graph reasoning, working memory, program execution)
+  training  — EntitySmolWrapper (entity-conditioned generation with LoRA)
+  serving   — FastAPI server with OpenAI-compatible /v1/chat/completions
+"""
+
+from ent.core.category import (
+    EntityObject,
+    EntityMorphism,
+    EntityCategory,
+    StructuralMorphism,
+    EmbeddingFunctor,
+    TypeClassifierFunctor,
+    Subcategory,
+)
+from ent.core.store import EntityStore
+from ent.core.reasoner import EntityGraph, EntityReasoner
+from ent.models.decoder import DecoderConfig, EntityConditionedDecoder
+from ent.core.inference import (
+    AbstractionNode,
+    AbstractionEdge,
+    AbstractionGraph,
+    MemoryItem,
+    DurableMemoryRecord,
+    DurableMemoryStore,
+    CandidateAnswer,
+    InferenceState,
+    EntityAbstractionLayer,
+    ProgramExecutor,
+    EntInferenceEngine,
+)
+
+__all__ = [
+    "EntityObject",
+    "EntityMorphism",
+    "EntityCategory",
+    "StructuralMorphism",
+    "EmbeddingFunctor",
+    "TypeClassifierFunctor",
+    "Subcategory",
+    "EntityStore",
+    "EntityGraph",
+    "EntityReasoner",
+    "DecoderConfig",
+    "EntityConditionedDecoder",
+    "AbstractionNode",
+    "AbstractionEdge",
+    "AbstractionGraph",
+    "MemoryItem",
+    "DurableMemoryRecord",
+    "DurableMemoryStore",
+    "CandidateAnswer",
+    "InferenceState",
+    "EntityAbstractionLayer",
+    "ProgramExecutor",
+    "EntInferenceEngine",
+]
+
+__version__ = "0.1.0"

ent/core/__init__.py

@@ -0,0 +1 @@
+"""Core entity reasoning primitives."""

ent/core/category.py

@@ -0,0 +1,405 @@
+"""Category theory foundations for entity reasoning.
+
+The entity hash encodes categorical structure without any neural
+computation. This module formalizes the structure:
+
+  Objects    — EntityObject: a single entity hash (17-bit)
+  Morphisms  — EntityMorphism: a structural relationship between entities,
+               derived from type/class/scope compatibility
+  Category   — EntityCategory: the discrete category of all entities
+  Functors   — Map EntityCategory → other categories (Vect, TypeDist, etc.)
+  Subcategory — Filtered view of the category by structural constraints
+
+All operations are O(1) or O(n) on the CPU — no matrix multiplies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Optional, Iterator
+
+import torch
+
+from architecture.entity_hash import (
+    get_type,
+    get_class,
+    get_scope,
+    get_arity,
+    get_role,
+    get_morphism,
+    encode,
+    NUM_ENTITIES,
+    NUM_TYPES,
+    NUM_CLASSES,
+    NUM_SCOPES,
+    SHIFT_TYPE,
+    SHIFT_CLASS,
+    SHIFT_SCOPE,
+    MASK_TYPE,
+    MASK_CLASS,
+    MASK_SCOPE,
+)
+
+
+@dataclass(frozen=True)
+class EntityObject:
+    """An object in the discrete category of entities.
+
+    Wraps a 17-bit entity hash and exposes its structural fields.
+    Two EntityObjects are equal iff their hashes are equal.
+    """
+
+    hash: int
+
+    @property
+    def type_id(self) -> int:
+        return int(get_type(torch.tensor(self.hash)).item())
+
+    @property
+    def class_id(self) -> int:
+        return int(get_class(torch.tensor(self.hash)).item())
+
+    @property
+    def scope_id(self) -> int:
+        return int(get_scope(torch.tensor(self.hash)).item())
+
+    @property
+    def arity(self) -> int:
+        return int(get_arity(torch.tensor(self.hash)).item())
+
+    @property
+    def role(self) -> int:
+        return int(get_role(torch.tensor(self.hash)).item())
+
+    @property
+    def morphism_bit(self) -> int:
+        return int(get_morphism(torch.tensor(self.hash)).item())
+
+    @property
+    def type_name(self) -> str:
+        names = {
+            0: "empty",
+            1: "number",
+            2: "proper-noun",
+            3: "lowercase-alpha",
+            4: "punctuation",
+            5: "alphanumeric",
+            6: "other",
+        }
+        return names.get(self.type_id, f"type-{self.type_id}")
+
+    def __repr__(self) -> str:
+        return (
+            f"Entity(hash={self.hash}, type={self.type_name}, "
+            f"class={self.class_id}, scope={self.scope_id})"
+        )
+
+
+class EntityMorphism:
+    """A morphism f: A → B between entity objects.
+
+    Morphisms arise from structural relationships:
+      - identity: A → A for every object
+      - scope-expanding: A → B when class(A)=class(B) and scope(A)<scope(B)
+      - type-specializing: A → B when scope(A)=scope(B) and types are compatible
+      - embedding: A → B with an associated vector transformation
+
+    The category is thin: at most one morphism between any two objects.
+    """
+
+    __slots__ = ("_source", "_target", "_kind", "_hash")
+
+    def __init__(
+        self,
+        source: EntityObject,
+        target: EntityObject,
+        kind: str = "structural",
+    ):
+        self._source = source
+        self._target = target
+        self._kind = kind
+        self._hash = hash((source.hash, target.hash, kind))
+
+    @property
+    def source(self) -> EntityObject:
+        return self._source
+
+    @property
+    def target(self) -> EntityObject:
+        return self._target
+
+    @property
+    def kind(self) -> str:
+        return self._kind
+
+    @property
+    def is_identity(self) -> bool:
+        return self._source == self._target and self._kind == "identity"
+
+    @property
+    def is_structural(self) -> bool:
+        return self._kind in ("structural", "scope", "type", "identity")
+
+    def compose(self, other: EntityMorphism) -> Optional[EntityMorphism]:
+        """Compose self: A→B with other: B→C to get other∘self: A→C.
+
+        Composition is defined when self.target == other.source.
+        Returns None if composition is not valid in this category.
+        """
+        if self.target != other.source:
+            return None
+        if self.is_identity:
+            return other
+        if other.is_identity:
+            return self
+        if not self._can_compose_with(other):
+            return None
+        composed_kind = "composed"
+        return EntityMorphism(self.source, other.target, kind=composed_kind)
+
+    def _can_compose_with(self, other: EntityMorphism) -> bool:
+        if self.kind == "embedding" or other.kind == "embedding":
+            return True
+        return (
+            self.source.class_id == other.source.class_id
+            or self.source.scope_id == other.source.scope_id
+            or self.source.type_id == other.source.type_id
+        )
+
+    def __call__(self) -> str:
+        return f"{self.source} → {self.target}"
+
+    def __repr__(self) -> str:
+        return f"Morphism({self.source.hash}→{self.target.hash}, {self.kind})"
+
+    def __hash__(self) -> int:
+        return self._hash
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, EntityMorphism):
+            return False
+        return (
+            self._source == other._source
+            and self._target == other._target
+            and self._kind == other._kind
+        )
+
+
+class EntityCategory:
+    """The discrete category C where:
+      - ob(C) = {0, 1, ..., 2^17 - 1}  (all entity hashes)
+      - hom(A, B) = {f: A→B | structural relationship holds}
+      - id_A = EntityMorphism(A, A, kind="identity")
+      - Composition of structural morphisms respects transitivity
+    """
+
+    def __init__(self) -> None:
+        self._identity_cache: dict[int, EntityMorphism] = {}
+
+    def obj(self, hash_val: int) -> EntityObject:
+        return EntityObject(hash_val)
+
+    def all_objects(self) -> range:
+        return range(NUM_ENTITIES)
+
+    def objects_of_type(self, type_id: int) -> Iterator[EntityObject]:
+        base = type_id << SHIFT_TYPE
+        for class_id in range(NUM_CLASSES):
+            for scope_id in range(NUM_SCOPES):
+                yield EntityObject(encode(type_id, class_id, scope_id, 0, 0, 0))
+
+    def objects_of_class(self, class_id: int) -> Iterator[EntityObject]:
+        base = class_id << SHIFT_CLASS
+        for type_id in range(NUM_TYPES):
+            for scope_id in range(NUM_SCOPES):
+                yield EntityObject(encode(type_id, class_id, scope_id, 0, 0, 0))
+
+    def objects_of_scope(self, scope_id: int) -> Iterator[EntityObject]:
+        for type_id in range(NUM_TYPES):
+            for class_id in range(NUM_CLASSES):
+                yield EntityObject(encode(type_id, class_id, scope_id, 0, 0, 0))
+
+    def identity(self, obj: EntityObject) -> EntityMorphism:
+        key = obj.hash
+        if key not in self._identity_cache:
+            self._identity_cache[key] = EntityMorphism(obj, obj, kind="identity")
+        return self._identity_cache[key]
+
+    def has_morphism(self, source: EntityObject, target: EntityObject) -> bool:
+        """Check whether a structural morphism exists between two entities."""
+        if source == target:
+            return True
+        return (
+            source.class_id == target.class_id
+            or source.scope_id == target.scope_id
+            or source.type_id == target.type_id
+        )
+
+    def hom(
+        self, source: EntityObject, target: EntityObject
+    ) -> Optional[EntityMorphism]:
+        """Return the unique morphism from source to target, if it exists."""
+        if source == target:
+            return self.identity(source)
+        if self.has_morphism(source, target):
+            kind = "structural"
+            if source.class_id == target.class_id:
+                kind = "class-equivalent"
+            elif source.scope_id == target.scope_id:
+                kind = "scope-equivalent"
+            elif source.type_id == target.type_id:
+                kind = "type-equivalent"
+            return EntityMorphism(source, target, kind=kind)
+        return None
+
+    def compose(
+        self, f: EntityMorphism, g: EntityMorphism
+    ) -> Optional[EntityMorphism]:
+        """Compose f: A→B with g: B→C to get g∘f: A→C."""
+        return f.compose(g)
+
+    def __repr__(self) -> str:
+        return f"EntityCategory(ob={NUM_ENTITIES}, types={NUM_TYPES}, classes={NUM_CLASSES}, scopes={NUM_SCOPES})"
+
+
+@dataclass
+class StructuralMorphism:
+    """A morphism encoded in the entity hash bits.
+
+    In v0, arity/role/morphism bits are always 0 (placeholder).
+    Future versions will populate these from syntactic context.
+    When populated, they define how entities transform into each other.
+    """
+
+    arity: int = 0
+    role: int = 0
+    morphism: int = 0
+
+    @property
+    def is_identity_like(self) -> bool:
+        return self.arity == 0 and self.role == 0 and self.morphism == 0
+
+    @property
+    def is_unary(self) -> bool:
+        return self.arity == 0
+
+    @property
+    def is_binary(self) -> bool:
+        return self.arity == 1
+
+    @property
+    def is_static(self) -> bool:
+        return self.morphism == 0
+
+    @property
+    def is_dynamic(self) -> bool:
+        return self.morphism == 1
+
+    def __repr__(self) -> str:
+        parts = []
+        parts.append("unary" if self.arity == 0 else "binary")
+        parts.append("caller" if self.role == 0 else "callee")
+        parts.append("static" if self.morphism == 0 else "dynamic")
+        return f"MorphismEncoding({', '.join(parts)})"
+
+
+class EmbeddingFunctor:
+    """The embedding functor F_embed: EntityCategory → Vect.
+
+    Maps each entity hash to its learned embedding vector
+    and each morphism to the difference of embeddings.
+
+    The entity_decoder's entity_embed IS this functor at the object level.
+    """
+
+    def __init__(self, embedding_weight: torch.Tensor):
+        self._weight = embedding_weight
+
+    def map_object(self, obj: EntityObject) -> torch.Tensor:
+        return self._weight[obj.hash]
+
+    def map_morphism(self, f: EntityMorphism) -> torch.Tensor:
+        return self.map_object(f.target) - self.map_object(f.source)
+
+    def map_objects_batch(self, hashes: torch.Tensor) -> torch.Tensor:
+        return self._weight[hashes]
+
+    def __call__(self, obj: EntityObject) -> torch.Tensor:
+        return self.map_object(obj)
+
+
+class TypeClassifierFunctor:
+    """The type-classifier functor F_type: EntityCategory → simplex(32).
+
+    Maps each entity to its predicted type distribution via the
+    entity_decoder's type_head.
+    """
+
+    def __init__(self, type_head_weight: torch.Tensor, type_head_bias: torch.Tensor):
+        self._w = type_head_weight
+        self._b = type_head_bias
+
+    def map_object(self, embedding: torch.Tensor) -> torch.Tensor:
+        logits = embedding @ self._w.T + self._b
+        return torch.softmax(logits, dim=-1)
+
+    def predicted_type(self, embedding: torch.Tensor) -> int:
+        logits = embedding @ self._w.T + self._b
+        return int(logits.argmax(dim=-1).item())
+
+
+class Subcategory:
+    """A full subcategory of EntityCategory filtered by structural constraints.
+
+    objects ⊆ ob(EntityCategory) restricted to matching type, class, and/or scope.
+    Morphisms are inherited from the parent category.
+    """
+
+    def __init__(
+        self,
+        parent: EntityCategory,
+        type_ids: Optional[list[int]] = None,
+        class_ids: Optional[list[int]] = None,
+        scope_ids: Optional[list[int]] = None,
+    ):
+        self.parent = parent
+        self.type_ids = set(type_ids) if type_ids else None
+        self.class_ids = set(class_ids) if class_ids else None
+        self.scope_ids = set(scope_ids) if scope_ids else None
+
+    def contains(self, obj: EntityObject) -> bool:
+        if self.type_ids is not None and obj.type_id not in self.type_ids:
+            return False
+        if self.class_ids is not None and obj.class_id not in self.class_ids:
+            return False
+        if self.scope_ids is not None and obj.scope_id not in self.scope_ids:
+            return False
+        return True
+
+    def objects(self) -> Iterator[EntityObject]:
+        for h in self.parent.all_objects():
+            obj = EntityObject(h)
+            if self.contains(obj):
+                yield obj
+
+    def identity(self, obj: EntityObject) -> Optional[EntityMorphism]:
+        if not self.contains(obj):
+            return None
+        return self.parent.identity(obj)
+
+    def hom(
+        self, source: EntityObject, target: EntityObject
+    ) -> Optional[EntityMorphism]:
+        if not self.contains(source) or not self.contains(target):
+            return None
+        return self.parent.hom(source, target)
+
+    def __repr__(self) -> str:
+        constraints = []
+        if self.type_ids:
+            constraints.append(f"types={sorted(self.type_ids)}")
+        if self.class_ids:
+            constraints.append(f"classes={sorted(self.class_ids)}")
+        if self.scope_ids:
+            constraints.append(f"scopes={sorted(self.scope_ids)}")
+        return f"Subcategory({', '.join(constraints)})"