HG API

Terminology

The key words “MUST”, “SHOULD”, “NOT RECOMMENDED”, and “MAY” in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.

Transport

FE to BE communicate using a websocket connection and use JSON for message serialization

FE -> BE

Send Prompt

{
    "prompt": "Who plays Katniss?"
}

Reengagement

After a certain time, the FE will send a request to get user information. It signals that the BE should reply with questions such as: “What was your favorite movie of the franchise?”

{
    "ext": "reengage"
}

BE -> FE

{
  "data": "Jennifer Lawrence brings to life the character of Katniss Everdeen in \"The Hunger Games\" film series, captivating audiences with her powerful portrayal. Known for her resilience and sharp survival skills, Katniss becomes a symbol of hope and rebellion against oppression. Lawrence's performance has been pivotal, earning acclaim for her depth and authenticity in the role.<p>[[Asset-0]]<p>Preparing for Katniss required Lawrence to undergo intense physical training and archery lessons, immersing herself in the character's world. This preparation helped her convincingly navigate the physical and emotional landscapes of the dystopian setting, from the perilous Hunger Games arena to the complexities of her relationships.<p>Jennifer Lawrence's role as Katniss Everdeen not only showcased her acting range but also significantly boosted her career, establishing her as a leading actress in Hollywood. Her portrayal resonates with fans for its strength and vulnerability, making Katniss a memorable and inspiring character.",
  "assets": [
    {
      "url": "https://en.wikipedia.org/wiki/Katniss_Everdeen#/media/File:Katniss_Everdeen.jpg",
      "title": "Katniss Everdeen, as portrayed by Jennifer Lawrence in the film the Hunger Games",
      "metadata":{"height":1365,"width":2048,"type":"image"}
    }
  ],
  "followup": [
    "How did Jennifer Lawrence prepare for the role of Katniss Everdeen?",
    "What were the challenges Jennifer Lawrence faced while filming \"The Hunger Games\"?"
  ]
}
  1. Reply MUST be a valid JSON object
  • data field MAY be omitted. It defaults to “”.
  • assets field MAY be omitted. It defaults to [].
  • followup field MAY be omitted. It defaults to [].
  1. Paragraphs SHOULD begin with <p>. (The first paragraph MAY not have it)
  2. Paragraphs after assets MAY not begin with <p>
  3. Assets MUST be images or videos
  4. References to assets MUST be [[Asset-#]]. The # is the index of the asset in the assets array
  5. Assets MUST have a url
  6. Assets SHOULD have a title
  7. Follow up MUST be simple text (no markup)
Info

The parser splits the data field using a regex that matches <p> or [[Asset-#]]. Strings between these separators are paragraphs, and [[Asset-#]] emits an asset. Empty paragraphs are removed.

Image Metadata

  • Assets SHOULD have a metadata field that indicates height, width and type. If absent, the FE will get the dimensions from the data (but it may cause a suboptimal UX) and the type defaults to “image”
  • type MUST be either “image” or “video”
metadata":{"height":1365,"width":2048,"type":"image"}

Content Feed

  1. The first reply from the server MUST be the content feed. It MAY have no data. The client will ignore the data field
  2. It SHOULD have assets. If not, the content feed is empty. The content feed is the array of assets
  3. It SHOULD have followups
  4. Assets and followup requirements from previous section apply
Note

Even though the content feed has an empty data field, it assumed to reference to every asset, i.e. [[Asset-0]][[Asset-1]][[Asset-2]]…

{
  "assets": [
    {
      "url": "https://en.wikipedia.org/wiki/Katniss_Everdeen#/media/File:Katniss_Everdeen.jpg",
      "title": "Katniss Everdeen, as portrayed by Jennifer Lawrence in the film the Hunger Games"
    }
  ],
  "followup": [
    "How did Jennifer Lawrence prepare for the role of Katniss Everdeen?",
    "What were the challenges Jennifer Lawrence faced while filming \"The Hunger Games\"?"
  ]
}

Get Followup of Content Feed Image

When the user selects an image from the content feed and switches to the chat, the FE MUST display a list of followup questions.

The FE will send a GetFollowupRequest request to the BE and expects a GetFollowupResponse

GetFollowupRequest

{
  "get_followup": "https://en.wikipedia.org/wiki/Katniss_Everdeen#/media/File:Katniss_Everdeen.jpg"
}

The content of the get_followup is the URL of the asset as returned in the content feed.

GetFollowupResponse

{
  "followup": [
    "How did Jennifer Lawrence prepare for the role of Katniss Everdeen?",
    "What were the challenges Jennifer Lawrence faced while filming \"The Hunger Games\"?"
  ]
}

Keep Alive (Ping/Pong)

The FE will periodically send a ping message and expects to receive a pong message.

Ping

{
  "ping": null
}

Pong

{
  "pong": null
}

Sequence

sequenceDiagram
    FE->>BE: WS Connect
    BE-->>FE: Content Feed
    loop repeat
    FE->>BE: Prompt
    BE-->>FE: Reply
    end
    FE->>BE: Reengage (When 30s elapsed without interaction)
    BE-->>FE: Prompt