logicroot 0.2.0__py3-none-any.whl

logicroot/__init__.py

@@ -0,0 +1,17 @@
+"""LOGICROOT - Your Linux Command Center.
+
+LOGICROOT is a hardware-aware, capability-driven, local-first Linux system command
+center. The package is import-safe on any platform: every Linux-specific
+subsystem degrades gracefully when the kernel interfaces it needs are absent.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__", "get_version"]
+
+__version__ = "0.2.0"
+
+
+def get_version() -> str:
+    """Return the installed LOGICROOT version string."""
+    return __version__

logicroot/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m logicroot`` to behave exactly like the ``logicroot`` command."""
+
+from __future__ import annotations
+
+from logicroot.cli import run
+
+if __name__ == "__main__":
+    run()

logicroot/assistant/__init__.py

@@ -0,0 +1,57 @@
+"""Optional AI assistant (Milestone 13).
+
+Disabled by default, offline-first, and text-only: the assistant answers
+questions *about* the system and never acts on it. See :mod:`logicroot.assistant.base`
+for the safety contract every provider follows.
+"""
+
+from logicroot.assistant.base import (
+    MAX_QUESTION_CHARS,
+    AssistantProvider,
+    context_is_safe,
+    sanitise_question,
+    scrub,
+)
+from logicroot.assistant.context import build_context
+from logicroot.assistant.local import LocalProvider
+from logicroot.assistant.manager import Assistant, for_system
+from logicroot.assistant.models import (
+    AssistantConfig,
+    AssistantContext,
+    AssistantMessage,
+    AssistantReply,
+    AssistantRole,
+    ProviderKind,
+)
+from logicroot.assistant.openai import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MODEL,
+    ENV_BASE_URL,
+    ENV_MODEL,
+    SYSTEM_PROMPT,
+    OpenAICompatibleProvider,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MODEL",
+    "ENV_BASE_URL",
+    "ENV_MODEL",
+    "MAX_QUESTION_CHARS",
+    "SYSTEM_PROMPT",
+    "Assistant",
+    "AssistantConfig",
+    "AssistantContext",
+    "AssistantMessage",
+    "AssistantProvider",
+    "AssistantReply",
+    "AssistantRole",
+    "LocalProvider",
+    "OpenAICompatibleProvider",
+    "ProviderKind",
+    "build_context",
+    "context_is_safe",
+    "for_system",
+    "sanitise_question",
+    "scrub",
+]

logicroot/assistant/base.py

@@ -0,0 +1,85 @@
+"""Assistant provider contract and safety rules.
+
+Opt-in is enforced by construction: providers do nothing unless asked, the
+network provider refuses to run without an explicit key *and* an explicit
+``enabled`` flag, and the safety rules below apply to every provider equally.
+
+What the assistant will never do, by design:
+
+* execute commands or change the system (it returns text; the user acts)
+* send secrets: API keys, tokens, and passwords are stripped from every
+  context bundle before any provider sees it
+* send file contents, command lines, or anything beyond coarse aggregates
+* make network calls unless the provider kind is ``openai-compatible`` and
+  the user explicitly enabled it for this invocation
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Protocol
+
+from logicroot.assistant.models import AssistantContext, AssistantReply
+from logicroot.constants import SECRET_KEY_PATTERN
+
+
+class AssistantProvider(Protocol):
+    """What every assistant backend implements."""
+
+    #: Backend id (``local``, ``openai-compatible``).
+    name: str
+
+    @property
+    def available(self) -> bool:
+        """True when this backend can answer right now."""
+        ...
+
+    def ask(self, question: str, context: AssistantContext) -> AssistantReply:
+        """Answer ``question`` given ``context`` (text in, text out)."""
+        ...
+
+
+#: Hard ceiling on a question: extremely long input is either a paste accident
+#: or an injection attempt, and neither deserves a network round-trip.
+MAX_QUESTION_CHARS = 2000
+
+_SECRET_RE = re.compile(SECRET_KEY_PATTERN, re.IGNORECASE)
+#: ``password=...``/``token ...`` shaped fragments inside a question or context.
+_SECRET_VALUE_RE = re.compile(
+    r"(?i)(api[_-]?key|token|secret|password|passwd|authorization|bearer)\s*[:=]\s*\S+"
+)
+
+
+def sanitise_question(question: str) -> str:
+    """Trim and bound a user question, refusing empties and pastes."""
+    text = question.strip()
+    if not text:
+        from logicroot.exceptions import UsageError
+
+        raise UsageError(
+            "No question asked.",
+            hint="Try: logicroot ask 'why is my disk full?'",
+        )
+    if len(text) > MAX_QUESTION_CHARS:
+        text = text[:MAX_QUESTION_CHARS]
+    return text
+
+
+def scrub(text: str) -> str:
+    """Redact ``key=value`` secret fragments from text bound for a provider."""
+    return _SECRET_VALUE_RE.sub(r"\1=[redacted]", text)
+
+
+def context_is_safe(context: AssistantContext) -> bool:
+    """True when the context bundle contains no secret-shaped fragments."""
+    bundle = context.to_prompt()
+    return _SECRET_VALUE_RE.search(bundle) is None
+
+
+__all__ = [
+    "MAX_QUESTION_CHARS",
+    "AssistantProvider",
+    "context_is_safe",
+    "sanitise_question",
+    "scrub",
+]

logicroot/assistant/context.py

@@ -0,0 +1,113 @@
+"""Building the context bundle the assistant reasons over.
+
+The context is assembled from data LOGICROOT already holds - the hardware profile,
+the latest diagnosis, and the process table - and reduced to short summary
+lines. Two filters keep it safe:
+
+* process command lines are dropped in favour of bare names (command lines
+  routinely contain passwords, tokens, and file paths)
+* the bundle is size-bounded; findings and processes are the first things
+  truncated, never the hardware facts that ground the answer
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from logicroot.assistant.base import scrub
+from logicroot.assistant.models import AssistantContext
+from logicroot.utils.logging import get_logger
+from logicroot.utils.text import human_bytes
+
+logger = get_logger("assistant.context")
+
+
+def build_context(
+    profile: Any | None = None,
+    *,
+    findings: tuple[str, ...] = (),
+    top_processes: tuple[str, ...] = (),
+    capabilities_note: str = "",
+    max_chars: int = 6000,
+) -> AssistantContext:
+    """Assemble an :class:`AssistantContext` from LOGICROOT data."""
+    context = AssistantContext(
+        hostname=_profile_attr(profile, "hostname"),
+        os_summary=_os_summary(profile),
+        cpu_summary=_cpu_summary(profile),
+        memory_summary=_memory_summary(profile),
+        disk_summary=_disk_summary(profile),
+        gpu_summary=_gpu_summary(profile),
+        findings=tuple(findings[:10]),
+        top_processes=tuple(top_processes[:5]),
+        capabilities_note=capabilities_note,
+    )
+    prompt = context.to_prompt()
+    if len(prompt) > max_chars:
+        # Truncate the variable parts first, keeping the hardware facts intact.
+        import dataclasses
+
+        context = dataclasses.replace(context, findings=(), top_processes=())
+    return context
+
+
+def _profile_attr(profile: Any | None, name: str) -> str:
+    if profile is None:
+        return ""
+    value = getattr(profile, name, "")
+    return scrub(str(value)) if value else ""
+
+
+def _os_summary(profile: Any | None) -> str:
+    if profile is None:
+        return ""
+    os_info = getattr(profile, "os", None)
+    if os_info is None:
+        return ""
+    return getattr(os_info, "display_name", "") or ""
+
+
+def _cpu_summary(profile: Any | None) -> str:
+    if profile is None:
+        return ""
+    cpu = getattr(profile, "cpu", None)
+    if cpu is None:
+        return ""
+    return getattr(cpu, "display_name", "") or ""
+
+
+def _memory_summary(profile: Any | None) -> str:
+    if profile is None:
+        return ""
+    memory = getattr(profile, "memory", None)
+    if memory is None:
+        return ""
+    total = getattr(memory, "total_bytes", None)
+    return f"{human_bytes(total)} total" if total else ""
+
+
+def _disk_summary(profile: Any | None) -> str:
+    if profile is None:
+        return ""
+    devices = getattr(profile, "storage_devices", None) or []
+    if not devices:
+        return ""
+    parts = []
+    for device in devices[:3]:
+        size = getattr(device, "size_bytes", None)
+        kind = getattr(device, "transport", "") or getattr(device, "kind", "")
+        parts.append(f"{human_bytes(size)} {kind}".strip())
+    text = ", ".join(part for part in parts if part)
+    extra = len(devices) - 3
+    return f"{text} (+{extra} more)" if extra > 0 else text
+
+
+def _gpu_summary(profile: Any | None) -> str:
+    if profile is None:
+        return ""
+    gpus = getattr(profile, "gpus", None) or []
+    names = [getattr(gpu, "display_name", "") or "GPU" for gpu in gpus]
+    return ", ".join(names)
+
+
+__all__ = ["build_context"]

logicroot/assistant/local.py

@@ -0,0 +1,198 @@
+"""Offline assistant: useful answers with no network, no key, no account.
+
+The local provider is deliberately *not* a language model. It is a small
+rule-based responder that reads the question for intent (disk pressure? failed
+services? heat? "what can you do"?) and answers from the context LOGICROOT already
+gathered - findings first, hardware facts second. Because it never leaves the
+machine, it is always available and always private.
+
+This is also the default provider, which keeps the promise that ``logicroot ask``
+works out of the box with nothing to configure and nothing to leak.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from logicroot.assistant.models import AssistantContext, AssistantReply, ProviderKind
+
+
+@dataclass
+class LocalProvider:
+    """Answers from LOGICROOT data with no network access."""
+
+    name: str = "local"
+
+    @property
+    def available(self) -> bool:
+        """Always True: there is nothing to install, configure, or reach."""
+        return True
+
+    def ask(self, question: str, context: AssistantContext) -> AssistantReply:
+        """Answer ``question`` from ``context`` using intent matching."""
+        text = _answer(question.strip(), context)
+        return AssistantReply(text=text, provider=ProviderKind.LOCAL, model="logicroot-local/1")
+
+
+def _answer(question: str, context: AssistantContext) -> str:
+    """Pick the best response section for the question's intent."""
+    lowered = question.casefold()
+    if _wants(lowered, ("disk", "storage", "space", "full", "large", "clean")):
+        return _disk_answer(context)
+    if _wants(lowered, ("memory", "ram", "swap", "oom")):
+        return _memory_answer(context)
+    if _wants(lowered, ("cpu", "load", "slow", "hot", "heat", "temperature", "fan")):
+        return _cpu_answer(context)
+    if _wants(lowered, ("service", "daemon", "failed", "boot", "startup")):
+        return _service_answer(context)
+    if _wants(lowered, ("network", "wifi", "internet", "ping", "connection")):
+        return _network_answer(context)
+    if _wants(lowered, ("gpu", "nvidia", "graphics", "display")):
+        return _gpu_answer(context)
+    if _wants(lowered, ("battery", "power", "charge")):
+        return _battery_answer(context)
+    if _wants(lowered, ("help", "what can you", "commands", "how do i use")):
+        return _help_answer()
+    return _general_answer(question, context)
+
+
+def _wants(lowered: str, keywords: tuple[str, ...]) -> bool:
+    return any(re.search(rf"\b{re.escape(keyword)}\b", lowered) for keyword in keywords)
+
+
+def _relevant(context: AssistantContext, keywords: tuple[str, ...]) -> list[str]:
+    """Findings mentioning any keyword, most relevant first."""
+    scored: list[tuple[int, str]] = []
+    for finding in context.findings:
+        lowered = finding.casefold()
+        score = sum(1 for keyword in keywords if keyword in lowered)
+        if score:
+            scored.append((score, finding))
+    scored.sort(reverse=True)
+    return [finding for _score, finding in scored]
+
+
+def _disk_answer(context: AssistantContext) -> str:
+    lines = ["Disk picture:"]
+    lines.append(f"- Storage: {context.disk_summary or 'unknown'}")
+    relevant = _relevant(context, ("disk", "filesystem", "inode", "full", "storage"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+        lines.append("- Suggested next steps:")
+        lines.append("  * logicroot storage scan ~   (what is using the space)")
+        lines.append("  * logicroot storage large    (biggest files)")
+        lines.append("  * logicroot cleanup          (safe reclaim preview)")
+    else:
+        lines.append("- No disk findings. Try 'logicroot storage scan ~' for a breakdown, or 'logicroot cleanup' for reclaimable space.")
+    return "\n".join(lines)
+
+
+def _memory_answer(context: AssistantContext) -> str:
+    lines = ["Memory picture:"]
+    lines.append(f"- Memory: {context.memory_summary or 'unknown'}")
+    relevant = _relevant(context, ("memory", "swap", "oom"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+        lines.append("- Suggested next step: logicroot processes --sort memory")
+    else:
+        lines.append("- No memory findings. 'logicroot processes --sort memory' ranks current usage.")
+    if context.top_processes:
+        lines.append("- Busiest processes right now:")
+        lines.extend(f"  * {process}" for process in context.top_processes[:5])
+    return "\n".join(lines)
+
+
+def _cpu_answer(context: AssistantContext) -> str:
+    lines = ["CPU picture:"]
+    lines.append(f"- CPU: {context.cpu_summary or 'unknown'}")
+    relevant = _relevant(context, ("cpu", "load", "thermal", "overheat", "temperature"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+        lines.append("- Suggested next step: logicroot processes --sort cpu")
+    else:
+        lines.append("- No CPU findings. 'logicroot processes --sort cpu' shows the current load.")
+    return "\n".join(lines)
+
+
+def _service_answer(context: AssistantContext) -> str:
+    lines = ["Services picture:"]
+    relevant = _relevant(context, ("service", "failed", "boot", "unit"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+        lines.append("- Suggested next steps:")
+        lines.append("  * logicroot services --failed   (everything that failed)")
+        lines.append("  * logicroot logs --errors       (why they failed)")
+    else:
+        lines.append("- No service findings. 'logicroot services' lists everything; '--failed' filters to problems.")
+    return "\n".join(lines)
+
+
+def _network_answer(context: AssistantContext) -> str:
+    lines = ["Network picture:"]
+    relevant = _relevant(context, ("network", "interface", "gateway", "error"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+    else:
+        lines.append("- No network findings.")
+    lines.append("- Suggested next steps:")
+    lines.append("  * logicroot network              (interfaces, gateway, DNS)")
+    lines.append("  * logicroot network connections  (who is talking to whom)")
+    lines.append("  * logicroot network ping <host>  (reachability)")
+    return "\n".join(lines)
+
+
+def _gpu_answer(context: AssistantContext) -> str:
+    lines = ["GPU picture:"]
+    lines.append(f"- GPUs: {context.gpu_summary or 'none detected'}")
+    relevant = _relevant(context, ("gpu", "vram", "nvidia", "temperature"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+    lines.append("- Suggested next step: logicroot gpu   (live utilisation, memory, temperature)")
+    return "\n".join(lines)
+
+
+def _battery_answer(context: AssistantContext) -> str:
+    lines = ["Battery picture:"]
+    relevant = _relevant(context, ("battery", "charge", "power"))
+    if relevant:
+        lines.append("- What LOGICROOT found:")
+        lines.extend(f"  * {finding}" for finding in relevant[:5])
+    else:
+        lines.append("- No battery findings. 'logicroot hardware' shows the detected battery, if any.")
+    return "\n".join(lines)
+
+
+def _help_answer() -> str:
+    return "\n".join(
+        [
+            "I answer from what LOGICROOT measured on this machine - findings first, hardware second.",
+            "Try questions like:",
+            "- 'why is my disk full?' / 'what is using my memory?' / 'why is it slow?'",
+            "Or skip me and go straight to the source:",
+            "- logicroot diagnose   (full health check with suggestions)",
+            "- logicroot processes  (what is running right now)",
+            "- logicroot hardware   (what this machine is)",
+        ]
+    )
+
+
+def _general_answer(question: str, context: AssistantContext) -> str:
+    lines = [f"Here is what I know about '{question}':"]
+    if context.findings:
+        lines.append("- Current findings:")
+        lines.extend(f"  * {finding}" for finding in context.findings[:5])
+        lines.append("For the full picture with suggestions, run: logicroot diagnose")
+    else:
+        lines.append("- LOGICROOT reports no active findings on this machine.")
+        lines.append("For the full picture, run: logicroot diagnose")
+    return "\n".join(lines)
+
+
+__all__ = ["LocalProvider"]

logicroot/assistant/manager.py

@@ -0,0 +1,107 @@
+"""Assistant orchestration: answer locally by default, network only on demand.
+
+``Assistant.ask`` implements the opt-in contract in one place:
+
+* **Default: local.** The offline provider answers from LOGICROOT data. Nothing
+  leaves the machine, nothing needs configuring.
+* **``--ai``: network.** The OpenAI-compatible provider answers, but only when
+  ``LOGICROOT_AI_API_KEY`` is set. Without the key the user gets setup instructions
+  instead of a silent fallback that pretends to be AI.
+
+Either way the reply is text. The assistant has no tools, no shell, and no
+ability to act - it can suggest ``logicroot diagnose``, but only the user can run it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from logicroot.assistant.base import AssistantProvider, sanitise_question
+from logicroot.assistant.context import build_context
+from logicroot.assistant.local import LocalProvider
+from logicroot.assistant.models import (
+    AssistantConfig,
+    AssistantContext,
+    AssistantReply,
+    ProviderKind,
+)
+from logicroot.assistant.openai import OpenAICompatibleProvider
+from logicroot.utils.logging import get_logger
+
+logger = get_logger("assistant.manager")
+
+
+@dataclass
+class Assistant:
+    """Answers questions about this machine, locally unless asked otherwise."""
+
+    config: AssistantConfig = field(default_factory=AssistantConfig)
+    local: LocalProvider = field(default_factory=LocalProvider)
+
+    def provider_for(self, *, use_ai: bool) -> AssistantProvider:
+        """Pick the backend: network only when requested *and* configured."""
+        if use_ai and self.config.network_allowed:
+            provider = OpenAICompatibleProvider.from_environment(timeout=self.config.timeout)
+            if provider is not None:
+                if self.config.model:
+                    provider.model = self.config.model
+                if self.config.base_url:
+                    provider.base_url = self.config.base_url.rstrip("/")
+                return provider
+            return _UnconfiguredProvider()
+        return self.local
+
+    def ask(
+        self,
+        question: str,
+        context: AssistantContext | None = None,
+        *,
+        use_ai: bool = False,
+        profile: Any | None = None,
+        findings: tuple[str, ...] = (),
+        top_processes: tuple[str, ...] = (),
+    ) -> AssistantReply:
+        """Answer ``question``, building context from ``profile`` when needed."""
+        clean = sanitise_question(question)
+        active = context or build_context(
+            profile,
+            findings=findings,
+            top_processes=top_processes,
+            max_chars=self.config.max_context_chars,
+        )
+        provider = self.provider_for(use_ai=use_ai)
+        logger.debug("assistant answering via %s", provider.name)
+        return provider.ask(clean, active)
+
+
+@dataclass
+class _UnconfiguredProvider:
+    """Explains how to enable AI when ``--ai`` was passed without a key."""
+
+    name: str = "openai-compatible"
+
+    @property
+    def available(self) -> bool:
+        return False
+
+    def ask(self, question: str, context: AssistantContext) -> AssistantReply:
+        _ = (question, context)
+        return AssistantReply(
+            text=(
+                "AI answers need two things:\n"
+                "1. A key: set LOGICROOT_AI_API_KEY (or LOGICROOT_AI_BASE_URL plus a key for a local server).\n"
+                "2. Consent per question: re-run with --ai.\n\n"
+                "Nothing was sent anywhere. Run the same question without --ai for the offline answer."
+            ),
+            provider=ProviderKind.OPENAI_COMPATIBLE,
+            model="",
+        )
+
+
+def for_system(config: AssistantConfig | None = None) -> Assistant:
+    """Build an assistant with the given (or default disabled) configuration."""
+    return Assistant(config=config or AssistantConfig())
+
+
+__all__ = ["Assistant", "for_system"]