context.dev 2.0.0 → 2.2.0

data/rbi/context_dev/models/monitor_retrieve_response.rbi

@@ -70,6 +70,19 @@ module ContextDev
       sig { returns(Time) }
       attr_accessor :updated_at
 
+      # Current baseline: the last observed value the monitor compares new snapshots
+      # against. Its shape follows `target.type` (page/sitemap/extract). Only populated
+      # on GET /monitors/{monitor_id}; null until the first baseline run completes (and
+      # after a target or change_detection update, which resets the baseline).
+      sig do
+        returns(
+          T.nilable(
+            ContextDev::Models::MonitorRetrieveResponse::Baseline::Variants
+          )
+        )
+      end
+      attr_accessor :baseline
+
       sig { returns(T.nilable(Time)) }
       attr_accessor :last_change_at
 
@@ -143,6 +156,14 @@ module ContextDev
               ContextDev::Models::MonitorRetrieveResponse::Target::Extract::OrHash
             ),
           updated_at: Time,
+          baseline:
+            T.nilable(
+              T.any(
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsPageBaseline::OrHash,
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsSitemapBaseline::OrHash,
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsExtractBaseline::OrHash
+              )
+            ),
           last_change_at: T.nilable(Time),
           last_error:
             T.nilable(
@@ -179,6 +200,11 @@ module ContextDev
         # Discriminated union describing what the monitor watches.
         target:,
         updated_at:,
+        # Current baseline: the last observed value the monitor compares new snapshots
+        # against. Its shape follows `target.type` (page/sitemap/extract). Only populated
+        # on GET /monitors/{monitor_id}; null until the first baseline run completes (and
+        # after a target or change_detection update, which resets the baseline).
+        baseline: nil,
         last_change_at: nil,
         # Error from the most recent failed run; null when the last run succeeded.
         last_error: nil,
@@ -207,6 +233,10 @@ module ContextDev
             target:
               ContextDev::Models::MonitorRetrieveResponse::Target::Variants,
             updated_at: Time,
+            baseline:
+              T.nilable(
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::Variants
+              ),
             last_change_at: T.nilable(Time),
             last_error:
               T.nilable(ContextDev::Models::MonitorRetrieveResponse::LastError),
@@ -265,9 +295,6 @@ module ContextDev
               )
             end
 
-          sig { returns(String) }
-          attr_accessor :query
-
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -277,21 +304,19 @@ module ContextDev
           sig { params(confidence_threshold: Float).void }
           attr_writer :confidence_threshold
 
-          # Detect meaning-level changes that match a natural language query.
+          # Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          # paraphrase-only differences. Which changes are meaningful is judged against the
+          # extract target's `instructions` (and `schema`, when provided).
           sig do
-            params(
-              query: String,
-              confidence_threshold: Float,
-              type: Symbol
-            ).returns(T.attached_class)
+            params(confidence_threshold: Float, type: Symbol).returns(
+              T.attached_class
+            )
           end
-          def self.new(query:, confidence_threshold: nil, type: :semantic)
+          def self.new(confidence_threshold: nil, type: :semantic)
           end
 
           sig do
-            override.returns(
-              { query: String, type: Symbol, confidence_threshold: Float }
-            )
+            override.returns({ type: Symbol, confidence_threshold: Float })
           end
           def to_hash
           end
@@ -610,8 +635,9 @@ module ContextDev
 
           # Watch a sitemap for URL additions and removals. Crawled URLs are normalized
           # (lowercased host, no trailing slash/fragment) and scoped to the monitored site
-          # and its subdomains before comparison. A new URL set must be observed on two
-          # consecutive runs before a change is reported, suppressing one-run crawl flaps.
+          # and its subdomains before comparison. On a detected difference the sitemap is
+          # re-fetched within the same run and only URLs both observations agree on are
+          # reported, suppressing transient crawl flaps.
           sig do
             params(
               url: String,
@@ -658,6 +684,11 @@ module ContextDev
               )
             end
 
+          # Natural-language instructions guiding which pages and facts to track and which
+          # changes to report.
+          sig { returns(String) }
+          attr_accessor :instructions
+
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -671,13 +702,6 @@ module ContextDev
           sig { params(follow_subdomains: T::Boolean).void }
           attr_writer :follow_subdomains
 
-          # Optional natural-language instructions guiding what to extract.
-          sig { returns(T.nilable(String)) }
-          attr_reader :instructions
-
-          sig { params(instructions: String).void }
-          attr_writer :instructions
-
           # Optional maximum link depth from the starting URL (0 = only the starting page).
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_depth
@@ -685,27 +709,37 @@ module ContextDev
           sig { params(max_depth: Integer).void }
           attr_writer :max_depth
 
-          # Maximum number of pages to analyze during extraction.
+          # Maximum number of pages to track.
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_pages
 
           sig { params(max_pages: Integer).void }
           attr_writer :max_pages
 
-          # JSON Schema describing the structured data to extract and watch for changes. If
-          # omitted, a default summary + key-points schema is used.
+          # JSON Schema describing the data you care about. It is used three ways: it guides
+          # which pages are selected for tracking, it gives the change judge extra context
+          # on which changes matter (alongside `instructions`), and it defines the shape of
+          # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          # about once a day). It is not a response format for changes: change events and
+          # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          # data in this schema's shape. If omitted, a default summary + key-points schema
+          # is used.
           sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
           attr_reader :schema
 
           sig { params(schema: T::Hash[Symbol, T.anything]).void }
           attr_writer :schema
 
-          # Watch a site's extracted structured data.
+          # Watch the monitor-relevant pages of a site for meaningful changes. A crawl
+          # guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
+          # track; each run re-checks exactly those pages, and confirmed content changes are
+          # judged for relevance against the monitor's `instructions` (and `schema`, when
+          # provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           sig do
             params(
+              instructions: String,
               url: String,
               follow_subdomains: T::Boolean,
-              instructions: String,
               max_depth: Integer,
               max_pages: Integer,
               schema: T::Hash[Symbol, T.anything],
@@ -713,17 +747,24 @@ module ContextDev
             ).returns(T.attached_class)
           end
           def self.new(
+            # Natural-language instructions guiding which pages and facts to track and which
+            # changes to report.
+            instructions:,
             # Root URL to extract structured data from.
             url:,
             follow_subdomains: nil,
-            # Optional natural-language instructions guiding what to extract.
-            instructions: nil,
             # Optional maximum link depth from the starting URL (0 = only the starting page).
             max_depth: nil,
-            # Maximum number of pages to analyze during extraction.
+            # Maximum number of pages to track.
             max_pages: nil,
-            # JSON Schema describing the structured data to extract and watch for changes. If
-            # omitted, a default summary + key-points schema is used.
+            # JSON Schema describing the data you care about. It is used three ways: it guides
+            # which pages are selected for tracking, it gives the change judge extra context
+            # on which changes matter (alongside `instructions`), and it defines the shape of
+            # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+            # about once a day). It is not a response format for changes: change events and
+            # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+            # data in this schema's shape. If omitted, a default summary + key-points schema
+            # is used.
             schema: nil,
             type: :extract
           )
@@ -732,10 +773,10 @@ module ContextDev
           sig do
             override.returns(
               {
+                instructions: String,
                 type: Symbol,
                 url: String,
                 follow_subdomains: T::Boolean,
-                instructions: String,
                 max_depth: Integer,
                 max_pages: Integer,
                 schema: T::Hash[Symbol, T.anything]
@@ -757,6 +798,175 @@ module ContextDev
         end
       end
 
+      # Current baseline: the last observed value the monitor compares new snapshots
+      # against. Its shape follows `target.type` (page/sitemap/extract). Only populated
+      # on GET /monitors/{monitor_id}; null until the first baseline run completes (and
+      # after a target or change_detection update, which resets the baseline).
+      module Baseline
+        extend ContextDev::Internal::Type::Union
+
+        Variants =
+          T.type_alias do
+            T.any(
+              ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsPageBaseline,
+              ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsSitemapBaseline,
+              ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsExtractBaseline
+            )
+          end
+
+        class MonitorsPageBaseline < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsPageBaseline,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # When this baseline was last captured or replaced.
+          sig { returns(Time) }
+          attr_accessor :captured_at
+
+          # The page's visible text as last observed.
+          sig { returns(String) }
+          attr_accessor :text
+
+          # Current baseline of a `page` monitor: the visible page text as last observed.
+          sig do
+            params(captured_at: Time, text: String).returns(T.attached_class)
+          end
+          def self.new(
+            # When this baseline was last captured or replaced.
+            captured_at:,
+            # The page's visible text as last observed.
+            text:
+          )
+          end
+
+          sig { override.returns({ captured_at: Time, text: String }) }
+          def to_hash
+          end
+        end
+
+        class MonitorsSitemapBaseline < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsSitemapBaseline,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # When this baseline was last captured or replaced.
+          sig { returns(Time) }
+          attr_accessor :captured_at
+
+          # Number of URLs in the baseline.
+          sig { returns(Integer) }
+          attr_accessor :url_count
+
+          # The sitemap URLs as last observed (sorted, normalized).
+          sig { returns(T::Array[String]) }
+          attr_accessor :urls
+
+          # Current baseline of a `sitemap` monitor: the normalized URL set as last
+          # observed.
+          sig do
+            params(
+              captured_at: Time,
+              url_count: Integer,
+              urls: T::Array[String]
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # When this baseline was last captured or replaced.
+            captured_at:,
+            # Number of URLs in the baseline.
+            url_count:,
+            # The sitemap URLs as last observed (sorted, normalized).
+            urls:
+          )
+          end
+
+          sig do
+            override.returns(
+              { captured_at: Time, url_count: Integer, urls: T::Array[String] }
+            )
+          end
+          def to_hash
+          end
+        end
+
+        class MonitorsExtractBaseline < ContextDev::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                ContextDev::Models::MonitorRetrieveResponse::Baseline::MonitorsExtractBaseline,
+                ContextDev::Internal::AnyHash
+              )
+            end
+
+          # When this baseline was last captured or replaced.
+          sig { returns(Time) }
+          attr_accessor :captured_at
+
+          # The extracted structured data, matching the monitor's extraction schema (same
+          # shape as the /web/extract endpoint's `data`). Refreshed when the monitor
+          # re-discovers its page set (at most about once a day); `null` when no extraction
+          # has been captured yet.
+          sig { returns(T.anything) }
+          attr_accessor :data
+
+          # The page URLs the monitor tracks and analyzes for changes.
+          sig { returns(T::Array[String]) }
+          attr_accessor :urls_analyzed
+
+          # Current baseline of an `extract` monitor: the pages it tracks and the structured
+          # data as last extracted.
+          sig do
+            params(
+              captured_at: Time,
+              data: T.anything,
+              urls_analyzed: T::Array[String]
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # When this baseline was last captured or replaced.
+            captured_at:,
+            # The extracted structured data, matching the monitor's extraction schema (same
+            # shape as the /web/extract endpoint's `data`). Refreshed when the monitor
+            # re-discovers its page set (at most about once a day); `null` when no extraction
+            # has been captured yet.
+            data:,
+            # The page URLs the monitor tracks and analyzes for changes.
+            urls_analyzed:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                captured_at: Time,
+                data: T.anything,
+                urls_analyzed: T::Array[String]
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+
+        sig do
+          override.returns(
+            T::Array[
+              ContextDev::Models::MonitorRetrieveResponse::Baseline::Variants
+            ]
+          )
+        end
+        def self.variants
+        end
+      end
+
       class LastError < ContextDev::Internal::Type::BaseModel
         OrHash =
           T.type_alias do

data/rbi/context_dev/models/monitor_update_params.rbi

@@ -222,9 +222,6 @@ module ContextDev
               )
             end
 
-          sig { returns(String) }
-          attr_accessor :query
-
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -234,21 +231,19 @@ module ContextDev
           sig { params(confidence_threshold: Float).void }
           attr_writer :confidence_threshold
 
-          # Detect meaning-level changes that match a natural language query.
+          # Detect meaning-level changes to tracked page content, ignoring cosmetic or
+          # paraphrase-only differences. Which changes are meaningful is judged against the
+          # extract target's `instructions` (and `schema`, when provided).
           sig do
-            params(
-              query: String,
-              confidence_threshold: Float,
-              type: Symbol
-            ).returns(T.attached_class)
+            params(confidence_threshold: Float, type: Symbol).returns(
+              T.attached_class
+            )
           end
-          def self.new(query:, confidence_threshold: nil, type: :semantic)
+          def self.new(confidence_threshold: nil, type: :semantic)
           end
 
           sig do
-            override.returns(
-              { query: String, type: Symbol, confidence_threshold: Float }
-            )
+            override.returns({ type: Symbol, confidence_threshold: Float })
           end
           def to_hash
           end
@@ -505,8 +500,9 @@ module ContextDev
 
           # Watch a sitemap for URL additions and removals. Crawled URLs are normalized
           # (lowercased host, no trailing slash/fragment) and scoped to the monitored site
-          # and its subdomains before comparison. A new URL set must be observed on two
-          # consecutive runs before a change is reported, suppressing one-run crawl flaps.
+          # and its subdomains before comparison. On a detected difference the sitemap is
+          # re-fetched within the same run and only URLs both observations agree on are
+          # reported, suppressing transient crawl flaps.
           sig do
             params(
               url: String,
@@ -553,6 +549,11 @@ module ContextDev
               )
             end
 
+          # Natural-language instructions guiding which pages and facts to track and which
+          # changes to report.
+          sig { returns(String) }
+          attr_accessor :instructions
+
           sig { returns(Symbol) }
           attr_accessor :type
 
@@ -566,13 +567,6 @@ module ContextDev
           sig { params(follow_subdomains: T::Boolean).void }
           attr_writer :follow_subdomains
 
-          # Optional natural-language instructions guiding what to extract.
-          sig { returns(T.nilable(String)) }
-          attr_reader :instructions
-
-          sig { params(instructions: String).void }
-          attr_writer :instructions
-
           # Optional maximum link depth from the starting URL (0 = only the starting page).
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_depth
@@ -580,27 +574,37 @@ module ContextDev
           sig { params(max_depth: Integer).void }
           attr_writer :max_depth
 
-          # Maximum number of pages to analyze during extraction.
+          # Maximum number of pages to track.
           sig { returns(T.nilable(Integer)) }
           attr_reader :max_pages
 
           sig { params(max_pages: Integer).void }
           attr_writer :max_pages
 
-          # JSON Schema describing the structured data to extract and watch for changes. If
-          # omitted, a default summary + key-points schema is used.
+          # JSON Schema describing the data you care about. It is used three ways: it guides
+          # which pages are selected for tracking, it gives the change judge extra context
+          # on which changes matter (alongside `instructions`), and it defines the shape of
+          # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+          # about once a day). It is not a response format for changes: change events and
+          # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+          # data in this schema's shape. If omitted, a default summary + key-points schema
+          # is used.
           sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
           attr_reader :schema
 
           sig { params(schema: T::Hash[Symbol, T.anything]).void }
           attr_writer :schema
 
-          # Watch a site's extracted structured data.
+          # Watch the monitor-relevant pages of a site for meaningful changes. A crawl
+          # guided by `schema`/`instructions` selects up to `max_pages` relevant pages to
+          # track; each run re-checks exactly those pages, and confirmed content changes are
+          # judged for relevance against the monitor's `instructions` (and `schema`, when
+          # provided). The tracked page set is refreshed by a periodic re-discovery crawl.
           sig do
             params(
+              instructions: String,
               url: String,
               follow_subdomains: T::Boolean,
-              instructions: String,
               max_depth: Integer,
               max_pages: Integer,
               schema: T::Hash[Symbol, T.anything],
@@ -608,17 +612,24 @@ module ContextDev
             ).returns(T.attached_class)
           end
           def self.new(
+            # Natural-language instructions guiding which pages and facts to track and which
+            # changes to report.
+            instructions:,
             # Root URL to extract structured data from.
             url:,
             follow_subdomains: nil,
-            # Optional natural-language instructions guiding what to extract.
-            instructions: nil,
             # Optional maximum link depth from the starting URL (0 = only the starting page).
             max_depth: nil,
-            # Maximum number of pages to analyze during extraction.
+            # Maximum number of pages to track.
             max_pages: nil,
-            # JSON Schema describing the structured data to extract and watch for changes. If
-            # omitted, a default summary + key-points schema is used.
+            # JSON Schema describing the data you care about. It is used three ways: it guides
+            # which pages are selected for tracking, it gives the change judge extra context
+            # on which changes matter (alongside `instructions`), and it defines the shape of
+            # the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most
+            # about once a day). It is not a response format for changes: change events and
+            # webhook payloads always contain diffs, summaries, and evidence excerpts — never
+            # data in this schema's shape. If omitted, a default summary + key-points schema
+            # is used.
             schema: nil,
             type: :extract
           )
@@ -627,10 +638,10 @@ module ContextDev
           sig do
             override.returns(
               {
+                instructions: String,
                 type: Symbol,
                 url: String,
                 follow_subdomains: T::Boolean,
-                instructions: String,
                 max_depth: Integer,
                 max_pages: Integer,
                 schema: T::Hash[Symbol, T.anything]