README.md

# Marcus Mint – VIP-Only Coin Expert Chatbot

Welcome to Marcus Mint: your go-to, AI-powered coin expert for Rich Off Error Coins. This Gradio app lets VIP members upload coin photos or ask text questions to identify error coins, die varieties, and more. Guests get a teaser—and a friendly nudge to upgrade.

Marcus Mint is designed to be:

- **Fast** – Simple chat interface, quick responses.
- **Accurate** – Stub logic is in place; swap in your trained model to detect die markers and error types.
- **Secure** – Only VIPs (via S2Member on WordPress) can upload images. All secrets (API keys, passwords) stay safe in Hugging Face’s “Secrets” panel, not in code.
- **Plug-and-Play** – Deploy on Hugging Face Spaces, then embed or link from your WordPress site.

---

## 🧰 Prerequisites

1. **Python 3.8+** (recommended 3.9 or 3.10)
2. A Hugging Face account with access to Spaces
3. (Locally) a `.env` file containing your own secrets
4. (Remotely) environment variables configured in your Space’s **Settings → Secrets**

---

## 🚀 Local Development

Clone or download this repo to your machine. Then:

1. **Create a virtualenv & activate it**  
   ```bash
   python3 -m venv venv
   source venv/bin/activate

    Install dependencies
    Make sure requirements.txt is present (see below). Then run:

pip install -r requirements.txt

Create a .env file (not committed to Git!)
Copy env.example → .env (if you have an example). Add your real values:

WP_API_URL=https://richofferrorcoins.com/wp-json
WP_API_USER=your_wp_username
WP_API_PASS=your_wp_application_password
SERP_API_KEY=your_serpapi_key
OPENAI_API_KEY=your_openai_key
UPGRADE_URL=https://richofferrorcoins.com/minty-vip

Run the app locally

    python app.py

        Point your browser to http://localhost:7860.

        You should see the chat interface. Enter a test-user ID (e.g. test-vip) or leave blank to simulate a “guest.”

        Try typing a question (“Is my Lincoln cent a doubled die?”). Guests will get a “VIP only” CTA if they mention uploads. VIPs (or test-vip—if you stub that) can upload an image to hit identify_error_coin().

📋 File Structure

/
├── app.py
├── requirements.txt
├── README.md
├── .gitignore
├── env.example
├── models/
│   └── model.pth             # (Optional) your trained PyTorch checkpoint
└── assets/
    └── logo.png              # (Optional) logo or static UI assets

    app.py – Main Gradio script. Contains:

        Environment loading (dotenv for local, os.getenv() for HF).

        WP/S2Member REST calls for membership gating.

        SerpAPI web-search stub (web_search()).

        Coin-ID model stub (identify_error_coin()).

        Gradio Blocks UI: chatbox, file uploader (VIP only), etc.

    requirements.txt – Lists all pip packages the Space needs:

gradio>=3.0
huggingface-hub>=0.13.3
python-dotenv>=0.21.0
requests>=2.28.0
serpapi>=2.4.0
torch>=1.13.0
transformers>=4.28.0
pillow>=9.0.0
beautifulsoup4>=4.11.1
python-multipart>=0.0.5

README.md – (That’s this file!) Explains setup, deployment, and usage.

.gitignore – Should contain:

    .env
    __pycache__/
    *.pyc
    models/*.pth

    env.example – Template for your .env, with placeholder keys (no real secrets).

    models/ – Optional folder to keep a small model checkpoint (model.pth). If your model is huge, consider hosting it separately (e.g. HF Model Hub) and downloading at runtime.

    assets/ – Optional assets (logos, CSS, small static files) used by the UI.

🔐 Environment Variables
Key	Description
WP_API_URL	WordPress REST base URL (e.g. https://richofferrorcoins.com/wp-json)
WP_API_USER	WP username (with “Application Password” capabilities)
WP_API_PASS	WP application password for REST API auth
SERP_API_KEY	Your SerpAPI key for Google (free tier is fine for testing)
OPENAI_API_KEY	Optional: If you use OpenAI endpoints for deeper NLP
UPGRADE_URL	Where to send “Not a VIP yet? Upgrade here!” links

    Note:

        Locally, python-dotenv reads .env.

        On Hugging Face, go to your Space’s Settings → Secrets and add each of these (exact names). The Space runner will populate them in os.environ.

📖 How Membership Gating Works

    membership_info(user_id) in app.py:

        Sends a GET to ${WP_API_URL}/s2member/v1/membership/${user_id}, using basic auth.

        Expects a JSON response with a field level (>0 means VIP).

        Returns {"status": "member", …} or {"status": "guest", "upgrade_url": …}.

    Chat logic (chat_fn):

        If uploaded_file is provided but status != "member", immediately reply with:

            “🔒 Image uploads are VIP-only! Upgrade here: [UPGRADE_URL]”

        If status == "member", pass the image path into identify_error_coin() (or your model).

        If user types text containing “upload” but they’re a guest, also add a teaser at the bottom.

    Stub vs. Real Logic:

        Out of the box, identify_error_coin() returns a placeholder JSON. Replace that with your real model inference.

        web_search(query) uses SerpAPI to return the top 5 organic results for that query. You can swap in Bing or any other provider if you prefer—but SerpAPI is ready to go once you put your key in .env.

🚨 Deploy to Hugging Face Spaces

    Log in & create a new Space

huggingface-cli login
huggingface-cli repo create your-username/MarcusMint --type=space

Push your code (no .env!):

git init
git add .
git commit -m "Initial Marcus Mint Space"
git branch -M main
git push https://huggingface.co/spaces/your-username/MarcusMint main

Add Secrets in HF UI

    Go to https://huggingface.co/spaces/your-username/MarcusMint/settings

    Under “Repository Secrets” or “Environment Variables”, add exactly:

    WP_API_URL
    WP_API_USER
    WP_API_PASS
    SERP_API_KEY
    OPENAI_API_KEY
    UPGRADE_URL

    (Use the same names you reference in os.getenv().)

Wait for build

    HF will read requirements.txt, install everything, then launch app.py.

    Look at the Log tab for errors (often a missing package or a typo in environment variable names).

Test the UI

    Visit https://huggingface.co/spaces/your-username/MarcusMint.

    Enter a test User ID (test-vip if you stubbed it) or leave empty to simulate a guest.

    Ask a question. Try uploading an image. Confirm that guests see the “upgrade” message, and VIPs hit your stubbed model.

Embed or Link

    To embed in WordPress, use an <iframe> block:

<iframe
  src="https://huggingface.co/spaces/your-username/MarcusMint?frozen=true"
  width="1000"
  height="900"
  frameborder="0"
  sandbox="allow-scripts allow-same-origin">
</iframe>

Or simply add a button:

        <a href="https://huggingface.co/spaces/your-username/MarcusMint" target="_blank">
          Chat with Marcus Mint
        </a>

🤝 Contributing & Extending

    Swap in your model

        In identify_error_coin(), replace the stub with your PyTorch/TensorFlow/Keras inference.

        If your checkpoint is large, consider hosting on HF Model Hub and downloading at runtime.

    Improve WP-S2Member integration

        The REST endpoint /s2member/v1/membership/<user_id>:

            Write a tiny WP plugin (or add to functions.php) that registers a custom REST route.

            In the callback, look up the user’s S2Member level. Return JSON:

            {
              "user_id": 123,
              "level": 1
            }

        That way, membership_info() can trust the response.

    Customize UI

        Tweak gr.Blocks(css=…) to match your site’s branding (fonts, colors, logos).

        Drop a gr.Image("assets/logo.png") or change the Markdown header (## Chat with Marcus Mint) to something flashier.

    Add analytics

        If you want to track usage, you can call a Pixel or post usage stats to an endpoint every time chat_fn runs. Just be mindful of PII—never log private user IDs or images.

💡 Tips & Tricks

    “Frozen” mode in Embed: ?frozen=true prevents the Gradio UI from showing the code editor or auto-reloading when you push updates. Perfect for production embedding.

    Test Secrets Locally: Use a local .env to avoid typos. If your local run says WP_API_URL is empty, you know your .env is missing or misnamed.

    Stubbing Membership
    If you haven’t built your WP plugin yet, temporarily stub membership_info() as:

def membership_info(user_id):
    if user_id and user_id.startswith("vip-"):
        return {"status": "member", "level": 1}
    return {"status": "guest", "upgrade_url": os.getenv("UPGRADE_URL")}

Then any ID starting with vip- will be treated as a VIP. Great for initial UI testing.

SerpAPI Limits
SerpAPI’s free tier allows ~100 searches/month. If you exceed that, consider switching to Bing’s API (Microsoft Azure) or caching queries. You could also parse a free site like CoinTrackers, but beware of ToS.

Latency Notice
Image→model inference can take a second or two. For a snappier UI, consider resizing/cropping images client-side or using a smaller/optimized model.