Shivam MishraandGitHub
3d20a7b049
## Manually triggering help center generation
Open a Rails console (`bundle exec rails console`):
```ruby
account = Account.find(<ACCOUNT_ID>)
user = account.users.first
# Optional: refresh brand info from the customer's website
domain = 'example.com'
result = WebsiteBrandingService.new("noreply@#{domain}").perform
account.update!(
name: result[:title].presence || account.name,
custom_attributes: account.custom_attributes.merge('website' => domain, 'brand_info' => result)
)
# Optional: wipe existing portals so a fresh one is created
account.portals.destroy_all
Onboarding::HelpCenterCreationService.new(account, user).perform
```
Sidekiq must be running — articles are written by
`Onboarding::HelpCenterArticleGenerationJob`. Avoid running on
production; generation calls the LLM provider.
### Generation flow (Happy Path)
```mermaid
sequenceDiagram
autonumber
participant Kickoff as HelpCenterCreationService
participant DB as DB
participant GenJob as HelpCenterArticleGenerationJob
participant Curator as HelpCenterCurator
participant Firecrawl as Firecrawl
participant CuratorLLM as Curation LLM
participant Redis as Redis Progress
participant WriterJob as HelpCenterArticleWriterJob
participant Builder as HelpCenterArticleBuilder
participant WriterLLM as Writer LLM
participant Cable as ActionCable
Kickoff->>DB: Create portal for account<br/>homepage_link=https://chatwoot.com
Kickoff->>DB: Attach brand logo if available
Kickoff->>GenJob: Enqueue generation job<br/>account_id, portal_id, user_id, generation_id
GenJob->>Curator: Curate help center plan
Curator->>Firecrawl: map https://chatwoot.com<br/>search: docs help support faq
Firecrawl-->>Curator: Return discovered links
Curator->>CuratorLLM: Select categories + article plans<br/>from discovered links only
CuratorLLM-->>Curator: Return categories, articles, allowed_urls
GenJob->>DB: Create portal categories
GenJob->>GenJob: Stamp articles with category_id
GenJob->>GenJob: Filter article URLs against allowed_urls
GenJob->>GenJob: Drop articles with no category<br/>or no approved source URLs
GenJob->>Redis: Start progress<br/>status=generating, total=N, finished=0
loop For each approved article
GenJob->>WriterJob: Enqueue writer job<br/>title, category_id, approved URLs
end
par Writer jobs run independently
WriterJob->>Builder: Build article from approved URLs
Builder->>Firecrawl: batch_scrape approved URLs
Firecrawl-->>Builder: Return Markdown source pages
Builder->>WriterLLM: Rewrite sources into one article
WriterLLM-->>Builder: Return title, description, Markdown content
Builder->>DB: Create draft portal article<br/>meta.source_urls
WriterJob->>Redis: Increment finished count
WriterJob->>Cable: Broadcast help_center.article_generated
end
WriterJob->>Redis: If finished >= total<br/>mark status=completed
WriterJob->>Cable: Broadcast help_center.generation_completed
```
### Redis State Management
```mermaid
stateDiagram-v2
[*] --> active_pointer_set
active_pointer_set --> generating: generation job creates valid plan
active_pointer_set --> skipped: curation skipped/failed
generating --> generating: each writer job increments finished
generating --> completed: finished == total
generating --> ignored_completion: generation_id superseded
skipped --> [*]
completed --> [*]
ignored_completion --> [*]
```
103 lines
3.5 KiB
Ruby
103 lines
3.5 KiB
Ruby
class Captain::Llm::ArticleWriterService < Captain::BaseTaskService
|
|
RESPONSE_SCHEMA = Captain::Llm::ArticleWriterSchema
|
|
SOURCE_MAX_LENGTH = 60_000
|
|
|
|
# source_pages: Array<{ url: String, markdown: String }>, 1-3 entries.
|
|
pattr_initialize [:account!, :source_pages!, { hint_title: nil }]
|
|
|
|
def perform
|
|
response = make_api_call(model: writer_model, messages: messages, schema: RESPONSE_SCHEMA)
|
|
return response if response[:error]
|
|
|
|
response.merge(message: extract_payload(response[:message]))
|
|
end
|
|
|
|
private
|
|
|
|
def extract_payload(message)
|
|
return {} if message.blank?
|
|
|
|
data = message.is_a?(Hash) ? message.deep_symbolize_keys : {}
|
|
{
|
|
title: data[:title].to_s.strip,
|
|
description: data[:description].to_s.strip,
|
|
content: data[:content].to_s.strip
|
|
}
|
|
end
|
|
|
|
def messages
|
|
[
|
|
{ role: 'system', content: system_prompt },
|
|
{ role: 'user', content: user_prompt }
|
|
]
|
|
end
|
|
|
|
def system_prompt
|
|
<<~PROMPT
|
|
You are rewriting web page content into a clean help-center article for a customer-support knowledge base.
|
|
You may receive 1 to 3 source pages. When given multiple sources, merge them into ONE coherent article:
|
|
deduplicate identical instructions, do not repeat the same step in different words, and order content
|
|
by the natural reading flow of the merged topic. When sources contradict, prefer the more authoritative
|
|
or detailed version. The result must read like a single article, not a stitched-together collage.
|
|
|
|
Preserve the substance: keep instructions, steps, code samples, configuration, troubleshooting, and FAQs intact.
|
|
Strip marketing copy, navigation breadcrumbs, "share this page" footers, repeated CTAs, and links to unrelated pages.
|
|
Output well-formatted Markdown — use headings, lists, and code fences where appropriate.
|
|
The body must stay under 18000 characters. If the combined sources are longer, trim repetition and tangents
|
|
before cutting steps or critical detail. Never invent content the sources do not support.
|
|
|
|
Write the title, description, and body in #{locale_name}.
|
|
If a source page is in another language, translate as you rewrite — do not copy source-language text into the output.
|
|
Code samples, command-line examples, API field names, and proper nouns stay in their original form.
|
|
PROMPT
|
|
end
|
|
|
|
def user_prompt
|
|
pages = Array(source_pages).reject { |p| p[:markdown].to_s.blank? }
|
|
per_source_cap = pages.size.positive? ? SOURCE_MAX_LENGTH / pages.size : SOURCE_MAX_LENGTH
|
|
|
|
sections = pages.each_with_index.map do |page, idx|
|
|
body = page[:markdown].to_s.truncate(per_source_cap, omission: "\n\n[source truncated for length]")
|
|
"=== Source #{idx + 1} of #{pages.size} (#{page[:url]}) ===\n#{body}"
|
|
end
|
|
|
|
parts = [
|
|
("Suggested title (you may rewrite): #{hint_title}" if hint_title.present?),
|
|
'Source pages (Markdown):',
|
|
sections.join("\n\n")
|
|
].compact
|
|
parts.join("\n\n")
|
|
end
|
|
|
|
def locale_name
|
|
code = account.locale.to_s
|
|
LANGUAGES_CONFIG.values.find { |v| v[:iso_639_1_code] == code }&.dig(:name) || code.presence || 'English (en)'
|
|
end
|
|
|
|
def event_name
|
|
'article_writer'
|
|
end
|
|
|
|
def llm_credential
|
|
@llm_credential ||= system_llm_credential
|
|
end
|
|
|
|
def captain_tasks_enabled?
|
|
true
|
|
end
|
|
|
|
# Rewrite runs on the operator's OpenAI key during onboarding; should not
|
|
# debit the customer's captain_responses quota.
|
|
def counts_toward_usage?
|
|
false
|
|
end
|
|
|
|
def writer_model
|
|
'gpt-5.2'
|
|
end
|
|
|
|
def build_follow_up_context?
|
|
false
|
|
end
|
|
end
|