Farmers Bounty Chatbot – Complete Documentation

Overview

The Farmers Bounty chatbot is a sophisticated AI-powered gardening assistant that combines Claude AI, web search via Tavily, and local knowledgebase to provide expert gardening advice.

User Message
    ↓
AJAX Handler
    ↓
Chatbot Handler
    ├→ Load Knowledgebase Context
    ├→ Search Web (Tavily) if needed
    └→ Send to Claude API with context
        ↓
Claude Response
    ↓
Display to User (with sources)

Features

🤖 AI-Powered Conversations

• Uses Claude 3.5 Sonnet (latest model)
• Context-aware responses
• Maintains conversation history (last 10 exchanges)
• Understands gardening terminology

🔍 Intelligent Web Search

• Automatically determines when web search is needed
• Searches 14 trusted gardening sources only
• Provides source attribution
• Caches results for 1 hour

📚 Knowledgebase Integration

• Loads plugin’s disambiguations
• References transplanting guides
• Includes user’s garden context
• Plant inventory awareness

🌱 User Context

• Knows user’s USDA zone
• Aware of plants in user’s garden
• Location-specific advice
• Seasonal recommendations

🎨 Beautiful UI

• Garden-themed green color palette
• Smooth animations and transitions
• Typing indicators
• Source citations
• Suggestion chips
• Responsive design

---

Usage

For Site Administrators

1. Setup API Keys

Go to Farmers Bounty > Settings > API Keys and enter:

• Claude API Key (required)
• Tavily API Key (optional but recommended)

2. Embed Chatbot

Use the shortcode on any page or post:

[bg_chatbot]

3. Customize Appearance

[bg_chatbot 
    title="Ask Your Garden Expert" 
    height="600px" 
    show_status="yes" 
    show_actions="yes"]

For Users

1. Ask Questions

• Type naturally: “When should I plant tomatoes?”
• Use garden terminology: “What’s bolting?”
• Describe problems: “My tomatoes have black spots”

1. Get Contextual Help

• Bot knows your USDA zone
• Aware of your garden’s plants
• Provides location-specific advice

1. Review Sources

• Web search results show source links
• Click to read full articles
• All sources are trusted gardening sites

---

Shortcode Parameters

Parameter	Default	Description
title	“Gardening Assistant”	Header title
height	“500px”	Messages area height
show_status	“yes”	Show online status indicator
show_actions	“yes”	Show action buttons (clear history)

Examples

Minimal:

[bg_chatbot]

Custom:

[bg_chatbot title="Garden Help" height="700px"]

Simple (no extras):

[bg_chatbot show_status="no" show_actions="no"]

---

API Integration Details

Claude API

Endpoint: https://api.anthropic.com/v1/messages
Model: claude-3-5-sonnet-20241022
Max Tokens: 4,096
Rate Limit: 100 requests/hour per user

System Prompt Includes:

• Gardening expertise areas
• User’s USDA zone
• User’s garden context
• Current plant inventory
• Additional web search context

Tavily API

Endpoint: https://api.tavily.com/search
Search Depth: Basic
Max Results: 5
Rate Limit: 100 requests/hour
Cache: 1 hour

Trusted Domains:

• extension.uga.edu (UGA Extension)
• walterreeves.com (Walter Reeves)
• planthardiness.ars.usda.gov (USDA)
• gardeningknowhow.com
• almanac.com (Farmer’s Almanac)
• And 9 more university extensions

Automatic Search Triggers

Web search activates when message contains:

• Questions (contains “?”)
• “how to”, “when to”, “what is”
• “pest”, “disease”, “problem”
• “current”, “latest”, “recent”
• “variety”, “cultivar”

---

User Experience

Initial State

Shows welcome message with suggestion chips:

• “When should I plant tomatoes?”
• “How do I deal with aphids?”
• “What vegetables grow well in shade?”
• “How often should I water my garden?”

During Conversation

• User messages: Right-aligned, green bubble
• Bot messages: Left-aligned, white bubble with border
• Typing indicator: Animated dots while processing
• Sources: Clickable links below bot messages
• Timestamps: On all messages

Error Handling

• Shows friendly error messages
• Auto-dismisses after 5 seconds
• Handles API failures gracefully
• Provides helpful suggestions

---

Privacy & Data

What’s Stored

• Conversation History: Last 50 exchanges per logged-in user
• Session ID: Temporary identifier for each chat session
• User Meta: Stored in WordPress user_meta table

What’s NOT Stored

• Full conversation transcripts (only last 50)
• Personal information beyond WordPress user data
• Message content sent to external APIs

Rate Limiting

• Claude: 100 requests/hour per user
• Tavily: 100 requests/hour globally
• Prevents API quota exhaustion
• User-friendly error messages

---

Styling & Customization

CSS Classes

All classes prefixed with bg- for namespace safety:

• .fb-chatbot-container – Main wrapper
• .fb-chatbot-header – Header area
• .fb-chatbot-messages – Messages area
• .fb-chat-message – Individual message
• .fb-message-bubble – Message bubble
• .fb-chatbot-textarea – Input field
• .fb-send-button – Send button

Color Palette

Primary Green: #6b8e65
Dark Green: #4c6e47
Light Green: #88a883
Background: #fafbf9
Border: #d4e1d1

Custom CSS

Add to your theme:

.fb-chatbot-container {
    max-width: 1000px;
    margin: 40px auto;
}

.fb-chatbot-header {
    background: linear-gradient(135deg, #your-color-1, #your-color-2);
}

---

Troubleshooting

Chatbot Not Working

1. Check API Keys

• Go to Settings > API Keys
• Verify Claude API key is entered
• Test connection

1. Check Browser Console

• Open Developer Tools (F12)
• Look for JavaScript errors
• Check Network tab for failed requests

1. Check Rate Limits

• Admin: Settings > System Status
• View current API usage
• Wait if limits exceeded

Empty Responses

• Cause: Claude API key invalid or quota exceeded
• Solution: Verify API key and billing status at Anthropic

No Web Search Results

• Cause: Tavily API not configured
• Solution: Add Tavily API key (optional feature)

Styling Issues

• Cause: CSS conflicts with theme
• Solution: Use browser inspector to identify conflicts

---

Performance

Caching Strategy

• Tavily Results: 1 hour
• Geocoding: 30 days
• Conversation History: Stored until user clears

Optimization

• Lazy loading of chatbot assets
• Only loads on pages with shortcode
• Minimal JavaScript payload
• Efficient AJAX requests

Best Practices

1. Don’t embed chatbot multiple times on same page
2. Use reasonable height values (500-700px)
3. Consider mobile users (responsive by default)
4. Test API keys before going live

---

Security

Implemented Protections

✅ Nonce verification on all AJAX requests
✅ Capability checks for admin features
✅ Input sanitization
✅ Output escaping
✅ API key encryption preparation
✅ Rate limiting
✅ CSRF protection

User Permissions

• Anyone: Can use chatbot
• Logged-in: Can save history
• Admin: Can configure API keys

---

Integration Examples

With Plant Pages

<?php
// Single plant template
if (is_singular('plant')) {
    echo do_shortcode('[bg_chatbot title="Ask About This Plant" height="400px"]');
}
?>

In Sidebar

// functions.php
add_action('widgets_init', function() {
    register_sidebar(array(
        'name' => 'Chatbot Sidebar',
        'id' => 'chatbot-sidebar',
        'before_widget' => '<div class="widget">',
        'after_widget' => '</div>',
    ));
});

// In sidebar template
dynamic_sidebar('chatbot-sidebar');
// Add shortcode to sidebar widget

With Contact Form

Place chatbot above contact form to answer questions first:

[bg_chatbot title="Have a Question?" height="500px"]

<!-- Contact Form Below -->
Error: Contact form not found.

---

Future Enhancements

Possible additions in future versions:

• Voice input/output
• Image recognition (plant identification)
• Conversation export
• Multi-language support
• Custom training on user’s garden
• Integration with calendar for reminders
• Proactive seasonal tips

---

Technical Specifications

Files Created

includes/
  api/
    class-claude-api.php (360 lines)
    class-tavily-api.php (340 lines)
  class-chatbot-handler.php (260 lines)
  class-chatbot-ajax.php (140 lines)
  class-chatbot-shortcode.php (150 lines)
assets/
  css/
    chatbot.css (420 lines)
  js/
    chatbot.js (300 lines)

Total: ~1,970 lines of production code

Dependencies

• PHP: 7.2+
• WordPress: 5.0+
• jQuery: Included with WordPress
• External APIs: Claude (Anthropic), Tavily

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+
• Mobile browsers (iOS Safari, Chrome Mobile)

---

Credits

AI Model: Claude 3.5 Sonnet by Anthropic
Web Search: Tavily API
Design: Custom garden-themed UI
Architecture: Inspired by gd-claude-chatbot (all Grateful Dead content removed)

---

---

Botanical Garden AI Skills Integration

The chatbot’s knowledge can be extended with 30 specialist Botanical Garden AI Skills covering:

• Horticulture & Grounds (11 skills) — Plant care, greenhouse management, IPM, irrigation, arboriculture
• Science & Conservation (8 skills) — Research, taxonomy, conservation biology, seed banking, GIS mapping
• Education & Programming (7 skills) — Curriculum, school programs, therapeutic horticulture, volunteer coordination
• Outreach & Community (4 skills) — Community engagement, PR, DEI, internship programs

These skills are available in the Cursor and Codex development environments and can inform chatbot context and knowledgebase expansion. See CLAUDE.md for the full skill inventory.

---

Support

For issues or questions:

1. Check this documentation
2. Review plugin settings
3. Test API connections
4. Check WordPress error logs
5. Contact plugin developer

---

Last Updated: March 19, 2026
Version: 1.1.0