AI System Configuration

This guide covers configuring the Gemini AI urgency analysis and the AI Knowledge Assistant from the admin panel.

---

Gemini AI Urgency Analysis

Enabling AI Processing

1. Navigate to Admin → Settings → AI Assistant
2. Set Enable AI Processing to Yes
3. Configure the following settings:

Setting	Value	Description
Gemini API Key	Your API key	Shared key for all Gemini features (urgency + assistant + note optimization)
Generative Model	gemini-2.5-flash	Model used for urgency analysis and chat
Enable AI Processing	Yes/No	Master toggle for urgency analysis
Max Tickets Per Cron Run	2 (default)	Configurable throttle for queue processing

Direct Gemini Integration

The system calls the Google Gemini REST API directly (generativelanguage.googleapis.com). There is no proxy or intermediate service.

Model Fallback Chains

If the primary model fails (e.g. 503 overload), fallback models are tried automatically:

Primary	Fallback 1	Fallback 2	Fallback 3
gemini-2.5-flash	gemini-2.5-flash-lite	—	—
gemini-2.5-pro	gemini-2.5-flash	gemini-3-flash-preview	—
gemini-3-pro-preview	gemini-3-flash-preview	gemini-2.5-pro	gemini-2.5-flash

Response Cache

Gemini responses are cached in the database (ost_gemini_response_cache) with a configurable TTL. This avoids redundant API calls for identical ticket content.

• Cache is bypassed during normal queue processing (bypass_cache=true)
• Expired entries are cleaned up automatically during cron runs
• Admin can configure TTL via Settings → AI Assistant

Urgency Criteria Editor

The urgency analysis prompt criteria can be customized:

1. Navigate to Admin → Settings → AI Assistant
2. Find the Urgency Criteria textarea
3. Edit the criteria text to adjust how urgency is evaluated
4. Click Reset to Default to restore the built-in criteria
5. Save settings

How It Works

Once enabled:

1. Every new thread entry (message, response, or note) triggers the motherload plugin
2. The ticket is queued in ost_gemini_queue
3. The cron-gemini.php cron job processes up to 2 tickets per run
4. Results update the ticket's AI custom fields
5. Critical urgency triggers email + SMS + browser notifications

Customer Type Classification

The AI uses "customer type" to calibrate urgency:

Type	Description	Impact
small	Small client, lower hours	Higher urgency threshold
medium	Mid-size client	Standard thresholds
large	Enterprise client, high hours	More nuanced analysis

Customer type is determined automatically based on organization configuration.

Critical Alert Configuration

When AI sets urgency to CRITICAL:

• Email sent to: assigned staff + PMs + department manager
• SMS sent to: PMs (if phone configured and opted in)
• Browser notification to: all subscribed staff
• Alert is deduplicated (one per ticket, tracked in ost_ticket_ai_history)

---

AI Knowledge Assistant ("Burt")

Enabling the Assistant

1. Navigate to Admin → Settings → AI Assistant
2. Set Enable AI Assistant to Yes
3. Configure Pinecone settings:

Setting	Value	Description
Pinecone API Key	Your Pinecone key	Vector database authentication
Pinecone Host	Index host URL	Pinecone serverless endpoint
Enabled Sources	JSON checkboxes	Which sources to include (tickets always active, plus sites/wiki/docs/GSM)
Max Context Results	10	Total results included as chat context
Max Conversation Messages	20	Conversation history depth
Chatbot Name	Burt	Display name used in chat UI and AI persona

Embedding Configuration

Setting	Value	Description
Embedding Model	gemini-embedding-001	768-dimension model for vector generation
Batch Size	50	Tickets processed per cron run
Embedding Cron Interval	Every 10 minutes	How often new tickets are embedded
Conversation Retention	30 days	Auto-delete old conversations

Verifying Embedding Status

Check how many tickets have been embedded:

-- Total embedded tickets
SELECT COUNT(*) FROM ost_ticket_embeddings;

-- Recently embedded
SELECT ticket_id, embedded_at
FROM ost_ticket_embeddings
ORDER BY embedded_at DESC
LIMIT 10;

-- Tickets without embeddings
SELECT t.ticket_id, t.number
FROM ost_ticket t
LEFT JOIN ost_ticket_embeddings e ON t.ticket_id = e.ticket_id
WHERE e.id IS NULL
ORDER BY t.created DESC
LIMIT 20;

---

AI Fields Management

Viewing AI Fields on Tickets

AI fields appear in the ticket detail view sidebar:

• Urgency: Color-coded badge (green/yellow/orange/red)
• Urgency %: Numeric score
• Estimated Hours: AI effort estimate
• Summary: Collapsible HTML summary
• Timeline: Collapsible event timeline
• Suggested Title: Click to apply as ticket subject

Custom Form Configuration

AI fields are attached via osTicket's custom form system:

1. Navigate to Admin → Manage → Forms
2. Find the ticket form with AI fields
3. Fields should have these properties:
   • Visibility: Internal (not shown to clients)
   • Editable: Staff can override AI values
   • Required: No (filled by automation)

---

Cron Job Monitoring

Gemini Queue Status

-- Pending items in queue
SELECT COUNT(*) as pending FROM ost_gemini_queue WHERE processed = 0;

-- Recently processed
SELECT ticket_id, processed_at
FROM ost_gemini_queue
WHERE processed = 1
ORDER BY processed_at DESC
LIMIT 10;

-- Stuck items (queued more than 1 hour ago)
SELECT * FROM ost_gemini_queue
WHERE processed = 0 AND created < NOW() - INTERVAL 1 HOUR;

Embedding Queue Status

# Check cron is running
php cron-embeddings.php --status

---

API Logging

All AI API calls are logged for debugging:

Location: var/logs/api/gemini/ Format: gemini-YYYY-MM-DD.log

Viewing Logs

# Today's Gemini log
cat var/logs/api/gemini/gemini-2026-05-04.log

# Search for a specific ticket
grep "ticket_id.*8826" var/logs/api/gemini/*.log

Log Entry Format

Each entry includes:

• Timestamp
• Request URL
• Request body (ticket data sent to Gemini)
• Response status code
• Response body (AI results)
• Duration (milliseconds)

Sensitive headers (API keys) are automatically redacted in logs.

---

Troubleshooting

Issue	Solution
AI fields not updating	Check ost_gemini_queue for pending items; verify cron is running
"API Error" in logs	Verify Gemini API key is valid; check model fallback chain in logs
Urgency always LOW	Review customer type; check if enough thread content is sent
AI Assistant not responding	Check Pinecone connectivity; verify embeddings exist
Embeddings not generating	Check Gemini embedding API key; review cron error output
Critical alerts not sending	Check dedup table; verify alert email template exists
AI fields blank on ticket	Verify custom form is attached to ticket; check form_entry linkage

---

Disabling AI Features

To disable AI features without removing configuration:

Toggle	Effect
Disable AI Processing	Stops urgency analysis; queue items will accumulate but not process
Disable AI Assistant	Hides chat widget; staff cannot use chatbot
Stop Gemini cron	No processing occurs; queue grows until cron resumes
Stop Embeddings cron	New tickets won't be searchable by AI; existing vectors remain

note

Disabling AI processing does not delete existing AI field values on tickets. Historical data is preserved.