Create readme.md

readme.md

@@ -0,0 +1,96 @@
+# Quantum Synchronicity Chatbot — README
+
+## Overview
+This application provides a mystical-toned chat interface to log, analyze, and detect patterns in personal synchronicities. It integrates basic pattern recognition via TF-IDF and cosine similarity to compare new entries with past ones and optionally syncs your data to a Hugging Face Space repository.
+
+## Features
+- Add synchronicity entries with tags and outcomes.
+- Analyze entries to find similar past events and predict potential patterns.
+- Export or reset your database.
+- Optional automatic synchronization to Hugging Face Hub.
+- CLI fallback mode when Gradio is unavailable.
+
+## Installation
+
+1. **Clone or copy the repository files:**
+   ```bash
+   git clone <your-repo-url>
+   cd <repo-folder>
+   ```
+
+2. **Create and activate a virtual environment (recommended):**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate   # On Windows use: venv\\Scripts\\activate
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Ensure the following files exist:**
+   - `synchronicities.json` initialized as:
+     ```json
+     {"entries": []}
+     ```
+   - `.env` file (optional) containing:
+     ```bash
+     HF_TOKEN=your_huggingface_token
+     HF_REPO=your_username/your_repo_name
+     ```
+
+## Running the App
+
+### Option 1: Web Interface (Gradio)
+```bash
+python app.py
+```
+Then open the local URL displayed (e.g., http://127.0.0.1:7860) in your browser.
+
+### Option 2: Command Line Mode
+If Gradio is not installed, you can use the CLI fallback:
+```bash
+python app.py
+```
+You’ll see prompts like:
+```
+> add       # Add a new synchronicity entry
+> export    # Print database as JSON
+> reset     # Clear the database
+> tests     # Run basic internal tests
+> exit      # Quit
+```
+
+## Environment Variables
+
+- `HF_TOKEN` — Your Hugging Face access token (for syncing data).
+- `HF_REPO` — The name of your Hugging Face repository (e.g., `username/space-repo`).
+
+If you don’t plan to sync data, you can omit these.
+
+## Deployment to Hugging Face Space
+
+1. Upload the following files to your Space:
+   - `app.py`
+   - `requirements.txt`
+   - `synchronicities.json`
+   - `README.md`
+
+2. Add your `HF_TOKEN` and `HF_REPO` as **Secrets** under Space Settings.
+
+3. Set the SDK to **Gradio** and the `app_file` to `app.py`.
+
+Your app will automatically build and launch with a chat-style interface.
+
+## Tests
+Run simple verification tests locally:
+```bash
+python app.py
+> tests
+```
+If all tests pass, you’ll see “All tests passed.”
+
+---
+
+✨ *The Oracle listens, remembers, and reveals patterns that bridge coincidence and consciousness.*