hub/docs/copilot.md

AI Copilot System

Overview

The AI Copilot system provides AI-powered content generation and improvement across multiple areas of the platform. It's a premium module that must be enabled per-business and requires provider API configuration.

Module Gating

Enabling Copilot

Copilot is gated behind the copilot_enabled module flag:

Admin Panel: /admin/businesses → Edit Business → Modules tab → Toggle "Copilot Module"

Database:

UPDATE businesses SET copilot_enabled = true WHERE name = 'Cannabrands';

In Code:

if ($business->copilot_enabled) {
    // Show Copilot buttons
}

In Blade:

@if($business->copilot_enabled)
    {{-- Copilot buttons --}}
@endif

Default Status

• Cannabrands: Enabled by default
• All other businesses: Disabled by default (must be enabled in admin)

AI Provider Configuration

Admin Settings (/admin/ai-settings)

Configure AI providers with:

1. Enable AI Copilot: Master toggle
2. AI Provider: Select from dropdown:
   • Anthropic / Claude
   • OpenAI / ChatGPT
   • Perplexity
   • Canva
   • Jasper
3. API Key: Provider-specific (encrypted in database)
4. Model: Provider-specific model dropdown (populated from config/ai.php)
5. Max Tokens: Request limit (default: 4096)

Provider-Specific Settings

Each provider has separate fields:

• Anthropic:
  • Models: claude-3-5-haiku, claude-3-5-sonnet, claude-sonnet-4-5, etc.
  • API Key format: sk-ant-...
• OpenAI:
  • Models: gpt-4o, gpt-4o-mini, o1-preview, etc.
  • API Key format: sk-...
• Perplexity:
  • Models: llama-3.1-sonar (small/large/huge) 128k-online
  • API Key format: pplx-...
• Canva:
  • Models: text-to-image, design-generation
  • API Key format: canva-...
• Jasper:
  • Models: jasper-command, jasper-chat
  • API Key format: jasper-...

Database Storage

Table: ai_settings (singleton, ID = 1)

Columns:

• is_enabled - Master toggle
• ai_provider - Selected provider (anthropic, openai, etc.)
• anthropic_api_key, openai_api_key, perplexity_api_key, canva_api_key, jasper_api_key - Encrypted
• anthropic_model, openai_model, perplexity_model, canva_model, jasper_model
• max_tokens_per_request

Copilot Buttons

Button Types

Three standard buttons appear when Copilot is enabled:

1. Generate: Create new content from scratch
2. Improve: Enhance existing content
3. Brand Voice: Apply brand voice/tone

Button Markup

@if($business->copilot_enabled)
<div class="flex gap-2 mt-2">
    <button type="button" class="btn btn-xs btn-ghost gap-1">
        <span class="icon-[heroicons--sparkles] size-3 text-primary"></span>
        Generate
    </button>
    <button type="button" class="btn btn-xs btn-ghost gap-1">
        <span class="icon-[heroicons--sparkles] size-3 text-primary"></span>
        Improve
    </button>
    <button type="button" class="btn btn-xs btn-ghost gap-1">
        <span class="icon-[heroicons--sparkles] size-3 text-primary"></span>
        Brand Voice
    </button>
</div>
@endif

Locations Where Copilot Appears

1. Marketing Campaigns (/s/{business}/marketing/campaigns/create|edit)

Campaign Create:

• Subject Line (Email): Generate, Improve, Brand Voice
• Message Body (Email): Generate, Improve, Brand Voice
• Message (SMS): Generate, Improve, Brand Voice

Campaign Edit:

• Same as create (subject + body/message)

2. Marketing Templates (/s/{business}/marketing/templates/create|edit)

• Subject Line: Generate, Improve, Brand Voice
• Body: Generate, Improve, Brand Voice

3. Product Content (/s/{business}/products/edit)

• Name: Generate, Improve, Brand Voice
• SKU: Generate options
• Description: Generate, Improve, Brand Voice
• Tagline: Generate, Improve, Brand Voice
• Full Description: Generate, Improve, Brand Voice

4. Brand Settings (/s/{business}/brands/edit)

• Brand Name: Improve, Brand Voice
• Tagline: Generate, Improve, Brand Voice
• Description: Generate, Improve, Brand Voice
• Brand Voice Definition: Guided prompts for defining voice/tone

Brand Voice System

Configuration

Brand Voice is defined per-brand in Brand Settings:

• Voice/Tone: Casual, professional, witty, authoritative, etc.
• Target Audience: Demographics, psychographics
• Key Messaging: Core values, differentiators
• Style Guidelines: Language preferences, avoided terms

Usage

When "Brand Voice" button is clicked:

1. Fetch brand's voice settings from database
2. Send to AI with context: "Apply this brand voice: [voice definition]"
3. AI rewrites content matching the brand's style
4. Replace textarea content with result

Storage

Brand voice stored in brands table (JSON or text field).

Integration Flow

Example: Email Campaign Subject Generation

1. User clicks "Generate" button next to Subject field
2. Frontend sends AJAX request to /api/copilot/generate
3. Backend:
   • Check $business->copilot_enabled (gate)
   • Fetch AI settings (provider, model, API key)
   • Call AI API with prompt: "Generate an email subject line for [campaign context]"
   • Return AI response
4. Frontend populates subject field with generated text

Error Handling

• Copilot disabled: Buttons don't render
• AI Settings not configured: Show error message
• API key invalid: Show error message with link to AI Settings
• Rate limit exceeded: Show error, suggest retry

Security Considerations

• API keys encrypted using Laravel's Crypt::encryptString()
• Never expose API keys to frontend
• All AI requests server-side only
• Validate copilot_enabled on every request
• Rate limiting on AI endpoints

Future Enhancements

• Context-aware suggestions (use product data, brand history)
• Multi-step generation (outline → full content)
• A/B testing suggestions
• Analytics on Copilot usage
• Cost tracking per business