# CRISP-T Web UI Documentation

## Overview

The CRISP-T Web UI provides a browser-based interface for interacting with CRISP-T's qualitative research tools using the GitHub Copilot SDK. It allows researchers to perform mixed-methods analysis through a conversational AI interface without needing to use the command line directly.

## Features

- **AI-Powered Chat Interface**: Interact with CRISP-T through natural language conversations
- **Multiple Model Support**: Dynamically loads all available models from GitHub Copilot SDK (GPT-5.2, GPT-5.1, GPT-4.1, Claude Opus 4.6, Claude Sonnet 4.5, o-series, and more)
- **Custom Provider Support**: Use local models (Ollama) or custom OpenAI-compatible APIs
- **Real-time Streaming**: Get responses as they're generated
- **CRISP-T CLI Integration**: Full access to all CRISP-T commands (crisp, crispt, crispviz)
- **Easy Configuration**: Simple web interface for setting up your research environment

## Installation

### Prerequisites

1. **Python 3.10+** installed
2. **CRISP-T** installed with Copilot support:
   ```bash
   pip install crisp-t[copilot]
   ```
3. **GitHub Copilot CLI** installed and configured:
   - Follow the [Copilot CLI installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)
   - Login using: `gh auth login` or `copilot auth login`

### Verify Installation

Check that everything is installed correctly:

```bash
# Verify CRISP-T CLI tools
crisp --help
crispt --help
crispviz --help

# Verify Copilot CLI
copilot --version

# Verify Web UI command
crisp-ui --help
```

## Starting the Web UI

### Basic Usage

Start the server on the default host and port (127.0.0.1:5000):

```bash
crisp-ui
```

Then open your browser and navigate to: `http://127.0.0.1:5000`

### Advanced Usage

```bash
# Start on a custom port
crisp-ui --port 8080

# Allow external connections (use 0.0.0.0 to bind to all interfaces)
crisp-ui --host 0.0.0.0 --port 8080

# Run in debug mode (for development)
crisp-ui --debug
```

## User Interface Guide

### Configuration Panel

The left panel contains configuration options:

#### 1. Model Selection
Choose the AI model to use for your research assistant. The Web UI dynamically loads all available models from the GitHub Copilot SDK, including:

**GPT Models:**
- GPT-5.2, GPT-5.1, GPT-5 (latest models with advanced reasoning)
- GPT-5.1 Codex, GPT-5 Codex (optimized for code)
- GPT-4.1, GPT-4o, GPT-4 (proven reliable models)
- GPT-4o Mini (faster, cost-effective)

**Claude Models:**
- Claude Opus 4.6, Claude Opus 4 (most capable)
- Claude Sonnet 4.5, 4, 3.5 (balanced performance)
- Claude Haiku 3.5 (fast responses)

**OpenAI o-series:**
- o3-mini, o1-preview, o1-mini (specialized reasoning models)

The available models depend on your GitHub Copilot subscription and may vary over time. The UI automatically fetches the current list of supported models from the Copilot SDK.

#### 2. Data Source
Specify the path to your research data:
- Enter the path to a folder containing your data files
- Supported formats: `.txt`, `.pdf`, `.csv`
- Example: `./data` or `/home/user/research_data`

#### 3. Advanced Settings

##### Custom Provider
Check this box to use a custom AI provider:
- **Provider Type**: OpenAI, Azure OpenAI, or Anthropic
- **Base URL**: API endpoint (e.g., `http://localhost:11434/v1` for Ollama)
- **API Key**: Your API key (optional for local providers like Ollama)

**Example: Using Ollama locally**
```
Provider Type: OpenAI
Base URL: http://localhost:11434/v1
API Key: (leave empty)
```

##### GitHub Token
Optionally provide a GitHub token for authentication:
- Required if not using the logged-in Copilot CLI session
- Generate a token at: https://github.com/settings/tokens

### Chat Interface

The right panel contains the chat interface:

#### Starting a Session
1. Configure your settings in the left panel
2. Click **"Start Session"**
3. Wait for the connection indicator to turn green
4. Start chatting with the AI assistant

#### Sending Messages
1. Type your message in the text box at the bottom
2. Press **Enter** or click **"Send"**
3. Wait for the AI response

#### Example Conversations

**Importing Data:**
```
You: Import data from ./data folder and show me what's in the corpus
AI: I'll import your data using CRISP-T...
[Executes: crisp --source ./data --out corpus]
```

**Topic Modeling:**
```
You: Perform topic modeling with 5 topics on the imported data
AI: I'll run topic modeling analysis...
[Executes: crisp --inp corpus --topics --num 5 --assign --out corpus]
```

**Visualization:**
```
You: Generate a word cloud of the most frequent terms
AI: I'll create a word cloud visualization...
[Executes: crispviz --inp corpus --wordcloud --out visualizations]
```

**Complex Analysis:**
```
You: Import the CSV data with "comments" as the text column, 
     perform sentiment analysis, and create a correlation heatmap
AI: I'll perform a comprehensive analysis...
[Executes multiple commands in sequence]
```

## Common Workflows

### 1. Basic Qualitative Analysis

```
1. You: "Import data from ./interviews folder"
2. You: "Generate a coding dictionary"
3. You: "Perform topic modeling with 5 topics"
4. You: "Show me the main themes"
5. You: "Create a word cloud visualization"
```

### 2. Mixed-Methods Triangulation

```
1. You: "Import CSV data from ./survey with 'open_response' as text column"
2. You: "Run topic modeling and sentiment analysis"
3. You: "Link the topic findings to the satisfaction_score variable"
4. You: "Run a regression analysis to see which topics predict satisfaction"
5. You: "Create a visualization showing the relationships"
```

### 3. Temporal Analysis

```
1. You: "Import time-stamped data from ./longitudinal"
2. You: "Link documents to rows by nearest timestamp"
3. You: "Filter data to the first quarter of 2025"
4. You: "Analyze sentiment changes over time"
5. You: "Create a temporal summary by week"
```

## Authentication Methods

The Web UI supports multiple authentication methods for GitHub Copilot:

### 1. Logged-in User (Default)
If you've logged in using `gh auth login` or `copilot auth login`, the Web UI will use your stored credentials automatically.

### 2. GitHub Token
Provide a personal access token in the Advanced Settings:
1. Generate a token at https://github.com/settings/tokens
2. Paste it in the "GitHub Token" field
3. Start your session

### 3. Custom Provider (BYOK)
Use your own API keys without GitHub authentication:
1. Check "Use Custom Provider"
2. Select provider type
3. Enter base URL and API key
4. No GitHub token needed

## Troubleshooting

### "Copilot SDK not available" Error

**Problem**: The github-copilot-sdk package is not installed.

**Solution**: Install CRISP-T with Copilot support:
```bash
pip install crisp-t[copilot]
```

### "Command not found" Errors

**Problem**: CRISP-T CLI tools are not in the PATH.

**Solution**: Ensure CRISP-T is installed and accessible:
```bash
which crisp
# If not found, reinstall:
pip install crisp-t[ml]
```

### "Failed to create session" Error

**Problem**: The Copilot CLI is not installed or not logged in.

**Solution**:
1. Install Copilot CLI: Follow [installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli)
2. Login: `gh auth login` or provide a GitHub token in the UI

### Session Not Responding

**Problem**: The session appears stuck or not responding.

**Solution**:
1. Wait a few moments - some operations take time
2. Check the browser console for errors (F12)
3. Stop and restart the session
4. Restart the server if issues persist

### Port Already in Use

**Problem**: Cannot start server on default port 5000.

**Solution**: Use a different port:
```bash
crisp-ui --port 8080
```

## Advanced Topics

### Using Ollama for Local Models

1. Install and start Ollama:
   ```bash
   # Install Ollama (see https://ollama.ai)
   # Pull a model
   ollama pull deepseek-coder-v2:16b
   ```

2. Configure in the Web UI:
   - Check "Use Custom Provider"
   - Provider Type: OpenAI
   - Base URL: `http://localhost:11434/v1`
   - API Key: (leave empty)
   - Model: `deepseek-coder-v2:16b`

3. Start your session and chat!

### Integrating with Azure OpenAI

1. Configure in the Web UI:
   - Check "Use Custom Provider"
   - Provider Type: Azure
   - Base URL: `https://your-resource.openai.azure.com`
   - API Key: Your Azure OpenAI key
   - Model: Your deployment name (e.g., `gpt-4`)

2. Start your session

### Running Behind a Reverse Proxy

If you're running the Web UI behind a reverse proxy (like nginx):

1. Start the server on localhost:
   ```bash
   crisp-ui --host 127.0.0.1 --port 5000
   ```

2. Configure your proxy to forward requests to `http://127.0.0.1:5000`

3. Ensure WebSocket support is enabled in your proxy configuration

## Architecture

The CRISP-T Web UI consists of three main components:

### 1. Quart Web Server (`server.py`)
- Async ASGI web server using Quart (migrated from Flask)
- Session management with Copilot SDK
- REST API endpoints for frontend communication
- Properly handles async operations with native event loop support

### 2. Frontend Interface (`templates/index.html`, `static/*`)
- Configuration panel for settings
- Chat interface for conversations
- Real-time message updates via polling
- Responsive design for various screen sizes

### 3. Copilot SDK Integration
- Creates sessions with custom tools
- Provides `execute_crisp_command` tool to the AI
- Handles streaming responses
- Manages session lifecycle

## API Reference

The Web UI exposes the following REST API endpoints:

### Health Check
```
GET /api/health
Response: {"status": "ok", "copilot_available": true, "version": "1.0.0"}
```

### List Models
```
GET /api/models
Response: {"models": ["gpt-5", "gpt-4.1", "claude-sonnet-4.5", ...]}
```

### Create Session
```
POST /api/session/create
Body: {
  "session_id": "session-123",
  "model": "gpt-5",
  "config": {
    "data_path": "./data",
    "github_token": "ghp_...",  // optional
    "use_custom_provider": true,  // optional
    "provider_type": "openai",
    "provider_base_url": "http://localhost:11434/v1",
    "provider_api_key": "..."  // optional
  }
}
Response: {"status": "ok", "session_id": "session-123", "model": "gpt-5"}
```

### Send Message
```
POST /api/session/{session_id}/send
Body: {"prompt": "Import data from ./data"}
Response: {"status": "ok"}
```

### Get Messages
```
GET /api/session/{session_id}/messages
Response: {
  "messages": [
    {"role": "user", "content": "Hello", "timestamp": "..."},
    {"role": "assistant", "content": "Hi there!", "timestamp": "..."}
  ]
}
```

### Destroy Session
```
POST /api/session/{session_id}/destroy
Response: {"status": "ok"}
```

## Security Considerations

1. **Local Deployment**: By default, the server binds to `127.0.0.1` (localhost only)
2. **Token Storage**: GitHub tokens are not stored on the server - they're kept in memory only
3. **Data Access**: The AI agent can execute CRISP-T commands, which can read/write files
4. **Network Access**: When using external models, your data may be sent to third-party APIs

**Best Practices:**
- Run on localhost for personal use
- Use HTTPS when deploying externally
- Be cautious about data privacy when using cloud models
- Review the CRISP CLI skill to understand what commands can be executed

## Performance Tips

1. **Large Datasets**: Use `--num` and `--rec` flags to limit data during testing
2. **Model Selection**: Faster models like GPT-4.1 for quick iterations
3. **Streaming**: Enabled by default for real-time feedback
4. **Session Management**: Stop sessions when not in use to free resources

## Contributing

To contribute to the Web UI:

1. The UI code is in `src/crisp_t/ui/`
2. Follow the existing code structure
3. Test with multiple models and configurations
4. Update documentation for new features
5. Ensure error handling is comprehensive

## Support

For issues and questions:
- GitHub Issues: https://github.com/dermatologist/crisp-t/issues
- Documentation: https://dermatologist.github.io/crisp-t/
- CRISP-T CLI Skill: `.agents/skills/crisp-cli/`

## License

CRISP-T Web UI is part of the CRISP-T project and is licensed under GPL-3.0.
