weft-sdk 0.7.0 → 0.9.0

data/lib/weft/generated/models/search_response.rb

@@ -1,9 +1,9 @@
 =begin
 #Weft API
 
-#The Weft API is the buyer-runtime surface that powers the `weft` CLI, the hosted MCP server (`weft.network/mcp`), and any third-party agent that wants to discover and pay for paid resources on Weft. v1 covers five buyer concerns:    1. Account onboarding (`/api/v1/auth/*`, `/api/v1/me`)   2. CLI authentication (`/api/v1/api_keys`)   3. Wallet visibility (`/api/v1/balance`)   4. Discovery (`/api/v1/search`)   5. Paid execution (`/api/v1/fetch`)   6. Purchase history (`/api/v1/payments`)  Seller-side concerns (agent management, payout analytics, webhook delivery, the public storefront for `data_api` resources) live in the dashboard and are intentionally not documented here. They will be split out into a separate, dashboard-scoped spec when they need to be SDK-consumable.  All errors share the envelope defined by `ErrorResponse`, except the buyer-runtime endpoints (`/search`, `/fetch`) which use bespoke envelopes carrying additional context — see `SearchErrorResponse` and `FetchErrorResponse`. 
+#The Weft API is the buyer-runtime surface that powers the `weft` CLI, the hosted MCP server (`weft.network/mcp`), and any third-party agent that wants to discover and pay for paid resources on Weft. v1 covers five buyer concerns:    1. Account onboarding (`/api/v1/auth/*`, `/api/v1/me`)   2. CLI authentication (`/api/v1/api_keys`)   3. Wallet visibility (`/api/v1/balance`)   4. Discovery (`/api/v1/search`)   5. Paid execution (`/api/v1/fetch`)   6. Purchase history (`/api/v1/purchases`)  Seller-side concerns (agent management, payout analytics, webhook delivery, the public storefront for `data_api` resources) live in the dashboard and are intentionally not documented here. They will be split out into a separate, dashboard-scoped spec when they need to be SDK-consumable.  All errors share the envelope defined by `ErrorResponse`, except the buyer-runtime endpoints (`/search`, `/fetch`) which use bespoke envelopes carrying additional context — see `SearchErrorResponse` and `FetchErrorResponse`.
 
-The version of the OpenAPI document: 0.7.0
+The version of the OpenAPI document: 0.9.0
 
 Generated by: https://openapi-generator.tech
 Generator version: 7.19.0
@@ -14,29 +14,104 @@ require 'date'
 require 'time'
 
 module Weft
-  # Spec-11 search envelope. `paid_usd`, `tx_hash`, and `artifact_id` are reserved for a later release that adds per-call billing and artifact persistence; they are always `null` in v1. `_mock: true` is set only by the mock backend.  Result rows: the mock backend (`SEARCH_BACKEND=mock`, the default while the real index is unshipped) emits the rich, SDK-facing `SearchResult` shape. The legacy `platform` backend proxies the upstream search service and passes its result rows through verbatim — Weft does not own or reshape that payload, so those rows are typed as a free-form object. SDK clients on v1 should treat unknown row shapes defensively until the platform backend is retrofitted to the `SearchResult` contract (specs 07 + 10).  Because the `PlatformSearchResult` branch is intentionally permissive (free-form, to admit the un-owned platform rows), the `anyOf` is satisfied by any object — so the committee response-validation gate does NOT strictly validate result-row shapes; the rich `SearchResult` contract is instead guarded by the `/api/v1/search` request spec. 
+  # The weft-search-platform `POST /v1/search` response envelope. The mock backend emits the same shape and adds `_mock: true`.
   class SearchResponse < ApiModelBase
-    attr_accessor :results
+    # Opaque trace id for the served query, matching the platform `query_trace_id` — and the `search_id` that re-reads it. Deliberately the same id rather than a second handle: one serve, one name.
+    attr_accessor :query_trace_id
+
+    attr_accessor :query
+
+    # Which view this response carries, echoing the requested format. `json` populates `results` and leaves `markdown` null; `markdown` populates `markdown` and leaves `results` empty. Exactly one is populated per response, never both — returning both eagerly would double the payload.
+    attr_accessor :format
+
+    # The flat comparison table, when `format` is `markdown`; null otherwise. Rendered deterministically from the same stored result the `json` view returns, so the two views of one search can never disagree.
+    attr_accessor :markdown
+
+    # How many `(Provider + Capability)` results the search produced. Read THIS, not `results.length`, for the count: on a `markdown` response `results` is empty by design, so `result_count > 0` with an empty `results` is a rendered table while `result_count == 0` is a genuine zero-result.
+    attr_accessor :result_count
+
+    # `live` for a fresh serve; `snapshot` for an immutable replay of a completed search. A re-read is a snapshot and says so — read it with `as_of` and `stale`.
+    attr_accessor :served_from
+
+    # When the results were produced. Now on a `live` serve; on a `snapshot` the ORIGINAL serve time, because a replay returns exactly what was paid for, not current truth.
+    attr_accessor :as_of
+
+    # Whether the active search index has changed since these results were produced. `true` does not mean the results are wrong — it means they are a snapshot of an index that has since moved. Always `false` on a `live` serve.
+    attr_accessor :stale
+
+    # How payment works across the catalog, stated once for the whole response rather than repeated in every endpoint's usage instructions.
+    attr_accessor :payment_note
 
-    # Always `null` in v1.
-    attr_accessor :paid_usd
+    # The `FilterSpec` actually applied to recall, echoed back so the caller sees exactly what constrained the results. In the current contract this is the caller's `filters` verbatim (empty object when none were sent).
+    attr_accessor :applied_filters
 
-    # Always `null` in v1.
-    attr_accessor :tx_hash
+    # Origin of `applied_filters`; always `CALLER`.
+    attr_accessor :decomposition_source
 
-    # Always `null` in v1.
-    attr_accessor :artifact_id
+    attr_accessor :embedder_model
+
+    attr_accessor :candidates_considered
+
+    attr_accessor :warnings
+
+    # Calibrated confidence in this result set — read this instead of thresholding a raw similarity score. `strong`: the top match is confidently on-intent, proceed. `weak`: above the relevance floor but inside the band where plausible-but-wrong matches live, verify the result before paying. `none`: nothing cleared the floor — `results` is empty and `reason` / `suggestion` say why. Results below the floor are never returned as near-misses.
+    attr_accessor :match_quality
+
+    # Machine-readable cause of an empty result set, non-null exactly when `match_quality` is `none`. `below_relevance_floor`: candidates ranked but the best scored under the floor. `filter_collapsed_pool`: a caller filter cut the pool before ranking and nothing relevant survived — relax the filter. `no_catalog_coverage`: recall returned no candidates at all on an unfiltered query. `unsupported_filter_value`: a CATEGORICAL filter value (`type` / `protocol`) matches zero stored values, so it could never have matched — categorical only, since a continuous bound like `price` that matches nothing is reported as `filter_collapsed_pool` instead (the bound needs raising, the dimension is not unsupported). `index_unavailable`: no active index — an operational fault, paired with the `EMPTY_INDEX` warning.
+    attr_accessor :reason
+
+    # Human/agent-readable explanation of `reason`, carrying the concrete numbers behind it (pool sizes, the best discarded score against the floor, the values actually stored for a filter). Non-null exactly when `reason` is.
+    attr_accessor :suggestion
+
+    # Ranked `(Provider + Capability)` results; empty when the index is empty or nothing cleared the relevance floor. Results BELOW the floor are never returned — an empty list plus a `reason` is the honest answer, not a list of near-misses in the same shape as a genuine match.
+    attr_accessor :results
 
     # Present and `true` only when served by the mock backend.
     attr_accessor :_mock
 
+    class EnumAttributeValidator
+      attr_reader :datatype
+      attr_reader :allowable_values
+
+      def initialize(datatype, allowable_values)
+        @allowable_values = allowable_values.map do |value|
+          case datatype.to_s
+          when /Integer/i
+            value.to_i
+          when /Float/i
+            value.to_f
+          else
+            value
+          end
+        end
+      end
+
+      def valid?(value)
+        !value || allowable_values.include?(value)
+      end
+    end
+
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
+        :'query_trace_id' => :'query_trace_id',
+        :'query' => :'query',
+        :'format' => :'format',
+        :'markdown' => :'markdown',
+        :'result_count' => :'result_count',
+        :'served_from' => :'served_from',
+        :'as_of' => :'as_of',
+        :'stale' => :'stale',
+        :'payment_note' => :'payment_note',
+        :'applied_filters' => :'applied_filters',
+        :'decomposition_source' => :'decomposition_source',
+        :'embedder_model' => :'embedder_model',
+        :'candidates_considered' => :'candidates_considered',
+        :'warnings' => :'warnings',
+        :'match_quality' => :'match_quality',
+        :'reason' => :'reason',
+        :'suggestion' => :'suggestion',
         :'results' => :'results',
-        :'paid_usd' => :'paid_usd',
-        :'tx_hash' => :'tx_hash',
-        :'artifact_id' => :'artifact_id',
         :'_mock' => :'_mock'
       }
     end
@@ -54,10 +129,24 @@ module Weft
     # Attribute type mapping.
     def self.openapi_types
       {
-        :'results' => :'Array<SearchResponseResultsInner>',
-        :'paid_usd' => :'String',
-        :'tx_hash' => :'String',
-        :'artifact_id' => :'String',
+        :'query_trace_id' => :'String',
+        :'query' => :'String',
+        :'format' => :'String',
+        :'markdown' => :'String',
+        :'result_count' => :'Integer',
+        :'served_from' => :'String',
+        :'as_of' => :'Time',
+        :'stale' => :'Boolean',
+        :'payment_note' => :'String',
+        :'applied_filters' => :'SearchFilterSpec',
+        :'decomposition_source' => :'String',
+        :'embedder_model' => :'String',
+        :'candidates_considered' => :'Integer',
+        :'warnings' => :'Array<SearchResponseWarningsInner>',
+        :'match_quality' => :'String',
+        :'reason' => :'String',
+        :'suggestion' => :'String',
+        :'results' => :'Array<SearchResult>',
         :'_mock' => :'Boolean'
       }
     end
@@ -84,24 +173,94 @@ module Weft
         h[k.to_sym] = v
       }
 
-      if attributes.key?(:'results')
-        if (value = attributes[:'results']).is_a?(Array)
-          self.results = value
+      if attributes.key?(:'query_trace_id')
+        self.query_trace_id = attributes[:'query_trace_id']
+      else
+        self.query_trace_id = nil
+      end
+
+      if attributes.key?(:'query')
+        self.query = attributes[:'query']
+      else
+        self.query = nil
+      end
+
+      if attributes.key?(:'format')
+        self.format = attributes[:'format']
+      end
+
+      if attributes.key?(:'markdown')
+        self.markdown = attributes[:'markdown']
+      end
+
+      if attributes.key?(:'result_count')
+        self.result_count = attributes[:'result_count']
+      end
+
+      if attributes.key?(:'served_from')
+        self.served_from = attributes[:'served_from']
+      end
+
+      if attributes.key?(:'as_of')
+        self.as_of = attributes[:'as_of']
+      end
+
+      if attributes.key?(:'stale')
+        self.stale = attributes[:'stale']
+      end
+
+      if attributes.key?(:'payment_note')
+        self.payment_note = attributes[:'payment_note']
+      end
+
+      if attributes.key?(:'applied_filters')
+        self.applied_filters = attributes[:'applied_filters']
+      end
+
+      if attributes.key?(:'decomposition_source')
+        self.decomposition_source = attributes[:'decomposition_source']
+      end
+
+      if attributes.key?(:'embedder_model')
+        self.embedder_model = attributes[:'embedder_model']
+      else
+        self.embedder_model = nil
+      end
+
+      if attributes.key?(:'candidates_considered')
+        self.candidates_considered = attributes[:'candidates_considered']
+      else
+        self.candidates_considered = nil
+      end
+
+      if attributes.key?(:'warnings')
+        if (value = attributes[:'warnings']).is_a?(Array)
+          self.warnings = value
         end
       else
-        self.results = nil
+        self.warnings = nil
       end
 
-      if attributes.key?(:'paid_usd')
-        self.paid_usd = attributes[:'paid_usd']
+      if attributes.key?(:'match_quality')
+        self.match_quality = attributes[:'match_quality']
+      else
+        self.match_quality = 'none'
       end
 
-      if attributes.key?(:'tx_hash')
-        self.tx_hash = attributes[:'tx_hash']
+      if attributes.key?(:'reason')
+        self.reason = attributes[:'reason']
       end
 
-      if attributes.key?(:'artifact_id')
-        self.artifact_id = attributes[:'artifact_id']
+      if attributes.key?(:'suggestion')
+        self.suggestion = attributes[:'suggestion']
+      end
+
+      if attributes.key?(:'results')
+        if (value = attributes[:'results']).is_a?(Array)
+          self.results = value
+        end
+      else
+        self.results = nil
       end
 
       if attributes.key?(:'_mock')
@@ -114,6 +273,34 @@ module Weft
     def list_invalid_properties
       warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
       invalid_properties = Array.new
+      if @query_trace_id.nil?
+        invalid_properties.push('invalid value for "query_trace_id", query_trace_id cannot be nil.')
+      end
+
+      if @query.nil?
+        invalid_properties.push('invalid value for "query", query cannot be nil.')
+      end
+
+      if !@result_count.nil? && @result_count < 0
+        invalid_properties.push('invalid value for "result_count", must be greater than or equal to 0.')
+      end
+
+      if @embedder_model.nil?
+        invalid_properties.push('invalid value for "embedder_model", embedder_model cannot be nil.')
+      end
+
+      if @candidates_considered.nil?
+        invalid_properties.push('invalid value for "candidates_considered", candidates_considered cannot be nil.')
+      end
+
+      if @candidates_considered < 0
+        invalid_properties.push('invalid value for "candidates_considered", must be greater than or equal to 0.')
+      end
+
+      if @warnings.nil?
+        invalid_properties.push('invalid value for "warnings", warnings cannot be nil.')
+      end
+
       if @results.nil?
         invalid_properties.push('invalid value for "results", results cannot be nil.')
       end
@@ -125,10 +312,145 @@ module Weft
     # @return true if the model is valid
     def valid?
       warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if @query_trace_id.nil?
+      return false if @query.nil?
+      format_validator = EnumAttributeValidator.new('String', ["json", "markdown"])
+      return false unless format_validator.valid?(@format)
+      return false if !@result_count.nil? && @result_count < 0
+      served_from_validator = EnumAttributeValidator.new('String', ["live", "snapshot"])
+      return false unless served_from_validator.valid?(@served_from)
+      decomposition_source_validator = EnumAttributeValidator.new('String', ["CALLER"])
+      return false unless decomposition_source_validator.valid?(@decomposition_source)
+      return false if @embedder_model.nil?
+      return false if @candidates_considered.nil?
+      return false if @candidates_considered < 0
+      return false if @warnings.nil?
+      match_quality_validator = EnumAttributeValidator.new('String', ["strong", "weak", "none"])
+      return false unless match_quality_validator.valid?(@match_quality)
+      reason_validator = EnumAttributeValidator.new('String', ["below_relevance_floor", "filter_collapsed_pool", "no_catalog_coverage", "unsupported_filter_value", "index_unavailable"])
+      return false unless reason_validator.valid?(@reason)
       return false if @results.nil?
       true
     end
 
+    # Custom attribute writer method with validation
+    # @param [Object] query_trace_id Value to be assigned
+    def query_trace_id=(query_trace_id)
+      if query_trace_id.nil?
+        fail ArgumentError, 'query_trace_id cannot be nil'
+      end
+
+      @query_trace_id = query_trace_id
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] query Value to be assigned
+    def query=(query)
+      if query.nil?
+        fail ArgumentError, 'query cannot be nil'
+      end
+
+      @query = query
+    end
+
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] format Object to be assigned
+    def format=(format)
+      validator = EnumAttributeValidator.new('String', ["json", "markdown"])
+      unless validator.valid?(format)
+        fail ArgumentError, "invalid value for \"format\", must be one of #{validator.allowable_values}."
+      end
+      @format = format
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] result_count Value to be assigned
+    def result_count=(result_count)
+      if result_count.nil?
+        fail ArgumentError, 'result_count cannot be nil'
+      end
+
+      if result_count < 0
+        fail ArgumentError, 'invalid value for "result_count", must be greater than or equal to 0.'
+      end
+
+      @result_count = result_count
+    end
+
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] served_from Object to be assigned
+    def served_from=(served_from)
+      validator = EnumAttributeValidator.new('String', ["live", "snapshot"])
+      unless validator.valid?(served_from)
+        fail ArgumentError, "invalid value for \"served_from\", must be one of #{validator.allowable_values}."
+      end
+      @served_from = served_from
+    end
+
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] decomposition_source Object to be assigned
+    def decomposition_source=(decomposition_source)
+      validator = EnumAttributeValidator.new('String', ["CALLER"])
+      unless validator.valid?(decomposition_source)
+        fail ArgumentError, "invalid value for \"decomposition_source\", must be one of #{validator.allowable_values}."
+      end
+      @decomposition_source = decomposition_source
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] embedder_model Value to be assigned
+    def embedder_model=(embedder_model)
+      if embedder_model.nil?
+        fail ArgumentError, 'embedder_model cannot be nil'
+      end
+
+      @embedder_model = embedder_model
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] candidates_considered Value to be assigned
+    def candidates_considered=(candidates_considered)
+      if candidates_considered.nil?
+        fail ArgumentError, 'candidates_considered cannot be nil'
+      end
+
+      if candidates_considered < 0
+        fail ArgumentError, 'invalid value for "candidates_considered", must be greater than or equal to 0.'
+      end
+
+      @candidates_considered = candidates_considered
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] warnings Value to be assigned
+    def warnings=(warnings)
+      if warnings.nil?
+        fail ArgumentError, 'warnings cannot be nil'
+      end
+
+      @warnings = warnings
+    end
+
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] match_quality Object to be assigned
+    def match_quality=(match_quality)
+      validator = EnumAttributeValidator.new('String', ["strong", "weak", "none"])
+      unless validator.valid?(match_quality)
+        fail ArgumentError, "invalid value for \"match_quality\", must be one of #{validator.allowable_values}."
+      end
+      @match_quality = match_quality
+    end
+
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] reason Object to be assigned
+    def reason=(reason)
+      validator = EnumAttributeValidator.new('String', ["below_relevance_floor", "filter_collapsed_pool", "no_catalog_coverage", "unsupported_filter_value", "index_unavailable"])
+      unless validator.valid?(reason)
+        fail ArgumentError, "invalid value for \"reason\", must be one of #{validator.allowable_values}."
+      end
+      @reason = reason
+    end
+
     # Custom attribute writer method with validation
     # @param [Object] results Value to be assigned
     def results=(results)
@@ -144,10 +466,24 @@ module Weft
     def ==(o)
       return true if self.equal?(o)
       self.class == o.class &&
+          query_trace_id == o.query_trace_id &&
+          query == o.query &&
+          format == o.format &&
+          markdown == o.markdown &&
+          result_count == o.result_count &&
+          served_from == o.served_from &&
+          as_of == o.as_of &&
+          stale == o.stale &&
+          payment_note == o.payment_note &&
+          applied_filters == o.applied_filters &&
+          decomposition_source == o.decomposition_source &&
+          embedder_model == o.embedder_model &&
+          candidates_considered == o.candidates_considered &&
+          warnings == o.warnings &&
+          match_quality == o.match_quality &&
+          reason == o.reason &&
+          suggestion == o.suggestion &&
           results == o.results &&
-          paid_usd == o.paid_usd &&
-          tx_hash == o.tx_hash &&
-          artifact_id == o.artifact_id &&
           _mock == o._mock
     end
 
@@ -160,7 +496,7 @@ module Weft
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [results, paid_usd, tx_hash, artifact_id, _mock].hash
+      [query_trace_id, query, format, markdown, result_count, served_from, as_of, stale, payment_note, applied_filters, decomposition_source, embedder_model, candidates_considered, warnings, match_quality, reason, suggestion, results, _mock].hash
     end
 
     # Builds the object from hash