spec

specs/003-ai-chat-window/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: AI Chat Window
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-26
+**Feature**: [Link to spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

specs/003-ai-chat-window/contracts/chat-api.yaml

@@ -0,0 +1,60 @@
+openapi: 3.0.0
+info:
+  title: Document MCP Chat API
+  version: 1.0.0
+paths:
+  /api/chat:
+    post:
+      summary: Send a message to the AI agent
+      description: Streams the response using Server-Sent Events (SSE).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  type: string
+                history:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      role:
+                        type: string
+                        enum: [user, assistant, system]
+                      content:
+                        type: string
+                persona:
+                  type: string
+                  default: default
+                model:
+                  type: string
+      responses:
+        '200':
+          description: Stream of tokens
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: "data: {\"type\": \"token\", \"content\": \"Hello\"}\n\n"
+  /api/chat/personas:
+    get:
+      summary: List available personas
+      responses:
+        '200':
+          description: List of personas
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: string
+                    name:
+                      type: string
+                    description:
+                      type: string

specs/003-ai-chat-window/data-model.md

@@ -0,0 +1,51 @@
+# Data Model: AI Chat Window
+
+## Entities
+
+### ChatMessage
+Represents a single message in the conversation history.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `role` | `enum` | `user`, `assistant`, `system` |
+| `content` | `string` | The text content of the message |
+| `timestamp` | `datetime` | ISO 8601 timestamp of creation |
+
+### ChatRequest
+The payload sent from Frontend to Backend to initiate/continue a chat.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | `string` | The new user message |
+| `history` | `List[ChatMessage]` | Previous conversation context |
+| `persona` | `string` | ID of the selected persona (e.g., "default", "auto-linker") |
+| `model` | `string` | Optional: Specific OpenRouter model ID |
+
+### ChatResponseChunk (SSE)
+The streaming data format received by the frontend.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `enum` | `token` (text chunk) or `tool_call` (tool execution status) |
+| `content` | `string` | The text fragment or status message |
+| `done` | `boolean` | True if generation is complete |
+
+## Persistence (Markdown Format)
+Saved in `data/vaults/{user_id}/Chat Logs/{timestamp}.md`
+
+```markdown
+---
+title: Chat Session - {timestamp}
+date: {date}
+tags: [chat-log, {persona}]
+model: {model_id}
+---
+
+# Chat Session
+
+## User ({time})
+What is the summary of...
+
+## Assistant ({time})
+Based on your notes...
+```

specs/003-ai-chat-window/plan.md

@@ -0,0 +1,83 @@
+# Implementation Plan: AI Chat Window
+
+**Branch**: `003-ai-chat-window` | **Date**: 2025-11-26 | **Spec**: [specs/003-ai-chat-window/spec.md](spec.md)
+**Input**: Feature specification from `/specs/003-ai-chat-window/spec.md`
+
+## Summary
+
+Implement an integrated AI Chat Window powered by OpenRouter. This involves a new backend `POST /api/chat` endpoint that uses the `openai` client to communicate with LLMs, exposing internal `VaultService` methods as tools. The frontend will receive a new `ChatWindow` component with streaming support (SSE) and persona selection. Chat history will be persisted as Markdown files in the vault.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+ (Backend), TypeScript/React 18 (Frontend)
+**Primary Dependencies**:
+- Backend: `openai` (for OpenRouter), `fastapi` (StreamingResponse)
+- Frontend: `fetch` (Streaming body reading), Tailwind CSS
+**Storage**:
+- Active Session: In-memory (or transient SQLite)
+- Persistence: Markdown files in `Chat Logs/` folder
+**Testing**: `pytest` (Backend), Manual/E2E (Frontend)
+**Target Platform**: Web Application (Linux Dev Environment)
+**Project Type**: Full-stack (FastAPI + React)
+**Performance Goals**: <3s time-to-first-token
+**Constraints**: Must reuse existing `VaultService` logic; no new database services (keep it lightweight).
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- [x] **Brownfield Integration**: Reuses `VaultService` and `IndexerService`. Matches `backend/src` and `frontend/src` structure.
+- [x] **Test-Backed Development**: Backend logic will be unit tested.
+- [x] **Incremental Delivery**: New API route and independent UI component.
+- [x] **Specification-Driven**: All features map to `spec.md` requirements.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-ai-chat-window/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output
+```
+
+### Source Code (repository root)
+
+```text
+backend/
+├── src/
+│   ├── api/
+│   │   └── routes/
+│   │       └── chat.py       # NEW: Chat endpoint logic
+│   ├── services/
+│   │   ├── chat.py           # NEW: Chat orchestration service (OpenAI wrapper)
+│   │   └── prompts.py        # NEW: System prompts/personas definitions
+│   └── models/
+│       └── chat.py           # NEW: Pydantic models for Chat requests/responses
+└── tests/
+    └── unit/
+        └── test_chat_service.py # NEW: Tests for chat logic
+
+frontend/
+├── src/
+│   ├── components/
+│   │   ├── chat/             # NEW: Chat UI Components
+│   │   │   ├── ChatWindow.tsx
+│   │   │   ├── ChatMessage.tsx
+│   │   │   └── PersonaSelector.tsx
+│   └── services/
+│       └── api.ts            # UPDATE: Add chat endpoints
+└── tests/
+```
+
+**Structure Decision**: Standard Full-stack separation. Backend adds a dedicated `chat` service and route to isolate LLM logic from core data services. Frontend adds a self-contained `chat/` directory for UI components.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| N/A       |            |                                     |

specs/003-ai-chat-window/quickstart.md

@@ -0,0 +1,32 @@
+# Quickstart: AI Chat Window
+
+## Prerequisites
+1.  **OpenRouter Key**: Get an API key from [openrouter.ai](https://openrouter.ai).
+2.  **Environment**: Set `OPENROUTER_API_KEY` in `backend/.env`.
+
+## Testing the Backend
+1.  **Start Server**:
+    ```bash
+    cd backend
+    source .venv/bin/activate
+    uvicorn src.api.main:app --reload
+    ```
+2.  **Test Endpoint**:
+    ```bash
+    curl -X POST http://localhost:8000/api/chat \
+      -H "Content-Type: application/json" \
+      -d '{"message": "Hello", "history": []}'
+    ```
+    *Note: This will output raw SSE stream data.*
+
+## Testing the Frontend
+1.  **Start Client**:
+    ```bash
+    cd frontend
+    npm run dev
+    ```
+2.  **Open UI**: Go to `http://localhost:5173`.
+3.  **Chat**: Click the "Chat" button in the sidebar. Select a persona and send a message.
+
+## Verification
+1.  **Check Logs**: After a chat, check `data/vaults/{user}/Chat Logs/` to see the saved Markdown file.

specs/003-ai-chat-window/research.md

@@ -0,0 +1,48 @@
+# Phase 0: Research & Design Decisions
+
+**Feature**: AI Chat Window (`003-ai-chat-window`)
+
+## 1. OpenRouter Integration
+**Question**: What is the best way to integrate OpenRouter in Python?
+**Finding**: OpenRouter is API-compatible with OpenAI. The standard `openai` Python client library is recommended, configured with `base_url="https://openrouter.ai/api/v1"` and the OpenRouter API key.
+**Decision**: Use `openai` Python package.
+**Rationale**: Industry standard, robust, async support.
+**Alternatives**: `requests` (too manual), `langchain` (too heavy/complex for this specific need).
+
+## 2. Real-time Streaming
+**Question**: How to stream LLM tokens from FastAPI to React?
+**Finding**: Server-Sent Events (SSE) is the standard for unidirectional text streaming. FastAPI supports this via `StreamingResponse`.
+**Decision**: Use `StreamingResponse` with a generator that yields SSE-formatted data (`data: ...\n\n`).
+**Rationale**: Simpler than WebSockets, works well through proxies/firewalls, native support in modern browsers (`EventSource` or `fetch` with readable streams).
+
+## 3. Tool Execution Strategy
+**Question**: How to invoke existing MCP tools (`list_notes`, `read_note`) from the chat endpoint?
+**Finding**: The tools are defined as decorated functions in `backend/src/mcp/server.py`. We can import them directly. However, `FastMCP` wraps them. We might need to access the underlying function or just call the wrapper if it allows direct invocation.
+**Decision**: Import the `mcp` object from `backend/src/mcp/server.py`. Use `mcp.list_tools()` to dynamically get tool definitions for the system prompt. Call the underlying functions directly if exposed, or use the `mcp.call_tool()` API if available. *Fallback*: Re-import the service functions (`vault_service.read_note`) directly if the MCP wrapper adds too much overhead/complexity for internal calls.
+**Refinement**: The `server.py` defines tools using `@mcp.tool`. The most robust way is to import the `vault_service` and `indexer_service` instances directly from `server.py` (or a shared module) and wrap them in a simple "Agent Tool" registry for the LLM, mirroring the MCP definitions. This avoids "fake" network calls to localhost.
+
+## 4. Frontend UI Components
+**Question**: What UI library to use for the chat interface?
+**Finding**: Project uses Tailwind + generic React.
+**Decision**: Build a custom `ChatWindow` component using Tailwind. Use a scrollable container for messages and a sticky footer for the input.
+**Rationale**: Lightweight, full control over styling.
+
+## 5. Chat History Persistence
+**Question**: How to store chat history?
+**Finding**: Spec requires saving to Markdown files in the vault.
+**Decision**:
+1.  **In-Memory/Database**: Use a simple `sqlite` table (or just in-memory if stateless) to hold the *active* conversation state for the UI.
+2.  **Persistence**: On "End Session" or auto-save (debounced), dump the conversation to `Chat Logs/{timestamp}-{title}.md`.
+**Rationale**: Markdown is the source of truth. The database is just for the "hot" state to avoid parsing MD files on every new message.
+
+## 6. System Prompts & Personas
+**Question**: How to manage prompts?
+**Decision**: Store prompts in a simple dictionary or JSON file in `backend/src/services/prompts.py`.
+**Structure**:
+```python
+PERSONAS = {
+    "default": "You are a helpful assistant...",
+    "auto-linker": "You are an expert editor. Your goal is to densely connect notes...",
+}
+```
+

specs/003-ai-chat-window/spec.md

@@ -0,0 +1,85 @@
+# Feature Specification: AI Chat Window
+
+**Feature Branch**: `003-ai-chat-window`  
+**Created**: 2025-11-26  
+**Status**: Draft  
+**Input**: User description: "Add an AI Chat Window using OpenRouter as the LLM provider. The system should reuse existing MCP tools (backend agent) to manage the vault. Include a 'Persona/Mode' selector to allow users to choose specialized system prompts for tasks like reindexing, cross-linking, and summarization. Chat history should be persisted to the vault."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - General Q&A with Vault Context (Priority: P1)
+
+As a user, I want to ask questions about my notes so that I can quickly find information or synthesize concepts without manually searching.
+
+**Why this priority**: This is the core value proposition—enabling natural language interaction with the knowledge base.
+
+**Independent Test**: Can be tested by asking a question about a known note and verifying the answer cites the correct information.
+
+**Acceptance Scenarios**:
+
+1. **Given** the chat window is open, **When** I ask "What is the summary of project X?", **Then** the agent searches the vault and returns a summary based on the note content.
+2. **Given** a specific note is open, **When** I ask "Summarize this", **Then** the agent reads the current note context and provides a summary.
+
+---
+
+### User Story 2 - Vault Management via Personas (Priority: P2)
+
+As a power user, I want to select specialized "Personas" (e.g., Auto-Linker, Tag Gardener) so that I can perform complex maintenance tasks with optimized prompts.
+
+**Why this priority**: Distinguishes this from a simple "chatbot" by adding workflow automation capabilities.
+
+**Independent Test**: Select a persona, give a relevant command, and verify the specific tool (write/update) is called.
+
+**Acceptance Scenarios**:
+
+1. **Given** the "Auto-Linker" persona is selected, **When** I ask "Fix links in Note A", **Then** the agent identifies unlinked concepts and updates the note with `[[WikiLinks]]`.
+2. **Given** the "Tag Gardener" persona is selected, **When** I ask "Clean up tags", **Then** the agent identifies synonymous tags and standardizes them across affected notes.
+
+---
+
+### User Story 3 - Chat History Persistence (Priority: P3)
+
+As a user, I want my chat conversations to be saved in the vault so that I can reference past insights or continue working later.
+
+**Why this priority**: Ensures work isn't lost and integrates chat logs as first-class citizens in the vault.
+
+**Independent Test**: Refresh the browser and verify the previous conversation is still visible.
+
+**Acceptance Scenarios**:
+
+1. **Given** I have had a conversation, **When** I refresh the page, **Then** the chat history is restored.
+2. **Given** a conversation is finished, **When** I look in the vault file explorer, **Then** I see a new Markdown file (e.g., in `Chat Logs/`) containing the transcript.
+
+---
+
+### Edge Cases
+
+- **Network Failure**: What happens if OpenRouter is down? (System should show error and allow retry).
+- **Large Context**: What happens if the vault search returns too much text? (Agent should truncate or summarize input).
+- **Invalid Tool Use**: What happens if the agent tries to write a file with invalid characters? (System should catch error and ask agent to retry).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST provide a UI interface for Chat (floating or sidebar) that persists across navigation.
+- **FR-002**: System MUST allow users to configure an OpenRouter API Key (via env vars or UI settings).
+- **FR-003**: System MUST expose existing internal MCP tools (`read_note`, `write_note`, `search_notes`, etc.) to the LLM.
+- **FR-004**: System MUST support selecting "Personas" that inject specific system prompts (Auto-Linker, Tag Gardener, etc.) into the context.
+- **FR-005**: Chat sessions MUST be automatically saved to the vault as Markdown files (e.g., in a `Chat Logs` folder).
+- **FR-006**: System MUST stream LLM responses to the UI for real-time feedback.
+- **FR-007**: System MUST support creating new chat sessions and switching between past sessions.
+
+### Key Entities
+
+- **Chat Session**: Represents a conversation thread. Properties: ID, Title, Created Date, Messages (User/Assistant/Tool).
+- **Persona**: A preset configuration of System Prompt + available Tools.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Agent responses start streaming within 3 seconds of user input.
+- **SC-002**: 95% of "Auto-Linker" requests result in valid WikiLinks being added without syntax errors.
+- **SC-003**: Users can switch between active chat and past history (refresh/reload) with zero data loss.
+- **SC-004**: System can handle a context window of at least 16k tokens (supporting moderate-sized note analysis).

specs/003-ai-chat-window/tasks.md

@@ -0,0 +1,74 @@
+# Tasks: AI Chat Window
+
+**Feature Branch**: `003-ai-chat-window`
+**Spec**: [specs/003-ai-chat-window/spec.md](spec.md)
+**Plan**: [specs/003-ai-chat-window/plan.md](plan.md)
+
+## Phase 1: Setup
+*Goal: Initialize project structure and install dependencies.*
+
+- [ ] T001 Create contracts directory and API spec at specs/003-ai-chat-window/contracts/chat-api.yaml
+- [ ] T002 [P] Create directory backend/src/services/chat
+- [ ] T003 [P] Create directory frontend/src/components/chat
+- [ ] T004 Add openai dependency to backend/requirements.txt
+
+## Phase 2: Foundational
+*Goal: Core backend logic for Chat (Service Layer).*
+
+- [ ] T005 [US1] Define ChatMessage and ChatRequest models in backend/src/models/chat.py
+- [ ] T006 [US1] Define Persona and Prompt models in backend/src/models/chat.py
+- [ ] T007 [US2] Implement prompt storage (dictionary of personas) in backend/src/services/prompts.py
+- [ ] T008 [US1] Create ChatService class skeleton in backend/src/services/chat.py
+
+## Phase 3: User Story 1 - General Q&A with Vault Context
+*Goal: Enable basic chat interactions with streaming and tool use.*
+*Test Criteria: Can ask a question and get a streaming response citing vault notes.*
+
+- [ ] T009 [US1] Implement OpenAI client initialization in backend/src/services/chat.py
+- [ ] T010 [US1] Implement tool registry (wrap VaultService/IndexerService) in backend/src/services/chat.py
+- [ ] T011 [US1] Implement stream_chat method with SSE generator in backend/src/services/chat.py
+- [ ] T012 [US1] Create unit tests for ChatService in backend/tests/unit/test_chat_service.py
+- [ ] T013 [US1] Implement POST /api/chat endpoint in backend/src/api/routes/chat.py
+- [ ] T014 [US1] Register chat router in backend/src/api/main.py
+- [ ] T015 [P] [US1] Create ChatMessage component in frontend/src/components/chat/ChatMessage.tsx
+- [ ] T016 [US1] Create ChatWindow component skeleton in frontend/src/components/chat/ChatWindow.tsx
+- [ ] T017 [US1] Implement streaming fetch logic in frontend/src/services/api.ts
+- [ ] T018 [US1] Connect ChatWindow to API and handle SSE stream in frontend/src/components/chat/ChatWindow.tsx
+
+## Phase 4: User Story 2 - Vault Management via Personas
+*Goal: Allow users to select specialized agents for maintenance tasks.*
+*Test Criteria: Selecting "Auto-Linker" injects the correct system prompt and tools.*
+
+- [ ] T019 [US2] Add GET /api/chat/personas endpoint to backend/src/api/routes/chat.py
+- [ ] T020 [P] [US2] Create PersonaSelector component in frontend/src/components/chat/PersonaSelector.tsx
+- [ ] T021 [US2] Add persona selection state to frontend/src/components/chat/ChatWindow.tsx
+- [ ] T022 [US2] Update ChatService to accept and apply persona ID in backend/src/services/chat.py
+
+## Phase 5: User Story 3 - Chat History Persistence
+*Goal: Save conversation logs to the vault.*
+*Test Criteria: Chat logs appear as Markdown files in "Chat Logs/" folder.*
+
+- [ ] T023 [US3] Implement save_chat_log method in backend/src/services/chat.py (Markdown formatting)
+- [ ] T024 [US3] Update POST /api/chat to auto-save on completion (or session end) in backend/src/api/routes/chat.py
+- [ ] T025 [US3] Add logic to restore history from ChatRequest.history in backend/src/services/chat.py
+- [ ] T026 [US3] Add "Clear History" or "New Chat" button in frontend/src/components/chat/ChatWindow.tsx
+
+## Phase 6: Polish & Cross-Cutting Concerns
+*Goal: Final UI touches and error handling.*
+
+- [ ] T027 [P] Style ChatWindow with Tailwind (responsive sidebar/floating) in frontend/src/components/chat/ChatWindow.tsx
+- [ ] T028 Implement error handling for OpenRouter failures in backend/src/services/chat.py
+- [ ] T029 Add tool execution status messages to UI stream in frontend/src/components/chat/ChatMessage.tsx
+
+## Dependencies
+
+- **US1** depends on Setup & Foundational tasks.
+- **US2** extends US1 (can be parallelized after US1 backend is stable).
+- **US3** extends US1 backend logic.
+
+## Implementation Strategy
+
+1.  **MVP (US1)**: Get the chat bubble working with a hardcoded "Hello World" stream, then hook up OpenRouter.
+2.  **Tools**: Enable `read_note` and `search_notes` so the agent isn't blind.
+3.  **Personas (US2)**: Add the dropdown and the specialized prompts.
+4.  **Persistence (US3)**: Add the file writing logic last.