Integration guide¶

calibre-librarian exposes a small event hook surface so external systems (PKM tools, agent wikis, note apps) can record how the library is used without coupling to the core package.

Events¶

Register handlers on the global bus:

from library.events import bus, SearchEvent, PassageEvent, IndexedEvent

def on_search(event: SearchEvent) -> None:
    ...

bus.on("search", on_search)
bus.on("passage", on_passage)
bus.on("indexed", on_indexed)

Guarantees¶

• Handlers are synchronous and fire-and-forget.
• Handler failures are logged and never propagate to the MCP tool response.
• Handlers receive fully typed dataclass payloads with citations and local file paths.

Example: record book usage in a PKM wiki¶

See tool-chest/integrations/library/agent_wiki_hook.py for a reference hook that writes structured usage records when searches and passages are retrieved.

Startup registration¶

Register hooks before serving MCP tools:

from library.events import bus
from my_integration import register_hooks

register_hooks(bus)

Do not import tool-chest paths from the library package itself. Integration code lives in the consumer repository.