htm 0.0.18 → 0.0.20

data/docs/api/yard/HTM/Config.md

@@ -0,0 +1,173 @@
+# Class: HTM::Config
+**Inherits:** Anyway::Config
+    
+
+HTM Configuration using Anyway Config
+
+Schema is defined in lib/htm/config/defaults.yml (single source of truth)
+Configuration uses nested sections for better organization:
+    - HTM.config.database.host
+    - HTM.config.embedding.provider
+    - HTM.config.providers.openai.api_key
+
+Configuration sources (lowest to highest priority):
+1.  Bundled defaults: lib/htm/config/defaults.yml (ships with gem)
+2.  XDG user config:
+    *   ~/Library/Application Support/htm/htm.yml (macOS only)
+    *   ~/.config/htm/htm.yml (XDG default)
+    *   $XDG_CONFIG_HOME/htm/htm.yml (if XDG_CONFIG_HOME is set)
+3.  Project config: ./config/htm.yml (environment-specific)
+4.  Local overrides: ./config/htm.local.yml (gitignored)
+5.  Environment variables (HTM_*)
+6.  Explicit values passed to configure block
+
+
+**`@example`**
+```ruby
+export HTM_EMBEDDING__PROVIDER=openai
+export HTM_EMBEDDING__MODEL=text-embedding-3-small
+export HTM_PROVIDERS__OPENAI__API_KEY=sk-xxx
+```
+**`@example`**
+```ruby
+embedding:
+  provider: ollama
+  model: nomic-embed-text:latest
+providers:
+  ollama:
+    url: http://localhost:11434
+```
+**`@example`**
+```ruby
+HTM.configure do |config|
+  config.embedding.provider = :openai
+  config.embedding.model = 'text-embedding-3-small'
+end
+```
+# Class Methods
+## active_xdg_config_file() {: #method-c-active_xdg_config_file }
+## config_section_with_defaults(section_key ) {: #method-c-config_section_with_defaults }
+Create a coercion that merges incoming value with SCHEMA defaults for a
+section. This ensures env vars like HTM_DATABASE__URL don't lose other
+defaults.
+## deep_merge_hashes(base , overlay ) {: #method-c-deep_merge_hashes }
+Deep merge helper for coercion
+## env() {: #method-c-env }
+## xdg_config_file() {: #method-c-xdg_config_file }
+## xdg_config_paths() {: #method-c-xdg_config_paths }
+XDG Config Path Helpers
+
+# Attributes
+## embedding_generator[RW] {: #attribute-i-embedding_generator }
+Callable Accessors (not loaded from config sources)
+
+
+## logger[RW] {: #attribute-i-logger }
+Returns the value of attribute logger.
+
+## proposition_extractor[RW] {: #attribute-i-proposition_extractor }
+Callable Accessors (not loaded from config sources)
+
+
+## tag_extractor[RW] {: #attribute-i-tag_extractor }
+Callable Accessors (not loaded from config sources)
+
+
+## token_counter[RW] {: #attribute-i-token_counter }
+Returns the value of attribute token_counter.
+
+
+# Instance Methods
+## anthropic_api_key() {: #method-i-anthropic_api_key }
+## azure_api_key() {: #method-i-azure_api_key }
+## azure_api_version() {: #method-i-azure_api_version }
+## azure_endpoint() {: #method-i-azure_endpoint }
+## bedrock_access_key() {: #method-i-bedrock_access_key }
+## bedrock_region() {: #method-i-bedrock_region }
+## bedrock_secret_key() {: #method-i-bedrock_secret_key }
+## chunk_overlap() {: #method-i-chunk_overlap }
+## chunk_size() {: #method-i-chunk_size }
+Chunking convenience accessors
+
+## circuit_breaker_failure_threshold() {: #method-i-circuit_breaker_failure_threshold }
+Circuit breaker convenience accessors
+
+## circuit_breaker_half_open_max_calls() {: #method-i-circuit_breaker_half_open_max_calls }
+## circuit_breaker_reset_timeout() {: #method-i-circuit_breaker_reset_timeout }
+## configure_ruby_llm(providernil) {: #method-i-configure_ruby_llm }
+## database_config() {: #method-i-database_config }
+## database_configured?() {: #method-i-database_configured? }
+**`@return`** [Boolean] 
+
+## database_url() {: #method-i-database_url }
+Database convenience methods
+
+## deepseek_api_key() {: #method-i-deepseek_api_key }
+## development?() {: #method-i-development? }
+**`@return`** [Boolean] 
+
+## embedding_dimensions() {: #method-i-embedding_dimensions }
+## embedding_model() {: #method-i-embedding_model }
+## embedding_provider() {: #method-i-embedding_provider }
+Embedding convenience accessors
+
+## embedding_timeout() {: #method-i-embedding_timeout }
+## environment() {: #method-i-environment }
+## extract_propositions() {: #method-i-extract_propositions }
+## gemini_api_key() {: #method-i-gemini_api_key }
+## huggingface_api_key() {: #method-i-huggingface_api_key }
+## initialize() {: #method-i-initialize }
+Instance Methods
+
+
+**`@return`** [Config] a new instance of Config
+
+## job_backend() {: #method-i-job_backend }
+Job backend convenience accessor
+
+## max_embedding_dimension() {: #method-i-max_embedding_dimension }
+## max_tag_depth() {: #method-i-max_tag_depth }
+## normalize_ollama_model(model_name) {: #method-i-normalize_ollama_model }
+Ollama Helpers
+
+
+## ollama_url() {: #method-i-ollama_url }
+## openai_api_key() {: #method-i-openai_api_key }
+Provider credential convenience accessors
+
+## openai_organization() {: #method-i-openai_organization }
+## openai_project() {: #method-i-openai_project }
+## openrouter_api_key() {: #method-i-openrouter_api_key }
+## production?() {: #method-i-production? }
+**`@return`** [Boolean] 
+
+## proposition_model() {: #method-i-proposition_model }
+## proposition_provider() {: #method-i-proposition_provider }
+Proposition convenience accessors
+
+## proposition_timeout() {: #method-i-proposition_timeout }
+## refresh_ollama_models!() {: #method-i-refresh_ollama_models! }
+## relevance_access_weight() {: #method-i-relevance_access_weight }
+## relevance_recency_half_life_hours() {: #method-i-relevance_recency_half_life_hours }
+## relevance_recency_weight() {: #method-i-relevance_recency_weight }
+## relevance_semantic_weight() {: #method-i-relevance_semantic_weight }
+Relevance scoring convenience accessors
+
+## relevance_tag_weight() {: #method-i-relevance_tag_weight }
+## reset_to_defaults() {: #method-i-reset_to_defaults }
+## service_name() {: #method-i-service_name }
+Service name convenience accessor
+
+## tag_model() {: #method-i-tag_model }
+## tag_provider() {: #method-i-tag_provider }
+Tag convenience accessors
+
+## tag_timeout() {: #method-i-tag_timeout }
+## test?() {: #method-i-test? }
+Environment Helpers
+
+
+**`@return`** [Boolean] 
+
+## validate!() {: #method-i-validate! }
+## validate_settings!() {: #method-i-validate_settings! }

data/docs/api/yard/HTM/ConfigSection.md

@@ -0,0 +1,28 @@
+# Class: HTM::ConfigSection
+**Inherits:** Object
+    
+
+ConfigSection provides method access to nested configuration hashes
+
+
+**`@example`**
+```ruby
+section = ConfigSection.new(host: 'localhost', port: 5432)
+section.host  # => 'localhost'
+section.port  # => 5432
+```
+
+# Instance Methods
+## `[](key)` {: #method-i-[] }
+## `[]=(key, value)` {: #method-i-[]= }
+## `each(&block)` {: #method-i-each }
+## `initialize(hash = {})` {: #method-i-initialize }
+**`@return`** [ConfigSection] a new instance of ConfigSection
+
+## `keys()` {: #method-i-keys }
+## `merge(other)` {: #method-i-merge }
+## `method_missing(method, *args, &block)` {: #method-i-method_missing }
+## `respond_to_missing?(method, include_private = false)` {: #method-i-respond_to_missing? }
+**`@return`** [Boolean] 
+
+## `to_h()` {: #method-i-to_h }

data/docs/api/yard/HTM/Database.md

@@ -8,7 +8,7 @@ initialization
 
 # Class Methods
 ## default_config() {: #method-c-default_config }
-Get default database configuration (respects HTM_ENV)
+Get default database configuration
 
 Uses HTM::Config for database settings.
 **`@return`** [Hash, nil] Connection configuration hash with PG-style keys

data/docs/api/yard/HTM/Railtie.md

@@ -20,8 +20,8 @@ This railtie automatically configures HTM when Rails boots:
 ```ruby
 # config/initializers/htm.rb
 HTM.configure do |config|
-  config.embedding.model = 'custom-model'
-  config.tag.model = 'custom-tag-model'
+  config.embedding_model = 'custom-model'
+  config.tag_model = 'custom-tag-model'
 end
 ```
 

data/docs/api/yard/HTM.md

@@ -6,61 +6,4 @@ examples/robot_groups/lib/htm/working_memory_channel.rb frozen_string_literal:
 true
 
 
-# Class Methods
-## configure() {: #method-c-configure }
-Configure HTM
-**`@yield`** [config] Configuration object
-
-**`@yieldparam`** [HTM::Configuration] 
-
-
-**`@example`**
-```ruby
-HTM.configure do |config|
-  config.embedding_generator = ->(text) { MyEmbedder.embed(text) }
-  config.tag_extractor = ->(text, ontology) { MyTagger.extract(text, ontology) }
-end
-```
-**`@example`**
-```ruby
-HTM.configure  # Uses RubyLLM defaults
-```
-## count_tokens(text ) {: #method-c-count_tokens }
-Count tokens using configured counter
-**`@param`** [String] Text to count tokens for
-
-**`@return`** [Integer] Token count
-
-## embed(text ) {: #method-c-embed }
-Generate embedding using EmbeddingService
-**`@param`** [String] Text to embed
-
-**`@return`** [Array<Float>] Embedding vector (original, not padded)
-
-## extract_propositions(text ) {: #method-c-extract_propositions }
-Extract propositions using PropositionService
-**`@param`** [String] Text to analyze
-
-**`@return`** [Array<String>] Extracted atomic propositions
-
-## extract_tags(text , existing_ontology: []) {: #method-c-extract_tags }
-Extract tags using TagService
-**`@param`** [String] Text to analyze
-
-**`@param`** [Array<String>] Sample of existing tags for context
-
-**`@return`** [Array<String>] Extracted and validated tag names
-
-## logger() {: #method-c-logger }
-Get configured logger
-**`@return`** [Logger] Configured logger instance
-
-## reset_configuration!() {: #method-c-reset_configuration! }
-Reset configuration to defaults
-# Attributes
-## configuration[RW] {: #attribute-c-configuration }
-Get current configuration
-
-**`@return`** [HTM::Configuration] 
-
 

data/docs/api/yard/index.csv

@@ -28,14 +28,6 @@ HTM::Telemetry.search_latency,Method,HTM/Telemetry.md#method-c-search_latency
 HTM::Telemetry.setup,Method,HTM/Telemetry.md#method-c-setup
 HTM::Telemetry.tag_latency,Method,HTM/Telemetry.md#method-c-tag_latency
 HTM,Class,HTM.md
-HTM.configure,Method,HTM.md#method-c-configure
-HTM.count_tokens,Method,HTM.md#method-c-count_tokens
-HTM.embed,Method,HTM.md#method-c-embed
-HTM.extract_propositions,Method,HTM.md#method-c-extract_propositions
-HTM.extract_tags,Method,HTM.md#method-c-extract_tags
-HTM.logger,Method,HTM.md#method-c-logger
-HTM.reset_configuration!,Method,HTM.md#method-c-reset_configuration!
-configuration,Attribute,HTM.md#attribute-c-configuration
 HTM::ActiveRecordConfig,Class,HTM/ActiveRecordConfig.md
 HTM::ActiveRecordConfig.connected?,Method,HTM/ActiveRecordConfig.md#method-c-connected?
 HTM::ActiveRecordConfig.connection_stats,Method,HTM/ActiveRecordConfig.md#method-c-connection_stats
@@ -55,59 +47,82 @@ failure_count,Attribute,HTM/CircuitBreaker.md#attribute-i-failure_count
 last_failure_time,Attribute,HTM/CircuitBreaker.md#attribute-i-last_failure_time
 name,Attribute,HTM/CircuitBreaker.md#attribute-i-name
 state,Attribute,HTM/CircuitBreaker.md#attribute-i-state
-HTM::Configuration,Class,HTM/Configuration.md
-HTM::Configuration.configure_ruby_llm,Method,HTM/Configuration.md#method-i-configure_ruby_llm
-HTM::Configuration.initialize,Method,HTM/Configuration.md#method-i-initialize
-HTM::Configuration.normalize_ollama_model,Method,HTM/Configuration.md#method-i-normalize_ollama_model
-HTM::Configuration.reset_to_defaults,Method,HTM/Configuration.md#method-i-reset_to_defaults
-HTM::Configuration.validate!,Method,HTM/Configuration.md#method-i-validate!
-anthropic_api_key,Attribute,HTM/Configuration.md#attribute-i-anthropic_api_key
-azure_api_key,Attribute,HTM/Configuration.md#attribute-i-azure_api_key
-azure_api_version,Attribute,HTM/Configuration.md#attribute-i-azure_api_version
-azure_endpoint,Attribute,HTM/Configuration.md#attribute-i-azure_endpoint
-bedrock_access_key,Attribute,HTM/Configuration.md#attribute-i-bedrock_access_key
-bedrock_region,Attribute,HTM/Configuration.md#attribute-i-bedrock_region
-bedrock_secret_key,Attribute,HTM/Configuration.md#attribute-i-bedrock_secret_key
-chunk_overlap,Attribute,HTM/Configuration.md#attribute-i-chunk_overlap
-chunk_size,Attribute,HTM/Configuration.md#attribute-i-chunk_size
-circuit_breaker_failure_threshold,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_failure_threshold
-circuit_breaker_half_open_max_calls,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_half_open_max_calls
-circuit_breaker_reset_timeout,Attribute,HTM/Configuration.md#attribute-i-circuit_breaker_reset_timeout
-connection_timeout,Attribute,HTM/Configuration.md#attribute-i-connection_timeout
-deepseek_api_key,Attribute,HTM/Configuration.md#attribute-i-deepseek_api_key
-embedding_dimensions,Attribute,HTM/Configuration.md#attribute-i-embedding_dimensions
-embedding_generator,Attribute,HTM/Configuration.md#attribute-i-embedding_generator
-embedding_model,Attribute,HTM/Configuration.md#attribute-i-embedding_model
-embedding_provider,Attribute,HTM/Configuration.md#attribute-i-embedding_provider
-embedding_timeout,Attribute,HTM/Configuration.md#attribute-i-embedding_timeout
-extract_propositions,Attribute,HTM/Configuration.md#attribute-i-extract_propositions
-gemini_api_key,Attribute,HTM/Configuration.md#attribute-i-gemini_api_key
-huggingface_api_key,Attribute,HTM/Configuration.md#attribute-i-huggingface_api_key
-job_backend,Attribute,HTM/Configuration.md#attribute-i-job_backend
-logger,Attribute,HTM/Configuration.md#attribute-i-logger
-max_embedding_dimension,Attribute,HTM/Configuration.md#attribute-i-max_embedding_dimension
-max_tag_depth,Attribute,HTM/Configuration.md#attribute-i-max_tag_depth
-ollama_url,Attribute,HTM/Configuration.md#attribute-i-ollama_url
-openai_api_key,Attribute,HTM/Configuration.md#attribute-i-openai_api_key
-openai_organization,Attribute,HTM/Configuration.md#attribute-i-openai_organization
-openai_project,Attribute,HTM/Configuration.md#attribute-i-openai_project
-openrouter_api_key,Attribute,HTM/Configuration.md#attribute-i-openrouter_api_key
-proposition_extractor,Attribute,HTM/Configuration.md#attribute-i-proposition_extractor
-proposition_model,Attribute,HTM/Configuration.md#attribute-i-proposition_model
-proposition_provider,Attribute,HTM/Configuration.md#attribute-i-proposition_provider
-proposition_timeout,Attribute,HTM/Configuration.md#attribute-i-proposition_timeout
-relevance_access_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_access_weight
-relevance_recency_half_life_hours,Attribute,HTM/Configuration.md#attribute-i-relevance_recency_half_life_hours
-relevance_recency_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_recency_weight
-relevance_semantic_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_semantic_weight
-relevance_tag_weight,Attribute,HTM/Configuration.md#attribute-i-relevance_tag_weight
-tag_extractor,Attribute,HTM/Configuration.md#attribute-i-tag_extractor
-tag_model,Attribute,HTM/Configuration.md#attribute-i-tag_model
-tag_provider,Attribute,HTM/Configuration.md#attribute-i-tag_provider
-tag_timeout,Attribute,HTM/Configuration.md#attribute-i-tag_timeout
-telemetry_enabled,Attribute,HTM/Configuration.md#attribute-i-telemetry_enabled
-token_counter,Attribute,HTM/Configuration.md#attribute-i-token_counter
-week_start,Attribute,HTM/Configuration.md#attribute-i-week_start
+HTM::ConfigSection,Class,HTM/ConfigSection.md
+HTM::ConfigSection.[],Method,HTM/ConfigSection.md#method-i-[]
+HTM::ConfigSection.[]=,Method,HTM/ConfigSection.md#method-i-[]=
+HTM::ConfigSection.each,Method,HTM/ConfigSection.md#method-i-each
+HTM::ConfigSection.initialize,Method,HTM/ConfigSection.md#method-i-initialize
+HTM::ConfigSection.keys,Method,HTM/ConfigSection.md#method-i-keys
+HTM::ConfigSection.merge,Method,HTM/ConfigSection.md#method-i-merge
+HTM::ConfigSection.method_missing,Method,HTM/ConfigSection.md#method-i-method_missing
+HTM::ConfigSection.respond_to_missing?,Method,HTM/ConfigSection.md#method-i-respond_to_missing?
+HTM::ConfigSection.to_h,Method,HTM/ConfigSection.md#method-i-to_h
+HTM::Config,Class,HTM/Config.md
+HTM::Config.anthropic_api_key,Method,HTM/Config.md#method-i-anthropic_api_key
+HTM::Config.azure_api_key,Method,HTM/Config.md#method-i-azure_api_key
+HTM::Config.azure_api_version,Method,HTM/Config.md#method-i-azure_api_version
+HTM::Config.azure_endpoint,Method,HTM/Config.md#method-i-azure_endpoint
+HTM::Config.bedrock_access_key,Method,HTM/Config.md#method-i-bedrock_access_key
+HTM::Config.bedrock_region,Method,HTM/Config.md#method-i-bedrock_region
+HTM::Config.bedrock_secret_key,Method,HTM/Config.md#method-i-bedrock_secret_key
+HTM::Config.chunk_overlap,Method,HTM/Config.md#method-i-chunk_overlap
+HTM::Config.chunk_size,Method,HTM/Config.md#method-i-chunk_size
+HTM::Config.circuit_breaker_failure_threshold,Method,HTM/Config.md#method-i-circuit_breaker_failure_threshold
+HTM::Config.circuit_breaker_half_open_max_calls,Method,HTM/Config.md#method-i-circuit_breaker_half_open_max_calls
+HTM::Config.circuit_breaker_reset_timeout,Method,HTM/Config.md#method-i-circuit_breaker_reset_timeout
+HTM::Config.configure_ruby_llm,Method,HTM/Config.md#method-i-configure_ruby_llm
+HTM::Config.database_config,Method,HTM/Config.md#method-i-database_config
+HTM::Config.database_configured?,Method,HTM/Config.md#method-i-database_configured?
+HTM::Config.database_url,Method,HTM/Config.md#method-i-database_url
+HTM::Config.deepseek_api_key,Method,HTM/Config.md#method-i-deepseek_api_key
+HTM::Config.development?,Method,HTM/Config.md#method-i-development?
+HTM::Config.embedding_dimensions,Method,HTM/Config.md#method-i-embedding_dimensions
+HTM::Config.embedding_model,Method,HTM/Config.md#method-i-embedding_model
+HTM::Config.embedding_provider,Method,HTM/Config.md#method-i-embedding_provider
+HTM::Config.embedding_timeout,Method,HTM/Config.md#method-i-embedding_timeout
+HTM::Config.environment,Method,HTM/Config.md#method-i-environment
+HTM::Config.extract_propositions,Method,HTM/Config.md#method-i-extract_propositions
+HTM::Config.gemini_api_key,Method,HTM/Config.md#method-i-gemini_api_key
+HTM::Config.huggingface_api_key,Method,HTM/Config.md#method-i-huggingface_api_key
+HTM::Config.initialize,Method,HTM/Config.md#method-i-initialize
+HTM::Config.job_backend,Method,HTM/Config.md#method-i-job_backend
+HTM::Config.max_embedding_dimension,Method,HTM/Config.md#method-i-max_embedding_dimension
+HTM::Config.max_tag_depth,Method,HTM/Config.md#method-i-max_tag_depth
+HTM::Config.normalize_ollama_model,Method,HTM/Config.md#method-i-normalize_ollama_model
+HTM::Config.ollama_url,Method,HTM/Config.md#method-i-ollama_url
+HTM::Config.openai_api_key,Method,HTM/Config.md#method-i-openai_api_key
+HTM::Config.openai_organization,Method,HTM/Config.md#method-i-openai_organization
+HTM::Config.openai_project,Method,HTM/Config.md#method-i-openai_project
+HTM::Config.openrouter_api_key,Method,HTM/Config.md#method-i-openrouter_api_key
+HTM::Config.production?,Method,HTM/Config.md#method-i-production?
+HTM::Config.proposition_model,Method,HTM/Config.md#method-i-proposition_model
+HTM::Config.proposition_provider,Method,HTM/Config.md#method-i-proposition_provider
+HTM::Config.proposition_timeout,Method,HTM/Config.md#method-i-proposition_timeout
+HTM::Config.refresh_ollama_models!,Method,HTM/Config.md#method-i-refresh_ollama_models!
+HTM::Config.relevance_access_weight,Method,HTM/Config.md#method-i-relevance_access_weight
+HTM::Config.relevance_recency_half_life_hours,Method,HTM/Config.md#method-i-relevance_recency_half_life_hours
+HTM::Config.relevance_recency_weight,Method,HTM/Config.md#method-i-relevance_recency_weight
+HTM::Config.relevance_semantic_weight,Method,HTM/Config.md#method-i-relevance_semantic_weight
+HTM::Config.relevance_tag_weight,Method,HTM/Config.md#method-i-relevance_tag_weight
+HTM::Config.reset_to_defaults,Method,HTM/Config.md#method-i-reset_to_defaults
+HTM::Config.service_name,Method,HTM/Config.md#method-i-service_name
+HTM::Config.tag_model,Method,HTM/Config.md#method-i-tag_model
+HTM::Config.tag_provider,Method,HTM/Config.md#method-i-tag_provider
+HTM::Config.tag_timeout,Method,HTM/Config.md#method-i-tag_timeout
+HTM::Config.test?,Method,HTM/Config.md#method-i-test?
+HTM::Config.validate!,Method,HTM/Config.md#method-i-validate!
+HTM::Config.validate_settings!,Method,HTM/Config.md#method-i-validate_settings!
+HTM::Config.active_xdg_config_file,Method,HTM/Config.md#method-c-active_xdg_config_file
+HTM::Config.config_section_with_defaults,Method,HTM/Config.md#method-c-config_section_with_defaults
+HTM::Config.deep_merge_hashes,Method,HTM/Config.md#method-c-deep_merge_hashes
+HTM::Config.env,Method,HTM/Config.md#method-c-env
+HTM::Config.xdg_config_file,Method,HTM/Config.md#method-c-xdg_config_file
+HTM::Config.xdg_config_paths,Method,HTM/Config.md#method-c-xdg_config_paths
+embedding_generator,Attribute,HTM/Config.md#attribute-i-embedding_generator
+logger,Attribute,HTM/Config.md#attribute-i-logger
+proposition_extractor,Attribute,HTM/Config.md#attribute-i-proposition_extractor
+tag_extractor,Attribute,HTM/Config.md#attribute-i-tag_extractor
+token_counter,Attribute,HTM/Config.md#attribute-i-token_counter
 HTM::Database,Class,HTM/Database.md
 HTM::Database.default_config,Method,HTM/Database.md#method-c-default_config
 HTM::Database.drop,Method,HTM/Database.md#method-c-drop

data/docs/api/yard-reference.md

@@ -24,7 +24,8 @@ Complete API documentation generated by [YARD](https://yardoc.org/) with [yard-m
 |--------------|-------------|
 | [HTM](yard/HTM.md) | Main API class for memory operations |
 | [HTM::CircuitBreaker](yard/HTM/CircuitBreaker.md) | Fault tolerance for external services |
-| [HTM::Configuration](yard/HTM/Configuration.md) | Multi-provider LLM configuration |
+| [HTM::Config](yard/HTM/Config.md) | HTM::Config class |
+| [HTM::ConfigSection](yard/HTM/ConfigSection.md) | HTM::ConfigSection class |
 | [HTM::Database](yard/HTM/Database.md) | Database schema and connection management |
 | [HTM::EmbeddingService](yard/HTM/EmbeddingService.md) | Vector embedding generation service |
 | [HTM::JobAdapter](yard/HTM/JobAdapter.md) | Background job abstraction layer |

data/docs/architecture/adrs/003-ollama-embeddings.md

@@ -1,23 +1,25 @@
-# ADR-003: Ollama as Default Embedding Provider
+# ADR-003: Default Embedding Provider Selection
 
-**Status**: Accepted (Reinstated After ADR-011 Reversal)
+**Status**: Accepted (Updated for Multi-Provider Support)
 
-**Date**: 2025-10-25 (Updated: 2025-10-27)
+**Date**: 2025-10-25 (Updated: 2025-12-21)
 
 **Decision Makers**: Dewayne VanHoozer, Claude (Anthropic)
 
 ---
 
-!!! success "Architecture Status (October 2025)"
-    **October 27, 2025**: This ADR is once again the current architecture. Following the reversal of ADR-011, HTM has returned to client-side embedding generation using Ollama as the default provider. Embeddings are generated in Ruby before database insertion.
+!!! success "Architecture Status"
+    HTM uses RubyLLM for embedding generation, supporting multiple providers. **Ollama is the default** for local development, but users can configure any supported provider (OpenAI, Anthropic, Gemini, Azure, Bedrock, DeepSeek) based on their requirements.
 
 ## Quick Summary
 
-HTM uses **Ollama with the nomic-embed-text model** as the default embedding provider, prioritizing local-first, privacy-preserving operation with zero API costs while supporting pluggable alternatives (OpenAI).
+HTM uses **Ollama with the nomic-embed-text model** as the **default** embedding provider for local development, prioritizing local-first, privacy-preserving operation with zero API costs. However, **HTM fully supports multiple providers** through RubyLLM, allowing users to choose OpenAI, Gemini, Azure, Bedrock, or other providers for production deployments.
 
-**Why**: Local embeddings eliminate API costs, preserve privacy, and enable offline operation while maintaining good semantic search quality.
+**Why Ollama as default**: Local embeddings eliminate API costs, preserve privacy, and enable offline operation—ideal for development and privacy-sensitive applications.
 
-**Impact**: Users must install Ollama locally, trading convenience for privacy and cost savings. Client-side embedding generation provides reliable operation without complex database extension dependencies.
+**Why multi-provider support**: Production deployments may require higher-quality embeddings, managed services, or integration with existing cloud infrastructure.
+
+**Impact**: Ollama is recommended for getting started quickly, but users can easily switch providers via configuration for their specific needs.
 
 ---
 
@@ -47,7 +49,16 @@ HTM requires vector embeddings for semantic search functionality. Embeddings con
 
 ## Decision
 
-We will use **Ollama with the gpt-oss model** as the default embedding provider for HTM, while supporting pluggable alternatives (OpenAI, Cohere, etc.).
+We will use **Ollama with the nomic-embed-text model** as the **default** embedding provider for HTM, while providing **full support for multiple providers** through RubyLLM:
+
+- **Ollama** (default) - Local, privacy-preserving, free
+- **OpenAI** - High-quality, production-ready
+- **Gemini** - Google Cloud integration
+- **Azure** - Enterprise Azure deployments
+- **Bedrock** - AWS integration
+- **DeepSeek** - Cost-effective alternative
+
+Users configure their preferred provider via `HTM.configure` or environment variables.
 
 ---
 
@@ -205,38 +216,36 @@ end
 
 ### User Configuration
 
-!!! info "pgai Configuration"
-    With pgai, configuration sets database session variables. Embedding generation happens automatically via triggers.
+Configure your preferred provider globally or per-instance:
 
 ```ruby
-# Default: Ollama with nomic-embed-text (768 dimensions)
-htm = HTM.new(robot_name: "My Robot")
-
-# Explicit Ollama configuration
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :ollama,
-  embedding_model: 'nomic-embed-text'
-)
+# Global configuration (recommended)
+HTM.configure do |config|
+  # Ollama (default for development)
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+
+  # Or OpenAI (recommended for production)
+  # config.embedding.provider = :openai
+  # config.embedding.model = 'text-embedding-3-small'
+
+  # Or Gemini
+  # config.embedding.provider = :gemini
+  # config.embedding.model = 'text-embedding-004'
+end
 
-# Use different Ollama model
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :ollama,
-  embedding_model: 'mxbai-embed-large',  # 1024 dimensions
-  embedding_dimensions: 1024
-)
+# Initialize HTM
+htm = HTM.new(robot_name: "My Robot")
 
-# Use OpenAI
-htm = HTM.new(
-  robot_name: "My Robot",
-  embedding_provider: :openai,
-  embedding_model: 'text-embedding-3-small'  # 1536 dimensions
-)
+# Add memory - embedding generated via configured provider
+htm.remember("PostgreSQL is awesome", tags: ["database"])
+```
 
-# Add node - embedding generated automatically by database trigger!
-htm.add_node("fact_001", "PostgreSQL is awesome", type: :fact)
-# No embedding parameter needed - pgai handles it in the database
+**Environment variables for cloud providers:**
+```bash
+export OPENAI_API_KEY="sk-..."      # For OpenAI
+export GEMINI_API_KEY="..."         # For Gemini
+export ANTHROPIC_API_KEY="sk-..."   # For Anthropic
 ```
 
 ---

data/docs/architecture/adrs/004-hive-mind.md

@@ -420,7 +420,7 @@ htm = HTM.new(
 - [Multi-Agent Systems](https://en.wikipedia.org/wiki/Multi-agent_system)
 - [ADR-002: Two-Tier Memory](002-two-tier-memory.md)
 - [ADR-008: Robot Identification](008-robot-identification.md)
-- [Multi-Robot Guide](../../guides/multi-robot.md)
+- [Multi-Robot Guide](../../robots/multi-robot.md)
 
 ---
 

data/docs/architecture/adrs/008-robot-identification.md

@@ -608,7 +608,7 @@ htm = HTM.new(
 - [ULID Specification](https://github.com/ulid/spec)
 - [Robot Registry Pattern](https://martinfowler.com/eaaCatalog/registry.html)
 - [ADR-004: Hive Mind Architecture](004-hive-mind.md)
-- [Multi-Robot Guide](../../guides/multi-robot.md)
+- [Multi-Robot Guide](../../robots/multi-robot.md)
 
 ---
 

data/docs/architecture/index.md

@@ -29,7 +29,7 @@ HTM provides intelligent memory management through five core components that wor
   <!-- Embedding Service -->
   <rect x="550" y="200" width="200" height="120" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
   <text x="650" y="235" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Embedding Service</text>
-  <text x="650" y="255" text-anchor="middle" fill="#B0B0B0" font-size="11">Ollama/OpenAI</text>
+  <text x="650" y="255" text-anchor="middle" fill="#B0B0B0" font-size="11">Multi-Provider (RubyLLM)</text>
   <text x="650" y="275" text-anchor="middle" fill="#B0B0B0" font-size="11">Vector Embeddings</text>
   <text x="650" y="295" text-anchor="middle" fill="#B0B0B0" font-size="11">Semantic Search</text>
 
@@ -113,12 +113,14 @@ Durable PostgreSQL storage for permanent knowledge retention. All memories are s
 
 Generates vector embeddings for semantic search and manages token counting for memory management.
 
-**Supported Providers:**
+**Supported Providers (via RubyLLM):**
 
-- **Ollama** (default): Local embedding models (gpt-oss, nomic-embed-text, mxbai-embed-large)
+- **Ollama** (default): Local embedding models (nomic-embed-text, mxbai-embed-large)
 - **OpenAI**: text-embedding-3-small, text-embedding-3-large
-- **Cohere**: embed-english-v3.0, embed-multilingual-v3.0
-- **Local**: Transformers.js for browser/edge deployment
+- **Gemini**: text-embedding-004
+- **Azure**: Azure OpenAI Service
+- **Bedrock**: Amazon Titan, Cohere models
+- **DeepSeek**: DeepSeek embeddings
 
 **Related ADRs:** [ADR-003](adrs/003-ollama-embeddings.md)
 
@@ -272,8 +274,8 @@ stateDiagram-v2
 Explore detailed architecture documentation:
 
 - **[Detailed Architecture](overview.md)** - Deep dive into system architecture, data flows, and performance characteristics
-- **[Two-Tier Memory System](two-tier-memory.md)** - Working memory and long-term memory design, eviction strategies, and context assembly
-- **[Hive Mind Architecture](hive-mind.md)** - Multi-robot shared memory, robot identification, and cross-robot knowledge sharing
+- **[Two-Tier Memory System](../robots/two-tier-memory.md)** - Working memory and long-term memory design, eviction strategies, and context assembly
+- **[Hive Mind Architecture](../robots/hive-mind.md)** - Multi-robot shared memory, robot identification, and cross-robot knowledge sharing
 
 ## Technology Stack
 
@@ -284,7 +286,7 @@ Explore detailed architecture documentation:
 | **Time-Series** | TimescaleDB | Hypertable partitioning, compression |
 | **Vector Search** | pgvector | Semantic similarity (HNSW) |
 | **Full-Text** | pg_trgm | Fuzzy text matching |
-| **Embeddings** | Ollama/OpenAI | Vector generation |
+| **Embeddings** | RubyLLM (multi-provider) | Vector generation |
 | **Connection Pool** | connection_pool gem | Database connection management |
 | **Testing** | Minitest | Test framework |
 
@@ -318,7 +320,7 @@ Explore detailed architecture documentation:
 
 - **Working Memory**: Limited by process RAM (~1-2GB for 128K tokens)
 - **Database**: PostgreSQL scales to TBs with proper indexing
-- **Embeddings**: Local models (Ollama) bounded by GPU/CPU
+- **Embeddings**: Local models (Ollama) bounded by GPU/CPU; cloud providers scale independently
 
 ### Horizontal Scaling