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:

```json
"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:

```json
"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:

```json
"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:

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

Do not write comma-separated lists inside one string:

```json
"textures": "gooey, soft, crunchy"
```

### IDs

IDs connect information across files. Use lowercase snake case:

```json
"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`:

```json
"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:

```json
"plain_explanation": "A tasty brownie."
```

Strong:

```json
"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:

```json
"best_for_customer_preferences": [
  "chocolate lovers"
]
```

Strong:

```json
"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

```json
{
  "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:

```json
{
  "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:

```json
"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:

```json
"maximum_add_on_budget_percentage": 20
```

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

```json
"maximum_add_on_budget_percentage": null
```

The complete order must still respect `never_exceed_budget`.

### `portion_rules`

Add multiple ranges for realistic group sizes:

```json
{
  "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.