ecoportal-api-graphql 1.3.4 → 1.3.9

data/lib/ecoportal/api/graphql/input/search_conf/ai_generator.rb

@@ -0,0 +1,234 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class SearchConf
+          # AI-assisted filter generation — builds a SearchConf from a natural-language
+          # description using Claude (Anthropic API) with structured tool use output.
+          #
+          # Requires the `anthropic` gem to be available in the caller's environment.
+          # No hard dependency is added to ecoportal-api-graphql's gemspec.
+          #
+          # Usage:
+          #   require 'anthropic'
+          #
+          #   conf = SearchConf.from_description(
+          #     "find active pages in the Safety register updated in the last month",
+          #     api_key:     ENV['ANTHROPIC_API_KEY'],
+          #     register_id: 'REG_SAFETY_123'
+          #   )
+          #   # => #<SearchConf filters=[...] sorters=...>
+          #
+          #   # Then use it:
+          #   org.pages(searchConf: conf.to_h, first: 50)
+          #
+          # Options:
+          #   api_key:      Anthropic API key (default: ENV['ANTHROPIC_API_KEY'])
+          #   model:        Claude model ID (default: 'claude-sonnet-4-6')
+          #   register_id:  Scope results to this register (adds register_filter)
+          #   context:      Hash of extra context passed to the prompt (e.g. available states)
+          #   validate:     Boolean — if true, raises on ambiguous/empty result (default: false)
+          module AIGenerator
+            TOOL_NAME     = 'build_search_conf'.freeze
+            DEFAULT_MODEL = 'claude-sonnet-4-6'.freeze
+
+            SYSTEM_PROMPT = <<~PROMPT.freeze
+              You are a search query translator for the EcoPortal GraphQL API.
+              Convert natural-language descriptions into structured searchConf filter specifications.
+
+              ## Available filter operations (snake_case strings — case-sensitive)
+
+              | operation           | params                                      | notes                          |
+              |---------------------|---------------------------------------------|--------------------------------|
+              | exact_filter        | key, value                                  | equality match                 |
+              | one_of_filter       | key, values (array)                         | any of N values                |
+              | none_of_filter      | key, values (array)                         | exclude all values             |
+              | date_filter         | key, gte, lte, time_zone (UTC default)      | ISO8601 or mode                |
+              | date_filter (mode)  | key, mode, time_zone                        | modes: last_month, last_week, current_year, past, future, etc. |
+              | register_filter     | ids (array)                                 | scope to register(s)           |
+              | has_any_filter      | key                                         | field has any non-empty value  |
+              | match_filter        | key, value                                  | partial text match             |
+              | and_filter          | filters (array of filter objects)           | explicit AND group             |
+              | or_filter           | filters (array of filter objects)           | OR group                       |
+              | boolean_filter      | key, value (true/false)                     | boolean field                  |
+              | numeric_range_filter| key, gte, lte                               | numeric bounds                 |
+              | isnt_exact_filter   | key, value                                  | negated equality               |
+
+              ## Common page field names (key values)
+
+              | fieldName       | type    | common values                          |
+              |-----------------|---------|----------------------------------------|
+              | state           | string  | "active", "inactive", "complete"       |
+              | external_id     | string  | unique identifier                      |
+              | name            | string  | page name (use match_filter for partial)|
+              | creator_id      | string  | PersonMember ID                        |
+              | created_at      | date    | ISO8601 datetime                       |
+              | updated_at      | date    | ISO8601 datetime                       |
+              | all_location_ids| string  | location node ID (includes ancestors)  |
+              | location_id     | string  | exact location node ID                 |
+              | other_tags      | string  | tag string values                      |
+              | archived        | boolean | true/false                             |
+              | draft           | boolean | true/false                             |
+
+              ## Rules
+              - Top-level filters array is implicitly AND — no need to wrap in and_filter unless nesting inside or_filter
+              - Use register_filter when a specific register is mentioned or provided in context
+              - Use date_filter with mode (e.g. "last_month") for relative dates; ISO8601 for absolute dates
+              - Default sort is created_at desc unless the user specifies otherwise
+              - If the description is too vague to produce a useful filter, produce an empty filters array and explain in the reasoning field
+              - snake_case operation names are MANDATORY — CamelCase returns no results silently
+
+              Call the build_search_conf tool with your result.
+            PROMPT
+
+            module_function
+
+            # Build a SearchConf from a natural-language description via Claude API.
+            def from_description(text, api_key: nil, model: DEFAULT_MODEL,
+                                 register_id: nil, context: {}, validate: false)
+              require_anthropic!
+
+              client = ::Anthropic::Client.new(api_key: api_key || ENV.fetch('ANTHROPIC_API_KEY'))
+
+              user_message = build_user_message(text, register_id: register_id, context: context)
+              response     = client.messages.create(
+                model:      model,
+                max_tokens: 1024,
+                system:     SYSTEM_PROMPT,
+                tools:      [SEARCH_CONF_TOOL],
+                messages:   [{ role: 'user', content: user_message }]
+              )
+
+              result = extract_tool_result(response)
+              conf   = build_search_conf(result, register_id: register_id)
+
+              if validate && conf.to_h.empty?
+                raise ArgumentError, "AI could not produce filters for: #{text.inspect}. " \
+                                     "Reasoning: #{result['reasoning']}"
+              end
+
+              conf
+            end
+
+            def require_anthropic!
+              require 'anthropic'
+            rescue LoadError
+              raise LoadError,
+                    "SearchConf.from_description requires the 'anthropic' gem. " \
+                    "Add `gem 'anthropic'` to your Gemfile and run `bundle install`."
+            end
+
+            def build_user_message(text, register_id:, context:)
+              parts = ["Convert this description to a searchConf filter: #{text.inspect}"]
+              parts << "Register ID to scope results: #{register_id}" if register_id
+              context.each { |k, v| parts << "Context — #{k}: #{v}" }
+              parts.join("\n")
+            end
+
+            def extract_tool_result(response)
+              tool_use = response.content.find { |b| b.type == 'tool_use' && b.name == TOOL_NAME }
+              raise "AI did not call #{TOOL_NAME} — response: #{response.content.map(&:type)}" unless tool_use
+
+              tool_use.input
+            end
+
+            def build_search_conf(result, register_id:)
+              conf = SearchConf.new
+              conf = apply_register(conf, result, register_id)
+              conf = apply_filters(conf, result['filters'])
+              conf = apply_sorters(conf, result['sorters'])
+              apply_query(conf, result['query'])
+            end
+
+            def apply_register(conf, result, register_id)
+              ids = result['register_ids']&.compact&.reject(&:empty?)
+              if ids && !ids.empty?
+                conf.filter(SearchConf::Register.new(*ids))
+              elsif register_id
+                conf.filter(SearchConf::Register.new(register_id))
+              else
+                conf
+              end
+            end
+
+            def apply_filters(conf, filters)
+              Array(filters).reduce(conf) do |c, f|
+                c.filter(SearchConf::RawFilter.new(f['operation'], **symbolize(f['params'] || {})))
+              end
+            end
+
+            def apply_sorters(conf, sorters)
+              Array(sorters).reduce(conf) do |c, s|
+                c.sort(s['key'].to_sym, s['direction']&.to_sym || :desc)
+              end
+            end
+
+            def apply_query(conf, query)
+              return conf unless query && !query.strip.empty?
+
+              conf.query(query)
+            end
+
+            def symbolize(hash)
+              hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+            end
+
+            # JSON Schema for the tool — Claude must call this with the filter spec.
+            SEARCH_CONF_TOOL = {
+              name:         TOOL_NAME,
+              description:  'Output a structured searchConf filter specification',
+              input_schema: {
+                type:       'object',
+                required:   %w[filters],
+                properties: {
+                  reasoning:    {
+                    type:        'string',
+                    description: 'Brief explanation of the chosen filters'
+                  },
+                  register_ids: {
+                    type:        'array',
+                    description: 'Register IDs to scope the search (leave empty for org-wide)',
+                    items:       { type: 'string' }
+                  },
+                  filters:      {
+                    type:        'array',
+                    description: 'Array of filter objects (top-level is implicit AND)',
+                    items:       {
+                      type:       'object',
+                      required:   %w[operation params],
+                      properties: {
+                        operation: {
+                          type:        'string',
+                          description: 'Filter operation name (snake_case)'
+                        },
+                        params:    {
+                          type:        'object',
+                          description: 'Operation parameters (key, value, ids, filters, gte, lte, etc.)'
+                        }
+                      }
+                    }
+                  },
+                  sorters:      {
+                    type:  'array',
+                    items: {
+                      type:       'object',
+                      required:   %w[key direction],
+                      properties: {
+                        key:       { type: 'string' },
+                        direction: { type: 'string', enum: %w[asc desc] }
+                      }
+                    }
+                  },
+                  query:        {
+                    type:        'string',
+                    description: 'Full-text search string (optional)'
+                  }
+                }
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/search_conf.rb

@@ -0,0 +1,367 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        # Builder for the searchConf hash argument used by pages, contractorEntities,
+        # personMembers, and other paginated queries.
+        #
+        # Usage:
+        #   conf = SearchConf.new
+        #     .filter(SearchConf::Exact.new(:external_id, 'ABC'))
+        #     .sort(:created_at, :desc)
+        #
+        #   # OR filter (find by one of several externalIds)
+        #   conf = SearchConf.new.filter(
+        #     SearchConf::Or.new(
+        #       SearchConf::Exact.new(:external_id, '1111'),
+        #       SearchConf::Exact.new(:external_id, '2222')
+        #     )
+        #   )
+        #
+        #   # Parametrize — reuse the same structure with a different value
+        #   base = SearchConf.new.filter(SearchConf::Exact.new(:external_id, 'X'))
+        #   copy = base.with(external_id: 'Y')
+        #
+        #   # Pass to any query:
+        #   org.pages(searchConf: conf.to_h, first: 10)
+        #
+        # Filter operations (snake_case — CamelCase silently returns no results):
+        #   SearchConf::Exact     — exact_filter
+        #   SearchConf::DateRange — date_filter
+        #   SearchConf::Register  — register_filter (org search only)
+        #   SearchConf::And       — and_filter (explicit AND group)
+        #   SearchConf::Or        — or_filter
+        class SearchConf
+          # ---------------------------------------------------------------------------
+          # AI-assisted filter generation (optional — requires 'anthropic' gem)
+          # ---------------------------------------------------------------------------
+          class << self
+            # Build a SearchConf from a natural-language description using Claude.
+            # See SearchConf::AIGenerator for full documentation and options.
+            #
+            # Usage:
+            #   require 'anthropic'
+            #   conf = SearchConf.from_description(
+            #     "active pages in Safety register updated this month",
+            #     register_id: 'REG_123'
+            #   )
+            def from_description(text, **opts)
+              require_relative 'search_conf/ai_generator'
+              AIGenerator.from_description(text, **opts)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Composable — adds & and | operators to filter classes so they can be
+          # combined using natural Ruby operator syntax:
+          #   filter1 & filter2  →  SearchConf::And.new(filter1, filter2)
+          #   filter1 | filter2  →  SearchConf::Or.new(filter1, filter2)
+          # ---------------------------------------------------------------------------
+          module Composable
+            def &(other)
+              SearchConf::And.new(self, other)
+            end
+
+            def |(other)
+              SearchConf::Or.new(self, other)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: exact_filter
+          # ---------------------------------------------------------------------------
+          class Exact
+            include Composable
+
+            OPERATION = 'exact_filter'.freeze
+
+            def initialize(key, value)
+              @key   = key.to_s
+              @value = value
+            end
+
+            def to_h
+              { operation: OPERATION, params: { key: @key, value: @value } }
+            end
+
+            def substitute(subs)
+              key_sym = @key.to_sym
+              return self unless subs.key?(key_sym)
+
+              self.class.new(@key, subs[key_sym])
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: date_filter
+          # ---------------------------------------------------------------------------
+          class DateRange
+            include Composable
+
+            OPERATION = 'date_filter'.freeze
+
+            def initialize(key, gte: nil, lte: nil, time_zone: 'UTC')
+              @key       = key.to_s
+              @gte       = gte
+              @lte       = lte
+              @time_zone = time_zone
+            end
+
+            def to_h
+              params = { key: @key, time_zone: @time_zone }
+              params[:gte] = @gte if @gte
+              params[:lte] = @lte if @lte
+              { operation: OPERATION, params: params }
+            end
+
+            def substitute(subs)
+              self.class.new(
+                @key,
+                gte:       subs.fetch(:gte, @gte),
+                lte:       subs.fetch(:lte, @lte),
+                time_zone: subs.fetch(:time_zone, @time_zone)
+              )
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: register_filter (org search only — scope to specific registers)
+          # ---------------------------------------------------------------------------
+          class Register
+            include Composable
+
+            OPERATION = 'register_filter'.freeze
+
+            def initialize(*ids)
+              @ids = ids.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { ids: @ids } }
+            end
+
+            def substitute(subs)
+              self.class.new(*Array(subs.fetch(:register_ids, @ids)))
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: and_filter (explicit AND group; top-level filters array is implicit AND)
+          # ---------------------------------------------------------------------------
+          class And
+            include Composable
+
+            OPERATION = 'and_filter'.freeze
+
+            def initialize(*filters)
+              @filters = filters.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
+            end
+
+            def substitute(subs)
+              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Filter: or_filter
+          # ---------------------------------------------------------------------------
+          class Or
+            include Composable
+
+            OPERATION = 'or_filter'.freeze
+
+            def initialize(*filters)
+              @filters = filters.flatten
+            end
+
+            def to_h
+              { operation: OPERATION, params: { filters: @filters.map(&:to_h) } }
+            end
+
+            def substitute(subs)
+              self.class.new(*@filters.map { |f| f.respond_to?(:substitute) ? f.substitute(subs) : f })
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # RawFilter — escape hatch for operations not yet wrapped as SearchConf classes.
+          # Supports & and | composition just like the typed filter classes.
+          # Usage:
+          #   SearchConf.new.filter(SearchConf::RawFilter.new('has_any_filter', key: 'external_id'))
+          # ---------------------------------------------------------------------------
+          class RawFilter
+            include Composable
+
+            def initialize(operation, **params)
+              @operation = operation
+              @params    = params
+            end
+
+            def to_h
+              { 'operation' => @operation, 'params' => @params.transform_keys(&:to_s) }
+            end
+
+            def substitute(_subs)
+              self
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # Fluent DSL class methods — factory for filter expressions.
+          #
+          # SearchConf[:field]  →  FieldRef (then call .eq, .since, .matches, etc.)
+          # SearchConf.in_register(id)  →  Register filter
+          # SearchConf.raw(op, **params)  →  RawFilter
+          #
+          # Examples:
+          #   SearchConf[:external_id].eq('ABC')
+          #   SearchConf[:state].is(:active)
+          #   SearchConf[:updated_at].since('2025-01-01T00:00:00Z')
+          #   SearchConf[:state].is(:active) & SearchConf.in_register('REG')
+          #   SearchConf[:state].is(:active) | SearchConf[:state].is(:complete)
+          # ---------------------------------------------------------------------------
+          class << self
+            def [](key)
+              FieldRef.new(key.to_s)
+            end
+
+            def in_register(*ids)
+              Register.new(*ids.flatten)
+            end
+
+            def raw(operation, **params)
+              RawFilter.new(operation, **params)
+            end
+          end
+
+          # FieldRef — intermediate object produced by SearchConf[:field].
+          # Calling an operation method returns a concrete Composable filter object.
+          class FieldRef
+            def initialize(key)
+              @key = key
+            end
+
+            def eq(value)
+              Exact.new(@key, value)
+            end
+
+            def is(value)
+              eq(value.to_s)
+            end
+
+            def one_of(*values)
+              Or.new(*values.flatten.map { |v| eq(v.to_s) })
+            end
+
+            def not_eq(value)
+              RawFilter.new('isnt_exact_filter', key: @key, value: value)
+            end
+
+            def matches(text)
+              RawFilter.new('match_filter', key: @key, value: text)
+            end
+
+            def since(date, time_zone: 'UTC')
+              DateRange.new(@key, gte: date, time_zone: time_zone)
+            end
+
+            def before(date, time_zone: 'UTC')
+              DateRange.new(@key, lte: date, time_zone: time_zone)
+            end
+
+            def between(from, til, time_zone: 'UTC')
+              DateRange.new(@key, gte: from, lte: til, time_zone: time_zone)
+            end
+
+            # Human date mode — Search[:updated_at].in_period(:last_month)
+            # See search_filters.md for full list of mode values.
+            def in_period(mode, time_zone: 'Pacific/Auckland', **extra)
+              RawFilter.new('date_filter', key: @key, mode: mode.to_s, time_zone: time_zone, **extra)
+            end
+
+            def present
+              RawFilter.new('has_any_filter', key: @key)
+            end
+
+            alias_method :exists, :present
+
+            def blank
+              RawFilter.new('doesnt_exist_filter', field: @key)
+            end
+
+            def true?
+              RawFilter.new('boolean_filter', key: @key, value: true)
+            end
+
+            def false?
+              RawFilter.new('boolean_filter', key: @key, value: false)
+            end
+
+            def between_nums(min, max)
+              RawFilter.new('numeric_range_filter', key: @key, gte: min, lte: max)
+            end
+          end
+
+          # ---------------------------------------------------------------------------
+          # SearchConf builder
+          # ---------------------------------------------------------------------------
+          def initialize
+            @filters      = []
+            @sorters      = []
+            @search_query = nil
+          end
+
+          # Add one or more filter objects. Multiple calls accumulate (implicit AND at top level).
+          def filter(*filter_objs)
+            @filters.concat(filter_objs.flatten)
+            self
+          end
+
+          # Add a sorter. direction: :asc or :desc.
+          # Multiple sorters are supported (applied in order).
+          def sort(key, direction = :desc)
+            @sorters << { key: key.to_s, direction: direction.to_s }
+            self
+          end
+
+          # Set a full-text search string.
+          def query(text)
+            @search_query = text
+            self
+          end
+
+          # Returns a new SearchConf with filter values substituted.
+          # Substitution keys match the filter's field key (e.g. external_id:, gte:, lte:).
+          # Filters that don't recognise a key are returned unchanged.
+          def with(**substitutions)
+            clone.tap do |copy|
+              copy.instance_variable_set(
+                :@filters,
+                @filters.map { |f| f.respond_to?(:substitute) ? f.substitute(substitutions) : f }
+              )
+            end
+          end
+
+          # Serialises to the Hash structure expected by searchConf arguments.
+          # Sorters: single object when one sorter (API convention), array when multiple.
+          def to_h
+            h = {}
+            h[:filters] = @filters.map(&:to_h) unless @filters.empty?
+            h[:sorters] = @sorters.length == 1 ? @sorters.first : @sorters unless @sorters.empty?
+            h[:query]   = @search_query if @search_query
+            h
+          end
+
+          # Allow JSON serialisation directly (via json gem as_json protocol).
+          def as_json(_ = nil)
+            to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/variable_binding.rb

@@ -0,0 +1,20 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class VariableBinding
+          attr_reader :name, :data_field_id
+
+          def initialize(name:, data_field_id:)
+            @name = name
+            @data_field_id = data_field_id
+          end
+
+          def to_h
+            { name: name, dataFieldId: data_field_id }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/workflow_command/add_action_tag.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddActionTag
+            SCHEMA_VERSION = '20260605'.freeze
+            VALID_KEYS = %i[stageId taskId scheduledCallbackId actionId tag].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/workflow_command/add_binding.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddBinding
+            SCHEMA_VERSION = '20260605'.freeze
+            VALID_KEYS = %i[placeholderId forceId name referenceId type].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/workflow_command/add_comment_tagging_user_group.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class WorkflowCommand
+          module AddCommentTaggingUserGroup
+            SCHEMA_VERSION = '20260605'.freeze
+            VALID_KEYS = %i[stageId userGroupId].freeze
+
+            def self.build(**kwargs)
+              kwargs.slice(*VALID_KEYS).compact
+            end
+          end
+        end
+      end
+    end
+  end
+end