# CalorieGram Recipes LLM Data Schema

## Overview
This document describes the structured data format used in CalorieGram recipe LLM files. Each recipe's /llm.txt endpoint contains both human-readable text and machine-readable JSON blocks.

## File Structure
Each recipe LLM file follows this structure:
1. Recipe title and description
2. Quick facts (human-readable)
3. Nutrition information (human-readable)
4. Ingredients list (human-readable)
5. Instructions (human-readable)
6. Machine-readable data blocks (JSON)

## Machine-Readable Data Blocks

### Recipe Metadata Block
Located under "### Recipe Metadata" section, contained in ```json code block:

```json
{
  "id": "uuid",                    // Unique recipe identifier
  "youtube_id": "string",          // YouTube video ID
  "title": "string",               // Recipe title
  "cuisine_type": "string",        // e.g., "Italian", "Mexican"
  "meal_type": ["string"],         // Array: ["breakfast", "lunch", "dinner", "snack"]
  "difficulty_level": "string",    // "easy", "medium", "hard"
  "servings": number,              // Number of servings
  "prep_time_minutes": number,     // Preparation time
  "cook_time_minutes": number,     // Cooking time
  "total_time_minutes": number,    // Total time (prep + cook)
  "health_score": number,          // 0-10 nutritional rating
  "created_at": "ISO8601",         // Creation timestamp
  "updated_at": "ISO8601"          // Last update timestamp
}
```

### Ingredients Data Block
Located under "### Ingredients Data" section:

```json
{
  "servings": number,              // Recipe yield
  "ingredients": [
    {
      "name": "string",            // Ingredient name
      "amount": number,            // Quantity
      "unit": "string",            // Measurement unit
      "notes": "string|null"       // Optional notes
    }
  ]
}
```

### Nutrition Data Block
Located under "### Nutrition Data (per serving)" section:

```json
{
  "calories": number,              // Calories per serving
  "macros": {
    "protein_g": number,           // Protein in grams
    "carbs_g": number,             // Carbohydrates in grams
    "fat_g": number,               // Fat in grams
    "fiber_g": number|null,        // Fiber in grams
    "sugar_g": number|null,        // Sugar in grams
    "sodium_mg": number|null       // Sodium in milligrams
  },
  "dietary_tags": {
    "vegan": boolean,              // Is vegan
    "vegetarian": boolean,         // Is vegetarian
    "gluten_free": boolean,        // Is gluten-free
    "dairy_free": boolean,         // Is dairy-free
    "nut_free": boolean            // Is nut-free
  }
}
```

## Field Types
- uuid: String in UUID v4 format
- ISO8601: DateTime string (e.g., "2024-01-15T10:30:00Z")
- number: Integer or floating-point
- boolean: true or false
- string: UTF-8 text
- null: Absent or unknown value

## Parsing Guidelines
1. JSON blocks are always contained within triple backticks with "json" language identifier
2. Each block starts with a heading (### Block Name)
3. Blocks appear in the "Machine-Readable Data" section at the end
4. All numeric values are already converted to appropriate units
5. Null values indicate data not available

## Example Usage
To extract nutrition data from a recipe:
1. Find the "### Nutrition Data (per serving)" heading
2. Parse the following JSON code block
3. Access macros.protein_g for protein content

## Version
Current schema version: 1.0
Check X-Data-Version header for version information

## Updates
Schema updates will be backward compatible. New fields may be added but existing fields won't be removed or changed in breaking ways.

---
CalorieGram LLM Schema Documentation v1.0