Computes Harsha Bala (positional happiness score) for all 7 classical planets in a Varshaphal solar return chart. Maximum 20 per planet (4 components × 5 points each).
SECTION: WHAT THIS TOOL COVERS
Harsha Bala is entirely distinct from Pancha Vargeeya Bala. Pancha Vargeeya Bala measures mathematical strength (sign dignity, exaltation arc, divisional chart fractions). Harsha Bala measures whether a planet is positionally comfortable — does it occupy the right house, sign, hemisphere, and return type for its nature? A planet with high Pancha Vargeeya Bala (60/80) but zero Harsha Bala has the capacity to deliver results, but does so through stress, delay, and frustration. A Year Lord (Varsha Pati) with 0 Harsha Bala signals a difficult year even when it wins the Pancha Adhikari election.
4 Components (5 points each, maximum 20):
1. STHANA — Happy house placement in the Varsha chart (measured from Varsha Ascendant, not natal Ascendant):
Sun=9th, Moon=3rd, Mars=6th, Mercury=1st, Jupiter=11th, Venus=5th, Saturn=12th.
2. SWAKSHETRA/UCCHA — Planet in its own sign (Swakshetra) or sign of exaltation (Uccha).
3. PUM-STRI (Gender/Hemisphere) — Male planets (Sun, Mars, Jupiter) prefer houses 7–12 (visible hemisphere). Female planets (Moon, Venus, Saturn) prefer houses 1–6 (invisible hemisphere). Mercury earns this component unconditionally.
4. DINA-RATRI (Day/Night) — Male planets (Sun, Mars, Jupiter) prefer a daytime solar return. Female planets (Moon, Venus, Saturn) prefer a nighttime return. Mercury earns this component unconditionally.
SECTION: WORKFLOW
BEFORE: RECOMMENDED — asterwise_get_varshaphal — identify the Year Lord (Varsha Pati) before interpreting Harsha Bala. The Year Lord's Harsha Bala is the most actionable number in this response.
AFTER: asterwise_get_varshaphal_saham — use Harsha Bala to assess whether each Saham lord can deliver its theme with ease or difficulty.
SECTION: INPUT CONTRACT
Same as asterwise_get_varshaphal — BirthData plus target_year.
target_year (required int): The Gregorian civil year of the solar return. Not age.
time (required): Solar return ascendant and house positions are time-sensitive.
SECTION: OUTPUT CONTRACT
data.target_year (int)
data.ayanamsa (string)
data.solar_return_utc (string — ISO UTC of solar return moment)
data.is_day_return (bool — true if solar return falls between sunrise and sunset; directly determines Dina-Ratri component results for all planets)
data.varshaphal_ascendant_longitude (float — Varsha Ascendant in degrees; all house placements are measured from this)
data.planets[] — 7 objects (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn in that order):
planet (string — planet name)
harsha_bala (int — total score 0–20)
max_harsha_bala (int — always 20)
varsha_house (int — planet's house in the Varsha chart, 1–12, from Varsha Ascendant)
rashi_index (int — 0–11, 0=Mesha)
rashi (string — Sanskrit sign name)
components{} — four keys:
sthana{}: earned (bool), points (int — 0 or 5), happy_house (int), actual_house (int), description (string)
swakshetra_uccha{}: earned (bool), points (int — 0 or 5), in_own_sign (bool), in_exaltation (bool), current_rashi_index (int)
pum_stri{}: earned (bool), points (int — 0 or 5), gender (string — 'male'|'female'|'neutral'), happy_hemisphere (string), actual_house (int)
dina_ratri{}: earned (bool), points (int — 0 or 5), happy_period (string), actual_period (string — 'day' or 'night')
interpretation (string — qualitative label: 'Excellent', 'Strong', 'Moderate', 'Weak', or 'Very weak')
(string — methodology and interpretation guidance)
SECTION: RESPONSE FORMAT
response_format=json serialises the complete response as indented JSON — use this for programmatic parsing, typed clients, and downstream tool chaining. response_format=markdown renders the same data as a human-readable report. Both modes return identical underlying data — no fields are added, removed, or filtered by either mode.
SECTION: COMPUTE CLASS
SLOW_COMPUTE — internally runs the full solar return computation before deriving Harsha Bala.
SECTION: ERROR CONTRACT
INVALID_PARAMS (local — caught before upstream call): None — BirthData Pydantic only.
INVALID_PARAMS (upstream): None — upstream rejection surfaces as MCP INTERNAL_ERROR.
INTERNAL_ERROR: Any upstream API failure or timeout → MCP INTERNAL_ERROR
Edge cases:
— Rahu and Ketu are excluded — Harsha Bala is defined only for the 7 classical grahas.
— Polar latitudes where sunrise/sunset cannot be computed affect is_day_return → MCP INTERNAL_ERROR.
— target_year is a Gregorian year, not age.
SECTION: DO NOT CONFUSE WITH
asterwise_get_varshaphal — returns Pancha Vargeeya Bala (mathematical strength out of 80) for the Pancha Adhikaris; Harsha Bala (positional happiness out of 20) is a completely different measurement returned by this tool.
asterwise_get_varshaphal_saham — derives sensitive zodiac points; this tool scores planet positional comfort.
asterwise_get_chart_strength — Shadbala for the natal chart, not Tajika Harsha Bala for the solar return.