AI Chat Assistant
Relevant source files
The following files were used as context for generating this wiki page:
The AI Chat Assistant provides a conversational interface for users to query and manage household data. It allows users to ask questions about contracts, warranties, trips, vehicles, properties, inventory, and wealth. The assistant operates in a read-only capacity for existing data but can propose new records or updates, which require explicit user confirmation before any database writes occur.
Sources: PRODUCT.md:27-27, src/app/(app)/assistant/page.tsx:64-68
System Architecture
The assistant uses a client-server architecture centered around a React client component and a streaming API. The system enforces privacy by keeping chat conversations private to the individual user, unlike other household data which is shared.
Components and Data Flow
- AssistantPage: Validates the user session and AI configuration. It fetches existing chat threads and messages for the user.
- AssistantClient: Manages the local UI state, including message history, streaming status, and thread navigation.
- API Handler (
/api/chat): Receives user messages and returns a Server-Sent Events (SSE) stream containing text deltas, tool calls, and proposed actions. - Tool Registry: A collection of functions that the AI agent can call to retrieve data or validate proposed changes.
The diagram shows the synchronous request from the client to the API, followed by asynchronous tool execution and SSE streaming back to the UI.
Sources: src/app/(app)/assistant/page.tsx:14-16, src/components/AssistantClient.tsx:50-109, src/lib/chat/tools.ts:326-348
Chat Threads and Privacy
Chat threads are the only data in Hearth that is not household-wide. They remain private to the creator. The system supports multiple persistent conversations, which users can navigate via a thread list.
| Feature | Description |
|---|---|
| Privacy | Threads stay private to the user who started them. |
| Persistence | Conversations are stored and can be resumed later via threadId. |
| Validation | The system falls back to a fresh conversation if a requested thread belongs to another user. |
Sources: src/app/(app)/assistant/page.tsx:53-57, PRODUCT.md:144-145
AI Tools and Capabilities
The assistant interacts with household data through a set of "Tools". These tools are categorized as read tools (fetching data) or guarded write tools (proposing changes).
Read Tools
Read tools allow the assistant to search and list data across all modules.
list_contracts: Lists contracts filtered by status or category.search_contracts: Searches contracts by title, provider, or notes.upcoming_renewals: Identifies active contracts ending within a specific horizon.spend_summary: Calculates estimated monthly spend.net_worth: Summarizes wealth, property, and inventory values.
Sources: src/lib/chat/tools.ts:77-160, src/lib/chat/tools.ts:219-226
Guarded Write Tools (Proposals)
Guarded write tools do not perform database mutations directly. Instead, they validate input against Zod schemas and return a "proposed action" to the UI.
Proposed actions ensure that nothing is written to the database without the requesting member's explicit confirmation.
Sources: src/lib/chat/tools.ts:233-247, src/components/ChatMessageList.tsx:13-14
Tool Configuration and Permissions
Access to tools is dynamically restricted based on the user's role and enabled household modules.
| Constraint | Enforcement Logic |
|---|---|
| Role: READONLY | Cannot use tools marked with isWrite: true. |
| Module Check | Tools for optional modules (e.g., TRAVEL, WEALTH) are only available if the module is enabled. |
| Error Handling | Tool failures return JSON error payloads to the LLM to allow for retries. |
Sources: src/lib/chat/tools.ts:33-40, src/lib/chat/tools.ts:316-324
SSE Stream Events
The /api/chat endpoint utilizes Server-Sent Events to provide a responsive interface during long-running tool executions or AI thinking.
| Event Type | Purpose |
|---|---|
delta | Incremental text content for the assistant's message. |
tool_call | Notifies the UI which tool is currently running (e.g., "Checking spending..."). |
proposed_action | Delivers a validated payload for a record creation or update. |
done | Indicates completion and provides the final threadId. |
Sources: src/components/AssistantClient.tsx:14-26, src/components/ChatMessageList.tsx:53-61
Conclusion
The AI Chat Assistant integrates deeply with the Hearth household data model while maintaining strict privacy and data integrity boundaries. By using a tool-based proposal system, it offers the convenience of AI-assisted data entry without sacrificing the user's ultimate control over their system of record.
Sources: PRODUCT.md:144-147, src/app/(app)/assistant/page.tsx:64-68