cnwu16/vedic-astro-skills

1. What this repository is

This is not a single application; it is a multi-skill astrology toolkit packaged three ways for Antigravity, Claude Code, and Codex. The same domain logic is mirrored under antigravity/skills/, claude-code/skills/, and codex/skills/, with Codex also carrying agents/openai.yaml descriptors.

2. Top-level architecture

The system is organized around seven skills: vedic-calculator, vedic-reader, vedic-core, vedic-career, vedic-love, vedic-rectifier, and vedic-synastry. The first is the computational foundation; the others are analysis or correction layers built on its output.

3. Canonical data boundary

The key architectural contract is an intermediate artifact called structured_data.md. The calculator produces it, the reader can validate it, and all downstream analysis skills consume it. This makes the calculator the authoritative source for chart data.

4. Input ingestion and routing

User input can arrive as:

- birth details directly,

- a PDF/screenshot/text chart report,

- or two people’s charts for synastry.

The reader acts as the entry router: it extracts birth data when needed, or passes direct birth information to the calculator. If no usable input is present, it falls back to a guided prompt flow.

5. vedic-calculator subsystem

This is the local chart computation engine. It is Python-based and depends on:

- Swiss Ephemeris data (scripts/ephe/*.se1)

- PyJHora-derived logic for positions, dashas, divisional charts, ashtakavarga, and bhava calculations

- a Shadbala correction layer in shadbala_pyjhora.py

It is designed as fail-fast and uses setup_env.py to provision and verify the Python environment rather than relying on ad hoc package installation.

6. vedic-reader subsystem

The reader is the extraction + verification front end. It supports PDF/image/text-based chart intake, then cross-checks the extracted information against calculator output. The resources/ directory holds its validation rules and data contract, showing that the reader is a policy-driven parsing layer rather than a heavy computation layer.

7. vedic-core and report generation

vedic-core is the main interpretive analysis engine. It performs:

- planet-by-planet audit,

- D9 cross-checks,

- house diagnosis,

- and synthesized life-domain reporting.

Its resources/ folder contains the interpretive frameworks and QA rules, while scripts/report_builder.py suggests it can package analysis into a structured report output.

8. Specialized downstream analyses

vedic-career and vedic-love are domain-specific analyzers that reuse the same chart foundation but focus on different questions:

- career blueprinting over multiple chart layers,

- relationship timing and marriage-phase analysis.

vedic-rectifier is a separate correction pipeline that uses life events to infer birth time adjustments, and it has its own scan script plus a dedicated event-to-house mapping resource.

9. vedic-synastry as a separate two-chart boundary

vedic-synastry is architecturally distinct because it requires two structured chart inputs. It performs cross-chart relationship analysis using its own rulebooks and scripts:

- build_synastry_data.py

- validate_synastry_data.py

Its resources encode relationship frameworks, aspect policy, koota policy, and signal triage, which means the logic is rule-heavy and intentionally separated from single-person analysis.

10. Resources as domain policy, not code

The resources/ directories are an important boundary. They contain interpretation frameworks, validation rules, report rules, and house mappings. These files function like knowledge and policy packs that shape how the scripts interpret computed chart data.

11. Runtime and infrastructure

The repo is fundamentally local Python tooling, not a networked service. The README indicates support for Python 3.8–3.13 and no requirement for external APIs. The only bundled infrastructure-like dependency is the ephemeris data shipped inside the calculator skill.

12. Quality and control model

The system emphasizes validation over guesswork:

- environment checks before execution,

- numeric cross-validation,

- explicit rule-based analysis,

- and fail-fast behavior rather than fallback approximations.

For diagramming purposes, the main flow is: user input → reader/calculator → structured chart data → specialized analysis skills, with synastry as a separate two-input branch and rectifier as a correction loop.