readme.md

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