htm 0.0.14 → 0.0.15

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

@@ -0,0 +1,108 @@
+# Class: HTM::SqlBuilder
+**Inherits:** Object
+    
+
+SQL building utilities for constructing safe, parameterized queries
+
+Provides class methods for building SQL conditions for:
+*   Timeframe filtering (single range or multiple ranges)
+*   Metadata filtering (JSONB containment)
+*   Embedding sanitization and padding (SQL injection prevention)
+*   LIKE pattern sanitization (wildcard injection prevention)
+
+All methods use proper escaping and parameterization to prevent SQL injection.
+
+
+**`@example`**
+```ruby
+HTM::SqlBuilder.timeframe_condition(1.week.ago..Time.now)
+# => "(created_at BETWEEN '2024-01-01' AND '2024-01-08')"
+```
+**`@example`**
+```ruby
+HTM::SqlBuilder.metadata_condition({ priority: "high" })
+# => "(metadata @> '{\"priority\":\"high\"}'::jsonb)"
+```
+**`@example`**
+```ruby
+HTM::SqlBuilder.sanitize_embedding([0.1, 0.2, 0.3])
+# => "[0.1,0.2,0.3]"
+```
+**`@example`**
+```ruby
+HTM::SqlBuilder.sanitize_like_pattern("test%pattern")
+# => "test\\%pattern"
+```
+# Class Methods
+## apply_metadata(scope , metadata , column: "metadata") {: #method-c-apply_metadata }
+Apply metadata filter to ActiveRecord scope
+**`@param`** [ActiveRecord::Relation] Base scope
+
+**`@param`** [Hash] Metadata to filter by
+
+**`@param`** [String] Column name (default: "metadata")
+
+**`@return`** [ActiveRecord::Relation] Scoped query
+
+## apply_timeframe(scope , timeframe , column: :created_at) {: #method-c-apply_timeframe }
+Apply timeframe filter to ActiveRecord scope
+**`@param`** [ActiveRecord::Relation] Base scope
+
+**`@param`** [nil, Range, Array<Range>] Time range(s)
+
+**`@param`** [Symbol] Column name (default: :created_at)
+
+**`@return`** [ActiveRecord::Relation] Scoped query
+
+## metadata_condition(metadata , table_alias: nil, column: "metadata") {: #method-c-metadata_condition }
+Build SQL condition for metadata filtering (JSONB containment)
+**`@param`** [Hash] Metadata to filter by
+
+**`@param`** [String, nil] Table alias (default: none)
+
+**`@param`** [String] Column name (default: "metadata")
+
+**`@return`** [String, nil] SQL condition or nil for no filter
+
+## pad_embedding(embedding , target_dimension: MAX_EMBEDDING_DIMENSION) {: #method-c-pad_embedding }
+Pad embedding to target dimension
+
+Pads embedding with zeros to reach the target dimension for pgvector
+compatibility.
+**`@param`** [Array<Numeric>] Embedding vector
+
+**`@param`** [Integer] Target dimension (default: MAX_EMBEDDING_DIMENSION)
+
+**`@return`** [Array<Numeric>] Padded embedding
+
+## sanitize_embedding(embedding ) {: #method-c-sanitize_embedding }
+Sanitize embedding for SQL use
+
+Validates that all values are numeric and converts to safe PostgreSQL vector
+format. This prevents SQL injection by ensuring only valid numeric values are
+included.
+**`@param`** [Array<Numeric>] Embedding vector
+
+**`@raise`** [ArgumentError] If embedding contains non-numeric values
+
+**`@return`** [String] Sanitized vector string for PostgreSQL (e.g., "[0.1,0.2,0.3]")
+
+## sanitize_like_pattern(pattern ) {: #method-c-sanitize_like_pattern }
+Sanitize a string for use in SQL LIKE patterns
+
+Escapes SQL LIKE wildcards (% and _) to prevent pattern injection.
+**`@param`** [String] Pattern to sanitize
+
+**`@return`** [String] Sanitized pattern safe for LIKE queries
+
+## timeframe_condition(timeframe , table_alias: nil, column: "created_at") {: #method-c-timeframe_condition }
+Build SQL condition for timeframe filtering
+**`@param`** [nil, Range, Array<Range>] Time range(s)
+
+**`@param`** [String, nil] Table alias (default: none)
+
+**`@param`** [String] Column name (default: "created_at")
+
+**`@return`** [String, nil] SQL condition or nil for no filter
+
+

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

@@ -29,6 +29,10 @@ Extract tags with validation and processing
 
 **`@return`** [Array<String>] Validated tag names
 
+## max_depth() {: #method-c-max_depth }
+Maximum tag hierarchy depth (configurable, default 4)
+**`@return`** [Integer] Max depth (3 colons max by default)
+
 ## parse_hierarchy(tag ) {: #method-c-parse_hierarchy }
 Parse hierarchical structure of a tag
 **`@param`** [String] Hierarchical tag (e.g., "ai:llm:embedding")

data/docs/api/yard/HTM/Telemetry/NullInstrument.md

@@ -0,0 +1,13 @@
+# Class: HTM::Telemetry::NullInstrument
+**Inherits:** Object
+    
+**Includes:** Singleton
+  
+
+Null instrument that accepts but ignores all metric operations
+
+
+
+# Instance Methods
+## add() {: #method-i-add }
+## record() {: #method-i-record }

data/docs/api/yard/HTM/Telemetry/NullMeter.md

@@ -0,0 +1,15 @@
+# Class: HTM::Telemetry::NullMeter
+**Inherits:** Object
+    
+**Includes:** Singleton
+  
+
+Null meter that creates null instruments Used when telemetry is disabled or
+SDK unavailable
+
+
+
+# Instance Methods
+## create_counter() {: #method-i-create_counter }
+## create_histogram() {: #method-i-create_histogram }
+## create_up_down_counter() {: #method-i-create_up_down_counter }

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

@@ -0,0 +1,109 @@
+# Module: HTM::Telemetry
+    
+
+OpenTelemetry-based observability for HTM
+
+Provides opt-in metrics collection with zero overhead when disabled. Uses the
+null object pattern - when telemetry is disabled or the SDK is not available,
+all metric operations are no-ops.
+
+**`@see`** [] for full implementation details
+
+
+**`@example`**
+```ruby
+HTM.configure do |config|
+  config.telemetry_enabled = true
+end
+```
+**`@example`**
+```ruby
+# Export to OTLP endpoint
+ENV['OTEL_METRICS_EXPORTER'] = 'otlp'
+ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'
+```
+# Class Methods
+## cache_operations() {: #method-c-cache_operations }
+Counter for cache operations (hits, misses)
+**`@return`** [OpenTelemetry::Metrics::Counter, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.cache_operations.add(1, attributes: { 'operation' => 'hit' })
+```
+## embedding_latency() {: #method-c-embedding_latency }
+Histogram for embedding generation latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.embedding_latency.record(145, attributes: { 'provider' => 'ollama', 'status' => 'success' })
+```
+## enabled?() {: #method-c-enabled? }
+Check if telemetry is enabled and SDK is available
+**`@return`** [Boolean] true if telemetry should be active
+
+## job_counter() {: #method-c-job_counter }
+Counter for job execution (enqueued, completed, failed)
+**`@return`** [OpenTelemetry::Metrics::Counter, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.job_counter.add(1, attributes: { 'job' => 'embedding', 'status' => 'success' })
+```
+## measure(histogram , attributes {}) {: #method-c-measure }
+Measure execution time of a block and record to a histogram
+**`@param`** [OpenTelemetry::Metrics::Histogram, NullInstrument] The histogram to record to
+
+**`@param`** [Hash] Attributes to attach to the measurement
+
+**`@return`** [Object] The result of the block
+
+**`@yield`** [] The block to measure
+
+
+**`@example`**
+```ruby
+result = Telemetry.measure(Telemetry.embedding_latency, 'provider' => 'ollama') do
+  generate_embedding(text)
+end
+```
+## meter() {: #method-c-meter }
+Get the meter for creating instruments
+**`@return`** [OpenTelemetry::Metrics::Meter, NullMeter] Real or null meter
+
+## reset!() {: #method-c-reset! }
+Reset telemetry state (for testing)
+**`@return`** [void] 
+
+## sdk_available?() {: #method-c-sdk_available? }
+Check if OpenTelemetry SDK is installed
+**`@return`** [Boolean] true if SDK can be loaded
+
+## search_latency() {: #method-c-search_latency }
+Histogram for search operation latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.search_latency.record(50, attributes: { 'strategy' => 'vector' })
+```
+## setup() {: #method-c-setup }
+Initialize OpenTelemetry SDK
+
+Called automatically when telemetry is enabled. Safe to call multiple times.
+**`@return`** [void] 
+
+## tag_latency() {: #method-c-tag_latency }
+Histogram for tag extraction latency
+**`@return`** [OpenTelemetry::Metrics::Histogram, NullInstrument] 
+
+
+**`@example`**
+```ruby
+Telemetry.tag_latency.record(250, attributes: { 'provider' => 'ollama', 'status' => 'success' })
+```

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

@@ -0,0 +1,176 @@
+# Class: HTM::WorkingMemoryChannel
+**Inherits:** Object
+    
+
+Provides real-time synchronization of working memory changes across multiple
+robots using PostgreSQL LISTEN/NOTIFY pub/sub mechanism.
+
+This class enables distributed robots to maintain synchronized working memory
+by broadcasting change notifications through PostgreSQL channels. When one
+robot adds, evicts, or clears working memory, all other robots in the group
+receive immediate notification.
+
+**`@see`** [] Higher-level coordination using this channel
+
+
+**`@example`**
+```ruby
+channel = HTM::WorkingMemoryChannel.new('support-team', db_config)
+
+# Subscribe to changes
+channel.on_change do |event, node_id, robot_id|
+  case event
+  when :added   then puts "Node #{node_id} added by robot #{robot_id}"
+  when :evicted then puts "Node #{node_id} evicted by robot #{robot_id}"
+  when :cleared then puts "Working memory cleared by robot #{robot_id}"
+  end
+end
+
+# Start listening in background thread
+channel.start_listening
+
+# Publish a change
+channel.notify(:added, node_id: 123, robot_id: 456)
+
+# Cleanup when done
+channel.stop_listening
+```
+# Attributes
+## notifications_received[RW] {: #attribute-i-notifications_received }
+Number of notifications received since channel was created
+
+**`@return`** [Integer] 
+
+
+# Instance Methods
+## channel_name() {: #method-i-channel_name }
+Returns the PostgreSQL channel name used for notifications.
+
+The channel name is derived from the group name with a prefix and sanitization
+of special characters.
+
+**`@return`** [String] The PostgreSQL LISTEN/NOTIFY channel name
+
+
+**`@example`**
+```ruby
+channel = HTM::WorkingMemoryChannel.new('my-group', db_config)
+channel.channel_name  # => "htm_wm_my_group"
+```
+## initialize(group_name, db_config) {: #method-i-initialize }
+Creates a new working memory channel for a robot group.
+
+The channel name is derived from the group name with non-alphanumeric
+characters replaced by underscores to ensure PostgreSQL compatibility.
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@option`** [] 
+
+**`@param`** [String] Name of the robot group (used to create unique channel)
+
+**`@param`** [Hash] PostgreSQL connection configuration hash
+
+**`@return`** [WorkingMemoryChannel] a new instance of WorkingMemoryChannel
+
+
+**`@example`**
+```ruby
+db_config = { host: 'localhost', port: 5432, dbname: 'htm_dev', user: 'postgres' }
+channel = HTM::WorkingMemoryChannel.new('customer-support', db_config)
+```
+## listening?() {: #method-i-listening? }
+Checks if the listener thread is currently active.
+
+**`@return`** [Boolean] true if listening for notifications, false otherwise
+
+
+**`@example`**
+```ruby
+channel.start_listening
+channel.listening?  # => true
+channel.stop_listening
+channel.listening?  # => false
+```
+## notify(event, node_id:, robot_id:) {: #method-i-notify }
+Broadcasts a working memory change notification to all listeners.
+
+Uses PostgreSQL's pg_notify function to send a JSON payload containing the
+event type, affected node ID, originating robot ID, and timestamp.
+
+**`@param`** [Symbol] Type of change (:added, :evicted, or :cleared)
+
+**`@param`** [Integer, nil] ID of the affected node (nil for :cleared events)
+
+**`@param`** [Integer] ID of the robot that triggered the change
+
+**`@return`** [void] 
+
+
+**`@example`**
+```ruby
+channel.notify(:added, node_id: 123, robot_id: 1)
+```
+**`@example`**
+```ruby
+channel.notify(:cleared, node_id: nil, robot_id: 1)
+```
+## on_change(&callback) {: #method-i-on_change }
+Registers a callback to be invoked when working memory changes occur.
+
+Multiple callbacks can be registered; all will be called for each event.
+Callbacks are invoked synchronously within the listener thread.
+
+**`@return`** [void] 
+
+**`@yield`** [event, node_id, robot_id] Block called for each notification
+
+**`@yieldparam`** [Symbol] Type of change (:added, :evicted, or :cleared)
+
+**`@yieldparam`** [Integer, nil] ID of the affected node
+
+**`@yieldparam`** [Integer] ID of the robot that triggered the change
+
+
+**`@example`**
+```ruby
+channel.on_change do |event, node_id, robot_id|
+  puts "Received #{event} event for node #{node_id}"
+end
+```
+## start_listening() {: #method-i-start_listening }
+Starts listening for notifications in a background thread.
+
+Creates a dedicated PostgreSQL connection that uses LISTEN to receive
+notifications. The thread polls every 0.5 seconds, allowing for clean shutdown
+via {#stop_listening}.
+
+**`@return`** [Thread] The background listener thread
+
+
+**`@example`**
+```ruby
+thread = channel.start_listening
+puts "Listening: #{channel.listening?}"  # => true
+```
+## stop_listening() {: #method-i-stop_listening }
+Stops the background listener thread.
+
+Signals the listener to stop, waits up to 0.5 seconds for clean exit, then
+forcefully terminates if still running. The PostgreSQL connection is closed
+automatically.
+
+**`@return`** [void] 
+
+
+**`@example`**
+```ruby
+channel.stop_listening
+puts "Listening: #{channel.listening?}"  # => false
+```

data/docs/api/yard/HTM.md

@@ -2,30 +2,10 @@
 **Inherits:** Object
     
 
-HTM (Hierarchical Temporal Memory) error classes
+examples/robot_groups/lib/htm/working_memory_channel.rb frozen_string_literal:
+true
 
-All HTM errors inherit from HTM::Error, allowing you to catch all HTM-related
-errors with a single rescue clause.
 
-
-**`@example`**
-```ruby
-begin
-  htm.remember("some content")
-rescue HTM::Error => e
-  logger.error "HTM error: #{e.message}"
-end
-```
-**`@example`**
-```ruby
-begin
-  htm.forget(node_id, soft: false)
-rescue HTM::NotFoundError
-  puts "Node not found"
-rescue HTM::ValidationError
-  puts "Invalid input"
-end
-```
 # Class Methods
 ## configure() {: #method-c-configure }
 Configure HTM
@@ -57,6 +37,12 @@ Generate embedding using EmbeddingService
 
 **`@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
@@ -75,4 +61,6 @@ Reset configuration to defaults
 ## configuration[RW] {: #attribute-c-configuration }
 Get current configuration
 
-**`@return`** [HTM::Configuration]
+**`@return`** [HTM::Configuration] 
+
+