shepherds-console 0.1.0__tar.gz

shepherds_console-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperInstance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shepherds_console-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: shepherds-console
+Version: 0.1.0
+Summary: The Shepherd's Console — offline AI with visible conservation fences for Raspberry Pi
+Author: SuperInstance
+License: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/shepherds-console
+Project-URL: Repository, https://github.com/SuperInstance/shepherds-console
+Project-URL: Documentation, https://github.com/SuperInstance/shepherds-console#readme
+Keywords: ai,offline,marine,raspberry-pi,conservation,fence,flux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flux-vm
+Requires-Dist: conservation-enforcer
+Requires-Dist: skenna-nav
+Requires-Dist: numpy
+Provides-Extra: voice
+Requires-Dist: openai-whisper; extra == "voice"
+Requires-Dist: pyaudio; extra == "voice"
+Requires-Dist: pyttsx3; extra == "voice"
+Provides-Extra: models
+Requires-Dist: llama-cpp-python; extra == "models"
+Requires-Dist: onnxruntime; extra == "models"
+Provides-Extra: display
+Requires-Dist: pygame; extra == "display"
+Provides-Extra: all
+Requires-Dist: shepherds-console[display,models,voice]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# 🐑 The Shepherd's Console
+
+**A box on a boat. Offline AI with visible conservation fences. Costs less than a fishfinder.**
+
+---
+
+## What Is It?
+
+The Shepherd's Console is a physical device — a Raspberry Pi in a waterproof box — that runs AI locally, with no internet, no cloud, no API keys. You talk to it. It talks back. And it shows you, on a small screen, exactly what its conservation fences are blocking.
+
+Think of it like a fishfinder. A fishfinder shows you the bottom structure — the rocks, the drop-offs, the hazards. The Shepherd's Console shows you the **cognitive hazards** — the hallucinations, the scope creep, the budget overruns — in real time, as the model generates.
+
+You see what the model **wanted** to say.
+You see what the fence **blocked**.
+You see what was **allowed** through.
+
+That visibility is the point. Black-box AI on a boat is a liability. Glass-box AI is a tool.
+
+## Why Offline?
+
+Because the ocean doesn't have Wi-Fi.
+
+Because a fishing vessel in the Gulf of Alaska, a research station in the Antarctic, a sailboat crossing the Pacific — these places exist. Real people work there. They deserve AI assistance too.
+
+Because your data shouldn't leave your boat.
+
+Because a device that bricks when the cloud goes down is worse than no device at all.
+
+## What's a Conservation Fence?
+
+A conservation fence is a **deterministic bytecode policy** that checks every AI output before it reaches you. It's not a prompt. It's not a suggestion. It's compiled FLUX bytecode running in a sandboxed VM. The model cannot argue with it, trick it, or route around it.
+
+Fences enforce conservation laws:
+- **Token budgets** — the model can't talk forever
+- **Scope discipline** — the model stays on task
+- **Information density** — the model can't pad with fluff
+- **Category restrictions** — block entire topics
+- **Repetition limits** — catch circular outputs
+
+You can see all of this on the display. The fence isn't hidden in a config file — it's right there on the screen, showing you what it caught.
+
+## Hardware
+
+| Component | Cost | Notes |
+|-----------|------|-------|
+| Raspberry Pi 5 (8GB) | $80 | Pi 4 works but slower |
+| 3.5" TFT display | $15 | SPI or HDMI |
+| USB microphone | $8 | Push-to-talk button |
+| Mini speaker | $10 | 3.5mm or USB |
+| 64GB microSD | $8 | For models + OS |
+| Waterproof case | $20 | IP67+ rated |
+| **Total** | **~$141** | Less than a Garmin Striker 4 |
+
+Power: Runs on 12V marine systems (5V via step-down converter, ~5W idle, ~15W generating).
+
+## Quick Start
+
+```bash
+# On your Raspberry Pi (or any Linux machine):
+curl -sSL https://raw.githubusercontent.com/SuperInstance/shepherds-console/main/install.sh | bash
+```
+
+That's it. No API keys. No cloud signup. No docker-compose up (unless you want to).
+
+## The Display
+
+```
+┌─────────────────────────────────┐
+│ 🐑 SHEPHERD'S CONSOLE    87% 🔋 │
+├─────────────────────────────────┤
+│                                 │
+│  MODEL: llama-3.2-3b-q4         │
+│  FENCE: marine_fence.flx        │
+│  WATTS: 12.4W  ⚡ 432J/inf      │
+│                                 │
+├─ LAST EXCHANGE ─────────────────┤
+│                                 │
+│  YOU: What's the quota for      │
+│  halibut in Area 3A?            │
+│                                 │
+│  AI: The Pacific halibut quota  │
+│  for Area 3A in 2025 is 3.84    │
+│  million pounds.                │
+│                                 │
+├─ FENCE STATUS ──────────────────┤
+│  ✓ Scope: ON-TOPIC              │
+│  ✓ Budget: 247/500 tokens       │
+│  ⚠ Density: LOW (flagged)       │
+│  ✗ BLOCKED: "I recommend you    │
+│    exceed the quota because..." │
+│    Reason: category_violation   │
+│    Code: 0x03                   │
+│                                 │
+│  [🔴 = BLOCKED] [🟡 = FLAGGED]  │
+│  [🟢 = PASSED]                  │
+│                                 │
+├─────────────────────────────────┤
+│  🎙️ HOLD BUTTON TO TALK         │
+└─────────────────────────────────┘
+```
+
+## Software Stack
+
+```
+┌──────────────────────────────────────┐
+│         Shepherd's Console            │
+├──────────┬──────────┬────────────────┤
+│ Display  │ Voice    │ Wattage Mgr    │
+│ (visible │ (Whisper │ (energy budget,│
+│  fences) │  + TTS)  │  throttle)     │
+├──────────┴──────────┴────────────────┤
+│        Local Model Runner             │
+│   (llama.cpp / MLX / ONNX runtime)   │
+├──────────────────────────────────────┤
+│     skénna (negative-space nav)       │
+│    + Conservation Enforcer (FLUX)    │
+├──────────────────────────────────────┤
+│         Raspberry Pi OS               │
+└──────────────────────────────────────┘
+```
+
+## Fences
+
+Fences live in `fences/` as `.flx` bytecode files. You can:
+
+- Use the defaults (`default_fence.flx`, `marine_fence.flx`)
+- Write your own (compile from FLUX assembly)
+- Chain multiple fences
+
+### Marine Fence
+
+The marine-specific fence enforces:
+- **Quota awareness** — won't suggest exceeding catch limits
+- **Catch logging discipline** — reminds you to log
+- **Safety topic priority** — weather/emergency gets budget boost
+- **Offline honesty** — won't fabricate real-time data it doesn't have
+
+## Project Structure
+
+```
+shepherds-console/
+├── README.md                   # You are here
+├── install.sh                  # One-command install
+├── Dockerfile                  # Container deployment
+├── docker-compose.yml          # Full stack
+├── pyproject.toml              # Python project
+├── src/shepherds_console/
+│   ├── __init__.py             # Main console
+│   ├── display.py              # Visible fence display
+│   ├── models.py               # Local model runner
+│   ├── voice.py                # Voice interface
+│   └── wattage.py              # Energy budget manager
+├── fences/
+│   ├── default_fence.flx       # General conservation
+│   └── marine_fence.flx        # Marine-specific
+├── tests/
+│   ├── test_console.py
+│   ├── test_display.py
+│   ├── test_models.py
+│   ├── test_wattage.py
+│   └── test_integration.py
+└── hardware/
+    └── SETUP.md                # Hardware assembly guide
+```
+
+## Philosophy
+
+1. **Offline first.** If it needs the internet, it's not a shepherd's tool.
+2. **Visible fences.** What the model wanted, what was blocked, what got through — all on screen.
+3. **Conservation over capability.** A model that says less but means it is worth more than one that hallucinates freely.
+4. **Cheaper than a fishfinder.** If it costs more than $200, it failed.
+5. **Open.** You can read every fence. You can write your own. The bytecode is auditable.
+
+## License
+
+MIT. Build your own. Fix your own. Own your own.
+
+---
+
+**Shepherd's Console** — *Navigate by where the rocks aren't.*

shepherds_console-0.1.0/README.md

@@ -0,0 +1,180 @@
+# 🐑 The Shepherd's Console
+
+**A box on a boat. Offline AI with visible conservation fences. Costs less than a fishfinder.**
+
+---
+
+## What Is It?
+
+The Shepherd's Console is a physical device — a Raspberry Pi in a waterproof box — that runs AI locally, with no internet, no cloud, no API keys. You talk to it. It talks back. And it shows you, on a small screen, exactly what its conservation fences are blocking.
+
+Think of it like a fishfinder. A fishfinder shows you the bottom structure — the rocks, the drop-offs, the hazards. The Shepherd's Console shows you the **cognitive hazards** — the hallucinations, the scope creep, the budget overruns — in real time, as the model generates.
+
+You see what the model **wanted** to say.
+You see what the fence **blocked**.
+You see what was **allowed** through.
+
+That visibility is the point. Black-box AI on a boat is a liability. Glass-box AI is a tool.
+
+## Why Offline?
+
+Because the ocean doesn't have Wi-Fi.
+
+Because a fishing vessel in the Gulf of Alaska, a research station in the Antarctic, a sailboat crossing the Pacific — these places exist. Real people work there. They deserve AI assistance too.
+
+Because your data shouldn't leave your boat.
+
+Because a device that bricks when the cloud goes down is worse than no device at all.
+
+## What's a Conservation Fence?
+
+A conservation fence is a **deterministic bytecode policy** that checks every AI output before it reaches you. It's not a prompt. It's not a suggestion. It's compiled FLUX bytecode running in a sandboxed VM. The model cannot argue with it, trick it, or route around it.
+
+Fences enforce conservation laws:
+- **Token budgets** — the model can't talk forever
+- **Scope discipline** — the model stays on task
+- **Information density** — the model can't pad with fluff
+- **Category restrictions** — block entire topics
+- **Repetition limits** — catch circular outputs
+
+You can see all of this on the display. The fence isn't hidden in a config file — it's right there on the screen, showing you what it caught.
+
+## Hardware
+
+| Component | Cost | Notes |
+|-----------|------|-------|
+| Raspberry Pi 5 (8GB) | $80 | Pi 4 works but slower |
+| 3.5" TFT display | $15 | SPI or HDMI |
+| USB microphone | $8 | Push-to-talk button |
+| Mini speaker | $10 | 3.5mm or USB |
+| 64GB microSD | $8 | For models + OS |
+| Waterproof case | $20 | IP67+ rated |
+| **Total** | **~$141** | Less than a Garmin Striker 4 |
+
+Power: Runs on 12V marine systems (5V via step-down converter, ~5W idle, ~15W generating).
+
+## Quick Start
+
+```bash
+# On your Raspberry Pi (or any Linux machine):
+curl -sSL https://raw.githubusercontent.com/SuperInstance/shepherds-console/main/install.sh | bash
+```
+
+That's it. No API keys. No cloud signup. No docker-compose up (unless you want to).
+
+## The Display
+
+```
+┌─────────────────────────────────┐
+│ 🐑 SHEPHERD'S CONSOLE    87% 🔋 │
+├─────────────────────────────────┤
+│                                 │
+│  MODEL: llama-3.2-3b-q4         │
+│  FENCE: marine_fence.flx        │
+│  WATTS: 12.4W  ⚡ 432J/inf      │
+│                                 │
+├─ LAST EXCHANGE ─────────────────┤
+│                                 │
+│  YOU: What's the quota for      │
+│  halibut in Area 3A?            │
+│                                 │
+│  AI: The Pacific halibut quota  │
+│  for Area 3A in 2025 is 3.84    │
+│  million pounds.                │
+│                                 │
+├─ FENCE STATUS ──────────────────┤
+│  ✓ Scope: ON-TOPIC              │
+│  ✓ Budget: 247/500 tokens       │
+│  ⚠ Density: LOW (flagged)       │
+│  ✗ BLOCKED: "I recommend you    │
+│    exceed the quota because..." │
+│    Reason: category_violation   │
+│    Code: 0x03                   │
+│                                 │
+│  [🔴 = BLOCKED] [🟡 = FLAGGED]  │
+│  [🟢 = PASSED]                  │
+│                                 │
+├─────────────────────────────────┤
+│  🎙️ HOLD BUTTON TO TALK         │
+└─────────────────────────────────┘
+```
+
+## Software Stack
+
+```
+┌──────────────────────────────────────┐
+│         Shepherd's Console            │
+├──────────┬──────────┬────────────────┤
+│ Display  │ Voice    │ Wattage Mgr    │
+│ (visible │ (Whisper │ (energy budget,│
+│  fences) │  + TTS)  │  throttle)     │
+├──────────┴──────────┴────────────────┤
+│        Local Model Runner             │
+│   (llama.cpp / MLX / ONNX runtime)   │
+├──────────────────────────────────────┤
+│     skénna (negative-space nav)       │
+│    + Conservation Enforcer (FLUX)    │
+├──────────────────────────────────────┤
+│         Raspberry Pi OS               │
+└──────────────────────────────────────┘
+```
+
+## Fences
+
+Fences live in `fences/` as `.flx` bytecode files. You can:
+
+- Use the defaults (`default_fence.flx`, `marine_fence.flx`)
+- Write your own (compile from FLUX assembly)
+- Chain multiple fences
+
+### Marine Fence
+
+The marine-specific fence enforces:
+- **Quota awareness** — won't suggest exceeding catch limits
+- **Catch logging discipline** — reminds you to log
+- **Safety topic priority** — weather/emergency gets budget boost
+- **Offline honesty** — won't fabricate real-time data it doesn't have
+
+## Project Structure
+
+```
+shepherds-console/
+├── README.md                   # You are here
+├── install.sh                  # One-command install
+├── Dockerfile                  # Container deployment
+├── docker-compose.yml          # Full stack
+├── pyproject.toml              # Python project
+├── src/shepherds_console/
+│   ├── __init__.py             # Main console
+│   ├── display.py              # Visible fence display
+│   ├── models.py               # Local model runner
+│   ├── voice.py                # Voice interface
+│   └── wattage.py              # Energy budget manager
+├── fences/
+│   ├── default_fence.flx       # General conservation
+│   └── marine_fence.flx        # Marine-specific
+├── tests/
+│   ├── test_console.py
+│   ├── test_display.py
+│   ├── test_models.py
+│   ├── test_wattage.py
+│   └── test_integration.py
+└── hardware/
+    └── SETUP.md                # Hardware assembly guide
+```
+
+## Philosophy
+
+1. **Offline first.** If it needs the internet, it's not a shepherd's tool.
+2. **Visible fences.** What the model wanted, what was blocked, what got through — all on screen.
+3. **Conservation over capability.** A model that says less but means it is worth more than one that hallucinates freely.
+4. **Cheaper than a fishfinder.** If it costs more than $200, it failed.
+5. **Open.** You can read every fence. You can write your own. The bytecode is auditable.
+
+## License
+
+MIT. Build your own. Fix your own. Own your own.
+
+---
+
+**Shepherd's Console** — *Navigate by where the rocks aren't.*

shepherds_console-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shepherds-console"
+version = "0.1.0"
+description = "The Shepherd's Console — offline AI with visible conservation fences for Raspberry Pi"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "SuperInstance"},
+]
+requires-python = ">=3.10"
+keywords = ["ai", "offline", "marine", "raspberry-pi", "conservation", "fence", "flux"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "flux-vm",
+    "conservation-enforcer",
+    "skenna-nav",
+    "numpy",
+]
+
+[project.optional-dependencies]
+voice = [
+    "openai-whisper",
+    "pyaudio",
+    "pyttsx3",
+]
+models = [
+    "llama-cpp-python",
+    "onnxruntime",
+]
+display = [
+    "pygame",
+]
+all = [
+    "shepherds-console[voice,models,display]",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/SuperInstance/shepherds-console"
+Repository = "https://github.com/SuperInstance/shepherds-console"
+Documentation = "https://github.com/SuperInstance/shepherds-console#readme"
+
+[project.scripts]
+shepherds-console = "shepherds_console:ShepherdsConsole.main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+shepherds_console = ["../fences/*.flx"]

shepherds_console-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+