OuEstCharlie Python Toolkit

Shared Python library for building OuEstCharlie photo management agents.

Overview

This toolkit provides four core capabilities:

1. MCP integration — MCP server lifecycle, tool registration, progress reporting, and logging
2. LanceDB index — per-photo columnar index, summaries, and the summary.json schema-version marker
3. XMP read-edit with consistency — sidecar read-modify-write with optimistic concurrency and field-level semantics
4. Image processing — thumbnail AVIF grid assembly and on-demand JPEG preview generation, delegated to ouestcharlie-imageproc

Package Structure

Sub-packages, lowest layer first. A module imports only from its own layer or a lower one (enforced by tests/test_architecture.py):

src/ouestcharlie_toolkit/
├── storage/      # Backend protocol, local and cloud-mount backends, .ouestcharlie/ layout, content hash
├── model/        # Searchable fields, tags, PhotoEntry / XmpSidecar, summaries, schema version
├── media/        # Photo (EXIF, HEIF, AVIF/JXL/RAW size) and Video (MP4/MOV, capture time)
├── xmp/          # Sidecar naming, parsing, serialization, XmpStore
├── index/        # LanceIndex, Lance schema, queries, compute_summary, SummaryStore
├── renditions/   # Thumbnails and previews: the only user of ouestcharlie-imageproc
└── agent/        # AgentBase (MCP server) and logging

Agents import from a sub-package (from ouestcharlie_toolkit.index import LanceIndex), never from a leaf module or a _private name. Tests mirror the same layout under tests/.

Installation

From PyPI (recommended)

pip install ouestcharlie-toolkit

ouestcharlie-imageproc (the Rust binary) is a separate package pulled in automatically. No Rust toolchain required at install time.

System prerequisites:

• macOS: brew install inih brotli gettext (required by pyexiv2 at runtime)
• Linux/Windows: no extra steps

From source (development)

# For macOs on arm64 architecture, the full Python version is required e.g.: cpython-3.14.5-macos-aarch64-none
#  the version string is listed by `uv python list`
uv venv --python 3.14
uv sync

uv sync uses the [tool.uv.sources] override to install ouestcharlie-imageproc from the adjacent ../outestcharlie-imageproc checkout as an editable install (which compiles the Rust binary). Make sure that repo is checked out alongside this one.

Running Tests

Always use .venv/bin/python -m pytest — do not use .venv/bin/pytest or a system python:

# Unit tests
.venv/bin/python -m pytest tests/ -v

# Run a specific file
.venv/bin/python -m pytest tests/media/photo/test_photo.py -v --tb=short

Integration tests (real image-proc binary) are in ouestcharlie-imageproc/tests_integration/.

Building a Wheel

The toolkit is pure Python — no Rust compilation required:

pip install hatch
hatch build
# produces dist/ouestcharlie_toolkit-*.whl (pure Python, any platform)

Dependencies

• mcp — Official MCP Python SDK
• pyexiv2 — EXIF extraction from image files (wraps Exiv2); requires brew install inih on macOS
• blake3 — Fast content hashing
• ouestcharlie-imageproc — Rust coprocessor for image decode, resize, AVIF assembly, JPEG preview

XMP parsing and serialization use stdlib only and have no native dependencies.

Usage

Creating an Agent

from ouestcharlie_toolkit import AgentBase


class HousekeepingAgent(AgentBase):
    def __init__(self):
        super().__init__(name="ouestcharlie-housekeeping", version="1.0.0")

        @self.mcp.tool()
        async def rebuild_partition(backend: str, partition: str, mode: str = "lazy"):
            """Rebuild partition thumbnails."""
            photos = await self.backend.list_files(partition, suffix=".jpg")
            progress = self.progress(total=len(photos))

            for photo in photos:
                await self.check_cancelled()
                await progress.advance(message=f"Processing {photo.path}")

            return {"photosProcessed": len(photos), "errors": 0}


if __name__ == "__main__":
    agent = HousekeepingAgent()
    agent.run()  # Runs on stdio transport

Working with XMP Sidecars

from ouestcharlie_toolkit import XmpStore


async def add_face_tags(store: XmpStore, photo_path: str, faces: list[str]):
    def modify(xmp):
        for face in faces:
            tag = f"ouestcharlie:faces/{face}"
            if tag not in xmp.tags:
                xmp.tags.append(tag)
        return xmp

    await store.read_modify_write(photo_path, modify)

Backend Configuration

export WOOF_BACKEND_CONFIG='{"type": "filesystem", "root": "/Users/alice/Photos"}'

Architecture

See py_toolkit_LLD.md for the design and agent_LLD_rationale.md for technology selection rationale.

Key design principles:

• Optimistic concurrency — All summary.json and XMP writes use version tokens to detect conflicts
• Unknown field preservation — Schema evolution via _extra dict in dataclasses
• Async throughout — All I/O operations are async
• Backend abstraction — Swappable storage backends (local, S3, GCS, etc.)
• MCP-native — Built on FastMCP for clean agent implementation

References

• MCP Python SDK
• MCP Specification
• pyexiv2
• OuEstCharlie HLD

License

MIT license