Relevant source files

The following files were used as context for generating this wiki page: - [backend/app/ARCHITECTURE.md](https://github.com/BalaBenna/Grace-AI/blob/main/backend/app/ARCHITECTURE.md) - [backend/app/modes/chat/prompt.md](https://github.com/BalaBenna/Grace-AI/blob/main/backend/app/modes/chat/prompt.md) - [backend/app/modes/computer/prompt.md](https://github.com/BalaBenna/Grace-AI/blob/main/backend/app/modes/computer/prompt.md) - [supabase/migrations/020_add_phase2_prompts.sql](https://github.com/BalaBenna/Grace-AI/blob/main/supabase/migrations/020_add_phase2_prompts.sql) - [supabase/migrations/014_update_phase1_prompt_templates.sql](https://github.com/BalaBenna/Grace-AI/blob/main/supabase/migrations/014_update_phase1_prompt_templates.sql) - [backend/app/prompts/system.py](https://github.com/BalaBenna/Grace-AI/blob/main/backend/app/prompts/system.py)

# Creating Custom Chat Modes In the Grace AI platform, **Modes** represent specialized operating configurations for the AI assistant. Each mode defines a unique combination of identity, behavior, toolsets, and execution loops. By utilizing a modular architecture, developers can extend the system by creating new modes that cater to specific user intents, such as deep research, technical development, or autonomous task execution. The system currently leverages a multi-stage orchestration engine that classifies user queries and routes them to the appropriate mode. Whether it is a conversational assistant like **Grace Chat** or an autonomous agent like **Grace Computer**, the architecture ensures that the underlying LLM is provided with the correct prompt overlays and tool registries required for the task. ## Architectural Overview Grace AI implements a "Mode Dispatcher" pattern within the backend API. When a request is sent to the chat endpoint, the system resolves the mode per request and initializes the corresponding agentic loop. ### Mode Dispatcher Logic The following diagram illustrates how the system routes a user request to a specific mode based on the `mode` parameter or internal classification. ```mermaid graph TD User[User Request] --> API[POST /api/v1/chat/{chat_id}/messages] API --> Dispatcher{Mode Dispatcher} Dispatcher --> |grace_chat| ChatAgent[run_agentic_loop] Dispatcher --> |grace_computer| ComputerAgent[run_grace_computer] Dispatcher --> |research| ResearchAgent[Phase 2 Research Mode] Dispatcher --> |developer| DevAgent[Phase 2 Developer Mode] subgraph Loops ChatAgent --> C_Loop[6-round cap loop] ComputerAgent --> Comp_Loop[Plan-Exec-Verify loop] end ``` Sources: [backend/app/ARCHITECTURE.md:44-55](), [supabase/migrations/020_add_phase2_prompts.sql:130-180]() ### Core Mode Components To create a new mode, developers must implement several key artifacts within the `app/modes/` directory: | Component | File Path Pattern | Purpose | | :--- | :--- | :--- | | **Agent Logic** | `app/modes//agent.py` | Defines the execution loop (e.g., sequential vs. plan-based). | | **Tool Registry** | `app/modes//tools.py` | Restricts or expands the available tools for the mode. | | **System Prompt** | `app/modes//prompt.md` | Defines the persona, identity, and behavioral rules. | | **Prompt Overlay** | `app/modes//prompts.py` | Dynamically builds the final prompt with context. | Sources: [backend/app/ARCHITECTURE.md:73-81](), [backend/app/modes/chat/prompt.md:1-10]() ## Existing Mode Implementations The platform ships with several predefined modes that serve as templates for custom implementations. These are primarily stored in the database as `prompt_templates` or as local markdown files. ### 1. Grace Chat (Conversational) Designed as a direct conversational assistant. It focuses on lead-with-the-answer responses and surgical tool usage. It is the default experience for users. * **Default Model:** `claude-sonnet-4-6` * **Tool Set:** Web search, files, skills, memory, and chat search. Sources: [backend/app/ARCHITECTURE.md:49](), [backend/app/modes/chat/prompt.md:1-15]() ### 2. Grace Computer (Autonomous) Modeled after autonomous agents, it operates in an "Observe -> Plan -> Execute -> Verify -> Deliver" loop. It uses a scratchpad (e.g., `todo.md`) in a persistent sandbox to track progress. * **Default Model:** `claude-opus-4-7` * **Capabilities:** Full chat tools + code execution + deep research. Sources: [backend/app/ARCHITECTURE.md:52](), [backend/app/modes/computer/prompt.md:1-25]() ### 3. Specialized Phase 2 Modes Additional modes are defined via SQL migrations in the `prompt_templates` table: * **Research Mode:** Evidence-first approach with structured explanations and mandatory citation blocks. * **Developer Mode:** Focuses on actionable technical guidance, architecture tradeoffs, and debugging checklists. * **Creative Mode:** Prioritizes imagination, tone matching, and collaboration on user ideas. Sources: [supabase/migrations/020_add_phase2_prompts.sql:130-313](), [supabase/migrations/014_update_phase1_prompt_templates.sql:11-80]() ## Steps to Add a New Custom Mode Adding a custom mode involves both backend code registration and prompt definition. ### Step 1: Define the Mode Schema First, the new mode must be registered in the backend schemas to be recognized by the API. 1. Add a `ModeEnum` value in `app/schemas/chat.py`. 2. Register a `ModeConfig` in `app/modes/registry.py`. Sources: [backend/app/ARCHITECTURE.md:73-81]() ### Step 2: Implement the Prompt Template Prompts can be defined in `app/prompts/system.py` or inserted into the Supabase `prompt_templates` table. A robust system prompt should follow the Grace AI standard: * **Identity:** Always identify as "Grace AI, built by Mana Intelligence." * **Response Guidelines:** Use the `` and `` blocks to ensure markdown consistency. * **Tool Instructions:** Proactively define how tools should be used (e.g., parallel tool calls). ```python # Example Prompt Template variables { "name": "new_custom_mode", "content": "You are Grace AI in [Custom] Mode...", "active_flag": true, "tags": ["mode", "custom"], "mode": "chat" } ``` Sources: [backend/app/prompts/system.py:15-100](), [supabase/migrations/020_add_phase2_prompts.sql:10-30]() ### Step 3: Database Registration If the mode is managed via the database, a migration is required to add the prompt template. ```sql INSERT INTO prompt_templates (id, name, content, version, active_flag, tags, mode) VALUES ( gen_random_uuid(), 'custom_mode_name', E'You are Grace AI in Custom Mode...', 1, true, '["mode", "phase2"]'::jsonb, 'chat' ); ``` Sources: [supabase/migrations/020_add_phase2_prompts.sql:1-15]() ## Mode Execution and Verification The system uses a state machine for agentic modes (particularly Grace Computer) to ensure tasks are completed reliably. ```mermaid stateDiagram-v2 [*] --> Understand: Goal Clarification Understand --> Plan: Atomic Steps Plan --> Execute: Tool suite usage Execute --> Observe: Check Changes Observe --> Verify: Success Criteria Verify --> Execute: Retry (up to 2x) if fail Verify --> Deliver: Final Artifacts Deliver --> [*] ``` Sources: [backend/app/modes/computer/prompt.md:7-15]() ### Verification Logic For autonomous modes, the agent must verify each success criterion. This is enforced by a verification contract that expects a strict JSON response. * **Plan Contract:** Requires `goal`, `steps`, and `success_criteria`. * **Verify Contract:** Requires `passed` (boolean), `criteria` (list), and `summary`. Sources: [backend/app/modes/computer/prompt.md:46-70]() ### Tool Set Customization Each mode can be restricted to specific tools to prevent hallucinations or unnecessary overhead. For example, **Concise Mode** skips pleasantries and elaborations, while **Research Mode** mandates the use of `retrieval_context` and `web_search`. Sources: [supabase/migrations/014_update_phase1_prompt_templates.sql:100-140](), [backend/app/modes/chat/prompt.md:45-65]() ## Summary Creating custom chat modes in Grace AI allows for the development of highly specialized AI personalities and autonomous workflows. By combining the **Mode Dispatcher** in the FastAPI backend with structured **Prompt Templates** in Supabase, developers can define how the AI identifies, thinks, and interacts with tools. Key to success is adhering to the established identity of "Grace AI" while providing specific success criteria and behavior loops for specialized tasks.