fishlib 0.5.0

A Python library for parsing, standardizing, and comparing seafood product descriptions in foodservice

fishlib 🐟

A Python library for parsing, standardizing, and comparing seafood product descriptions in the food industry.

The Problem: Seafood product descriptions are messy. The same product can be described a hundred different ways. Comparing prices across distributors, suppliers, or market data requires deep domain knowledge to know if two items are actually comparable.

The Solution: fishlib parses item descriptions into structured attributes, standardizes them to common codes, and enables apples-to-apples comparisons—so you don't need to be a fish expert to work with seafood data.

Installation

pip install fishlib

Quick Start

import fishlib

# Parse any item description
item = fishlib.parse("SALMON FIL ATL SKON DTRM 6OZ IVP")

print(item)
# {
#     'species': 'Atlantic Salmon',
#     'form': 'FIL',
#     'skin': 'SKON',
#     'bone': 'BNLS',
#     'trim': 'D',
#     'size': '6OZ',
#     'size_bucket': '6-8OZ',
#     'pack': 'IVP',
#     'storage': 'FRZ'
# }

# Get a comparison key for matching
key = fishlib.comparison_key(item)
print(key)
# "SALMON|ATLANTIC|FIL|SKON|BNLS|D|6-8OZ"

# Check if two items are comparable
distributor_item = "SALMON PORTION ATL BNLS SKLS 6 OZ CENTER CUT"
circana_item = "Portico Salmon Fillet 6 oz Boneless / Skinless"

match = fishlib.match(distributor_item, circana_item)
print(match)
# {
#     'is_match': True,
#     'confidence': 0.85,
#     'differences': ['form: PORTION vs FIL'],
#     'recommendation': 'Comparable with caution - form differs'
# }

Features

Parse Item Descriptions

Turn messy text into structured data:

fishlib.parse("SALMON SOCKEYE FIL WILD ALASKA SKON 8OZ IQF")
# Returns structured dict with all attributes

Origin Tracking (v0.4.0)

Separate harvest and processing countries for accurate sourcing:

fishlib.parse("POLLOCK FIL WILD ALASKA PROCESSED IN CHINA 6OZ")
# Returns:
# {
#     'origin_harvest': 'USA',
#     'origin_processed': 'CHN',
#     'freeze_cycle': 'TWICE',
#     ...
# }

Freeze Cycle Inference (v0.4.0)

Automatically determines single-frozen vs twice-frozen:

• Finfish + Asian processing country → TWICE (twice-frozen)
• Finfish domestic processing → SINGLE (single-frozen)
• Crustaceans/mollusks → exempt
• Freeze cycle mismatch = hard block on comparability

Size Bucket Matching (v0.4.2)

Exact sizes and ranges map to competitive buckets for PMI comparisons:

fishlib.parse("POLLOCK FIL 2OZ")['size_bucket']    # '2-3OZ'
fishlib.parse("POLLOCK FIL 2-3OZ")['size_bucket']  # '2-3OZ'

# Now comparable!
fishlib.is_comparable("POLLOCK FIL 2OZ", "POLLOCK FIL 2-3OZ")  # True

Enhanced Attribute Extraction (v0.2.0)

# Crab meat grade detection
fishlib.parse("CRAB MEAT JUMBO LUMP PASTEURIZED")
# Returns: {'meat_grade': 'JUMBO_LUMP', ...}

# Preparation status (raw, cooked, smoked, cured)
fishlib.parse("SHRIMP 16/20 P&D COOKED")
# Returns: {'preparation': 'COOKED', ...}

# Value-added detection (breaded, stuffed, marinated, etc.)
fishlib.parse("COD FIL PANKO CRUSTED 4OZ")
# Returns: {'value_added': 'BREADED', ...}

Standardize Codes

Consistent codes across any data source:

Attribute	Codes
Form	FIL (Fillet), PRTN (Portion), LOIN, WHL (Whole), STEAK, etc.
Skin	SKON (Skin On), SKLS (Skinless), SKOFF (Skin Off)
Bone	BNLS (Boneless), BIN (Bone In), PBO (Pin Bone Out)
Trim	A, B, C, D, E (see Trim Guide)
Pack	IVP, IQF, CVP, BULK
Storage	FRZ (Frozen), FRSH (Fresh), RFRSH (Refreshed)
Meat Grade	JUMBO_LUMP, LUMP, BACKFIN, SPECIAL, CLAW
Preparation	RAW, COOKED, SMOKED, CURED
Value-Added	BREADED, STUFFED, MARINATED, GLAZED, BLACKENED, FORMED

Species Support

Built-in knowledge for 46 seafood categories and 90+ species:

• Salmon: Atlantic, King/Chinook, Sockeye, Coho, Keta/Chum, Pink
• Crab: King, Snow, Dungeness, Blue, Stone, Jonah, Soft Shell
• Lobster: Maine, Canadian, Warm Water
• Shrimp: White, Pink, Brown, Tiger, Rock, Royal Red
• Groundfish: Cod (Atlantic, Pacific, Black/Sablefish, Ling), Haddock, Pollock, Rockfish
• Flatfish: Flounder, Halibut, Sole (Dover, Petrale, Lemon, Rex, Gray)
• Shellfish: Scallops (Sea, Bay, Calico), Clams, Oysters, Mussels
• Snapper: Red, Yellowtail, Vermilion, Lane, Mangrove, Silk
• Grouper: Red, Black, Gag, Yellowedge, Scamp
• Catfish: US Farm-Raised (Domestic), Channel (Imported), Blue
• Other Finfish: Branzino, Sea Bass (Chilean, Black, Striped), Trout, Barramundi, Wahoo, Monkfish, Mahi, Swordfish, Tuna, Anchovy, Whiting, Perch, Sardine, Herring, Mackerel, Hake, Orange Roughy, Corvina, Cobia, Hamachi, Pike
• Other Shellfish: Crawfish, Calamari, Octopus, Langostino, Conch

Reference Data

Access industry knowledge:

# Salmon trim levels
fishlib.reference.trim_levels('salmon')
# Returns definitions for Trim A-E with skin status

# Species price tiers (relative positioning, not dollar amounts)
fishlib.species.get_price_tier('salmon', 'king')
# Returns: 'ultra-premium'

# Cut style definitions
fishlib.reference.cut_style('center_cut')
# Returns: {'description': 'Portions from center of fish only...', 'premium': True}

Match & Compare

Find comparable items across data sources:

# Simple match
fishlib.is_comparable(item1, item2)  # Returns True/False

# Detailed match with confidence score
fishlib.match(item1, item2)  # Returns match details

# Find best matches in a list
fishlib.find_matches(target_item, list_of_items, threshold=0.8)

Trim Guide (Salmon)

Trim	Description	Skin
A	Backbone off, bellybone off	ON
B	+ Backfin off, collarbone off, belly fat/fins off	ON
C	+ Pin bone out	ON
D	+ Back trimmed, tailpiece off, belly membrane off, nape trimmed	ON
E	Everything in D + skin removed	OFF

Key insight: Trim A-D are all skin ON. Only Trim E is skin OFF. Foodservice standard: Trim D (skin on) and Trim E (skin off).

Cut Styles (Portions)

Style	Description	Value
Center Cut	From center of fish only, no tails/nape	Premium
Bias	Cut at angle for better presentation	Premium
Block	Straight cuts end-to-end, includes tails	Mid
Random	Mixed pieces, various shapes	Value

Why This Exists

In food distribution, comparing prices requires knowing if products are truly comparable. A "6oz salmon fillet" from two different sources might be:

• Center-cut bias portion (premium)
• Block-cut with tail pieces (commodity)

Without the right attributes, price comparisons are meaningless. fishlib encodes the domain knowledge needed to make accurate comparisons—so you don't need 20 years of fish experience to work with seafood data.

Changelog

See CHANGELOG.md for full version history.

Latest: v0.4.3

• Rockfish: Own category (Pacific Rockfish / Sebastes) — no longer misclassified as Striped Bass
• Striped Bass: Reversed word order ("BASS STRIPED") now parses correctly
• Catfish: Split into Domestic (US farm-raised), Channel (imported), and Blue subspecies
• Scallop: Fixed false-match on standalone "SEA" alias

v0.4.2

• Size buckets: 2OZ and 2-3OZ now match for competitive comparisons

v0.4.0

• Origin split: Separate harvest vs processing country tracking
• Freeze cycle: Automatic single-frozen vs twice-frozen inference

v0.3.0

• 14 new species: Anchovy, Whiting, Perch, Sardine, Herring, Mackerel, Hake, Orange Roughy, Corvina, Cobia, Langostino, Conch, Hamachi, Pike

v0.2.0

• New attributes: meat_grade, preparation, value_added
• 19 new species: Snapper, Grouper, Branzino, Sea Bass, Trout, Barramundi, Wahoo, Monkfish, Crawfish

v0.1.0

• Initial release

Contributing

Contributions welcome! Areas of interest:

• Additional species and regional variants
• International market terminology
• Packaging and processing codes

Author

Karen Morton — Seafood industry professional with 20+ years of experience in category management and procurement.

Built from years of experience managing seafood categories and the realization that this knowledge should be accessible to everyone, not trapped in experts' heads.

License

MIT License — Use it, modify it, share it. Just make seafood data better for everyone.