Ingredient Parser

https://github.com/strangetom/ingredient-parser
Admin
Ingredient Parser is a Python package that uses sequence labeling to extract structured information...
Tokens:39,419
Snippets:308
Trust Score:6.8
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install and Run Webtools - Bash

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/webtools.md

This snippet outlines the steps to clone the ingredient-parser repository, set up a Python virtual environment, install development dependencies, and then navigate to the webtools directory to install Node.js packages and start the development server.

```bash
# Clone repository
$ git clone https://github.com/strangetom/ingredient-parser.git
$ cd ingredient-parser

# Create venv and install required packages
$ python -m venv venv
$ source venv/bin/activate
$ python -m pip install -r requirements-dev.txt

# Install webtools
$ cd webtools
$ npm install
$ npm run dev
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Installs the necessary development dependencies for training the model. This command should be run from the project's root directory.

```bash
python -m pip install -r requirements-dev.txt
```

--------------------------------

### Install and Configure Pre-commit Hooks

Source: https://github.com/strangetom/ingredient-parser/blob/master/README.md

Installs the pre-commit framework and its associated hooks for the repository. These hooks run automatically before each commit to ensure code quality and consistency for both the Python library and the web app.

```bash
pre-commit install
```

--------------------------------

### Install Documentation Build Dependencies

Source: https://github.com/strangetom/ingredient-parser/blob/master/README.md

Installs the dependencies required to build the project's documentation. This is useful for developers who want to generate or update the documentation locally.

```bash
pip install -r requirements-doc.txt
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/strangetom/ingredient-parser/blob/master/README.md

Installs the necessary dependencies for developing and contributing to the Ingredient Parser library. This includes tools for training and fine-tuning models.

```bash
pip install -r requirements-dev.txt
```

--------------------------------

### Install Ingredient Parser using pip

Source: https://github.com/strangetom/ingredient-parser/blob/master/README.md

Installs the ingredient-parser-nlp package from pip. This is the primary method for adding the library to your Python environment.

```bash
python -m pip install ingredient-parser-nlp
```

--------------------------------

### Parsing Ingredient Amounts Example

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/postprocessing.md

Demonstrates how ingredient amounts are parsed from a sentence. It shows the tokenized sentence and the resulting list of IngredientAmount objects, including quantities, units, and confidence scores. This example highlights how different units like 'cup' and 'g' are parsed into separate amounts.

```python
>>> p = PreProcessor("3/4 cup (170g) heavy cream")
>>> p.tokenized_sentence
['0.75', 'cup', '(', '170', 'g', ')', 'heavy', 'cream']
...
>>> parsed = PostProcessor(sentence, tokens, labels, scores).parsed()
>>> amounts = parsed.amount
[
    IngredientAmount(quantity=Fraction(3, 4),
              quantity_max=Fraction(3, 4),
              unit=<Unit('cup')>,
              text='0.75 cups',
              confidence=0.999881,
              starting_index=0,
              unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
              APPROXIMATE=False,
              SINGULAR=False,
              RANGE=False,
              MULTIPLIER=False,
              PREPARED_INGREDIENT=False),
    IngredientAmount(quantity=Fraction(170, 1),
              quantity_max=Fraction(170, 1),
              unit=<Unit('gram')>,
              text='170 g',
              confidence=0.995941,
              starting_index=3,
              unit_system=<UnitSystem.METRIC: 'metric'>,
              APPROXIMATE=False,
              SINGULAR=False,
              RANGE=False,
              MULTIPLIER=False,
              PREPARED_INGREDIENT=False)
]
```

--------------------------------

### Parse Ingredients with Preparation Instructions (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Demonstrates parsing ingredient strings where preparation instructions are appended or prepended. The 'PREPARED_INGREDIENT' flag is set to True when the preparation modifies the ingredient before measurement.

```python
>>> parse_ingredient("1 cup flour, sifted")
ParsedIngredient(name=[IngredientText(text='flour',
                                      confidence=0.998215,
                                      starting_index=2)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(1, 1),
                                          quantity_max=Fraction(1, 1),
                                          unit=<Unit('cup')>,
                                          text='1 cup',
                                          confidence=0.999959,
                                          starting_index=0,
                                          unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False)],
                 preparation=IngredientText(text='sifted',
                                            confidence=0.999754,
                                            starting_index=4),
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='1 cup flour, sifted')

>>> parse_ingredient("1 cup sifted flour")
ParsedIngredient(name=[IngredientText(text='flour',
                                      confidence=0.986433,
                                      starting_index=3)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(1, 1),
                                          quantity_max=Fraction(1, 1),
                                          unit=<Unit('cup')>,
                                          text='1 cup',
                                          confidence=0.99918,
                                          starting_index=0,
                                          unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=True)],
                 preparation=IngredientText(text='sifted',
                                            confidence=0.990133,
                                            starting_index=2),
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='1 cup sifted flour')
```

--------------------------------

### Basic Ingredient Parsing with Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Demonstrates the basic usage of the `parse_ingredient` function to parse a simple ingredient string. It shows the full output structure, including name, size, amount, and preparation details.

```python
>>> parse_ingredient("1 large red onion, finely diced")
ParsedIngredient(name=[IngredientText(text='red onion',
                                      confidence=0.994235,
                                      starting_index=2)],
                 size=IngredientText(text='large',
                                     confidence=0.997111,
                                     starting_index=1),
                 amount=[IngredientAmount(quantity=Fraction(1, 1),
                                          quantity_max=Fraction(1, 1),
                                          unit='',
                                          text='1',
                                          confidence=0.999933,
                                          starting_index=0,
                                          unit_system=<UnitSystem.NONE: 'none'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False)],
                 preparation=IngredientText(text='finely diced',
                                            confidence=0.998908,
                                            starting_index=5),
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='1 large red onion, finely diced')
```

--------------------------------

### Parse Alternative Ingredients in Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Demonstrates how the library identifies multiple valid ingredient names when alternatives are present in a sentence. It ensures that compound ingredient names like 'olive oil' are correctly parsed instead of just 'olive'.

```python
>>> parse_ingredient("2 tbsp olive or sunflower oil")
ParsedIngredient(name=[IngredientText(text='olive oil',
                                      confidence=0.989134,
                                      starting_index=2),
                       IngredientText(text='sunflower oil',
                                      confidence=0.982565,
                                      starting_index=4)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(2, 1),
                                          quantity_max=Fraction(2, 1),
                                          unit=<Unit('tablespoon')>,
                                          text='2 tbsps',
                                          confidence=0.999819,
                                          starting_index=0,
                                          unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False)],
                 preparation=None,
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='2 tbsp olive or sunflower oil')
```

--------------------------------

### Train Models with LBFGS and AP Algorithms (Default Hyper-parameters)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Trains models using the LBFGS and AP algorithms with their default hyper-parameters. This is a basic grid search setup.

```bash
python train.py gridseach --model parser --database train/data/training.sqlite3 --algos lbfgs ap
```

--------------------------------

### Parse Ingredient with Foundation Foods (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

This snippet shows how to call the `parse_ingredient` function with `foundation_foods=True` to get detailed ingredient information, including specific foundation food data like FDC ID and category. It requires the `ingredient_parser` library.

```python
from fractions import Fraction
from ingredient_parser.parsers import parse_ingredient
from ingredient_parser.models import IngredientText, IngredientAmount, FoundationFood, UnitSystem

# Example usage:
result = parse_ingredient("1 large red onion, finely diced", foundation_foods=True)
print(result)
```

--------------------------------

### Parse Alternative Ingredients with Different Amounts in Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Illustrates the parsing of ingredient sentences that contain multiple alternative ingredients, each with a distinct specified amount. The library correctly separates and identifies these distinct ingredient-amount pairs.

```python
>>> parse_ingredient("1 cup peeled and cooked fresh chestnuts (about 20), or 1 cup canned, unsweetened chestnuts")
ParsedIngredient(name=[IngredientText(text='fresh chestnuts',
                                  confidence=0.977679,
                                  starting_index=5)],
             size=None,
             amount=[IngredientAmount(quantity=Fraction(1, 1),
                                      quantity_max=Fraction(1, 1),
                                      unit=<Unit('cup')>,
                                      text='1 cup',
                                      confidence=0.999549,
                                      starting_index=0,
                                      unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                      APPROXIMATE=False,
                                      SINGULAR=False,
                                      RANGE=False,
                                      MULTIPLIER=False,
                                      PREPARED_INGREDIENT=True),
                     IngredientAmount(quantity=Fraction(20, 1),
                                      quantity_max=Fraction(20, 1),
                                      unit='',
                                      text='20',
                                      confidence=0.887524,
                                      starting_index=9,
                                      unit_system=<UnitSystem.NONE: 'none'>,
                                      APPROXIMATE=True,
                                      SINGULAR=False,
                                      RANGE=False,
                                      MULTIPLIER=False,
                                      PREPARED_INGREDIENT=False)],
             preparation=IngredientText(text='peeled and cooked',
                                        confidence=0.999523,
                                        starting_index=2),
             comment=IngredientText(text='or 1 cup canned, unsweetened '
                                        'chestnuts',
                                    confidence=0.925894,
                                    starting_index=12),
             purpose=None,
             foundation_foods=[],
             sentence='1 cup peeled and cooked fresh chestnuts (about 20), '
                      'or 1 cup canned, unsweetened chestnuts')
```

--------------------------------

### Configure Foundation Foods Debug Logging to Stdout - Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/logging.md

This code example shows how to enable debug logging specifically for the 'ingredient-parser.foundation-foods' namespace, directing output to standard output. It includes the necessary imports, logging configuration, and a call to the parsing function with the `foundation_foods` parameter set to True.

```python
import logging, sys
from ingredient_parser import parse_ingredient

logging.basicConfig(stream=sys.stdout)
logging.getLogger("ingredient-parser.foundation-foods").setLevel(logging.DEBUG)

parsed = parse_ingredient("24 fresh basil leaves or dried basil", foundation_foods=True)
```

--------------------------------

### Parsing Ingredients with Multiple Amounts in Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Illustrates how the library handles ingredient strings with multiple amounts, such as '2 28 ounce cans'. It highlights the separation of outer and inner amounts and the `SINGULAR` flag for inner amounts.

```python
>>> parse_ingredient("2 28 ounce cans whole tomatoes")
ParsedIngredient(name=[IngredientText(text='whole tomatoes',
                                      confidence=0.999044,
                                      starting_index=4)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(2, 1),
                                          quantity_max=Fraction(2, 1),
                                          unit='cans',
                                          text='2 cans',
                                          confidence=0.999825,
                                          starting_index=0,
                                          unit_system=<UnitSystem.OTHER: 'other'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False),
                         IngredientAmount(quantity=Fraction(28, 1),
                                          quantity_max=Fraction(28, 1),
                                          unit=<Unit('ounce')>,
                                          text='28 ounces',
                                          confidence=0.999437,
                                          starting_index=1,
                                          unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                          APPROXIMATE=False,
                                          SINGULAR=True,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False)],
                 preparation=None,
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='2 28 ounce cans whole tomatoes')
```

--------------------------------

### Parse Ingredient with Imperial Units

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Parses an ingredient string specifying the 'imperial' volumetric unit system. This is crucial for recipes originating from or intended for regions using imperial measurements.

```python
>>> parse_ingredient("2 cups boiled water", volumetric_units_system="imperial")
ParsedIngredient(name=[IngredientText(text='water',
                                      confidence=0.823288,
                                      starting_index=3)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(2, 1),
                                          quantity_max=Fraction(2, 1),
                                          unit=<Unit('imperial_cup')>,
                                          text='2 cups',
                                          confidence=0.999709,
                                          starting_index=0,
                                          unit_system=<UnitSystem.IMPERIAL: 'imperial'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=True)],
                 preparation=IngredientText(text='boiled',
                                            confidence=0.833938,
                                            starting_index=2),
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='2 cups boiled water')
```

--------------------------------

### Parse Ingredient with Default US Units

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

Parses an ingredient string using the default US customary volumetric units. This is useful when the ingredient list adheres to US standards.

```python
>>> parse_ingredient("2 cups boiled water")
ParsedIngredient(name=[IngredientText(text='water',
                                      confidence=0.823288,
                                      starting_index=3)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(2, 1),
                                          quantity_max=Fraction(2, 1),
                                          unit=<Unit('cup')>,
                                          text='2 cups',
                                          confidence=0.999709,
                                          starting_index=0,
                                          unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=True)],
                 preparation=IngredientText(text='boiled',
                                            confidence=0.833938,
                                            starting_index=2),
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='2 cups boiled water')
```

--------------------------------

### Parse Ingredient with Approximate Amount (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/tutorials/examples.md

This Python code snippet shows how the `parse_ingredient` function processes an ingredient string containing an approximate amount ('about 400 g'). It highlights the `APPROXIMATE=True` flag set for the relevant amount.

```python
>>> parse_ingredient("4 pork chops, about 400 g each")
ParsedIngredient(name=[IngredientText(text='pork chops',
                                      confidence=0.9961,
                                      starting_index=1)],
                 size=None,
                 amount=[IngredientAmount(quantity=Fraction(4, 1),
                                          quantity_max=Fraction(4, 1),
                                          unit='',
                                          text='4',
                                          confidence=0.999876,
                                          starting_index=0,
                                          unit_system=<UnitSystem.NONE: 'none'>,
                                          APPROXIMATE=False,
                                          SINGULAR=False,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False),
                         IngredientAmount(quantity=Fraction(400, 1),
                                          quantity_max=Fraction(400, 1),
                                          unit=<Unit('gram')>,
                                          text='400 g',
                                          confidence=0.995449,
                                          starting_index=5,
                                          unit_system=<UnitSystem.METRIC: 'metric'>,
                                          APPROXIMATE=True,
                                          SINGULAR=True,
                                          RANGE=False,
                                          MULTIPLIER=False,
                                          PREPARED_INGREDIENT=False)],
                 preparation=None,
                 comment=None,
                 purpose=None,
                 foundation_foods=[],
                 sentence='4 pork chops, about 400 g each')
```

--------------------------------

### Using Pint Unit Registry (UREG) in Python

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Demonstrates how to access and use the Pint unit registry (`UREG`) configured with cooking-specific units. This allows for direct quantity creation, custom density definitions, and unit conversions within a cooking context.

```python
from ingredient_parser import UREG

# Create quantities directly
flour_mass = 250 * UREG("g")
water_volume = 1 * UREG("cup")

# Define custom density for conversion
flour_density = 120 * UREG("g/cup")

# Convert with density context
with UREG.context("density", p=flour_density):
    flour_in_cups = flour_mass.to("cup")
    print(f"{flour_in_cups:.2f}")  # ~2.08 cup

# Access cooking-specific units
metric_cup = UREG("metric_cup")      # 250 ml
imperial_pint = UREG("imperial_pint") # UK pint
aus_tablespoon = UREG("aus_tablespoon")  # 20 ml (Australian)
jp_cup = UREG("jp_cup")  # 200 ml (Japanese)
```

--------------------------------

### Show Help for Grid Search

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Displays all available options for the `gridsearch` sub-command of the `train.py` script, useful for understanding tuning parameters.

```bash
python train.py gridsearch --help
```

--------------------------------

### Example of Incorrect POS Tagging

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/appendix/pos-tags.md

This code snippet shows an example of how NLTK's default part of speech tagger incorrectly tags 'pear' as an adjective (JJ) instead of a noun (NN) in an ingredient sentence.

```python
>>> pos_tag(tokenize("1 pear cored, peeled and chopped"))
[('1', 'CD'), ('pear', 'JJ'), ('cored', 'VBN'), (',', ','), ('peeled', 'VBN'), ('and', 'CC'), ('chopped', 'VBD')]
```

--------------------------------

### Display Model Card Documentation with Python

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Illustrates how to display the model card documentation for the Ingredient Parser library using the `show_model_card` function. This documentation includes details about training data, model performance, and usage guidelines.

```python
from ingredient_parser import show_model_card

# Opens the model card in the default markdown viewer
show_model_card(lang="en")
```

--------------------------------

### IngredientText Dataclass

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/dataclasses.md

Represents a parsed ingredient string, storing the text, confidence score, and starting index within the sentence. It's a fundamental building block for more complex ingredient parsing.

```python
class IngredientText:
    def __init__(self, text: str, confidence: float, starting_index: int):
        self.text = text
        self.confidence = confidence
        self.starting_index = starting_index
```

--------------------------------

### Initialize PreProcessor and Normalize Sentence (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/normalisation.md

Demonstrates the initialization of the `PreProcessor` class with an ingredient sentence and shows the resulting normalized sentence. This highlights the initial transformation applied to the input data.

```python
from Preprocess import PreProcessor
p = PreProcessor("1/2 cup orange juice, freshly squeezed")
print(p.sentence)
```

--------------------------------

### Train Models with All Possible Algorithms (Default Hyper-parameters)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Trains models using each of the possible algorithms (lbfgs, l2sgd, ap, pa, arow) with their default hyper-parameters. This provides a baseline performance comparison across algorithms.

```bash
python train.py gridsearch --model parser --database train/data/training.sqlite3 --algos lbfgs l2sgd ap pa arow
```

--------------------------------

### IngredientText Dataclass Definition

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/postprocessing.md

Represents a segment of text identified for a specific ingredient attribute (like name, size, etc.). It stores the extracted text, its confidence score, and its starting index within the original sentence.

```python
from dataclasses import dataclass

@dataclass
class IngredientText:
    """Dataclass for holding a parsed ingredient string.

    Attributes
    ----------
    text : str
        Parsed text from ingredient.
        This is comprised of all tokens with the same label.
    confidence : float
        Confidence of parsed ingredient text, between 0 and 1.
        This is the average confidence of all tokens that contribute to this object.
    starting_index : int
        Index of token in sentence that starts this text
    """

    text: str
    confidence: float
    starting_index: int

```

--------------------------------

### Rank Ingredient Matches using Fuzzy Document Distance

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/foundation.md

Initializes the fuzzy ranker and applies it to rank ingredient matches. This method calculates relevance based on Euclidean distance between token embeddings, offering a different perspective than USIF but being computationally more expensive.

```python
from ingredient_parser.en.foundationfoods._fuzzy import get_fuzzy_ranker
fuzzy = get_fuzzy_ranker()
rankings = fuzzy.rank_matches(["red", "pepper"])
for rank in rankings[:5]:
        print(f"{rank.score:.4f}: {rank.fdc.description}")
```

--------------------------------

### Convert Ingredient Amounts with Pint

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Converts ingredient amounts between different units using the Pint library. Supports mass-to-mass, volume-to-mass conversions with default or custom densities.

```python
from ingredient_parser import parse_ingredient, UREG

# Basic unit conversion (mass to mass)
result = parse_ingredient("1.2 kg lamb shank")
converted = result.amount[0].convert_to("lbs")
print(converted.unit)  # <Unit('pound')>
print(converted.text)  # '2.65 pound'

# Convert volume to mass using default density (water: 1000 kg/m^3)
result = parse_ingredient("1 cup water")
converted = result.amount[0].convert_to("g")
print(converted.text)  # '236.588 gram'

# Convert volume to mass with custom density (flour: 120g per cup)
result = parse_ingredient("2 cups all purpose flour")
converted = result.amount[0].convert_to("g", density=120 * UREG("g/cup"))
print(converted.quantity)  # 240.0
print(converted.text)      # '240 gram'

# Convert ounces to grams
result = parse_ingredient("8 oz cheddar cheese")
converted = result.amount[0].convert_to("g")
print(f"{float(converted.quantity):.1f} grams")  # '226.8 grams'
```

--------------------------------

### Parse Ingredient Strings with Python

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Demonstrates basic ingredient parsing using the `parse_ingredient` function. It shows how to extract composite amounts, joiners, and convert units. This function is the primary entry point for parsing single ingredient strings.

```python
from ingredient_parser import parse_ingredient

# Composite amount: 1 lb 2 oz
result = parse_ingredient("1lb 2 oz lamb shank")
composite = result.amount[0]

print(composite.text)        # '1lb 2 oz'
print(composite.subtractive) # False (amounts add together)

# Get combined amount as pint.Quantity
combined = composite.combined()
print(combined)  # 18 ounce

# Convert combined amount to different units
converted = composite.convert_to("kg")
print(converted)  # ~0.51 kilogram

# Composite with "plus" joining amounts
result = parse_ingredient("1 cup plus 1 tablespoon vegetable oil")
composite = result.amount[0]
print(composite.join)  # ' plus '
print(composite.amounts[0].text)  # '1 cup'
print(composite.amounts[1].text)  # '1 tablespoon'
```

--------------------------------

### Handle Composite Ingredient Amounts

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Demonstrates handling of composite amounts like '1 lb 2 oz' or '1 cup plus 1 tablespoon'. This functionality is part of the `IngredientAmount` class.

```python
from ingredient_parser import parse_ingredient

# Example for composite amounts would go here, but no code is provided in the source text.
```

--------------------------------

### Convert IngredientAmount units to different units (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/convert-units.md

Demonstrates converting an IngredientAmount object to a different unit using the `convert_to` method. The target unit must be recognized by the pint library. The output is an IngredientAmount object with the converted quantity and unit.

```python
>>> amount = parse_ingredient("1.2 kg lamb shank").amount[0]
>>> amount.convert_to("lbs")
IngredientAmount(quantity=Fraction(66138678655463271, 25000000000000000),
    quantity_max=Fraction(66138678655463271, 25000000000000000),
    unit=<Unit('pound')>,
    text='2.65 pound',
    confidence=0.99986,
    starting_index=0,
    unit_system=<UnitSystem.US_CUSTOMARY: 'us_customary'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)
```

--------------------------------

### Execute Model Training Script

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Executes the main training script to train the ingredient parser model on all available datasets. This command allows specifying the model name and the database file.

```bash
python train.py train --model parser --database train/data/training.sqlite3
```

--------------------------------

### Convert volume to mass using custom density (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/convert-units.md

Demonstrates converting a volume-based ingredient amount to mass using a custom density value provided to the `convert_to` method. This is useful for ingredients where the standard density differs significantly from water. Quantities are converted to float in this type of conversion.

```python
>>> amount = parse_ingredient("2 cups all purpose flour").amount[0]
>>> # Using custom density value: 1 cup flour = 120 g
>>> amount.convert_to("g", density=120 * UREG("g/cup"))
IngredientAmount(quantity=240.0,
    quantity_max=240.0,
    unit=<Unit('gram')>,
    text='240 gram',
    confidence=0.999949,
    starting_index=0,
    unit_system=<UnitSystem.METRIC: 'metric'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)
```

--------------------------------

### Parse Ingredient with Foundation Foods Matching (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/foundation.md

Demonstrates how to use the `parse_ingredient` function with the `foundation_foods=True` argument to enable matching ingredient names to the FDC database. This function takes an ingredient string and returns a parsed ingredient object, including any matched foundation foods.

```python
from ingredient_parser import parse_ingredient

parsed_ingredient = parse_ingredient("24 fresh basil leaves or dried basil", foundation_foods=True)

print(parsed_ingredient)
```

--------------------------------

### PreProcessor Class

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/preprocessor.md

The PreProcessor class handles the cleaning and tokenization of recipe ingredient sentences to prepare them for the ingredient parser model.

```APIDOC
## Class ingredient_parser.en.preprocess.PreProcessor

### Description
Recipe ingredient sentence PreProcessor class. Performs the necessary preprocessing on a sentence to generate the features required for the ingredient parser model. Each input sentence goes through a cleaning process to tidy up the input into a standardised form.

### Parameters
#### Path Parameters
- **input_sentence** (str) - Required - Input ingredient sentence.

### Attributes
- **input** (str) - Input ingredient sentence.
- **sentence** (str) - Input ingredient sentence, cleaned to standardised form.
- **singularised_indices** (list) - Indices of tokens in tokenized sentence that have been converted from plural to singular.
- **tokenized_sentence** (list) - Tokenised ingredient sentence.

### Methods
#### sentence_features()

##### Description
Return dict of features for each token in sentence.

##### Method
GET

##### Endpoint
/preprocess/sentence_features

##### Response
#### Success Response (200)
- **List[FeatureDict]** (list) - List of feature dicts for each token in sentence.

#### Response Example
{
  "example": "[{"token": "1", "features": {"is_numeric": true, "is_unit": false, ...}}, {"token": "cup", "features": {"is_numeric": false, "is_unit": true, ...}}]"
}

### Notes
The cleaning steps are as follows:
1. Replace all en-dashes and em-dashes with hyphens.
2. Replace numbers given as words with the numeric equivalent (e.g., one >> 1).
3. Replace fractions given in html markup with the unicode representation (e.g., &frac12; >> ½).
4. Replace unicode fractions with the equivalent decimal form, rounded to a maximum of 3 decimal places (e.g., ½ >> 0.5).
5. Identify fractions represented by 1/2, 2/3 etc. by replacing the slash with $ and prepending # (e.g., 1/2 >> #1$2).
6. Enforce a space between quantities and units.
7. Remove trailing periods from units (e.g., tsp. >> tsp).
8. Replace numeric ranges indicated in words using “to” or “or” with a standard numeric form (e.g., 1 or 2 >> 1-2).
9. Units are made singular using a predefined list of plural units and their singular form.

Following the cleaning of the input sentence, it is tokenized into a list of tokens. Each token is either a word (including most punctuation marks) or opening/closing parentheses, braces, brackets, comma, or speech marks. The features for each token are computed on demand using the `sentence_features` method, which returns a list of dictionaries. Each dictionary is the feature set for each token. The sentence features can then be passed to the CRF model which will generate the parsed output.
```

--------------------------------

### Train Models with LBFGS and AP Algorithms (Global Hyper-parameters)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Trains models using LBFGS and AP algorithms, varying only the global hyper-parameters that apply to all models. This allows for broad tuning across algorithms.

```bash
python train.py gridseach --model parser --database train/data/training.sqlite3 --algos lbfgs  ap --global-params '{"feature.minfreq":[0, 1, 5],"feature.possible_transitions":[true, false],"feature.possible_states":[true, false]}'
```

--------------------------------

### Pre-process and Predict Labels with CRFsuite in Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/usage.md

This Python snippet demonstrates how to use the PreProcessor class to pre-process an ingredient sentence and then utilize pycrfsuite to load a trained model and predict labels for the sentence tokens. It requires the `ingredient_parser.en` and `pycrfsuite` libraries.

```python
from ingredient_parser.en import PreProcessor
import pycrfsuite

# Pre-process sentence
p = PreProcessor("100 g green beans")

# Create tagger object and load model
tagGER = pycrfsuite.Tagger()
tagGER.open("model.en.crfsuite")

# Predict labels using token features
labels_pred = tagger.tag(p.sentence_features())
```

--------------------------------

### Match Ingredient to Foundation Foods (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/foundationfoods.md

Matches ingredient names to foundation foods using a three-stage process: token normalization, USIF-based candidate down-selection, and fuzzy embedding document metric for best match selection. It requires ingredient tokens, POS tags, and the name index. Returns a FoundationFood object or None.

```python
from ingredient_parser.en.foundationfoods import match_foundation_foods

# Example usage:
tokens = ['sugar', 'granulated']
pos_tags = ['NOUN', 'ADJ']
name_idx = 0

foundation_food = match_foundation_foods(tokens, pos_tags, name_idx)

if foundation_food:
    print(f"Matched Foundation Food: {foundation_food.name}")
else:
    print("No matching Foundation Food found.")
```

--------------------------------

### Run Multiple Model Training Cycles

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Executes the model training process multiple times to obtain average performance and uncertainty. The `--runs` argument specifies the number of training cycles.

```bash
python train.py multiple --model parser --database train/data/training.sqlite3 --runs 10
```

--------------------------------

### Rank Foundation Food Entries using BM25

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/foundation.md

Demonstrates how to use the BM25 ranker to find relevant foundation food entries for a given ingredient. It initializes the BM25 ranker and then ranks a list of ingredient tokens, printing the top 5 results with their scores and descriptions. The BM25 scores are arbitrary and only meaningful for relative comparison within a single ranking.

```python
from ingredient_parser.en.foundationfoods._bm25 import get_bm25_ranker
BM25 = get_bm25_ranker()
rankings = BM25.rank_matches(["red", "pepper"])
for rank in rankings[:5]:
        print(f"{rank.score:.4f}: {rank.fdc.description}")
```

--------------------------------

### Quantity Parsing with Fractions

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/postprocessing.md

Illustrates how quantities are parsed into `fractions.Fraction` objects when the `quantity_fractions` option is enabled. This ensures precise representation of fractional quantities, falling back to strings for non-numeric inputs like 'dozen'.

```python
>>> parsed = parse_ingredient("1/3 cup oil", quantity_fractions=True)
>>> parsed.amount.quantity
Fraction(1, 3)
```

--------------------------------

### Convert volume to mass using default density (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/convert-units.md

Illustrates converting a volume-based ingredient amount to mass using the `convert_to` method with the default density of water (1000 kg/m³). Note that when converting between mass and volume, quantities are converted to float.

```python
>>> amount = parse_ingredient("1 cup water").amount[0]
>>> # Using default density value
>>> amount.convert_to("g")
IngredientAmount(quantity=236.58823649999997,
    quantity_max=236.58823649999997,
    unit=<Unit('gram')>,
    text='236.588 gram',
    confidence=0.999943,
    starting_index=0,
    unit_system=<UnitSystem.METRIC: 'metric'>,
    APPROXIMATE=False,
    SINGULAR=False,
    RANGE=False,
    MULTIPLIER=False,
    PREPARED_INGREDIENT=False
)
```

--------------------------------

### IngredientAmount Flags in Python

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Explains how to access semantic flags on parsed ingredient amounts to identify characteristics like approximate quantities, ranges, singular units, prepared ingredients, and multipliers. These flags provide deeper insights into the ingredient's nature.

```python
from ingredient_parser import parse_ingredient

# APPROXIMATE flag - for "about", "approximately", etc.
result = parse_ingredient("4 pork chops, about 400 g each")
print(result.amount[1].APPROXIMATE)  # True
print(result.amount[1].SINGULAR)     # True (applies to each chop)

# RANGE flag - for quantity ranges like "1-2"
result = parse_ingredient("1-2 cups milk")
print(result.amount[0].RANGE)        # True
print(result.amount[0].quantity)     # Fraction(1, 1) (lower bound)
print(result.amount[0].quantity_max) # Fraction(2, 1) (upper bound)

# SINGULAR flag - inner amount applies to singular unit
result = parse_ingredient("2 28 ounce cans whole tomatoes")
print(result.amount[0].text)      # '2 cans'
print(result.amount[1].text)      # '28 ounces'
print(result.amount[1].SINGULAR)  # True (28 oz per can)

# PREPARED_INGREDIENT flag - amount refers to prepared state
result = parse_ingredient("1 cup sifted flour")
print(result.amount[0].PREPARED_INGREDIENT)  # True (measure after sifting)

result = parse_ingredient("1 cup flour, sifted")
print(result.amount[0].PREPARED_INGREDIENT)  # False (measure before sifting)

# MULTIPLIER flag - for "1x", "2x" style quantities
result = parse_ingredient("2x 400g cans chopped tomatoes")
print(result.amount[0].MULTIPLIER)  # True
```

--------------------------------

### Train Models with LBFGS Algorithm and Specified Hyper-parameters

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Trains models using the LBFGS algorithm, iterating through specified combinations of hyper-parameters. Unspecified parameters will use default values.

```bash
python train.py gridseach --model parser --database train/data/training.sqlite3 --algos lbfgs --lbfgs-params '{"c1": [0.05, 0.1, 0.5, 1], "c2":[0.1, 0.5, 1, 2]}'
```

--------------------------------

### Parse Ingredient Sentence using Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/README.md

Demonstrates how to import and use the `parse_ingredient` function from the library. It takes an ingredient string and returns a structured object containing parsed components like name, amount, and preparation. Optional parameters are available for advanced usage.

```python
from ingredient_parser import parse_ingredient

parsed_data = parse_ingredient("3 pounds pork shoulder, cut into 2-inch chunks")
print(parsed_data)
```

--------------------------------

### Tokenize Ingredient Sentence (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/features.md

Demonstrates tokenizing an ingredient sentence using the PreProcessor class. The output shows the sentence split into individual tokens, with special handling for numbers, units, and punctuation.

```python
from Preprocess import PreProcessor
p = PreProcessor("1/2 cup orange juice, freshly squeezed")
print(p.tokenised_sentence)
```

--------------------------------

### Inspect Parser Debugging Information with Python

Source: https://context7.com/strangetom/ingredient-parser/llms.txt

Shows how to use the `inspect_parser` function to obtain detailed debugging information about the ingredient parsing process. This includes accessing preprocessor tokens, the CRF tagger, and postprocessor results for in-depth analysis.

```python
from ingredient_parser import inspect_parser

debug_info = inspect_parser("2 cups finely chopped onions")

# Access preprocessor tokens
print(debug_info.PreProcessor.tokens)
# [Token(index=0, text='2', ...), Token(index=1, text='cups', ...), ...]

# Access the CRF tagger
print(debug_info.tagger)  # pycrfsuite.Tagger object

# Access postprocessor results
print(debug_info.PostProcessor.parsed)  # ParsedIngredient object
```

--------------------------------

### Ingredient Parsing with Pint Unit Standardization (Python)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/postprocessing.md

Demonstrates how to use the `parse_ingredient` function with the Pint library for unit standardization. It shows how to specify different volumetric unit systems ('us_customary' and 'imperial') and the resulting `pint.Unit` objects in the parsed output. The `string_units` parameter can be set to `True` to return units as strings instead of Pint objects.

```python
from ingredient_parser import parse_ingredient

# Example using default US customary units
result_us = parse_ingredient("3/4 cup heavy cream", volumetric_units_system="us_customary")
print(result_us)

# Example using imperial units
result_imperial = parse_ingredient("3/4 cup heavy cream", volumetric_units_system="imperial")
print(result_imperial)
```

--------------------------------

### Rank Ingredient Matches using USIF

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/foundation.md

Retrieves the USIF ranker and uses it to rank potential ingredient matches based on input tokens. The output includes scores and descriptions of the top matches. This method is efficient for finding reasonable matches.

```python
from ingredient_parser.en.foundationfoods._usif import get_usif_ranker
usif = get_usif_ranker()
rankings = usif.rank_matches(["red", "pepper"])
for rank in rankings[:5]:
        print(f"{rank.score:.4f}: {rank.fdc.description}")
```

--------------------------------

### Train CRF Model with Python-CRFsuite

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/training.md

Demonstrates how to train a Conditional Random Fields (CRF) model using the python-crfsuite library. It involves instantiating a trainer, setting hyperparameters, appending training data, and saving the trained model.

```python
import pycrfsuite

# Instantiate Trainer object
trainer = pycrfsuite.Trainer(verbose=False)

# Configure model hyper-parameters
trainer.set_params(
    {
        "feature.possible_states": True,
        "feature.possible_transitions": True,
        "c1": 0.2,
        "c2": 1,
        ...
    }
)
# Add data to the Trainer
for X, y in zip(features_train, truth_train):
    trainer.append(X, y)
# Train the model and save to the given file
trainer.train("model.crfsuite")
```

--------------------------------

### Generate Sentence Features with PreProcessor

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/features.md

This Python code snippet demonstrates how to use the PreProcessor class from the ingredient_parser.en library to generate detailed features for each token in an ingredient sentence. It takes a string representing the ingredient sentence as input and outputs a dictionary of features for a specified token.

```python
from ingredient_parser.en import PreProcessor
p = PreProcessor("1/2 cup orange juice, freshly squeezed")
print(p.sentence_features()[1])
```

--------------------------------

### Tokenize and Predict Labels for Heavy Cream in Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/explanation/usage.md

This Python code illustrates tokenizing a specific ingredient sentence ('3/4 cup (170g) heavy cream') using the PreProcessor and then predicting the corresponding labels using a loaded CRFsuite tagger. It shows the tokenized output and the predicted labels.

```python
p = PreProcessor("3/4 cup (170g) heavy cream")

# Display tokenized sentence
print([t.text for t in p.tokenized_sentence])

# Predict labels
print(tagger.tag(p.sentence_features()))
```

--------------------------------

### Configure General Debug Logging to Stdout - Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/logging.md

This snippet demonstrates how to configure Python's logging module to output debug messages from the 'ingredient-parser' namespace to standard output. It imports necessary modules, sets up basic configuration, and then calls the parsing function.

```python
import logging, sys
from ingredient_parser import parse_ingredient

logging.basicConfig(stream=sys.stdout)
logging.getLogger("ingredient-parser").setLevel(logging.DEBUG)

parsed = parse_ingredient("24 fresh basil leaves or dried basil")
```

--------------------------------

### Download NLTK Resources - Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/common.md

Checks for the presence of required NLTK resources and downloads them if they are missing. This ensures that the ingredient parser has the necessary data to function correctly, avoiding errors related to missing linguistic models.

```python
import nltk

def download_nltk_resources():
    """Check if required nltk resources can be found and if not, download them."""
    try:
        nltk.data.find('tokenizers/punkt')
    except nltk.downloader.DownloadError:
        nltk.download('punkt')
    try:
        nltk.data.find('corpora/wordnet')
    except nltk.downloader.DownloadError:
        nltk.download('wordnet')
    try:
        nltk.data.find('corpora/omw-1.4')
    except nltk.downloader.DownloadError:
        nltk.download('omw-1.4')

```

--------------------------------

### PostProcessor Class

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/postprocessor.md

The PostProcessor class is used to perform postprocessing on recipe ingredient sentences after they have been tagged by a CRF model. It takes the sentence, tokens, POS tags, labels, and confidence scores as input and returns a structured object containing the parsed ingredient data.

```APIDOC
## PostProcessor Class

### Description
Performs the necessary postprocessing on the sentence tokens and labels for the tokens after tagging with the CRF model in order to return a coherent structure of parsed information.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **sentence** (str) - Required - Original ingredient sentence.
- **tokens** (list[str]) - Required - List of tokens for original ingredient sentence.
- **pos_tags** (list[str]) - Required - List of part of speech tags for tokens.
- **labels** (list[str]) - Required - List of labels for tokens.
- **scores** (list[float]) - Required - Confidence associated with the label for each token.
- **separate_names** (bool) - Optional - If True and the sentence contains multiple alternative ingredients, return an IngredientText object for each ingredient name, otherwise return a single IngredientText object. Default is True.
- **discard_isolated_stop_words** (bool) - Optional - If True, isolated stop words are discarded from the name, preparation or comment fields. Default value is True.
- **string_units** (bool) - Optional - If True, return all IngredientAmount units as strings. If False, convert IngredientAmount units to pint.Unit objects where possible. Default is False.
- **volumetric_units_system** (str) - Optional - Specifies the volumetric units system to use. Default is 'us_customary'.
- **imperial_units** (bool) - Optional - If True, use imperial units instead of US customary units for pint.Unit objects for the following units: fluid ounce, cup, pint, quart, gallon. Default is False. This has no effect if string_units=True.
- **foundation_foods** (bool) - Optional - If True, populate the foundation_foods field of ParsedIngredient. Default is False.

### Request Example
```json
{
  "sentence": "1 cup of flour",
  "tokens": ["1", "cup", "of", "flour"],
  "pos_tags": ["CD", "NN", "IN", "NN"],
  "labels": ["B-QUANTITY", "B-UNIT", "O", "B-INGREDIENT"],
  "scores": [0.9, 0.8, 0.7, 0.95],
  "separate_names": true,
  "discard_isolated_stop_words": true,
  "string_units": false,
  "volumetric_units_system": "us_customary",
  "imperial_units": false,
  "foundation_foods": false
}
```

### Response
#### Success Response (200)
- **parsed** (ParsedIngredient) - Object containing structured data from sentence.

#### Response Example
```json
{
  "parsed": {
    "ingredient_name": {
      "name": "flour",
      "preparation": null,
      "comment": null
    },
    "quantity": {
      "amount": 1.0,
      "unit": "cup"
    },
    "nutritional_info": null,
    "foundation_foods": []
  }
}
```
```

--------------------------------

### Train Ingredient Parser Model (Bash)

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/how-to/extending.md

Command to train the ingredient parser model, specifying the database file and the database table for a specific language (e.g., Spanish 'es'). This is part of the training and evaluation phase.

```bash
python train.py train --database train/data/training.es.sqlite3 --database-table es
```

--------------------------------

### Show Model Card - Python

Source: https://github.com/strangetom/ingredient-parser/blob/master/docs/source/reference/common.md

Opens the model card for a specified language using the default application. This function is designed to provide users with access to documentation or information about the underlying models, supporting different languages.

```python
import os
import webbrowser

def show_model_card(lang: str = 'en'):
    """Open model card for specified language in default application."""
    supported_languages = ['en', 'es', 'fr'] # Example languages
    if lang not in supported_languages:
        raise ValueError(f"Unsupported language: {lang}. Supported languages are: {', '.join(supported_languages)}")

    # Construct the expected path to the model card
    # This is a placeholder and should be adapted to your project structure
    model_card_path = os.path.join(os.path.dirname(__file__), f'model_card_{lang}.html')

    if not os.path.exists(model_card_path):
        raise FileNotFoundError(f"Model card not found at: {model_card_path}")

    webbrowser.open(f'file://{os.path.realpath(model_card_path)}')

```
Tokens:
Raw