lovarch-cli 0.2.1__py3-none-any.whl

lovarch_cli/mcp/tools.py

@@ -0,0 +1,372 @@
+"""Tool implementations for the Lovarch MCP server.
+
+Kept as plain, dependency-injected functions (independent of the FastMCP wiring)
+so they can be unit-tested directly. ``server.py`` wraps each of these in an
+``@mcp.tool()``.
+
+Every tool that runs paid AI goes through :class:`LovarchAiGateway`, so the
+user's Lovarch credits are debited by the 1000cr=$1 rule — the MCP server never
+calls a model provider directly.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from lovarch_cli.ai import AiGatewayError, InsufficientCreditsError, LovarchAiGateway
+from lovarch_cli.credits.lovarch import LovarchCreditsClient
+
+
+def _projects_root(home: Path | None = None) -> Path:
+    base = home or (Path.home() / ".lovarch")
+    return base / "projects"
+
+
+async def tool_whoami(session: Any) -> dict:
+    """Report the authenticated Lovarch user and CLI mode."""
+    if session is None:
+        return {
+            "authenticated": False,
+            "mode": "none",
+            "hint": "Esegui `lovarch login --premium` per autenticarti.",
+        }
+    return {
+        "authenticated": True,
+        "mode": "premium",
+        "user_id": session.user_id,
+        "email": session.email,
+    }
+
+
+async def tool_credits(session: Any) -> dict:
+    """Return the user's Lovarch credit balance (does not debit)."""
+    if session is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    balance = await LovarchCreditsClient(session).check()
+    return {
+        "balance": balance.balance,
+        "monthly_used": balance.monthly_used,
+        "credits_remaining": balance.credits_remaining,
+        "is_admin": balance.is_admin,
+    }
+
+
+async def tool_generate_image(
+    gateway: LovarchAiGateway | None,
+    *,
+    prompt: str,
+    output_path: str,
+    quality: str = "medium",
+    aspect: str = "1:1",
+    mode: str = "generate",
+    image_urls: list[str] | None = None,
+) -> dict:
+    """Generate an image via the platform (debits credits) and save it to disk.
+
+    Returns the saved path and the exact number of credits charged.
+    """
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    try:
+        result = await gateway.generate_image(
+            prompt,
+            quality=quality,  # type: ignore[arg-type]
+            aspect=aspect,
+            mode=mode,  # type: ignore[arg-type]
+            image_urls=image_urls,
+            operation_type="mcp:generate_image",
+        )
+    except InsufficientCreditsError as exc:
+        return {
+            "ok": False,
+            "error": "insufficient_credits",
+            "credits_available": exc.available,
+            "credits_needed": exc.needed,
+        }
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+
+    out = Path(output_path).expanduser()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(result.image_bytes)
+    return {
+        "ok": True,
+        "saved_to": str(out),
+        "content_type": result.content_type,
+        "credits_charged": result.credits_charged,
+        "balance": result.balance,
+        "revised_prompt": result.revised_prompt,
+    }
+
+
+def tool_audit_input(project_dir: str) -> dict:
+    """Run the 18-point input audit on a project's ``input/`` directory."""
+    # Imported lazily to avoid a hard dependency at module import time.
+    from lovarch_cli.commands.audit import _overall_verdict, _run_checks
+
+    root = Path(project_dir).expanduser()
+    input_dir = root / "input" if (root / "input").exists() else root
+    if not input_dir.exists():
+        return {"error": "input_dir_not_found", "path": str(input_dir)}
+    results = _run_checks(input_dir)
+    verdict = _overall_verdict(results)
+    return {
+        "verdict": verdict.value,
+        "checks": [
+            {"index": r.index, "key": r.key, "status": r.status.value,
+             "detail": r.detail, "required": r.required}
+            for r in results
+        ],
+    }
+
+
+def tool_list_projects(home: Path | None = None) -> dict:
+    """List local Lovarch projects with their workflow + last audit verdict."""
+    root = _projects_root(home)
+    if not root.exists():
+        return {"projects": []}
+    projects = []
+    for child in sorted(root.iterdir()):
+        meta_file = child / "project.yaml"
+        if not meta_file.is_file():
+            continue
+        try:
+            meta = yaml.safe_load(meta_file.read_text()) or {}
+        except yaml.YAMLError:
+            meta = {}
+        projects.append({
+            "name": child.name,
+            "workflow": meta.get("workflow"),
+            "last_audit": (meta.get("last_audit") or {}).get("verdict"),
+            "last_run": (meta.get("last_run") or {}).get("status"),
+        })
+    return {"projects": projects}
+
+
+async def tool_ai_text(
+    gateway: Any,
+    *,
+    prompt: str,
+    role: str = "executor",
+    model: str | None = None,
+    system: str | None = None,
+    max_tokens: int | None = None,
+    language: str | None = None,
+) -> dict:
+    """Generate text via the platform gateway (debits credits by real tokens)."""
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    try:
+        result = await gateway.generate_text(
+            prompt, role=role, model=model, system=system,
+            max_tokens=max_tokens, language=language,
+            operation_type="mcp:ai_text",
+        )
+    except InsufficientCreditsError as exc:
+        return {"ok": False, "error": "insufficient_credits",
+                "credits_available": exc.available, "credits_needed": exc.needed}
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+    return {
+        "ok": True,
+        "text": result.text,
+        "model": result.model,
+        "credits_charged": result.credits_charged,
+        "balance": result.balance,
+    }
+
+
+async def tool_user_context(gateway: Any, *, lead_id: str | None = None) -> dict:
+    """Fetch the user's personalization bundle (brand, style, signature, language)."""
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    try:
+        return await gateway.get_user_context(lead_id=lead_id)
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+async def tool_render(
+    workflows: Any,
+    *,
+    description: str,
+    output_path: str,
+    mode: str | None = None,
+    render_style: str = "moderno",
+    aspect_ratio: str = "16:9",
+    reference_image_path: str | None = None,
+    language: str = "it",
+) -> dict:
+    """Photorealistic render via the platform (credits debited server-side)."""
+    if workflows is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.workflows import WorkflowError
+
+    try:
+        result = await workflows.render(
+            description, mode=mode, render_style=render_style,
+            aspect_ratio=aspect_ratio, reference_image_path=reference_image_path,
+            language=language,
+        )
+    except WorkflowError as exc:
+        return {"ok": False, "error": str(exc)}
+    out: dict = {"ok": True, "message": result.message}
+    image_bytes = result.image_bytes
+    if result.image_url:
+        # The EF persisted the render in the user's Lovarch storage — keep the
+        # URL AND download a local copy for CLI convenience (best-effort).
+        out["image_url"] = result.image_url
+        if image_bytes is None:
+            try:
+                import httpx
+
+                async with httpx.AsyncClient(timeout=60.0) as client:
+                    resp = await client.get(result.image_url)
+                    if resp.status_code == 200:
+                        image_bytes = resp.content
+            except Exception:  # noqa: BLE001
+                image_bytes = None
+    if image_bytes:
+        p = Path(output_path).expanduser()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(image_bytes)
+        out["saved_to"] = str(p)
+    return out
+
+
+async def tool_colors(
+    workflows: Any,
+    *,
+    style: str = "modern",
+    base_colors: list[str] | None = None,
+    image_url: str | None = None,
+    language: str = "it",
+) -> dict:
+    """Brand color palette via the platform."""
+    if workflows is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.workflows import WorkflowError
+
+    try:
+        return await workflows.colors(
+            style=style, base_colors=base_colors, image_url=image_url, language=language,
+        )
+    except WorkflowError as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+async def tool_copy(
+    workflows: Any,
+    *,
+    brief: str,
+    mode: str = "post",
+    slide_count: int = 5,
+    language: str = "it",
+) -> dict:
+    """Marketing copy (caption + hashtags) via the platform."""
+    if workflows is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.workflows import WorkflowError
+
+    try:
+        return await workflows.copy(brief, mode=mode, slide_count=slide_count, language=language)
+    except WorkflowError as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+def tool_verify_misure(dxf_path: str) -> dict:
+    """Deterministic DXF check (ISO layers, room labels, CNAPPC cartiglio). Free."""
+    from lovarch_cli.verify import verify_misure
+
+    report = verify_misure(dxf_path)
+    return {"verdict": report.verdict, "findings": report.findings, "stats": report.stats}
+
+
+async def tool_verify_normativa(
+    gateway: Any, *, document_path: str, language: str = "it"
+) -> dict:
+    """Adversarial normative-citation check (Sonnet extracts → Opus refutes)."""
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.verify import verify_normativa
+    from lovarch_cli.verify.normativa import NormativaError
+
+    try:
+        report = await verify_normativa(gateway, document_path, language=language)
+    except NormativaError as exc:
+        return {"ok": False, "error": str(exc)}
+    except InsufficientCreditsError as exc:
+        return {"ok": False, "error": "insufficient_credits",
+                "credits_available": exc.available, "credits_needed": exc.needed}
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+    return {
+        "ok": True,
+        "verdict": report.verdict,
+        "citations": report.citations,
+        "verdicts": report.verdicts,
+        "canonical_found": report.canonical_found,
+        "credits_charged": report.credits_charged,
+        "notes": report.notes,
+    }
+
+
+async def tool_job_status(workflows: Any, *, job_id: str | None = None, limit: int = 10) -> dict:
+    """Async job status (video/export/upscale). Without job_id lists recent jobs."""
+    if workflows is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.workflows import WorkflowError
+
+    try:
+        if job_id:
+            return {"ok": True, "job": await workflows.job_status(job_id)}
+        return {"ok": True, "jobs": await workflows.jobs_list(limit=limit)}
+    except WorkflowError as exc:
+        return {"ok": False, "error": str(exc)}
+
+
+async def tool_verify_contratto(
+    gateway: Any, *, document_path: str, language: str = "it"
+) -> dict:
+    """Adversarial CNAPPC contract check (structure + compenso QN_007)."""
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.verify import verify_contratto
+    from lovarch_cli.verify.normativa import NormativaError
+
+    try:
+        report = await verify_contratto(gateway, document_path, language=language)
+    except NormativaError as exc:
+        return {"ok": False, "error": str(exc)}
+    except InsufficientCreditsError as exc:
+        return {"ok": False, "error": "insufficient_credits",
+                "credits_available": exc.available, "credits_needed": exc.needed}
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+    return {"ok": True, "verdict": report.verdict, "structure": report.structure,
+            "findings": report.findings, "credits_charged": report.credits_charged}
+
+
+async def tool_verify_dossier(
+    gateway: Any, *, directory: str, language: str = "it", max_llm_files: int = 8
+) -> dict:
+    """Full standalone QA over a deliverables folder."""
+    if gateway is None:
+        return {"error": "not_authenticated", "hint": "Esegui `lovarch login --premium`."}
+    from lovarch_cli.verify import verify_dossier
+    from lovarch_cli.verify.normativa import NormativaError
+
+    try:
+        report = await verify_dossier(gateway, directory, language=language,
+                                      max_llm_files=max_llm_files)
+    except NormativaError as exc:
+        return {"ok": False, "error": str(exc)}
+    except InsufficientCreditsError as exc:
+        return {"ok": False, "error": "insufficient_credits",
+                "credits_available": exc.available, "credits_needed": exc.needed}
+    except AiGatewayError as exc:
+        return {"ok": False, "error": str(exc)}
+    return {"ok": True, "verdict": report.verdict, "files": report.files,
+            "skipped": report.skipped, "credits_charged": report.credits_charged}

lovarch_cli/sample_downloader.py

@@ -0,0 +1,255 @@
+"""Lazy downloader for the villa-chianti sample-input asset.
+
+The 49MB sample-input (photos/DXF/PDF) is NOT bundled in the wheel — it ships
+via GitHub Releases asset `sample-villa-chianti.zip` and is fetched on demand
+by `lovarch init --sample`.
+
+Flow when `arch init --sample` is invoked:
+
+    1. Check if bundled sample exists at lovarch_cli/squad/data/sample-input-
+       villa-chianti/. If yes → return its path (offline/dev case).
+    2. Check cache at ~/.lovarch/cache/sample-villa-chianti/. If extracted
+       and SHA-verified → return cached path.
+    3. Download sample-villa-chianti.zip from GitHub Releases with progress
+       bar, verify SHA256, extract to cache, return path.
+
+The SHA256 is pinned per release (see SAMPLE_ASSET_SHA256). Bumping requires
+re-pinning here. Pre-release builds may set this to None to skip verification
+(NOT for prod).
+"""
+from __future__ import annotations
+
+import hashlib
+import shutil
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+from lovarch_cli.config import DEFAULT_HOME
+from lovarch_cli.i18n import t
+
+
+# Release pinning — bump together when shipping a new sample.
+SAMPLE_RELEASE_TAG = "v0.1.0-beta.1"
+SAMPLE_ASSET_NAME = "sample-villa-chianti.zip"
+SAMPLE_ASSET_URL = (
+    f"https://github.com/ArchPrime-official/lovarch-cli/releases/download/"
+    f"{SAMPLE_RELEASE_TAG}/{SAMPLE_ASSET_NAME}"
+)
+SAMPLE_ASSET_SHA256 = (
+    "fa3c057adb9ea70c8338fa1102f1c807524ae847768ad01238cdf364fd335be4"
+)
+# When extracted, the zip contains a top-level dir named sample-input-villa-
+# chianti/ — we keep this convention so the resulting cache path matches the
+# bundled-squad path used elsewhere.
+EXTRACTED_DIR_NAME = "sample-input-villa-chianti"
+
+# Network limits.
+DOWNLOAD_TIMEOUT_SECONDS = 120
+DOWNLOAD_CHUNK_SIZE = 64 * 1024
+
+
+@dataclass(frozen=True)
+class SampleSource:
+    """Result of resolving the sample-input source path."""
+
+    path: Path
+    origin: str  # "bundled" | "cache" | "download"
+
+
+class SampleDownloadError(RuntimeError):
+    """Raised when the sample asset cannot be obtained or verified."""
+
+
+def _bundled_dir(squad_src: Optional[Path] = None) -> Path:
+    """Path the build hook would populate (if sample bundled).
+
+    Honors the same override chain as the runner via squad_loader: an
+    explicit `squad_src` argument > `$LOVARCH_SQUAD_SRC` env var > bundled
+    vendor. Falls back silently to the bundled path if resolution raises
+    (so the lazy-download flow still kicks in instead of crashing).
+    """
+    from lovarch_cli.squad_loader import SquadNotFoundError, resolve_squad_root
+
+    try:
+        root = resolve_squad_root(override=squad_src)
+    except SquadNotFoundError:
+        # Resolution failed (no override, no bundled) — fall through to the
+        # bundled path so downstream cache/download logic handles "not
+        # bundled" naturally.
+        root = Path(__file__).resolve().parent / "squad"
+    return root / "data" / EXTRACTED_DIR_NAME
+
+
+def _cache_root(home: Optional[Path] = None) -> Path:
+    base = home or DEFAULT_HOME
+    return base / "cache"
+
+
+def _cached_dir(home: Optional[Path] = None) -> Path:
+    return _cache_root(home) / EXTRACTED_DIR_NAME
+
+
+def _cached_zip(home: Optional[Path] = None) -> Path:
+    return _cache_root(home) / SAMPLE_ASSET_NAME
+
+
+def _sha256_of(path: Path) -> str:
+    hasher = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(DOWNLOAD_CHUNK_SIZE), b""):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def _download_with_progress(
+    url: str,
+    dst: Path,
+    console: Console,
+    lang: Optional[str],
+) -> None:
+    """Stream-download `url` to `dst` with a rich progress bar."""
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dst.with_suffix(dst.suffix + ".partial")
+    try:
+        with httpx.stream(
+            "GET",
+            url,
+            timeout=DOWNLOAD_TIMEOUT_SECONDS,
+            follow_redirects=True,
+        ) as response:
+            response.raise_for_status()
+            total = int(response.headers.get("content-length", 0)) or None
+            with Progress(
+                TextColumn("[bold gold1]⬇ {task.description}"),
+                BarColumn(bar_width=None),
+                DownloadColumn(),
+                TransferSpeedColumn(),
+                TimeRemainingColumn(),
+                console=console,
+                transient=True,
+            ) as progress:
+                task_id = progress.add_task(
+                    t("init.downloading", lang=lang, asset=SAMPLE_ASSET_NAME),
+                    total=total,
+                )
+                with tmp.open("wb") as fh:
+                    for chunk in response.iter_bytes(DOWNLOAD_CHUNK_SIZE):
+                        fh.write(chunk)
+                        progress.update(task_id, advance=len(chunk))
+        tmp.replace(dst)
+    except httpx.HTTPError as exc:
+        tmp.unlink(missing_ok=True)
+        raise SampleDownloadError(
+            t("init.download_failed", lang=lang, url=url, error=str(exc))
+        ) from exc
+
+
+def _verify_zip(zip_path: Path, lang: Optional[str]) -> None:
+    if not SAMPLE_ASSET_SHA256:
+        return  # Pre-release / explicit skip
+    actual = _sha256_of(zip_path)
+    if actual != SAMPLE_ASSET_SHA256:
+        raise SampleDownloadError(
+            t(
+                "init.checksum_failed",
+                lang=lang,
+                expected=SAMPLE_ASSET_SHA256,
+                actual=actual,
+            )
+        )
+
+
+def _extract_into_cache(
+    zip_path: Path,
+    cache_root: Path,
+    lang: Optional[str],
+) -> Path:
+    """Extract zip into cache_root/EXTRACTED_DIR_NAME, replacing any prior copy."""
+    target = cache_root / EXTRACTED_DIR_NAME
+    if target.exists():
+        shutil.rmtree(target)
+    cache_root.mkdir(parents=True, exist_ok=True)
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            # Defense against path-traversal in zip entries.
+            for name in zf.namelist():
+                resolved = (cache_root / name).resolve()
+                if cache_root.resolve() not in resolved.parents and resolved != (
+                    cache_root / EXTRACTED_DIR_NAME
+                ).resolve():
+                    if not str(resolved).startswith(str(cache_root.resolve())):
+                        raise SampleDownloadError(
+                            t("init.zip_unsafe", lang=lang, entry=name)
+                        )
+            zf.extractall(cache_root)
+    except (zipfile.BadZipFile, OSError) as exc:
+        raise SampleDownloadError(
+            t("init.extract_failed", lang=lang, error=str(exc))
+        ) from exc
+    if not target.exists() or not target.is_dir():
+        raise SampleDownloadError(
+            t("init.unexpected_zip_layout", lang=lang, expected=EXTRACTED_DIR_NAME)
+        )
+    return target
+
+
+def resolve_sample_source(
+    *,
+    console: Console,
+    lang: Optional[str] = None,
+    home: Optional[Path] = None,
+    allow_download: bool = True,
+    squad_src: Optional[Path] = None,
+) -> SampleSource:
+    """Return a populated SampleSource, downloading & caching if needed.
+
+    Resolution order:
+      1. Bundled inside the resolved squad root (honors --squad-src /
+         $LOVARCH_SQUAD_SRC overrides — see lovarch_cli.squad_loader)
+      2. Cached extraction in ~/.lovarch/cache/...
+      3. Fresh download from GitHub Releases (if allow_download)
+
+    Raises SampleDownloadError on network/integrity/IO failures when neither
+    bundled nor cache is usable.
+    """
+    bundled = _bundled_dir(squad_src=squad_src)
+    if bundled.is_dir() and any(bundled.iterdir()):
+        return SampleSource(path=bundled, origin="bundled")
+
+    cached = _cached_dir(home)
+    if cached.is_dir() and any(cached.iterdir()):
+        return SampleSource(path=cached, origin="cache")
+
+    if not allow_download:
+        raise SampleDownloadError(t("init.no_sample_offline", lang=lang))
+
+    zip_path = _cached_zip(home)
+    if zip_path.exists():
+        # Reuse a previously-downloaded zip if checksum still matches.
+        try:
+            _verify_zip(zip_path, lang)
+        except SampleDownloadError:
+            zip_path.unlink(missing_ok=True)
+
+    if not zip_path.exists():
+        console.print(
+            f"[dim]{t('init.fetching_sample', lang=lang, url=SAMPLE_ASSET_URL)}[/dim]"
+        )
+        _download_with_progress(SAMPLE_ASSET_URL, zip_path, console, lang)
+        _verify_zip(zip_path, lang)
+
+    extracted = _extract_into_cache(zip_path, _cache_root(home), lang)
+    return SampleSource(path=extracted, origin="download")