htm 0.0.20 → 0.0.31

data/lib/htm/config/defaults.yml

@@ -49,7 +49,7 @@ defaults:
   # Access: HTM.config.embedding.provider, HTM.config.embedding.model, etc.
   # ---------------------------------------------------------------------------
   embedding:
-    provider: ollama
+    provider: :ollama
     model: nomic-embed-text:latest
     dimensions: 768
     timeout: 120
@@ -65,7 +65,7 @@ defaults:
   #   %{taxonomy_context} - existing taxonomy info or new taxonomy message
   # ---------------------------------------------------------------------------
   tag:
-    provider: ollama
+    provider: :ollama
     model: gemma3:latest
     timeout: 180
     max_depth: 4
@@ -91,8 +91,9 @@ defaults:
       RULES:
       1. Each concept belongs to ONE path only
       2. Use lowercase, hyphens for multi-word terms
-      3. Return 2-5 tags that best classify this text
-      4. Match existing taxonomy paths when applicable
+      3. ALWAYS use SINGULAR forms, never plurals (user NOT users, framework NOT frameworks, model NOT models)
+      4. Return 2-5 tags that best classify this text
+      5. Match existing taxonomy paths when applicable
 
       TEXT: %{text}
 
@@ -109,38 +110,66 @@ defaults:
   #   %{text} - the content to extract propositions from
   # ---------------------------------------------------------------------------
   proposition:
-    provider: ollama
+    provider: :ollama
     model: gemma3:latest
     timeout: 180
     enabled: true
+    min_length: 10
+    max_length: 1000
+    min_words: 5
 
     system_prompt: |
-      You are an atomic fact extraction system. Your goal is maximum decomposition.
-      Break every statement into its smallest possible factual units.
+      You are an atomic fact extraction system. Extract factual propositions from text.
       Output ONLY propositions, one per line, prefixed with a dash (-).
+      NEVER ask for clarification or more text - extract what you can from the given text.
+      If the text contains no extractable facts, output nothing.
 
     user_prompt_template: |
-      Extract all ATOMIC factual propositions from the following text.
+      Extract ATOMIC factual propositions from the following text.
 
-      An atomic proposition expresses exactly ONE relationship or fact.
+      An atomic proposition:
+      - Expresses exactly ONE fact or relationship
+      - Is understandable WITHOUT any additional context
+      - Uses FULL NAMES, never pronouns (he, she, it, they, this, that)
+      - Contains at least 5 words for sufficient context
 
-      Rules:
+      PRONOUN REPLACEMENT EXAMPLES:
+      BAD:  "It is important to know the enemy."
+      GOOD: "Knowing the enemy is important for spiritual warfare."
+
+      BAD:  "They support thousands of users."
+      GOOD: "The Every.to products support thousands of daily users."
+
+      BAD:  "This results in a calculation."
+      GOOD: "The age calculation depends on whether the birthday has occurred."
+
+      CONTEXT ENRICHMENT EXAMPLES:
+      BAD:  "Wiring costs $1,000."
+      GOOD: "Solar panel wiring costs $1,000 for the Oklahoma barndominium project."
+
+      BAD:  "The driveway is gravel."
+      GOOD: "Dewayne's barndominium driveway is gravel."
+
+      RULES:
       1. Split compound statements into separate atomic facts
       2. Each proposition = exactly one fact
-      3. Use full names, never pronouns
-      4. Make each proposition understandable in isolation
+      3. Replace ALL pronouns with the actual names/nouns they refer to
+      4. Include enough context to understand the fact in isolation
+      5. If unsure what a pronoun refers to, omit that proposition
 
       TEXT: %{text}
 
       Return ONLY atomic propositions, one per line. Use a dash (-) prefix for each.
+      If you cannot extract any facts, return nothing. Do NOT ask for more text.
 
   # ---------------------------------------------------------------------------
   # Chunking Configuration (for file loading)
-  # Access: HTM.config.chunking.size, HTM.config.chunking.overlap
+  # Access: HTM.config.chunking.chunk_size, HTM.config.chunking.chunk_overlap
+  # Note: Using chunk_size/chunk_overlap to avoid collision with Enumerable#size
   # ---------------------------------------------------------------------------
   chunking:
-    size: 1024
-    overlap: 64
+    chunk_size: 1024
+    chunk_overlap: 64
 
   # ---------------------------------------------------------------------------
   # Circuit Breaker Configuration
@@ -167,16 +196,16 @@ defaults:
   # Access: HTM.config.job.backend
   # ---------------------------------------------------------------------------
   job:
-    backend: fiber
+    backend: :fiber
 
   # ---------------------------------------------------------------------------
   # General Settings
   # Access: HTM.config.week_start, HTM.config.connection_timeout, etc.
   # ---------------------------------------------------------------------------
-  week_start: sunday
+  week_start: :sunday
   connection_timeout: 60
   telemetry_enabled: false
-  log_level: info
+  log_level: :info
 
   # ---------------------------------------------------------------------------
   # Provider Credentials
@@ -222,7 +251,7 @@ defaults:
 development:
   database:
     name: htm_development
-  log_level: debug
+  log_level: :debug
 
 # =============================================================================
 # Test Environment Overrides
@@ -231,8 +260,8 @@ test:
   database:
     name: htm_test
   job:
-    backend: inline
-  log_level: warn
+    backend: :inline
+  log_level: :warn
   telemetry_enabled: false
 
 # =============================================================================
@@ -242,5 +271,16 @@ production:
   database:
     pool_size: 25
     sslmode: require
-  log_level: warn
+  log_level: :warn
   telemetry_enabled: true
+
+# =============================================================================
+# Examples Environment Overrides (for running example scripts)
+# =============================================================================
+examples:
+  database:
+    name: htm_examples
+  job:
+    backend: :inline
+  log_level: :info
+  telemetry_enabled: false

data/lib/htm/config/validator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class HTM
+  class Config
+    module Validator
+      SUPPORTED_PROVIDERS = %i[
+        openai anthropic gemini azure ollama
+        huggingface openrouter bedrock deepseek
+      ].freeze
+
+      SUPPORTED_JOB_BACKENDS = %i[active_job sidekiq inline thread fiber].freeze
+      SUPPORTED_WEEK_STARTS = %i[sunday monday].freeze
+
+      def validate_config
+        validate_providers
+        validate_job_backend
+        validate_week_start
+        validate_relevance_weights
+      end
+
+      def validate_providers
+        validate_provider(:embedding_provider, embedding_provider)
+        validate_provider(:tag_provider, tag_provider)
+        validate_provider(:proposition_provider, proposition_provider)
+      end
+
+      def validate_provider(name, value)
+        return if value.nil?
+
+        unless SUPPORTED_PROVIDERS.include?(value)
+          raise_validation_error("#{name} must be one of: #{SUPPORTED_PROVIDERS.join(', ')} (got #{value.inspect})")
+        end
+      end
+
+      def validate_job_backend
+        return unless job_backend
+
+        unless SUPPORTED_JOB_BACKENDS.include?(job_backend)
+          raise_validation_error("job.backend must be one of: #{SUPPORTED_JOB_BACKENDS.join(', ')} (got #{job_backend.inspect})")
+        end
+      end
+
+      def validate_week_start
+        unless SUPPORTED_WEEK_STARTS.include?(week_start)
+          raise_validation_error("week_start must be one of: #{SUPPORTED_WEEK_STARTS.join(', ')} (got #{week_start.inspect})")
+        end
+      end
+
+      def validate_relevance_weights
+        total = relevance_semantic_weight + relevance_tag_weight +
+                relevance_recency_weight + relevance_access_weight
+
+        unless (0.99..1.01).cover?(total)
+          raise_validation_error("relevance weights must sum to 1.0 (got #{total})")
+        end
+      end
+
+      def validate_callables
+        unless @embedding_generator.respond_to?(:call)
+          raise HTM::ValidationError, "embedding_generator must be callable"
+        end
+
+        unless @tag_extractor.respond_to?(:call)
+          raise HTM::ValidationError, "tag_extractor must be callable"
+        end
+
+        unless @proposition_extractor.respond_to?(:call)
+          raise HTM::ValidationError, "proposition_extractor must be callable"
+        end
+
+        unless @token_counter.respond_to?(:call)
+          raise HTM::ValidationError, "token_counter must be callable"
+        end
+      end
+
+      def validate_logger
+        unless @logger.respond_to?(:info) && @logger.respond_to?(:warn) && @logger.respond_to?(:error)
+          raise HTM::ValidationError, "logger must respond to :info, :warn, and :error"
+        end
+      end
+    end
+  end
+end