US03-03: Generate and Persist Versioned Proposals (#63)
This commit was merged in pull request #63.
This commit is contained in:
326
photo_pipeline/services/proposals.py
Normal file
326
photo_pipeline/services/proposals.py
Normal file
@@ -0,0 +1,326 @@
|
||||
"""ProposalService — AI-assisted, versioned album naming proposals (US03-03).
|
||||
|
||||
Generates one durable proposal per album from the US03-01 evidence, names it through
|
||||
the US03-02 policy, and keeps rationale, confidence, evidence version, model/prompt
|
||||
version, edits, and approval state durable. **No rename ever happens here**: approval
|
||||
records intent, and Phase D performs the filesystem work.
|
||||
|
||||
Provider minimality — the adapter receives only a compact aggregated summary
|
||||
(album/folder name, date, top tags, top locations, counts and a few descriptions).
|
||||
Asset IDs, file paths, and raw model responses are never sent, so a proposal cannot
|
||||
leak per-photo identity into the naming provider.
|
||||
|
||||
Failure handling is explicit and safely retryable: a malformed response, a rate limit,
|
||||
or a provider error stores ``status='error'`` with an ``error_code`` and leaves the
|
||||
album eligible for another ``generate`` call. Retrying never duplicates a proposal —
|
||||
rows are keyed by album, so a regeneration updates the existing row and bumps its
|
||||
version.
|
||||
|
||||
Staleness: a proposal records the ``evidence_version`` it was generated from. When the
|
||||
album's current evidence version differs, the proposal reads back as ``stale`` and
|
||||
approval is refused until it is regenerated.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import uuid
|
||||
from datetime import datetime, timezone
|
||||
from typing import Protocol
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.orm import sessionmaker
|
||||
|
||||
from photo_pipeline.models import AlbumProposal
|
||||
from photo_pipeline.services.albums import AlbumService
|
||||
from photo_pipeline.services.naming import NamingPolicy, build_fields, render_name, validate
|
||||
|
||||
MODEL = "gemini-2.5-flash"
|
||||
PROMPT_VERSION = "1"
|
||||
# Bounds on what the provider is allowed to see, so the summary stays minimal.
|
||||
MAX_TAGS = 12
|
||||
MAX_LOCATIONS = 3
|
||||
MAX_DESCRIPTIONS = 5
|
||||
|
||||
PENDING = "pending"
|
||||
PROPOSED = "proposed"
|
||||
EDITED = "edited"
|
||||
APPROVED = "approved"
|
||||
ERROR = "error"
|
||||
|
||||
|
||||
class ProposalProvider(Protocol):
|
||||
def propose(self, summary: dict) -> dict:
|
||||
"""Return ``{name, rationale, confidence}`` for one album summary."""
|
||||
|
||||
|
||||
class ProposalError(RuntimeError):
|
||||
"""Invalid request against a proposal (unknown album, bad name, stale evidence)."""
|
||||
|
||||
|
||||
class ConflictError(RuntimeError):
|
||||
"""Optimistic version check failed; the proposal changed since it was read."""
|
||||
|
||||
|
||||
class ProviderError(RuntimeError):
|
||||
"""The naming provider failed. ``code`` distinguishes retryable causes."""
|
||||
|
||||
def __init__(self, code: str, message: str = "") -> None:
|
||||
super().__init__(message or code)
|
||||
self.code = code
|
||||
|
||||
|
||||
class RateLimited(ProviderError):
|
||||
def __init__(self, message: str = "rate limited") -> None:
|
||||
super().__init__("rate_limited", message)
|
||||
|
||||
|
||||
def _now() -> datetime:
|
||||
return datetime.now(timezone.utc)
|
||||
|
||||
|
||||
def evidence_summary(evidence: dict) -> dict:
|
||||
"""The minimum aggregated evidence a naming provider may see. Bounded and free of
|
||||
asset IDs and file paths."""
|
||||
return {
|
||||
"folder_name": evidence.get("folder_name"),
|
||||
"parent_path": evidence.get("parent_path"),
|
||||
"photo_count": evidence.get("asset_count"),
|
||||
"analyzed_count": evidence.get("analyzed_count"),
|
||||
"dominant_year": evidence.get("dominant_year"),
|
||||
"year_conflict": evidence.get("year_conflict"),
|
||||
"years": [item["value"] for item in (evidence.get("years") or [])],
|
||||
"top_tags": [item["value"] for item in (evidence.get("tags") or [])[:MAX_TAGS]],
|
||||
"locations": [item["value"] for item in (evidence.get("locations") or [])[:MAX_LOCATIONS]],
|
||||
"settings": [item["value"] for item in (evidence.get("settings") or [])],
|
||||
"descriptions": (evidence.get("descriptions") or [])[:MAX_DESCRIPTIONS],
|
||||
}
|
||||
|
||||
|
||||
def validate_response(raw: dict) -> dict:
|
||||
"""Validate a provider response into ``{name, rationale, confidence}``.
|
||||
|
||||
Raises ``ProviderError('malformed_response')`` for anything unusable, so a bad
|
||||
model reply is quarantined rather than persisted as a name.
|
||||
"""
|
||||
if not isinstance(raw, dict):
|
||||
raise ProviderError("malformed_response", "response is not an object")
|
||||
name = raw.get("name")
|
||||
if not isinstance(name, str) or not name.strip():
|
||||
raise ProviderError("malformed_response", "missing or empty 'name'")
|
||||
rationale = raw.get("rationale")
|
||||
if rationale is not None and not isinstance(rationale, str):
|
||||
raise ProviderError("malformed_response", "'rationale' must be a string")
|
||||
confidence = raw.get("confidence")
|
||||
if confidence is not None:
|
||||
if isinstance(confidence, bool) or not isinstance(confidence, (int, float)):
|
||||
raise ProviderError("malformed_response", "'confidence' must be a number")
|
||||
confidence = float(confidence)
|
||||
if not 0.0 <= confidence <= 1.0:
|
||||
raise ProviderError("malformed_response", "'confidence' must be within 0..1")
|
||||
return {"name": name.strip(), "rationale": rationale, "confidence": confidence}
|
||||
|
||||
|
||||
class ProposalService:
|
||||
def __init__(
|
||||
self,
|
||||
session_factory: sessionmaker,
|
||||
*,
|
||||
provider: ProposalProvider | None = None,
|
||||
library_roots: tuple = (),
|
||||
policy: NamingPolicy | None = None,
|
||||
) -> None:
|
||||
self._session_factory = session_factory
|
||||
self._provider = provider
|
||||
self._albums = AlbumService(session_factory, library_roots=library_roots)
|
||||
self._policy = policy or NamingPolicy()
|
||||
|
||||
# ── evidence ──────────────────────────────────────────────────────────────
|
||||
|
||||
def _evidence_by_album(self) -> dict[str, dict]:
|
||||
page = self._albums.aggregate_evidence()
|
||||
return {folder["album"]: folder for folder in page["folders"]}
|
||||
|
||||
# ── generation ────────────────────────────────────────────────────────────
|
||||
|
||||
def generate(self, albums: list[str] | None = None) -> dict:
|
||||
"""Generate (or regenerate) proposals. Returns ``{proposed, errors, skipped}``.
|
||||
|
||||
Retry-safe: one row per album, updated in place. A provider failure records an
|
||||
error and leaves the album eligible for another attempt.
|
||||
"""
|
||||
evidence_by_album = self._evidence_by_album()
|
||||
targets = albums if albums is not None else sorted(evidence_by_album)
|
||||
proposed = errors = skipped = 0
|
||||
|
||||
for album in targets:
|
||||
evidence = evidence_by_album.get(album)
|
||||
if evidence is None:
|
||||
skipped += 1
|
||||
continue
|
||||
try:
|
||||
result = self._propose_one(evidence)
|
||||
except ProviderError as error:
|
||||
self._store_error(album, error.code, str(error), evidence["version"])
|
||||
errors += 1
|
||||
continue
|
||||
self._store_proposal(album, result, evidence["version"])
|
||||
proposed += 1
|
||||
return {"proposed": proposed, "errors": errors, "skipped": skipped}
|
||||
|
||||
def _propose_one(self, evidence: dict) -> dict:
|
||||
summary = evidence_summary(evidence)
|
||||
if self._provider is None:
|
||||
# No provider configured: fall back to the deterministic policy name, so
|
||||
# proposals still work offline. Rationale says so; confidence stays low.
|
||||
name = render_name(build_fields(evidence), self._policy)
|
||||
if not name:
|
||||
raise ProviderError("no_evidence", "no evidence to build a name from")
|
||||
return {
|
||||
"name": name,
|
||||
"rationale": "Generated from folder evidence using the naming template.",
|
||||
"confidence": 0.3,
|
||||
"raw": None,
|
||||
}
|
||||
raw = self._provider.propose(summary)
|
||||
validated = validate_response(raw)
|
||||
validated["raw"] = json.dumps(raw, ensure_ascii=False, default=str)
|
||||
return validated
|
||||
|
||||
def _store_proposal(self, album: str, result: dict, evidence_version: str) -> None:
|
||||
# Names are always run through the naming policy before they are stored, so a
|
||||
# model can never introduce a path separator or reserved name.
|
||||
checked = validate(result["name"], policy=self._policy)
|
||||
name = checked.name or (checked.suggestions[0] if checked.suggestions else "")
|
||||
with self._session_factory() as session:
|
||||
row = self._row(session, album) or AlbumProposal(id=str(uuid.uuid4()), album=album)
|
||||
row.proposed_name = name
|
||||
row.final_name = None # a regeneration clears a previous edit
|
||||
row.rationale = result.get("rationale")
|
||||
row.confidence = result.get("confidence")
|
||||
row.status = PROPOSED
|
||||
row.error_code = row.error_message = None
|
||||
row.evidence_version = evidence_version
|
||||
row.model = MODEL if self._provider is not None else "policy"
|
||||
row.prompt_version = PROMPT_VERSION
|
||||
row.raw_response = result.get("raw")
|
||||
row.approved_at = None
|
||||
row.version = (row.version or 0) + 1
|
||||
row.updated_at = _now()
|
||||
session.add(row)
|
||||
session.commit()
|
||||
|
||||
def _store_error(self, album: str, code: str, message: str, evidence_version: str) -> None:
|
||||
with self._session_factory() as session:
|
||||
row = self._row(session, album) or AlbumProposal(id=str(uuid.uuid4()), album=album)
|
||||
row.status = ERROR
|
||||
row.error_code = code
|
||||
row.error_message = message[:500]
|
||||
row.evidence_version = evidence_version
|
||||
row.version = (row.version or 0) + 1
|
||||
row.updated_at = _now()
|
||||
session.add(row)
|
||||
session.commit()
|
||||
|
||||
# ── reads ─────────────────────────────────────────────────────────────────
|
||||
|
||||
@staticmethod
|
||||
def _row(session, album: str) -> AlbumProposal | None:
|
||||
return session.scalar(select(AlbumProposal).where(AlbumProposal.album == album))
|
||||
|
||||
def get(self, album: str) -> dict | None:
|
||||
current = self._evidence_by_album().get(album)
|
||||
with self._session_factory() as session:
|
||||
row = self._row(session, album)
|
||||
if row is None:
|
||||
return None
|
||||
return _as_dict(row, current["version"] if current else None)
|
||||
|
||||
def list(self, *, status: str | None = None) -> dict:
|
||||
versions = {
|
||||
album: evidence["version"] for album, evidence in self._evidence_by_album().items()
|
||||
}
|
||||
with self._session_factory() as session:
|
||||
rows = list(session.scalars(select(AlbumProposal).order_by(AlbumProposal.album)))
|
||||
items = [_as_dict(row, versions.get(row.album)) for row in rows]
|
||||
if status:
|
||||
items = [item for item in items if item["status"] == status]
|
||||
return {"items": items, "total": len(items)}
|
||||
|
||||
# ── edit / approve ────────────────────────────────────────────────────────
|
||||
|
||||
def edit(self, album: str, name: str, *, expected_version: int) -> dict:
|
||||
"""Replace the proposed name with the user's own. Validated by the naming
|
||||
policy; an invalid name is rejected with its structured issues."""
|
||||
checked = validate(name, policy=self._policy)
|
||||
if not checked.name:
|
||||
raise ProposalError(f"name is empty after sanitization: {checked.issues}")
|
||||
with self._session_factory() as session:
|
||||
row = self._require(session, album, expected_version)
|
||||
row.final_name = checked.name
|
||||
row.status = EDITED
|
||||
row.approved_at = None
|
||||
row.version += 1
|
||||
row.updated_at = _now()
|
||||
session.add(row)
|
||||
session.commit()
|
||||
return self.get(album)
|
||||
|
||||
def approve(self, album: str, *, expected_version: int) -> dict:
|
||||
"""Approve the current proposal. Validates the latest version and that the
|
||||
evidence has not moved on. Records intent only — no rename occurs."""
|
||||
current = self._evidence_by_album().get(album)
|
||||
with self._session_factory() as session:
|
||||
row = self._require(session, album, expected_version)
|
||||
if row.status == ERROR:
|
||||
raise ProposalError(f"proposal for {album!r} is in error state")
|
||||
name = row.final_name or row.proposed_name
|
||||
if not name:
|
||||
raise ProposalError(f"proposal for {album!r} has no name to approve")
|
||||
if current is not None and row.evidence_version != current["version"]:
|
||||
raise ProposalError(
|
||||
f"proposal for {album!r} is stale; regenerate it before approving"
|
||||
)
|
||||
row.status = APPROVED
|
||||
row.approved_at = _now()
|
||||
row.version += 1
|
||||
row.updated_at = _now()
|
||||
session.add(row)
|
||||
session.commit()
|
||||
return self.get(album)
|
||||
|
||||
def _require(self, session, album: str, expected_version: int) -> AlbumProposal:
|
||||
row = self._row(session, album)
|
||||
if row is None:
|
||||
raise ProposalError(f"unknown album proposal {album!r}")
|
||||
if row.version != expected_version:
|
||||
raise ConflictError(
|
||||
f"proposal for {album!r} is at version {row.version}, expected {expected_version}"
|
||||
)
|
||||
return row
|
||||
|
||||
|
||||
def _as_dict(row: AlbumProposal, current_evidence_version: str | None) -> dict:
|
||||
stale = (
|
||||
current_evidence_version is not None
|
||||
and row.evidence_version is not None
|
||||
and row.evidence_version != current_evidence_version
|
||||
)
|
||||
return {
|
||||
"album": row.album,
|
||||
"proposed_name": row.proposed_name,
|
||||
"final_name": row.final_name,
|
||||
"name": row.final_name or row.proposed_name,
|
||||
"rationale": row.rationale,
|
||||
"confidence": row.confidence,
|
||||
"status": row.status,
|
||||
"error_code": row.error_code,
|
||||
"error_message": row.error_message,
|
||||
"evidence_version": row.evidence_version,
|
||||
"current_evidence_version": current_evidence_version,
|
||||
"stale": stale,
|
||||
"model": row.model,
|
||||
"prompt_version": row.prompt_version,
|
||||
"version": row.version,
|
||||
"approved_at": row.approved_at.isoformat() if row.approved_at else None,
|
||||
}
|
||||
Reference in New Issue
Block a user