Personal AI Assistant — Product & Engineering Spec | DATASPHERES AI - DATASPHERES AI
Personal AI Assistant — Product & Engineering Spec
Status: Implementation Complete — All Phases + All Gaps Closed | Author: Dataspheres AI ...
Personal AI Assistant — Product & Engineering Spec Status: Implementation Complete — All Phases + All Gaps Closed | Author: Dataspheres AI | Date: March 29, 2026 | Priority: P0 — Core Platform Feature Implementation Branch: feature/personal-ai-assistant All features implemented and verified via curl: Schema (3 models) + migration, unified auth middleware (JWT + API key), conversation CRUD API, SSE streaming with GPT-5, auto tool invocation (AI planning → tool execution → enhanced response), 8 registered tools (list_dataspheres, list_pages, list_datasets, list_sequencers, list_surveys, web_search, trending, analyze), polymorphic message renderer (registry pattern), full-screen shell + bottom bar + modern composer + conversation sidebar + skill actions panel + settings panel + guided empty state, mobile nav integration (AI tab), capacity gate (402 on 0%), reserved URI collision detection, attachment wiring (AdvancedUploadModal), /app/assistant route, personal KB CRUD (add/list/remove entries), conversation export to page, web search tool with real Tavily results A private, persistent AI assistant for every user — accessible from anywhere in the platform via a bottom bar. Full ChatGPT/Gemini-class conversational experience, deeply integrated with all Dataspheres resources via the same REST APIs that power the developer portal. 1. Vision & Principles The Personal AI Assistant is the user's private command center — a persistent, always-available AI chat that understands your dataspheres, pages, surveys, datasets, and sequencers. Unlike datasphere-scoped conversations (which are collaborative and public), this is your private workspace. API-first architecture — Every assistant capability maps 1:1 to a REST API endpoint. If the assistant can do it, a developer can do it via the API. This incentivizes us to build robust, well-documented public APIs. Polymorphic rendering — One AssistantMessage component renders all message types (text, tool results, media, charts, tables) via a registry pattern. No copy-paste per-type components. Chain-of-thought transparency — Users see the assistant's thinking process: status messages, tool invocations, intermediate results, then the final streamed response. Not a black box. Dual auth support — REST APIs accept both session tokens (browser users) and API keys (developer portal). The assistant uses session tokens internally, but the same endpoints work externally with dsk_ keys. Capacity gate trumps all UI — Every AI operation checks user capacity via checkCapacityWithWaterfall before execution. At 0% capacity, the assistant is fully gated — no messages can be sent, and the non-dismissible SubscriptionEducationOverlay takes over. This is not a degraded experience; it is a hard stop with a clear upgrade path. 2. User Experience 2.1 Entry Points Desktop: A slim, fixed bottom bar spanning the viewport width (below page content, above any footer). Contains: AI avatar/icon (left) with subtle breathing animation Truncated last-message preview or "Ask anything..." placeholder Click anywhere on the bar → expands to full-screen assistant overlay ( z-[60] , above all modals) Mobile: Restructure MobileBottomNav from 5 tabs to 5 tabs with new layout: Discover | Research | Upload (center, gold circle) | AI Assistant | Datasphere. Camera tab is removed (merged into Upload). The AI Assistant tab renders the Dataspheres AI logo icon with "AI" label and luxurious-gold accent. Tap → full-screen assistant view. The mobile assistant IS the full-screen view — no intermediate bottom bar. 2.2 Full-Screen Assistant Layout When expanded, the assistant takes over the viewport with three zones: Left sidebar (desktop only, 280px, collapsible): Conversation history — grouped by Today / Yesterday / This Week / Older. Each item shows title (auto-generated from first message) + timestamp. "New Chat" button pinned at top. Search conversations input. Center (flex-1): The active conversation thread. Messages scroll vertically. The composer is pinned at the bottom. AI messages use the Dataspheres AI logo as the avatar with "Dataspheres AI" as the sender name. User messages use their profile avatar. This creates a branded, personal conversation — users are chatting with "Dataspheres AI", not a generic bot. Header bar: Model selector dropdown (left), conversation title (center, editable on click), close button (right, → collapses back to bottom bar). 2.3 The Composer (Modern Input Area) A single, contained input area with all controls inside the bounding box — no external toolbars. Textarea — auto-grows up to 6 lines, then scrolls. Placeholder: "Ask anything about your dataspheres..." Bottom row inside the composer box: Attachment button (paperclip icon) → opens AdvancedUploadModal at high z-index Model selector pill (e.g., "GPT-5" with dropdown caret) Spacer Character/token count (subtle, right-aligned) Send button (arrow-up icon in a circle, dfg-money-green when content pr