Hebrew Gematria

A Hebrew gematria engine that deterministically sums the standard letter values (mispar hechrachi, 1-400) of a Hebrew name. Niqqud are stripped and unsupported characters are rejected. Because gematria compares raw totals, the total is stamped in the selection modifiers over a single structural result symbol; standard versus mispar gadol finals (500-900) is configurable.

from fortune_telling_core import Querent, ReadingRequest
from fortune_telling_core.traditions.hebrew_gematria import (
    HEBREW_GEMATRIA_DECK,
    HEBREW_GEMATRIA_SPREAD,
    build_engine,
)

request = ReadingRequest(
    deck_id=HEBREW_GEMATRIA_DECK.id,
    spread_id=HEBREW_GEMATRIA_SPREAD.id,
    querent=Querent(id="sample", display_name="Sample", attributes={"name": "שלום"}),
)
reading = build_engine().cast(request)
# reading.summary -> "Gematria total 376."

hebrew_gematria

HEBREW_GEMATRIA_DECK module-attribute

HEBREW_GEMATRIA_DECK = Deck(
    id="hebrew_gematria.deck.total.v1",
    symbols=(
        Symbol(
            id=HEBREW_GEMATRIA_RESULT_SYMBOL,
            name="Gematria Total",
            attributes={"kind": "raw_total"},
        ),
    ),
)

HEBREW_GEMATRIA_SPREAD module-attribute

HEBREW_GEMATRIA_SPREAD = Spread(
    id="hebrew_gematria.spread.name.v1",
    name="Hebrew Gematria Total",
    positions=(
        Position(
            "total",
            "Total",
            "The summed gematria value of the name.",
        ),
    ),
)

FinalLetterMode

Bases: StrEnum

How the five Hebrew final forms (sofit) are valued.

STANDARD gives each final form the same value as its base letter. GADOL (mispar gadol) gives the final forms the values 500-900.

STANDARD class-attribute instance-attribute

STANDARD = 'standard'

GADOL class-attribute instance-attribute

GADOL = 'gadol'

HebrewGematriaEngine

HebrewGematriaEngine(
    *,
    final_letter_mode: FinalLetterMode = FinalLetterMode.STANDARD,
)

Bases: AbstractEngine

Hebrew gematria engine.

The engine deterministically sums the standard gematria values of a Hebrew name. Gematria compares raw totals rather than reducing to a single digit, so the total is the symbol-bearing value and is stamped into the selection modifiers over a single structural result symbol.

Parameters:

Name	Type	Description	Default
final_letter_mode	FinalLetterMode	Default treatment of final forms (sofit) when the request does not specify final_letter_mode.	STANDARD

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def __init__(self, *, final_letter_mode: FinalLetterMode = FinalLetterMode.STANDARD) -> None:
    self.final_letter_mode = final_letter_mode

id class-attribute instance-attribute

id = 'hebrew_gematria.engine'

version class-attribute instance-attribute

version = '0.1.0'

final_letter_mode instance-attribute

final_letter_mode = final_letter_mode

deck

deck(request: ReadingRequest) -> Deck

Return the Hebrew gematria deck.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request whose deck_id must match HEBREW_GEMATRIA_DECK.id.	required

Returns:

Type	Description
Deck	The bundled deck.

Raises:

Type	Description
ValidationError	If the requested deck is unsupported.

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def deck(self, request: ReadingRequest) -> Deck:
    """Return the Hebrew gematria deck.

    Args:
        request: Reading request whose ``deck_id`` must match
            ``HEBREW_GEMATRIA_DECK.id``.

    Returns:
        The bundled deck.

    Raises:
        ValidationError: If the requested deck is unsupported.
    """

    if request.deck_id != HEBREW_GEMATRIA_DECK.id:
        raise ValidationError(f"unsupported Hebrew gematria deck: {request.deck_id}")
    return HEBREW_GEMATRIA_DECK

spread

spread(request: ReadingRequest) -> Spread

Return the Hebrew gematria spread.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request whose spread_id must match HEBREW_GEMATRIA_SPREAD.id.	required

Returns:

Type	Description
Spread	The bundled spread.

Raises:

Type	Description
ValidationError	If the requested spread is unsupported.

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def spread(self, request: ReadingRequest) -> Spread:
    """Return the Hebrew gematria spread.

    Args:
        request: Reading request whose ``spread_id`` must match
            ``HEBREW_GEMATRIA_SPREAD.id``.

    Returns:
        The bundled spread.

    Raises:
        ValidationError: If the requested spread is unsupported.
    """

    if request.spread_id != HEBREW_GEMATRIA_SPREAD.id:
        raise ValidationError(f"unsupported Hebrew gematria spread: {request.spread_id}")
    return HEBREW_GEMATRIA_SPREAD

draw

draw(request: ReadingRequest, rng: Rng) -> Draw

Compute the gematria total as a deterministic draw.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request with name and optional final_letter_mode in options or querent attributes.	required
rng	Rng	Ignored. The argument is present for Engine compatibility.	required

Returns:

Type	Description
Draw	A draw with the single total selection.

Raises:

Type	Description
ValidationError	If the name is missing, has no Hebrew letters, or final_letter_mode is invalid.

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def draw(self, request: ReadingRequest, rng: Rng) -> Draw:
    """Compute the gematria total as a deterministic draw.

    Args:
        request: Reading request with ``name`` and optional
            ``final_letter_mode`` in options or querent attributes.
        rng: Ignored. The argument is present for ``Engine`` compatibility.

    Returns:
        A draw with the single total selection.

    Raises:
        ValidationError: If the name is missing, has no Hebrew letters, or
            ``final_letter_mode`` is invalid.
    """

    del rng
    fields = collect_values(request)
    name = require_string(fields, "name")
    mode = _parse_final_letter_mode(fields.get("final_letter_mode"), self.final_letter_mode)

    units = hebrew_gematria.values(name, final_letter_mode=mode)
    if not units:
        raise ValidationError("name must contain at least one Hebrew letter")
    total = hebrew_gematria.total(units)

    selection = Selection(
        "total",
        HEBREW_GEMATRIA_RESULT_SYMBOL,
        {
            "value": str(total),
            "total": str(total),
            "value_system": hebrew_gematria.ID,
            "value_system_version": hebrew_gematria.VERSION,
            "final_letter_mode": mode.value,
            "normalized_name": "".join(unit.char for unit in units),
            "values": format_value_trace(units),
        },
    )
    return Draw(HEBREW_GEMATRIA_DECK.id, HEBREW_GEMATRIA_SPREAD.id, (selection,))

cast

cast(request: ReadingRequest) -> Reading

Compute a Hebrew gematria reading without a caller RNG.

Parameters:

Name	Type	Description	Default
request	ReadingRequest	Reading request containing the name and optional configuration.	required

Returns:

Type	Description
Reading	A reading with the total placement and structural summary.

Raises:

Type	Description
ValidationError	If the name or options are invalid.

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def cast(self, request: ReadingRequest) -> Reading:
    """Compute a Hebrew gematria reading without a caller RNG.

    Args:
        request: Reading request containing the name and optional
            configuration.

    Returns:
        A reading with the total placement and structural summary.

    Raises:
        ValidationError: If the name or options are invalid.
    """

    draw = self.draw(request, _NULL_RNG)
    return self._interpret(request, draw, rng=None)

build_engine

build_engine(
    *,
    final_letter_mode: FinalLetterMode = FinalLetterMode.STANDARD,
) -> HebrewGematriaEngine

Create a Hebrew gematria engine.

Parameters:

Name	Type	Description	Default
final_letter_mode	FinalLetterMode	Default treatment of final forms (sofit).	STANDARD

Returns:

Type	Description
HebrewGematriaEngine	A new HebrewGematriaEngine instance.

Source code in src/fortune_telling_core/traditions/hebrew_gematria/engine.py

def build_engine(
    *, final_letter_mode: FinalLetterMode = FinalLetterMode.STANDARD
) -> HebrewGematriaEngine:
    """Create a Hebrew gematria engine.

    Args:
        final_letter_mode: Default treatment of final forms (sofit).

    Returns:
        A new ``HebrewGematriaEngine`` instance.
    """

    return HebrewGematriaEngine(final_letter_mode=final_letter_mode)