README.md

metadata

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

# 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)

• Basic Gradio interface
• Essential dignity calculator
• Lot calculator (Fortune, Spirit)
• Annual profections
• Educational content
• 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