WebtreesChatBot 🌳

An AI-powered genealogy chatbot for Webtrees family history websites. Powered by Google Gemini, it answers questions about your ancestors directly from your Webtrees database — without expensive per-query token costs.

---

Features

• 🔍 Natural language search — users ask questions like "Who were John Smith's parents?" and get conversational answers
• 🧬 Multi-hop GEDCOM traversal — automatically retrieves parents, spouses, and children in a single query
• 🔒 Privacy-first — living individuals and restricted records are never shown
• 💰 Cost-optimized — uses the cheapest Gemini model for name parsing, and auto-downgrades after 100 daily chats
• 🌀 Rolling logs — conversation logs rotate at 2 MB and are pruned after 6 months
• 🛡️ Apache firewall — .htaccess blocks bots and non-POST requests

---

Requirements

Requirement	Details
PHP	7.4 or higher
PHP Extensions	pdo_mysql, curl
Database	MySQL or MariaDB (standard Webtrees install)
Webtrees	Any recent version (uses wt_ prefixed tables)
Google Gemini API Key	Free tier available — see below
Web Server	Apache (with mod_rewrite enabled)

---

Getting a Free Gemini API Key

1. Go to aistudio.google.com/app/apikey
2. Sign in with your Google account
3. Click Create API Key
4. Copy it into your .env file as GEMINI_API_KEY

The free tier supports up to 1,500 requests/day on gemini-flash-lite. Upgrading to a paid API key unlocks higher quality responses.

---

Installation

Step 1 — Upload files to your server

Upload the two folders to the root of your public Webtrees directory:

public_html/
├── chatbot_backend/     ← PHP API + .env
│   ├── chat-api.php
│   ├── .htaccess
│   └── .env             ← You create this (see Step 2)
└── chatbot_widget/      ← Frontend popup
    ├── chat.html
    ├── chat.css
    └── chat.js

Step 2 — Create your .env file

Copy .env.example to .env in the chatbot_backend/ folder and fill in your values:

DB_HOST="localhost"
DB_PORT="3306"
DB_NAME="your_database_name"
DB_USER="your_db_username"
DB_PASS="your_db_password"
DB_PREFIX="wt_"

GEMINI_API_KEY="your_gemini_api_key_here"

SITE_NAME="My Family Tree"
SITE_URL="https://your-domain.com"

⚠️ Never commit your .env file to version control! It contains your database password and API key.

Step 3 — Create a read-only database user (Recommended)

For security, create a dedicated user with SELECT-only permissions:

CREATE USER 'chatbot'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT SELECT ON your_webtrees_database.* TO 'chatbot'@'localhost';
FLUSH PRIVILEGES;

Use this user's credentials in your .env file.

Step 4 — Lock down the .htaccess firewall (Optional but recommended)

Edit chatbot_backend/.htaccess and uncomment the domain lock section, replacing your-domain.com with your actual domain:

RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^https?://(www\.)?your-domain\.com [NC]
RewriteRule ^(.*)$ - [F,L]

Step 5 — Embed the chat button on your Webtrees site

Add this snippet to your Webtrees site's custom header HTML (via Control Panel → Website → Header):

<!-- WebtreesChatBot Launch Button -->
<style>
  #wtcb-launch-btn {
    position: fixed; bottom: 24px; right: 24px; z-index: 9999;
    background: linear-gradient(135deg, #3b82f6, #8b5cf6);
    color: white; border: none; border-radius: 28px;
    padding: 14px 20px; font-size: 0.95rem; font-weight: 600;
    cursor: pointer; box-shadow: 0 4px 20px rgba(59,130,246,0.4);
    font-family: inherit;
  }
</style>
<button id="wtcb-launch-btn" onclick="window.open('/chatbot_widget/chat.html', 'WebtreesChatBot', 'width=450,height=680,resizable=no')">
  🌳 Ask the AI
</button>

Adjust /chatbot_widget/chat.html to match the path where you uploaded the widget folder.

---

Configuration Reference

Variable	Description	Example
DB_HOST	Database hostname	localhost
DB_PORT	Database port	3306
DB_NAME	Webtrees database name	my_webtrees_db
DB_USER	Database username	chatbot_user
DB_PASS	Database password	••••••••
DB_PREFIX	Webtrees table prefix	wt_
GEMINI_API_KEY	Google Gemini API key	AIzaSy...
SITE_NAME	Name used in AI persona	Smith Family Tree
SITE_URL	Your site URL for CORS	https://my-site.com

---

Directory Structure

WebtreesChatBot/
├── chatbot_backend/
│   ├── chat-api.php        ← Main PHP backend
│   ├── .htaccess           ← Apache security rules
│   ├── .env.example        ← Template — copy to .env
│   └── chat_logs/          ← Auto-created, auto-pruned
├── chatbot_widget/
│   ├── chat.html           ← Popup chat window
│   ├── chat.css            ← Styles
│   └── chat.js             ← Chat logic
├── .gitignore
├── .env.example
└── README.md

---

Privacy & Security

• Living individuals are automatically excluded (no 1 DEAT tag = skipped)
• Restricted records (1 RESN) are always skipped
• Private chat logs are stored in chatbot_backend/chat_logs/ which is blocked from web access by its own .htaccess
• The API endpoint is blocked from GET requests, curl, and all standard bot user agents

---

Contributing

Pull requests, bug reports, and feature suggestions are welcome! Please open an issue before submitting large changes.

---

License

MIT License — see LICENSE for details.

---

Originally developed for Kiancestry.com and open-sourced for the Webtrees community.