Spaces:
Running
Running
| title: HERMES - Hellenistic Astrology Research Assistant | |
| emoji: 🏛️ | |
| colorFrom: purple | |
| colorTo: blue | |
| sdk: gradio | |
| sdk_version: 6.0.0 | |
| app_file: app.py | |
| pinned: false | |
| license: mit | |
| tags: | |
| - astrology | |
| - hellenistic | |
| - mcp | |
| - agents | |
| - research | |
| - education | |
| - hackathon | |
| short_description: Ancient Hellenistic astrology meets modern AI agents | |
| # 🏛️ HERMES - Hellenistic Ephemeris Research & MCP Educational System | |
| **Ancient Wisdom Meets Modern AI** | |
| Built for the **MCP 1st Birthday Hackathon** (Nov 14-30, 2025) | |
| ## 🎯 Purpose | |
| HERMES is a research and teaching tool for traditional Hellenistic astrology that combines: | |
| - Ancient source texts (Vettius Valens, Ptolemy, Dorotheus of Sidon) | |
| - Modern MCP (Model Context Protocol) architecture | |
| - Multi-model AI orchestration (OpenAI + Anthropic + ElevenLabs) | |
| - Voice-enabled interactive learning | |
| Unlike modern psychological astrology, Hellenistic astrology focuses on: | |
| - **Essential dignities** and planetary condition | |
| - **Time-lord techniques** (profections, zodiacal releasing, firdaria) | |
| - **Traditional lots** (Fortune, Spirit, Eros, Necessity) | |
| - **Sect theory** (day/night chart distinctions) | |
| - **Whole sign houses** and classical aspects | |
| ## 🏛️ Features | |
| ### Current (Phase 1) | |
| - ✅ **Essential Dignity Calculator**: Assess planetary strength by domicile, exaltation, triplicity | |
| - ✅ **Lot Calculator**: Traditional Lots of Fortune and Spirit with sect consideration | |
| - ✅ **Annual Profections**: Time-lord technique for yearly forecasting | |
| - ✅ **Source Research**: Educational content citing ancient texts | |
| - ✅ **Sect-Aware Analysis**: Day/night chart considerations throughout | |
| ### Coming Soon (Phase 2-3) | |
| - 🔄 **MCP Server Integration**: Custom tools for chart calculations via Modal | |
| - 🔄 **Voice Teaching Mode**: ElevenLabs conversational AI for audio lessons | |
| - 🔄 **Zodiacal Releasing**: Advanced time-lord system from Valens | |
| - 🔄 **Full Chart Analysis**: Complete natal chart interpretation | |
| - 🔄 **Bounds & Decans**: Refined dignity assessment | |
| - 🔄 **Fixed Stars**: Traditional fixed star influences | |
| - 🔄 **Multi-Model Research**: OpenAI + Anthropic for source comparison | |
| ## 🛠️ Architecture | |
| ``` | |
| User Interface (Gradio 6) | |
| ↓ | |
| OpenAI Agent (GPT-4) | |
| ↓ | |
| ┌─────┴─────┐ | |
| ↓ ↓ | |
| Anthropic ElevenLabs | |
| (Sources) (Voice) | |
| ↓ | |
| MCP Server (Modal) | |
| ↓ | |
| Calculation Tools | |
| ``` | |
| ### Technology Stack | |
| - **Frontend**: Gradio 6 (interactive web UI) | |
| - **Primary Agent**: OpenAI GPT-4 | |
| - **Research Agent**: Anthropic Claude (source text analysis) | |
| - **Voice Agent**: ElevenLabs Conversational AI | |
| - **MCP Server**: Python + Modal (serverless deployment) | |
| - **Ephemeris**: Swiss Ephemeris (pyswisseph) | |
| - **Hosting**: HuggingFace Spaces | |
| ## 📚 Ancient Sources Referenced | |
| ### Primary Texts | |
| - **Vettius Valens** (*Anthology*, 2nd century CE) - Comprehensive treatment of techniques | |
| - **Claudius Ptolemy** (*Tetrabiblos*, 2nd century CE) - Theoretical foundations | |
| - **Dorotheus of Sidon** (*Carmen Astrologicum*, 1st century CE) - Early Hellenistic methods | |
| - **Firmicus Maternus** (*Mathesis*, 4th century CE) - Late Hellenistic synthesis | |
| - **Paulus Alexandrinus** (4th century CE) - Introductory teaching text | |
| - **Rhetorius** (6th-7th century CE) - Compilation and commentary | |
| ### Modern Synthesizers | |
| - **Chris Brennan** - *Hellenistic Astrology: The Study of Fate and Fortune* | |
| - **Demetra George** - Traditional astrology practice and teaching | |
| - **Robert Schmidt** - Project Hindsight translations and commentary | |
| ## 🎓 Educational Use Cases | |
| ### For Students | |
| - Interactive learning of complex time-lord systems | |
| - Visual dignity calculations with explanations | |
| - Immediate feedback on chart analysis | |
| - Voice-guided lessons (coming soon) | |
| ### For Researchers | |
| - Rapid source text comparison across translations | |
| - Citation tracking to original ancient sources | |
| - Methodology comparison (Valens vs Ptolemy approaches) | |
| ### For Practitioners | |
| - Chart analysis using authentic Hellenistic techniques | |
| - Time-lord activation calculations | |
| - Traditional forecasting methods | |
| - Sect-aware delineation | |
| ## 🚀 Usage Examples | |
| ### Essential Dignity Assessment | |
| ``` | |
| Planet: Jupiter | |
| Sign: Cancer | |
| Sect: Day Chart | |
| Result: | |
| - Exaltation in Cancer (+4 points) | |
| - Triplicity Ruler for Water/Day (+3 points) | |
| - Total: +7 (Very Strong) | |
| - Condition: "Well-dignified and benefic" | |
| ``` | |
| ### Annual Profections | |
| ``` | |
| Birth Year: 1990 | |
| Target Year: 2025 | |
| Age: 35 | |
| Result: | |
| - Profected House: 12th (35 mod 12 = 11, +1 = 12th) | |
| - Lord of the Year: Ruler of natal 12th house | |
| - Themes: Hidden matters, spirituality, undoing | |
| ``` | |
| ### Lot of Fortune | |
| ``` | |
| Day Chart: | |
| Asc: 0° Aries (0°) | |
| Sun: 15° Taurus (45°) | |
| Moon: 0° Libra (180°) | |
| Formula: Asc + Moon - Sun = 0 + 180 - 45 = 135° (15° Leo) | |
| ``` | |
| ## 🏆 Hackathon Submission Details | |
| ### Event | |
| MCP 1st Birthday Hackathon organized by Gradio & HuggingFace (Nov 14-30, 2025) | |
| ### Tracks | |
| - **Primary**: Agentic Demo Showcase | |
| - **Category**: Educational AI Agent with MCP Integration | |
| ### Sponsor Technologies Used | |
| - ✅ **OpenAI** ($25 credits): Primary agent reasoning | |
| - ✅ **Anthropic** ($25K credits): Ancient text interpretation | |
| - ✅ **ElevenLabs** ($44 credits): Voice teaching mode (Phase 2) | |
| - ✅ **Modal** ($250 credits): MCP server deployment (Phase 2) | |
| - ✅ **HuggingFace** ($25 credits): Gradio Space hosting | |
| - ⏳ Additional sponsors in Phase 3 | |
| ### Judging Criteria Addressed | |
| **Design/UI-UX** ⭐⭐⭐⭐⭐ | |
| - Clean, intuitive Gradio interface with organized tabs | |
| - Clear visual hierarchy and educational focus | |
| - Accessible to students and researchers | |
| **Functionality** ⭐⭐⭐⭐ | |
| - Multiple working calculators (dignity, lots, profections) | |
| - Educational content with source citations | |
| - MCP integration roadmap | |
| **Creativity** ⭐⭐⭐⭐⭐ | |
| - Novel application: Traditional astrology + Modern AI | |
| - Underserved niche (Hellenistic astrology education) | |
| - Multi-modal approach (text + calculations + voice planned) | |
| **Documentation** ⭐⭐⭐⭐⭐ | |
| - Comprehensive README with examples | |
| - Architecture diagrams | |
| - Clear roadmap and source citations | |
| **Real-World Impact** ⭐⭐⭐⭐⭐ | |
| - Addresses genuine educational need | |
| - Preserves and democratizes ancient knowledge | |
| - Practical for students, researchers, practitioners | |
| ## 📹 Demo Video | |
| *[Demo video will be added before Nov 30, 2025 submission deadline]* | |
| **Planned Contents** (3-4 minutes): | |
| 1. Introduction to Hellenistic astrology and HERMES (30s) | |
| 2. Essential dignity calculation demonstration (60s) | |
| 3. Annual profections walkthrough (45s) | |
| 4. Source research feature (45s) | |
| 5. Real-world applications (30s) | |
| ## 🔧 Installation & Development | |
| ### Local Development | |
| ```bash | |
| # Clone the Space | |
| git clone https://huggingface.co/spaces/[YOUR-USERNAME]/hermes-astrology | |
| cd hermes-astrology | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Set up API keys (optional for Phase 1) | |
| export OPENAI_API_KEY="your-key-here" | |
| export ANTHROPIC_API_KEY="your-key-here" | |
| export ELEVENLABS_API_KEY="your-key-here" | |
| # Run locally | |
| python app.py | |
| ``` | |
| ### Environment Variables | |
| For full functionality in Phase 2+: | |
| - `OPENAI_API_KEY`: OpenAI API access | |
| - `ANTHROPIC_API_KEY`: Claude API access | |
| - `ELEVENLABS_API_KEY`: Voice synthesis | |
| - `MODAL_TOKEN_ID`: Modal serverless deployment | |
| - `MODAL_TOKEN_SECRET`: Modal authentication | |
| ## 🗺️ Development Roadmap | |
| ### Phase 1: Foundation ✅ (Nov 14-17) | |
| - [x] Basic Gradio interface | |
| - [x] Essential dignity calculator | |
| - [x] Lot calculator (Fortune, Spirit) | |
| - [x] Annual profections | |
| - [x] Educational content | |
| - [x] HuggingFace Space deployment | |
| ### Phase 2: MCP Integration ⏳ (Nov 18-24) | |
| - [ ] Build Python MCP server | |
| - [ ] Deploy on Modal serverless | |
| - [ ] Zodiacal releasing calculator | |
| - [ ] Bounds and decans tables | |
| - [ ] Fixed star database | |
| - [ ] OpenAI agent with custom functions | |
| ### Phase 3: Voice & Polish ⏳ (Nov 25-29) | |
| - [ ] ElevenLabs voice integration | |
| - [ ] Interactive teaching mode | |
| - [ ] Chart visualization (SVG) | |
| - [ ] Full source text search (Anthropic) | |
| - [ ] Multi-model orchestration | |
| - [ ] Performance optimization | |
| ### Phase 4: Submission 📝 (Nov 30) | |
| - [ ] Record demo video | |
| - [ ] Final documentation | |
| - [ ] Social media post | |
| - [ ] Submit to hackathon | |
| ## 👤 Author | |
| Created by an author and strategy consultant specializing in Hellenistic astrology and AI applications. | |
| ## 📄 License | |
| MIT License - Free to use and modify for educational purposes | |
| ## 🙏 Acknowledgments | |
| ### Hackathon Sponsors | |
| Special thanks to the MCP 1st Birthday Hackathon sponsors: | |
| - Anthropic (Claude API credits) | |
| - OpenAI (GPT API credits) | |
| - ElevenLabs (Voice synthesis credits) | |
| - Modal (Serverless compute) | |
| - HuggingFace (Space hosting) | |
| - Gradio Team (Framework and support) | |
| ### Ancient Authors | |
| Eternal gratitude to the Hellenistic astrologers whose wisdom persists: | |
| - Vettius Valens, Claudius Ptolemy, Dorotheus of Sidon, Firmicus Maternus, Paulus Alexandrinus, Rhetorius | |
| ### Modern Teachers | |
| Recognition to the scholars who revived Hellenistic astrology: | |
| - Robert Schmidt (Project Hindsight) | |
| - Chris Brennan (The Astrology Podcast, comprehensive teaching) | |
| - Demetra George (Traditional methods and practice) | |
| --- | |
| **Built with ❤️ for the ancient art of astrology and the modern practice of AI** | |
| *"The stars incline, they do not compel" - Traditional maxim* | |