

# 🔮 Cosmic Oracle

**Cosmic Oracle** is a mystical command-line decision oracle built in Python using the Rich terminal UI framework.
Ask any question, and the Oracle responds with animated prophecies rendered in a dramatic terminal interface.

While playful in spirit, the project is designed as a structured CLI system that will gradually evolve into an intelligent rule-based decision engine.

---

## ✨ Features

* Interactive command-line question system
* Animated prophecy reveal panels
* Clean modular architecture (CLI → UI → Engine separation)
* Rich-powered terminal styling and loaders
* Lightweight, fast, and fully offline

---

## 📦 Installation

```bash
pip install cosmic-oracle
```

---

## 🚀 Usage

Run the Oracle from your terminal:

```bash
oracle
```

Then simply ask your question and receive the prophecy.

---

## 🧠 Project Philosophy

Cosmic Oracle began as a fun experimental CLI project, but it is being developed with real engineering practices:

* modular system architecture
* clean packaging and release workflow
* incremental feature evolution
* structured intelligence layers

The goal is to transform a playful terminal tool into a progressively smarter **rule-driven prophecy engine**.

---

## 🔭 Future Roadmap

Planned upgrades include:

* Context-aware prophecy generation
* Regex-based question classification
* Template-driven response synthesis
* Adaptive response learning modules
* Extended CLI command system
* Optional analytics and history tracking

Eventually, the Oracle will move from random responses toward **lightweight NLP-style reasoning**, while remaining fast and fully offline.

---

## 🛠 Development

Clone the repository and run locally:

```bash
git clone <repo-url>
cd cosmic-oracle
python -m venv venv
source venv/bin/activate
pip install -e .
```

Then run:

```bash
oracle
```

---

## 📜 License

MIT License

---

## 🌌 Closing Note

Some tools are built purely for productivity.
Some are built for curiosity.
Cosmic Oracle is built for both — a small terminal ritual today, a smarter decision engine tomorrow.


