tools.librarian_tool module

Autonomous Librarian subagent dispatch tool.

The Librarian handles long-term memory management for Stargazer agents by recording notes in a git-versioned paginated notebook. It operates asynchronously with a scoped toolset.

Follows the established Redis-backed subagent lifecycle:

_create_subagent → _call_subagent → _delete_subagent

as used by the Swarm Supervisor (scripts/swarm_supervisor.py).

async tools.librarian_tool.dispatch_librarian(ctx, instruction, model='gemini-3-flash')[source]

Spawn the Librarian subagent to manage the notebook in the background.

The dispatch_librarian tool handler. After an authorization check it schedules the Librarian runner as a detached asyncio task and returns immediately, so the LLM gets an instant confirmation while the actual notebook analysis and writing happen out of band; results land in the system log rather than the reply.

Interactions: gates on _check_subagent_access(); launches _librarian_runner() via asyncio.create_task and keeps a strong reference in the module-level _active_librarians set (with a done-callback that discards it) so the loop does not GC-cancel the in-flight task. The runner itself, not this function, touches Redis, subagents, and the LLM. Dispatched by name through tool_loader from the TOOLS list (and exercised directly by tests/test_librarian_tool.py and tests/test_subagent_access_gating.py).

Parameters:

  • ctx (ToolContext) – The tool context, supplying identity, Redis, platform, and channel.

  • instruction (str) – The task for the Librarian (e.g. summarize a decision).

  • model (str) – The LLM model the Librarian should use; defaults to _DEFAULT_LIBRARIAN_MODEL.

Returns:

A plain confirmation string on dispatch, or the JSON error from _check_subagent_access() when the caller is unauthorized.

Return type:

str