.tenets.example.yml

# .tenets.example.yml - Complete Tenets Configuration Example
# Copy this to .tenets.yml and customize for your project
# https://github.com/jddunn/tenets

# ============================================================================
# API KEYS (OPTIONAL - Currently only used for LLM summarization)
# ============================================================================
# WARNING: Add .tenets.yml to .gitignore if you put API keys here!
#
# Priority order: Environment variables override these config values
# So you can commit a config without keys and use env vars in production

# OpenAI API key for GPT models
# OPENAI_API_KEY: ""

# Anthropic API key for Claude models
# ANTHROPIC_API_KEY: ""

# OpenRouter API key for multiple models
# OPENROUTER_API_KEY: ""

# ============================================================================
# GLOBAL SETTINGS
# ============================================================================

# Maximum tokens for context generation (affects LLM costs)
max_tokens: 100000 # Range: 1000-2000000

# Debug mode - enables verbose logging
debug: false

# Quiet mode - suppresses non-essential output
quiet: false

# ============================================================================
# NLP (NATURAL LANGUAGE PROCESSING) - Centralized text processing
# ============================================================================
# All NLP operations go through the centralized tenets.core.nlp package

nlp:
  # Enable NLP features globally
  enabled: true

  # ---- STOPWORD CONFIGURATION ----
  # Dual stopword system for different contexts
  stopwords_enabled: true

  # Stopword set for code search (ultra-minimal, ~25 words)
  # Preserves ALL programming keywords like async, function, class, etc.
  code_stopword_set: minimal # minimal|aggressive|custom

  # Stopword set for prompt parsing (aggressive, 200+ words)
  # Filters common words to extract core concepts
  prompt_stopword_set: aggressive # minimal|aggressive|custom

  # Additional custom stopword files
  custom_stopword_files: []

  # ---- TOKENIZATION CONFIGURATION ----
  # How text is broken into tokens
  tokenization_mode: auto # code|text|auto

  # Keep original tokens alongside split versions for exact matching
  preserve_original_tokens: true

  # Split camelCase and PascalCase (getUserName → get, user, name)
  split_camelcase: true

  # Split snake_case (user_name → user, name)
  split_snakecase: true

  # Minimum token length to keep
  min_token_length: 2

  # ---- KEYWORD EXTRACTION ----
  # How keywords are extracted from text
  keyword_extraction_method: auto # auto|rake|yake|bm25|tfidf|frequency

  # Maximum keywords to extract
  max_keywords: 30

  # Maximum n-gram size (for phrases like "machine learning")
  ngram_size: 3

  # YAKE deduplication threshold (if YAKE is available)
  yake_dedup_threshold: 0.7

  # ---- TF-IDF CONFIGURATION ----
  # Optional alternative to BM25 (when explicitly configured)
  tfidf_use_sublinear: true # Use log scaling for term frequency
  tfidf_use_idf: true # Use inverse document frequency
  tfidf_norm: l2 # Normalization method

  # ---- BM25 CONFIGURATION ----
  # Best Matching 25 algorithm settings
  bm25_k1: 1.2 # Term frequency saturation
  bm25_b: 0.75 # Length normalization

  # ---- EMBEDDINGS CONFIGURATION (ML) ----
  # Semantic embeddings for similarity computation
  embeddings_enabled: false # Requires sentence-transformers

  # Embedding model to use
  # Options: all-MiniLM-L6-v2, all-MiniLM-L12-v2, all-mpnet-base-v2
  embeddings_model: all-MiniLM-L6-v2

  # Device for embeddings
  embeddings_device: auto # auto|cpu|cuda

  # Cache computed embeddings
  embeddings_cache: true

  # Batch size for embedding generation
  embeddings_batch_size: 32

  # ---- SIMILARITY CONFIGURATION ----
  # How similarity is computed
  similarity_metric: cosine # cosine|euclidean|manhattan
  similarity_threshold: 0.7 # Minimum similarity to consider relevant

  # ---- NLP CACHE CONFIGURATION ----
  # Cache TTL for NLP operations
  cache_embeddings_ttl_days: 30
  cache_bm25_ttl_days: 7 # BM25 cache TTL
  cache_tfidf_ttl_days: 7 # TF-IDF cache TTL (when used)
  cache_keywords_ttl_days: 7

  # ---- PERFORMANCE OPTIMIZATION ----
  # Multiprocessing for large operations
  multiprocessing_enabled: true
  multiprocessing_workers: null # null = cpu_count()
  multiprocessing_chunk_size: 100

# ============================================================================
# FILE RANKING - How files are scored for relevance
# ============================================================================

ranking:
  # Algorithm for ranking files by relevance
  # Options: fast, balanced, thorough, ml, custom
  algorithm: balanced

  # Minimum relevance score to include file (0.0-1.0)
  # Lower values include more files
  threshold: 0.10

  # Text similarity algorithm for ranking
  # BM25 is the default and recommended for code search
  text_similarity_algorithm: bm25 # bm25 (default) | tfidf (optional)
  use_tfidf: false # Deprecated - use text_similarity_algorithm instead

  # Filter common programming keywords (reduces noise)
  # This now uses the centralized NLP stopword system
  use_stopwords: false # For code search, use minimal stopwords

  # Use semantic embeddings for similarity (requires ML)
  # This now uses the centralized NLP embeddings
  use_embeddings: false

  # Include git signals in ranking
  use_git: true

  # Enable ML features (uses NLP embeddings)
  use_ml: false

  # Embedding model for ML mode (uses NLP config)
  embedding_model: all-MiniLM-L6-v2

  # Custom weights for ranking factors (advanced)
  custom_weights:
    keyword_match: 0.25 # Uses NLP keyword extraction
    path_relevance: 0.20
    import_graph: 0.20
    git_activity: 0.15
    file_type: 0.10
    complexity: 0.10

  # Parallel processing settings
  workers: 2
  parallel_mode: auto # thread, process, or auto
  batch_size: 100 # Batch size for ML operations

# ============================================================================
# CONTENT SUMMARIZATION - Compress large files to fit token limits
# ============================================================================

summarizer:
  # Default summarization strategy
  # Options: extractive, compressive, textrank, transformer, llm, auto
  default_mode: auto

  # Target compression ratio (0.3 = compress to 30% of original)
  target_ratio: 0.3

  # Cache summaries for repeated content
  enable_cache: true
  max_cache_size: 100

  # Preserve code structure (imports, function signatures)
  preserve_code_structure: true

  # ---- DOCSTRING WEIGHT CONFIGURATION ----
  # Control how much emphasis to place on docstrings when summarizing code
  # This affects whether docstrings are included in summaries and how much space they take

  # Weight for including docstrings in code summaries
  # Values: 0.0 to 1.0
  #   0.0 = Never include docstrings (maximum compression, focuses on code structure only)
  #   0.3 = Include only critical docstrings (high compression, minimal documentation)
  #   0.5 = Default - Include important docstrings (balanced approach)
  #   0.7 = Prefer including docstrings (less compression, more documentation context)
  #   1.0 = Always include all docstrings (maximum documentation preservation)
  #
  # Use cases:
  # - Implementation/refactoring tasks: Use 0.0-0.3 to focus on code structure
  # - API review/understanding: Use 0.7-1.0 to see interfaces and contracts
  # - General analysis: Use 0.5 for balanced view (default)
  #
  # CLI override: tenets distill "task" --docstring-weight 0.8
  docstring_weight: 0.5

  # Include all class and function signatures, not just top N
  # When true: Shows ALL classes/functions found (comprehensive structure view)
  # When false: Shows only top classes/functions (more compressed output)
  include_all_signatures: true

  # LLM Configuration (optional - requires API keys above)
  # llm_provider: ""  # openai, anthropic, openrouter
  # llm_model: ""     # gpt-3.5-turbo, gpt-4, claude-3-haiku, etc.
  # llm_temperature: 0.3  # 0-1, lower = more deterministic
  # llm_max_tokens: 500   # Max tokens in response

  # ML Configuration
  enable_ml_strategies: true # Enable transformer models (requires ML)
  quality_threshold: medium # Quality target: low, medium, high
  batch_size: 10 # Files to process in parallel

# ============================================================================
# FILE SCANNING - Control which files are analyzed
# ============================================================================

scanner:
  # Respect .gitignore patterns
  respect_gitignore: true

  # Follow symbolic links
  follow_symlinks: false

  # Maximum file size to analyze (bytes)
  max_file_size: 5000000 # 5MB

  # Maximum total files to scan
  max_files: 10000

  # Check for and skip binary files
  binary_check: true

  # File encoding
  encoding: utf-8

  # Additional patterns to ignore (glob patterns)
  additional_ignore_patterns:
    - '*.generated.*'
    - '*.min.js'
    - '*.min.css'
    - vendor/
    - node_modules/
    - .venv/
    - '*.log'
    - '*.tmp'

  # Patterns to explicitly include (overrides ignores)
  additional_include_patterns: []

  # Parallel scanning settings
  workers: 4
  parallel_mode: auto
  timeout: 5.0 # Per-file timeout in seconds

# ============================================================================
# OUTPUT FORMATTING - How context is formatted
# ============================================================================

output:
  # Default output format
  # Options: markdown, xml (for Claude), json
  default_format: markdown

  # Enable syntax highlighting in output
  syntax_highlighting: true

  # Include line numbers in code blocks
  line_numbers: false

  # Maximum line length before wrapping
  max_line_length: 120

  # Include metadata (file stats, git info, etc.)
  include_metadata: true

  # Automatically summarize files larger than this (characters)
  compression_threshold: 10000

  # Target compression ratio for large files
  summary_ratio: 0.25

  # Automatically copy distill output to clipboard
  copy_on_distill: false

# ============================================================================
# CACHING - Speed up repeated operations
# ============================================================================

cache:
  # Enable caching system
  enabled: true

  # Cache directory (defaults to ~/.tenets/cache)
  # directory: /custom/cache/path

  # How long to keep cached data (days)
  ttl_days: 7

  # Maximum cache size (MB)
  max_size_mb: 500

  # Compress cached data (saves space, slower)
  compression: false

  # In-memory cache size
  memory_cache_size: 1000

  # SQLite performance tuning
  sqlite_pragmas:
    journal_mode: WAL
    synchronous: NORMAL
    cache_size: '-64000' # 64MB
    temp_store: MEMORY

  # Maximum age for analysis cache (hours)
  max_age_hours: 24

# ============================================================================
# GIT INTEGRATION - Include version control context
# ============================================================================

git:
  # Enable git integration
  enabled: true

  # Include commit history in context
  include_history: true

  # Maximum commits to include
  history_limit: 100

  # Include git blame information
  include_blame: false

  # Include repository statistics
  include_stats: true

  # Authors to ignore (bots, etc.)
  ignore_authors:
    - 'dependabot[bot]'
    - 'github-actions[bot]'
    - 'renovate[bot]'

  # Branch names considered "main"
  main_branches:
    - main
    - master
    - develop
    - trunk

# ============================================================================
# TENET SYSTEM - Smart injection of guiding principles for AI interactions
# ============================================================================

tenet:
  # ---- CORE SETTINGS ----
  # Automatically inject tenets into context
  auto_instill: true

  # Maximum tenets to include per context
  max_per_context: 5

  # Reinforce critical tenets at end
  reinforcement: true

  # Injection strategy for placement
  # Options: strategic, top, distributed, uniform, random
  injection_strategy: strategic

  # Minimum distance between tenet injections (characters)
  min_distance_between: 1000

  # Prefer injecting at natural break points (sections, paragraphs)
  prefer_natural_breaks: true

  # Tenet storage directory (defaults to ~/.tenets/tenets)
  # storage_path: /custom/tenets/path

  # Enable tenet collections (grouped tenets)
  collections_enabled: true

  # ---- SMART INJECTION FREQUENCY ----
  # Control when and how often tenets are injected

  # Injection frequency mode
  # Options:
  #   always   - Inject into every distilled context
  #   periodic - Inject every Nth distillation (set by injection_interval)
  #   adaptive - Smart injection based on context complexity and session
  #   manual   - Only inject when explicitly requested
  injection_frequency: adaptive

  # Interval for periodic injection (e.g., 3 = every 3rd distill)
  injection_interval: 3

  # Complexity threshold for adaptive injection (0-1)
  # Higher values = inject only on complex contexts
  session_complexity_threshold: 0.7

  # Minimum distills in session before first injection
  # Prevents overwhelming users in short sessions
  min_session_length: 5

  # Enable adaptive injection based on context analysis
  adaptive_injection: true

  # Track injection history per session for smarter decisions
  track_injection_history: true

  # How quickly tenet importance decays (0-1)
  # 0 = never decay, 1 = immediate decay
  # Lower values = tenets stay "fresh" longer
  decay_rate: 0.1

  # Reinforce critical tenets every N injections
  reinforcement_interval: 10

  # ---- SESSION TRACKING ----
  # Session-aware injection patterns

  # Enable session-aware injection patterns
  session_aware: true

  # Maximum concurrent sessions to track in memory
  session_memory_limit: 100

  # Persist session histories to disk
  persist_session_history: true

  # ---- ADVANCED INJECTION SETTINGS ----
  # Fine-tune injection behavior

  # Weight given to complexity in injection decisions (0-1)
  complexity_weight: 0.5

  # Boost factor for critical priority tenets
  priority_boost_critical: 2.0

  # Boost factor for high priority tenets
  priority_boost_high: 1.5

  # Skip low priority tenets when context complexity exceeds threshold
  skip_low_priority_on_complex: true

  # ---- METRICS AND ANALYSIS ----
  # Track and analyze tenet effectiveness

  # Enable effectiveness tracking
  track_effectiveness: true

  # Days to consider for effectiveness analysis
  effectiveness_window_days: 30

  # Minimum compliance score before forcing reinforcement
  min_compliance_score: 0.6

# ============================================================================
# INJECTION FREQUENCY EXAMPLES
# ============================================================================
#
# Example configurations for different use cases:
#
# 1. ALWAYS INJECT (Maximum reinforcement)
# tenet:
#   injection_frequency: always
#   max_per_context: 3  # Limit to avoid overwhelming
#
# 2. PERIODIC INJECTION (Regular intervals)
# tenet:
#   injection_frequency: periodic
#   injection_interval: 5  # Every 5th distill
#   min_session_length: 0  # Start immediately
#
# 3. ADAPTIVE INJECTION (Smart, context-aware)
# tenet:
#   injection_frequency: adaptive
#   session_complexity_threshold: 0.6  # Medium complexity trigger
#   min_session_length: 3  # Wait for session to develop
#   adaptive_injection: true
#   decay_rate: 0.2  # Moderate decay
#
# 4. MANUAL ONLY (User control)
# tenet:
#   injection_frequency: manual
#   auto_instill: false  # Disable automatic injection
#
# 5. AGGRESSIVE REINFORCEMENT (Learning/training)
# tenet:
#   injection_frequency: periodic
#   injection_interval: 2  # Every other distill
#   reinforcement_interval: 5  # Frequent reinforcement
#   priority_boost_critical: 3.0  # Strong critical boost
#
# 6. GENTLE REMINDER (Long sessions)
# tenet:
#   injection_frequency: adaptive
#   min_session_length: 10  # Wait for established session
#   decay_rate: 0.05  # Very slow decay
#   session_complexity_threshold: 0.8  # Only complex contexts
#
# ============================================================================

# ============================================================================
# CUSTOM CONFIGURATION - Project-specific settings
# ============================================================================

custom:
  # Add any project-specific configuration here
  # These values are accessible via config.custom

  # Example: Project metadata
  # project_name: "My Project"
  # project_version: "1.0.0"

  # Example: Team preferences
  # team:
  #   lead: "john.doe@example.com"
  #   slack_channel: "#dev-team"

  # Example: Integration settings
  # integrations:
  #   jira_url: "https://company.atlassian.net"
  #   github_org: "my-org"
# ============================================================================
# ENVIRONMENT VARIABLE OVERRIDES
# ============================================================================
#
# Any configuration value can be overridden using environment variables.
# This includes API keys - env vars take precedence over config values.
#
# Format: TENETS_<SECTION>_<KEY>=value
#
# Examples:
#   TENETS_MAX_TOKENS=150000
#   TENETS_RANKING_ALGORITHM=thorough
#   TENETS_RANKING_THRESHOLD=0.05
#   TENETS_RANKING_USE_STOPWORDS=false
#   TENETS_SUMMARIZER_DEFAULT_MODE=extractive
#   TENETS_SUMMARIZER_TARGET_RATIO=0.2
#   TENETS_CACHE_ENABLED=false
#   TENETS_GIT_ENABLED=true
#   TENETS_SCANNER_MAX_FILE_SIZE=10000000
#
# NLP configuration overrides:
#   TENETS_NLP_ENABLED=true
#   TENETS_NLP_EMBEDDINGS_ENABLED=true
#   TENETS_NLP_EMBEDDINGS_MODEL=all-MiniLM-L12-v2
#   TENETS_NLP_KEYWORD_EXTRACTION_METHOD=yake
#   TENETS_NLP_STOPWORDS_ENABLED=false
#   TENETS_NLP_MULTIPROCESSING_ENABLED=true
#   TENETS_NLP_MULTIPROCESSING_WORKERS=8
#
# Tenet system configuration overrides:
#   TENETS_TENET_AUTO_INSTILL=true
#   TENETS_TENET_MAX_PER_CONTEXT=5
#   TENETS_TENET_INJECTION_FREQUENCY=adaptive
#   TENETS_TENET_INJECTION_INTERVAL=3
#   TENETS_TENET_SESSION_COMPLEXITY_THRESHOLD=0.7
#   TENETS_TENET_MIN_SESSION_LENGTH=5
#   TENETS_TENET_ADAPTIVE_INJECTION=true
#   TENETS_TENET_TRACK_INJECTION_HISTORY=true
#   TENETS_TENET_DECAY_RATE=0.1
#   TENETS_TENET_REINFORCEMENT_INTERVAL=10
#   TENETS_TENET_SESSION_AWARE=true
#   TENETS_TENET_COMPLEXITY_WEIGHT=0.5
#   TENETS_TENET_PRIORITY_BOOST_CRITICAL=2.0
#   TENETS_TENET_PRIORITY_BOOST_HIGH=1.5
#   TENETS_TENET_TRACK_EFFECTIVENESS=true
#
# API Keys can also be set as env vars (overrides config):
#   export OPENAI_API_KEY=sk-...
#   export ANTHROPIC_API_KEY=sk-ant-...
#   export OPENROUTER_API_KEY=sk-or-...
#
# Use 'tenets config show --key models' to see model pricing
# Use 'tenets estimate-cost' to calculate costs before running
#
# ============================================================================

# ============================================================================
# NOTES ON NLP CONSOLIDATION
# ============================================================================
#
# The NLP system has been consolidated into tenets.core.nlp package:
#
# 1. All tokenization goes through nlp.tokenizer
# 2. All keyword extraction goes through nlp.keyword_extractor
# 3. All stopword filtering goes through nlp.stopwords
# 4. All embeddings go through nlp.embeddings
# 5. All similarity computation goes through nlp.similarity
#
# The dual stopword system is critical:
# - Code search uses MINIMAL stopwords (~25 words) to preserve accuracy
# - Prompt parsing uses AGGRESSIVE stopwords (200+ words) to extract intent
#
# Example: "async function" in code keeps both words
# Example: "please implement async function" in prompt → ["async", "function"]
#
# ML features (embeddings, semantic similarity) require:
#   pip install sentence-transformers
#
# Without ML dependencies, the system falls back to:
# - BM25 for similarity (default) or TF-IDF (optional)
# - Frequency-based keyword extraction
#
# ============================================================================

# ============================================================================
# NOTES ON TENET INJECTION SYSTEM
# ============================================================================
#
# The tenet injection system provides sophisticated control over when and how
# guiding principles are injected into AI context:
#
# 1. **Frequency Modes**:
#    - always: Every single distillation gets tenets
#    - periodic: Regular intervals (every Nth distill)
#    - adaptive: Smart injection based on context analysis
#    - manual: User controls when to inject
#
# 2. **Session Awareness**:
#    - Tracks injection history across a session
#    - Prevents overwhelming users in short interactions
#    - Adjusts injection based on session length and complexity
#
# 3. **Priority System**:
#    - Critical tenets get boosted injection priority
#    - Low priority tenets can be skipped in complex contexts
#    - Reinforcement ensures critical tenets stay fresh
#
# 4. **Decay and Reinforcement**:
#    - Tenets "decay" in importance over time
#    - Critical tenets are reinforced at regular intervals
#    - Adaptive system learns from effectiveness metrics
#
# 5. **Complexity Analysis**:
#    - Analyzes context complexity before injection
#    - Adjusts injection strategy based on content
#    - Prevents information overload in complex contexts
#
# The system is designed to maintain consistent AI behavior without
# overwhelming the context or degrading performance.
#
# ============================================================================