eigenstate-dictionary 1.0.0

Prismatic semantic coordinate SDK — maps 170k+ English words to eigenstate coordinates E(w) = (theta, r, eta)

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.

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

pip install eigenstate-dictionary

Quickstart

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:

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

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

# 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.

Quickstart

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="[e-mail]",
    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="[e-mail]")

# 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="[e-mail]",
    language="toki-pona",
)

Self-hosted / local API

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).

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

---

Running Tests

pip install pytest
pytest tests/ -v

---

Roadmap

• 25,000 entries (Phase 1 pilot — this release)
• 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.

Citation

@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}
}