🌟 SkyWhisper - Your Personal Astronomy Assistant

Discover what's visible in the night sky, right from your Telegram messenger 🔭

🚀 Quick Links

Features • Demo • Installation • Usage • Tech Stack • Contributing

📖 About

SkyWhisper is an intelligent Telegram bot that brings the wonders of astronomy to your fingertips. Simply message the bot with your location, and it will tell you exactly which celestial bodies are visible in your night sky right now!

Using advanced astronomical calculations and AI-powered natural language understanding, SkyWhisper provides:

🪐 Real-time planetary visibility from your location
🌙 Moon phase information and viewing times
⭐ Rise, set, and transit times for celestial objects
🌅 Best viewing recommendations for each object
🔭 Telescope observing tips

✨ Features

🌍 Location-Based Astronomy

Calculate celestial visibility from any coordinates on Earth
Support for latitude, longitude, and elevation
Automatic timezone handling

🤖 AI-Powered Responses

Natural language understanding powered by DeepSeek via OpenRouter
Conversational interface - just chat naturally!
Context-aware recommendations

🔭 Comprehensive Celestial Data

Planets: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune
Moon: Phase information, illumination percentage, viewing times
Sun: Position tracking (with safety warnings!)
Rise/set times and transit calculations
Altitude, azimuth, and magnitude data

⚡ Real-Time Processing

Instant calculations using the astronomy-engine library
Workflow-based architecture with Inngest
Memory persistence for conversation context

💬 Telegram Integration

Simple, intuitive chat interface
Works on all Telegram platforms (mobile, desktop, web)
No app installation required!

🎬 Demo

💬 Example Conversations

You: Hi! What can I see tonight?

Bot: Hello! I'd be happy to help you discover what's visible in 
the night sky! To provide accurate information, I'll need your 
location. Could you please share your approximate latitude and 
longitude, or just tell me your city?

You: I'm in Patna

Bot: Great! Let me check what's visible from Patna tonight...

Currently 4 celestial bodies are visible: Saturn, Neptune, Mars, 
and Mercury!

🪐 Saturn - Currently visible! Best viewing around 8:45 PM when 
it's highest in the sky. Perfect for telescope viewing - don't 
miss those spectacular rings!

♂️ Mars - Visible now! Sets in about 3.2 hours. The Red Planet 
is showing well tonight.

☿️ Mercury - Morning object: Rises at 5:23 AM. Best viewing 1-2 
hours after rise, just before sunrise.

🔵 Neptune - Currently visible but very faint (magnitude 7.8). 
You'll need a telescope to spot this one!

Would you like detailed information about any specific object?

🛠️ Tech Stack

Core Technologies

AI & APIs

Infrastructure

Key Libraries

astronomy-engine - Precise astronomical calculations
@mastra/core - Agent and workflow framework
@mastra/inngest - Workflow orchestration
@openrouter/ai-sdk-provider - AI model integration
ai (Vercel AI SDK) - LLM streaming and tool calling

📦 Installation

Prerequisites

Node.js >= 20.9.0
npm or yarn
A Telegram Bot Token (Get one from @BotFather)
OpenRouter API Key (Get one here)

Local Development

Clone the repository

git clone https://github.com/Aryan-git-byte/SkyWhisper.git
cd SkyWhisper

Install dependencies
```
npm install
```

Set up environment variables

Create a .env file in the root directory:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
OPENROUTER_API_KEY=your_openrouter_api_key
PORT=5000

Start the Inngest dev server

npm run dev:inngest
# Or manually:
./scripts/inngest.sh

Start the application
```
npm run dev
```

Set up Telegram webhook (for local testing, use ngrok)

# In a new terminal
ngrok http 5000

# Then set webhook
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-ngrok-url.ngrok.io/webhooks/telegram/action"}'

🚀 Deployment

Deploy to Render

Fork this repository
Create a new Web Service on Render
- Connect your GitHub repository
- Use the following settings:
  - Build Command: npm install && npm run build
  - Start Command: node scripts/start-render.js
  - Environment: Node

Set environment variables in Render Dashboard:

TELEGRAM_BOT_TOKEN=your_token
OPENROUTER_API_KEY=your_key
PORT=10000
NODE_ENV=production
MASTRA_HIDE_CLOUD_CTA=true

Deploy! Render will automatically build and deploy your bot

Set Telegram webhook to your Render URL:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.onrender.com/webhooks/telegram/action"}'

Deploy to Other Platforms

The bot can be deployed to any Node.js hosting platform. Key requirements:

Node.js 20.9.0 or higher
Persistent file system for SQLite (or configure PostgreSQL)
Support for long-running processes (for Inngest server)

💡 Usage

Basic Commands

Start a conversation
```
/start
```
or simply say "Hi!"

Ask about visibility

What can I see in the sky tonight?
What planets are visible?
I'm in [your city]

Get specific information

When does Jupiter rise?
Tell me about Saturn
What phase is the Moon?

Tips for Best Results

📍 Provide your location for accurate calculations
🌃 Ask about specific celestial objects for detailed info
🔭 Mention if you have a telescope for specialized tips
🌙 Check Moon phase for best stargazing nights

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                  Telegram User                       │
└────────────────┬────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────┐
│            Telegram Bot API (Webhook)                │
└────────────────┬────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────┐
│              Mastra Server (Hono)                    │
│  ┌──────────────────────────────────────────────┐  │
│  │   Telegram Trigger Handler                    │  │
│  └────────────────┬─────────────────────────────┘  │
└──────────────────┼────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│           Inngest Workflow Engine                    │
│  ┌──────────────────────────────────────────────┐  │
│  │  celestialTelegramWorkflow                    │  │
│  │                                                │  │
│  │  Step 1: useCelestialAgent                   │  │
│  │  ├─ Call Celestial Agent                     │  │
│  │  ├─ Use celestialVisibilityTool              │  │
│  │  └─ Generate AI response                     │  │
│  │                                                │  │
│  │  Step 2: sendTelegramReply                   │  │
│  │  └─ Send message back to user                │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│              Celestial Agent                         │
│  ┌──────────────────────────────────────────────┐  │
│  │  DeepSeek LLM (via OpenRouter)               │  │
│  │  + celestialVisibilityTool                    │  │
│  │  + Conversation Memory (SQLite)               │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────┐
│         Astronomy Engine Library                     │
│  (Planetary calculations & ephemeris data)           │
└─────────────────────────────────────────────────────┘

Key Components

Telegram Trigger: Receives webhook events from Telegram
Mastra Workflow: Orchestrates the bot's response pipeline
Celestial Agent: AI-powered assistant with astronomy knowledge
Visibility Tool: Performs astronomical calculations
Memory System: Maintains conversation context

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`TELEGRAM_BOT_TOKEN`	Your Telegram bot token from @BotFather	✅ Yes	-
`OPENROUTER_API_KEY`	API key for OpenRouter (DeepSeek)	✅ Yes	-
`PORT`	Port for the web server	❌ No	`5000`
`NODE_ENV`	Environment (development/production)	❌ No	`development`
`MASTRA_HIDE_CLOUD_CTA`	Hide Mastra cloud promotions	❌ No	`false`

Customization

Change AI Model

Edit src/mastra/agents/celestialAgent.ts:

model: openrouter("deepseek/deepseek-chat"), // Change this

Available models on OpenRouter:

openai/gpt-4-turbo
anthropic/claude-3-opus
google/gemini-pro

Modify Agent Instructions

Customize the agent's personality and behavior in src/mastra/agents/celestialAgent.ts:

instructions: `Your custom instructions here...`

Add New Tools

Create tools in src/mastra/tools/ and register them with the agent.

🧪 Testing

Run Type Checking

npm run check

Format Code

npm run format

Test Telegram Webhook (Local)

curl -X POST http://localhost:5000/webhooks/telegram/action \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "message_id": 1,
      "from": {"id": 123456789, "first_name": "Test"},
      "chat": {"id": 123456789, "type": "private"},
      "date": 1234567890,
      "text": "Hi"
    }
  }'

🤝 Contributing

Contributions are welcome! Here's how you can help:

Ways to Contribute

🐛 Report bugs
💡 Suggest new features
📝 Improve documentation
🔧 Submit pull requests
⭐ Star the repository

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow TypeScript best practices
Use Prettier for formatting: npm run format
Add comments for complex logic
Write descriptive commit messages

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Mastra - Powerful AI agent framework
astronomy-engine - Accurate astronomical calculations
OpenRouter - Access to DeepSeek AI
Telegram - Excellent bot platform
Render - Free hosting for the bot

📧 Contact

Aryan Kumar

GitHub: @Aryan-git-byte
Email: aryan17550@gmail.com

🌟 Support

If you find this project helpful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting new features
📢 Sharing with others

Made with ❤️ and ☕ by Aryan Kumar

SkyWhisper - Bringing the cosmos to your conversations

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.config/inngest		.config/inngest
.local/state/replit/agent		.local/state/replit/agent
scripts		scripts
src		src
.gitignore		.gitignore
.replit		.replit
LICENSE		LICENSE
README.md		README.md
docs-mastra.md		docs-mastra.md
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🌟 SkyWhisper - Your Personal Astronomy Assistant

🚀 Quick Links

📖 About

✨ Features

🌍 Location-Based Astronomy

🤖 AI-Powered Responses

🔭 Comprehensive Celestial Data

⚡ Real-Time Processing

💬 Telegram Integration

🎬 Demo

💬 Example Conversations

🛠️ Tech Stack

Core Technologies

AI & APIs

Infrastructure

Key Libraries

📦 Installation

Prerequisites

Local Development

🚀 Deployment

Deploy to Render

Deploy to Other Platforms

💡 Usage

Basic Commands

Tips for Best Results

🏗️ Architecture

Key Components

🔧 Configuration

Environment Variables

Customization

Change AI Model

Modify Agent Instructions

Add New Tools

🧪 Testing

Run Type Checking

Format Code

Test Telegram Webhook (Local)

🤝 Contributing

Ways to Contribute

Development Workflow

Code Style

📝 License

🙏 Acknowledgments

📧 Contact

🌟 Support

Made with ❤️ and ☕ by Aryan Kumar

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages