Skip to content

ui.md

Latest commit

 

History

History
432 lines (323 loc) · 11.9 KB

ui.md

File metadata and controls

432 lines (323 loc) · 11.9 KB
Raw

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: 
    pip install crisp-t[copilot]
  3. GitHub Copilot CLI installed and configured:

Verify Installation

Check that everything is installed correctly:

# 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):

crisp-ui

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

Advanced Usage

# 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:

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:

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:

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
  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:

crisp-ui --port 8080

Advanced Topics

Using Ollama for Local Models

  1. Install and start Ollama:

    # 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:

    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:

License

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