swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/v3/configuration.rb

@@ -0,0 +1,490 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # Global configuration for V3 agents
+    #
+    # Provides sensible defaults that can be overridden per-agent
+    # via AgentDefinition attributes. Also forwards provider API keys
+    # to RubyLLM when {#apply_provider_config!} is called.
+    #
+    # @example Configure defaults
+    #   SwarmSDK::V3.configure do |config|
+    #     config.default_model = "claude-sonnet-4"
+    #     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+    #   end
+    #
+    # @example Reset to defaults
+    #   SwarmSDK::V3.reset_configuration!
+    class Configuration
+      # --- LLM defaults ---
+
+      # @return [String] Default LLM model for agents without explicit model
+      attr_accessor :default_model
+
+      # --- Provider API keys and endpoints ---
+
+      # @return [String, nil] OpenAI API key
+      attr_accessor :openai_api_key
+
+      # @return [String, nil] OpenAI custom API base URL
+      attr_accessor :openai_api_base
+
+      # @return [Boolean] Use "system" role instead of "developer" for OpenAI.
+      #   OpenAI's API uses "developer" by default, but some OpenAI-compatible
+      #   servers still require the traditional "system" role.
+      attr_accessor :openai_use_system_role
+
+      # @return [String, nil] Anthropic API key
+      attr_accessor :anthropic_api_key
+
+      # @return [String, nil] Anthropic custom API base URL
+      attr_accessor :anthropic_api_base
+
+      # @return [String, nil] Google Gemini API key
+      attr_accessor :gemini_api_key
+
+      # @return [String, nil] Gemini custom API base URL
+      attr_accessor :gemini_api_base
+
+      # @return [String, nil] AWS Bedrock access key
+      attr_accessor :bedrock_api_key
+
+      # @return [String, nil] AWS Bedrock secret key
+      attr_accessor :bedrock_secret_key
+
+      # @return [String, nil] AWS Bedrock region
+      attr_accessor :bedrock_region
+
+      # @return [String, nil] AWS Bedrock session token
+      attr_accessor :bedrock_session_token
+
+      # --- Background LLM configuration ---
+
+      # @return [String, nil] Model for background tasks (compression, summarization)
+      attr_accessor :background_model
+
+      # @return [String, nil] Provider for background model
+      attr_accessor :background_provider
+
+      # @return [String, nil] Custom API base URL for background model
+      attr_accessor :background_base_url
+
+      # @return [Hash] Custom HTTP headers for background model
+      attr_accessor :background_headers
+
+      # @return [Hash] Raw API body parameters for background model (temperature, etc.)
+      attr_accessor :background_parameters
+
+      # --- Subtask LLM configuration ---
+
+      # @return [String, nil] Model for subtask agents (nil = inherit from parent)
+      attr_accessor :subtask_model
+
+      # @return [String, nil] Provider for subtask model (nil = inherit from parent)
+      attr_accessor :subtask_provider
+
+      # @return [String, nil] Custom API base URL for subtask model
+      attr_accessor :subtask_base_url
+
+      # @return [Hash] Custom HTTP headers for subtask model
+      attr_accessor :subtask_headers
+
+      # @return [Hash] Raw API body parameters for subtask model (temperature, etc.)
+      attr_accessor :subtask_parameters
+
+      # --- Tool configuration ---
+
+      # @return [Array<Symbol>] Tools added to every agent (defaults to [])
+      attr_accessor :default_tools
+
+      # @return [Array<Symbol>, nil] Available tools (nil = all built-in tools)
+      attr_accessor :registered_tools
+
+      # @return [Integer, nil] Default max concurrent tool executions per agent.
+      #   When set, agents execute multiple tool calls from a single LLM response
+      #   concurrently using Async. nil disables concurrency (sequential execution).
+      attr_accessor :default_max_concurrent_tools
+
+      # --- Embedding configuration ---
+
+      # @return [String] Sentence-transformer model name for embeddings
+      attr_accessor :embedding_model
+
+      # @return [String, nil] Cache directory for downloaded embedding models
+      attr_accessor :embedding_cache_dir
+
+      # --- Memory defaults ---
+
+      # @return [Integer] Default number of recent turns to keep in short-term memory
+      attr_accessor :default_stm_turns
+
+      # @return [Integer] Default number of memory cards to retrieve per turn
+      attr_accessor :default_retrieval_top_k
+
+      # @return [Float] Default semantic weight for hybrid search (0.0-1.0)
+      attr_accessor :default_semantic_weight
+
+      # @return [Float] Default keyword weight for hybrid search (0.0-1.0)
+      attr_accessor :default_keyword_weight
+
+      # --- Exposure score weights ---
+
+      # @return [Float] Weight for frequency component in exposure score (α)
+      attr_accessor :exposure_frequency_weight
+
+      # @return [Float] Weight for recency component in exposure score (β)
+      attr_accessor :exposure_recency_weight
+
+      # @return [Float] Weight for dwell component in exposure score (γ)
+      attr_accessor :exposure_dwell_weight
+
+      # @return [Integer] Half-life for recency decay in seconds (default: 7 days)
+      attr_accessor :exposure_recency_half_life
+
+      # --- Memory lifecycle tuning ---
+      #
+      # These parameters control how often the agent runs background memory
+      # maintenance tasks (compression, consolidation, promotion) during
+      # conversation. Lower intervals mean more frequent maintenance.
+
+      # How often the agent compresses low-exposure memory cards.
+      # Compression advances cards through the L0→L4 ladder, reducing
+      # storage and context window usage. Lower values compress more
+      # aggressively (every 3 turns vs every 10).
+      #
+      # @return [Integer] Run compression every N turns (default: 5)
+      attr_accessor :compression_interval
+
+      # How often the agent runs consolidation (dedup, cluster updates,
+      # conflict detection). Consolidation merges near-duplicate cards,
+      # updates cluster rolling summaries, and creates `contradicts`
+      # edges between conflicting cards.
+      #
+      # @return [Integer] Run consolidation every N turns (default: 10)
+      attr_accessor :consolidation_interval
+
+      # Minimum access count before a compressed card (L1-L4) is promoted
+      # back toward L0. Promotion rebuilds richer text from graph neighbors
+      # and LLM, counterbalancing compression for frequently-accessed cards.
+      #
+      # @return [Integer] Min access count for promotion (default: 5)
+      attr_accessor :promotion_access_threshold
+
+      # --- Retrieval tuning ---
+      #
+      # These parameters control hybrid search: how semantic embeddings and
+      # BM25 keyword scores are combined, and how graph expansion works.
+
+      # Reciprocal Rank Fusion (RRF) constant. Controls how semantic and
+      # keyword search ranks are combined. Higher values flatten rank
+      # differences, giving later results more weight relative to top hits.
+      # Standard value from the RRF paper is 60.
+      #
+      # @return [Integer] RRF constant k (default: 60)
+      attr_accessor :rrf_k
+
+      # BM25 term frequency saturation parameter (k1). Controls how quickly
+      # repeated terms in a document contribute diminishing returns.
+      # Higher values give more weight to repeated terms. Standard
+      # Okapi BM25 default is 1.2.
+      #
+      # @return [Float] BM25 k1 parameter (default: 1.2)
+      attr_accessor :bm25_k1
+
+      # BM25 document length normalization parameter (b). Controls how
+      # much longer documents are penalized relative to average length.
+      # 0.0 = no penalty (all docs treated equally), 1.0 = full penalty.
+      # Standard Okapi BM25 default is 0.75.
+      #
+      # @return [Float] BM25 b parameter (default: 0.75)
+      attr_accessor :bm25_b
+
+      # Extra score boost per entity match in keyword search. When a
+      # query term appears in a card's entity list (not just its text),
+      # this boost is added to the BM25 score. Helps surface cards about
+      # specific named entities like "JWT", "PostgreSQL", etc.
+      #
+      # @return [Float] Entity match boost per match (default: 0.5)
+      attr_accessor :bm25_entity_boost
+
+      # Maximum 1-hop graph neighbors to expand per seed card during
+      # retrieval. After finding the top-k cards, the retriever traverses
+      # graph edges to pull in related cards. This caps how many neighbors
+      # any single card can contribute, preventing highly-connected cards
+      # from dominating results.
+      #
+      # @return [Integer] Max neighbors per seed (default: 4)
+      attr_accessor :max_neighbors_per_seed
+
+      # --- Context builder tuning ---
+      #
+      # These parameters control how the working context is assembled from
+      # memory tiers: retrieved cards, exploration sprinkle, and dedup.
+
+      # Number of low-exposure "anti-forgetting" cards sprinkled into each
+      # context build. These are rarely-accessed cards with some relevance
+      # to the query, included to prevent permanent forgetting. Set to 0
+      # to disable exploration entirely.
+      #
+      # @return [Integer] Exploration sprinkle size (default: 2)
+      attr_accessor :exploration_sample_size
+
+      # Minimum embedding similarity between the query and an exploration
+      # candidate card. Lower values include more diverse (less relevant)
+      # cards in the sprinkle. Higher values restrict to cards that are
+      # at least loosely relevant.
+      #
+      # @return [Float] Min similarity for exploration (default: 0.15)
+      attr_accessor :exploration_min_similarity
+
+      # Similarity threshold above which cards are considered near-duplicates
+      # during context assembly. When two cards in the working context have
+      # similarity above this threshold, the duplicate is removed. Uses the
+      # adapter's {Adapters::Base#similarity} method.
+      #
+      # @return [Float] Dedup threshold (default: 0.92)
+      attr_accessor :dedup_similarity_threshold
+
+      # @return [Boolean] Default associative memory setting for agents.
+      #   When enabled, exploration cards are labeled distinctly and guidance
+      #   is injected encouraging the LLM to naturally surface tangential memories.
+      attr_accessor :default_associative_memory
+
+      # --- Ingestion tuning ---
+      #
+      # These parameters control how new conversation turns are processed
+      # into memory cards, entities, and graph edges.
+
+      # Minimum embedding similarity for creating `same_entity` edges
+      # between new cards and existing cards during cross-turn entity
+      # linking. Lower values create more connections but may produce
+      # false positives.
+      #
+      # @return [Float] Min similarity for entity edges (default: 0.3)
+      attr_accessor :entity_edge_min_similarity
+
+      # Maximum number of existing cards to scan when creating cross-turn
+      # entity edges. Limits the O(n*m) scan to prevent slowdowns as the
+      # memory store grows. Scans the most recent cards first.
+      #
+      # @return [Integer] Cross-turn edge scan limit (default: 50)
+      attr_accessor :cross_turn_edge_scan_limit
+
+      # --- Consolidation tuning ---
+      #
+      # These parameters control periodic maintenance: dedup, merging,
+      # cluster updates, and conflict detection.
+
+      # Similarity threshold for detecting duplicate cards during
+      # consolidation. Cards with vector similarity above this threshold
+      # are merged into a canonical card. Lower values merge more
+      # aggressively but risk merging distinct-but-similar concepts.
+      #
+      # @return [Float] Consolidator dedup threshold (default: 0.92)
+      attr_accessor :consolidator_dedup_threshold
+
+      # Minimum similarity for considering two cards as potential conflicts.
+      # The conflict band is: conflict_threshold <= similarity < dedup_threshold.
+      # Raise to reduce false positives; lower to catch subtler contradictions.
+      #
+      # @return [Float] Min similarity for conflict detection (default: 0.75)
+      attr_accessor :consolidator_conflict_threshold
+
+      # --- MCP settings ---
+
+      # @return [Boolean] Global SSL verification for MCP HTTP connections (default: true).
+      #   OpenSSL 3.6 enforces CRL checking by default, which breaks most HTTPS MCP
+      #   endpoints. Set to false to disable verification for local development.
+      #   Can be overridden per-server via ServerDefinition's ssl_verify option.
+      attr_accessor :mcp_ssl_verify
+
+      # --- Subtask limits ---
+
+      # @return [Integer] Maximum nesting depth for SubTask spawning (default: 1)
+      attr_accessor :max_subtask_depth
+
+      # --- Tool limits ---
+
+      # @return [Integer] Maximum output character limit for tool results
+      attr_accessor :output_character_limit
+
+      # @return [Integer] Maximum line character limit for Read tool
+      attr_accessor :line_character_limit
+
+      # @return [Integer] Default line limit for Read tool
+      attr_accessor :read_line_limit
+
+      # @return [Integer] Maximum results from Glob tool
+      attr_accessor :glob_result_limit
+
+      # @return [Integer] Default Bash command timeout in milliseconds
+      attr_accessor :bash_command_timeout
+
+      # @return [Integer] Maximum Bash command timeout in milliseconds
+      attr_accessor :bash_command_max_timeout
+
+      def initialize
+        reset!
+      end
+
+      # Reset all configuration to defaults
+      #
+      # @return [void]
+      def reset!
+        # LLM defaults
+        @default_model = "claude-sonnet-4"
+
+        # Provider keys
+        @openai_api_key = nil
+        @openai_api_base = nil
+        @openai_use_system_role = false
+        @anthropic_api_key = nil
+        @anthropic_api_base = nil
+        @gemini_api_key = nil
+        @gemini_api_base = nil
+        @bedrock_api_key = nil
+        @bedrock_secret_key = nil
+        @bedrock_region = nil
+        @bedrock_session_token = nil
+
+        # Background LLM
+        @background_model = nil
+        @background_provider = nil
+        @background_base_url = nil
+        @background_headers = {}
+        @background_parameters = {}
+
+        # Subtask LLM
+        @subtask_model = nil
+        @subtask_provider = nil
+        @subtask_base_url = nil
+        @subtask_headers = {}
+        @subtask_parameters = {}
+
+        # Tools
+        @default_tools = []
+        @registered_tools = nil
+        @default_max_concurrent_tools = nil
+
+        # Embedding
+        @embedding_model = "sentence-transformers/multi-qa-MiniLM-L6-cos-v1"
+        @embedding_cache_dir = nil
+
+        # Memory retrieval (optimized via manual-memory-evals.md Phases 1-2)
+        @default_stm_turns = 8
+        @default_retrieval_top_k = 10  # was 15 — less noise, better precision
+        @default_semantic_weight = 0.4 # was 0.5 — slightly keyword-leaning for entity recall
+        @default_keyword_weight = 0.6  # was 0.5 — better for named entities and numbers
+
+        # Exposure score weights (additive: α·frequency + β·recency + γ·dwell)
+        @exposure_frequency_weight = 0.4
+        @exposure_recency_weight = 0.4
+        @exposure_dwell_weight = 0.2
+        @exposure_recency_half_life = 7 * 24 * 3600 # 7 days in seconds
+
+        # Memory lifecycle
+        @compression_interval = 5
+        @consolidation_interval = 10
+        @promotion_access_threshold = 5
+
+        # Retrieval (optimized via manual-memory-evals.md Phases 3-4)
+        @rrf_k = 120              # was 60 — flatter ranking gives more diverse results
+        @bm25_k1 = 1.2
+        @bm25_b = 1.0             # was 0.75 — full length normalization for short memory cards
+        @bm25_entity_boost = 0.5
+        @max_neighbors_per_seed = 4
+
+        # Context builder
+        @exploration_sample_size = 2
+        @exploration_min_similarity = 0.15
+        @dedup_similarity_threshold = 0.92
+        @default_associative_memory = false
+
+        # Ingestion
+        @entity_edge_min_similarity = 0.3
+        @cross_turn_edge_scan_limit = 50
+
+        # Consolidation
+        @consolidator_dedup_threshold = 0.92
+        @consolidator_conflict_threshold = 0.75
+
+        # MCP
+        @mcp_ssl_verify = true
+
+        # Subtask limits
+        @max_subtask_depth = 1
+
+        # Tool limits
+        @output_character_limit = 30_000
+        @line_character_limit = 2_000
+        @read_line_limit = 2_000
+        @glob_result_limit = 500
+        @bash_command_timeout = 120_000
+        @bash_command_max_timeout = 600_000
+      end
+
+      # Forward provider API keys and settings to RubyLLM
+      #
+      # Call this after setting provider keys to configure RubyLLM.
+      # Only sets values that are non-nil.
+      #
+      # @return [void]
+      #
+      # @example
+      #   config = SwarmSDK::V3::Configuration.instance
+      #   config.anthropic_api_key = "sk-ant-..."
+      #   config.apply_provider_config!
+      def apply_provider_config!
+        RubyLLM.configure do |c|
+          c.openai_api_key = @openai_api_key if @openai_api_key
+          c.openai_api_base = @openai_api_base if @openai_api_base
+          c.openai_use_system_role = @openai_use_system_role
+          c.anthropic_api_key = @anthropic_api_key if @anthropic_api_key
+          c.anthropic_api_base = @anthropic_api_base if @anthropic_api_base
+          c.gemini_api_key = @gemini_api_key if @gemini_api_key
+          c.gemini_api_base = @gemini_api_base if @gemini_api_base
+          c.bedrock_api_key = @bedrock_api_key if @bedrock_api_key
+          c.bedrock_secret_key = @bedrock_secret_key if @bedrock_secret_key
+          c.bedrock_region = @bedrock_region if @bedrock_region
+          c.bedrock_session_token = @bedrock_session_token if @bedrock_session_token
+        end
+      end
+
+      class << self
+        # Get the global configuration instance
+        #
+        # @return [Configuration]
+        def instance
+          @instance ||= new
+        end
+
+        # Configure global settings
+        #
+        # Yields the configuration instance, then applies provider settings
+        # to RubyLLM automatically.
+        #
+        # @yield [Configuration] The configuration instance
+        # @return [Configuration]
+        #
+        # @example
+        #   SwarmSDK::V3::Configuration.configure do |config|
+        #     config.default_model = "claude-sonnet-4"
+        #     config.anthropic_api_key = "sk-ant-..."
+        #   end
+        def configure
+          yield(instance) if block_given?
+          instance.apply_provider_config!
+          instance
+        end
+
+        # Reset configuration to defaults
+        #
+        # @return [void]
+        def reset!
+          instance.reset!
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/debug_log.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # Lightweight debug logging for V3 agents
+    #
+    # Activated by setting the `DEBUG` or `SWARM_DEBUG` environment variable.
+    # Outputs timestamped debug messages to stderr with timing information
+    # for performance profiling.
+    #
+    # @example Enable debug logging
+    #   DEBUG=1 bundle exec ruby my_script.rb
+    #
+    # @example Use in code
+    #   DebugLog.log("retriever", "semantic search found 15 cards")
+    #   DebugLog.time("retriever", "keyword_search") { keyword_search(query) }
+    module DebugLog
+      class << self
+        # Whether debug logging is enabled
+        #
+        # @return [Boolean]
+        def enabled?
+          return @enabled if defined?(@enabled)
+
+          @enabled = ENV["DEBUG"] == "1" || ENV["SWARM_DEBUG"] == "1"
+        end
+
+        # Log a debug message to stderr
+        #
+        # @param component [String] Component name (e.g., "retriever", "ingestion")
+        # @param message [String] Debug message
+        # @return [void]
+        #
+        # @example
+        #   DebugLog.log("agent", "initializing memory store")
+        def log(component, message)
+          return unless enabled?
+
+          timestamp = Time.now.strftime("%H:%M:%S.%L")
+          warn("[DEBUG #{timestamp}] [#{component}] #{message}")
+        end
+
+        # Execute a block and log its execution time
+        #
+        # @param component [String] Component name
+        # @param label [String] Operation label
+        # @yield Block to time
+        # @return [Object] Block return value
+        #
+        # @example
+        #   result = DebugLog.time("retriever", "semantic_search") do
+        #     adapter.vector_search(embedding, top_k: 30)
+        #   end
+        def time(component, label)
+          unless enabled?
+            return yield
+          end
+
+          log(component, "#{label} START")
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = yield
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+          log(component, "#{label} DONE (#{format_duration(elapsed)})")
+
+          result
+        end
+
+        private
+
+        # Format duration in human-readable form
+        #
+        # @param seconds [Float] Duration in seconds
+        # @return [String] Formatted duration
+        def format_duration(seconds)
+          if seconds < 0.001
+            "#{(seconds * 1_000_000).round}us"
+          elsif seconds < 1.0
+            "#{(seconds * 1_000).round(1)}ms"
+          else
+            "#{seconds.round(2)}s"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/event_stream.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # EventStream provides fiber-local event emission for V3 agents
+    #
+    # Thread-safe and fiber-safe event system using Fiber storage.
+    # Each fiber gets its own emitter instance, preventing cross-fiber contamination.
+    #
+    # Two emitter slots are available:
+    # - **Global emitter** (via `emitter=`): For logging/monitoring across all operations
+    # - **Block emitter** (via `block_emitter=`): For per-call event handling in `ask()` blocks
+    #
+    # @example Emit an event
+    #   EventStream.emit(type: "agent_start", agent: :backend, model: "claude-sonnet-4")
+    #
+    # @example Subscribe to events globally
+    #   EventStream.emitter = ->(event) { puts event.inspect }
+    #   agent.ask("Hello")
+    #   EventStream.reset!
+    #
+    # @example Receive events via block (set internally by Agent#ask)
+    #   agent.ask("Hello") do |event|
+    #     case event[:type]
+    #     when "content_chunk"
+    #       print event[:content]
+    #     end
+    #   end
+    module EventStream
+      FIBER_KEY = :v3_event_stream_emitter
+      BLOCK_KEY = :v3_event_stream_block_emitter
+
+      class << self
+        # Emit a structured event
+        #
+        # Adds timestamp and forwards to both the global emitter and block emitter.
+        # No-op if no emitters are configured.
+        #
+        # @param data [Hash] Event data (type, agent, and event-specific fields)
+        # @return [void]
+        #
+        # @example
+        #   EventStream.emit(
+        #     type: "tool_call",
+        #     agent: :backend,
+        #     tool: "Read",
+        #     arguments: { file_path: "src/main.rb" },
+        #   )
+        def emit(**data)
+          global = Fiber[FIBER_KEY]
+          block = Fiber[BLOCK_KEY]
+          return if global.nil? && block.nil?
+
+          entry = data.merge(timestamp: Time.now.utc.iso8601(6)).compact
+
+          call_emitter(global, entry)
+          call_emitter(block, entry)
+        end
+
+        # Set the global emitter for the current fiber
+        #
+        # Use this for logging, monitoring, and analytics that should
+        # receive all events regardless of where they originate.
+        #
+        # @param callable [#call] Object responding to call(Hash)
+        # @return [void]
+        def emitter=(callable)
+          Fiber[FIBER_KEY] = callable
+        end
+
+        # Get the current global emitter
+        #
+        # @return [#call, nil] Current emitter or nil
+        def emitter
+          Fiber[FIBER_KEY]
+        end
+
+        # Set the block emitter for the current fiber
+        #
+        # Used internally by Agent#ask to wire the user's block to receive events.
+        # Not typically called directly by SDK users.
+        #
+        # @param callable [#call, nil] Object responding to call(Hash), or nil to clear
+        # @return [void]
+        def block_emitter=(callable)
+          Fiber[BLOCK_KEY] = callable
+        end
+
+        # Get the current block emitter
+        #
+        # @return [#call, nil] Current block emitter or nil
+        def block_emitter
+          Fiber[BLOCK_KEY]
+        end
+
+        # Reset both emitters for the current fiber
+        #
+        # @return [void]
+        def reset!
+          Fiber[FIBER_KEY] = nil
+          Fiber[BLOCK_KEY] = nil
+        end
+
+        # Check if any emitter is configured
+        #
+        # @return [Boolean]
+        def enabled?
+          !Fiber[FIBER_KEY].nil? || !Fiber[BLOCK_KEY].nil?
+        end
+
+        private
+
+        # Call an emitter with error handling
+        #
+        # @param emitter [#call, nil] Emitter to call
+        # @param entry [Hash] Event data to pass
+        # @return [void]
+        def call_emitter(emitter, entry)
+          return unless emitter
+
+          emitter.call(entry)
+        rescue StandardError => e
+          # Never let event emission break agent execution, but log to stderr
+          # so failures are visible during debugging rather than silently lost.
+          warn("[SwarmSDK::V3::EventStream] Emitter error: #{e.class}: #{e.message}")
+        end
+      end
+    end
+  end
+end