---
inclusion: always
---

# Project Structure

## File Organization

```
aisidebar/
├── __init__.py              # Module exports (AISidebar class)
├── aisidebar.py             # Main RevealerWindow implementation
├── chat_widget.py           # Chat UI widget with message handling
├── ollama_client.py         # HTTP client for Ollama REST API
├── ollama_monitor.py        # Availability monitoring with callbacks
├── conversation_manager.py  # Conversation persistence layer
└── data/
    └── conversations/       # JSON conversation files (auto-created)
        └── default.json     # Default conversation transcript
```

## Module Responsibilities

### `aisidebar.py`
- Main window class extending `widgets.RevealerWindow`
- Handles slide-in animation from left side
- Manages window visibility and keyboard focus
- Integrates with Ignis WindowManager

### `chat_widget.py`
- Complete chat UI implementation
- Message list rendering and scrolling
- Input handling and submission
- Background thread management for AI requests
- Ollama availability monitoring integration

### `ollama_client.py`
- Low-level HTTP client for Ollama API
- Model listing with caching
- Blocking chat API calls
- Connection health checking
- Graceful error handling without exceptions

### `ollama_monitor.py`
- Periodic availability checking (30s interval)
- Callback-based state change notifications
- GLib timeout integration for non-blocking checks

### `conversation_manager.py`
- JSON-based conversation persistence
- Atomic file writes for data safety
- Message validation (system/user/assistant roles)
- Timestamp tracking for messages

## Naming Conventions

- Private methods/attributes: `_method_name`, `_attribute_name`
- Widget references: `self._widget_name` (e.g., `self._entry`, `self._message_list`)
- CSS classes: kebab-case (e.g., `ai-sidebar`, `ai-sidebar-content`)
- Constants: UPPER_SNAKE_CASE (e.g., `VALID_ROLES`, `DEFAULT_CONVERSATION_ID`)

## Code Style

- Type hints on function signatures
- Docstrings for classes and public methods
- Dataclasses for structured data (`ConversationState`)
- Context managers for file operations
- Property decorators for computed attributes
- Threading: daemon threads for background work
- Error messages: user-friendly with actionable instructions