# Query Enhancer Plugin Specification

## Overview

The Query Enhancer Plugin uses a fast model to enhance user queries before sending to the main model, dramatically improving response quality especially with "dumb" models. This is particularly useful when using smaller or less capable models that need more context and specificity to produce good results.

**Location:** `plugins/query_enhancer_plugin.py`

**Version:** 1.0.0

## Features

### Query Enhancement

- **Fast model integration**: Uses separate fast model (e.g., qwen3-0.6b) for enhancement
- **Intelligent expansion**: Adds relevant context, clarifies ambiguity, makes queries more specific
- **Length control**: Configurable max length for enhanced queries
- **Keyword filtering**: Skips enhancement for simple greetings and confirmations
- **Performance tracking**: Optional metrics on enhancement time and effectiveness

### LLM Integration

- **Pre-processing**: Enhances queries via `USER_INPUT_PRE` hook before main processing
- **Transparent to user**: Enhancement happens behind the scenes
- **Status display**: Optional status indicator showing enhancement activity
- **Fallback**: Gracefully handles fast model failures (uses original query)

## Configuration

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Enable the plugin (disabled by default) |
| `show_status` | boolean | `true` | Display enhancement status |
| `fast_model.api_url` | string | `"http://localhost:1234"` | Fast model API endpoint |
| `fast_model.model` | string | `"qwen3-0.6b"` | Model name for enhancement |
| `fast_model.temperature` | float | `0.3` | Temperature for enhancement (lower = more deterministic) |
| `fast_model.timeout` | int | `5` | Timeout for enhancement requests (seconds) |
| `max_length` | int | `500` | Maximum enhanced query length |
| `min_query_length` | int | `10` | Minimum query length to enhance |
| `skip_enhancement_keywords` | list | `["hi", "hello", ...]` | Keywords to skip enhancement |
| `performance_tracking` | boolean | `true` | Track enhancement performance metrics |

### Configuration File

Edit `~/.kollabor-cli/config.json`:

```json
{
  "plugins": {
    "query_enhancer": {
      "enabled": true,
      "show_status": true,
      "fast_model": {
        "api_url": "http://localhost:1234",
        "model": "qwen3-0.6b",
        "temperature": 0.3,
        "timeout": 5
      },
      "enhancement_prompt": "You are a query enhancement specialist...",
      "max_length": 500,
      "min_query_length": 10,
      "skip_enhancement_keywords": ["hi", "hello", "thanks", "thank you", "ok", "okay", "yes", "no"],
      "performance_tracking": true
    }
  }
}
```

### Configuration Widgets

```python
{
  "title": "Query Enhancer Plugin",
  "widgets": [
    {"type": "checkbox", "label": "Show Status", "config_path": "plugins.query_enhancer.show_status"},
    {"type": "text_input", "label": "Fast Model API URL", "config_path": "plugins.query_enhancer.fast_model.api_url"},
    {"type": "text_input", "label": "Fast Model", "config_path": "plugins.query_enhancer.fast_model.model"},
    {"type": "slider", "label": "Fast Model Temperature", "config_path": "plugins.query_enhancer.fast_model.temperature", "min_value": 0.0, "max_value": 1.0, "step": 0.1},
    {"type": "slider", "label": "Fast Model Timeout", "config_path": "plugins.query_enhancer.fast_model.timeout", "min_value": 1, "max_value": 30, "step": 1},
    {"type": "slider", "label": "Max Query Length", "config_path": "plugins.query_enhancer.max_length", "min_value": 100, "max_value": 2000, "step": 50},
    {"type": "slider", "label": "Min Query Length", "config_path": "plugins.query_enhancer.min_query_length", "min_value": 1, "max_value": 50, "step": 1},
    {"type": "checkbox", "label": "Performance Tracking", "config_path": "plugins.query_enhancer.performance_tracking"}
  ]
}
```

## Architecture

### Plugin Structure

```python
class QueryEnhancerPlugin:
    - initialize(event_bus, config, **kwargs) -> None
    - shutdown() -> None
    - register_hooks() -> None
    - get_default_config() -> Dict[str, Any]
    - get_startup_info(config) -> List[str]
    - get_config_widgets() -> Dict[str, Any]
    - _enhance_query(query: str) -> Optional[str]
    - _call_fast_model(prompt: str) -> Optional[str]
    - _should_enhance(query: str) -> bool
    - _get_enhancement_prompt(query: str) -> str
```

### Data Flow

```
User Input
    ↓
USER_INPUT_PRE hook
    ↓
QueryEnhancerPlugin._on_user_input()
    ↓
Check if should enhance (length, keywords)
    ↓
If yes:
    - Build enhancement prompt
    - Call fast model API
    - Parse response
    - Return enhanced query
If no or error:
    - Return original query
    ↓
Enhanced query used for main LLM processing
```

### Event Integration

| Event Type | Description |
|------------|-------------|
| `USER_INPUT_PRE` | Pre-processes user query through fast model |

## Enhancement Prompt

### Default Prompt

```
You are a query enhancement specialist. Your job is to improve user queries to get better responses from AI assistants.

Take this user query and enhance it by:
1. Making it more specific and detailed
2. Adding relevant context
3. Clarifying any ambiguity
4. Keeping the original intent

Return ONLY the enhanced query, nothing else.

Original query: {query}

Enhanced query:
```

### Customization

You can customize the enhancement prompt in the configuration:

```json
{
  "plugins": {
    "query_enhancer": {
      "enhancement_prompt": "Your custom enhancement prompt with {query} placeholder"
    }
  }
}
```

## Usage Examples

### Basic Enhancement

**User input:**
```
add error handling to the auth function
```

**Enhanced query:**
```
Please add comprehensive error handling to the authentication function in auth.py. 
Include validation for:
- Missing or invalid credentials
- Network timeout errors
- Database connection failures
- Rate limiting scenarios

Also ensure proper error messages are returned to the user and errors are logged appropriately.
```

### Technical Query Enhancement

**User input:**
```
optimize this slow function
```

**Enhanced query:**
```
Please analyze and optimize the slow function in the codebase. 
Identify performance bottlenecks and suggest improvements such as:
- Algorithm optimization
- Caching strategies
- Database query optimization
- Memory usage reduction

Provide before/after code examples and explain the expected performance improvements.
```

### Skipping Simple Queries

**User input:**
```
thanks
```

**Result:**
- Query NOT enhanced (matches `skip_enhancement_keywords`)
- Original "thanks" passed through unchanged

## Status Display

When `show_status` is enabled, the plugin displays enhancement status:

```
[Enhanced] Query length: 23 → 187 chars (0.2s)
```

The agnoster segment shows:
- Green "Enhanced" when successful
- Yellow "Skipped" when not enhanced
- Red "Failed" when enhancement fails

## Performance Tracking

When enabled, the plugin tracks:

- **Total enhancements**: Number of queries enhanced
- **Total time**: Cumulative enhancement time
- **Average time**: Average enhancement duration
- **Success rate**: Percentage of successful enhancements
- **Average length increase**: Character count growth

Access via `/query_stats` (if implemented) or check logs.

## Error Handling

### Common Errors

| Error | Cause | Resolution |
|-------|-------|------------|
| Fast model unavailable | API endpoint unreachable | Check fast model is running |
| Timeout | Enhancement took too long | Increase timeout or use faster model |
| Response too long | Enhanced query exceeds max_length | Increase max_length or adjust prompt |
| Invalid response | Fast model returned malformed response | Check fast model logs |

### Graceful Degradation

On any error, the plugin:
1. Logs the error
2. Falls back to original query
3. Displays status indicator (if enabled)
4. Continues normal processing

## Best Practices

### When to Enable

Enable query enhancement when:
- Using smaller/dumber models (0.6B - 7B)
- Queries are often vague or brief
- You need detailed, specific responses
- You have a separate fast model available

### When to Disable

Disable query enhancement when:
- Using large/capable models (70B+)
- Queries are already detailed and specific
- Latency is critical (enhancement adds ~0.2-0.5s)
- No separate fast model available

### Fast Model Selection

Recommended fast models for enhancement:
- **qwen3-0.6b**: Very fast, good at expansion
- **phi-3-mini-3.8b**: Good balance of speed and quality
- **gemma-2-2b**: Fast, good at clarifying intent

Avoid using the same model for both enhancement and main response (no benefit).

## Implementation Checklist

### Core Functionality
- [x] Query enhancement via fast model
- [x] Pre-processing hook integration
- [x] Keyword filtering
- [x] Length control
- [x] Graceful degradation

### Configuration
- [x] Fast model configuration
- [x] Enhancement prompt customization
- [x] Length and keyword controls
- [x] Status display toggle
- [x] Performance tracking

### Testing
- [ ] Integration tests with various fast models
- [ ] Performance benchmarks
- [ ] Edge case testing (very short, very long queries)

## Related Documentation

- /docs/reference/hook-system-sdk.md - Hook system
- /docs/configuration/fast-models.md - Fast model setup guide
- /docs/performance/query-optimization.md - Query optimization strategies

## Advanced Features

### Multi-Stage Enhancement

Future enhancement: multiple enhancement passes for complex queries.

### Context-Aware Enhancement

Future enhancement: use conversation history to inform enhancement.

### Model Routing

Future enhancement: dynamically select enhancement model based on query complexity.

## Troubleshooting

### Enhancement Not Working

1. Check if plugin is enabled in config
2. Verify fast model API URL is accessible
3. Check logs for specific error messages
4. Verify query meets minimum length requirement
5. Check if query contains skip keywords

### Slow Responses

1. Check fast model timeout setting
2. Consider using a smaller/faster model
3. Disable enhancement if latency is critical
4. Check network latency to fast model

### Poor Quality Enhancements

1. Review and customize enhancement prompt
2. Adjust temperature (lower = more deterministic)
3. Try different fast model
4. Check that fast model is properly configured
