phentrieve.yaml.template

# Phentrieve Configuration Template
# Copy this file to your home directory at ~/.phentrieve/phentrieve.yaml
# or to the project root directory to customize settings

# =============================================================================
# DATA PATH CONFIGURATION
# =============================================================================
# These can be overridden via command-line arguments when applicable

# Main data directory for HPO files, terms, and graph data
data_dir: "~/phentrieve_data"

# Directory for ChromaDB vector indexes
index_dir: "~/phentrieve_data/indexes"

# Directory for benchmark results
results_dir: "~/phentrieve_data/results"

# =============================================================================
# HARDWARE & PERFORMANCE
# =============================================================================

# device: "auto"  # Options: "auto", "cuda", "cpu", or specific device like "cuda:0"
# use_fp16: false  # Use half-precision floating point for better performance when available

# =============================================================================
# EMBEDDING MODELS
# =============================================================================

# Default embedding model for retrieval
# default_model: "FremyCompany/BioLORD-2023-M"

# =============================================================================
# RETRIEVAL SETTINGS
# =============================================================================

# Minimum similarity score to display results (0.0-1.0)
# min_similarity_threshold: 0.3

# Default number of results to return
# default_top_k: 10

# Similarity calculation method
# Options: "hybrid", "cosine", "dot_product"
# similarity_formula: "hybrid"

# =============================================================================
# TEXT PROCESSING
# =============================================================================

# Default language for text processing
# default_language: "en"

# =============================================================================
# BENCHMARK SETTINGS
# =============================================================================

# benchmark:
#   # Similarity threshold for benchmark evaluation
#   similarity_threshold: 0.1
#
#   # K values for hit rate calculation (Recall@K, Precision@K)
#   k_values: [1, 3, 5, 10]
#
#   # Output settings
#   save_summaries: true
#   save_detailed_results: true
#   create_visualizations: true
#
#   # Models to benchmark (evaluated in order)
#   models:
#     - "FremyCompany/BioLORD-2023-M"
#     - "jinaai/jina-embeddings-v2-base-de"
#     - "T-Systems-onsite/cross-en-de-roberta-sentence-transformer"
#     - "sentence-transformers/paraphrase-multilingual-mpnet-base-v2"
#     - "sentence-transformers/distiluse-base-multilingual-cased-v2"
#     - "BAAI/bge-m3"
#     - "Alibaba-NLP/gte-multilingual-base"
#     - "sentence-transformers/LaBSE"
#     - "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"

# =============================================================================
# HPO DATA CONFIGURATION
# =============================================================================

# hpo_data:
#   # HPO ontology version to download
#   version: "v2025-03-03"
#
#   # Base URL for HPO releases on GitHub
#   base_url: "https://github.com/obophenotype/human-phenotype-ontology/releases/download"
#
#   # Download timeout in seconds
#   download_timeout: 60
#
#   # Chunk size for streaming downloads (in bytes)
#   chunk_size: 8192

# =============================================================================
# MULTI-VECTOR EMBEDDING SETTINGS (Issue #136)
# =============================================================================
# Multi-vector indexing creates separate embeddings for each HPO term component
# (label, synonyms, definition) enabling fine-grained retrieval.
# Multi-vector provides ~10% improvement in MRR (0.823 → 0.922 for BioLORD).

multi_vector:
  # Whether to use multi-vector indexes by default (recommended: true)
  # Multi-vector provides better retrieval quality at the cost of larger indexes
  enabled: true

  # Aggregation strategy for combining component scores
  # Options: label_only, label_synonyms_min, label_synonyms_max,
  #          all_weighted, all_max, all_min, custom
  aggregation_strategy: "label_synonyms_max"

  # Component weights (used when aggregation_strategy is "all_weighted")
  # Weights should sum to 1.0 for normalized scores
  # component_weights:
  #   label: 0.5
  #   synonyms: 0.3
  #   definition: 0.2

  # Custom formula (used when aggregation_strategy is "custom")
  # Available functions: min(), max(), avg()
  # Available variables: label, synonyms (list), definition
  # Example: "0.5 * max(label, max(synonyms)) + 0.5 * definition"
  # custom_formula: null

# =============================================================================
# CONFIGURATION PROFILES
# =============================================================================
# Named profiles for common CLI workflows. Pass --profile NAME to apply.
# See docs/user-guide/configuration-profiles.md for the full schema.

# profiles:
#   high_recall_german:
#     description: "Recall-oriented German extraction"
#     command: text process              # bind to a specific command (optional)
#     language: de
#     chunk_retrieval_threshold: 0.6
#
#   fast_query:
#     command: query
#     num_results: 5
#     similarity_threshold: 0.5

# =============================================================================
# HPO EXTRACTION THRESHOLDS
# =============================================================================
# Read by phentrieve/config.py to populate DEFAULT_CHUNK_RETRIEVAL_THRESHOLD,
# DEFAULT_MIN_CONFIDENCE_AGGREGATED, DEFAULT_CHUNK_CONFIDENCE, and
# DEFAULT_ASSERTION_PREFERENCE. Key names match the existing config.py reads
# exactly - DO NOT rename.

# extraction:
#   chunk_threshold: 0.7
#   min_confidence: 0.75
#   chunk_confidence: 0.2
#   assertion_preference: dependency
#
#   # Adaptive re-chunking (opt-in). When a chunk's retrieval is poor,
#   # subdivide it into sentence-bounded sub-chunks and re-query.
#   # See docs/user-guide/adaptive-rechunking.md for full details.
#   adaptive_rechunking:
#     enabled: false                 # opt-in switch; default behavior unchanged
#     quality_threshold: 0.55        # top-1 floor; encoder-calibrated for BioLORD
#     margin_threshold: 0.03         # minimum top-1 minus top-2 distance
#     use_ontology_coherence: false  # reserved, inert in v1
#     max_depth: 2                   # recursion cap; 1 + max_depth query_batch calls worst case
#     min_chunk_chars: 30            # drop sub-chunks shorter than this many chars
#     max_sentences_per_subchunk: 3  # sliding-window size in sentences
#     overlap_sentences: 1           # sentence-level overlap between sub-chunk windows
#     score_improvement_gate: 0.05   # children below this top-1 lift over parent are reverted

# =============================================================================
# OUTPUT FORMAT DEFAULTS
# =============================================================================
# Read by phentrieve/config.py to populate DEFAULT_OUTPUT_FORMAT_QUERY and
# DEFAULT_OUTPUT_FORMAT_PROCESS.

# output:
#   format_query: text
#   format_process: json_lines

# =============================================================================
# EXTRACTION BENCHMARK CONFIGURATION
# =============================================================================

extraction_benchmark:
  averaging_strategy: micro  # micro, macro, weighted
  enable_assertions: true
  enable_relaxed_matching: false
  bootstrap_samples: 1000
  confidence_level: 0.95