V

VilaAI Technical Briefing

June 6, 2026
15:50 JST
Static Deployment
Executive Gap Analysis

VilaAI vs AirPilot & LibCyberAI

Key Insight: VilaAI recently introduced custom WHMCS operational tools and highly polished Telegram safeguards that do not exist in AirPilot or the LibCyberAI custom worktree. While AirPilot handles broader multi-tenant SaaS conversation tables, VilaAI delivers deep WHMCS-integrated chat diagnostics, webhook claim token locking, retroactive promo redemption engines, and policy-enforced auto-refund rules.

This brief outlines the technical divergence of the modules. It assesses codebase structure, active developer worktrees, API integrations, and maps out porting priorities for aligning operational capabilities.

Compared Repository Surfaces

VilaAI Module

VilaAI WHMCS

whmcsModules/vilaai

Dirty Worktree (branch: main)

The primary integration module built on top of WHMCS. Contains active, stateful customer service webhook handlers and automated operations controllers.

  • WHMCS Chat Logs Viewer
  • Telegram Default-Polish & Confirmation
  • Promo Redemption & Auto-Billing
AirPilot SaaS

AirPilot Platform

AirPilot & whmcsModules/airpilot

Dirty Worktree (branch: main)

Composed of two repositories: the core Python SaaS app (AirPilot) and a thin WHMCS billing/client connector. Contains robust database conversation engines but lacks localized support tools.

  • SaaS Portal Admin Conversation API
  • Telegram Webhook (Basic unique constraints)
  • Promo Redemption WHMCS Integrations
LibCyberAI fork

LibCyberAI Variant

LibCyberAI

Dirty Worktree (branch: libcyberai)

A single-tenant white-label fork of AirPilot. Structured for strict BYOK (Bring Your Own Key) operation. It has removed all billing-related code blocks and platform reliance by design.

  • WHMCS Connector / Billing Hook
  • Telegram Callbacks (Manual /polish only)
  • Platform Key Fallback (Strict BYOK)

Recent Additions & Commit History

Dataset Sync & Platform Config Update

Jun 1, 2026
Synchronized data/train.json download URL to version v2.12.21. Added production rules and localized links for the Fire TV APK deployment.

Billing Automation & Staged Refund Policy

Late May 2026
Implemented a staged 5-working-day review window for refunds in PromptRepository. Restricts agent prompts from making direct refund promises and triggers active user retention scripts. Integrated automatic cancellation of stale invoice renewals during customer account merges.

High-Tier Endpoint Fallback Transport

Mid May 2026
Added fallback handling logic to manage failures on high-tier models. If the xhigh transport endpoint fails, the system automatically clamps and routes the request to standard OpenAI high compatible APIs without breaking client feedback loops.

Retroactive Promo Redemption Engine

Early May 2026
Created active tools allowing support agents to evaluate and apply promo discounts retrospectively. Syncs discount parameters directly back into active WHMCS client invoices.

Active Worktree Local Modifications (Uncommitted Files)

The following files are modified locally in whmcsModules/vilaai and represent the experimental additions currently undergoing validation:

admin_replies.php api/public/chat.php api/webhooks/telegram.php data/train.json src/Controllers/Admin/LogsController.php src/Services/Telegram/MenuStateRepository.php vilaai.php docs/prototypes/

Telegram Notification Interactivity: Before vs After

AirPilot alerts lack inline dashboard routing, whereas VilaAI embeds parameterized links pointing directly into localized WHMCS client logs.

AirPilot / Generic Notification Basic Alert Only
AirPilot Support Bot bot
Support Chat #1042 has a new message from Client #248. Reply to this notification directly to send a message back.
15:42
Behavior limitations: Support agents must log in to the portal separately and search manually for the Client ID to find the conversation thread.
VilaAI Notification Deep Link Enabled
VilaAI Support Bot bot
Support Chat #1042 (Client: Jane Doe) has a new message from Client #248. Click link below to view.
15:43
Open WHMCS Chat Logs
Deep link hydration: Automatically parses message details, aggregates them using the configured session gap time window, and points directly to the correct conversation view in WHMCS.

Telegram Default-Polish & Confirmation Safe-fail Flow

VilaAI mitigates LLM-polishing failures. Instead of sending raw text, it holds the payload, frees the lock state, and presents administrative confirmation overrides.

1 Receive Webhook Update
Telegram triggers webhook at api/webhooks/telegram.php.
Concurrency Check ↓
2 Duplicate & Stale Claim Tokens (shouldProcessUpdate)
Validates claim token state. If duplicate update request is in-flight, returns 503 Service Unavailable. Stale updates (>30 minutes) are purged, allowing locks to release.
If lock acquired ↓
3 Evaluate Polish Status (maybePolishDefaultReply)
Checks if telegram_polish_by_default is set. If true, hands off response to LLM engine to apply customer service polish.
If polish execution fails or returns blank ↓
4 Raw-Confirm Safe Gate Triggered
Saves the unpolished response into pending_raw_reply inside the MenuStateRepository. Immediately clears the locked pending ticket state so other processes don't deadlock.
Webhook Response sent to Admin ↓
Option A: Send As-Is
Admin selects the Send as-is button callback. Sends the raw response text directly to the customer. Clears memory buffer.
Option B: Cancel (Stale purge after 2h)
Admin selects Cancel or allows a 2-hour timeout to elapse. The MenuStateRepository purges the stale pending_raw_reply.

Feature Parity Matrix

Click on any feature row to inspect detailed comparisons, directory paths, and source code anchors.

Feature Description VilaAI Support AirPilot Support LibCyberAI Support
WHMCS Conversational Log Viewer Admin/Logs
Supported Defaults raw queries to structured conv views. No Local UI SaaS portal has API but WHMCS connector lacks UI. N/A Single-tenant system; no WHMCS module.
VilaAI Implementation Details

LogsController.php groups logs from mod_vilaai_chat_logs using a configurable time gap (vilaai_chat_session_gap_minutes). Supports complex filters like conv, ts, session, q, and hydrates sessions with administrative metadata.

File Anchors & References
VilaAI: src/Controllers/Admin/LogsController.php VilaAI: admin_replies.php AirPilot: app/api/v1/admin_conversations.py
Telegram claim token locking Telegram
Supported Prevents concurrency race conditions. Basic Uses basic processed update constraints. Basic Uses basic processed update constraints.
VilaAI Implementation Details

Uses claim tokens during webhook ingress. Returns 503 for duplicate triggers in progress. Allows stale claims to time out and retry after 30 minutes.

File Anchors & References
VilaAI: api/webhooks/telegram.php -> shouldProcessUpdate() AirPilot: Basic processed updates mapped in SQLAlchemy.
Telegram default-polish / confirmation Telegram
Supported Polishes replies by default; safe-gate fallback. Manual Only Must invoke manual /polish callback buttons. Manual Only Must invoke manual /polish callback buttons.
VilaAI Implementation Details

Enabled via telegram_polish_by_default. If empty output or failure is caught, the response is buffered under pending_raw_reply for 2 hours in MenuStateRepository.php, prompting admin via Telegram to confirm manually or abort.

File Anchors & References
VilaAI: api/webhooks/telegram.php -> maybePolishDefaultReply() VilaAI: src/Services/Telegram/MenuStateRepository.php
Retroactive Promo Redemption Tools & Billing
Supported Supports retroactive invoice corrections. Unsupported No WHMCS promo tooling present. Unsupported Billing infrastructure entirely removed.
VilaAI Implementation Details

Integrates tools evaluate_promo_redemption and apply_promo_redemption, enabling administrators to check and modify invoice details post-issuance.

File Anchors & References
VilaAI: vilaai.php VilaAI: docs/prototypes/
5-Day Review Refund Policy Policy & Transport
Supported Prompt constraints dictate a 5-day review process. Unsupported Default prompts lack refund carve-outs. Unsupported Billing-exempt profile.
VilaAI Implementation Details

System prompts in PromptRepository enforce staged refund procedures: carve-out limits, 5 working days validation audit, suppression of direct refund guarantees, and pre-emptive retention promotion prompts.

File Anchors & References
VilaAI: src/Repositories/PromptRepository.php
xhigh Custom Fallback Clamp Policy & Transport
Supported Clamps model routing if xhigh is offline. Unsupported Lacks dynamic model clamping parameters. N/A (Strict BYOK) Mandatory BYOK disables platform key routing.
VilaAI Implementation Details

Manages backend API timeouts on xhigh transport by catching errors and shifting to standard OpenAI high targets. Prevents blank response errors during provider outages.

File Anchors & References
VilaAI: src/Services/AI/TransportManager.php (or fallback loops in api/public/chat.php)
Core Conversation Database Not a Gap
Supported Integrated WHMCS logger modules. Supported Full conversation database schemas. Supported Client-side sqlite or direct api mapping.
Comparison Analysis

AirPilot features broader conversation APIs and admin dashboard structures (admin_conversations.py) than the thin WHMCS connector alone. The gap lies in operation logs, deep-linking, and automated callback policies rather than the basic existence of conversation databases.

File Anchors & References
AirPilot: app/api/v1/admin_conversations.py VilaAI: src/Controllers/Admin/LogsController.php

WHMCS Module & Billing Tool Parity

Comparison of direct API tools exposed to agents. Note naming conventions and system-specific dependencies.

VilaAI Modules Billing & Promo Support Tools

evaluate_promo_redemption Assesses eligibility criteria for historical promotions.
Active
apply_promo_redemption Applies retro discounts and rebuilds WHMCS invoices.
Active
compensate_overdue_invoice_time Adds compensatory runtime (VilaAI specific naming).
Active
merge_duplicate_services Merges services and cancels outstanding renewal debt.
Active

AirPilot Platform Core Tools

evaluate_promo_redemption Not defined in AirPilot config files.
Missing
apply_promo_redemption Not defined in AirPilot config files.
Missing
compensate_overdue_time Alternate naming used in AirPilot connector.
Active
merge_duplicate_services Missing from connector definitions.
Missing

Porting Priorities & Recommendations

High Priority

Immediate Action
  • Telegram Raw-Confirm Safeguard: Port the pending_raw_reply hold and claim-token verification logic to AirPilot to avoid webhook double-processing and prevent broken or unpolished AI outputs from reaching clients.
  • Hydrated Notification Deep-Links: Add the parameterized addonmodules.php links to AirPilot Telegram notifications to reduce manual search overhead for support agents.
  • Billing Promo Tools: Migrate evaluate_promo_redemption and apply_promo_redemption to sync promotion events with client databases.

Medium Priority

Next Sprint
  • Hardened Refund Staging Policy: Copy the staged 5-working-day review guidelines and retention prompts from VilaAI's PromptRepository into AirPilot core configuration.
  • xhigh Fallback Transport: Implement the OpenAI compatible backup-clamp routing in AirPilot to shield customers from model outages on high-tier API endpoints.

Low / Not Applicable

Deferred
  • LibCyberAI Platform Key Fallbacks: Do not port fallbacks. LibCyberAI is designed specifically as a white-label single-tenant bypass where BYOK is strictly mandatory. Keeping fallback keys absent maintains design constraints.