entity-ent 0.1.0__tar.gz

entity_ent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beag Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

entity_ent-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: entity-ent
+Version: 0.1.0
+Summary: Entity-conditioned language model with category-theoretic reasoning
+Author: beag labs
+License: Apache-2.0
+Project-URL: Repository, https://github.com/beaglabs/entity-ent
+Project-URL: Models, https://huggingface.co/beaglabs
+Keywords: entity-reasoning,category-theory,graph-reasoning,nlp,llm,language-model
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.40
+Requires-Dist: peft>=0.10
+Requires-Dist: safetensors>=0.4
+Requires-Dist: tqdm>=4.64
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.100; extra == "serve"
+Requires-Dist: pydantic>=2.0; extra == "serve"
+Provides-Extra: train
+Requires-Dist: datasets>=2.14; extra == "train"
+Requires-Dist: accelerate>=0.30; extra == "train"
+Dynamic: license-file
+
+# ent
+
+Entity-conditioned language models with category-theoretic reasoning.
+
+`ent` augments pretrained transformers with a structured entity stream: tokens
+are mapped to hashed entity IDs, decoded into learned embeddings, and
+injected into the LM hidden space before generation. The inference engine
+layers on abstraction hierarchies, graph reasoning, working memory, and
+deterministic program execution.
+
+## Install
+
+```bash
+pip install entity-ent
+```
+
+For serving:
+
+```bash
+pip install entity-ent[serve]
+```
+
+## Quickstart
+
+```python
+from transformers import AutoTokenizer
+from ent.training.train import EntitySmolWrapper
+
+base_model = "HuggingFaceTB/SmolLM2-1.7B-Instruct"
+tokenizer = AutoTokenizer.from_pretrained(base_model)
+tokenizer.pad_token = tokenizer.eos_token
+
+model = EntitySmolWrapper.from_pretrained(
+    path="beaglabs/lancero-1.7B",
+    base_model_name=base_model,
+    device="cuda",
+    tokenizer=tokenizer,
+)
+
+response = model.chat([
+    {"role": "user", "content": "What type of entity is 'Paris'?"}
+])
+print(response)
+```
+
+Or load with `trust_remote_code` from HuggingFace:
+
+```python
+from transformers import AutoModel, AutoTokenizer
+model = AutoModel.from_pretrained("beaglabs/lancero-1.7B", trust_remote_code=True)
+```
+
+## Architecture
+
+```
+Token stream ──→ Entity hashing ──→ Entity embeddings ──→ Projection
+     │                                        │
+     ▼                                        ▼
+Token embeddings ───────────────────→ Sum ──→ Transformer ──→ Output
+```
+
+The entity stream provides explicit identity, type, and structural
+information that subword tokens cannot express. The broader engine includes:
+
+- **Abstraction**: Type-aware is-a/specializes-to hierarchies
+- **Graph reasoning**: BFS path finding between entity pairs
+- **Working memory**: Confidence-scored active filtering
+- **Durable memory**: Semantic and procedural records across calls
+- **Program execution**: Deterministic arithmetic, comparison, deduction
+
+Symbolic queries (entity resolution, type lookups, graph traversal, math)
+run on hashes alone — zero neural inference. Open-ended generation falls
+through to the entity-conditioned LM.
+
+## Models
+
+| Model | Base | Link |
+|-------|------|------|
+| Lancero 1.7B | SmolLM2-1.7B-Instruct | [beaglabs/lancero-1.7B](https://huggingface.co/beaglabs/lancero-1.7B) |
+
+## License
+
+Apache 2.0

entity_ent-0.1.0/README.md

@@ -0,0 +1,83 @@
+# ent
+
+Entity-conditioned language models with category-theoretic reasoning.
+
+`ent` augments pretrained transformers with a structured entity stream: tokens
+are mapped to hashed entity IDs, decoded into learned embeddings, and
+injected into the LM hidden space before generation. The inference engine
+layers on abstraction hierarchies, graph reasoning, working memory, and
+deterministic program execution.
+
+## Install
+
+```bash
+pip install entity-ent
+```
+
+For serving:
+
+```bash
+pip install entity-ent[serve]
+```
+
+## Quickstart
+
+```python
+from transformers import AutoTokenizer
+from ent.training.train import EntitySmolWrapper
+
+base_model = "HuggingFaceTB/SmolLM2-1.7B-Instruct"
+tokenizer = AutoTokenizer.from_pretrained(base_model)
+tokenizer.pad_token = tokenizer.eos_token
+
+model = EntitySmolWrapper.from_pretrained(
+    path="beaglabs/lancero-1.7B",
+    base_model_name=base_model,
+    device="cuda",
+    tokenizer=tokenizer,
+)
+
+response = model.chat([
+    {"role": "user", "content": "What type of entity is 'Paris'?"}
+])
+print(response)
+```
+
+Or load with `trust_remote_code` from HuggingFace:
+
+```python
+from transformers import AutoModel, AutoTokenizer
+model = AutoModel.from_pretrained("beaglabs/lancero-1.7B", trust_remote_code=True)
+```
+
+## Architecture
+
+```
+Token stream ──→ Entity hashing ──→ Entity embeddings ──→ Projection
+     │                                        │
+     ▼                                        ▼
+Token embeddings ───────────────────→ Sum ──→ Transformer ──→ Output
+```
+
+The entity stream provides explicit identity, type, and structural
+information that subword tokens cannot express. The broader engine includes:
+
+- **Abstraction**: Type-aware is-a/specializes-to hierarchies
+- **Graph reasoning**: BFS path finding between entity pairs
+- **Working memory**: Confidence-scored active filtering
+- **Durable memory**: Semantic and procedural records across calls
+- **Program execution**: Deterministic arithmetic, comparison, deduction
+
+Symbolic queries (entity resolution, type lookups, graph traversal, math)
+run on hashes alone — zero neural inference. Open-ended generation falls
+through to the entity-conditioned LM.
+
+## Models
+
+| Model | Base | Link |
+|-------|------|------|
+| Lancero 1.7B | SmolLM2-1.7B-Instruct | [beaglabs/lancero-1.7B](https://huggingface.co/beaglabs/lancero-1.7B) |
+
+## License
+
+Apache 2.0

entity_ent-0.1.0/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

entity_ent-0.1.0/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

entity_ent-0.1.0/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

entity_ent-0.1.0/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)

entity_ent-0.1.0/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"

entity_ent-0.1.0/ent/core/__init__.py

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