Pixahunt Cloud APIs & Community AI Engine Architecture (chat_user, gemini, gemini_brand)

# Pixahunt Cloud APIs & Community AI Engine Architecture Pixahunt manages AI models and external service keys through the **Admin Cloud APIs** system (`/admin/cloud-apis`). To guarantee system stability, model flexibility, and cost optimization, AI operations are strictly partitioned into dedicated roles identified by their `username`. --- ## 1. Cloud API Identifiers (`username` mapping) Pixahunt uses three distinct key identifiers in the `admin_cloud_apis` table: | Identifier (`username`) | Role / Purpose | Supported Engines | Target System Services | | :--- | :--- | :--- | :--- | | **`chat_user`** | **User Messenger Live Chat & Feed Discussions** | Google Gemini (`gemini-2.5-flash`), OpenAI (`gpt-4o-mini`) | `AiChatService`, `TechnicianAgentService`, Discussion Auto-replies | | **`gemini`** | **Specs Auto-fill & General Hardware Data** | Google Gemini | Gadget Product Specifications scraping & benchmarks | | **`gemini_brand`** | **Brand Priority & High-Traffic Extraction** | Google Gemini | High-priority manufacturer spec sync & partner feeds | --- ## 2. Decoupled Chat Engine Architecture (`chat_user`) The live messaging assistant and community comment engine are powered by `App\Services\AiChatService` and queried using `username: 'chat_user'`. ### Future-Proof Model Swapping Pixahunt admins can switch models at any time from `/admin/cloud-apis`: - If an OpenAI key (`sk-proj-...`) is saved under `chat_user`, the system automatically connects to the OpenAI Chat Completions API. - If a Google Gemini key (`AIzaSy...`) is saved, it automatically calls the Gemini Generative Language API. - Zero codebase modifications are required when switching providers. --- ## 3. Technician Agent Hardware-Only Boundary The Pixahunt Technician Agent (`ai_role = 'technician'`, username: `@pixahunt_technician`) operates under strict behavioral rules: 1. **Domain Boundary:** It strictly answers questions about PC hardware, CPUs, GPUs, motherboards, cooling, power supplies (PSUs), bottlenecks, and PC builds. 2. **Non-Hardware Topics:** If mentioned on non-technical posts (e.g. food, sports, general chat), it politely clarifies its hardware lab role and asks how it can help with tech or gadgets instead of hallucinating. 3. **Contextual Awareness:** Before generating a reply to any post or comment, it inspects up to 15 prior comments in the thread to provide a coherent, contextual, and continuous conversation. 4. **1-Hour Shift Refreshment Break:** If a user messages the technician continuously for over 60 minutes, the agent takes a 10-minute refreshment break, simulating a realistic human engineer shift change. --- ## 4. Community Mentions & Friend-Gating Rules Pixahunt discussions support rich user tagging via `@username`: - **AI Mentions:** Any user can call `@pixahunt_technician` at any time to receive expert advice. - **Human Mentions:** Normal users can **only** tag users who are confirmed **friends** (`user_friends` status: `accepted`) or system staff. - **Immediate Notifications:** Tagged users and comment authors receive instant notifications with direct jump-links to the discussion. --- ## 5. Automated Moderation & Pending Status Community submissions undergo real-time screening through `App\Services\ContentModerationService`: - Clean posts and comments are published immediately (`status: 'approved'`). - Posts containing suspicious keywords (betting, gambling, abusive slurs, or repetitive flood characters) are held in `status: 'pending'` with an attached `moderation_note` for admin review and approval at `/admin/discussions`. --- *Updated and maintained by the Pixahunt Engineering & AI Core Team.*