gitlab-foss/gems/gitlab-active-context/doc/getting_started.md

Getting started

Unit Primitives

See glossary for what a unit primitive is.

Consider creating separate unit primitives (e.g., semantic_search_code, semantic_search_issue, semantic_search_documentation) when:

• Different features will exist in different product tiers
• You need different entitlements for different search types
• You plan to package sub-features separately
• You require more granular end-user permissions
• You need to track usage separately for billing purposes

Use a single unit primitive (e.g., semantic_search) when:

• All features share the same entitlement level
• There's no need for tier-specific access control
• You want to reduce implementation complexity
• The feature is still in flux or experimental

Keep in mind that splitting or adding primitives increases implementation effort. See documentation.

Follow the Cloud Connector guidance for adding a new feature.

Configuration

Add an initializer with the following options:

1. enabled: true|false. Defaults to false
2. indexing_enabled: true|false. Defaults to false
3. re_enqueue_indexing_workers: true|false. Defaults to false
4. logger: Logger. Defaults to Logger.new($stdout)

For example:

ActiveContext.configure do |config|
  config.enabled = true
  config.indexing_enabled = true
  config.logger = ::Gitlab::Elasticsearch::Logger.build
end

Create a connection

Create a Ai::ActiveContext::Connection record in the database with the following fields:

• name: Useful name
• adapter_class: One of
  • ActiveContext::Databases::Elasticsearch::Adapter
  • ActiveContext::Databases::Opensearch::Adapter
  • ActiveContext::Databases::Postgres::Adapter
• options: Connection options
  • For Elasticsearch: url, client_request_timeout, retry_on_failure, log, debug
  • For OpenSearch: url, aws, aws_region, aws_access_key, aws_secret_access_key, client_request_timeout, retry_on_failure, log, debug
  • For Postgres: port, host, username, password

Use Elasticsearch settings from Advanced Search

Ai::ActiveContext::Connection.create!(
  name: "elastic",
  adapter_class: "ActiveContext::Databases::Elasticsearch::Adapter",
  options: ::Gitlab::CurrentSettings.elasticsearch_config
)

Use OpenSearch settings from Advanced Search

Ai::ActiveContext::Connection.create!(
  name: "opensearch",
  adapter_class: "ActiveContext::Databases::Opensearch::Adapter",
  options: ::Gitlab::CurrentSettings.elasticsearch_config
)

Activate a connection

To make a connection active and deactivate the existing active connection if it is set:

connection.activate!