taster 3.1.0__py3-none-any.whl

sommelier/__init__.py

@@ -0,0 +1,2 @@
+"""Sommelier - Teach AI your taste. Apply it to everything."""
+__version__ = "3.1.0"

sommelier/api/__init__.py

@@ -0,0 +1,4 @@
+"""Sommelier REST API."""
+from .app import create_app
+
+__all__ = ["create_app"]

sommelier/api/app.py

@@ -0,0 +1,44 @@
+"""FastAPI application factory for the Sommelier API."""
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from sommelier import __version__
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Sommelier API",
+        description="Universal AI-powered media classification platform",
+        version=__version__,
+    )
+
+    # CORS middleware for frontend access
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Mount routers
+    from sommelier.api.routers.profiles import router as profiles_router
+    from sommelier.api.routers.classify import router as classify_router
+    from sommelier.api.routers.results import router as results_router
+    from sommelier.api.routers.training import router as training_router
+
+    app.include_router(profiles_router)
+    app.include_router(classify_router)
+    app.include_router(results_router)
+    app.include_router(training_router)
+
+    @app.get("/")
+    async def root():
+        return {
+            "name": "Sommelier API",
+            "version": __version__,
+            "docs": "/docs",
+        }
+
+    return app

sommelier/api/models.py

@@ -0,0 +1,194 @@
+"""Pydantic models for the API layer."""
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ── Profile models ──────────────────────────────────────────────────────
+
+class CategoryDefinitionModel(BaseModel):
+    """A single output category."""
+    name: str
+    description: str
+    color: Optional[str] = None
+
+
+class PhotoProfileSettingsModel(BaseModel):
+    """Photo/video-specific settings."""
+    enable_burst_detection: bool = True
+    enable_face_detection: bool = True
+    contains_children_check: bool = True
+    appropriateness_check: bool = True
+
+
+class DocumentProfileSettingsModel(BaseModel):
+    """Document-specific settings."""
+    extract_text: bool = True
+    extract_metadata: bool = True
+    enable_similarity_grouping: bool = True
+    similarity_threshold: float = 0.85
+    max_pages_to_analyze: int = 10
+
+
+class ProfileCreate(BaseModel):
+    """Request body for creating a new profile."""
+    name: str = Field(..., min_length=1, max_length=128)
+    description: str = ""
+    media_types: List[str] = Field(default_factory=lambda: ["image"])
+    categories: List[CategoryDefinitionModel] = Field(default_factory=list)
+    default_category: str = "Review"
+    top_priorities: List[str] = Field(default_factory=list)
+    positive_criteria: Dict[str, List[str]] = Field(default_factory=dict)
+    negative_criteria: Dict[str, List[str]] = Field(default_factory=dict)
+    specific_guidance: List[str] = Field(default_factory=list)
+    philosophy: str = ""
+    thresholds: Dict[str, float] = Field(default_factory=dict)
+    photo_settings: Optional[PhotoProfileSettingsModel] = None
+    document_settings: Optional[DocumentProfileSettingsModel] = None
+
+
+class ProfileUpdate(BaseModel):
+    """Request body for updating a profile (all fields optional)."""
+    description: Optional[str] = None
+    media_types: Optional[List[str]] = None
+    categories: Optional[List[CategoryDefinitionModel]] = None
+    default_category: Optional[str] = None
+    top_priorities: Optional[List[str]] = None
+    positive_criteria: Optional[Dict[str, List[str]]] = None
+    negative_criteria: Optional[Dict[str, List[str]]] = None
+    specific_guidance: Optional[List[str]] = None
+    philosophy: Optional[str] = None
+    thresholds: Optional[Dict[str, float]] = None
+    photo_settings: Optional[PhotoProfileSettingsModel] = None
+    document_settings: Optional[DocumentProfileSettingsModel] = None
+
+
+class ProfileSummary(BaseModel):
+    """Summary view of a profile (for listing)."""
+    name: str
+    description: str
+    media_types: List[str]
+    categories: List[str]
+    created_at: str
+    updated_at: str
+    version: int
+
+
+class ProfileDetail(BaseModel):
+    """Full detail view of a profile."""
+    name: str
+    description: str
+    media_types: List[str]
+    categories: List[CategoryDefinitionModel]
+    default_category: str
+    top_priorities: List[str]
+    positive_criteria: Dict[str, List[str]]
+    negative_criteria: Dict[str, List[str]]
+    specific_guidance: List[str]
+    philosophy: str
+    thresholds: Dict[str, float]
+    photo_settings: Optional[PhotoProfileSettingsModel] = None
+    document_settings: Optional[DocumentProfileSettingsModel] = None
+    created_at: str
+    updated_at: str
+    version: int
+
+
+# ── Classification / job models ─────────────────────────────────────────
+
+class JobStatus(str, Enum):
+    """Status of a classification job."""
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class ClassifyFolderRequest(BaseModel):
+    """Request body for classifying a local folder."""
+    folder_path: str
+    profile_name: str = "default-photos"
+    dry_run: bool = False
+
+
+class JobStatusResponse(BaseModel):
+    """Status information for a classification job."""
+    job_id: str
+    status: JobStatus
+    profile_name: str
+    folder_path: Optional[str] = None
+    progress: float = 0.0
+    total_files: int = 0
+    processed_files: int = 0
+    created_at: str
+    completed_at: Optional[str] = None
+    error: Optional[str] = None
+
+
+class ClassificationResultItem(BaseModel):
+    """A single file's classification result."""
+    file_path: str
+    file_name: str
+    category: str
+    confidence: Optional[float] = None
+    reasoning: Optional[str] = None
+    burst_size: int = 1
+
+
+class JobResultsResponse(BaseModel):
+    """Full results for a completed classification job."""
+    job_id: str
+    status: JobStatus
+    profile_name: str
+    stats: Dict[str, int] = Field(default_factory=dict)
+    results: List[ClassificationResultItem] = Field(default_factory=list)
+
+
+# ── Results / export models ──────────────────────────────────────────────
+
+class FileInCategory(BaseModel):
+    """A file listed within a category."""
+    file_path: str
+    file_name: str
+    confidence: Optional[float] = None
+    reasoning: Optional[str] = None
+
+
+class CategoryFiles(BaseModel):
+    """Files belonging to a specific category."""
+    category: str
+    count: int
+    files: List[FileInCategory]
+
+
+# ── Training / feedback models ───────────────────────────────────────────
+
+class FeedbackItem(BaseModel):
+    """User feedback on a single classification."""
+    file_path: str
+    original_category: str
+    corrected_category: str
+    notes: Optional[str] = None
+
+
+class FeedbackRequest(BaseModel):
+    """Request body for submitting feedback."""
+    job_id: Optional[str] = None
+    profile_name: str = "default-photos"
+    feedback: List[FeedbackItem]
+
+
+class GenerateProfileRequest(BaseModel):
+    """Request body for generating a profile from feedback."""
+    profile_name: str = Field(..., min_length=1)
+    base_profile: Optional[str] = None
+    examples_folder: Optional[str] = None
+
+
+class TrainingStats(BaseModel):
+    """Statistics about collected training data."""
+    total_feedback_items: int = 0
+    profiles_with_feedback: List[str] = Field(default_factory=list)
+    corrections_by_category: Dict[str, int] = Field(default_factory=dict)

sommelier/api/routers/__init__.py

@@ -0,0 +1 @@
+"""API routers."""

sommelier/api/routers/classify.py

@@ -0,0 +1,55 @@
+"""Classification endpoints."""
+from fastapi import APIRouter, HTTPException
+
+from sommelier.api.models import ClassifyFolderRequest, JobStatusResponse
+from sommelier.api.services.classification_service import ClassificationService
+from sommelier.core.config import load_config
+
+router = APIRouter(prefix="/api/classify", tags=["classify"])
+
+_service = None
+
+
+def _get_service() -> ClassificationService:
+    global _service
+    if _service is None:
+        config = load_config()
+        _service = ClassificationService(config)
+    return _service
+
+
+@router.post("/folder")
+async def classify_folder(request: ClassifyFolderRequest):
+    """Start a classification job on a local folder."""
+    try:
+        svc = _get_service()
+        job_id = svc.start_job(
+            folder_path=request.folder_path,
+            profile_name=request.profile_name,
+            dry_run=request.dry_run,
+        )
+        return {"job_id": job_id, "status": "started"}
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/{job_id}")
+async def get_job_status(job_id: str):
+    """Get the status of a classification job."""
+    svc = _get_service()
+    status = svc.get_job_status(job_id)
+    if status is None:
+        raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found")
+    return status
+
+
+@router.get("/{job_id}/results")
+async def get_job_results(job_id: str):
+    """Get the results of a completed classification job."""
+    svc = _get_service()
+    results = svc.get_job_results(job_id)
+    if results is None:
+        raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found")
+    return results

sommelier/api/routers/profiles.py

@@ -0,0 +1,51 @@
+"""Profile CRUD endpoints."""
+from fastapi import APIRouter, HTTPException
+
+from sommelier.api.models import ProfileCreate, ProfileUpdate, ProfileSummary, ProfileDetail
+from sommelier.api.services.profile_service import ProfileService
+
+router = APIRouter(prefix="/api/profiles", tags=["profiles"])
+
+_service = ProfileService()
+
+
+@router.get("/", response_model=list[ProfileSummary])
+async def list_profiles():
+    """List all available taste profiles."""
+    return _service.list_profiles()
+
+
+@router.get("/{name}")
+async def get_profile(name: str):
+    """Get full details of a taste profile."""
+    try:
+        return _service.get_profile(name)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Profile '{name}' not found")
+
+
+@router.post("/", status_code=201)
+async def create_profile(data: ProfileCreate):
+    """Create a new taste profile."""
+    try:
+        return _service.create_profile(data.model_dump())
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.put("/{name}")
+async def update_profile(name: str, data: ProfileUpdate):
+    """Update an existing taste profile."""
+    try:
+        updates = {k: v for k, v in data.model_dump().items() if v is not None}
+        return _service.update_profile(name, updates)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Profile '{name}' not found")
+
+
+@router.delete("/{name}")
+async def delete_profile(name: str):
+    """Delete a taste profile."""
+    if _service.delete_profile(name):
+        return {"status": "deleted", "name": name}
+    raise HTTPException(status_code=404, detail=f"Profile '{name}' not found")

sommelier/api/routers/results.py

@@ -0,0 +1,66 @@
+"""Results and export endpoints."""
+import csv
+import io
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from sommelier.api.services.classification_service import ClassificationService
+from sommelier.core.config import load_config
+
+router = APIRouter(prefix="/api/results", tags=["results"])
+
+_service = None
+
+
+def _get_service() -> ClassificationService:
+    global _service
+    if _service is None:
+        config = load_config()
+        _service = ClassificationService(config)
+    return _service
+
+
+@router.get("/{job_id}")
+async def get_results(job_id: str):
+    """Get detailed results for a classification job."""
+    svc = _get_service()
+    results = svc.get_job_results(job_id)
+    if results is None:
+        raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found")
+    return results
+
+
+@router.get("/{job_id}/export")
+async def export_results(job_id: str, format: str = "csv"):
+    """Export classification results as CSV."""
+    svc = _get_service()
+    results = svc.get_job_results(job_id)
+    if results is None:
+        raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found")
+
+    if format == "csv":
+        output = io.StringIO()
+        if results:
+            writer = csv.DictWriter(output, fieldnames=results[0].keys())
+            writer.writeheader()
+            writer.writerows(results)
+        content = output.getvalue()
+        return StreamingResponse(
+            iter([content]),
+            media_type="text/csv",
+            headers={"Content-Disposition": f"attachment; filename=results_{job_id}.csv"},
+        )
+
+    return results
+
+
+@router.get("/{job_id}/files/{category}")
+async def list_files_in_category(job_id: str, category: str):
+    """List files classified into a specific category."""
+    svc = _get_service()
+    results = svc.get_job_results(job_id)
+    if results is None:
+        raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found")
+
+    filtered = [r for r in results if r.get("destination") == category]
+    return {"category": category, "count": len(filtered), "files": filtered}

sommelier/api/routers/training.py

@@ -0,0 +1,43 @@
+"""Training and feedback endpoints."""
+from fastapi import APIRouter, HTTPException
+
+from sommelier.api.models import FeedbackRequest, TrainingStats
+from sommelier.api.services.training_service import TrainingService
+
+router = APIRouter(prefix="/api/training", tags=["training"])
+
+_service = TrainingService()
+
+
+@router.post("/feedback")
+async def submit_feedback(request: FeedbackRequest):
+    """Submit classification feedback/corrections."""
+    results = []
+    for item in request.feedback:
+        result = _service.submit_feedback(
+            file_path=item.file_path,
+            correct_category=item.corrected_category,
+            reasoning=item.notes or "",
+        )
+        results.append(result)
+    return {"status": "received", "count": len(results)}
+
+
+@router.post("/generate-profile")
+async def generate_profile(profile_name: str):
+    """Generate a taste profile from accumulated feedback."""
+    try:
+        profile = _service.generate_profile_from_feedback(profile_name)
+        return {"status": "created", "profile": profile}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/stats", response_model=TrainingStats)
+async def get_stats():
+    """Get training data statistics."""
+    stats = _service.get_stats()
+    return TrainingStats(
+        total_feedback_items=stats.get("total_feedback", 0),
+        corrections_by_category=stats.get("by_category", {}),
+    )