AaronPo/the-biergarten-app
1
0
Fork 0
mirror of https://github.com/aaronpo97/the-biergarten-app.git synced 2026-05-31 17:53:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add localized name/description to data models

Browse Source
This commit is contained in:
Aaron Po
2026-04-17 22:08:26 -04:00
parent fcc7a5dc8b
commit f782fdb51d
8 changed files with 181 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
pipeline/biergarten_pipeline.puml
View File

@@ -66,8 +66,10 @@ package "Data models" {
}
class BreweryResult <<struct>> {
+name: std::string
+description: std::string
+name_en: std::string
+description_en: std::string
+name_local: std::string
+description_local: std::string
}
class UserResult <<struct>> {

9
pipeline/includes/data_generation/llama_generator_helpers.h
View File

@@ -12,6 +12,8 @@
#include <string>
#include <string_view>
#include "data_model/brewery_result.h"
struct llama_vocab;
using llama_token = int32_t;
@@ -39,13 +41,10 @@ void AppendTokenPiece(const llama_vocab* vocab, llama_token token,
* @brief Validates and parses brewery JSON output.
*
* @param raw Raw model output.
* @param name_out Parsed brewery name.
* @param description_out Parsed brewery description.
* @param brewery_out Parsed brewery payload.
* @return Validation error message if invalid, or std::nullopt on success.
*/
std::optional<std::string> ValidateBreweryJson(const std::string& raw,
std::string& name_out,
std::string& description_out,
std::string& reasoning_out);
BreweryResult& brewery_out);
#endif // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_

14
pipeline/includes/data_model/brewery_result.h
View File

@@ -12,11 +12,17 @@
* @brief Generated brewery payload.
*/
struct BreweryResult {
/// @brief Brewery display name.
std::string name{};
/// @brief Brewery display name in English.
std::string name_en;
/// @brief Brewery description text.
std::string description{};
/// @brief Brewery description text in English.
std::string description_en;
/// @brief Brewery display name in the local language.
std::string name_local;
/// @brief Brewery description text in the local language.
std::string description_local;
};
#endif // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_BREWERY_RESULT_H_

75
pipeline/prompts/system.md
View File

@@ -1,7 +1,3 @@
Return only one raw JSON object as the final answer, with exactly three keys: "reasoning", "name", and "description".
The "reasoning" key MUST be the first key in the object.
No markdown, code fences, preamble, or extra keys.
# FULL SYSTEM PROMPT
You are an expert brewery copywriter, an architectural observer, and a master of zymurgy.
@@ -26,32 +22,36 @@ $$Information about local beer culture, history, or geography$$
ABSOLUTELY NO MARKDOWN FORMATTING. Do NOT wrap your response in json or ``` blocks.
NO PREAMBLE OR POSTSCRIPT outside the JSON object. Do not say "Here is the JSON" or "Enjoy!".
Do not add markdown, code fences, or postscript around the final JSON object. Do not say "Here is the JSON" or "Enjoy!".
The JSON must contain exactly three keys ("reasoning", "name", and "description"); do not rename or add any other keys.
The JSON must contain exactly four keys ("name_en", "description_en", "name_local", "description_local") in that order. Do not rename or add any other keys.
The "reasoning" key MUST be first in the object.
ESCAPE ALL QUOTES inside all description fields using \", or use single quotes (' ') instead. This applies equally to description_en and description_local. If the local language uses non-standard quotation marks (such as guillemets or corner brackets), write them as literal Unicode characters rather than escaped HTML entities, and do not nest them inside double quotes without escaping.
ESCAPE ALL QUOTES inside the description using ", or use single quotes (' ') instead. Escaping quotes perfectly is super important to avoid errors later.
DO NOT use actual line breaks (\n) inside any string. Keep all descriptions as one continuous string each.
DO NOT use actual line breaks (\n) inside the string. Keep the description as one continuous string.
The description_en and description_local must each be between 225 and 300 words. Do not pad with repetition or summary, every sentence must earn its place. Be concise and specific.
Expected JSON format:
```json
{
"reasoning": "Briefly plan the environmental hook, the technical brewing detail, the architectural detail, and the objective invitation.",
"name": "Fictional Local Brewery Name",
"description": "The description goes here."
"name_en": "Fictional Local Brewery Name in English",
"description_en": "The English description goes here.",
"name_local": "Translated brewery name in the local language",
"description_local": "The localised description goes here."
}
```
## CONTENT RULES AND CONSTRAINTS:
### THE HOOK:
The first sentence must be an immersive, sensory environmental hook. It needs to clearly establish the weather, smells, or sounds typical of that city. Do not start by using the brewery's name or standard welcoming phrases.
The first sentence must be a sensory environmental hook written as a personal observation, something the owner notices or has always noticed. It should establish the local weather, smell, or soundscape of the city. Do not open with the brewery's name or a generic welcome.
### GEOGRAPHIC & CULTURAL ANCHOR:
The story must be deeply tied to the provided geographic and cultural info. It should mix historical brewing facts with the gritty reality of modern craft brewing, making sure it fits the local culture perfectly.
The story must be deeply tied to the provided geographic and cultural info. Weave in one or two specific historical or cultural details that ground the brewery in its place, enough to feel local, not so much that it reads like a history lesson.
### TECHNICAL BREWING DETAIL (VARY THIS!):
@@ -59,15 +59,25 @@ You must include one highly specialized technical brewing detail. To avoid sound
### ARCHITECTURAL DETAIL (VARY THIS!):
You must include one specific architectural or environmental detail, highlighting the building's physical wear, structure, or history. Examples include rusty steel beams, weird acoustics from an old factory, decaying brickwork, or worn-out local infrastructure. Avoid overused industry clichés like repurposed dairy equipment or glycol chillers.
You must include one specific architectural or environmental detail, highlighting the building's physical wear, structure, or history. The owner should describe it with personal familiarity, something they've lived with long enough to stop noticing, then started noticing again. Avoid overused industry clichés like repurposed dairy equipment or glycol chillers.
### THE INVITATION:
The last sentence must be an atmospheric invitation to hang out in the space, kept totally objective. Good examples include suggesting where to stand, like "Observation may commence near the foundational supports," or "Positioning adjacent to the exterior loading apparatus is suggested." Avoid regular sayings like telling people to grab a seat or ask the bartender.
The last sentence must be a personal, low-key invitation from the owner, specific about place, not generic about the experience. The owner should point somewhere concrete rather than issuing a formal welcome. Avoid clichés like "come find us," "stop by anytime," "grab a stool," or "ask the bartender."
### LOCAL LANGUAGE VERSION:
name_local is a direct translation of name_en into the local language or script.
description_local carries the same content and structure as description_en but should read as though written by an owner who assumes their reader shares the local cultural context, references that needed explaining in English can be stated plainly, and phrasing should reflect natural idiom in that language rather than translated English sentence structure.
The length and anti-AI-pattern requirements apply equally to description_local.
The register of description_local should match the local variant of the language appropriate to the city, québécois French for Montréal, Belgian French for Brussels, castilian Spanish for Madrid, rioplatense Spanish for Buenos Aires, and so on.
### THE BLOCKLIST (FORBIDDEN CONCEPTS):
You absolutely cannot use the following words and phrases because they are overused and too casual. Make sure your final output doesn't have any of these:
You absolutely cannot use the following words and phrases. Make sure your final output doesn't have any of these:
- "hidden gem"
- "passion"
@@ -79,19 +89,40 @@ You absolutely cannot use the following words and phrases because they are overu
- "mash temperature"
- "grab a stool"
- "ask the bartender"
- "come find us"
- "stop by anytime"
#### FORBIDDEN WRITING PATTERNS
The following patterns are common AI writing pitfalls and must not appear in either description:
- Negative parallelism constructions: "It's not X, it's Y" or "We're not about X, we're about Y"
- Inflated significance phrases: "stands as a testament," "plays a vital role," "leaves a lasting impact," "watershed moment," "deeply rooted," "rich cultural heritage," "rich cultural tapestry," "enduring legacy"
- Superficial trailing analyses: sentences ending in -ing words that add opinion without content ("ensuring consistency," "reflecting the city's spirit," "highlighting our commitment")
- Promotional travel-copy tone: "breathtaking," "must-visit," "stunning," "vibrant"
- Overused conjunctive transitions used as sentence openers: "Moreover," "Furthermore," "In addition," "In contrast"
- Rule of three: do not consistently organise ideas or examples in triplets
### VOICE & PERSPECTIVE:
The description must be written strictly in the third-person objective. You need to act like a detached architectural observer looking at the space and the brewing process from the outside. Do not use first-person or second-person pronouns, keeping an atmosphere of academic distance and professionalism.
The description must be written in the first person, from the perspective of the brewery's owner. Favour "we" and "our" over "I" and "my." The owner may use "I" sparingly for personal observations that only they could make, but the default register should be collective. The tone should feel lived-in and a little weathered. Do not use third-person or second-person pronouns.
## EXAMPLE:
Input:
CITY: Sapporo
COUNTRY: Japan
CONTEXT: Sapporo is the capital of Hokkaido, Japan's northernmost main island, with a subarctic climate: winters are severe and protracted, with the city averaging over 6 metres of cumulative snowfall per season...
CITY: Montréal
COUNTRY: Canada
CONTEXT: Montréal has been brewing since 1646 when Jesuit Brother Ambroise first introduced brewing to New France. By the 19th century, Pointe-Saint-Charles became the industrial heart of the city, home to railway yards, canal workers, and a tavern on nearly every block. Molson, one of North America's oldest commercial breweries, has operated on the St. Lawrence since 1786. By the early 1980s, Molson, Labatt, and Carling controlled 96% of the Quebec beer market. The craft revival began slowly in the late 1980s and has accelerated sharply since 2002, when 33 brewing companies have grown to over 300 province-wide.
$$Truncated for brevity, but assumes full context provided$$
Output:
{ "name": "Tokachi Grain & Ferment", "description": "By February, the powder snow blowing off the Teine range buries the bicycle racks on Susukino's side streets to the crossbar. Sapporo has been in the business of serious lager since 1876, but Tokachi Grain & Ferment isn't interested in replicating the macro-brew legacy. Instead, they source base malt exclusively from Obihiro-area farms and run the entire grain bill through a rigorous Burtonization protocol, driving up calcium sulfate levels to pull a sharp, mineral snap into the finish. The taproom is carved from a former Meiji-era goods shed, where a single run of oxidized copper piping bisects the ceiling and weeps green verdigris onto the communal timber table below. Observation may commence beneath the deteriorating copper, where the pale ale may be procured while the surrounding acoustics are analyzed." }
```json
{
"name_en": "Canal Street Grain & Ferment",
"description_en": "In February the wind off the Lachine Canal has a particular quality, wet and cold in a way that feels industrial, like it's been sitting in the lock chambers since the last barge went through. Pointe-Saint-Charles used to be called the neighbourhood of a hundred taverns, and you can still see the old storefronts with sealed windows and faded signage for brands that haven't existed in forty years. We started in 2019 in a former rail maintenance shed two streets from the canal. The inspection pit where mechanics used to work under locomotives is still in the floor, we covered it with plate steel, and on cold nights it hums from the temperature differential. Our house ale runs through a turbid mash borrowed loosely from Belgian lambic practice, never fully clarified before fermentation, which keeps the mouthfeel thick through a long cold secondary. It took two winters to dial in. The plate steel end of the room is where things tend to get quiet on a slow Tuesday.",
"name_local": "Fermentation rue du Canal",
"description_local": "En février, le vent du canal Lachine a quelque chose de particulier, humide et froid d'une façon qui sent le fer et le béton mouillé. La Pointe s'appelait autrefois le quartier aux cent tavernes, et on voit encore les vieilles devantures aux fenêtres condamnées, avec leurs enseignes pour des marques disparues depuis quarante ans. On a ouvert en 2019 dans un ancien hangar d'entretien ferroviaire à deux rues du canal. La fosse d'inspection où les mécaniciens travaillaient sous les locomotives est encore là dans le plancher, on l'a recouverte d'une plaque d'acier qui vibre les soirs de grand froid. Notre ale maison passe par un empâtage trouble inspiré de la pratique lambic belge, jamais complètement clarifié avant la fermentation, ce qui garde une belle rondeur en bouche après une longue garde à froid. Ça nous a pris deux hivers à stabiliser. Le bout de la salle côté plaque d'acier, c'est là que ça se calme les mardis tranquilles."
}
```

8
pipeline/src/biergarten_data_generator/log_results.cc
View File

@@ -16,8 +16,12 @@ void BiergartenDataGenerator::LogResults() const {
"iso3166_2={} lat={} lon={}",
index, location.city, location.country, location.state_province,
location.iso3166_2, location.latitude, location.longitude);
spdlog::info(" brewery_name=\"{}\"", brewery.name);
spdlog::info(" brewery_description=\"{}\"", brewery.description);
spdlog::info(" brewery_name_en=\"{}\"", brewery.name_en);
spdlog::info(" brewery_description_en=\"{}\"",
brewery.description_en);
spdlog::info(" brewery_name_local=\"{}\"", brewery.name_local);
spdlog::info(" brewery_description_local=\"{}\"",
brewery.description_local);
++index;
}
}

23
pipeline/src/data_generation/llama/generate_brewery.cc
View File

@@ -17,7 +17,8 @@
#include "data_generation/llama_generator_helpers.h"
static constexpr std::string_view kBreweryJsonGrammar = R"json_brewery(
root ::= ws "{" ws "\"reasoning\"" ws ":" ws string ws "," ws "\"name\"" ws ":" ws string ws "," ws "\"description\"" ws ":" ws string ws "}" ws
root ::= thought-block "{" ws "\"name_en\"" ws ":" ws string ws "," ws "\"description_en\"" ws ":" ws string ws "," ws "\"name_local\"" ws ":" ws string ws "," ws "\"description_local\"" ws ":" ws string ws "}" ws
thought-block ::= [^{]*
ws ::= [ \t\n\r]*
string ::= "\"" char+ "\""
char ::= [^"\\\x7F\x00-\x1F] | [\\] escape
@@ -75,25 +76,24 @@ BreweryResult LlamaGenerator::GenerateBrewery(
for (int attempt = 0; attempt < max_attempts; ++attempt) {
// Generate brewery data from LLM
raw = this->Infer(system_prompt, user_prompt, max_tokens, kBreweryJsonGrammar);
spdlog::debug("LlamaGenerator: raw output (attempt {}): {}", attempt + 1,
spdlog::info("LlamaGenerator: raw output (attempt {}): {}", attempt + 1,
raw);
// Validate output: parse JSON and check required fields
std::string name;
std::string description;
std::string reasoning;
BreweryResult brewery;
const std::optional<std::string> validation_error =
ValidateBreweryJson(raw, name, description, reasoning);
ValidateBreweryJson(raw, brewery);
if (!validation_error.has_value()) {
// Success: return parsed brewery data
spdlog::info(
"LlamaGenerator: successfully generated brewery data on attempt {}:\n reasoning='{}',\n name='{}',\n description='{}'",
attempt + 1, reasoning, name, description);
"LlamaGenerator: successfully generated brewery data on attempt {}:\n name_en='{}',\n description_en='{}',\n name_local='{}',\n description_local='{}'",
attempt + 1, brewery.name_en, brewery.description_en,
brewery.name_local, brewery.description_local);
return BreweryResult{.name = std::move(name),
.description = std::move(description)};
return brewery;
}
// Validation failed: log error and prepare corrective feedback
@@ -111,14 +111,13 @@ BreweryResult LlamaGenerator::GenerateBrewery(
"LlamaGenerator: detected truncated JSON; increasing max_tokens from {} to {} and retrying",
previous_max_tokens, max_tokens);
continue;
}
// Update prompt with error details to guide LLM toward correct output.
user_prompt = std::format(
R"(Your previous response was invalid. Error: {}
Return ONLY valid JSON with exactly these keys, in this exact order: {{"reasoning": "<brief planning summary>", "name": "<brewery name>", "description": "<single-paragraph description>"}}.
Return the thought process before the JSON if needed, then return ONLY valid JSON with exactly these keys, in this exact order: {{"name_en": "<English brewery name>", "description_en": "<English single-paragraph description>", "name_local": "<local-language brewery name>", "description_local": "<local-language single-paragraph description>"}}.
Do not include markdown, comments, extra keys, or literal placeholder values.
Keep the JSON strings concise enough to fit within the token budget.

133
pipeline/src/data_generation/llama/helpers.cc
View File

@@ -115,90 +115,101 @@ void AppendTokenPiece(const llama_vocab* vocab, llama_token token,
"LlamaGenerator: failed to decode sampled token piece");
}
std::optional<std::string> ValidateBreweryJson(const std::string& raw,
std::string& name_out,
std::string& description_out,
std::string& reasoning_out) {
auto validate_object = [&](const boost::json::value& json_value,
std::string& error_out) -> bool {
if (!json_value.is_object()) {
error_out = "JSON root must be an object";
static bool ReadRequiredTrimmedStringField(const boost::json::object& obj,
std::string_view key,
std::string& out,
std::string* error_out) {
const boost::json::value* field = obj.if_contains(key);
if (field == nullptr || !field->is_string()) {
if (error_out != nullptr) {
*error_out = "JSON field '" + std::string(key) +
"' is missing or not a string";
}
return false;
}
const auto& obj = json_value.get_object();
if (!obj.contains("reasoning") || !obj.at("reasoning").is_string()) {
error_out = "JSON field 'reasoning' is missing or not a string";
const auto& string_value = field->as_string();
out = Trim(std::string_view(string_value.data(), string_value.size()));
if (out.empty()) {
if (error_out != nullptr) {
*error_out = "JSON field '" + std::string(key) + "' must not be empty";
}
return false;
}
if (!obj.contains("name") || !obj.at("name").is_string()) {
error_out = "JSON field 'name' is missing or not a string";
return false;
return true;
}
if (!obj.contains("description") || !obj.at("description").is_string()) {
error_out = "JSON field 'description' is missing or not a string";
return false;
}
const auto& reasoning_value = obj.at("reasoning").as_string();
reasoning_out = Trim(std::string_view(reasoning_value.data(), reasoning_value.size()));
if (reasoning_out.empty()) {
error_out = "JSON field 'reasoning' must not be empty";
return false;
}
const auto& name_value = obj.at("name").as_string();
const auto& description_value = obj.at("description").as_string();
name_out = Trim(std::string_view(name_value.data(), name_value.size()));
description_out = Trim(
std::string_view(description_value.data(), description_value.size()));
if (name_out.empty()) {
error_out = "JSON field 'name' must not be empty";
return false;
}
if (description_out.empty()) {
error_out = "JSON field 'description' must not be empty";
return false;
}
std::string name_lower = name_out;
std::string description_lower = description_out;
auto string_to_lower = [](std::string& str_out) {
std::ranges::transform(str_out, str_out.begin(),
static bool HasSchemaPlaceholder(const std::array<std::string*, 4>& values) {
for (const std::string* value : values) {
std::string lowered = *value;
std::ranges::transform(lowered, lowered.begin(),
[](unsigned char character) {
return static_cast<char>(std::tolower(character));
});
};
string_to_lower(name_lower);
string_to_lower(description_lower);
if (lowered == "string") {
return true;
}
}
if (name_lower == "string" || description_lower == "string") {
error_out = "JSON appears to be a schema placeholder, not content";
return false;
}
error_out.clear();
return true;
};
std::optional<std::string> ValidateBreweryJson(const std::string& raw,
BreweryResult& brewery_out) {
boost::system::error_code error_code;
boost::json::value json_value = boost::json::parse(raw, error_code);
std::string validation_error;
const std::string_view raw_view(raw);
const size_t opening_brace = raw_view.find('{');
if (opening_brace == std::string_view::npos) {
return "JSON parse error: missing opening brace '{'";
}
const std::string_view json_payload = raw_view.substr(opening_brace);
boost::json::value json_value = boost::json::parse(json_payload, error_code);
if (error_code) {
return "JSON parse error: " + error_code.message();
}
if (!validate_object(json_value, validation_error)) {
if (!json_value.is_object()) {
return "JSON root must be an object";
}
const auto& obj = json_value.get_object();
if (obj.size() != 4) {
return "JSON object must contain exactly four keys";
}
std::string validation_error;
if (!ReadRequiredTrimmedStringField(obj, "name_en", brewery_out.name_en,
&validation_error)) {
return validation_error;
}
if (!ReadRequiredTrimmedStringField(obj, "description_en",
brewery_out.description_en,
&validation_error)) {
return validation_error;
}
if (!ReadRequiredTrimmedStringField(obj, "name_local",
brewery_out.name_local,
&validation_error)) {
return validation_error;
}
if (!ReadRequiredTrimmedStringField(obj, "description_local",
brewery_out.description_local,
&validation_error)) {
return validation_error;
}
const std::array<std::string*, 4> schema_placeholders = {
&brewery_out.name_en, &brewery_out.description_en,
&brewery_out.name_local, &brewery_out.description_local};
if (HasSchemaPlaceholder(schema_placeholders)) {
return "JSON appears to be a schema placeholder, not content";
}
return std::nullopt;
}

6
pipeline/src/data_generation/mock/generate_brewery.cc
View File

@@ -36,7 +36,9 @@ BreweryResult MockGenerator::GenerateBrewery(
state_suffix, country_suffix);
return {
.name = name,
.description = description,
.name_en = name,
.description_en = description,
.name_local = name,
.description_local = description,
};
}