Horoscoop Engine
# Introductie van onze Horoscoop Engine
Onze horoscoop engine is een deterministische astrologische runtime, ontworpen voor echte productieproducten, niet voor het genereren van ongewone tekst.
Het combineert de berekening van Swiss Ephemeris, strikte factor-activering en redactionele rendering, zodat uw app stabiele, uitlegbare en premium rapporten ontvangt.
-f59e0b?style=for-the-badge)
## Op welke manier u werkt
Tijdens de runtime berekent de engine de daadwerkelijke staat van de hemel en verzamelt betekenis uit geactiveerde astrologische factoren.
Voor identieke payloads blijven de outputs byte voor byte stabiel.
Wanneer personalisatie-inputs worden verstrekt, activeren huis-niveau en geboorte-context vectoren om gebruikersspecifieke verschillen te produceren.
Dit geeft uw team:- **Voorspelbare outputs** voor testen, kwaliteitscontrole en cachen — identieke verzoeken retourneren altijd hetzelfde JSON.
- **Uitlegbare rapport samenstelling** via sporen `factor_details` in elke sectie.
- **Een duidelijke route** van eenvoudige signrapporten naar gepersonaliseerde premiumrapporten.
- **Periodebewuste diepte** — dagelijks (5-6 factoren), wekelijks (10), maandelijks (11) en jaarlijks (13) factor stacks met expliciete gewichten.
## Architectuur in een Notendop
### Volledige Engine Architectuur
### Verzoek-naar-Antwoord Architectuur
## Deterministische Pipeline1. **Gateway** valideert authenticatie, quota's en verzoekbeleid.
2. **Validatie van het verzoekcontract** dwingt de geaccepteerde schema en opties af.
3. **Engine** bepaalt de bron van de signaal, het tijdsvenster en de configuratie van de ephemeris.
4. **Swiss Ephemeris** berekent posities, aspecten en huizen (wanneer mogelijk).
5. **Aggregatielaag** samplet het tijdsvenster, extraheert gebeurtenissen (aspecten, ingangen, stations, lunaties, eclipses), en rangschikt de drivers.
6. **Interpretatie-engine** koppelt factor specificaties aan redacteermateriaal met een vaste volgorde, expliciete gewichten en een stabiele hash variant selectie.
7. **Redacteere-engine** genereert secties van het verhaal uit V2 content packs met periodespecifieke arc compositie (opening → verschuiving → uitkomst).
8. **Gateway** retourneert de engine payload plus enterprise wrappers (`_enterprise`, `_api_metadata_`) voor integratiemeta-informatie.
## Garanties van Determinisme
Determinisme is geen toeval — het wordt afgedwongen op elk niveau:
| Garantie | Handhaving Mechanisme |
|---|---|
| Identiek payload → identieke factoren | Expliciete volgorde van factoren per periode + vaste gewichten |
| Identieke factoren → identieke inhoudsvarianten | SHA-256 stabiele hash index selectie |
| Identieke varianten → identieke formulering | Deterministische cyclus van zinnen uit V2 content packs |
| Identieke formulering → identiek JSON | Consistent redactiewerk + deduplicatie van afzonderlijke secties |
Dit betekent dat u twee onafhankelijke verzoeken met hetzelfde payload kunt hashen en dezelfde output kunt krijgen, waardoor betrouwbare caching, QA regressietesten en reproduceerbare debugging mogelijk zijn.
## Open versus Gepersonaliseerde Rapporten
Beide modi zijn geschikt voor productiegebruik.
Het verschil is niet de kwaliteit; het gaat om **activeringsniveau**.
### Open Modus (Op basis van een zonnteken)
Geef alleen een zonnteken en datum op.
De motor produceert een stabiele, gedeelde interpretatie voor alle gebruikers met dat zonnteken in die periode.
- Uitstekend geschikt voor brede publieksfeeds en kostenefficiënte caching (12 tekens × 4 perioden × 365 dagen = ~17.520 unieke dagelijkse caches)
- Geen berekeningen op basis van huizen — `rising_sign`, `house_cusps` en lichaam `house` toewijzingen zijn `null`
- Sterk geschikt voor een snelle implementatie, tijdschriftstijl horoscopen en freemium tiers### Gepersonaliseerde modus (Geboren Datum)
Geef geboortedetails (`birth_time`, coördinaten, tijdzone) om diepere vectoren te activeren.
Twee gebruikers met hetzelfde teken kunnen verschillende artikelen ontvangen omdat de positie en het opkomende teken de factoren anders interpreteren.
- **Vereiste velden:** `birth_time` (HH:MM) + `birth_latitude` + `birth_longitude`
- **Ontgrendelt:** opkomend teken, 12 huizen, planet-to-house toewijzingen en huizen-specifieke factoren (`daily_house_focus`, `weekly_house_focus`, `monthly_house_focus`, `yearly_house_focus`)
- Het meest geschikt voor premium abonnementen en hoogretentie-ervaringen
- Ondersteunt uitgebreidere app-modules en gepersonaliseerde workflows
## Factoren-gedreven redactiemodel
De motor wordt aangedreven door expliciete **factorenstacks** — deterministische interpretatie-drivers die worden berekend op basis van astronomische snapshots en periodieke aggregatie.
Elke periode heeft een gedefinieerde factorenvolgorde en expliciete gewichten.
### Factorenstacks per periode
| Periode | Aantal Factoren | Belangrijkste Factoren |
|---|---|---|
| **Dagelijks** | 5-6 | `sun_in_sign`, `moon_in_sign`, `transits_archetypes`, `aspects`, `daily_house_focus` |
| **Wekelijks** | 10 | `weekly_moon_phase`, `planetary_focus`, `retrograde_archetypes`, `weekly_theme_archetypes`, `weekly_house_focus` |
| **Maandelijks** | 11 | `monthly_lunation_archetypes`, `eclipse_archetypes`, `outer_planet_focus`, `monthly_theme_archetypes`, `monthly_house_focus` |
| **Jaarlijks** | 13 | `jupiter_in_sign`, `saturn_in_sign`, `nodal_axis`, `yearly_house_focus`, `yearly_theme_archetypes` |
Aanvullende rapportfamilies:
- **Planeet:** `planet_core_archetypes`, `planet_condition_archetypes`, `planet_house_focus`, `planet_sign_archetypes`
- **Geboortedatum:** `solar_return_tone`, `birthday_year_reset`, `natal_sun_house_year_theme`
- **Aspect:** aspect-gebaseerde stacks met berekende of overschreven dominante aspecten
- **Transit:** transit-gebaseerde stacks met berekende of overschreven dominante transit archetypen
Elke factor heeft een expliciete gewicht (bijv. `moon_in_sign: 1.15` (dagelijks), `yearly_theme_archetypes: 1.30` (jaarlijks)) dat de score en intensiteit beïnvloedt.
Dit model voorkomt willekeurige tekstdrift en houdt de redactiestijl gekoppeld aan berekende factoren met volledige traceerbaarheid in `factor_details`.
## Dagelijkse Gepersonaliseerde App Statistieken (Hoofdpredictie)
Voor de dagelijkse gepersonaliseerde modus, retourneert de engine rijke statistiekblokken die geschikt zijn voor apps op `data.daily_personalized_stats`.
Deze zijn ideaal voor dashboardkaarten en samenvattingswidgets.
**Activeringsvoorwaarde:** `period=daily` **en** een gepersonaliseerde geboortedata bevat zowel `birth_time` **als** `coordinates`.
Belangrijke blokken:
- `overall_pulse` — samengestelde dagelijkse vitaliteitsscore
- `archetype_scores` — acht-dimensionale analyse (`wisdom`, `creativity`, `confidence`, `intuition`, `allure`, `romance`, `career`, `emotions`)
- `harmony_discord` — top 4 harmonieuze en top 4 disharmonieuze tekens
- `elemental_balance` — verdeling van vuur/aarde/lucht/water
- `momentum_channels` — planetaire momentum signalen
Payload-dichtheid controle:
- `daily_stats_detail: "full"` voor volledige chartdata met betrouwbaarheidsniveaus per blok
- `daily_stats_detail: "compact"` voor lichtere client payloads (ideaal voor mobiele widgets)
## Belangrijke punten in het ontwerp van de aanvraag
De motor ondersteunt duidelijke, getypeerde controles voor astrologische configuratie en renderinggedrag.
Veelvoorkomende opties zijn onder meer:
| Veld | Type | Doel |
|---|---|---|
| `period` | string | `daily`, `weekly`, `monthly`, `yearly` |
| `sections` | array | Leefgebieden om in te sluiten (bijv. `general`, `career`, `love_singles`) |
| `sign` / `birth` | string / object | Bron van het teken (openbaar vs. gepersonaliseerd) |
| `target_date` | string | Expliciete datum-anker (`YYYY-MM-DD`) voor reproduceerbaarheid |
| `zodiac_system` | string | `tropical` of `sidereal` |
| `ayanamsa` | string | Sidereaal afwijkingssysteem (`lahiri`, `fagan_bradley`, enz.) |
| `house_system` | string | `placidus`, `whole_sign`, `equal`, `koch` |
| `node_type` | string | `true` (daadwerkelijk) of `mean` (gemiddelde) maansknop |
| `tenant_id` | string | Cache-ruimte isolatie voor multi-tenant of A/B scenario's |
## Antwoordvorm Garantiën in de Gateway
Gateway antwoordresponsen gaan door via engine data en voegen wrappers toe:
- `_enterprise` — plan tier, quota en rate-limiet metadata
- `_api_metadata_` — endpoint info, ondersteunde talen en verzoekcontext
Voor engine-ondersteunde rapport endpoints, is `_api_metadata_.supported_languages` alleen in het Engels:
```json
{
"_api_metadata_": {
"supported_languages": ["en"]
}
}
Taal- en VertalingspolicyLive engine-backed report endpoints currently support lang=en only.¶
Dit is bewust om deterministische redactionele nuances te behouden in productie, terwijl de vertrouwbaarheid van de vertaling apart wordt beheerd.De gateway vertaalhulp laag (lang=en|es|de|fr|pt) biedt vertaalde uitvoer op het API-niveau voor alle endpoints die geen horoscooprapporten bevatten.
Inhoudspijplijn: V2 Content Packs¶
De inhoud wordt verkregen uit gestructureerde V2 content packs in de contentrepository van de motor. At runtime, the content repository selects variants deterministically via stable hash selection with a four-level fallback chain:
- Exact overeenkomst (factor_type + factor_waarde + intensiteit)2. Elke waarde voor
factor_type(factor_type + intensiteit)
--- EINDE MARKDOWN ---3. Elke factor in de sectie (sectie + intensiteit)
--- EINDE MARKDOWN ---4. Template voor alternatieve secties
This structure ensures editorial variety across intensities while preserving reproducibility for the same seed.
Vertrouwmodel: Gesloten Kern + Open Source Lite¶
Onze belangrijkste productie-engine is gesloten bron en geoptimaliseerd voor bedrijfsbetrouwbaarheid, diepte en beheerde operaties.Het bevat:
- Volledige, persoonlijke rapporten (alle periodes)
- Rapporten over de geboortedatumcyclus met factoren voor zonne terugkeer
- Suites van rapporten met planeten, aspecten, transits, huizen en planet-huis relaties
- Geboorte chart met configureerbare SVG rendering
- Redis caching, metrics, gezondheidscontroles en horizontale schaalbaarheid
Om onafhankelijke astrologen en de evaluatie van ontwikkelaars te ondersteunen, bieden we ook de open-source lite engine aan:
Gebruik OpAstro om de kwaliteit van de engine te evalueren, de logica voor het berekenen van factoren te onderzoeken en de integratie met Swiss Ephemeris te verifiëren. Schaal naar NumerologyAPI enterprise routes voor rijkere rapportlagen, breder endpoint-bereik en beheerde productieomgevingen.
Integratiemogelijkheden1. Begin met rapporten op signaalniveau — dagelijks/wekelijks/maandelijks/jaarlijks, uitsluitend met sign. Geen geboortedata vereist. Efficiënte caching.¶
- Voeg gepersonaliseerde geboortedetails toe — lever
birth_time+ coördinaten aan om verschillende editorials te ontsluiten met rekening houdend met huizen. - Voeg gespecialiseerde rapportfamilies toe — planeten, aspecten, transits en huizen endpoints voor diepere productoppervlakken.
- Voeg natal endpoints toe — volledige geboorte chart JSON + SVG wielt voor visualisatie en geavanceerde astrologische workflows.
- Optimaliseer met secties — vraag alleen de
sectionsaan die uw UI nodig heeft (bijv.["general", "career"]) om de payloadgrootte te verkleinen. - Gebruik
tenant_idvoor cache-isolatie — scheid gratis/premium tiers of A/B test varianten zonder cachevervuiling.
Caching Strategie¶
| Mode | Cache Efficiëntie | Strategie |
|---|---|---|
| Publiek (alleen op signaalniveau) | Hoog — ~17.520 unieke dagelijkse caches | Voorverwarm de volgende dag; TTL 1-4 uur |
| Gepersonaliseerd (geboorte-bewust) | Lager — per gebruiker | Cache keys per gebruiker; TTL 24 uur; Aanbevolen: Redis |