Logo

Configuration Guide

Configuration Guide

This guide explains how to update and manage configuration data in the Haya Routing Service. All configuration can be managed through JSON files and is automatically loaded into Qdrant for runtime use.

Overview

The Haya Routing Service uses several types of configuration:

  1. Hierarchy Data (data/hierarchy-data.json) - Service, category, and collection definitions
  2. Embedding Weights (config/optimized-embedding-weights-v3.json) - Field weight configurations
  3. Confidence Config (config/confidence-config.json) - Confidence calculation settings
  4. Boost/Penalty Config (config/boost-penalty-config.json) - Query intent and keyword boosts
  5. Query Intent Config (config/query-intent-config.json) - Intent detection settings
  6. Level Config (data/level-config.json) - Level-based field and behavior definitions

Hierarchy Data Configuration

Location

data/hierarchy-data.json

Structure

The hierarchy data file contains three main sections:

{
  "metadata": {
    "description": "...",
    "version": "2.0.0",
    "tenant": "tenant-001",
    "app": "app-001"
  },
  "services": [...],
  "categories": [...],
  "collections": [...]
}

Key Configuration Sections

1. Routing Keywords (Service Level)

Located in services[].level_context.routing_keywords:

{
  "routing_keywords": {
    "boost_keywords": [
      "search",
      "find",
      "documentation"
    ],
    "penalty_keywords": [
      "api",
      "sql",
      "database"
    ],
    "boost_value": 0.2,
    "penalty_value": -0.6
  }
}

Purpose: Controls keyword-based routing at the service level.

  • boost_keywords: Keywords that increase similarity when found in queries
  • penalty_keywords: Keywords that decrease similarity when found in queries
  • boost_value: Amount to add to similarity (0.0 to 1.0)
  • penalty_value: Amount to subtract from similarity (negative value)

Best Practices:

  • Use specific phrases for better matching (e.g., "list all", "show network")
  • Set higher boost values (0.5-0.6) for services that need stronger routing
  • Set stronger penalties (-0.4 to -0.6) to prevent false matches
  • Add SQL/REST-specific terms to Document Search penalty keywords

2. Query Intent Boosts (Service Level)

Located in services[].level_context.query_intent_boosts:

{
  "query_intent_boosts": {
    "documentation": 0.25,
    "data_query": -0.25,
    "api_call": 0.35
  }
}

Purpose: Applies boosts/penalties based on detected query intent.

Intent Types:

  • documentation: User wants documentation/search results
  • data_query: User wants to query data/databases
  • api_call: User wants to call APIs
  • mcp_config: User wants MCP/model configuration

Best Practices:

  • Use values between 0.25-0.35 for stronger intent-based routing
  • Negative values penalize mismatched intents

3. Embedding Configuration

Located in services[].embedding_config and collections[].embedding_config:

{
  "embedding_config": {
    "weight_strategy": "context_heavy"  // or "balanced"
  }
}

For collections:

{
  "embedding_config": {
    "embedding_weights": {
      "description_weight": 0.4,
      "document_types_weight": 0.3,
      "content_characteristics_weight": 0.3
    }
  }
}

Purpose: Controls how embeddings are generated for semantic matching.

Weight Strategies:

  • context_heavy: Emphasizes context fields (use_cases, domain_context)
  • balanced: Equal weight across all fields

Updating Hierarchy Data

  1. Edit the JSON file:

    vim data/hierarchy-data.json

  2. Validate JSON syntax:

    python3 -m json.tool data/hierarchy-data.json > /dev/null

  3. Register the updated data:

    ./fresh-register.sh

    Or use the API:

    curl -X POST "http://localhost:3000/api/v1/admin/hierarchy/bulk-register" \
  -H "Content-Type: application/json" \
  -d @data/hierarchy-data.json

Common Updates

Adding a New Service

  1. Add service object to services array
  2. Set level: 0, root_type, and level_context.routing_keywords
  3. Register using ./fresh-register.sh

Updating Keyword Boosts

  1. Edit routing_keywords in service's level_context
  2. Adjust boost_value and penalty_value
  3. Add/remove keywords from boost_keywords and penalty_keywords
  4. Re-register hierarchy data

Tuning Routing Accuracy

  1. Increase boost values (0.3 → 0.5-0.6) for services that need stronger routing
  2. Increase penalty values (-0.2 → -0.4 to -0.6) to prevent false matches
  3. Add phrase keywords (e.g., "list all", "show network") for better matching
  4. Add SQL/REST terms to Document Search penalties to prevent cross-service matches

Embedding Weights Configuration

Location

config/optimized-embedding-weights-v3.json

Structure

{
  "level_0": {
    "name_weight": 0.03,
    "description_weight": 0.10,
    "use_cases_weight": 0.28,
    "capabilities_weight": 0.18,
    "domain_context_weight": 0.20,
    ...
  },
  "level_1": { ... },
  "level_2": { ... }
}

Purpose

Controls the relative importance of each field when generating embeddings. Higher weights mean the field has more influence on semantic matching.

Updating Embedding Weights

  1. Edit the JSON file:

    vim config/optimized-embedding-weights-v3.json

  2. Bootstrap to Qdrant:

    npm run bootstrap-configs

    This loads all config files from config/ into Qdrant.

  3. Verify:

    curl "http://localhost:3000/api/v1/admin/config/embedding-weights?tenant_id=tenant-001&app_id=app-001"

Best Practices

  • Use Cases should have highest weight (0.25-0.30) - they describe what the service does
  • Domain Context should have high weight (0.20-0.25) - provides domain-specific context
  • Description should have moderate weight (0.10-0.15) - general description
  • Name should have low weight (0.03-0.05) - least important for matching

Confidence Configuration

Location

config/confidence-config.json

Structure

{
  "confidence_calculation": {
    "high_confidence_threshold": 0.7,
    "clear_gap_threshold": 0.15,
    "clear_winner_bonus": 0.1
  }
}

Purpose

Controls how confidence scores are calculated from similarity scores.

  • high_confidence_threshold: Minimum similarity for high confidence (0.7 = 70%)
  • clear_gap_threshold: Minimum gap between top match and second match to apply bonus (0.15 = 15%)
  • clear_winner_bonus: Bonus added when there's a clear winner (0.1 = 10%)

Updating Confidence Config

  1. Edit the JSON file:

    vim config/confidence-config.json

  2. Bootstrap to Qdrant:

    npm run bootstrap-configs

  3. Restart service (configs are cached):

    docker-compose restart haya-routing

Tuning Confidence

  • Lower threshold (0.6-0.65): More routes accepted, but may include lower-quality matches
  • Higher threshold (0.75-0.8): Only high-quality routes accepted, may reject valid routes
  • Larger gap threshold (0.2-0.25): More strict about "clear winner" bonus
  • Smaller gap threshold (0.1-0.12): More lenient about "clear winner" bonus

Boost/Penalty Configuration

Location

config/boost-penalty-config.json

Structure

{
  "service_type_boosts": {
    "service_level": {
      "documentation": {
        "SEARCH": 0.25,
        "SQL": -0.25
      },
      "data_query": {
        "SQL": 0.25,
        "SEARCH": -0.25
      }
    }
  },
  "similarity_boosts": {
    "service_type_hint": 0.25,
    "context_match": {
      "threshold": 0.7,
      "multiplier": 0.2
    }
  }
}

Purpose

Provides global boost/penalty settings that apply across all services. These are used as fallbacks when service-specific settings aren't available.

Updating Boost/Penalty Config

  1. Edit the JSON file:

    vim config/boost-penalty-config.json

  2. Bootstrap to Qdrant:

    npm run bootstrap-configs

  3. Restart service:

    docker-compose restart haya-routing

Query Intent Configuration

Location

config/query-intent-config.json

Structure

{
  "intent_patterns": {
    "documentation": {
      "keywords": ["how", "what", "show", "find"],
      "patterns": ["how to", "how do", "what is"]
    },
    "data_query": {
      "keywords": ["list", "count", "show", "get"],
      "patterns": ["list all", "show me", "get data"]
    }
  }
}

Purpose

Defines patterns and keywords for detecting query intent.

Updating Query Intent Config

  1. Edit the JSON file
  2. Bootstrap to Qdrant: npm run bootstrap-configs
  3. Restart service

Level Configuration

Location

data/level-config.json

Structure

{
  "0": {
    "fields": ["root_type", "level_context"],
    "parentLevels": null,
    "embedding_method": "service",
    "matching_strategy": "service-level"
  },
  "1": {
    "fields": ["level_context"],
    "parentLevels": [0],
    "embedding_method": "category",
    "matching_strategy": "category-level"
  },
  "2": {
    "fields": ["level_context", "routing_info"],
    "parentLevels": [0, 1],
    "embedding_method": "collection",
    "matching_strategy": "collection-level"
  }
}

Purpose

Defines which fields are available at each hierarchy level and how matching works.

Updating Level Config

  1. Edit the JSON file:

    vim data/level-config.json

  2. Bootstrap to Qdrant:

    npm run bootstrap-level-config

  3. Restart service

Configuration Workflow

Initial Setup

  1. Bootstrap all configs:

    npm run bootstrap-configs
npm run bootstrap-level-config

  2. Register hierarchy data:

    ./fresh-register.sh

Updating Configuration

  1. Edit JSON files in config/ or data/
  2. Validate JSON syntax: 
    python3 -m json.tool <file> > /dev/null
  3. Bootstrap configs (if config files changed): 
    npm run bootstrap-configs
  4. Re-register hierarchy (if hierarchy-data.json changed): 
    ./fresh-register.sh
  5. Restart service (if configs changed): 
    docker-compose restart haya-routing

Verifying Configuration

Check configs in Qdrant:

# Check embedding weights
curl "http://localhost:3000/api/v1/admin/config/embedding-weights?tenant_id=tenant-001&app_id=app-001"

# Check confidence config
curl "http://localhost:3000/api/v1/admin/config/confidence?tenant_id=tenant-001&app_id=app-001"

# Check level config
curl "http://localhost:3000/api/v1/admin/config/level-config?tenant_id=tenant-001&app_id=app-001"

Best Practices

Hierarchy Data

  1. Use specific keywords: Prefer phrases like "list all" over single words
  2. Balance boosts/penalties: Higher boosts (0.5-0.6) for services that need stronger routing
  3. Strong penalties: Use -0.4 to -0.6 penalties to prevent false matches
  4. Add SQL/REST terms to Document Search penalties: Prevents cross-service matches
  5. Test after changes: Always run tests after updating hierarchy data

Embedding Weights

  1. Prioritize use cases: Give highest weight to use_cases (0.25-0.30)
  2. Emphasize domain context: High weight for domain_context (0.20-0.25)
  3. Keep name weight low: Name should have minimal weight (0.03-0.05)

Confidence

  1. Start with defaults: Use 0.7 threshold, 0.15 gap, 0.1 bonus
  2. Adjust based on results: Lower threshold if too many rejections, raise if too many false positives
  3. Monitor test results: Use test suite to validate confidence settings

Troubleshooting

Config Not Loading

  1. Check JSON syntax: python3 -m json.tool <file>
  2. Verify bootstrap ran: Check logs for "Config loaded from Qdrant"
  3. Restart service: Configs are cached on startup

Changes Not Taking Effect

  1. Hierarchy data: Must re-register after changes
  2. Config files: Must bootstrap and restart service
  3. Check cache: Service caches configs on startup

Validation Errors

  1. Check required fields are present
  2. Verify field types match expected types
  3. Check level constraints (e.g., level 0 must have root_type)

© 2025 All rights reservedBuilt with DataHub Cloud

Built with LogoDataHub Cloud