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.*
