Query Enhancement

CIAK includes a built-in query enhancement engine that automatically improves your search queries before they reach the search backend. This helps you find more relevant results even when your query doesn't exactly match the code's terminology.

What It Does

When you search for code, the enhancer applies several transformations:

• Synonym expansion — "function" also searches for method, procedure, handler
• Acronym resolution — "jwt" expands to include token, authentication
• Technical jargon — "async" also matches asynchronous, concurrent, nonblocking
• Language-specific terms — "fn" in a Rust context also matches function
• Intent classification — detects whether you're looking for an implementation, debugging, exploring structure, etc.
• Stop word filtering — ignores filler words like the, a, in during expansion

Example

A query like "find async function handler" might be expanded to:

find async function handler method procedure asynchronous concurrent

This expanded query is then used internally for search, giving you broader recall without losing precision.

Supported Tools

Query enhancement is available in these MCP tools:

Tool	Enhanced by default
search_code	✅
analyze_symbols	✅
vector_search	✅
optimize_context	✅

The get_related_context, analyze_relationships, and search_knowledge tools are not enhanced because they take exact targets (file paths, symbol names) rather than free-text queries.

Controlling Enhancement

Every search tool accepts an enhance_query parameter:

{
  "query": "AuthService",
  "project_path": "/home/user/my-project",
  "enhance_query": false
}

Value	Behavior
true (default)	Query is expanded with synonyms, acronyms, and language-specific terms
false	Query is passed through as-is — useful for exact symbol name lookups

When to Disable Enhancement

Disable query enhancement (enhance_query: false) when:

• You're searching for an exact symbol name (e.g., "AuthService", "handleRequest")
• You want precise, narrow results without related terms
• The expansion is adding noise to your results (rare, but possible for very specific queries)

When to Keep It Enabled

Keep enhancement enabled (the default) when:

• You're describing what you're looking for in natural language (e.g., "function that validates JWT tokens")
• You're not sure of the exact naming used in the codebase
• You want to find code across different languages that use different terminology for the same concept

Customizing the Mappings

All synonym, acronym, jargon, and intent data is loaded from a TOML configuration file. CIAK ships with sensible defaults, but you can override them per-project.

Creating a Custom Config

Place a file at .ciak/query_enhancer.toml in your project root:

# .ciak/query_enhancer.toml

[settings]
max_synonyms_per_term = 3
min_expansion_confidence = 0.7
enable_language_expansions = true
enable_jargon_expansions = true
max_total_expansions = 10

[synonyms]
# Add your own domain-specific synonyms
# Format: term = [["synonym", confidence], ...]
user = [["account", 0.8], ["profile", 0.7]]
payment = [["transaction", 0.9], ["charge", 0.8], ["billing", 0.7]]

[acronyms]
# Add project-specific acronyms
rbac = [["role", 0.9], ["access control", 0.8]]
sso = [["single sign-on", 0.9], ["authentication", 0.8]]

[jargon]
# Technical abbreviations used in your project
svc = [["service", 0.9]]
repo = [["repository", 0.9], ["codebase", 0.7]]

When a custom config exists, it replaces the default mappings entirely. If you only want to add a few terms, copy the relevant sections from the default config and add your entries.

Configuration Reference

[settings]

Key	Type	Default	Description
max_synonyms_per_term	integer	3	Maximum synonym expansions per query term
min_expansion_confidence	float	0.7	Minimum confidence score to include an expansion (0.0–1.0)
enable_language_expansions	boolean	true	Enable language-specific term mapping
enable_jargon_expansions	boolean	true	Enable technical jargon expansion
max_total_expansions	integer	10	Maximum total expansion terms added to a query

[synonyms]

Maps terms to synonyms with confidence scores. Higher confidence means the synonym is more likely to be relevant.

[synonyms]
function = [["method", 0.9], ["procedure", 0.8], ["handler", 0.7]]

[acronyms]

Maps acronyms to their expanded meanings.

[acronyms]
jwt = [["token", 0.9], ["authentication", 0.8]]

[jargon]

Maps informal/abbreviated terms to formal equivalents.

[jargon]
async = [["asynchronous", 0.9], ["concurrent", 0.7]]

[languages.<name>]

Language-specific term mappings. Only applied when the language is detected or specified.

[languages.rust]
expansions = [
    ["fn", "function", 0.9],
    ["struct", "type", 0.8],
    ["trait", "interface", 0.8],
]

[languages.python]
expansions = [
    ["def", "function", 0.9],
    ["dict", "dictionary", 0.9],
]

[stop_words]

Words to ignore during expansion (they remain in the query itself).

[stop_words]
words = ["the", "a", "an", "and", "or", "for", "in", "on", "at", "to"]

[intent.phrases] and [intent.keywords]

Configure intent classification patterns. The engine uses these to detect whether a query is about finding implementations, debugging, exploring structure, etc.

[intent.phrases]
patterns = [
    ["find implementation", "find_implementation", 1.2],
    ["fix error", "debug", 1.2],
    ["how to use", "find_usage", 1.2],
]

[intent.keywords]
find = [["find_implementation", 0.7]]
error = [["debug", 0.9]]

Available intents: find_implementation, find_usage, understand_concept, debug, explore_structure, find_documentation, general_search.

[language_detection]

Keywords used to auto-detect the programming language from query text.

[language_detection]
rust = ["fn ", "impl ", "struct ", "trait ", "crate ", ".rs"]
typescript = ["interface ", "type ", "angular", ".ts"]
python = ["def ", "class ", "import ", "django", ".py"]

How It Works Internally

1. The query is normalized (whitespace cleanup)
2. Programming language is detected from query text or the language parameter
3. Each non-stop-word is looked up in synonym, acronym, and jargon maps
4. Language-specific expansions are applied if a language is detected
5. Intent is classified from phrase patterns and keyword weights
6. Expansions are sorted by confidence and truncated to max_total_expansions
7. Unique expansion terms are appended to the original query
8. The expanded query is passed to the search backend

The original query is always preserved — expansions only add terms, never remove them.