SVE Chat

What is SVE Chat?

SVE Chat is an AI-powered question-and-answer widget for the Sunland Village East HOA website. Residents type a question in plain English and receive a concise answer drawn from:

• HOA governing documents — CC&Rs, bylaws, rules, policies, and other community documents stored in the SVE document database.
• Live calendar events — upcoming tournaments, club meetings, classes, and activities from the SVE Community Calendar.
• Amenity availability — open booking slots for the clubhouse, pool, courts, gym, and other facilities via the SVE Fastbook system.

The chat is powered by Claude (Anthropic) and uses a Retrieval-Augmented Generation (RAG) pipeline — the AI never guesses from general knowledge; it only answers from SVE-specific sources.

How It Works

Every question goes through a multi-step pipeline before an answer is returned:

Requirements

Using the Chat Widget

The chat widget appears on any page where an administrator has placed the

1. Navigate to the page with the chat widget. Ask your community manager or check the HOA website for the page where SVE Chat is available.
2. Type your question in the text box at the bottom of the widget. You can ask in plain, conversational English — no special syntax required. Questions can be up to 500 characters.
3. Press Enter or click the send button. A loading indicator appears while the AI retrieves and processes your answer, typically within a few seconds.
4. Read the answer. The AI cites the source document or section where applicable. If it cannot find an answer, it will tell you rather than guess.
5. Continue the conversation. You can ask follow-up questions. Each question is answered independently — the AI does not carry memory between questions.

What to Ask

SVE Chat is designed to answer questions about SVE community life. Here are good examples by category:

Rules & Policies

• “What are the quiet hours in SVE?”
• “Can I park an RV in my driveway?”
• “What is the pet policy for SVE?”
• “How do I get approval for a home improvement project?”
• “What are the rules for garage sales?”

Community Events

• “What events are happening this week?”
• “When is the next pickleball tournament?”
• “Are there any club meetings this month?”
• “What fitness classes are offered?”

Amenity Booking

• “When is the clubhouse available this weekend?”
• “Are there any open tennis court slots tomorrow?”
• “How do I book the pool area for a party?”
• “Is the gym available on Saturday mornings?”

Governing Documents

• “What does the CC&R say about fences?”
• “How are HOA board members elected?”
• “What are the landscaping requirements?”
• “What is the process for filing an architectural review request?”

Tips for Better Answers

Installation & Setup

1. Install the Plugin

Upload the sve-chat folder to wp-content/plugins/ and activate it through the WordPress admin. A database table ({prefix}sve_chat_unanswered) is created automatically on activation.

2. Add the Anthropic API Key

Add the following constant to wp-config.php:

define( 'ANTHROPIC_API_KEY', 'sk-ant-...' );

3. Verify the AI Engine Bridge

The MU-plugin sve-ai-engine-bridge.php must be present in wp-content/mu-plugins/ and must provide the sve_pg_search_run() function. SVE Chat will throw an error if this function is missing when a question is submitted.

Adding the Widget to a Page

Place the

Shortcode Attributes

Examples

		

			

				📄
				Ask About SVE
			
			

				

					
Hello! I can answer questions about SVE HOA governing documents,events, room availability, contractors, and resident contact data. (Just enter their name) What would you like to know?
				
			
			

				Ask a question
				
				
					
				
			
		
		

		

			

				📄
				Ask a Question
			
			

				

					
Hello! I can answer questions about SVE HOA governing documents,events, room availability, contractors, and resident contact data. (Just enter their name) What would you like to know?
				
			
			

				Ask a question
				
				
					
				
			
		
		

		

			

				📄
				SVE Document Assistant
			
			

				

					
Hello! I can answer questions about SVE HOA governing documents,events, room availability, contractors, and resident contact data. (Just enter their name) What would you like to know?
				
			
			

				Ask a question
				
				
					
				
			
		
		

Unanswered Questions Log

When the AI cannot find an answer — because the relevant information is not in the document database or tool results — the question is automatically logged. This log is a valuable tool for identifying gaps in your SVE document library.

Dashboard Statistics

The top of the admin page shows three summary cards:

Most Common Unanswered Questions

A ranked table of the questions asked most frequently that did not receive a satisfactory answer. Use this to prioritize which documents to add or update in the SVE document library.

Full Question Log

A paginated table (50 per page) showing every logged question with:

• Date and time asked
• The full question text
• IP address of the requester
• Resident name (linked to their WordPress user profile) if logged in

Individual entries can be deleted once reviewed. Use the search box to filter by keyword.

Exporting to CSV

The admin page includes a SQL query you can run directly in your database client (phpMyAdmin, TablePlus, etc.) to export all unanswered questions:

SELECT question, user_ip, user_id, blog_id, asked_at
FROM wp_sve_chat_unanswered
ORDER BY asked_at DESC;

Access Control

SVE Chat mirrors the access level configured in the SVE Docs plugin (min_role_view setting). This ensures the chat widget is only accessible to residents who are already permitted to browse HOA documents.

Access control is enforced at the REST API level (POST /wp-json/sve-chat/v1/ask). Unauthenticated or insufficiently privileged requests receive an HTTP 401 response and are not counted against the rate limit.

Rate Limiting

To prevent abuse and control API costs, SVE Chat limits each IP address to 30 questions per hour. This limit is enforced using WordPress site transients and is network-scoped — the same 30-question budget applies across all subsites in the multisite installation.

When the limit is reached, the API returns HTTP 429 and the widget displays a friendly message asking the resident to wait before asking more questions. The counter resets automatically after 60 minutes.

Dependencies

AI Tools

When the Anthropic provider is active, Claude has access to tools it can call during the agentic loop. Two tools are built in. Additional tools can be added by any plugin — see Adding a Tool.

Adding a Tool from Another Plugin

SVE Chat uses an extensible provider pattern. Any WordPress plugin can register additional AI tools without modifying the SVE Chat source code. Claude will automatically have access to the new tool and will call it when appropriate.

How it works

SVE Chat defines an abstract base class SVE_Chat_Tool_Provider. You create a class that extends it, implement two methods, then hook it into the sve_chat_tool_providers filter. The executor picks up your provider, merges your tool definitions into the API request, and routes tool calls back to your class.

Step 1 — Create the provider class

Create a PHP file in your plugin. The class must extend SVE_Chat_Tool_Provider and implement two methods:

• get_tool_definitions() — returns the Anthropic tool schema array (name, description, input_schema).
• execute_tool( string $name, array $input ) — runs the tool and returns a JSON string result.

The base class also provides a protected parse_date( string $value, string $default ) helper for tools that accept date inputs.

Step 2 — Register the provider

Hook into sve_chat_tool_providers on plugins_loaded. The filter receives an array of provider instances and must return the modified array.

Complete example — Work Order search tool

The following example adds a search_work_orders tool from a hypothetical SVE Maintenance plugin, so residents can ask the chat “Is my fence repair request still open?” or “What maintenance requests are pending in my area?”

<?php
/**
 * SVE_Maintenance_Chat_Tool — adds work-order search to SVE Chat.
 *
 * File: wp-content/plugins/sve-maintenance/includes/class-maintenance-chat-tool.php
 */
defined( 'ABSPATH' ) || exit;

class SVE_Maintenance_Chat_Tool extends SVE_Chat_Tool_Provider {

    /**
     * Tell Anthropic what this tool does and what inputs it accepts.
     */
    public function get_tool_definitions(): array {
        return [
            [
                'name'        => 'search_work_orders',
                'description' => 'Search SVE maintenance work orders. Use this when a '
                               . 'resident asks about repair requests, maintenance status, '
                               . 'or open work orders in the community.',
                'input_schema' => [
                    'type'       => 'object',
                    'properties' => [
                        'status' => [
                            'type'        => 'string',
                            'description' => 'Filter by status: open, in_progress, completed, or all.',
                        ],
                        'location' => [
                            'type'        => 'string',
                            'description' => 'Optional area name (e.g. "pool", "tennis courts", "gate").',
                        ],
                        'since_date' => [
                            'type'        => 'string',
                            'description' => 'Only return work orders submitted after this date (Y-m-d).',
                        ],
                    ],
                    'required' => [],
                ],
            ],
        ];
    }

    /**
     * Execute the tool and return a JSON string for the model.
     */
    public function execute_tool( string $name, array $input ): string {
        // Guard: make sure our plugin's class is available.
        if ( ! class_exists( 'SVE_Work_Order' ) ) {
            return wp_json_encode( [ 'error' => 'Maintenance plugin is not active.' ] );
        }

        $status   = sanitize_key( $input['status']   ?? 'open' );
        $location = sanitize_text_field( $input['location'] ?? '' );
        $since    = $this->parse_date( $input['since_date'] ?? '', '' );

        // Query work orders from the maintenance plugin.
        $orders = SVE_Work_Order::query( [
            'status'   => $status,
            'location' => $location,
            'since'    => $since,
            'limit'    => 15,
        ] );

        if ( empty( $orders ) ) {
            return wp_json_encode( [
                'message' => 'No work orders found matching your criteria.',
                'orders'  => [],
            ] );
        }

        $results = array_map( static fn( $o ) => [
            'id'          => $o->id,
            'title'       => $o->title,
            'status'      => $o->status,
            'location'    => $o->location,
            'submitted'   => $o->submitted_at,
            'description' => mb_substr( $o->description, 0, 200 ),
        ], $orders );

        return wp_json_encode( [ 'work_orders' => $results ] );
    }
}

Then register the provider in your plugin’s main file:

// In sve-maintenance.php (or wherever your plugin bootstraps)

add_action( 'plugins_loaded', function (): void {
    // Only register if SVE Chat is active.
    if ( ! class_exists( 'SVE_Chat_Tool_Provider' ) ) {
        return;
    }

    require_once __DIR__ . '/includes/class-maintenance-chat-tool.php';

    add_filter( 'sve_chat_tool_providers', function ( array $providers ): array {
        $providers[] = new SVE_Maintenance_Chat_Tool();
        return $providers;
    } );
} );

That’s all. No changes to SVE Chat are required. Once registered, Claude will automatically consider calling search_work_orders whenever a resident’s question is relevant to maintenance.

Rules for tool definitions

• Tool names must be unique across all providers. Use a plugin-specific prefix (e.g. myplugin_search_foo) to avoid collisions.
• Descriptions matter. Claude decides whether to call a tool based entirely on its description. Write it from the resident’s perspective — describe the kinds of questions that should trigger the tool.
• Keep results compact. Tool results are inserted back into the Claude context window. Truncate long text fields, cap list sizes, and avoid returning binary data.
• Always return valid JSON. Use wp_json_encode(). An invalid return value will cause the agentic loop to fail.

Configuration Constants

These constants in includes/class-chat-handler.php control core AI behavior. Edit them to tune performance and cost.

Actions & Filters

add_filter( 'sve_chat_tool_providers', function( array $providers ): array {
    $providers[] = new My_Plugin_Chat_Tool_Provider();
    return $providers;
} );

add_action( 'sve_chat_unanswered_question', function( string $question, ?int $user_id, string $ip ): void {
    // Send an admin notification, log to Slack, create a ticket, etc.
}, 10, 3 );