docs/PROJECT_DOCUMENTATION.md

Project Documentation: KP AI Astrologer

1. Introduction

This document outlines the architecture, features, and implementation plan for the KP AI Astrologer, a tool for predicting cricket match outcomes using KP astrology.

2. System Architecture

The application will be built with a modular architecture to separate concerns and facilitate focused development.

• Frontend (app): A Streamlit-based web interface for user input (match details) and displaying the astrological analysis.
• Backend Core (kp_core): A Python-based engine responsible for all astrological calculations.
  • kp_engine.py: Handles the generation of the Muhurta chart, planetary positions, cusps, and other core astrological details.
  • timeline_generator.py: Constructs the dynamic Ascendant and Moon timelines based on SSL transitions, ensuring no duplicate entries.
  • analysis_engine.py: Contains the logic for interpreting the astrological data and generating predictive text (Muhurta analysis, timeline verdicts, and comments).
• Configuration (config): Stores static data required for calculations, such as Nakshatra lords, Sub lords, etc.
• Scripts (scripts): Contains standalone scripts for testing, data generation, or debugging specific functionalities.

3. Core Features & Implementation Plan

Phase 1: Foundation and Core Logic

1. Project Setup (Complete):

   • Create directory structure.
   • Initialize README.md and PROJECT_DOCUMENTATION.md.
   • Create requirements.txt.

2. Path Correction:

   • Implement the sys.path modification at the entry point of the application (app/main_dashboard.py) to ensure all modules are imported correctly across the project structure.

3. Core KP Engine (kp_core/kp_engine.py):

   • Port and adapt the core KP functions from the reference repository.
   • Develop functions to calculate:
     • Ascendant and Moon longitude.
     • Planetary positions for a given time and location.
     • Cusp positions.
     • Planetary lordships (Nakshatra, Sub, Sub-Sub).
     • House significators.

Phase 2: Timeline Generation

1. Timeline Generator (kp_core/timeline_generator.py):
   • Implement the logic to calculate SSL transition times with second-level precision for a given celestial body (Ascendant or Moon).
   • The timeline should be generated for the duration of the match.
   • Incorporate the de-duplication logic from the reference project to handle rapid transitions.
   • The output for each interval should include:
     • Start and End Time.
     • Ruling Lords: Nakshatra Lord (NL), Sub Lord (SL), Sub-Sub Lord (SSL).

Phase 3: Dashboard and UI

1. Main Dashboard (app/main_dashboard.py):
   • Create the Streamlit interface.
   • Input Sidebar:
     • Date of Match
     • Time of Match (local)
     • Timezone
     • Location (Latitude, Longitude)
     • Team A (Ascendant)
     • Team B (Descendant)
   • Display Area:
     • A tabbed or sectioned layout.
     • A placeholder for the three main prediction outputs.

Phase 4: AI Analysis and Final Output

1. Analysis Engine (kp_core/analysis_engine.py):

   • Muhurta Analysis: Develop a function that takes the generated Muhurta chart and produces a textual analysis of which team is favored, based on KP principles (e.g., strength of Ascendant lord, cusp significations).
   • Timeline Analysis: Develop a function that iterates through the generated timelines (Ascendant and Moon) and, for each interval, provides:
     • Verdict: "Favors Team A", "Favors Team B", "Neutral".
     • Comment: A descriptive astrological reason (e.g., "SSL is a strong significator for houses 6 & 11, indicating victory over opponents," or "SSL in the star of a planet in the 12th house may cause an unexpected loss/wicket.").

2. Integration and Display:

   • Integrate the analysis engine with the main dashboard.
   • On form submission, trigger the full pipeline: Chart -> Timelines -> Analysis.
   • Display the three distinct outputs clearly in the UI:
     1. Muhurta Chart Analysis.
     2. Ascendant CSSL Timeline Table.
     3. Moon SSL Timeline Table.