Source observer

Add cheap structural observation that makes a new media type plannable at all.

A media type indx cannot observe cannot be planned, no matter what your descriptors say. A SourceObserver supplies the cheap structural evidence routing decides on, and installing a distribution that declares one is what makes a new format plannable. Every format indx observes reaches it exactly this way — PDF, images, Office, text and email, from five distributions of the shape yours will have. There is no built-in path your extension is a lesser version of. Package and install it as the overview describes.

from indx_interfaces import (
    EMPTY_SIGNAL,
    PageEvidence,
    SourceObserver,
    TextLayerState,
)

MEDIA_TYPE = "application/vnd.acme.purchase-order"
PAGE_BREAK = "\f"


class Observer:
    def observe(self, content: bytes, media_type: str) -> tuple[PageEvidence, ...]:
        # Nothing is how an observer says "not mine": dispatch moves on to
        # the next one. Raising would end the search instead.
        if media_type != MEDIA_TYPE:
            return ()
        body = content.decode("utf-8", errors="replace").split(PAGE_BREAK)
        return tuple(
            PageEvidence(
                page=number,
                text_layer=TextLayerState.USABLE,
                signals=(EMPTY_SIGNAL,) if not page.strip() else (),
            )
            for number, page in enumerate(body, start=1)
        )


class Provider:
    def descriptors(self) -> tuple[CapabilityDescriptor, ...]:
        ...

    def source_observers(self) -> tuple[SourceObserver, ...]:
        return (Observer(),)

source_observers() is optional, like embedding_spaces(): a provider reading a format indx already observes never implements it. Observation runs for every plan, so it inherits preflight’s budget—cheap, local, deterministic, no OCR, no rendering, no model, no network. Return page evidence rather than a whole preflight context: the source digest a plan is bound to stays indx’s to mint, and the page count is derived from what you returned.

Installed observers are asked before the ones indx ships, so you can claim a format indx already observes. Bytes of a type you claimed that will not open are an InvalidSourceError, not an empty answer—that ends the search rather than letting the next observer misread them.

Checklist

Test that an observer answers with nothing for a media type it does not claim, and raises for bytes of one it does.

Source observer

Checklist

Reference

Developer