The KeywordIntentDetector uses a multi-layered approach to detect domain and intent from natural language input. Each layer acts as a fallback mechanism, ensuring robust detection even when some methods fail or dependencies are missing.
The detection process follows this exact order:
_normalize_text_lower)Always active - No dependencies
def _normalize_text_lower(self, text_lower: str) -> str:
Steps:
ł → l, ą → a, etc.)doker → docker, dokcer → docker)startuj → uruchom)Fallback behavior: Always works, gracefully handles missing spaCy
_detect_fast_path)Always active - No dependencies
def _detect_fast_path(self, text_lower: str) -> Optional[DetectionResult]:
Purpose: Quick detection of browser and search queries Patterns:
przeglądark, browser, otwórz stronę, open urlszukaj w google, wyszukaj w google, search webFallback behavior: Returns None if no match, continues to next step
_compute_sql_context)Always active - No dependencies
def _compute_sql_context(self, text_lower: str) -> tuple[bool, bool]:
Purpose: Determine if text contains SQL keywords
Returns: (sql_context, sql_explicit)
Fallback behavior: Always works, returns (False, False) if no SQL context
_detect_sql_drop_table)Conditional - Requires SQL context
def _detect_sql_drop_table(self, text_lower: str, *, sql_context: bool, sql_explicit: bool) -> Optional[DetectionResult]:
Purpose: High-priority detection of dangerous SQL DROP operations
Activation: Only runs if sql_context is True
Fallback behavior: Returns None if no DROP pattern, continues to next step
_detect_explicit_docker)Always active - No dependencies
def _detect_explicit_docker(self, text_lower: str) -> Optional[DetectionResult]:
Purpose: High-priority detection of Docker commands
Patterns: docker run, docker stop, docker-compose, etc.
Fallback behavior: Returns None if no Docker pattern, continues to next step
_detect_explicit_kubernetes)Always active - No dependencies
def _detect_explicit_kubernetes(self, text_lower: str) -> Optional[DetectionResult]:
Purpose: High-priority detection of Kubernetes commands
Patterns: kubectl, k8s, pod, deployment, etc.
Fallback behavior: Returns None if no K8s pattern, continues to next step
_detect_explicit_service_restart)Always active - No dependencies
def _detect_explicit_service_restart(self, text_lower: str) -> Optional[DetectionResult]:
Purpose: High-priority detection of service restart commands
Patterns: restartuj usługę, systemctl restart, etc.
Fallback behavior: Returns None if no restart pattern, continues to next step
_detect_best_from_priority_intents)Always active - No dependencies
def _detect_best_from_priority_intents(self, text_lower: str, *, sql_context: bool, sql_explicit: bool) -> Optional[DetectionResult]:
Purpose: Check high-priority intents first (configured in keyword_intent_detector_config.json)
Priority Order (Shell): service_start, service_restart, service_stop, service_status, then others
Fallback behavior: Returns None if no priority intent matches, continues to next step
_detect_best_from_patterns)Always active - No dependencies
def _detect_best_from_patterns(self, text_lower: str, *, sql_context: bool, sql_explicit: bool) -> Optional[DetectionResult]:
Purpose: General keyword matching across all domains and intents Process:
_match_keywordFallback behavior: Returns None if no pattern matches confidence threshold, continues to next step
_detect_best_from_fuzzy)Conditional - Requires rapidfuzz library
def _detect_best_from_fuzzy(self, text_lower: str) -> Optional[DetectionResult]:
Purpose: Handle typos and variations using fuzzy string matching
Activation: Only runs if rapidfuzz is installed
Threshold: 85% similarity minimum
Fallback behavior: Returns None if rapidfuzz not installed or no good matches, continues to next step
unknown intent)Always active - No dependencies
return DetectionResult(
domain='unknown',
intent='unknown',
confidence=0.0,
matched_keyword=None,
)
Purpose: Guaranteed return value when all detection methods fail
| Method | Dependencies | Always Works? | Fallback |
|---|---|---|---|
| Text Normalization | None (optional spaCy) | ✅ Yes | Regex-only normalization |
| Fast Path Detection | None | ✅ Yes | Returns None |
| SQL Context Detection | None | ✅ Yes | Returns (False, False) |
| SQL DROP Detection | SQL context only | ✅ Yes | Returns None |
| Docker Detection | None | ✅ Yes | Returns None |
| Kubernetes Detection | None | ✅ Yes | Returns None |
| Service Restart Detection | None | ✅ Yes | Returns None |
| Priority Intents | None | ✅ Yes | Returns None |
| Pattern Matching | None | ✅ Yes | Returns None |
| Fuzzy Matching | rapidfuzz library |
❌ No | Skipped if missing |
| Final Fallback | None | ✅ Yes | Always returns result |
Input: "restartuj usługę nginx"
1. Text normalization: Uses regex only (no lemmatization)
2. Fast path: No match
3. SQL context: No SQL keywords
4. Pattern matching: Finds "restartuj usługę" → service_restart
Result: ✅ Works correctly
Input: "dokcer ps" (typo)
1. Text normalization: "dokcer" → "docker"
2. Pattern matching: "docker ps" → docker/list
Result: ✅ Works correctly (fuzzy not needed)
Input: "unknown command xyz"
1. All detection methods return None
2. Final fallback: unknown/unknown
Result: ✅ Always returns something
Input: "ps" (no docker keyword)
1. Domain scan for Docker: Requires booster → fails
2. Shell pattern matching: "ps" → list_processes
Result: ✅ Falls back to shell
keyword_intent_detector_config.json){
"priority_intents": {
"shell": ["service_start", "service_restart", "service_stop", "service_status", ...]
}
}
{
"domain_boosters": {
"docker": ["docker", "doker", "dokcer", "kontener", ...],
"shell": ["plik", "file", "katalog", "directory", ...]
}
}
{
"fast_path": {
"browser_keywords": ["przeglądark", "browser", ...],
"search_keywords": ["szukaj w google", "search web", ...]
}
}
NoneThe system is tested with:
All tests pass regardless of optional dependencies being available.