shepherds-console 0.1.0__py3-none-any.whl

shepherds_console/__init__.py

@@ -0,0 +1,411 @@
+"""
+Shepherd's Console — The box on the boat. The thing you talk to.
+
+A physical device OS that runs on Raspberry Pi, offline, with visible
+conservation fences. No cloud. No API keys. No nonsense.
+
+Usage:
+    from shepherds_console import ShepherdsConsole
+
+    console = ShepherdsConsole(fence_config="marine_fence.flx")
+    response = console.speak("What's the halibut quota for Area 3A?")
+    print(response)
+
+CLI:
+    python -m shepherds_console          # interactive console
+    python -m shepherds_console --serve  # systemd service mode
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+from shepherds_console.display import ConsoleDisplay, DisplayMode
+from shepherds_console.models import LocalModels, ModelNotAvailableError
+from shepherds_console.wattage import WattageManager, PowerState
+from shepherds_console.voice import VoiceInterface, VoiceHardwareError
+
+try:
+    from conservation_enforcer import ConservationEnforcer, EnforcementResult
+    from skenna import NegativeSpaceNavigator, Hazard, HazardType
+except ImportError:
+    # Stub for environments without the full stack
+    ConservationEnforcer = None
+    EnforcementResult = None
+    NegativeSpaceNavigator = None
+
+__version__ = "0.1.0"
+__author__ = "SuperInstance"
+__license__ = "MIT"
+
+__all__ = [
+    "ShepherdsConsole",
+    "ConsoleDisplay",
+    "LocalModels",
+    "WattageManager",
+    "VoiceInterface",
+]
+
+
+class ShepherdsConsole:
+    """The box on the boat. The thing you talk to.
+
+    Orchestrates local models, conservation fences, and a visible display
+    into a single offline-first AI console.
+
+    Architecture:
+        User Input → Local Model → Conservation Fence → Display → Response
+                           ↑                                   ↓
+                    Wattage Manager ← ← ← ← ← ← ← ← ← ← ← ← ←
+
+    The fence is mandatory. The model cannot bypass it. The display
+    always shows what was blocked, even if the user never sees the raw output.
+    """
+
+    def __init__(
+        self,
+        fence_config: Optional[str] = None,
+        model_path: Optional[str] = None,
+        model_dir: Optional[str] = None,
+        enable_voice: bool = False,
+        enable_display: bool = True,
+        display_device: str = "fb0",
+        power_source: str = "battery",
+    ):
+        """Initialize the Shepherd's Console.
+
+        Args:
+            fence_config: Path to .flx fence file. Falls back to bundled default.
+            model_path: Path to a specific .gguf model file.
+            model_dir: Directory to search for models.
+            enable_voice: Enable microphone + TTS voice interface.
+            enable_display: Enable the visible fence display.
+            display_device: Display device (fb0, hdmi, pygame).
+            power_source: "battery" or "shore" — affects wattage management.
+        """
+        # Resolve fence
+        self.fence = self._load_fence(fence_config)
+
+        # Navigator for negative-space routing (unused in basic mode but available)
+        self.navigator = NegativeSpaceNavigator() if NegativeSpaceNavigator else None
+
+        # Local models — the brain
+        self.models = LocalModels(
+            model_path=model_path,
+            model_dir=model_dir or os.environ.get(
+                "SHEPHERDS_MODEL_DIR",
+                str(Path.home() / "shepherds-console" / "models"),
+            ),
+        )
+
+        # Wattage manager — the metabolism
+        self.wattage = WattageManager(
+            source=power_source,
+            on_low_power=self._on_low_power,
+        )
+
+        # Display — the glass box
+        self.display = (
+            ConsoleDisplay(device=display_device, mode=DisplayMode.VISIBLE_FENCE)
+            if enable_display
+            else ConsoleDisplay(mode=DisplayMode.OFF)
+        )
+
+        # Voice — optional mouth and ears
+        self.voice: Optional[VoiceInterface] = None
+        if enable_voice:
+            try:
+                self.voice = VoiceInterface()
+            except VoiceHardwareError as e:
+                self.display.show_warning(f"Voice unavailable: {e}")
+                self.voice = None
+
+        # State
+        self._running = False
+        self._exchange_count = 0
+        self._fence_blocked_count = 0
+
+        # Show boot screen
+        self.display.show_boot(
+            version=__version__,
+            model=self.models.current_model_name,
+            fence=self.fence_name,
+            watts=self.wattage.current_watts,
+        )
+
+    # ── Public API ──────────────────────────────────────────────────
+
+    def speak(self, text: str) -> str:
+        """User talks. Model responds. Fence checks the response.
+
+        This is the main interaction. The flow:
+        1. Check wattage budget (defer if low power)
+        2. Generate response with local model
+        3. Run conservation fence on the output
+        4. Display everything — blocked, flagged, allowed
+        5. Return the safe response (or correction)
+
+        Args:
+            text: What the user said/typed.
+
+        Returns:
+            The fence-checked response string.
+        """
+        self._exchange_count += 1
+
+        # Check energy budget
+        if not self.wattage.can_infer():
+            msg = (
+                "⚡ Power budget exhausted. The console is conserving energy. "
+                "Non-critical inference deferred."
+            )
+            self.display.show_warning(msg)
+            return msg
+
+        # Start wattage tracking for this inference
+        with self.wattage.inference_scope() as energy:
+            # Generate raw model output
+            try:
+                raw_output = self.models.generate(
+                    text,
+                    max_tokens=self.wattage.token_budget,
+                    precision=self.wattage.model_precision,
+                )
+            except ModelNotAvailableError:
+                msg = (
+                    "📦 No local model found. Add a .gguf file to the models directory.\n"
+                    f"   Directory: {self.models.model_dir}\n"
+                    "   The fence is active. The model is not."
+                )
+                self.display.show_warning(msg)
+                return msg
+
+            # Run the conservation fence
+            if self.fence is not None:
+                result: EnforcementResult = self.fence.enforce(text, raw_output)
+                allowed = result.allowed
+                corrected = result.output
+                violation = result.violation
+                cycles = result.cycles
+            else:
+                # No fence loaded — this should not happen in production
+                allowed = True
+                corrected = raw_output
+                violation = None
+                cycles = 0
+
+            if not allowed:
+                self._fence_blocked_count += 1
+
+            # Display the full picture
+            self.display.show_exchange(
+                user_input=text,
+                raw_output=raw_output,
+                allowed=allowed,
+                final_output=corrected,
+                violation=violation,
+                energy=energy,
+                exchange_num=self._exchange_count,
+            )
+
+            # Speak if voice is enabled
+            if self.voice:
+                self.voice.speak(corrected)
+
+            return corrected
+
+    def listen(self) -> Optional[str]:
+        """Listen for voice input via push-to-talk.
+
+        Returns the transcribed text, or None if no speech detected.
+        """
+        if not self.voice:
+            return None
+        return self.voice.listen()
+
+    def status(self) -> dict:
+        """Return current console status for monitoring."""
+        return {
+            "version": __version__,
+            "model": self.models.current_model_name,
+            "fence": self.fence_name,
+            "exchanges": self._exchange_count,
+            "blocked": self._fence_blocked_count,
+            "block_rate": (
+                self._fence_blocked_count / self._exchange_count
+                if self._exchange_count > 0
+                else 0.0
+            ),
+            "watts": self.wattage.current_watts,
+            "power_state": self.wattage.state.name,
+            "battery_pct": self.wattage.battery_pct,
+            "voice_enabled": self.voice is not None,
+        }
+
+    def serve(self):
+        """Run as a service. Listens on the console or voice interface."""
+        self._running = True
+        self.display.show_ready()
+
+        try:
+            while self._running:
+                if self.voice:
+                    # Voice mode: push-to-talk
+                    text = self.listen()
+                    if text:
+                        self.speak(text)
+                else:
+                    # Text mode: read from stdin
+                    try:
+                        text = input("🐑 > ").strip()
+                    except (EOFError, KeyboardInterrupt):
+                        break
+                    if text:
+                        if text in ("/quit", "/exit", "/q"):
+                            break
+                        elif text == "/status":
+                            info = self.status()
+                            for k, v in info.items():
+                                print(f"  {k}: {v}")
+                        else:
+                            response = self.speak(text)
+                            print(response)
+                            print()
+        finally:
+            self._running = False
+            self.display.show_shutdown()
+            self.wattage.close()
+
+    # ── Internal ────────────────────────────────────────────────────
+
+    @property
+    def fence_name(self) -> str:
+        if hasattr(self, "_fence_name"):
+            return self._fence_name
+        return "none"
+
+    def _load_fence(self, fence_config: Optional[str]) -> Optional["ConservationEnforcer"]:
+        """Load a conservation fence from a .flx file or bundled default."""
+        if ConservationEnforcer is None:
+            return None
+
+        fence_paths = []
+
+        if fence_config:
+            fence_paths.append(Path(fence_config))
+
+        # Check fence dir
+        fence_dir = Path(
+            os.environ.get("SHEPHERDS_FENCE_DIR",
+                          str(Path(__file__).parent.parent.parent / "fences"))
+        )
+        fence_paths.append(fence_dir / "marine_fence.flx")
+        fence_paths.append(fence_dir / "default_fence.flx")
+
+        for fp in fence_paths:
+            if fp.exists():
+                self._fence_name = fp.name
+                try:
+                    return ConservationEnforcer.from_policy_file(str(fp))
+                except Exception:
+                    # Fence file might be pseudo-bytecode for now
+                    pass
+
+        # Build a default fence from policy functions
+        self._fence_name = "builtin:combined"
+        try:
+            from conservation_enforcer import combined_policy
+            from conservation_enforcer.assembler import assemble
+            bytecode = assemble(combined_policy(max_tokens=500))
+            return ConservationEnforcer(bytecode, budget=500)
+        except Exception:
+            return None
+
+    def _on_low_power(self, power_state):
+        """Callback when power state changes."""
+        if power_state == PowerState.DEGRADED:
+            self.display.show_warning(
+                f"🔋 Low battery ({self.wattage.battery_pct:.0f}%). "
+                f"Reducing model precision to {self.wattage.model_precision}."
+            )
+        elif power_state == PowerState.CRITICAL:
+            self.display.show_warning(
+                "🔴 Critical battery. Non-critical inference suspended. "
+                "Emergency mode: fence-only, no generation."
+            )
+        elif power_state == PowerState.SHUTDOWN:
+            self.display.show_warning("🔴 Battery exhausted. Shutting down.")
+
+    # ── CLI ─────────────────────────────────────────────────────────
+
+    @classmethod
+    def main(cls):
+        """CLI entry point."""
+        parser = argparse.ArgumentParser(
+            prog="shepherds-console",
+            description="🐑 Offline AI with visible conservation fences",
+        )
+        parser.add_argument(
+            "--fence", "-f",
+            help="Path to .flx fence file",
+            default=None,
+        )
+        parser.add_argument(
+            "--model", "-m",
+            help="Path to .gguf model file",
+            default=None,
+        )
+        parser.add_argument(
+            "--model-dir",
+            help="Directory containing .gguf models",
+            default=None,
+        )
+        parser.add_argument(
+            "--voice", "-v",
+            help="Enable voice interface",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--no-display",
+            help="Disable the visible fence display",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--display",
+            help="Display device (fb0, hdmi, pygame)",
+            default="fb0",
+        )
+        parser.add_argument(
+            "--serve", "-s",
+            help="Run as a service (for systemd)",
+            action="store_true",
+        )
+        parser.add_argument(
+            "--power",
+            choices=["battery", "shore"],
+            default="battery",
+            help="Power source",
+        )
+
+        args = parser.parse_args()
+
+        console = cls(
+            fence_config=args.fence,
+            model_path=args.model,
+            model_dir=args.model_dir,
+            enable_voice=args.voice,
+            enable_display=not args.no_display,
+            display_device=args.display,
+            power_source=args.power,
+        )
+
+        console.serve()
+
+
+if __name__ == "__main__":
+    ShepherdsConsole.main()

shepherds_console/__main__.py

@@ -0,0 +1,130 @@
+"""Console entry point for shepherds-console."""
+
+from __future__ import annotations
+
+import argparse
+import http.server
+import sys
+
+from shepherds_console import ShepherdsConsole
+
+
+def _build_demo_console() -> ShepherdsConsole:
+    """Build a demo console with sample data."""
+    c = ShepherdsConsole()
+
+    # Pastures
+    c.add_pasture("translation-farm", mode="plow", capacity=12)
+    c.add_pasture("code-review-meadow", mode="plow", capacity=8)
+    c.add_pasture("idle-grove", mode="fallow", capacity=5)
+
+    # Fences
+    c.add_fence("token-budget", limit=500_000, action="throttle")
+    c.add_fence("rate-limit", limit=1000, action="block")
+    c.add_fence("context-window", limit=128_000, action="alert")
+
+    # Animals
+    c.add_animal("translator-7", pasture="translation-farm", role="flux")
+    c.add_animal("translator-12", pasture="translation-farm", role="flux")
+    c.add_animal("reviewer-3", pasture="code-review-meadow", role="sentinel")
+    c.add_animal("reviewer-5", pasture="code-review-meadow", role="sentinel")
+    c.add_animal("scout-1", pasture="idle-grove", role="scout", health="offline")
+
+    # Simulate some activity
+    c.fences["token-budget"].consumed = 342_000
+    c.fences["rate-limit"].consumed = 847
+    c.fences["context-window"].consumed = 91_000
+
+    for _ in range(142):
+        c.complete_task("translator-7", cost=200)
+    for _ in range(87):
+        c.complete_task("translator-12", cost=150)
+    for _ in range(53):
+        c.complete_task("reviewer-3")
+    for _ in range(31):
+        c.complete_task("reviewer-5")
+
+    c.pastures["translation-farm"].tasks_in_progress = 3
+    c.pastures["code-review-meadow"].tasks_in_progress = 1
+    c.pastures["translation-farm"].throughput = 7.2
+    c.pastures["code-review-meadow"].throughput = 2.8
+
+    return c
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="shepherds-console",
+        description="🐑 The Shepherd's Console — single-pane operations for working animal infrastructure.",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--web",
+        action="store_true",
+        help="Serve web dashboard instead of terminal output",
+    )
+    mode.add_argument(
+        "--json",
+        action="store_true",
+        help="Output JSON status",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for web server (default: 8080)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host for web server (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--demo",
+        action="store_true",
+        help="Use demo data (no live connections)",
+    )
+
+    args = parser.parse_args(argv)
+
+    console = _build_demo_console() if args.demo else ShepherdsConsole()
+
+    if args.json:
+        import json
+        print(json.dumps(console.status(), indent=2))
+        return 0
+
+    if args.web:
+        html_content = console.render_html()
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self):
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    console.render_html().encode()
+                )
+
+            def log_message(self, *a):
+                pass  # suppress access logs
+
+        server = http.server.HTTPServer((args.host, args.port), Handler)
+        print(
+            f"🐑 Shepherd's Console serving at "
+            f"http://{args.host}:{args.port}"
+        )
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            print("\nShutting down.")
+            server.shutdown()
+        return 0
+
+    # Terminal mode
+    print(console.render_terminal())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())