How Stars Engine computes spirit lookups, natal charts, graph traversal, convergence analysis, geomancy, and sigil generation. Every computation traced to its source, every limitation documented.
Engine version 2.7.0 · 148 systems · 194 output keys per chart · 147,841 content-addressed charts archived
The spirit lookup endpoint (GET /api/stars/esoteric/spirits?sign=°ree=)
maps any zodiac degree to its governing spirits across four independent
traditions. All mappings are derived from primary source texts and are
deterministic — the same sign+degree always returns the same spirits.
The 72 Goetic spirits from the Lemegeton Clavicula Salomonis (Ars Goetia, 17th c.) are mapped to 72 quinary segments of the zodiac. Each segment spans 5° of ecliptic longitude, dividing the 360° circle into 72 equal parts.
quinary_segment = floor(absolute_longitude / 5) % 72 + 1
spirit = GOETIA_BY_QUINARY[quinary_segment - 1]
Example: Scorpio 22° → absolute longitude 232° → floor(232 / 5) % 72 = 46 → segment 47 → Uvall (Duke).
Source: Lemegeton Clavicula Salomonis, Ars Goetia. Ed. Crowley/Mathers (1904); Peterson, The Lesser Key of Solomon (2001). The 72-spirit enumeration follows the standard Lemegeton ordering.
The 72 angels of the Shem HaMephorash (the explicit name of God) are derived from Exodus 14:19-21. Each of the three verses contains 72 Hebrew letters. By combining corresponding letters across the three verses and appending a divine suffix, 72 three-letter angel names are formed. These 72 angels map to the same 72 quinary segments as the Goetic spirits.
quinary_segment = floor(absolute_longitude / 5) % 72 + 1
angel = SHEM_ANGELS[quinary_segment - 1]
Example: Scorpio 22° → segment 47 → Asaliah, derived from Exodus 14:21. Office: "Contemplation, elevation of the soul, truth."
Source: Sefer Ha-Shem (The Book of the Name). Cf. Agrippa, De Occulta Philosophia III §24 (1533); Lenain, La Science Cabalistique (1823); Godwin, Cabbalistic Encyclopedia (1979).
The 36 Egyptian decans divide the zodiac into 10° segments. Each decan is associated with a specific Egyptian deity, a domain of influence, a body part, a protective function, and a shadow expression. The decan system predates Hellenistic astrology and was originally used for timekeeping — each decan marked a 10-day period of the Egyptian year.
decan_index = floor(absolute_longitude / 10) % 36 + 1
decan = DECAN_BY_NUMBER[decan_index]
Example: Scorpio 22° → absolute longitude 232° → floor(232 / 10) % 36 = 23 → decan 24 → Serqet, domain: "Transformation venom, sexual magic, antidote."
Source: Egyptian decan lists from the Temple of Dendera; Greco-Egyptian magical papyri (PGM); Firmicus Maternus, Mathesis II.4 (4th c. CE); Neugebauer & Parker, Egyptian Astronomical Texts (1960-1969).
The 30 Enochian Aethyrs are visionary realms received by John Dee and Edward Kelley during their angelic communications (1582-1589). Each Aethyr spans 12° of the zodiac. The Aethyrs are numbered from 30 (TEX, the outermost, at 0° Aries) down to 1 (LIL, the innermost, at the final segment of Pisces).
aethyr_number = 30 - floor(absolute_longitude / 12)
aethyr_name = AETHYR_NAMES[aethyr_number]
Example: Scorpio 22° → absolute longitude 232° → 30 - floor(232 / 12) = 30 - 19 = Aethyr 11 → ICH.
Source: Liber Scientiae, Auxilii, et Victoriae Terrestris, received by John Dee & Edward Kelley (1582-1589). Recorded in Mysteriorum Libri Quinque; A True & Faithful Relation (ed. Casaubon, 1659); modern reconstruction by Peterson (2003) and James (1984).
All natal chart computation begins with the NASA Jet Propulsion Laboratory DE440 ephemeris — a 120 MB kernel providing planetary positions with sub-arcsecond precision. The Skyfield library computes planetary longitudes, declinations, house cusps, and angles from birth data (date, time, latitude, longitude).
From a single ephemeris pass, the engine computes:
From these base computations, 148 derived systems are computed — Vedic nakshatras and dashas, Human Design gates and channels, BaZi Four Pillars, Gene Keys activations, I Ching hexagrams, Kabbalah Tree of Life pillars, and 140+ more. Each system is computed by an independent module with error isolation — one system failing does not affect the others.
Every system in the engine carries a derivation classification describing how far it sits from the raw astronomical data. This classification allows convergence analysis to distinguish between independent measurements and systems that derive from each other.
| Tier | Meaning | Examples | Count |
|---|---|---|---|
| D0 — Celestial | Computed directly from JPL ephemeris. No interpretation. | Planetary positions, houses, angles, declinations, speeds | 31 |
| D1 — Calendrical | Derived from date/name arithmetic. No ephemeris needed. | Chinese zodiac animal, Mayan Tzolk'in, numerology | 22 |
| D2 — Chart-Derived | D0 position + a traditional interpretive framework. | Elements, modes, essential dignities, aspects, nakshatras, BaZi pillars, HD gates | 55 |
| D3 — Re-Encoding | D0-D2 outputs mapped onto a historically-independent tradition. | Gene Keys (HD gates re-mapped), Spiral Dynamics (chart re-encoded) | 17 |
| D4 — Synthesis | Composites of multiple prior tiers. | Convergence scores, keystone detection, ensemble predictions | 43 |
The concept graph connects 5,061 nodes through 1,801 edges spanning 113+ traditions. A query like "Mars in Golden Dawn" traverses the graph from the concept "Mars" across linguistic, doctrinal, and empirical edges to return correspondences in the target tradition.
The graph is built by an 8-pass builder (scripts/build_concept_graph.py):
engine/derivation.py,
and curated edges from hand-verified corrections.Every edge carries a mechanism annotation describing how the connection was established:
| Type | Count | Meaning |
|---|---|---|
| Doctrinal Correspondence | 316 | Connection attested in a primary source text. "Mars corresponds to Iron because Agrippa III §10 says so." These are the highest-quality edges — they come from named authorities in specific texts. |
| Empirical Co-Occurrence | 1,054 | Connection observed in chart data — two systems produce correlated outputs across a sample of charts. These are statistical associations, not attested doctrines. They may reflect real patterns or shared computational lineage. |
| Computational Lineage | 431 | Connection derived from engine architecture — one system feeds into another. "Elements derives from positions" is a computational fact, not a doctrinal claim. |
22 hyperedges connect groups of 3+ concepts that share a common basis.
The synonym builder (scripts/build_concept_synonyms.py) maps
305 concepts to ~2,200 surface forms across 8 languages. "Surya" → Sun.
"Mercury" → planet, metal, alchemical principle. The system returns the
most likely concept for any surface form, with context-aware disambiguation.
The convergence analysis measures how often independent astrological systems produce aligned results from the same birth data.
For each chart in a 500-chart sample, 158 extractors pull dimension vectors from the master data dict. Each extractor maps one system's output to a set of shared dimensions (e.g., "emotional_depth," "cognitive_style"). Pairwise cosine similarity is computed between every pair of D0-D2 systems that share at least 3 dimensions.
96 D0-D2 systems converge at mean pairwise cosine similarity of 0.5673 across 500 independently-computed charts. This is significantly above the null expectation (cos≈0.0 for random dimension vectors of this dimensionality). Published claim passes criteria B, C, and E from the validation framework.
96 independent measurement systems produce aligned results 57% of the time, significantly above chance. This suggests these systems are measuring real underlying patterns in birth data, regardless of what interpretive framework you prefer.
The geomancy endpoint (POST /api/stars/divination/cast)
generates a full Shield Chart using the traditional geomantic method.
Input: a seed string provided by the user. Each character of the seed is hashed to produce binary values — odd → 1 dot, even → 2 dots. This generates the four Mothers, the foundational figures of the Shield Chart.
4 Mothers → generated from seed hash
4 Daughters → derived from the Mothers by reading
across rows (Mother 1 row 1 + Mother 2 row 1 + Mother 3 row 1 +
Mother 4 row 1 → Daughter 1)
4 Nephews → derived by XOR-ing adjacent Mothers and
Daughters (Mother 1 + Mother 2 → Nephew 1, etc.)
2 Witnesses → Right Witness = Nephew 1 + Nephew 2;
Left Witness = Nephew 3 + Nephew 4
1 Judge → Right Witness + Left Witness (XOR)
Each figure is one of the 16 traditional geomantic figures (Populus, Acquisitio, Carcer, etc.). The Judge's dot count is validated — it must be even for the reading to be valid.
Source: Traditional geomantic method as documented in John Michael Greer, The Art and Practice of Geomancy (2009); Agrippa, De Occulta Philosophia II (1533); the geomantic literature of the medieval Arabic and Latin traditions.
The sigil endpoint (POST /api/stars/chaos/sigilize)
generates sigils from intent statements using two methods.
The user provides an intent statement (e.g., "I WILL COMPLETE THE WORK"). The system removes duplicate letters, reducing the statement to its unique characters. These letters are mapped onto a word-grid (a kamea-like arrangement of the alphabet) to produce a set of points. The points are connected in sequence to form the sigil shape.
Source: Austin Osman Spare, The Book of Pleasure (Self-Love): The Psychology of Ecstasy (1913). Spare's method of sigilization — reducing a statement of intent to its unique letters, arranging them into a glyph, and charging it through gnosis — is the foundation of modern chaos magic sigil practice.
An alternative method mapping the intent letters onto a planetary kamea (magic square) associated with the intent's dominant planet. Letters are placed on the kamea grid and connected in sequence, producing a sigil that incorporates the planetary correspondence.
Source: Rose Cross sigil method from the Hermetic Order of the Golden Dawn, as documented in Regardie, The Golden Dawn (1937-40), Volume 4.
Stars Engine computes planetary positions, derives system outputs from those positions, and documents what source texts say about those outputs. It does not tell anyone what their chart means for their life. It does not offer advice, diagnosis, or prediction. The interpretation belongs to the practitioner, in their tradition, with their training.
Every correspondence carries a citation to a primary source. We have made our best effort to trace claims to their textual origins. We may be wrong. The citations let you verify, dispute, and correct. If you find an error — a misattributed source, a wrong chapter reference, a mapping that contradicts the text it cites — tell us. Corrections are credited publicly.
The convergence claim (§5) is about computational systems producing correlated outputs. It is not about the empirical validity of astrology. Every published finding carries a sample size, a p-value or effect size, and a statement of what was tested and on what population. We scope claims narrowly — not because the engine is limited, but because overclaiming is the fastest way to lose credibility.
The 148 systems in the engine are computational models of astrological and esoteric traditions. They are not the traditions themselves. A Vedic astrologer is not their software. A Human Design analyst is not their bodygraph tool. A ceremonial magician is not their grimoire lookup. The traditions belong to their practitioners. Stars provides the calculator and the library. The wisdom belongs to the living lineages.