Apresentando o Nosso Motor de Horóscopo¶

Nosso motor de horóscopo é um ambiente de execução astrológico determinístico, projetado para produtos de produção reais, e não para geração de texto de entretenimento. Ele combina a computação do Swiss Ephemeris, ativação estrita de fatores e renderização editorial, para que sua aplicação receba resultados de relatórios estáveis, explicáveis e de alta qualidade.

Sobre o Que Você Está Construindo¶

Em tempo de execução, o motor calcula o estado celeste real e monta o significado a partir dos fatores astrológicos ativados. Para payloads idênticos, os resultados permanecem estáveis, byte a byte. Quando são fornecidas entradas de personalização, os vetores de nível de casa e contexto de nascimento são ativados para produzir diferenças específicas do usuário.

Isso oferece à sua equipe: - Saídas previsíveis para testes, QA e cache: requisições idênticas sempre retornam o mesmo JSON. - Composição de relatórios explicável através de rastros factor_details em cada seção. - Um caminho limpo de relatórios de assinatura leves a relatórios personalizados premium. - Profundidade consciente do período: pilares diários (5-6 fatores), semanais (10), mensais (11) e anuais (13) com pesos explícitos.

Visão Geral da Arquitetura¶

Arquitetura do Motor Completo¶

Arquitetura de Requisição-Resposta¶

Pipeline Determinístico1. Gateway valida a autenticação, as quotas e a política de requisição.¶

1. Validação do contrato de requisição garante o esquema e as opções aceitos.
2. Motor resolve a fonte de assinatura, a janela de período e a configuração da ephemeris.
3. Swiss Ephemeris calcula posições, aspectos e casas (quando aplicável).
4. Camada de agregação amostra o período, extrai eventos (aspectos, entradas, estações, lunations, eclipses) e classifica os drivers.
5. Motor de interpretação mapeia as especificações de fatores para conteúdo editorial usando uma ordem fixa, pesos explícitos e seleção estável de variantes de hash.
6. Motor editorial renderiza narrativas de seções a partir de pacotes de conteúdo V2 com composição de arco específica para o período (abertura → mudança → resultado).
7. Gateway retorna o payload do motor, além de wrappers empresariais (_enterprise, _api_metadata_) para metadados de integração.

Garantias de Determinismo¶

O determinismo não é um acidente — ele é garantido em todas as camadas:

Isso significa que você pode calcular o hash de duas solicitações independentes com o mesmo corpo e obter o mesmo resultado, permitindo o armazenamento em cache confiável, testes de regressão de QA e depuração reprodutível.

Relatórios Públicos vs. Personalizados¶

Ambos são modos válidos para produção. A diferença não é na qualidade; é na profundidade de ativação.

Modo Público (Baseado em Signo)¶

Forneça apenas um signo e uma data do zodíaco. O motor produz uma leitura estável e compartilhada para todos os usuários com esse signo nesse período.

• Ótimo para feeds de público amplo e armazenamento em cache eficiente (12 signos × 4 períodos × 365 dias = ~17.520 caches diárias únicas)
• Sem cálculos de casas — as atribuições rising_sign, house_cusps e do corpo house são null
• Adequado para lançamento rápido, horóscopos de estilo de revista e níveis freemium### Modo Personalizado (Consciente da Data de Nascimento)

Forneça o contexto de nascimento (birth_time, coordenadas, fuso horário) para ativar vetores mais profundos. Dois usuários com o mesmo signo podem receber diferentes editoriais, pois a posição da casa e o signo ascendente alteram a pontuação dos fatores.

• Campos obrigatórios: birth_time (HH:MM) + birth_latitude + birth_longitude
• Desbloqueia: signo ascendente, cúspes das 12 casas, atribuições planeta-casa e fatores de foco de casa (daily_house_focus, weekly_house_focus, monthly_house_focus, yearly_house_focus)
• Ideal para assinaturas premium e experiências de alta retenção
• Suporta módulos de aplicativo mais ricos e funis de personalização

Modelo de Editorial Baseado em Fatores¶

O motor é impulsionado por pilas de fatores explícitas — interpretadores determinísticos calculados a partir de capturas celestes e agregação de períodos. Cada período tem uma ordem de fator definida e pesos explícitos.

Pilas de Fatores por Período¶

Camada adicional de famílias de relatórios com pilares de fatores dedicados: - Planeta: planet_core_archetypes, planet_condition_archetypes, planet_house_focus, planet_sign_archetypes - Data de Nascimento: solar_return_tone, birthday_year_reset, natal_sun_house_year_theme - Aspecto: pilares de aspecto liderados com aspecto dominante calculado ou substituído - Trânsito: pilares de trânsito liderados com arquétipo de trânsito dominante calculado ou substituído

Cada fator possui um peso explícito (por exemplo, moon_in_sign: 1.15 diário, yearly_theme_archetypes: 1.30 anual) que influencia a pontuação da seção e a derivação da intensidade.

Este modelo evita a deriva aleatória do texto e mantém o tom editorial ligado aos impulsionadores calculados, com total rastreabilidade em factor_details.

Estatísticas de Aplicativo Personalizadas Diárias (Horóscopo Principal)¶

Para o modo personalizado diário, o motor retorna blocos de estatísticas de aplicativo prontos em data.daily_personalized_stats. Estes são ideais para cartões e widgets de resumo. Gatilho de ativação: period=daily e solicitação de nascimento personalizada inclui tanto birth_time quanto coordinates. Blocos-chave:

• overall_pulse — pontuação diária composta de vitalidade

• archetype_scores — análise em oito dimensões (wisdom, creativity, confidence, intuition, allure, romance, career, emotions)

• harmony_discord — 4 signos principais harmoniosos e 4 signos principais discordantes

• elemental_balance — fire/earth/air/water distribution

• momentum_channels — sinais de impulso planetário Controle de densidade de carga:

• daily_stats_detail: "full" para dados completos do gráfico com níveis de confiança por bloco- daily_stats_detail: "compact" para payloads de cliente mais leves (ideal para widgets móveis)

Destaques no Design da Requisição¶

The engine supports clear, typed controls for astrological configuration and rendering behavior. Opções comuns incluem:

Garantias de Formato de Resposta na Gateway¶

As respostas da Gateway incluem dados do motor e adicionam wrappers:

• _enterprise — informações sobre o nível do plano, quota e limite de taxa
• _api_metadata_ — informações sobre o endpoint, idiomas suportados e contexto da solicitação

Para endpoints de relatório com suporte do motor, _api_metadata_.supported_languages é apenas em inglês:

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

Política de Idioma e Tradução¶

Endpoints de relatórios com motor em tempo real atualmente suportam apenas lang=en. Isso é intencional para preservar a nuance editorial determinística em produção enquanto a confiabilidade da tradução é curada separadamente. As camadas de ajuda de tradução do gateway (lang=en|es|de|fr|pt) fornecem saída traduzida na fronteira da API para todos os endpoints de relatórios que não são de horóscopo.

Pipeline de Conteúdo: Pacotes de Conteúdo V2¶

Conteúdo editorial é proveniente de pacotes de conteúdo V2 estruturados no repositório de conteúdo do motor. At runtime, the content repository selects variants deterministically via stable hash selection with a four-level fallback chain:

1. Correspondência exata (tipo_fator + valor_fator + intensidade)

---2. Qualquer valor para factor_type ( factor_type + intensity)

• FIM MARKDOWN ---3. Qualquer fator na seção (seção + intensidade)

---4. Modelo de template de fallback de seção

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

Modelo de Confiança: Núcleo Fechado + Código Aberto Leve¶

Nosso motor principal de produção é de código fechado e otimizado para confiabilidade empresarial, profundidade e operações gerenciadas. Inclui:

• Relatórios personalizados completos, considerando todos os períodos
• Relatórios do ciclo de aniversário com fatores de retorno solar
• Conjuntos de relatórios de planeta, aspecto, trânsito, casa e planeta-casa
• Mapa astral natal com renderização SVG configurável
• Cache Redis, métricas, verificações de saúde e escalabilidade horizontal

Para apoiar astrólogos independentes e avaliação de desenvolvedores, também fornecemos o motor de código aberto lite:

• Site OpAstro
• GitHub OpAstro
• PyPI OpAstro

Use o OpAstro para avaliar a qualidade do motor, explorar a lógica de cálculo de fatores e verificar a integração com Swiss Ephemeris. Escalone para as rotas empresariais da NumerologyAPI para camadas de relatórios mais ricas, cobertura mais ampla de endpoints e operações de produção gerenciadas.

Caminho de Integração1. Comece com relatórios públicos de nível de assinatura — diários/semanais/mensais/anuais usando apenas sign. Não são necessários dados de nascimento. Cache de forma eficiente.¶

1. Adicione campos de nascimento personalizados — forneça birth_time + coordenadas para desbloquear edições diferenciadas com fatores conscientes da casa.
2. Crie famílias de relatórios especializadas — planetas, aspectos, transitos e pontos de extremidade da casa para superfícies de produtos mais profundas.
3. Adicione pontos de extremidade de nascimento — JSON completo do mapa de nascimento + roda SVG para visualização e fluxos de trabalho astrológicos avançados.
4. Otimize com seções — solicite apenas a sections que sua interface de usuário precisa (por exemplo, ["general", "career"]) para reduzir o tamanho do payload.
5. Use tenant_id para isolamento de cache — nivele tiers gratuitos/premium ou variantes de teste A/B sem poluição de cache.

Estratégia de Cache¶

Próxima Leitura¶

• Visão Geral da API de Relatórios de Horóscopo
• Horóscopo de Hoje
• Horóscopo Semanal
• Horóscopo Mensal
• Horóscopo Anual
• Horóscopo de Aniversário
• Mapa de Nascimento