Metadata-Version: 2.4
Name: eigenstate-dictionary
Version: 1.0.0
Summary: Prismatic semantic coordinate SDK — maps 170k+ English words to eigenstate coordinates E(w) = (theta, r, eta)
Project-URL: Homepage, https://github.com/eigenstate-dict/eigenstate-dictionary
Project-URL: Documentation, https://github.com/eigenstate-dict/eigenstate-dictionary#readme
Project-URL: Issues, https://github.com/eigenstate-dict/eigenstate-dictionary/issues
License: MIT License
        
        Copyright (c) 2026 Eigenstate Dictionary Project
        
        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.
License-File: LICENSE
Keywords: coordinate,dictionary,eigenstate,language,mathematics,nlp,semantics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# eigenstate-dictionary

**The world's first mathematical language system for AI concept exchange.**

Maps English words to precise eigenstate coordinates `E(w) = (θ, r, η)` in a 360°
prismatic semantic space — enabling AI systems to communicate with mathematical
precision about any human concept.

```bash
pip install eigenstate-dictionary
```

---

## What Is This?

Natural language is ambiguous. When an AI says "the bank overflowed," does it mean a
financial institution or a riverbank? When we say "light," do we mean illumination or
weight?

The Eigenstate Dictionary solves this by assigning every English word a precise
mathematical coordinate:

```
E(water) = (θ=64.8°, r=0.99, η=270°)  →  domain=AQUATIC, subcategory=A5 (Water-Boundary)
E(love)  = (θ=165.6°, r=0.75, η=0°)   →  domain=COGNITIVE, subcategory=C2 (Emotion-Positive)
E(logic) = (θ=309.6°, r=0.15, η=0°)   →  domain=ABSTRACT, subcategory=E2 (Logical-Philosophical)
```

Two AI systems that share this dictionary can exchange concepts with zero ambiguity.

---

## Coordinate Semantics

| Symbol | Name | Range | Meaning |
|--------|------|-------|---------|
| **θ** (theta) | Primary angle | [0°, 360°) | Domain family position |
| **r** | Radial magnitude | [0.0, 1.0] | Concreteness (0=abstract, 1=concrete) |
| **η** (eta) | Harmonic phase | {0°, 90°, 180°, 270°} | Semantic mode |

**Domains** (72° sectors):

| Domain | Range | Examples |
|--------|-------|---------|
| AQUATIC | 0° – 72° | ocean, river, cloud, wave |
| BIOTIC | 72° – 144° | tree, eagle, mushroom, grass |
| COGNITIVE | 144° – 216° | love, fear, thought, culture |
| GEOLOGIC | 216° – 288° | mountain, crystal, storm, desert |
| ABSTRACT | 288° – 360° | number, logic, time, system |

---

## Tier 1 — Offline SDK (free, no API key)

All coordinate math runs **locally** — no internet required.  Ideal for local AI
systems (Ollama, LM Studio, local Claude) that need private, offline concept exchange.

### Install

```bash
pip install eigenstate-dictionary
```

### Quickstart

```python
from eigenstate_dictionary import map_word, map_batch, combine_words, disambiguate, semantic_distance

# Map a word to its eigenstate coordinate
coord = map_word("ocean")
print(coord)
# {
#   'lemma': 'ocean', 'theta': 30.2, 'r': 0.7788, 'eta': 180.0,
#   'domain': 'AQUATIC', 'subcategory': 'A3',
#   'subcategory_name': 'Atmospheric-Water',
#   'stacking_depth': 2.5066, 'eigenenergy': 0.156327,
#   'algorithm_version': '1.0.0'
# }

# Batch lookup
coords = map_batch(["water", "tree", "love", "mountain", "logic"])

# Combine two concepts (weighted circular mean)
oasis = combine_words("desert", "water", weight_a=0.5)
print(f"oasis → θ={oasis['theta']:.1f}° ({oasis['domain']})")

# Disambiguate polysemous words using context
bank = disambiguate("bank", context=["river", "flood", "water"])
print(f"bank (river context) → sense='{bank['sense_key']}', θ={bank['theta']}°")

# Semantic distance
d = semantic_distance("love", "hate")
print(f"similarity: {d['similarity']:.4f}, angular distance: {d['angular_distance']:.1f}°")
```

### Polysemy Resolution

Seven built-in polysemous words with context-sensitive disambiguation:

```python
from eigenstate_dictionary import disambiguate

# "tree" has 4 senses: botanical, data-structure, genealogy, decision-tree
botanical = disambiguate("tree", context=["forest", "leaf", "bark"])
data      = disambiguate("tree", context=["graph", "node", "algorithm"])
print(botanical["sense_key"])  # → "tree_botanical"
print(data["sense_key"])       # → "tree_data"
```

### QA Validation

```python
from eigenstate_dictionary import map_word, validate_coordinate, audit_coverage

# Validate a coordinate against all 8 QA rules
result = validate_coordinate("love", map_word("love"))
print(result.valid, result.errors)

# Check 25-subcategory coverage in your dataset
entries = [(w, map_word(w)) for w in ["ocean", "tree", "love", "desert", "logic", ...]]
coverage = audit_coverage(entries)
print(f"Coverage: {coverage['coverage_percent']}%")
```

### CLI

```bash
# Map a word
eigenstate-dict map ocean

# Batch lookup
eigenstate-dict batch water tree love mountain

# Semantic distance
eigenstate-dict distance love hate

# Combine concepts
eigenstate-dict combine desert water --weight 0.5

# Disambiguate with context
eigenstate-dict disambiguate bank --context river flood water

# Validate a word's coordinate
eigenstate-dict validate ocean
```

---

## Tier 2 — Live Dictionary Client (API key required)

Connect to the **Alive Dictionary** — the community-driven, ever-growing corpus of
eigenstate-mapped words.  Submit new words, query the live database, and flag
entries for QA review.

Get an API key at [eigenstate-dictionary.com](https://eigenstate-dictionary.com).

### Quickstart

```python
from eigenstate_dictionary import EigenstateDictionaryClient

client = EigenstateDictionaryClient(api_key="eig_your_api_key")

# Look up a word in the live database
coord = client.get_word("sonder")

# Submit a new word (auto-coordinates derived from definition)
result = client.submit_word(
    word="sonder",
    definition=(
        "The sudden awareness that each bystander has a life as vivid and complex "
        "as one's own — an epic story that continues beyond one's line of sight."
    ),
    creator_name="Jane Doe",
    creator_email="jane@example.com",
    tier="free",   # free=5/day, pro=100/day, enterprise=500/day
)
print(result["attribution"])         # "sonder — coined by Jane Doe"
print(result["eigenstate_coordinates"])
print(f"Daily remaining: {result['daily_remaining']}")

# Flag a word for QA review
client.flag_word("badword", reason="Culturally insensitive term.", reporter_email="jane@example.com")

# List community-submitted words
words = client.list_user_created(limit=50, language="en")

# Batch submit a constructed language vocabulary
client.submit_batch(
    words=[
        {"word": "nanpa", "oxford_definition": "number (Toki Pona)", "pos": "noun"},
        {"word": "telo",  "oxford_definition": "water, liquid (Toki Pona)", "pos": "noun"},
    ],
    creator_name="Alice",
    creator_email="alice@example.com",
    language="toki-pona",
)
```

### Self-hosted / local API

```python
client = EigenstateDictionaryClient(
    api_key="eig_your_key",
    base_url="http://localhost:8000",  # point at your local API server
)
```

---

## Pilot Dataset

The `pilot_dataset/` directory ships **24,996 certified entries** from Phase 1 of the
full Oxford Dictionary expansion (170,000+ entries planned).

```python
import csv

with open("pilot_dataset/coordinates_25k.csv") as f:
    entries = {row["lemma"]: row for row in csv.DictReader(f)}

print(entries["desert"])
# {'lemma': 'desert', 'theta': '225.0', 'r': '0.8', 'eta': '0.0',
#  'domain': 'GEOLOGIC', 'subcategory': 'D1'}
```

---

## Package Structure

```
eigenstate_dictionary/
  __init__.py           public API (Tier 1 + Tier 2 exports)
  _calculator.py        Phase 1 E(n,T) engine — deterministic coordinate derivation
  _validator.py         QA validation rules — 8 validation checks
  _bias.py              Anti-bias protocol v1.1
  cli.py                eigenstate-dict CLI entry point
  client.py             Tier 2 live API client

# backward-compat shims (dev use; not installed as top-level in pip)
eigenstate_calculator.py
coordinate_validator.py
anti_bias_protocol.py

pilot_dataset/
  coordinates_25k.csv   24,996 certified entries
  coordinates_25k.json  Same data in JSON format
examples/
  basic_lookup.py
  word_combination.py
  context_disambiguation.py
  jupyter_walkthrough.ipynb
docs/
  mathematical_specification.md
  subcategory_matrix.md
  anti_bias_protocol.md
tests/
  test_calculator.py    52 unit + integration tests (pytest)
```

---

## Mathematical Foundation

The coordinate system is built on the `E(n,T)` eigenenergy function:

```
E(n, T) = 0.5·(T/n)² + R·(1 − cos T) + F²·(1/n²)·δ(n,1)

Where:
  n   = stacking depth (word complexity, 1.0–5.0+)
  T   = theta in radians
  R   = reflectance constant (0.98889694)
  F²  = interference coefficient (−39.84)
  δ   = Kronecker delta
```

Full specification: [docs/mathematical_specification.md](docs/mathematical_specification.md)

---

## Running Tests

```bash
pip install pytest
pytest tests/ -v
```

---

## Roadmap

- [x] 25,000 entries (Phase 1 pilot — this release)
- [x] pip-installable SDK with offline Tier 1 + live Tier 2 client
- [ ] 50,000 entries (Phase 6 Month 2)
- [ ] 100,000 entries (Phase 6 Month 3)
- [ ] 170,000+ entries (full Oxford Dictionary — Phase 6 complete)
- [ ] Multilingual extensions (Phase 7)
- [ ] Embedding export (numpy / torch tensors)

---

## License

MIT — see [LICENSE](LICENSE).

## Citation

```bibtex
@software{eigenstate_dictionary_2026,
  title  = {Eigenstate Dictionary: Mathematical Coordinates for English Language Concepts},
  year   = {2026},
  url    = {https://github.com/sajjaddadashpour/eigenstate-dictionary},
  note   = {Phase 1 pilot dataset, 24,996 entries, algorithm v1.0.0}
}
```
