Introducing Our Horoscope Engine¶

Our horoscope engine is a deterministic astrology runtime designed for real production products, not novelty text generation. It combines Swiss Ephemeris computation, strict factor activation, and editorial rendering so your app receives stable, explainable, and premium report output.

What You Are Building On¶

At runtime, the engine calculates real celestial state and assembles meaning from activated astrological factors. For identical payloads, outputs remain byte-for-byte stable. When personalization inputs are provided, house-level and birth-context vectors activate to produce user-specific differences.

This gives your team:

• Predictable outputs for testing, QA, and caching — identical requests always return identical JSON.
• Explainable report composition through factor_details traces on every section.
• A clean path from lightweight sign reports to premium personalized reports.
• Period-aware depth — daily (5-6 factors), weekly (10), monthly (11), and yearly (13) factor stacks with explicit weights.

Architecture at a Glance¶

Full Engine Architecture¶

Request-to-Response Architecture¶

Deterministic Pipeline¶

1. Gateway validates authentication, quotas, and request policy.
2. Request contract validation enforces accepted schema and options.
3. Engine resolves sign source, period window, and ephemeris configuration.
4. Swiss Ephemeris computes positions, aspects, and houses (when eligible).
5. Aggregation layer samples the period, extracts events (aspects, ingresses, stations, lunations, eclipses), and ranks drivers.
6. Interpretation engine maps factor specs to editorial content using fixed order, explicit weights, and stable hash variant selection.
7. Editorial engine renders section narratives from V2 content packs with period-specific arc composition (opening → shift → outcome).
8. Gateway returns engine payload plus enterprise wrappers (_enterprise, _api_metadata_) for integration metadata.

Determinism Guarantees¶

Determinism is not an accident — it is enforced at every layer:

This means you can hash two independent requests with the same body and get the same output, enabling reliable caching, QA regression testing, and reproducible debugging.

Public vs Personalized Reports¶

Both are production-valid modes. The difference is not quality; it is activation depth.

Public Mode (Sign-Based)¶

Provide only a zodiac sign and date. The engine produces a stable, shared reading for all users with that sign in that period.

• Great for broad audience feeds and cost-efficient caching (12 signs × 4 periods × 365 days = ~17,520 unique daily caches)
• No house calculations — rising_sign, house_cusps, and body house assignments are null
• Strong fit for rapid rollout, magazine-style horoscopes, and freemium tiers

Personalized Mode (Birth-Aware)¶

Provide birth context (birth_time, coordinates, timezone) to activate deeper vectors. Two users with the same sign can receive different editorials because house placement and rising sign change the factor scoring.

• Required fields: birth_time (HH:MM) + birth_latitude + birth_longitude
• Unlocks: rising sign, 12 house cusps, planet-to-house assignments, and house-focus factors (daily_house_focus, weekly_house_focus, monthly_house_focus, yearly_house_focus)
• Best for premium subscriptions and high-retention experiences
• Supports richer app modules and personalization funnels

Factor-Driven Editorial Model¶

The engine is driven by explicit factor stacks — deterministic interpretation drivers computed from celestial snapshots and period aggregation. Each period has a defined factor order and explicit weights.

Factor Stacks by Period¶

Additional report families layer dedicated factor stacks: - Planet: planet_core_archetypes, planet_condition_archetypes, planet_house_focus, planet_sign_archetypes - Birthday: solar_return_tone, birthday_year_reset, natal_sun_house_year_theme - Aspect: aspect-led stacks with computed or overridden dominant aspect - Transit: transit-led stacks with computed or overridden dominant transit archetype

Each factor carries an explicit weight (e.g., moon_in_sign: 1.15 daily, yearly_theme_archetypes: 1.30 yearly) that influences section scoring and intensity derivation.

This model avoids random prose drift and keeps editorial tone tied to computed drivers with full traceability in factor_details.

Daily Personalized App Stats (Main Horoscope)¶

For daily personalized mode, the engine returns rich app-ready stats blocks at data.daily_personalized_stats. These are ideal for dashboard cards and summary widgets.

Activation trigger: period=daily and personalized birth request includes both birth_time and coordinates.

Key blocks:

• overall_pulse — composite daily vitality score
• archetype_scores — eight-dimension breakdown (wisdom, creativity, confidence, intuition, allure, romance, career, emotions)
• harmony_discord — top 4 harmonious and top 4 discordant sign drivers
• elemental_balance — fire/earth/air/water distribution
• momentum_channels — planetary momentum signals

Payload density control:

• daily_stats_detail: "full" for complete chart data with confidence tiers per block
• daily_stats_detail: "compact" for lighter client payloads (ideal for mobile widgets)

Request Design Highlights¶

The engine supports clear, typed controls for astrological configuration and rendering behavior. Common options include:

Response Shape Guarantees in the Gateway¶

Gateway report responses pass through engine data and append wrappers:

• _enterprise — plan tier, quota, and rate-limit metadata
• _api_metadata_ — endpoint info, supported languages, and request context

For engine-backed report endpoints, _api_metadata_.supported_languages is English-only:

{
  "_api_metadata_": {
    "supported_languages": ["en"]
  }
}

Language and Translation Policy¶

Live engine-backed report endpoints currently support lang=en only. This is intentional to preserve deterministic editorial nuance in production while translation reliability is curated separately. The gateway translation helper layer (lang=en|es|de|fr|pt) provides translated output at the API boundary for all non-horoscope report endpoints.

Content Pipeline: V2 Content Packs¶

Editorial content is sourced from structured V2 content packs in the engine's content repository.

At runtime, the content repository selects variants deterministically via stable hash selection with a four-level fallback chain:

1. Exact match (factor_type + factor_value + intensity)
2. Any value for factor_type (factor_type + intensity)
3. Any factor in section (section + intensity)
4. Section fallback template

This structure ensures editorial variety across intensities while preserving reproducibility for the same seed.

Trust Model: Closed Core + Open Source Lite¶

Our main production engine is closed-source and optimized for enterprise reliability, depth, and managed operations. It includes:

• Full house-aware personalized reports (all periods)
• Birthday cycle reports with solar return factors
• Planet, aspect, transit, house, and planet-house report suites
• Natal birth chart with configurable SVG wheel rendering
• Redis caching, metrics, health checks, and horizontal scaling

To support indie astrologers and developer evaluation, we also provide the open-source lite engine:

• OpAstro site
• OpAstro GitHub
• OpAstro PyPI

Use OpAstro to evaluate engine quality, explore factor computation logic, and verify Swiss Ephemeris integration. Scale to NumerologyAPI enterprise routes for richer report layers, broader endpoint coverage, and managed production operations.

Integration Path¶

1. Start with public sign-level reports — daily/weekly/monthly/yearly using sign only. No birth data required. Cache efficiently.
2. Add personalized birth fields — supply birth_time + coordinates to unlock differentiated editorials with house-aware factors.
3. Layer specialized report families — planetary, aspects, transits, and house endpoints for deeper product surfaces.
4. Add natal endpoints — full birth chart JSON + SVG wheel for visualization and advanced astrology workflows.
5. Optimize with sections — request only the sections your UI needs (e.g., ["general", "career"]) to reduce payload size.
6. Use tenant_id for cache isolation — separate free/premium tiers or A/B test variants without cache pollution.

Caching Strategy¶

Next Reading¶

• Horoscope Reports API Overview
• Today Horoscope
• Weekly Horoscope
• Monthly Horoscope
• Yearly Horoscope
• Birthday Horoscope
• Natal Birth Chart