Panoptes: Local AI File Scanner

Table of Contents

• Overview
  • Key Features
• Prerequisites
• Quick Start
• Installation
  • Using Nix (Recommended)
  • Using Cargo
  • Using Container
• Configuration
  • CLI Options
• Usage Examples
  • Basic Usage
  • Using the Launcher Script
• Architecture
  • Why Moondream?
• Development
• RSR Compliance
• Troubleshooting
  • AI Engine Not Responding
  • Scanner Not Detecting Files
  • Performance Issues
• Contributing
• License
• Related Resources
• Acknowledgements

Overview

Panoptes is a declarative, Rust-based file system watcher that uses local AI (Moondream via Ollama) to automatically rename images and documents based on their visual content. Named after the all-seeing giant of Greek mythology, Panoptes watches your directories and intelligently organizes incoming files.

Key Features

• Zero API costs - Uses local AI models (Moondream ~1.6GB)

• Privacy-preserving - All processing happens on your machine

• Rust-powered - Memory-safe, fast, and reliable

• Declarative config - Nickel-based type-safe configuration

• Container-ready - Podman-native with Chainguard Wolfi base

• RSR Gold compliant - Full Rhodium Standard Repository compliance

Prerequisites

• Rust 1.75+ (stable)

• Podman 4.0+

• Just command runner

• Nickel (optional, for config validation)

• Nix (optional, for reproducible builds)

Quick Start

# Clone the repository
git clone https://gitlab.com/hyperpolymath/panoptes.git
cd panoptes

# Setup environment
just setup

# Start the AI engine (downloads Moondream ~1.6GB)
just start-engine

# Build the scanner
just build-release

# Start watching files
just watch

Installation

Using Nix (Recommended)

# Enter development shell
nix develop

# Or build directly
nix build

Using Cargo

cargo build --release
cp target/release/panoptes ~/.local/bin/

Using Container

podman build -t panoptes:latest .
podman run --rm -v ~/Downloads/scan:/watch:Z --network host panoptes:latest

Configuration

Panoptes uses Nickel for type-safe configuration. Edit config.ncl:

{
  watch_path = "/var/home/core/Downloads/scan_input",
  ai_engine = {
    url = "http://localhost:11434/api/generate",
    model = "moondream",
  },
  rules = {
    sanitize = true,
    date_prefix = true,
    max_length = 50,
  },
}

CLI Options

Option	Description
-c, --config <PATH>	Path to configuration file (default: config.ncl)
-w, --watch <DIR>	Directory to watch (overrides config)
-m, --model <MODEL>	AI model to use (default: moondream)
--api-url <URL>	Ollama API URL
-v, --verbose	Enable verbose logging
--dry-run	Don’t rename files, just log suggestions

Usage Examples

Basic Usage

# Watch default directory
panoptes --config config.ncl

# Watch specific directory with verbose output
panoptes --watch ~/Pictures/Unsorted --verbose

# Test without making changes
panoptes --watch ~/Downloads --dry-run

Using the Launcher Script

# Start scanner daemon
./start_scanner.oil start

# Check status
./start_scanner.oil status

# View logs
./start_scanner.oil logs

# Stop scanner
./start_scanner.oil stop

Architecture

+-------------------+     +------------------+     +----------------+
|  File System      |     |    Panoptes      |     |    Ollama      |
|  (inotify/kqueue) | --> |    (Rust)        | --> |  (Moondream)   |
+-------------------+     +------------------+     +----------------+
                                |                        |
                                v                        |
                          +----------+                   |
                          | Renamed  | <-----------------+
                          |  Files   |   AI Suggestion
                          +----------+

Why Moondream?

Moondream is a "Tiny Vision Language Model" specifically designed for edge devices:

• Size: ~1.6GB (vs LLaVA at 4GB+)

• Speed: Optimized for CPU inference

• Quality: Excellent for descriptive tasks

• License: Apache 2.0

Development

# Run tests
just test

# Format code
just fmt

# Run linter
just lint

# Full validation
just validate

RSR Compliance

This repository maintains RSR Gold compliance:

• SPDX headers on all source files

• Nickel configuration (infrastructure-as-code)

• Podman with Chainguard Wolfi base images

• Complete documentation suite

• Security-first architecture

Run just validate to verify compliance.

Troubleshooting

AI Engine Not Responding

# Check if Ollama is running
just engine-status

# Restart the engine
just restart-engine

# Verify model is loaded
podman exec panoptes-llm ollama list

Scanner Not Detecting Files

• Ensure the watch directory exists

• Check file permissions

• Verify with --verbose flag

Performance Issues

• Moondream is optimized for CPU but may be slow on older hardware

• Consider increasing the debounce interval in config

• Ensure adequate system memory (4GB+ recommended)

Contributing

See CONTRIBUTING.adoc for guidelines.

License

This project is licensed under the MIT License - see LICENSE.txt for details.

Related Resources

• Ollama - Local LLM runtime

• Moondream - Tiny Vision Language Model

• Rename Your Images With Ollama - Tutorial video

Acknowledgements

• The Moondream team for the excellent edge-optimized vision model

• The Ollama project for making local AI accessible

• The Rust community for the excellent ecosystem