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

   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:

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.