🕉️ Daily Hindu Panchanga AI Summary

An automated system that computes the Hindu Panchanga for each day and uses a local LLM to generate a rich summary — including stories, legends, and spiritual guidance — delivered to Slack.

Architecture

┌─────────────────────────────────────────────────┐
│  Docker Container (cron @ midnight US Central)  │
│                                                 │
│  main.py                                        │
│    ├── panchanga.py    → compute 5 limbs        │
│    │                   → scrape festivals        │
│    │                     (drikpanchang.com)      │
│    └── summary_generator.py → LangChain + Ollama│
│         │                                       │
│         ├── Slack webhook → your channel         │
│         └── output/YYYY-MM-DD.md (backup)       │
└────────────────────┬────────────────────────────┘
                     │ HTTP
              ┌──────▼──────┐
              │   Ollama    │
              │ llama3.3:70b│
              └─────────────┘

Quick Start

Prerequisites

• Ollama running on a machine in your network with the model pulled:

  ollama pull llama3.3:70b
  

• Docker & Docker Compose
• Slack Incoming Webhook URL (create one here)

Configuration

1. Copy the example environment file and fill in your values:

   cp .env.example .env
   

2. Edit .env with your actual configuration:

   # ── Ollama ──────────────────────────────────────────
   OLLAMA_HOST=http://your-ollama-host:11434
   OLLAMA_MODEL=llama3.3:70b
   
   # ── Slack ───────────────────────────────────────────
   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx
   

   Variable	Default	Description
   OLLAMA_HOST	http://localhost:11434	Ollama server URL
   OLLAMA_MODEL	llama3.3:70b	Model for summary generation
   SLACK_WEBHOOK_URL	(required)	Slack incoming webhook URL
   TZ	America/Chicago	Container timezone (set in docker-compose.yml)

Deploy with Docker (production)

# Make sure .env exists with your configuration (see above)

# Build & start (cron runs at midnight US Central daily)
docker compose up -d --build

# Check logs
docker logs -f panchanga-daily

# Test immediately without waiting for midnight
docker exec panchanga-daily python /app/main.py --force

How Scheduling Works

The container uses multiple layers to ensure the daily summary is never missed:

Cron Job

A single cron entry runs every 4 hours inside the container:

0 */4 * * *  /app/run_daily.sh    # Fires at 0:00, 4:00, 8:00, 12:00, 16:00, 20:00

• The 0:00 run is the primary daily trigger
• Later runs (4:00, 8:00, etc.) are automatic catch-ups — if midnight was missed for any reason, the next window picks it up
• Duplicate protection in main.py ensures only one Slack message is sent per day (checks if output/YYYY-MM-DD.md was written today)
• The container's timezone is set to America/Chicago (US Central) via TZ in docker-compose.yml
• run_daily.sh is a wrapper that sources Docker env vars (which cron doesn't inherit) and runs main.py

Startup Catch-Up

The entrypoint.sh script runs on every container start and checks if today's summary has been generated. If not, it runs main.py immediately — so even a container restart or host reboot at midnight won't cause a missed day.

Retry & Error Alerting

• If the LLM or network is temporarily down, main.py retries up to 3 times with exponential backoff (30s → 60s → 120s)
• If all retries fail, an error notification is sent to Slack so you know something went wrong (instead of silent failure)

Limitations

• No backfill for missed days. If the host is down for multiple days, only today's summary is generated when it comes back. Past days are not automatically caught up. To backfill manually:

  docker exec panchanga-daily python /app/main.py --date 2026-05-07
  docker exec panchanga-daily python /app/main.py --date 2026-05-08
  

Logs

Logs are written to ./logs/panchanga.log (mounted as a Docker volume) and also forwarded to docker logs:

# View via docker logs
docker logs -f panchanga-daily

# Or read the persistent log file on the host
cat logs/panchanga.log

Manual Runs

To test end-to-end immediately without waiting for midnight:

# Run inside the container
docker exec panchanga-daily python /app/main.py --force

# Or for a specific date (past or future)
docker exec panchanga-daily python /app/main.py --date 2026-05-10

This runs the exact same pipeline that cron would run — computes panchanga, generates the LLM summary, sends it to Slack, and saves the backup file.

Duplicate Protection

The app prevents duplicate Slack messages using smart detection:

• Cron runs (no --date) check if today's output file exists and was written today. If so, the run is skipped.
• Manual --date runs always execute — they're considered intentional.
• Running --date for a future date is safe. For example, running --date 2026-05-10 on May 9 creates the output file with a May 9 timestamp. When cron fires on May 10, it sees the file was written yesterday and re-runs, delivering a fresh summary.
• Use --force to bypass all duplicate checks.

CLI Reference

python main.py [OPTIONS]

Options:
  --date YYYY-MM-DD   Generate summary for a specific date (default: today)
  --force             Run even if today's output file already exists

Project Structure

panchanga_summary_app/
├── main.py                # Orchestrator — CLI, retry, Slack delivery
├── panchanga.py           # Panchanga computation + drikpanchang.com scraping
├── summary_generator.py   # LangChain + Ollama summary chain
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container with cron
├── docker-compose.yml     # Production deployment config
├── entrypoint.sh          # Startup catch-up + env export + cron launcher
├── run_daily.sh           # Cron wrapper (sources env, runs main.py)
├── .env.example           # Template — copy to .env and fill in your values
├── output/                # Backup summaries (also sent to Slack)
└── logs/                  # Persistent logs (mounted volume)