Skip to main content

Developer Guide

This guide provides an overview of the Style Suggestions feature for developers integrating or maintaining Deepdesk's agent assist capabilities. It includes the full backend documentation and a short overview of how the frontend integrates.

Purpose​

Style Suggestions help agents improve communication by detecting specific keywords or phrases in their messages and providing actionable guidance. The system supports both real-time feedback and analytics for compliance monitoring.

Architecture Overview​

  • Backend exposes a REST API (POST /style-suggestions) for keyword detection.
  • Frontend displays eventual style suggestions to agents and sends a "style suggested" event
  • When agent sends a message, the ingestion pipeline detects eventual style breaks and sends a style breaks found event.

Overview​

Style Suggestions provide guidance to agents based on keyword triggers present in messages. The backend supports two main capabilities:

  1. Synchronous detection via API: POST /style-suggestions returns detected keyword matches for a given profile_code and message.
  2. Asynchronous analytics in ingestion: when agent messages are ingested, the system detects style breaks and emits analytics events to BigQuery and ClickHouse.

The source of truth for suggestions is the Admin (Django) database. The backend reads those records via a repository.

Data model (Pydantic)​

File: backend/domains/style_suggestions/models/style_suggestion.py

class StyleSuggestion(BaseModel):
    id: int
    title: str
    message: str
    keywords: list[str]

The backend receives Django ORM rows and maps them to this Pydantic model (see Repository below).

API​

File: backend/domains/style_suggestions/api/routes.py

Endpoint: POST /style-suggestions

  • Security: jwt_or_oauth, requires scope conversations:read.
  • Body: StyleSuggestionRequest.
  • Response: StyleSuggestionResponse.

Example:

POST /style-suggestions
Authorization: Bearer <token-with-conversations:read>
Content-Type: application/json

{
  "profile_code": "retail-en",
  "message": "We can't process this kind of request right now."
}

Response:

{
  "keyword_matches": [
    {"keyword": "can't", "title": "Avoid negative phrasing", "suggestion": "Try phrasing in positive terms ..."}
  ]
}

Schemas​

File: backend/domains/style_suggestions/api/schemas.py

class StyleSuggestionRequest(BaseModel):
    profile_code: str
    message: str

class KeywordMatch(BaseModel):
    keyword: str
    title: str
    suggestion: str

class StyleSuggestionResponse(BaseModel):
    keyword_matches: list[KeywordMatch]

Repository​

File: backend/domains/style_suggestions/repositories/style_suggestion.py

Responsibilities:

  • Query the Admin (Django) ORM for StyleSuggestion objects associated with a Profile code.
  • Map ORM instances to Pydantic StyleSuggestion models.
  • Provide both sync (get_by_profile_code) and async (aget_by_profile_code) variants.

Service​

File: backend/domains/style_suggestions/services/style_suggestion_service.py

Responsibilities:

  • For a profile_code and message, load suggestions via the repository.
  • Run detection using StyleDetector.
  • Return a list of KeywordMatch.

Detecting style breaks​

File: backend/tasks.py — function publish_style_break_events

Flow:

  1. Validate the Conversation object has profile_code; return early if absent.
  2. Load style suggestions for that profile_code via the repository.
  3. Filter to agent-authored messages.
  4. Run detection with StyleDetector for each agent message.
  5. If matches exist, emit a BigQueryStyleBreakEvent per affected message.

Detection logic​

File: backend/domains/style_suggestions/services/style_detector.py

Summary of behavior:

  • Case-insensitive regex search.
  • Enforces non-word boundaries so partial words do not trigger (e.g., can won’t match inside candy).
  • Multi-word keywords are supported; spaces in the keyword are matched with \s+ so flexible whitespace is allowed.
  • Quote characters in keywords are relaxed to match similar quote styles.
  • Occurrences wrapped in curly braces { ... } are ignored via negative lookbehind/lookahead (to avoid matching templated placeholders).

Output is a list of KeywordMatch { keyword, title, suggestion } where keyword is the matched substring from the message.

Analytics​

For reporting we track style suggestion usage and compliance. When the backend detects style breaks in agent messages, it emits the style breaks found event to the analytics pipeline. These events help monitor the detection of style issues and the delivery of guidance to agents.

Destinations:

  • BigQuery dataset/table: {PROJECT}.{ACCOUNT_CODE}_analytics_dataset.events_v2 via google.cloud.bigquery.Client.insert_rows_json.
  • ClickHouse events table via insert_rows_into_clickhouse.delay(...).

Deprecated We are in the process of migrating to a ClickHouse-based analytics pipeline, so the BigQuery destination is still used for now.

Event payload:

  • Model: BigQueryStyleBreakEvent in backend/tasks.py.
  • Fields: event_id, conversation_id, profile_code, platform_session_id, platform, agent_* fields, time_utc (ISO 8601), and data JSON string containing {"style_breaks": [{"title", "trigger"}]}.

Info The event payload contains the external agent ID, as received from the CX platform.

Operational notes​

  • Only suggestions that are ENABLED and associated to the relevant Profiles (configured in Studio) will be effective.
  • Curate keyword lists to minimize false positives; prefer specific phrases where possible.
  • For dynamic placeholders in templates, wrap them in {} to avoid matching as style breaks.
  • See tests under backend/tests/domains/style_suggestions/ for examples and edge cases.