astrology-backend-integration

このスキルでは、予測や鑑定を行うために占星術 API と AI／LLM システムを統合する、ヴェーダ占星術バックエンドの実装方法を説明します。占星術アプリケーションに固有のパターン、データ構造、ベストプラクティスをまとめています。

このスキルを使用するタイミング

次のような場合に、このスキルを適用してください。

• ヴェーダ占星術の鑑定プラットフォームを構築する
• 占星術 API（AstrologyAPI.com、Prokerala など）を統合する
• クンドリー（出生図）を生成して保存する
• ダシャーに基づく予測を実装する
• ドーシャ（マンガリク、ピトリなど）を検出する
• 宝石やルドラークシャを推奨する
• AI を活用した占星術コンサルタントを作成する
• 家族やメンバーの出生図管理に対応する
• 相性診断・マッチングシステムを構築する

前提条件

このスキルを使用する前に、次の条件を満たしている必要があります。

• ai-integrated-api-backend スキルを完了している（または外部 API と AI の統合について理解している）
• ヴェーダ占星術の基本概念を理解している
• 占星術 API プロバイダーを利用できる

占星術の基礎知識

基本概念

クンドリー（出生図）

• 人の占星術的なプロフィール全体を表します
• 必要な情報：出生年月日、出生時刻、出生地（緯度／経度）
• タイムゾーン：精度を確保するうえで重要です（インドの場合、デフォルトの IST = 5.5）
• 構成要素：チャート、惑星、ダシャー、ドーシャ、対処法

チャート（分割図）

• D1（ラーシチャート）：メインの出生図。12 室で構成されます
• D9（ナヴァーンシャ）：結婚と精神性を表すチャートです
• 特定の人生の領域を分析するためのその他の分割図（D10、D60 など）

ハウス（バーヴァ）

• 人生の領域を表す12のハウスです
• 重要な対応関係：
  • ハウス1：自分、健康、性格
  • ハウス2：富、家族、話し方
  • ハウス4：母親、不動産、幸福
  • ハウス5：子ども、教育、創造性
  • ハウス7：結婚、パートナーシップ
  • ハウス10：仕事、評判、父親
  • ハウス11：利益、友人、願望
  • ハウス12：損失、精神性、外国

惑星（グラハ）

• ヴェーダ占星術で扱う9つの惑星：
  • 太陽（スーリヤ）：権威、自分、エゴ
  • 月（チャンドラ）：心、感情、母親
  • 火星（マンガル）：エネルギー、勇気、対立
  • 水星（ブダ）：コミュニケーション、知性
  • 木星（グル）：知恵、発展、幸運
  • 金星（シュクラ）：愛、関係、ぜいたく
  • 土星（シャニ）：規律、カルマ、遅延
  • ラーフ：欲望、執着、異国
  • ケートゥ：執着からの解放、精神性、前世

サインの支配星（黄道十二宮の支配星）

• それぞれのサインは惑星に支配されています。
  • 牡羊座 → 火星
  • 牡牛座 → 金星
  • 双子座 → 水星
  • 蟹座 → 月
  • 獅子座 → 太陽
  • 乙女座 → 水星
  • 天秤座 → 金星
  • 蠍座 → 火星
  • 射手座 → 木星
  • 山羊座 → 土星
  • 水瓶座 → 土星
  • 魚座 → 木星

ダシャー（惑星の運行期間）

• ヴィムショッタリー・ダシャー：120年周期
• 構造：主要期（マハーダシャー）→ 副次期（アンタルダシャー）→ さらに細分化された期間（プラティヤンタル）
• 各惑星には、それぞれ特定の運行年数が割り当てられています
• 予測の時期を判断するうえで重要です：「X はいつ起こるのか？」

ドーシャ（障害）

• マンガリク・ドーシャ：特定のハウス（1、2、4、7、8、12）に火星がある状態
  • 結婚の相性に影響します
  • パーセンテージ（0～100％）で測定されます
  • 解消条件があります（例：両者がマンガリクの場合）
• ピトリ・ドーシャ：先祖から受け継いだ負債
  • ラーフ／ケートゥによって太陽／月が傷つけられている状態
  • 対処法：プージャ、慈善活動

対処法

• 宝石：弱い惑星を強めます
  • 各惑星には対応する宝石があります（太陽にはルビー、月には真珠など）
  • 指、曜日、金属を指定して身に着けます
  • カラット数が指定されます
• ルドラークシャ：精神的な対処法に用いる数珠
  • 惑星ごとに異なるムキー（面数）があります
  • 守護とバランスを目的に身に着けます
• プージャ／マントラ：儀式による対処法

占星術 API の統合パターン

ステップ 1：占星術 API プロバイダーを選ぶ

主な選択肢：

• AstrologyAPI.com (https://json.astrologyapi.com/)
• Prokerala API
• GeoVedic API
• AstroSage API

必要となることの多い機能：

• 出生図の生成（D1、D9）
• ナクシャトラを含む惑星の位置
• ヴィムショッタリー・ダシャー
• ドーシャ分析（マンガリク、ピトリ、カール・サルプなど）
• 宝石／ルドラークシャの提案
• パンチャンガ（毎日の暦）
• 相性診断／マッチング

ステップ 2：API エンドポイントのマッピング

必須エンドポイント（AstrologyAPI.com の例）：

Base URL: https://json.astrologyapi.com/

1. POST /v1/horo_chart/{chart_id}
   - Get D1 (chart_id=D1), D9 (chart_id=D9), etc.
   - Returns: List of 12 houses with sign and planets

2. POST /v1/planets
   - Get detailed planetary positions
   - Returns: Planet positions, retrograde status, nakshatra, longitude

3. POST /v1/astro_details
   - Get basic astrological details
   - Returns: Ascendant, rasi, nakshatra, etc.

4. POST /v1/current_vdasha
   - Get current dasha period
   - Returns: Major, minor, sub-minor planet and dates

5. POST /v1/current_vdasha_all
   - Get complete dasha timeline
   - Returns: All major/minor/sub-minor periods from birth to 120 years

6. POST /v1/manglik
   - Check Manglik dosha
   - Returns: Manglik status, percentage, explanation

7. POST /v1/pitra_dosha_report
   - Check Pitra dosha
   - Returns: Present/absent, explanation

8. POST /v1/basic_gem_suggestion
   - Get gemstone recommendation
   - Returns: Gemstone, metal, finger, day, deity, mantra, carat weight

9. POST /v1/rudraksha_suggestion
   - Get Rudraksha recommendation
   - Returns: Mukhi number, ruling planet, benefits

10. POST /v1/puja_suggestion
    - Get puja recommendations
    - Returns: Puja type, purpose, timing

ステップ 3：基本ペイロードの構造

標準的な出生情報ペイロード：

{
  "day": 15,           // Day of birth (1-31)
  "month": 6,          // Month (1-12)
  "year": 1990,        // Year (YYYY)
  "hour": 14,          // Hour in 24-hour format (0-23)
  "min": 30,           // Minute (0-59)
  "lat": 28.7041,      // Latitude (decimal)
  "lon": 77.1025,      // Longitude (decimal)
  "tzone": 5.5         // Timezone offset (5.5 for IST)
}

重要な考慮事項：

• タイムゾーン：正確である必要があります。インドのデフォルトの IST は 5.5 です
• 時刻形式：12 時間制の AM/PM ではなく、24 時間制を使用します
• 座標：正確な緯度・経度を取得するには、Google Maps Geocoding API などを使用します
• 日付の検証：有効な日付であることを確認します（2 月 30 日などは不可）

ステップ 4：API マネージャーの実装

役割：

• API で認証します（通常は HTTP Basic Auth または API Key）
• ユーザーの出生情報からペイロードを構築します
• 複数のエンドポイント（チャート、ダシャー、ドーシャ、改善策）を呼び出します
• API のレート制限とエラーを処理します
• 構造化されたレスポンスを返します

主なパターン：

API Manager Methods:
- get_horo_chart(birth_details, chart_id) → D1/D9 chart
- get_planets(birth_details) → Planet positions
- get_dasha(birth_details) → Current dasha
- get_dasha_all(birth_details) → Complete timeline
- get_manglik(birth_details) → Dosha status
- get_gem_suggestion(birth_details) → Remedies

並列フェッチ：

• ほとんどのエンドポイントは独立しています
• 非同期タスク（Celery など）を使用して並列にフェッチします
• 合計時間を 9×3s = 27s から約 3s に短縮できます

データストレージのパターン

データベーススキーマの設計

コレクション 1：ユーザーの出生情報（user_metadata）

{
  "user_id": 12345,
  "dob_full_name": "John Doe",
  "dob_gender": "male",
  "dob_day": 15,
  "dob_month": 6,
  "dob_year": 1990,
  "dob_hour": 14,
  "dob_minute": 30,
  "dob_lat": 28.7041,
  "dob_long": 77.1025,
  "dob_city": "New Delhi",
  "dob_state": "Delhi",
  "created_on": "2024-01-15T10:00:00Z",
  "updated_on": "2024-01-15T10:00:00Z"
}

コレクション 2：占星術の生データ（user_astro_metadata）

{
  "user_id": 12345,
  "astro_details": { /* API response */ },
  "horo_d1_chart_data": { /* D1 chart response */ },
  "horo_d9_chart_data": { /* D9 chart response */ },
  "planet_chart_data": { /* Planets response */ },
  "current_vdasha": { /* Current dasha */ },
  "current_vdasha_all": { /* Complete dasha */ },
  "manglik": { /* Manglik dosha */ },
  "pitra_dosha_report": { /* Pitra dosha */ },
  "basic_gem_suggestion": { /* Gemstone */ },
  "rudraksha_suggestion": { /* Rudraksha */ },
  "created_on": "2024-01-15T10:05:00Z",
  "updated_on": "2024-01-15T10:05:00Z"
}

コレクションを 2 つに分ける理由

• 出生情報はほとんど変更されません（不変です）
• 占星術データは更新できます（ダシャーは時間の経過とともに変化します）
• 分離することで、個別に更新できます

家族・メンバーのサポート

コレクション 3：家族メンバーの出生情報（user_member_metadata）

{
  "_id": "member_unique_id",
  "user_id": 12345,
  "relation": "spouse",
  "dob_full_name": "Jane Doe",
  "dob_gender": "female",
  "age": 32,
  "dob_day": 20,
  "dob_month": 8,
  "dob_year": 1992,
  // ... same birth detail fields
}

コレクション 4：家族メンバーの占星術データ（user_member_astro_metadata）

{
  "user_id": 12345,
  "member_id": "member_unique_id",
  // ... same astro data fields as user_astro_metadata
}

関係の種類：

• "self"（メインユーザー）
• "spouse"、"mother"、"father"
• "son"、"daughter"、"child"
• "brother"、"sister"
• 必要に応じてカスタムの関係を指定できます

クンドリー変換のパターン

問題の説明

課題：API レスポンスは入れ子構造で冗長なうえ、キーの命名に一貫性がありません。これを、明確で AI に適した構造に変換する必要があります。

API レスポンスの問題例：

• 大文字・小文字が混在するキー："Sign"、"sign"、"SIGN"
• 冗長な記述："7 室の火星により、その人は 28.5% のマンガリクです..."
• 深く入れ子になった構造：ハウス → サイン → 惑星 → 詳細
• 文字列形式：構造化データではなく "Mars(Retrograde)"

解決策：複数ステップの変換パイプライン

ステップ 1：キーの正規化

• すべてのキーを小文字に変換します
• 入れ子になったオブジェクトを再帰的に処理します
• 配列の構造を標準化します

ステップ 2：チャートの変換

• ハウスのリストを辞書に変換します（ハウス番号 → 詳細）
• 各ハウスからサインを抽出します
• サインをサインの支配星に対応付けます（Aries → Mars）
• 各ハウスの惑星を抽出します

ステップ 3：惑星情報の拡充

• 惑星の文字列を解析します："Mars(Retrograde)" → {name: "Mars", isRetrograde: true}
• ナクシャトラ、経度、位置を追加します
• 吉星・凶星の状態を示します

ステップ 4：ダシャーのタイムラインの構築

• 日付文字列を ISO 形式に解析します
• 現実的な期間を対象に絞ります（例：2010 年から current_year + 25 まで）
• 大期 → 中期 → 小期の階層構造にします

ステップ 5：ドーシャ値の抽出

• 冗長なレポートを主要な値にまとめます
• マンガリク：パーセンテージのみを抽出します
• ピトラ：該当するかどうかのみを抽出します

ステップ 6：改善策の形式化

• 宝石：名前、金属、指、曜日、カラットを抽出します
• ルドラークシャ：ムキー、惑星、効能を抽出します

出力：完全なクンドリー構造

Relation with user: self

Birth Details:
  name: John Doe
  gender: male
  date_of_birth: 15 Jun 1990
  time_of_birth: 02:30 PM
  place_of_birth: New Delhi, Delhi

D1 Chart:
  House 1:
    sign: Aries
    sign_lord: Mars
    planets:
      - name: Sun
        isRetrograde: false
        nakshatra: Ashwini
        longitude: 65.23
      - name: Mercury
        isRetrograde: true
        nakshatra: Bharani
        longitude: 72.45
  House 2:
    sign: Taurus
    sign_lord: Venus
    planets: []
  # ... Houses 3-12

D9 Chart:
  # Same structure as D1

Dasha Timeline:
  - major_planet: Venus
    start_date: 2015-05-01
    end_date: 2035-05-01
    minor_periods:
      - planet: Venus
        start_date: 2015-05-01
        end_date: 2018-09-01
      - planet: Sun
        start_date: 2018-09-01
        end_date: 2019-09-01
      # ... more minor periods

Current Dasha:
  major: Venus
  minor: Moon
  sub_minor: Mars

Doshas:
  manglik_percentage: 28.5
  pitra_dosha_present: false

Remedies:
  gemstone:
    name: Diamond
    metal: Silver
    finger: Middle
    day: Friday
    carat: 2-3
  rudraksha:
    mukhi: 6
    ruling_planet: Venus
    benefits: "Harmony, love, relationships"

AI プロンプト統合のパターン

コンテキストの組み立て

注入するコンポーネント：

1. 完全なクンドリー（上記の YAML 形式）
2. クエリに応じたハウスのマッピング
3. 性別を考慮した解釈ルール
4. 時期判定に使う現在のダシャー
5. 言語設定（Hindi/English）

システムプロンプトの構造：

You are an expert Vedic astrologer with deep knowledge of:
- Planetary positions and aspects
- House significations
- Dasha timing predictions
- Dosha analysis and remedies

User's Complete Birth Chart:
<kundli>
[YAML kundli structure here]
</kundli>

Query Analysis Rules:
- Marriage questions → Focus on House 7, Venus, Jupiter
- Career questions → Focus on House 10, Saturn, Sun
- Finance questions → Focus on House 2, 11, Jupiter
- Health questions → Focus on House 1, 6, planets in these houses
- Children questions → Focus on House 5, Jupiter
- Property questions → Focus on House 4, Mars

Gender-Specific Rules:
- For females: Jupiter = husband, Venus = marriage
- For males: Venus = wife, Mars = passion

Timing Predictions:
- Use current dasha: [Major/Minor/Sub-minor]
- Consider transits for immediate events
- Dasha changes indicate life phase shifts

Response Format:
- Provide predictions based on chart analysis
- Cite specific planetary positions
- Mention relevant dasha periods
- Suggest remedies if doshas present
- Answer in [Hindi/English] as per user preference

クエリに応じたコンテキスト

結婚に関するクエリの例：

Query: "When will I get married?"

Additional Context:
- House 7 analysis: [Sign, Lord, Planets]
- Venus position: [House, Sign, Strength]
- Jupiter position: [House, Sign, Strength]
- Current dasha: [Will marriage planet dasha start soon?]
- Manglik dosha: [If yes, mention in prediction]

Prediction Approach:
1. Check House 7 lord strength
2. Check Venus/Jupiter periods in dasha
3. Look for favorable transits
4. Consider dosha impacts

キャリアに関するクエリの例：

Query: "What career is best for me?"

Additional Context:
- House 10 analysis: [Sign, Lord, Planets]
- Sun position: [Authority, leadership]
- Saturn position: [Discipline, perseverance]
- Mercury position: [Communication, intellect]
- Strongest planet in chart: [Natural talent]

Prediction Approach:
1. Identify dominant planets
2. Map to career domains (Sun→govt, Mercury→business, etc.)
3. Check House 10 lord placement
4. Consider current dasha planet's signification

高度な機能

互換性／マッチング（クンドリー・ミラン）

アシュタクート・システム（8項目のマッチング）：

1. ヴァルナ（1ポイント）：精神的な相性 2.ヴァーシャ（2ポイント）：相互の魅力
2. ターラー（3ポイント）：誕生星の相性
3. ヨーニ（4ポイント）：身体的な相性
4. グラハ・マイトリー（5ポイント）：精神的な相性
5. ガナ（6ポイント）：気質
6. バクート（7ポイント）：愛情と親愛
7. ナーディー（8ポイント）：健康と子孫

合計：最大36ポイント

• 18～24：平均的な相性
• 25～32：良い相性
• 33～36：非常に良い相性

実装：

• 両方のクンドリーが必要です
• マッチング API エンドポイントを呼び出します
• ポイントの内訳を表示します
• 両者がマンガリクの場合、マンガリクの解消を強調表示します

パンチャン（デイリーカレンダー）

構成要素：

• ティティ（太陰日）
• ヴァーラ（曜日）
• ナクシャトラ（月宿）
• ヨーガ（太陽と月の組み合わせ）
• カラナ（半ティティ）

ユースケース：

• ムフールタの選定（吉兆な時間）
• 祭日の確認
• 毎日のホロスコープの背景情報

トランジット予測

現在の惑星位置：

• 現在の日付の惑星位置を取得します
• 出生図と比較します
• アスペクト（合、衝、トライン、スクエア）を特定します
• 短期的な出来事を予測します

実装チェックリスト

フェーズ1：API のセットアップ

• 占星術 API プロバイダーを選択する
• 認証情報を設定する
• 必要なすべてのエンドポイントをテストする
• API レスポンスを内部モデルにマッピングする
• API 障害時のエラー処理を実装する

フェーズ2：データモデル

• 出生情報スキーマを作成する（user_metadata）
• 占星術データスキーマを作成する（user_astro_metadata）
• 家族サポート用のメンバースキーマを作成する
• インデックスを追加する（user_id、member_id）
• データ保持ポリシーを計画する

フェーズ3：クンドリーの構築

• キーの正規化を実装する
• チャート（D1、D9）を変換する
• 惑星の詳細情報を補完する
• ダシャーのタイムラインを構築する
• ドーシャの値を抽出する
• 改善策を整形する
• API レスポンスのサンプルでテストする

フェーズ4：AI の統合

• クンドリーのコンテキストを含むシステムプロンプトを設計する
• クエリの種類をハウスの重点項目にマッピングする
• 性別を考慮したルールを追加する
• 時期の予測にダシャーを含める
• ヒンディー語／英語の応答に対応する
• 予測の精度をテストする

フェーズ5：機能

• ユーザーのオンボーディング（出生情報の収集）
• 場所のオートコンプリート（Google Maps API）
• クンドリーの生成と表示
• 家族メンバーの管理
• 相性マッチング
• ドーシャの検出と改善策
• パンチャンの統合
• 毎日のホロスコープ

フェーズ6：最適化

• クンドリーのデータをキャッシュする（TTL は10～60分）
• API 呼び出しを並列化する（非同期タスク）
• 大きなクンドリーのコンテキストを圧縮する
• API の使用量とコストを監視する
• レート制限を実装する

フェーズ7：品質保証

• タイムゾーンの精度を検証する
• エッジケース（午前0時の出生、夏時間）をテストする
• ダシャーの計算を検証する
• ドーシャのロジックを確認する
• 占星術師によるユーザー受け入れテストを実施する
• 多言語テストを実施する

ベストプラクティス

精度を最優先

1. タイムゾーンは重要です：常に正確なタイムゾーンオフセットを使用します
2. 座標は重要です：ジオコーディングで正確な緯度／経度を取得します
3. 時刻形式：24時間形式を使用し、AM／PM の変換を検証します
4. 日付の検証：有効な日付と閏年を確認します

データ管理

1. 出生データと占星術データを分けます：出生情報は変更不可、占星術データは更新可能です
2. 適切にキャッシュします：クンドリーは頻繁には変わらないため、数時間キャッシュします
3. クンドリー形式にバージョンを付けます：将来のスキーマ変更に備えてバージョンフィールドを追加します
4. 監査証跡：デバッグ用に、すべてのクンドリー生成をログに記録します

AI プロンプトエンジニアリング

1. 構造化されたコンテキスト：明確なセクション分けに YAML／XML タグを使用します
2. クエリの分類：重点領域を判断するために、クエリを事前処理します
3. 引用：回答で惑星位置を引用するよう AI に指示します
4. フォールバック：チャートがクエリを裏付けない場合に対応します

ユーザーエクスペリエンス

1. 段階的な読み込み：詳細な分析の読み込み中は、基本的なチャートを表示します
2. 解説：占星術用語をわかりやすく説明します
3. 対処法：実践可能な対処法を必ず提示します
4. 同意：センシティブな出生データのプライバシーを守ります

よくある落とし穴

1. タイムゾーンの誤り：チャートがまったく異なる結果になります
2. 12時間制の午前・午後の混同：2:30 PM ≠ 14:30 であり、12時間の誤差が生じます
3. 逆行の無視：惑星の逆行によって解釈が変わります
4. ダシャーの固定化：ダシャーは時間とともに変化するため、定期的に更新してください
5. 予測の単純化しすぎ：AI には太陽星座だけでなく、詳細なコンテキストが必要です
6. 性別に関するコンテキストの不足：金星／木星の解釈は性別によって異なります
7. ドーシャの無視：マンガリック・ドーシャは結婚の予測において重要です

フレームワークへの適用

Django

• ドキュメントストレージに MongoDB を使用
• 非同期 API 呼び出しに Celery を使用
• クンドリーのキャッシュに Django cache を使用
• フロントエンド向けに REST API を使用

FastAPI

• Motor（非同期 MongoDB ドライバー）
• バックグラウンドタスクまたは Celery
• Redis キャッシュ
• リアルタイム予測に WebSocket を使用

Node.js (Express)

• MongoDB に Mongoose を使用
• ジョブキューに Bull を使用
• Redis キャッシュ
• リアルタイム処理に Socket.io を使用

Spring Boot

• Spring Data MongoDB
• Spring Async または RabbitMQ
• Spring Cache
• リアクティブ処理に WebFlux を使用

関連リソース

• ヴェーダ占星術の文献：Brihat Parashara Hora Shastra、Jaimini Sutras
• API プロバイダー：AstrologyAPI.com、Prokerala、GeoVedic
• ライブラリ：Swiss Ephemeris（惑星の計算）
• 用語：https://en.wikipedia.org/wiki/Hindu_astrology

まとめ

占星術バックエンドの構築には、以下が必要です。

1. ドメイン知識：ハウス、惑星、ダシャー、ドーシャを理解する
2. 正確なデータ：タイムゾーンと座標が重要です
3. 構造化された変換：冗長な API データを整理されたクンドリーに変換する
4. 豊富な AI コンテキスト：完全な出生チャートを LLM に提供する
5. クエリのインテリジェントな処理：ユーザーの質問を関連するチャートの項目に対応付ける
6. 対処法：実践可能なガイダンスを必ず提示する

このスキルは、AI 統合を備えた本番環境向けヴェーダ占星術システムの構築に必要なパターンとドメイン知識を提供します。完全な実装ガイダンスについては、ai-integrated-api-backend スキルと組み合わせてください。

重要な占星術データの項目：

• astro_details — 基本的な出生チャートの詳細
• horo_d1_chart_data — メインの出生チャート（ラーシ・チャート）
• horo_d9_chart_data — ナヴァーンシャの分割チャート
• planet_chart_data — 詳細な惑星の位置
• current_vdasha — 現在のヴィムショッタリ・ダシャーの期間
• current_vdasha_all — ダシャーの全期間
• manglik — マンガリック・ドーシャの分析
• pitra_dosha_report — ピトラ・ドーシャの分析
• basic_gem_suggestion — 宝石の推奨
• rudraksha_suggestion — ルドラクシャの数珠玉の推奨