terpene_engine

Terpene Engine – Cannabis phytochemistry modulation layer.

Loads terpene profiles and strain definitions from terpene_profiles.yaml, computes composite NCM deltas per strain, resolves entourage synergies, and provides the sativa/indica gradient interpolation used by the cascade engine for bipolar ENDOCANNABINOID_DRIFT staging.

# 🔥 the stoner goddess gets her pharmacology right 💀

class terpene_engine.TerpeneProfile(name, polarity, boiling_point_c, aroma, ncm_deltas, flavor_mods, effects)

Bases: object

A single cannabis terpene with pharmacological properties.

Parameters:

• name (str)

• polarity (float)

• boiling_point_c (float)

• aroma (str)

• ncm_deltas (Dict[str, float])

• flavor_mods (Dict[str, float])

• effects (str)

name: str

polarity: float

boiling_point_c: float

aroma: str

ncm_deltas: Dict[str, float]

flavor_mods: Dict[str, float]

effects: str

class terpene_engine.StrainProfile(name, strain_gradient, classification, thc_pct, description, terpene_weights)

Bases: object

A cannabis strain with its terpene composition.

Parameters:

• name (str)

• strain_gradient (float)

• classification (str)

• thc_pct (float)

• description (str)

• terpene_weights (Dict[str, float])

name: str

strain_gradient: float

classification: str

thc_pct: float

description: str

terpene_weights: Dict[str, float]

class terpene_engine.StrainEffect(strain_name, strain_gradient, composite_deltas, entourage_bonuses, total_deltas, flavor_shifts, dominant_terpene, pole_label, active_entourage_rules)

Bases: object

Computed pharmacological effect of a strain.

Parameters:

• strain_name (str)

• strain_gradient (float)

• composite_deltas (Dict[str, float])

• entourage_bonuses (Dict[str, float])

• total_deltas (Dict[str, float])

• flavor_shifts (Dict[str, float])

• dominant_terpene (str)

• pole_label (str)

• active_entourage_rules (List[str])

strain_name: str

strain_gradient: float

composite_deltas: Dict[str, float]

entourage_bonuses: Dict[str, float]

total_deltas: Dict[str, float]

flavor_shifts: Dict[str, float]

dominant_terpene: str

pole_label: str

active_entourage_rules: List[str]

to_dict()

Convert to dict representation.

Returns:

Result dictionary.

Return type:

dict

class terpene_engine.TerpeneEngine(yaml_path=None)

Bases: object

Cannabis phytochemistry computation engine.

Loads terpene profiles and strains from YAML, computes composite NCM effects, resolves entourage synergies, and provides the bipolar sativa/indica gradient for cascade interpolation.

Parameters:

yaml_path (Optional[str])

__init__(yaml_path=None)

Initialize the instance.

Parameters:

yaml_path (Optional[str]) – Path to terpene_profiles.yaml. Defaults to same directory as this module.

Return type:

None

get_terpene(name)

Look up a terpene by name (case-insensitive).

Return type:

Optional[TerpeneProfile]

Parameters:

name (str)

get_strain(name)

Look up a strain by name (case-insensitive, underscore-normalized).

Return type:

Optional[StrainProfile]

Parameters:

name (str)

list_terpenes()

List all terpene names.

Return type:

List[str]

list_strains()

List all strain names.

Return type:

List[str]

compute_strain_effect(strain_name)

Compute the full pharmacological effect of a cannabis strain.

Resolves terpene weights to composite NCM deltas, applies entourage synergy rules, computes flavor axis shifts, and determines the sativa/indica pole label.

Parameters:

strain_name (str) – Name of the strain to compute.

Return type:

Optional[StrainEffect]

Returns:

StrainEffect dataclass or None if strain not found.

compute_gradient_blend(gradient)

Interpolate between sativa and indica NCM pole signatures.

Used by the cascade engine to lerp ENDOCANNABINOID_DRIFT stage deltas based on strain_gradient position.

Parameters:

gradient (float) – 0.0 (pure indica) to 1.0 (pure sativa).

Return type:

Dict[str, float]

Returns:

Dict of NCM node -> delta value, interpolated between poles.

get_cadence_state(gradient)

Return the appropriate cadence state for a strain gradient.

Parameters:

gradient (float) – 0.0 (indica) to 1.0 (sativa).

Returns:

‘stoned_indica’, ‘stoned’, or ‘stoned_sativa’.

Return type:

str

get_pole_info(pole)

Return pole definition for ‘sativa’ or ‘indica’.

Return type:

Dict[str, Any]

Parameters:

pole (str)

find_strain_by_gradient(target_gradient, n=3)

Find the N strains closest to a target gradient value.

Parameters:

• target_gradient (float) – Desired sativa/indica position.

• n (int) – Number of results to return.

Return type:

List[StrainProfile]

Returns:

List of StrainProfile sorted by distance to target.