Class: Forem::AdminConcept

Inherits:
APIResource show all
Extended by:
Forem::APIOperations::List, Forem::APIOperations::Retrieve
Includes:
Forem::APIOperations::Delete
Defined in:
lib/forem/resources/admin_concept.rb

Overview

Represents a Concept managed through the admin-only Concepts API.

Concepts are curated topics that Forem uses to classify articles and comments via embedding similarity. The admin endpoints under /api/admin/concepts expose full CRUD over those records plus a trigger_lookback action that re-runs classification over older content. Every endpoint requires an API key belonging to a super admin — a regular user key receives HTTP 401.

Read-only access to the public concept endpoints lives on Concept; this resource is strictly the administrative surface.

Available operations:

- +List+             — GET /api/admin/concepts
- +Retrieve+         — GET /api/admin/concepts/:id
- +create+           — POST /api/admin/concepts
- +update+           — PUT /api/admin/concepts/:id
- +Delete+           — DELETE /api/admin/concepts/:id
- +trigger_lookback+ — POST /api/admin/concepts/:id/trigger_lookback

Concept Fields

  • id (Integer) — Unique identifier
  • name (String, required) — Display name, max 100 characters
  • slug (String) — Generated from name by the API; not writable
  • description (String) — Generated from name when omitted on create
  • parent_id (Integer) — Optional parent concept, forming a hierarchy
  • similarity_threshold (Float) — Cosine similarity cutoff between 0.0 and 1.0 used when classifying records (may be null)
  • score (Float) — Ranking score for the concept
  • max_lookback_days (Integer) — How far back classification has already been run; read-only (set by trigger_lookback, never by create/update)
  • created_at / updated_at (String) — ISO 8601 timestamps

The list endpoint returns a trimmed projection (+id+, name, slug, description, parent_id, similarity_threshold, max_lookback_days, created_at, updated_at) ordered by name, while the show endpoint returns the full record.

Writable attributes

Only name, description, parent_id, similarity_threshold, and score are permitted on create and update. Any other attribute (notably slug and max_lookback_days) is silently ignored by the API. Attributes are sent wrapped in a concept object, which this resource does for you.

Examples:

List concepts

concepts = client.admin_concepts.list(per_page: 100)
concepts.each { |c| puts "#{c.id}: #{c.name}" }

Create a concept (flat params — the concept: wrapper is added)

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

See Also:

Constant Summary collapse

OBJECT_NAME = 
"admin_concept"
RESOURCE_PATH = 
"/api/admin/concepts"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Forem::APIOperations::List

list

Methods included from Forem::APIOperations::Retrieve

retrieve

Methods included from Forem::APIOperations::Delete

#delete, included

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from Forem::APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Class Method Details

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

Create a new concept.

Sends a POST to /api/admin/concepts with the attributes wrapped in a concept object. The API generates the slug, and generates the description and anchor embedding from name before saving, so creation only requires a name.

Parameters:

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

    concept attributes, either flat or already wrapped in :concept.

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

    per-request options.

Options Hash (params):

  • :name (String) — default: required —

    the concept name (max 100 chars)

  • :description (String) —

    human-readable description

  • :parent_id (Integer) —

    ID of the parent concept

  • :similarity_threshold (Float) —

    cutoff between 0.0 and 1.0

  • :score (Float) —

    ranking score for the concept

Options Hash (opts):

  • :api_key (String) —

    override the API key for this request.

  • :requestor (APIRequestor) —

    a custom requestor to use.

Returns:

Raises:



88
89
90
91
92
 
# File 'lib/forem/resources/admin_concept.rb', line 88

def self.create(params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:post, resource_path, wrap_params(params), opts)
  construct_from(resp.parsed_body, requestor: requestor)
end

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

Queue a classification lookback for a concept.

Sends a POST to /api/admin/concepts/:id/trigger_lookback, enqueueing a background job that classifies records published within the last days days. The requested days 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: 40).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) — default: required —

    how many days back to classify.

Returns:

  • (ForemObject) —

    an object carrying a message describing the queued lookback.

Raises:

  • (InvalidRequestError) —

    on HTTP 422 when days is not greater than both zero and the concept's max_lookback_days.



132
133
134
135
136
 
# File 'lib/forem/resources/admin_concept.rb', line 132

def self.trigger_lookback(id, params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:post, "#{resource_path}/#{id}/trigger_lookback", params, opts)
  ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end

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

Update an existing concept.

Sends a PUT to /api/admin/concepts/:id with the attributes wrapped in a concept object. Changing name or description causes the API to regenerate the concept's anchor embedding.

Parameters:

  • id (Integer, String) —

    the concept ID.

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

    attributes to change, either flat or already wrapped in :concept. Same permitted keys as create.

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

    per-request options.

Returns:

Raises:



107
108
109
110
111
 
# File 'lib/forem/resources/admin_concept.rb', line 107

def self.update(id, params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:put, "#{resource_path}/#{id}", wrap_params(params), opts)
  construct_from(resp.parsed_body, requestor: requestor)
end

Instance Method Details

#trigger_lookback(days, opts = {}) ⇒ ForemObject

Queue a classification lookback for this concept instance.

Examples:

concept = client.admin_concepts.retrieve(7)
concept.trigger_lookback(90)

Parameters:

  • days (Integer) —

    how many days back to classify. Must be positive and greater than this concept's max_lookback_days.

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

    per-request options.

Returns:

Raises:



163
164
165
166
167
 
# File 'lib/forem/resources/admin_concept.rb', line 163

def trigger_lookback(days, opts = {})
  requestor = opts[:requestor] || @requestor
  resp = request(:post, "#{resource_url}/trigger_lookback", { days: days }, opts)
  ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end