Notice formatter service

NoticeFormatterService maps categorized notices onto Telegram-ready templates. LLM classification, fuzzy job matching, and per-type layouts without blowing past message length limits.

The Notice Formatter Service resides within the application’s services layer and interacts with data clients, database services, and notification channels through a well-defined dependency injection architecture.

graph TB
subgraph "Services Layer"
NFS[NoticeFormatterService]
NS[NotificationService]
TS[TelegramService]
end
subgraph "Clients Layer"
SS[SupersetClientService]
end
subgraph "Runners Layer"
UR[UpdateRunner]
NR[NotificationRunner]
end
subgraph "Data Layer"
SJ[structured_job_listings.json]
PO[placement_offers.json]
end
UR --> SS
UR --> NFS
NR --> NS
NS --> TS
SS --> SJ
SS --> PO

The Notice Formatter Service is built around a LangGraph-based state machine that processes notices through distinct stages: text extraction, classification, job matching, enrichment, structured extraction, and final formatting. It maintains a compact set of helper utilities for date formatting, currency display, HTML breakdown parsing, and content prettification.

It can:

• Multi-stage LLM classification into categories (job posting, shortlisting, webinar, hackathon, announcement, update)
• Fuzzy company name matching against structured job listings
• Structured information extraction tailored to each notice category
• Category-specific formatting templates with consistent Markdown/HTML output
• Integration hooks for job enrichment callbacks
• Content cleaning and sanitization for Telegram compatibility

Stateful pipeline from messy notice text to a standard message. Add a notice type or channel by extending the maps, not by forking the class.

sequenceDiagram
participant CR as "UpdateRunner"
participant SS as "SupersetClientService"
participant NFS as "NoticeFormatterService"
participant DB as "DatabaseService"
participant NS as "NotificationService"
participant TS as "TelegramService"
CR->>SS : Fetch notices and jobs
CR->>NFS : format_notice(notice, jobs, job_enricher)
NFS->>NFS : extract_text()
NFS->>NFS : classify_post()
NFS->>NFS : match_job()
NFS->>NFS : enrich_matched_job()
NFS->>NFS : extract_info()
NFS->>NFS : format_message()
NFS-->>CR : formatted notice
CR->>DB : save_notice(formatted)
NS->>TS : send_message(formatted_message)
TS-->>NS : success/failure
NS-->>CR : delivery stats

NoticeFormatterService class#

The core formatter implements a LangGraph StateGraph with six nodes representing the processing pipeline. Each node encapsulates a specific transformation step with explicit input/output contracts.

classDiagram
class NoticeFormatterService {
-llm : ChatGoogleGenerativeAI
-app : StateGraph
+format_notice(notice, jobs, job_enricher) Dict
+format_many(notices, jobs) List[Dict]
+extract_text(state) PostState
+classify_post(state) PostState
+match_job(state) PostState
+enrich_matched_job(state) PostState
+extract_info(state) PostState
+format_message(state) PostState
+_ensure_str_content(content) str
+_format_ms_epoch_to_ist(ms, fmt) str
+_prettify_raw_text(raw) str
+_format_package(amount, annum_months) str
+format_html_breakdown(html_content) str
}
class PostState {
<<TypedDict>>
+notice : Notice
+jobs : List[Job]
+job_enricher : Optional[Any]
+id : str
+raw_text : str
+category : str
+matched_job : Optional[Job]
+matched_job_id : Optional[str]
+job_location : Optional[str]
+extracted : Dict[str, Any]
+formatted_message : str
}
NoticeFormatterService --> PostState : "manages"

Content transformation pipeline#

The pipeline transforms raw HTML content through multiple stages, each with specific responsibilities:

1. Text Extraction: Converts HTML to plain text while preserving structure
2. Classification: LLM-driven categorization using strict labeling rules
3. Job Matching: Entity extraction and fuzzy matching against job listings
4. Enrichment: Optional detailed job retrieval for matched entries
5. Structured Extraction: Category-specific JSON parsing with validation
6. Formatting: Template-based message composition with Telegram compatibility

flowchart TD
Start([Raw Notice Content]) --> Extract["Extract Clean Text"]
Extract --> Classify["LLM Classification"]
Classify --> Match{"Company Names Found?"}
Match --> |Yes| FuzzyMatch["Fuzzy Company Matching"]
Match --> |No| ExtractInfo["Extract Structured Info"]
FuzzyMatch --> Enrich{"Enrich Required?"}
Enrich --> |Yes| EnrichJob["Job Enrichment Callback"]
Enrich --> |No| ExtractInfo
EnrichJob --> ExtractInfo
ExtractInfo --> Format["Category-Specific Formatting"]
Format --> Telegram["Telegram-Compatible Output"]
Telegram --> End([Standardized Message])

Category-Specific formatting templates#

The formatter implements distinct templates for each notice type, so consistent presentation across channels:

Job posting template#

• Header: " Job Posting" with company and role
• Key Sections: Location, CTC with package breakdown, eligibility criteria, hiring flow
• Deadlines: Prominent warning with IST formatting
• Links: Direct job details URL when available

Shortlisting template#

• Header: " Shortlisting Update"
• Lists: Total shortlisted count and student names with enrollment numbers
• Context: Company, role, location, package information
• Process: Hiring flow steps when available

Webinar template#

• Header: " Webinar Details"
• Timing: Flexible date/time formatting with IST timezone
• Venue: Platform or physical location
• Registration: Direct link handling with deadline warnings

Hackathon template#

• Header: " Hackathon"
• Duration: Start/end date formatting
• Structure: Theme, team size, prize pool, venue
• Registration: Deadline and link handling

Announcement template#

• Header: Bold title with passthrough content
• Attribution: Author and timestamp footer
• Minimal Processing: Light cleanup for readability

Integration with telegram message formatting#

The formatter produces content compatible with Telegram’s HTML parsing, with automatic fallback to MarkdownV2 escaping when needed. The Telegram service handles:

• Character limit enforcement (4000 character chunks)
• Automatic message splitting with line-aware boundaries
• Markdown/HTML conversion with special handling for links and headers
• Retry mechanisms with plain text fallback

sequenceDiagram
participant NFS as "NoticeFormatterService"
participant TS as "TelegramService"
participant TG as "Telegram API"
NFS->>TS : send_message(formatted_message, parse_mode="HTML")
alt Message > 4000 chars
TS->>TS : split_long_message(max_length=4000)
loop For each chunk
TS->>TG : sendMessage(parse_mode="HTML")
alt HTML fails
TS->>TG : sendMessage(parse_mode="")
end
end
else Message ≤ 4000 chars
TS->>TG : sendMessage(parse_mode="HTML")
end
TG-->>TS : success/failure

Content cleaning and safety features#

The formatter implements detailed content cleaning to ensure safe, readable output:

• HTML Stripping: BeautifulSoup-based extraction with table parsing and paragraph handling
• Line Normalization: Collapse excessive blank lines and trim trailing whitespace
• Special Character Encoding: Proper handling of non-breaking spaces and Unicode characters
• Link Preservation: Maintains hyperlinks while keeping HTML anchor tags valid
• Markdown Compatibility: Automatic escaping for Telegram MarkdownV2 special characters

Integration with notification delivery system#

The formatted notices integrate smoothly with the broader notification infrastructure:

graph LR
subgraph "Data Sources"
SS[SupersetClientService]
SJ[structured_job_listings.json]
PO[placement_offers.json]
end
subgraph "Processing"
UR[UpdateRunner]
NFS[NoticeFormatterService]
end
subgraph "Storage"
DB[DatabaseService]
end
subgraph "Delivery"
NS[NotificationService]
TS[TelegramService]
WP[WebPushService]
end
SS --> UR
SJ --> UR
PO --> UR
UR --> NFS
NFS --> DB
DB --> NS
NS --> TS
NS --> WP

The Notice Formatter Service maintains loose coupling with external dependencies through well-defined interfaces and typed data models.

graph TB
subgraph "External Dependencies"
LLM[LangChain + Gemini]
BS4[BeautifulSoup4]
RF[rapidfuzz]
TZ[zoneinfo]
end
subgraph "Internal Dependencies"
SC[SupersetClient Models]
DS[DatabaseService]
NS[NotificationService]
TS[TelegramService]
end
NFS[NoticeFormatterService] --> LLM
NFS --> BS4
NFS --> RF
NFS --> TZ
NFS --> SC
NFS --> DS
NFS --> NS
NFS --> TS

The formatter is optimized for production use with several performance-conscious design decisions:

• Selective Enrichment: Jobs are only enriched when matched during notice processing, avoiding unnecessary API calls
• Fuzzy Matching Thresholds: Configurable similarity thresholds (80+) prevent false positives while maintaining accuracy
• State Machine Efficiency: LangGraph minimizes memory overhead through state reuse
• Batch Processing: Support for formatting multiple notices in sequence
• Caching Opportunities: Job lookup dictionaries prevent repeated database queries

Common issues and their resolutions:

LLM parsing failures#

Symptoms: Empty extracted fields or JSON parsing errors Causes:

• LLM output format inconsistencies
• Complex HTML structures causing extraction ambiguity
• Insufficient context for classification

Resolutions:

• Verify LLM prompt templates are properly formatted
• Check HTML content complexity and consider preprocessing
• Monitor classification confidence scores

Telegram message limits#

Symptoms: Truncated messages or delivery failures Causes:

• Messages exceeding 4000 characters
• Improper HTML/Markdown formatting

Resolutions:

• Enable automatic message splitting in TelegramService
• Validate message length before sending
• Test with simplified content first

Job matching issues#

Symptoms: Missed job matches or incorrect fuzzy matches Causes:

• Company name variations in notices vs. job listings
• Low similarity threshold settings
• Missing job enrichment callback

Resolutions:

• Adjust fuzzy matching thresholds (currently >80)
• Implement job enrichment callback for matched entries
• Verify company name normalization

Classify, extract structure, apply per-category templates aimed at Telegram. Add a notice type by extending the maps, not by forking the service.