monkeybrain-runtime 1.0.0__py3-none-any.whl

services/suppliers/routers/supplier_inventory.py

@@ -0,0 +1,105 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.suppliers.helpers import supplier_inventory as crud
+from services.common.auth import require_permission
+from services.suppliers.models.supplier_inventory import (
+    PaginatedSupplierInventoryResponse,
+    SupplierInventoryCreate,
+    SupplierInventoryResponse,
+    SupplierInventoryUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedSupplierInventoryResponse)
+async def list_supplier_inventory(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSupplierInventoryResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-supplier/{supplier_id}", response_model=list[SupplierInventoryResponse])
+async def list_supplier_inventory_by_supplier(
+    supplier_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_supplier(db, supplier_id)
+
+
+@router.get("/by-item/{item_id}", response_model=list[SupplierInventoryResponse])
+async def list_supplier_inventory_by_item(
+    item_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_item(db, item_id)
+
+
+@router.get("/by-location/{location_id}", response_model=list[SupplierInventoryResponse])
+async def list_supplier_inventory_by_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_location(db, location_id)
+
+
+@router.get("/by-sku/{sku}", response_model=list[SupplierInventoryResponse])
+async def list_supplier_inventory_by_sku(
+    sku: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_sku(db, sku)
+
+
+@router.get("/{supplier_inventory_id}", response_model=SupplierInventoryResponse)
+async def get_supplier_inventory(
+    supplier_inventory_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    record = await crud.get_by_id(db, supplier_inventory_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier inventory '{supplier_inventory_id}' not found")
+    return record
+
+
+@router.post("/", response_model=SupplierInventoryResponse, status_code=status.HTTP_201_CREATED)
+async def create_supplier_inventory(
+    data: SupplierInventoryCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-products")),
+):
+    return await crud.create(db, data)
+
+
+@router.patch("/{supplier_inventory_id}", response_model=SupplierInventoryResponse)
+async def update_supplier_inventory(
+    supplier_inventory_id: str,
+    data: SupplierInventoryUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-products")),
+):
+    updated = await crud.update(db, supplier_inventory_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier inventory '{supplier_inventory_id}' not found")
+    return updated
+
+
+@router.delete("/{supplier_inventory_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_supplier_inventory(
+    supplier_inventory_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-products")),
+):
+    if not await crud.delete(db, supplier_inventory_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier inventory '{supplier_inventory_id}' not found")

services/suppliers/routers/supplier_locations.py

@@ -0,0 +1,89 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.suppliers.helpers import supplier_locations as crud
+from services.common.auth import require_permission
+from services.suppliers.models.supplier_locations import (
+    PaginatedSupplierLocationResponse,
+    SupplierLocationCreate,
+    SupplierLocationResponse,
+    SupplierLocationUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedSupplierLocationResponse)
+async def list_supplier_locations(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSupplierLocationResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-supplier/{supplier_id}", response_model=list[SupplierLocationResponse])
+async def list_supplier_locations_by_supplier(
+    supplier_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_supplier(db, supplier_id)
+
+
+@router.get("/by-item/{item_id}", response_model=list[SupplierLocationResponse])
+async def list_supplier_locations_by_item(
+    item_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_item(db, item_id)
+
+
+@router.get("/{location_id}", response_model=SupplierLocationResponse)
+async def get_supplier_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    record = await crud.get_by_id(db, location_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier location '{location_id}' not found")
+    return record
+
+
+@router.post("/", response_model=SupplierLocationResponse, status_code=status.HTTP_201_CREATED)
+async def create_supplier_location(
+    data: SupplierLocationCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-products")),
+):
+    if await crud.get_by_id(db, data.location_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"Supplier location '{data.location_id}' already exists")
+    return await crud.create(db, data)
+
+
+@router.patch("/{location_id}", response_model=SupplierLocationResponse)
+async def update_supplier_location(
+    location_id: str,
+    data: SupplierLocationUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-products")),
+):
+    updated = await crud.update(db, location_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier location '{location_id}' not found")
+    return updated
+
+
+@router.delete("/{location_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_supplier_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-products")),
+):
+    if not await crud.delete(db, location_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier location '{location_id}' not found")

services/suppliers/routers/supplier_pricing.py

@@ -0,0 +1,96 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.suppliers.helpers import supplier_pricing as crud
+from services.common.auth import require_permission
+from services.suppliers.models.supplier_pricing import (
+    PaginatedSupplierPricingResponse,
+    SupplierPricingCreate,
+    SupplierPricingResponse,
+    SupplierPricingUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedSupplierPricingResponse)
+async def list_supplier_pricing(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSupplierPricingResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-supplier/{supplier_id}", response_model=list[SupplierPricingResponse])
+async def list_supplier_pricing_by_supplier(
+    supplier_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_supplier(db, supplier_id)
+
+
+@router.get("/by-item/{item_id}", response_model=list[SupplierPricingResponse])
+async def list_supplier_pricing_by_item(
+    item_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_item(db, item_id)
+
+
+@router.get("/by-location/{location_id}", response_model=list[SupplierPricingResponse])
+async def list_supplier_pricing_by_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_location(db, location_id)
+
+
+@router.get("/{supplier_pricing_id}", response_model=SupplierPricingResponse)
+async def get_supplier_pricing(
+    supplier_pricing_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    record = await crud.get_by_id(db, supplier_pricing_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier pricing '{supplier_pricing_id}' not found")
+    return record
+
+
+@router.post("/", response_model=SupplierPricingResponse, status_code=status.HTTP_201_CREATED)
+async def create_supplier_pricing(
+    data: SupplierPricingCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-products")),
+):
+    return await crud.create(db, data)
+
+
+@router.patch("/{supplier_pricing_id}", response_model=SupplierPricingResponse)
+async def update_supplier_pricing(
+    supplier_pricing_id: str,
+    data: SupplierPricingUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-products")),
+):
+    updated = await crud.update(db, supplier_pricing_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier pricing '{supplier_pricing_id}' not found")
+    return updated
+
+
+@router.delete("/{supplier_pricing_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_supplier_pricing(
+    supplier_pricing_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-products")),
+):
+    if not await crud.delete(db, supplier_pricing_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier pricing '{supplier_pricing_id}' not found")

services/suppliers/routers/supplier_quality.py

@@ -0,0 +1,96 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.suppliers.helpers import supplier_quality as crud
+from services.common.auth import require_permission
+from services.suppliers.models.supplier_quality import (
+    PaginatedSupplierQualityResponse,
+    SupplierQualityCreate,
+    SupplierQualityResponse,
+    SupplierQualityUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedSupplierQualityResponse)
+async def list_supplier_quality(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSupplierQualityResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-supplier/{supplier_id}", response_model=list[SupplierQualityResponse])
+async def list_supplier_quality_by_supplier(
+    supplier_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_supplier(db, supplier_id)
+
+
+@router.get("/by-item/{item_id}", response_model=list[SupplierQualityResponse])
+async def list_supplier_quality_by_item(
+    item_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_item(db, item_id)
+
+
+@router.get("/by-location/{location_id}", response_model=list[SupplierQualityResponse])
+async def list_supplier_quality_by_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_location(db, location_id)
+
+
+@router.get("/{supplier_quality_id}", response_model=SupplierQualityResponse)
+async def get_supplier_quality(
+    supplier_quality_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    record = await crud.get_by_id(db, supplier_quality_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier quality '{supplier_quality_id}' not found")
+    return record
+
+
+@router.post("/", response_model=SupplierQualityResponse, status_code=status.HTTP_201_CREATED)
+async def create_supplier_quality(
+    data: SupplierQualityCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-products")),
+):
+    return await crud.create(db, data)
+
+
+@router.patch("/{supplier_quality_id}", response_model=SupplierQualityResponse)
+async def update_supplier_quality(
+    supplier_quality_id: str,
+    data: SupplierQualityUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-products")),
+):
+    updated = await crud.update(db, supplier_quality_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier quality '{supplier_quality_id}' not found")
+    return updated
+
+
+@router.delete("/{supplier_quality_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_supplier_quality(
+    supplier_quality_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-products")),
+):
+    if not await crud.delete(db, supplier_quality_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier quality '{supplier_quality_id}' not found")

services/suppliers/routers/supplier_shipping.py

@@ -0,0 +1,96 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.db import get_database
+from services.suppliers.helpers import supplier_shipping as crud
+from services.common.auth import require_permission
+from services.suppliers.models.supplier_shipping import (
+    PaginatedSupplierShippingResponse,
+    SupplierShippingCreate,
+    SupplierShippingResponse,
+    SupplierShippingUpdate,
+)
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedSupplierShippingResponse)
+async def list_supplier_shipping(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedSupplierShippingResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-supplier/{supplier_id}", response_model=list[SupplierShippingResponse])
+async def list_supplier_shipping_by_supplier(
+    supplier_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_supplier(db, supplier_id)
+
+
+@router.get("/by-item/{item_id}", response_model=list[SupplierShippingResponse])
+async def list_supplier_shipping_by_item(
+    item_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_item(db, item_id)
+
+
+@router.get("/by-location/{location_id}", response_model=list[SupplierShippingResponse])
+async def list_supplier_shipping_by_location(
+    location_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    return await crud.get_by_location(db, location_id)
+
+
+@router.get("/{supplier_shipping_id}", response_model=SupplierShippingResponse)
+async def get_supplier_shipping(
+    supplier_shipping_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-products")),
+):
+    record = await crud.get_by_id(db, supplier_shipping_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier shipping '{supplier_shipping_id}' not found")
+    return record
+
+
+@router.post("/", response_model=SupplierShippingResponse, status_code=status.HTTP_201_CREATED)
+async def create_supplier_shipping(
+    data: SupplierShippingCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-products")),
+):
+    return await crud.create(db, data)
+
+
+@router.patch("/{supplier_shipping_id}", response_model=SupplierShippingResponse)
+async def update_supplier_shipping(
+    supplier_shipping_id: str,
+    data: SupplierShippingUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-products")),
+):
+    updated = await crud.update(db, supplier_shipping_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier shipping '{supplier_shipping_id}' not found")
+    return updated
+
+
+@router.delete("/{supplier_shipping_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_supplier_shipping(
+    supplier_shipping_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-products")),
+):
+    if not await crud.delete(db, supplier_shipping_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"Supplier shipping '{supplier_shipping_id}' not found")

services/supply_allocation/main.py

@@ -0,0 +1,46 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from services.common.cors import cors_allow_origins
+
+from services.common.db import close_db, connect_db
+from services.common.logging import configure_service_logging, install_request_logging
+from services.common.tracing import install_route_tracing
+from services.supply_allocation.routers.allocation import router as allocation_router
+
+
+logger = configure_service_logging("supply_allocation")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await connect_db()
+    yield
+    await close_db()
+
+
+app = FastAPI(
+    title="Supply Allocation Service",
+    description="Microservice for available-to-promise, reservations, commitments, and allocation arbitration across demand sources.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+install_request_logging(app, "supply_allocation")
+install_route_tracing(app, "supply_allocation")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=cors_allow_origins(),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(allocation_router, prefix="/api/v1/supply-allocation", tags=["Supply Allocation"])
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    return {"status": "healthy"}

services/supply_allocation/routers/__init__.py

@@ -0,0 +1 @@
+

services/supply_allocation/routers/allocation.py

@@ -0,0 +1,20 @@
+from fastapi import APIRouter
+
+
+router = APIRouter()
+
+
+@router.get("/capabilities")
+async def capabilities() -> dict:
+    return {
+        "service": "supply_allocation",
+        "capabilities": [
+            "available_to_promise",
+            "available_to_allocate",
+            "reservation_commitment",
+            "demand_arbitration",
+            "allocation_policy",
+            "shortage_detection",
+        ],
+        "status": "scaffolded",
+    }

services/taxonomy/helpers/__init__.py

@@ -0,0 +1,7 @@
+"""taxonomy service helpers package."""
+
+__all__ = [
+    "classes",
+    "family",
+    "subclass",
+]

services/taxonomy/helpers/classes.py

@@ -0,0 +1,48 @@
+from typing import Optional
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from services.taxonomy.models.classes import EquipmentClassCreate, EquipmentClassUpdate
+
+COLLECTION = "classes"
+
+
+def _serialize(doc: dict) -> dict:
+    doc.pop("_id", None)
+    return doc
+
+async def get_all(
+    db: AsyncIOMotorDatabase,
+    page: int = 1,
+    page_size: int = 20
+) -> tuple[list[dict], int]:
+    query: dict = {}
+    total = await db[COLLECTION].count_documents(query)
+    cursor = db[COLLECTION].find(query).skip((page - 1) * page_size).limit(page_size)
+    return [_serialize(d) async for d in cursor], total
+
+
+async def get_by_id(db: AsyncIOMotorDatabase, class_id: str) -> Optional[dict]:
+    doc = await db[COLLECTION].find_one({"id": class_id})
+    return _serialize(doc) if doc else None
+
+
+async def create(db: AsyncIOMotorDatabase, data: EquipmentClassCreate) -> dict:
+    doc = data.model_dump()
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(
+    db: AsyncIOMotorDatabase, class_id: str, data: EquipmentClassUpdate
+) -> Optional[dict]:
+    fields = {k: v for k, v in data.model_dump().items() if v is not None}
+    if not fields:
+        return await get_by_id(db, class_id)
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": class_id}, {"$set": fields}, return_document=True
+    )
+    return _serialize(result) if result else None
+
+
+async def delete(db: AsyncIOMotorDatabase, class_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": class_id})
+    return result.deleted_count == 1

services/taxonomy/helpers/family.py

@@ -0,0 +1,53 @@
+from typing import Optional
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from services.taxonomy.models.family import FamilyCreate, FamilyUpdate
+
+COLLECTION = "families"
+
+
+def _serialize(doc: dict) -> dict:
+    doc.pop("_id", None)
+    return doc
+
+
+async def get_all(
+    db: AsyncIOMotorDatabase,
+    page: int = 1,
+    page_size: int = 20,
+    tag: Optional[str] = None,
+) -> tuple[list[dict], int]:
+    query: dict = {}
+    if tag:
+        query["tags"] = tag
+
+    total = await db[COLLECTION].count_documents(query)
+    cursor = db[COLLECTION].find(query).skip((page - 1) * page_size).limit(page_size)
+    return [_serialize(d) async for d in cursor], total
+
+
+async def get_by_id(db: AsyncIOMotorDatabase, family_id: str) -> Optional[dict]:
+    doc = await db[COLLECTION].find_one({"id": family_id})
+    return _serialize(doc) if doc else None
+
+
+async def create(db: AsyncIOMotorDatabase, data: FamilyCreate) -> dict:
+    doc = data.model_dump()
+    await db[COLLECTION].insert_one(doc)
+    return _serialize(doc)
+
+
+async def update(
+    db: AsyncIOMotorDatabase, family_id: str, data: FamilyUpdate
+) -> Optional[dict]:
+    fields = {k: v for k, v in data.model_dump().items() if v is not None}
+    if not fields:
+        return await get_by_id(db, family_id)
+    result = await db[COLLECTION].find_one_and_update(
+        {"id": family_id}, {"$set": fields}, return_document=True
+    )
+    return _serialize(result) if result else None
+
+
+async def delete(db: AsyncIOMotorDatabase, family_id: str) -> bool:
+    result = await db[COLLECTION].delete_one({"id": family_id})
+    return result.deleted_count == 1