---
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*