sifty 0.6.0__py3-none-any.whl

sifty/__init__.py

@@ -0,0 +1,3 @@
+"""Sifty — an AI-assisted Windows maintenance CLI that sifts the junk from the keep."""
+
+__version__ = "0.6.0"

sifty/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m sifty`` as an alternative to the ``sifty`` console script."""
+
+from .cli.app import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

sifty/ai/__init__.py

@@ -0,0 +1 @@
+"""Local AI layer (Ollama) — advises, never acts on its own."""

sifty/ai/advisor.py

@@ -0,0 +1,71 @@
+"""AI advisory prompts.
+
+The advisor only ever receives *metadata* — names, sizes, paths, extensions,
+counts — never file contents. It explains and recommends; it never deletes.
+The calling command does the acting, with the usual dry-run/confirm safeguards.
+"""
+
+from __future__ import annotations
+
+from .client import OllamaClient, OllamaUnavailable
+
+SYSTEM_PROMPT = (
+    "You are Sifty, a careful Windows maintenance assistant embedded in a CLI/TUI "
+    "tool. You are given only file/app metadata, never file contents. Be concise, "
+    "practical, and cautious; when unsure whether something is safe to remove, say so. "
+    "Format answers in Markdown.\n\n"
+    "To remove an installed program, ALWAYS recommend a proper uninstall — Sifty's own "
+    "`apps` command (which uses winget under the hood), `winget uninstall`, or Windows "
+    "Settings > Apps. NEVER tell the user to manually delete a program's folder under "
+    "C:\\Program Files, C:\\Program Files (x86), or to hand-edit files in C:\\Windows, "
+    "ProgramData, or their personal documents — Sifty refuses those paths anyway, and "
+    "manual deletion leaves the registry and the system in a broken state. Do not "
+    "suggest `DISM` or `sfc /scannow` unless the user explicitly reports system file "
+    "corruption; they are not part of uninstalling an app.\n\n"
+    "Sifty deletes safely (to the Recycle Bin, dry-run by default), so point users at "
+    "Sifty's commands rather than destructive manual steps."
+)
+
+# Back-compat alias for internal callers.
+_SYSTEM = SYSTEM_PROMPT
+
+
+def _safe(client: OllamaClient, user_prompt: str) -> str | None:
+    """Run a prompt, returning None if the AI is unavailable."""
+    if not client.is_available():
+        return None
+    try:
+        return client.chat(_SYSTEM, user_prompt)
+    except OllamaUnavailable:
+        return None
+
+
+def explain_item(client: OllamaClient, name: str, path: str, size_human: str) -> str | None:
+    """Explain what an item is and whether it's safe to remove."""
+    return _safe(
+        client,
+        f"What is this Windows item, and is it generally safe to delete?\n"
+        f"Name: {name}\nPath: {path}\nSize: {size_human}\n"
+        f"Answer in 2-3 sentences.",
+    )
+
+
+def summarize_disk(client: OllamaClient, items: list[tuple[str, str]], question: str) -> str | None:
+    """Answer a natural-language question about the biggest disk items."""
+    listing = "\n".join(f"- {name}: {size}" for name, size in items)
+    return _safe(
+        client,
+        f"Here are the largest items in a directory:\n{listing}\n\n"
+        f"User question: {question}\n"
+        f"Give a brief, practical answer and flag anything risky to delete.",
+    )
+
+
+def suggest_organization(client: OllamaClient, sample_names: list[str]) -> str | None:
+    """Propose a folder scheme for a messy directory from sample filenames."""
+    listing = "\n".join(f"- {n}" for n in sample_names[:40])
+    return _safe(
+        client,
+        f"These are sample filenames from a cluttered folder:\n{listing}\n\n"
+        f"Suggest a simple folder structure to organize them. Be concise.",
+    )

sifty/ai/agent.py

@@ -0,0 +1,227 @@
+"""AI agent loop with autonomy levels.
+
+The agent sends the user's request to Ollama with a tool registry. Ollama may
+respond with one or more tool calls; the agent dispatches them (subject to the
+autonomy level and a confirm callback), appends the results, and re-submits
+until the model produces a plain text answer.
+
+Autonomy levels:
+  ``ask``           — confirm every ``low`` or ``high`` risk tool before running.
+  ``low_risk_auto`` — auto-run ``low`` risk tools; confirm ``high`` ones.
+  ``full_auto``     — run all tools automatically (still routes through safety.trash).
+
+The active level is read from a small override file (set via the TUI) layered
+over the static ``ai.autonomy`` config default — see :func:`current_autonomy`.
+
+Models that don't emit ``tool_calls`` (not tool-capable) produce a plain reply
+on the first iteration; the agent yields that as a :class:`FallbackEvent` so
+callers can detect the downgrade.
+
+Events are yielded as the agent progresses so callers (TUI, CLI) can display
+each step live instead of waiting for the whole chain.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+
+from ..infra.config import app_data_dir, load_config
+from .client import OllamaClient, OllamaUnavailable
+from .tools import TOOLS, Tool, ToolResult
+from .tools import get as get_tool
+
+logger = logging.getLogger("sifty.ai")
+
+_MAX_ITERATIONS = 10
+_VALID_LEVELS = ("ask", "low_risk_auto", "full_auto")
+
+# Appended to the system prompt in agentic mode so the model adds insight rather
+# than re-dumping data the UI already renders as tables.
+TOOL_USE_NOTE = (
+    "\n\nYou can call tools to inspect and maintain this machine. Tool results are "
+    "shown to the user directly (large results as tables), so do NOT repeat the raw "
+    "data back — give a short, useful interpretation and a clear recommendation. "
+    "Before any destructive action (clean_junk, uninstall_app, apply_updates) explain "
+    "what you're about to do; the user is asked to approve it."
+)
+
+
+# ---------------------------------------------------------------------------
+# Event types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolCallEvent:
+    """The model is requesting a tool call."""
+    tool_name: str
+    args: dict
+    risk: str           # from the Tool definition
+
+
+@dataclass
+class ToolResultEvent:
+    """A tool has been executed (or skipped due to a denied confirm)."""
+    tool_name: str
+    result: str
+    skipped: bool = False           # True when the user declined to run it
+    table: ToolResult | None = None  # structured output for rich UI rendering
+
+
+@dataclass
+class FinalAnswerEvent:
+    """The model produced a plain text reply — the agent is done."""
+    text: str
+
+
+@dataclass
+class FallbackEvent:
+    """The model doesn't support tools; plain advisory answer returned."""
+    text: str
+
+
+AgentEvent = ToolCallEvent | ToolResultEvent | FinalAnswerEvent | FallbackEvent
+
+
+# ---------------------------------------------------------------------------
+# Autonomy: config default + user override file
+# ---------------------------------------------------------------------------
+
+def _override_file():
+    return app_data_dir() / "ai_state.json"
+
+
+def autonomy_from_config(config=None) -> str:
+    config = config or load_config()
+    return config.section("ai").get("autonomy", "ask")
+
+
+def current_autonomy(config=None) -> str:
+    """The active autonomy level: user override file wins, else config default."""
+    path = _override_file()
+    if path.exists():
+        try:
+            val = json.loads(path.read_text(encoding="utf-8")).get("autonomy")
+            if val in _VALID_LEVELS:
+                return val
+        except (ValueError, OSError):
+            pass
+    return autonomy_from_config(config)
+
+
+def set_autonomy(level: str) -> bool:
+    """Persist the active autonomy level. Returns False for an invalid level."""
+    if level not in _VALID_LEVELS:
+        return False
+    try:
+        _override_file().write_text(json.dumps({"autonomy": level}), encoding="utf-8")
+        return True
+    except OSError:
+        logger.exception("failed to persist autonomy level")
+        return False
+
+
+def _needs_confirm(risk: str, autonomy: str) -> bool:
+    """Return True if this risk level requires a confirm under the given autonomy."""
+    if risk == "read":
+        return False
+    if autonomy == "full_auto":
+        return False
+    if autonomy == "low_risk_auto" and risk == "low":
+        return False
+    return True  # "ask" confirms low+high; "low_risk_auto" confirms high
+
+
+# ---------------------------------------------------------------------------
+# Agent loop
+# ---------------------------------------------------------------------------
+
+def run(
+    client: OllamaClient,
+    messages: list[dict],
+    *,
+    autonomy: str = "ask",
+    confirm: Callable[[str], bool] | None = None,
+    tools: list[Tool] | None = None,
+) -> Iterator[AgentEvent]:
+    """Drive an agentic conversation and yield :data:`AgentEvent` instances.
+
+    ``messages`` is the full Ollama-format conversation history (including the
+    system message). ``confirm`` is called with a human-readable prompt when a
+    tool requires confirmation; return ``True`` to proceed, ``False`` to skip.
+    Defaults to always-refuse (safe) when not provided.
+    """
+    if confirm is None:
+        confirm = lambda _: False  # noqa: E731 — safe default, not interactive
+
+    active_tools = tools if tools is not None else TOOLS
+    schemas = [t.to_ollama() for t in active_tools]
+    tool_map = {t.name: t for t in active_tools}
+
+    current_messages = list(messages)
+
+    for _ in range(_MAX_ITERATIONS):
+        try:
+            msg = client.chat_once(current_messages, tools=schemas)
+        except OllamaUnavailable as exc:
+            logger.warning("agent: Ollama unavailable: %s", exc)
+            yield FinalAnswerEvent(text=f"(AI unavailable: {exc})")
+            return
+
+        tool_calls = msg.get("tool_calls") or []
+
+        if not tool_calls:
+            text = (msg.get("content") or "").strip() or "(no response)"
+            # A plain reply on the very first turn means the model ignored tools.
+            is_fallback = len(current_messages) == len(messages)
+            yield (FallbackEvent(text=text) if is_fallback else FinalAnswerEvent(text=text))
+            return
+
+        current_messages.append(msg)
+
+        for call in tool_calls:
+            fn = call.get("function", {})
+            name = fn.get("name", "")
+            raw_args = fn.get("arguments", {})
+            args = raw_args if isinstance(raw_args, dict) else {}
+
+            tool = tool_map.get(name) or get_tool(name)
+            if tool is None:
+                result_text = f"Unknown tool: {name}"
+                yield ToolResultEvent(tool_name=name, result=result_text)
+                current_messages.append({"role": "tool", "content": result_text})
+                continue
+
+            yield ToolCallEvent(tool_name=name, args=args, risk=tool.risk)
+
+            if _needs_confirm(tool.risk, autonomy):
+                if not confirm(_confirm_prompt(tool, args)):
+                    result_text = f"(user declined to run {name})"
+                    yield ToolResultEvent(tool_name=name, result=result_text, skipped=True)
+                    current_messages.append({"role": "tool", "content": result_text})
+                    continue
+
+            try:
+                result = tool.handler(args)
+            except Exception as exc:
+                logger.exception("tool %s failed", name)
+                result = ToolResult(summary=f"Error running {name}: {exc}")
+
+            if isinstance(result, ToolResult):
+                result_text = result.summary
+                table = result if result.has_table else None
+            else:
+                result_text = str(result)
+                table = None
+
+            yield ToolResultEvent(tool_name=name, result=result_text, table=table)
+            current_messages.append({"role": "tool", "content": result_text})
+
+    yield FinalAnswerEvent(text="(agent reached the iteration limit without a final answer)")
+
+
+def _confirm_prompt(tool: Tool, args: dict) -> str:
+    args_str = ", ".join(f"{k}={v!r}" for k, v in args.items()) if args else ""
+    return f"Run {tool.name}({args_str}) — risk: {tool.risk}"

sifty/ai/client.py

@@ -0,0 +1,176 @@
+"""Thin wrapper around a local Ollama server.
+
+Everything degrades gracefully: if Ollama isn't running, :func:`is_available`
+returns ``False`` and callers fall back to non-AI behaviour instead of crashing.
+
+Chat is **streamed**. A local model has to be loaded into RAM/VRAM on its first
+request (a cold start that can take many seconds) and then emits tokens slowly.
+A single blocking request with one wall-clock budget covers *all* of that at
+once, so a model that is working — just slow — trips the timeout and the user
+gets nothing. Streaming turns the timeout into "time between tokens" instead of
+"time for the whole answer", so a slow-but-alive model keeps going and callers
+can show progress as it arrives.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+import httpx
+
+from ..infra.config import load_config
+
+
+class OllamaUnavailable(Exception):
+    """Raised when the local Ollama server can't be reached."""
+
+
+@dataclass
+class OllamaClient:
+    host: str
+    model: str
+    timeout: float
+    keep_alive: str = "10m"
+
+    @classmethod
+    def from_config(cls, config=None) -> OllamaClient:
+        config = config or load_config()
+        ai = config.section("ai")
+        return cls(
+            host=ai.get("host", "http://localhost:11434"),
+            model=ai.get("model", "qwen2.5:3b"),
+            timeout=float(ai.get("timeout_seconds", 60)),
+            keep_alive=str(ai.get("keep_alive", "10m")),
+        )
+
+    def _timeout(self) -> httpx.Timeout:
+        """Split timeout: connecting is instant; generation is the slow part.
+
+        ``timeout`` bounds the wait *between* streamed chunks (and the initial
+        model load), not the total length of the answer.
+        """
+        return httpx.Timeout(self.timeout, connect=5.0, write=10.0, pool=5.0)
+
+    def is_available(self) -> bool:
+        """Return True if the Ollama server responds to a tags request."""
+        try:
+            resp = httpx.get(f"{self.host}/api/tags", timeout=3.0)
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def list_models(self) -> list[str]:
+        """Return the names of locally-pulled Ollama models (empty on error)."""
+        try:
+            resp = httpx.get(f"{self.host}/api/tags", timeout=3.0)
+            if resp.status_code != 200:
+                return []
+            return [m.get("name", "") for m in resp.json().get("models", [])]
+        except httpx.HTTPError:
+            return []
+
+    def _payload(self, messages: list[dict], tools: list[dict] | None = None) -> dict:
+        payload: dict = {
+            "model": self.model,
+            "stream": True,
+            "keep_alive": self.keep_alive,
+            "messages": messages,
+        }
+        if tools:
+            payload["tools"] = tools
+        return payload
+
+    def _build_messages(self, system: str, user: str) -> list[dict]:
+        return [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+
+    def chat_stream(
+        self,
+        system: str,
+        user: str,
+        *,
+        messages: list[dict] | None = None,
+    ) -> Iterator[str]:
+        """Stream the assistant's reply token-by-token.
+
+        Pass ``messages`` (a full Ollama-format list) to continue a conversation;
+        omit it for a single-turn exchange built from ``system`` + ``user``.
+        Yields content chunks as they arrive. Raises :class:`OllamaUnavailable`
+        with a human-readable message on transport errors or timeouts.
+        """
+        payload_messages = messages if messages is not None else self._build_messages(system, user)
+        try:
+            with httpx.stream(
+                "POST",
+                f"{self.host}/api/chat",
+                json=self._payload(payload_messages),
+                timeout=self._timeout(),
+            ) as resp:
+                resp.raise_for_status()
+                for line in resp.iter_lines():
+                    if not line:
+                        continue
+                    try:
+                        data = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    chunk = data.get("message", {}).get("content", "")
+                    if chunk:
+                        yield chunk
+                    if data.get("done"):
+                        break
+        except httpx.TimeoutException as exc:
+            raise OllamaUnavailable(
+                "timed out — the model may still be loading; try again"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise OllamaUnavailable(str(exc)) from exc
+
+    def chat(
+        self,
+        system: str,
+        user: str,
+        *,
+        messages: list[dict] | None = None,
+    ) -> str:
+        """Send a chat and return the full assistant text.
+
+        Pass ``messages`` to continue a multi-turn conversation; omit for a
+        single-turn exchange. Consumes :meth:`chat_stream` internally.
+        """
+        return "".join(self.chat_stream(system, user, messages=messages)).strip()
+
+    def chat_once(
+        self,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+    ) -> dict:
+        """Non-streaming POST to /api/chat; returns the full assistant message dict.
+
+        Use for agentic steps where you need to inspect ``tool_calls`` before
+        deciding whether to dispatch or yield a final answer.  The returned dict
+        is shaped like ``{"role": "assistant", "content": "...", "tool_calls": [...]}``;
+        ``tool_calls`` is absent (or empty) when the model produces a plain reply.
+        Raises :class:`OllamaUnavailable` on network or HTTP errors.
+        """
+        payload = self._payload(messages, tools)
+        payload["stream"] = False
+        try:
+            resp = httpx.post(
+                f"{self.host}/api/chat",
+                json=payload,
+                timeout=self._timeout(),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return data.get("message", {"role": "assistant", "content": ""})
+        except httpx.TimeoutException as exc:
+            raise OllamaUnavailable(
+                "timed out — the model may still be loading; try again"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise OllamaUnavailable(str(exc)) from exc

sifty/ai/context.py

@@ -0,0 +1,92 @@
+"""Machine context snapshot for the AI advisor.
+
+Builds a compact, *metadata-only* description of the current system state —
+volumes, junk totals, recent history — that is injected into the AI system
+prompt so it can give advice that is specific to *this* machine.
+
+Rules that must never change:
+- File *contents* are never included, only names, sizes, paths, and counts.
+- Building the snapshot must degrade gracefully (any OS call can fail).
+"""
+
+from __future__ import annotations
+
+from ..console import human_size
+
+
+def build(*, include_junk: bool = True, include_volumes: bool = True,
+          include_history: bool = True) -> str:
+    """Return a Markdown-formatted system context string for injection into prompts."""
+    sections: list[str] = []
+
+    if include_volumes:
+        section = _volume_section()
+        if section:
+            sections.append(section)
+
+    if include_junk:
+        section = _junk_section()
+        if section:
+            sections.append(section)
+
+    if include_history:
+        section = _history_section()
+        if section:
+            sections.append(section)
+
+    if not sections:
+        return ""
+
+    return "## Current machine context\n\n" + "\n\n".join(sections)
+
+
+def _volume_section() -> str:
+    try:
+        from ..core import disk
+        vols = disk.volumes()
+    except Exception:
+        return ""
+    if not vols:
+        return ""
+    lines = ["**Disk volumes:**"]
+    for v in vols:
+        lines.append(
+            f"- {v.mountpoint} ({v.fstype}): {human_size(v.free)} free / "
+            f"{human_size(v.total)} total ({v.percent:.0f}% used)"
+        )
+    return "\n".join(lines)
+
+
+def _junk_section() -> str:
+    try:
+        from ..core import junk
+        cats = junk.scan()
+    except Exception:
+        return ""
+    total_bytes = sum(c.size for c in cats)
+    total_files = sum(c.file_count for c in cats)
+    if not cats:
+        return ""
+    lines = [f"**Junk scan:** {total_files:,} files, {human_size(total_bytes)} reclaimable"]
+    for c in cats:
+        if c.size > 0:
+            lines.append(f"- {c.category.label}: {human_size(c.size)} ({c.file_count:,} files)")
+    return "\n".join(lines)
+
+
+def _history_section() -> str:
+    try:
+        from ..core import history
+        runs = history.recent_runs(5)
+        summ = history.summary()
+    except Exception:
+        return ""
+    if not runs:
+        return ""
+    lines = [
+        f"**Cleanup history:** {summ['runs']} runs, "
+        f"{human_size(summ['bytes_freed'])} reclaimed total"
+    ]
+    for r in runs[:3]:
+        lines.append(f"- {r.ts[:10]}: {r.action} — {human_size(r.bytes_freed)} freed")
+    return "\n".join(lines)