data/meltmind/JSON_AUTHORING_GUIDE.md

MeltMind JSON Authoring Guide

This guide explains every JSON file inside data/meltmind/, what information belongs in it, and how detailed each answer should be.

You may continue answering the easier Markdown forms inside answers/. Edit the JSON files directly only when you are comfortable with JSON syntax.

JSON basics

Text values

Text must be inside double quotes:

"plain_explanation": "A warm, fudgy brownie with a soft centre."

Use one or two factual sentences for short explanations. Detailed descriptions may contain several sentences.

Numbers

Numbers must not use quotes, currency symbols, commas, or percentage signs:

"price_inr": 30,
"serves_min": 1,
"comfort_food_score": 90

Yes, no, and unknown

Use real JSON booleans when a field expects yes or no:

"made_to_order": true,
"easy_to_share": false,
"premium_add_on": null

Use null when a factual value has not been verified. Do not write "null", "unknown", or an empty string in boolean or numeric fields.

Some dietary fields intentionally use the controlled text values "yes", "no", and "unknown".

Lists

Use arrays for multiple values:

"textures": [
  "gooey",
  "soft",
  "slightly crunchy"
]

Do not write comma-separated lists inside one string:

"textures": "gooey, soft, crunchy"

IDs

IDs connect information across files. Use lowercase snake case:

"product_id": "pistachio_royale",
"ingredient_id": "pistachio_cream",
"add_on_id": "extra_chocolate_sauce"

References must exactly match the ID used in the source file.

Dates

Use YYYY-MM-DD:

"last_verified_date": "2026-06-10"

Duplicating entries

When adding another product, ingredient, FAQ, example, or test:

1. Copy the complete object between { and }.
2. Add a comma after the previous object.
3. Change its ID and contents.
4. Keep all field names unchanged.

How detailed should information be?

Prefer specific, decision-useful facts.

Weak:

"plain_explanation": "A tasty brownie."

Strong:

"plain_explanation": "A single-serve fudgy brownie with a soft centre and a lightly crisp top, designed for customers who want a straightforward chocolate dessert."

Weak:

"best_for_customer_preferences": [
  "chocolate lovers"
]

Strong:

"best_for_customer_preferences": [
  "customers who want a classic chocolate-first dessert",
  "customers who prefer a soft centre with a lightly crisp top",
  "first-time MeltRoom customers who want a simple starting point"
]

Do not add promotional claims that cannot be verified.

---

File Guide

product_knowledge.json

Purpose

This is the most important MeltMind knowledge file. It contains deep facts for every product and powers:

• Product explanations
• Product comparisons
• Preference matching
• Allergy and dietary answers
• Pairings and add-ons
• Serving recommendations

Create one complete object inside products for every product in data/menu.json.

Do not enter prices or image paths here.

product_id and product_name

• product_id: Stable snake-case identifier used by other files.
• product_name: Must exactly match the name in data/menu.json.

identity

• tagline: Short emotional line, ideally 3–8 words.
• plain_explanation: Literal explanation for someone unfamiliar with it.
• sales_description: Attractive but truthful description.
• what_makes_it_different: Concrete distinction from similar products.
• signature_components: Most defining ingredients or components.
• customer_friendly_keywords: Searchable words customers may use.
• common_customer_names: Nicknames, shortened names, or common misspellings.

sensory_profile

• sweetness: low, balanced, high, or very_high.
• chocolate_intensity: none, low, medium, high, or very_high.
• richness: Same intensity scale.
• flavour_notes: All noticeable flavours.
• primary_flavour: The most dominant flavour.
• secondary_flavours: Supporting flavours.
• textures: Every meaningful texture experienced while eating.
• temperature_served: Example: "warm" or "chilled".
• aroma_notes: Smells noticeable before or while eating.
• aftertaste: What remains after the bite.
• portion_feeling: Example: "light snack", "satisfying", or "very filling".

composition

Enter what is physically inside the product:

• ingredient_ids: IDs from ingredients.json.
• base: Main foundation.
• filling: Interior filling, or an empty string if none.
• toppings: Visible finishing components.
• sauces: Included sauces.
• contains_ice_cream: true, false, or null.
• preparation_summary: Clear preparation explanation.
• made_to_order: true, false, or null.

serving

• serves_min and serves_max: Realistic numeric serving range.
• portion_description: Explain portion size in customer-friendly language.
• easy_to_share: Whether it can practically be shared.
• travel_friendly: Whether it survives transport well.
• best_eaten_within_minutes: Number of minutes, or null.
• storage_guidance: Verified storage and reheating advice.

The public data/menu.json file also contains can_be_served_for. Enter a short customer-facing range such as "1 person", "1-2 people", or "2-3 people". This value should agree with serves_min and serves_max.

dietary_and_safety

This section must be verified by MeltRoom.

• Dietary fields use "yes", "no", or "unknown".
• allergen_ids: Confirmed allergens from ingredients.json.
• possible_cross_contact_allergen_ids: Possible kitchen cross-contact.
• removable_allergen_ids: Allergens that can genuinely be removed.
• non_removable_allergen_ids: Allergens inherent to the product.
• allergy_customer_message: Exact approved response MeltMind should provide.

recommendation_profile

Use descriptive phrases rather than isolated words:

• best_for_moods: Examples: "comfort after a stressful day".
• best_for_occasions: Examples: "casual solo treat", "birthday sharing".
• best_for_group_types: Examples: "one person", "friends sharing".
• best_for_customer_preferences: Specific reasons someone would like it.
• avoid_for_preferences: Reasons it may be unsuitable.
• Score fields should be numbers from 0 to 10.

pairing_and_customization

Use exact IDs:

• compatible_add_on_ids: Add-ons that can be ordered with it.
• recommended_add_on_ids: Best add-ons, not every possible add-on.
• recommended_product_ids: Products that pair well.
• not_recommended_with_product_ids: Pairings that are redundant or poor.
• customization_notes: Real customization possibilities.
• upsell_reason: Honest reason an add-on improves the experience.

comparison_guidance

This helps Chat with MeltMind answer questions like “Which is sweeter?”

• List similar, richer, lighter, sweeter, and less-sweet product IDs.
• Write full comparison facts in comparison_talking_points.

owner_notes

Record real staff and customer knowledge:

• Why it sells well
• Common praise
• Common confusion
• Common objections
• How experienced staff explains it
• Who verified the information and when

Example

{
  "product_id": "example_brownie",
  "product_name": "Example Brownie",
  "identity": {
    "tagline": "The classic chocolate beginning",
    "plain_explanation": "A single-serve fudgy brownie with a soft centre and lightly crisp top.",
    "sales_description": "A warm, chocolate-first classic made for straightforward comfort.",
    "what_makes_it_different": "It has no heavy toppings, making the brownie itself the focus.",
    "signature_components": [
      "fudgy brownie base"
    ],
    "customer_friendly_keywords": [
      "classic",
      "simple",
      "fudgy"
    ],
    "common_customer_names": [
      "original brownie"
    ]
  }
}

---

ingredients.json

Purpose

Contains the ingredient and allergen truth used for explanations and safety checks.

allergen_catalogue

Create one entry for every relevant allergen:

• allergen_id: Stable ID used across all files.
• display_name: Customer-friendly name.
• customer_warning: Approved general warning.
• cross_contact_possible: true, false, or null.

ingredients

Create entries for meaningful ingredients and prepared components, such as:

• Brownie base
• Chocolate sauce
• Pistachio cream
• Ice cream
• Cookie crumble

Fields:

• ingredient_type: Example: "base", "sauce", "topping", "filling".
• plain_explanation: What it is.
• why_meltroom_uses_it: Why it matters to the product.
• flavour_contribution and texture_contribution: Arrays of specific effects.
• quality_or_sourcing_notes: Only verified quality or sourcing information.
• allergen_ids: IDs from allergen_catalogue.
• dietary_labels: Example: "vegetarian" or "eggless".
• used_in_product_ids: Every product containing it.
• can_be_removed_after_ordering: Whether staff can omit it.
• customer_faq_notes: Useful facts customers commonly ask about.

Example:

{
  "ingredient_id": "example_chocolate_sauce",
  "name": "Example Chocolate Sauce",
  "ingredient_type": "sauce",
  "plain_explanation": "A smooth chocolate sauce added as a finishing drizzle.",
  "why_meltroom_uses_it": "It increases chocolate intensity and adds a glossy, soft finish.",
  "flavour_contribution": [
    "deep chocolate"
  ],
  "texture_contribution": [
    "smooth",
    "saucy"
  ],
  "quality_or_sourcing_notes": "",
  "allergen_ids": [
    "milk"
  ],
  "dietary_labels": [
    "vegetarian"
  ],
  "used_in_product_ids": [],
  "can_be_removed_after_ordering": true,
  "customer_faq_notes": []
}

---

add_ons.json

Purpose

Defines only the customizations customers can actually purchase.

Enter one object for each add-on:

• add_on_id: Stable snake-case ID.
• name: Customer-facing name.
• price_inr: Numeric price without ₹.
• description: What it adds.
• availability: available, seasonal, temporarily_unavailable, or unknown.
• compatible_product_ids: Exact products that support it.
• compatible_categories: Categories that generally support it.
• incompatible_product_ids: Exceptions.
• Contribution fields: Specific flavour, texture, sweetness, richness, and portion effects.
• allergen_ids: Confirmed allergen IDs.
• best_for_preferences: Who will enjoy it.
• avoid_for_preferences: When not to recommend it.
• recommended_when: Situations where it adds real value.
• upsell_message: Honest customer-facing suggestion.
• premium_add_on: true, false, or null.

---

business_profile.json

Purpose

Contains approved facts Chat with MeltMind uses when answering questions about MeltRoom.

Sections

• brand: Identity, description, personality, differentiators, speciality, promise, and approved vocabulary.
• story: Founder information, origin story, milestones, quote, and vision.
• quality: Ingredient, preparation, freshness, packaging, and quality-control explanations.
• contact: Exact contact links and address.
• service: Operating hours, delivery areas, ordering channels, and payments.
• approved_short_answers: Polished answers for the most frequent questions.
• Verification fields: Who approved the file and when.

For operating_hours, use clear strings:

"operating_hours": [
  "Monday-Saturday: 12:00 PM-10:00 PM",
  "Sunday: Closed"
]

---

operations_and_policies.json

Purpose

Contains operational rules and safety boundaries. All information must be approved by MeltRoom.

Sections

• ordering: Minimum order, notice periods, customization, confirmation, and change rules.
• delivery_and_pickup: Availability, areas, fees, estimates, and delays.
• returns_and_issues: Cancellation, refund, incorrect order, damage, and reporting rules.
• food_safety: Approved allergy disclaimer, storage, reheating, and consumption guidance.
• chatbot_boundaries: Claims MeltMind must never make, topics requiring human help, and the exact handoff message.

Use null for unknown numeric or boolean values. Keep policy explanations complete enough that MeltMind can answer without improvising.

---

recommendation_rules.json

Purpose

Controls Design Your Perfect Melt. These rules are enforced by Python and take priority over language-model suggestions.

hard_constraints

These are rules that must never be violated. Keep safety and budget constraints as true.

maximum_add_on_budget_percentage may be numeric when MeltRoom wants a percentage cap:

"maximum_add_on_budget_percentage": 20

Use null when add-ons may use any portion of the customer's total budget:

"maximum_add_on_budget_percentage": null

The complete order must still respect never_exceed_budget.

portion_rules

Add multiple ranges for realistic group sizes:

{
  "group_size_min": 2,
  "group_size_max": 3,
  "recommended_total_servings_min": 2,
  "recommended_total_servings_max": 4,
  "variety_target": 2,
  "notes": "Recommend at least two different products when budget permits."
}

scoring_weights

Values represent relative importance. They do not have to total 100, but a larger number means greater influence.

mood_mapping

For each mood, add phrases customers use, preferred product attributes, avoided attributes, and the tone MeltMind should use when explaining the plan.

occasion_mapping

Define the variety, sharing, and premium expectations for birthdays, movie nights, gifts, solo treats, and other occasions.

plan_styles

These represent different plans MeltMind can offer, such as Best Match, Best Value, and Premium Experience. weight_overrides changes scoring for that specific plan.

upsell_rules

Set strict limits so upselling remains useful rather than aggressive.

---

faq.json

Purpose

Contains approved direct answers for frequent questions.

For every FAQ:

• faq_id: Unique snake-case ID.
• category: Example: "menu", "ordering", "allergens", "delivery".
• question: Canonical question.
• alternate_questions: Other ways customers ask the same thing.
• approved_answer: Complete factual answer MeltMind may use.
• Related IDs: Products and ingredients involved.
• related_policy_section: Example: "food_safety.allergy_disclaimer".
• follow_up_suggestions: Helpful next questions or actions.
• requires_human_handoff: Whether MeltMind should redirect the customer.
• Verification fields.

Create separate FAQ entries when two questions require meaningfully different answers.

---

language_dictionary.json

Purpose

Helps MeltMind understand informal language, product nicknames, misspellings, and customer intent.

Sections

• preference_phrases: Group exact customer phrases by meaning.
• product_aliases: Map nicknames and misspellings to product IDs.
• category_aliases: Map informal category names.
• intent_examples: Add many realistic messages for each request type.
• supported_languages: Define supported languages and words that should not be translated.

Use phrases customers genuinely say. Do not write model-generated variations unless they represent likely customer language.

---

customer_examples.json

Purpose

Stores ideal examples that demonstrate how MeltMind should behave. These may later support prompts or fine-tuning.

chat_examples

• customer_message: Exact user message.
• conversation_context: Earlier messages required to understand it.
• detected_intent: Expected intent.
• facts_that_must_be_used: Facts required in the answer.
• facts_that_must_not_be_claimed: Hallucinations or unsafe claims to avoid.
• tools_that_should_be_called: Expected tools such as compare_products.
• ideal_response: Excellent final response.
• ideal_follow_up_question: Helpful next question.
• ideal_actions: Example: "offer_add_to_basket".

designer_examples

Record the original request, expected structured preferences, required and forbidden products, add-ons, maximum total, and ideal explanation.

Create examples for simple, vague, difficult, and safety-sensitive requests.

---

evaluation_cases.json

Purpose

Contains tests, not teaching examples. These determine whether MeltMind is correct.

Test types

• chat_tests: Factual answers, comparisons, and tool behavior.
• designer_tests: Budget, group, preference, availability, and allergen compliance.
• safety_tests: Questions MeltMind must refuse or hand to a human.
• quality_targets: Required overall quality metrics.

Tests should be strict and difficult. Include cases where the correct behavior is to say that information is unknown.

---

customer_evidence.json

Purpose

Stores anonymized real-world feedback and impact measurements.

Sections

• testimonials: Approved customer quotes.
• product_feedback: Specific likes, dislikes, customer language, and business insights.
• impact_baseline: Measurements before MeltMind.
• impact_after_meltmind: The same measurements after customers use MeltMind.

Never include private customer information without permission.

For percentage fields, enter a number between 0 and 100 without %.

---

Recommended Workflow

1. Answer the Markdown forms naturally.
2. Verify ingredients, allergens, serving sizes, and policies.
3. Transfer verified facts into JSON.
4. Ensure all referenced IDs exist.
5. Validate JSON syntax.
6. Build recommendation tools.
7. Add realistic customer examples.
8. Add strict evaluation cases.
9. Measure real customer impact.