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
