Update models dependency to v2.1.0 and enhance item lifecycle and benchmark APIs

- Updated the models dependency in requirements.txt to version 2.1.0.
- Added new item lifecycle and benchmark routes in main.py to expand API functionality.
- Enhanced item creation logic in item.py to link existing items to catalog products based on brand and product IDs.
- Improved product enrichment task in enrich_product.py to update linked items with catalog product IDs.

Author: maplethorpej

app/api/benchmark.py

@@ -0,0 +1,64 @@
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi_sqlalchemy import db
+from pydantic import BaseModel
+from typing import Optional
+
+from models.base import User, CategoryBenchmark
+from utils.auth import authenticate
+from utils.gear_lifecycle import get_all_benchmarks, DEFAULT_BENCHMARKS
+
+logger = logging.getLogger(__name__)
+
+route = APIRouter(dependencies=[Depends(authenticate)])
+
+
+@route.get("")
+def fetch_benchmarks(user: User = Depends(authenticate)):
+    return get_all_benchmarks(db.session, user.id)
+
+
+class BenchmarkUpdate(BaseModel):
+    lifespan_years: Optional[float] = None
+    expected_nights: Optional[float] = None
+    expected_distance: Optional[float] = None
+    distance_unit: Optional[str] = None
+
+
+@route.put("/{category_name}")
+def upsert_benchmark(category_name: str, payload: BenchmarkUpdate, user: User = Depends(authenticate)):
+    if category_name not in DEFAULT_BENCHMARKS:
+        raise HTTPException(400, f"Unknown category: {category_name}")
+
+    override = db.session.query(CategoryBenchmark).filter_by(
+        user_id=user.id, category_name=category_name
+    ).first()
+
+    if not override:
+        override = CategoryBenchmark(user_id=user.id, category_name=category_name)
+        db.session.add(override)
+
+    fields = payload.dict(exclude_none=True)
+    for key, value in fields.items():
+        setattr(override, key, value)
+
+    try:
+        db.session.commit()
+        db.session.refresh(override)
+    except Exception:
+        logger.exception("Failed to update benchmark")
+        raise HTTPException(400, "Unable to update benchmark.")
+
+    return get_all_benchmarks(db.session, user.id)
+
+
+@route.delete("/{category_name}", status_code=204)
+def reset_benchmark(category_name: str, user: User = Depends(authenticate)):
+    override = db.session.query(CategoryBenchmark).filter_by(
+        user_id=user.id, category_name=category_name
+    ).first()
+
+    if override:
+        db.session.delete(override)
+        db.session.commit()

app/api/item.py

@@ -8,7 +8,7 @@
 from io import StringIO
 from sqlalchemy import or_, func
 
-from models.base import User, Item, ItemCategory, Category, Brand, Product, ProductVariant
+from models.base import User, Item, ItemCategory, Category, Brand, Product, ProductVariant, CatalogProduct
 from utils.auth import authenticate
 from utils.weight import standardize_weight_unit
 from utils.item_category import get_or_create_item_category
@@ -39,6 +39,28 @@ class ItemType(BaseModel):
     wishlist: bool = None
     notes: str = None
 
+    acquired_date: str = None
+    acquisition_type: str = None
+    purchase_retailer: str = None
+    condition: str = None
+    status: str = None
+    retired_date: str = None
+    retired_reason: str = None
+    replaced_by_id: int = None
+
+
+def _find_catalog_product(session, brand_id: int, product_id: int, product_variant_id: int | None):
+    q = session.query(CatalogProduct).filter(
+        CatalogProduct.brand_id == brand_id,
+        CatalogProduct.product_id == product_id,
+        CatalogProduct.status == "approved",
+    )
+    if product_variant_id:
+        q = q.filter(CatalogProduct.product_variant_id == product_variant_id)
+    else:
+        q = q.filter(CatalogProduct.product_variant_id.is_(None))
+    return q.first()
+
 
 @route.post("", status_code=201)
 def create(payload: ItemType, user: User = Depends(authenticate)):
@@ -56,6 +78,14 @@ def create(payload: ItemType, user: User = Depends(authenticate)):
 
     new_item = Item(user_id=user.id, **item_data)
 
+    if new_item.brand_id and new_item.product_id:
+        catalog_match = _find_catalog_product(
+            db.session, new_item.brand_id, new_item.product_id,
+            new_item.product_variant_id
+        )
+        if catalog_match:
+            new_item.catalog_product_id = catalog_match.id
+
     try:
         db.session.add(new_item)
         db.session.commit()

app/api/item_lifecycle.py

@@ -0,0 +1,164 @@
+import datetime
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi_sqlalchemy import db
+from pydantic import BaseModel
+from typing import Optional
+
+from models.base import User, Item, ItemLog
+from utils.auth import authenticate
+from utils.gear_lifecycle import replacement_score, get_benchmark
+
+logger = logging.getLogger(__name__)
+
+route = APIRouter(dependencies=[Depends(authenticate)])
+
+VALID_CONDITIONS = {"new", "good", "fair", "worn", "retired"}
+VALID_STATUSES = {"active", "wishlist", "retired", "sold", "lost"}
+VALID_ACQUISITION_TYPES = {"purchased", "gifted", "traded", "diy"}
+VALID_RETIRED_REASONS = {"worn_out", "upgraded", "lost", "sold", "gifted"}
+
+
+class LifecycleUpdate(BaseModel):
+    acquired_date: str = None
+    acquisition_type: str = None
+    purchase_retailer: str = None
+    condition: str = None
+    status: str = None
+    retired_date: str = None
+    retired_reason: str = None
+    replaced_by_id: int = None
+
+
+@route.put("/{item_id}/lifecycle")
+def update_lifecycle(item_id: int, payload: LifecycleUpdate, user: User = Depends(authenticate)):
+    item = db.session.query(Item).filter_by(id=item_id, user_id=user.id).first()
+    if not item:
+        raise HTTPException(404, "Item not found.")
+
+    if payload.condition and payload.condition not in VALID_CONDITIONS:
+        raise HTTPException(400, f"Invalid condition. Must be one of: {', '.join(VALID_CONDITIONS)}")
+
+    if payload.status and payload.status not in VALID_STATUSES:
+        raise HTTPException(400, f"Invalid status. Must be one of: {', '.join(VALID_STATUSES)}")
+
+    if payload.acquisition_type and payload.acquisition_type not in VALID_ACQUISITION_TYPES:
+        raise HTTPException(400, f"Invalid acquisition_type. Must be one of: {', '.join(VALID_ACQUISITION_TYPES)}")
+
+    if payload.retired_reason and payload.retired_reason not in VALID_RETIRED_REASONS:
+        raise HTTPException(400, f"Invalid retired_reason. Must be one of: {', '.join(VALID_RETIRED_REASONS)}")
+
+    if payload.replaced_by_id:
+        replacement = db.session.query(Item).filter_by(
+            id=payload.replaced_by_id, user_id=user.id
+        ).first()
+        if not replacement:
+            raise HTTPException(400, "Replacement item not found.")
+
+    old_condition = item.condition
+
+    fields = payload.dict(exclude_none=True)
+    for key, value in fields.items():
+        setattr(item, key, value)
+
+    if payload.condition and payload.condition != old_condition:
+        log_entry = ItemLog(
+            item_id=item.id,
+            user_id=user.id,
+            event_type="condition_change",
+            event_date=datetime.date.today(),
+            old_condition=old_condition,
+            new_condition=payload.condition,
+        )
+        db.session.add(log_entry)
+
+    try:
+        db.session.commit()
+        db.session.refresh(item)
+    except Exception:
+        logger.exception("Failed to update item lifecycle")
+        raise HTTPException(400, "Unable to update item lifecycle.")
+
+    return item
+
+
+VALID_EVENT_TYPES = {
+    "acquired", "condition_change", "repair", "maintenance",
+    "weight_check", "retired", "sold", "note",
+}
+
+
+class ItemLogCreate(BaseModel):
+    event_type: str
+    event_date: str
+    note: Optional[str] = None
+    old_condition: Optional[str] = None
+    new_condition: Optional[str] = None
+    old_weight: Optional[float] = None
+    new_weight: Optional[float] = None
+    cost: Optional[float] = None
+
+
+@route.post("/{item_id}/log", status_code=201)
+def create_log(item_id: int, payload: ItemLogCreate, user: User = Depends(authenticate)):
+    item = db.session.query(Item).filter_by(id=item_id, user_id=user.id).first()
+    if not item:
+        raise HTTPException(404, "Item not found.")
+
+    if payload.event_type not in VALID_EVENT_TYPES:
+        raise HTTPException(400, f"Invalid event_type. Must be one of: {', '.join(VALID_EVENT_TYPES)}")
+
+    log_entry = ItemLog(
+        item_id=item.id,
+        user_id=user.id,
+        **payload.dict(),
+    )
+
+    try:
+        db.session.add(log_entry)
+        db.session.commit()
+        db.session.refresh(log_entry)
+    except Exception:
+        logger.exception("Failed to create item log")
+        raise HTTPException(400, "Unable to create log entry.")
+
+    return log_entry
+
+
+@route.get("/{item_id}/log")
+def fetch_logs(item_id: int, user: User = Depends(authenticate)):
+    item = db.session.query(Item).filter_by(id=item_id, user_id=user.id).first()
+    if not item:
+        raise HTTPException(404, "Item not found.")
+
+    logs = db.session.query(ItemLog).filter_by(
+        item_id=item.id
+    ).order_by(ItemLog.event_date.desc(), ItemLog.created_at.desc()).all()
+
+    return logs
+
+
+@route.get("/{item_id}/replacement-score")
+def get_replacement_score(item_id: int, user: User = Depends(authenticate)):
+    item = db.session.query(Item).filter_by(id=item_id, user_id=user.id).first()
+    if not item:
+        raise HTTPException(404, "Item not found.")
+
+    category_name = (
+        item.category.category.name
+        if item.category and item.category.category
+        else "Miscellaneous"
+    )
+
+    benchmark = get_benchmark(db.session, user.id, category_name)
+    score = replacement_score(item.acquired_date, item.condition, benchmark)
+
+    return {
+        "item_id": item.id,
+        "score": score,
+        "category": category_name,
+        "benchmark": benchmark,
+        "acquired_date": str(item.acquired_date) if item.acquired_date else None,
+        "condition": item.condition,
+    }

app/main.py

@@ -5,7 +5,7 @@
 from sqlalchemy import create_engine
 
 from utils.consts import DATABASE_URL, DEVELOPMENT, APP_HOST
-from api import user, resources, item, trip, category, pack, kit, hiker_profile, webhook
+from api import user, resources, item, item_lifecycle, benchmark, trip, category, pack, kit, hiker_profile, webhook
 
 ENGINE_KWARGS = dict(
     pool_size=5,
@@ -65,6 +65,20 @@
     responses={404: {"description": "Not found"}}
 )
 
+app.include_router(
+    item_lifecycle.route,
+    prefix="/item",
+    tags=["item-lifecycle"],
+    responses={404: {"description": "Not found"}}
+)
+
+app.include_router(
+    benchmark.route,
+    prefix="/benchmark",
+    tags=["benchmark"],
+    responses={404: {"description": "Not found"}}
+)
+
 
 app.include_router(
     trip.route,

app/tasks/enrich_product.py

@@ -585,4 +585,19 @@ def enrich_product(self, brand_id: int, product_id: int, product_variant_id: int
         session.commit()
         logger.info("Inserted %s (confidence=%.3f)", display_name, confidence)
 
+        variant_filter = (
+            Item.product_variant_id == variant.id
+            if variant
+            else Item.product_variant_id.is_(None)
+        )
+        linked = session.query(Item).filter(
+            Item.brand_id == brand.id,
+            Item.product_id == product.id,
+            variant_filter,
+            Item.catalog_product_id.is_(None),
+        ).update({"catalog_product_id": entry.id}, synchronize_session=False)
+        if linked:
+            session.commit()
+            logger.info("Linked %d existing items to catalog product %d", linked, entry.id)
+
         find_product_image.delay(entry.id)