Class: Forem::Services::AdminConceptService

Inherits:
BaseService
  • Object
show all
Defined in:
lib/forem/services/admin_concept_service.rb

Overview

Service for interacting with the Forem Admin Concepts API.

Provides full CRUD over concepts — the curated topics Forem uses to classify articles and comments — plus the trigger_lookback action that re-runs classification over older content. Every endpoint requires an API key with super admin privileges; regular user keys receive HTTP 401.

Access via Client#admin_concepts. All methods inject the client's requestor automatically so no additional configuration is required.

Examples:

client = Forem::Client.new("admin-api-key")
concept = client.admin_concepts.create(name: "Machine Learning")
client.admin_concepts.trigger_lookback(concept.id, days: 90)

See Also:

Instance Method Summary collapse

Methods inherited from BaseService

#initialize

Constructor Details

This class inherits a constructor from Forem::Services::BaseService

Instance Method Details

#create(params = {}, opts = {}) ⇒ AdminConcept

Create a new concept.

Attributes are sent wrapped in a concept object for you. The API generates the slug, and generates a description and the anchor embedding from name, so only name is required.

Examples:

client.admin_concepts.create(
  name: "Machine Learning",
  description: "Posts about ML and AI",
  similarity_threshold: 0.8
)

Parameters:

  • params (Hash) (defaults to: {}) —

    concept attributes

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :name (String) —

    the concept name, max 100 chars (required)

  • :description (String) —

    human-readable description

  • :parent_id (Integer) —

    ID of the parent concept

  • :similarity_threshold (Float) —

    classification cutoff (0.0–1.0)

  • :score (Float) —

    ranking score for the concept

Returns:

Raises:



78
79
80
 
# File 'lib/forem/services/admin_concept_service.rb', line 78

def create(params = {}, opts = {})
  AdminConcept.create(params, opts_with_requestor(opts))
end

#delete(id, opts = {}) ⇒ AdminConcept?

Delete a concept.

The API responds with HTTP 204 and no body on success.

Examples:

client.admin_concepts.delete(7)

Parameters:

  • id (Integer, String) —

    the concept ID

  • opts (Hash) (defaults to: {}) —

    per-request options

Returns:

Raises:



113
114
115
 
# File 'lib/forem/services/admin_concept_service.rb', line 113

def delete(id, opts = {})
  AdminConcept.delete(id, opts_with_requestor(opts))
end

#list(params = {}, opts = {}) ⇒ ListObject

List concepts, ordered by name.

Returns a trimmed projection of each concept: id, name, slug, description, parent_id, similarity_threshold, max_lookback_days, created_at, and updated_at.

Examples:

client.admin_concepts.list(per_page: 100)

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    results per page (default: 50, max: 100)

Returns:



36
37
38
 
# File 'lib/forem/services/admin_concept_service.rb', line 36

def list(params = {}, opts = {})
  AdminConcept.list(params, opts_with_requestor(opts))
end

#retrieve(id, opts = {}) ⇒ AdminConcept

Retrieve a single concept by ID.

Returns the full concept record, unlike #list which returns a trimmed projection.

Examples:

client.admin_concepts.retrieve(7)

Parameters:

  • id (Integer, String) —

    the concept ID

  • opts (Hash) (defaults to: {}) —

    per-request options

Returns:

Raises:



52
53
54
 
# File 'lib/forem/services/admin_concept_service.rb', line 52

def retrieve(id, opts = {})
  AdminConcept.retrieve(id, opts_with_requestor(opts))
end

#trigger_lookback(id, params = {}, opts = {}) ⇒ ForemObject

Queue a classification lookback for a concept.

Enqueues a background job that classifies records from the last days days. The value must be positive and strictly greater than the concept's current max_lookback_days, otherwise the API responds with HTTP 422.

Examples:

client.admin_concepts.trigger_lookback(7, days: 90).message

Parameters:

  • id (Integer, String) —

    the concept ID

  • params (Hash) (defaults to: {}) —

    request body

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :days (Integer) —

    how many days back to classify (required)

Returns:

Raises:



133
134
135
 
# File 'lib/forem/services/admin_concept_service.rb', line 133

def trigger_lookback(id, params = {}, opts = {})
  AdminConcept.trigger_lookback(id, params, opts_with_requestor(opts))
end

#update(id, params = {}, opts = {}) ⇒ AdminConcept

Update an existing concept.

Attributes are sent wrapped in a concept object for you. Only name, description, parent_id, similarity_threshold, and score are writable; slug and max_lookback_days are ignored. Changing name or description regenerates the anchor embedding.

Examples:

client.admin_concepts.update(7, similarity_threshold: 0.9)

Parameters:

  • id (Integer, String) —

    the concept ID

  • params (Hash) (defaults to: {}) —

    attributes to change (see #create)

  • opts (Hash) (defaults to: {}) —

    per-request options

Returns:

Raises:



98
99
100
 
# File 'lib/forem/services/admin_concept_service.rb', line 98

def update(id, params = {}, opts = {})
  AdminConcept.update(id, params, opts_with_requestor(opts))
end