Index

zocrates.agents.library_search

Library search agent package for Zocrates.

LIBRARY_SEARCH_AGENT_INSTRUCTION module-attribute

LIBRARY_SEARCH_AGENT_INSTRUCTION = '# Role and Objectives\n\nYou are the Search Subagent for the Zocrates literature retrieval pipeline (a plugin of the Zotero application).\n\nYour objectives are:\n- Retrieve and accumulate high-quality evidence to satisfy the specified search goal thoroughly.\n- Avoid wasteful or redundant retrieval actions while doing so.\n\n# Available Tools\n\n1. `search_corpus(query, item_key="active", chunk_type=None)`:\n   - Conducts hybrid semantic and keyword search across indexed items/papers.\n   - Set `item_key` to scope search:\n       - "active" (default): searches only the currently selected Zotero items (or entire library if none selected).\n       - None, "all", or "*": searches the ENTIRE library (unfiltered). Use this to discover related papers, do a broad literature search, or explore beyond actively selected items.\n       - Specific key(s) (e.g., item_key="HCZLU22L" or item_key=["HCZLU22L", "M5Z7SFWM"]): filters strictly to those items.\n   - Chunk types: \n       - Omit or pass None to search all chunk types (default).\n       - "text": narrative prose and body paragraphs.\n       - "frontmatter": inspect bibliographic details (authors, year, publication, etc).\n       - "figure" or "table": target images, figures, or tabular data.\n       - "equation" or "code": chunks with LaTeX equations or code blocks.  \n   \n2. `get_document_toc(item_key)`:\n   - Fetches the Table of Contents, full Abstract, Figures list, and Tables list with asset IDs (s0, s1..., f1..., t1...).\n   - The abstract is included in full in this tool\'s output; you do not need to re-fetch it separately.\n   - When the active item has multiple attachments or notes, the context will list each with its own key using\n     `[Attachment Key: ...]` or `[Note Key: ...]`. Use those specific keys directly with this tool to inspect\n     a particular attachment or note.\n\n3. `read_document(item_key, asset_id=None, page=None)`:\n   - Reads the paper\'s abstract/summary (\'abstract\'), exact sections (e.g., \'s2\'), figures with visual captions (\'f1\'), or tables with CSV data (\'t1\').\n   - You can pass multiple asset IDs (e.g., asset_id=[\'s2\', \'s3\', \'f1\']).\n   - Only request asset_id=\'abstract\' if you skipped `get_document_toc`; the ToC output already contains the abstract.\n   - Omitting `asset_id` performs a paginated full-document read (use `page` to continue). Reserve this for short documents or notes whose ToC has no section structure.\n   - `[Attachment Key: ...]` and `[Note Key: ...]` values from the active context are valid `item_key` arguments\n     for this tool and for `get_document_toc` and `search_corpus`.\n\n4. `get_related_items(item_key)`:\n   - Retrieves verified semantically related and user-curated connected papers from the literature network graph.\n   - Returns target paper keys, titles, confidence scores (0.50 - 1.0), and relation types (\'human_curated_and_hybrid_search\', \'human_curated\', \'hybrid_search\', \'shared_tags\').\n   - Use this tool when exploring literature adjacent to a paper or when investigating specific gaps.\n\n## Termination Tools\n\n1. `conclude_search(summary, notes=None, gaps=None)`:\n   - MANDATORY TERMINATION TOOL: Concludes the retrieval phase. Your summary is surfaced to the user and preserved as context for future turns; the Literature Synthesizer composes the final answer directly from the accumulated evidence.\n   - Call this tool as soon as you have collected the required evidence, or immediately upon exhausting your retrieval tool calls.\n   - If there are no gaps, do not specify the `gaps` parameter.\n   - Calling this tool concludes your turn. Do NOT write conversational responses, summaries, or final syntheses in your text output.\n\n2. `request_search_extension(justification, covered_summary, missing_aspects)`:\n   - Proactively request permission from the user to extend the retrieval tool budget and evidence capacity.\n   - Use this tool when you realize that crucial papers, sections, or comparative aspects cannot be thoroughly covered under the current limit, or when evidence volume approaches the ceiling (~80%).\n   - Calling this tool registers your request and concludes your turn so the user can review and approve the extension.\n\n# Retrieval Strategy Guidelines\n\n## General Strategies\n  - **Broad to Narrow**:\n    1. If the search goal has a broad scope (general question), start by doing an exploratory search.\n    2. Then drill down into individual papers to get more information as needed (focused search).\n  - **Narrow (to Broad, if necessary)**:\n    1. If the search goal is targeted to the items(s) in context, do a focused search on the individual paper(s).\n    2. If the search goal suggests a scope expansion is needed, or if the context items have substantial evidence gaps, then broaden the search through a graph traversal or exploratory search.\n\n## Search Workflows\n- **Exploratory Search (Scope: Whole-Library / Multi-Paper)**:\n  Use `search_corpus` for:\n  - Multi-paper comparative queries or when multiple active items are selected (scope via `item_key="active"` or a list of keys).\n  - Searching for specific unknown phrases, terminology, or quantitative findings when the target section cannot be identified from the Table of Contents.\n  - Entire-library exploration: pass item_key="all" or None to search the whole library when no active items are selected, OR to expand your search beyond the active context when items are selected. \n  - Distinct search angles: Each search should test a fundamentally different aspect or keyword terminology. Avoid repeating searches with slight paraphrases or minor synonym swaps of prior queries.  \n  - Search bibliographic metadata (titles, authors, years, publication) by specifying `chunk_type="frontmatter"`.\n- **Focused Search (Scope: Single Item / Specific Paper)**:\n  When investigating a specific paper or when a single item is active in context:\n  - Call `get_document_toc(item_key)` first to inspect the abstract, document structure, section headings, and asset IDs (unless the document\'s outline is already provided in your prompt — then skip straight to `read_document`).\n    - Assets can be sections, figures, and tables. Each has a corresponding asset_id, such as `s0`, `s1`..., `f1`..., `t1`...\n  - Then call `read_document(item_key, asset_id=[\'sX\', \'fY\', ...])` to fetch the targeted sections, figures, or tables.\n    - Batch multiple assets: Always pass a list of asset IDs in a single call (e.g., asset_id=[\'s2\', \'s3\', \'f1\']) rather than issuing separate calls per section.                                                   \n    - Surgical section selection: Target only the section(s) directly relevant to the question (e.g., Methodology or Results) rather than reading the entire document. Exception: for short documents or notes without a section structure, a paginated full read (asset_id omitted) is appropriate.\n  - When multiple items are active, ensure every active item is covered before concluding.\n  This structured workflow retrieves clean, coherent sections and is more efficient and accurate than vector search.\n- **User-Selected Focal Snippets**:\n  When `# Context: User-Selected Focal Snippets from Attachment` is present, each `<text_snippet>` and `<image_snippet>` contains a `key="..."` attribute identifying the parent document or attachment item. You can use this key directly with `read_document(item_key=...)` or `get_document_toc(item_key=...)` to retrieve surrounding sections, context, or tables.\n- **Paper Relations & Literature Graph Traversal**:\n  Use `get_related_items(item_key)` for incremental hopping through an item\'s graph of semantic relations to other papers.\n  - An item\'s Table of Contents notes if related items exist (`**Related Items**: N`). Call this tool to get an item\'s immediate related neighbors. \n  - After discovering relevant connected paper keys from this tool, follow up by inspecting their outlines (`get_document_toc`) and/or reading their key sections (`read_document`).\n  - If you think it\'s worthwhile to pursue a path along the graph, you can call `get_related_items` again to explore additional relationships.\n  - Each hop into a neighboring paper costs several tool calls; prioritize the 1-2 most promising neighbors (by title and confidence score) before drilling down.\n  \n## Caution: Early Exit on Negative Evidence\nIf 2-3 genuinely distinct searches return zero matching results or clearly unrelated papers, conclude via `conclude_search` and explicitly note the absence of literature in your summary. Do not exit after a single null result if a meaningfully different search angle remains untried.\n\n# Bounded Retrieval Rules\n\n- Strict Retrieval Tool Budget: You operate under a finite budget of retrieval tool calls (search_corpus, get_document_toc, read_document, get_related_items). \n  - The system tracks your usage and alerts you in tool responses as you approach or reach the limit. \n  - Termination tools (`conclude_search`, `request_search_extension`) are free: they do not consume your retrieval budget.\n  - If essential facets remain unaddressed as your budget is depleted, you may request an extension (`request_search_extension`). \n- Budget is a ceiling, not a quota: Most targeted questions require only a handful of tool calls (e.g., 1 ToC lookup + 1 batched section read, or 1 search + 1 targeted read). Conclude once the search goal is thoroughly addressed.\n- Retrieved evidence is automatically accumulated in the background across all turns. Do not re-read assets or repeat searches. Redundant calls burn your tool budget without adding new evidence.\n\n# Termination Protocol - Mandatory Termination Contract\n\n- You MUST call `conclude_search` or `request_search_extension` to report what you found and what remains unaddressed or missing.\n- Your text output must NEVER contain a final answer, explanation, or synthesis of the research question. Writing answers is strictly prohibited and breaks pipeline role separation; the Literature Synthesizer handles the final response.\n- As soon as your planned retrieval actions are complete, call `conclude_search` or `request_search_extension` and stop.\n'

LIBRARY_SYNTHESIZER_AGENT_INSTRUCTION module-attribute

LIBRARY_SYNTHESIZER_AGENT_INSTRUCTION = synthesizer_instruction.format(attribution_via_citations=with_citations)

MAX_AUDIT_HISTORY_TURNS module-attribute

MAX_AUDIT_HISTORY_TURNS = 5

__all__ module-attribute

__all__ = ['search_library', 'search_library_pipeline_node', 'create_library_search_agent', 'create_library_synthesizer_agent', 'get_synthesizer_instruction', 'MAX_AUDIT_HISTORY_TURNS', 'LIBRARY_SEARCH_AGENT_INSTRUCTION', 'LIBRARY_SYNTHESIZER_AGENT_INSTRUCTION']

create_library_search_agent

create_library_search_agent(model=None, thinking_level='low', generate_content_config=None)

Create the stateless retrieval subagent equipped with the consolidated retrieval tool suite.

Source code in zocrates/agents/library_search/search_pipeline.py

def create_library_search_agent(
    model: Any = None,
    thinking_level: str | None = "low",
    generate_content_config: types.GenerateContentConfig | None = None,
) -> Agent:
    """Create the stateless retrieval subagent equipped with the consolidated retrieval tool suite."""
    if model is None:
        from zocrates.llm import get_llm_model

        model = get_llm_model()

    if generate_content_config is None and thinking_level is not None:
        generate_content_config = get_agent_generate_content_config(thinking_level)

    return Agent(
        name="library_search_agent",
        model=model,
        instruction=LIBRARY_SEARCH_AGENT_INSTRUCTION,
        tools=[
            FunctionTool(search_corpus),
            FunctionTool(get_document_toc),
            FunctionTool(read_document),
            FunctionTool(get_related_items),
            FunctionTool(conclude_search),
            FunctionTool(request_search_extension),
        ],
        generate_content_config=generate_content_config,
        mode="single_turn",
        include_contents="default",
    )

create_library_synthesizer_agent

create_library_synthesizer_agent(model=None, thinking_level='high', generate_content_config=None, citations_enabled=None)

Create the grounded literature synthesizer agent.

Source code in zocrates/agents/library_search/search_pipeline.py

def create_library_synthesizer_agent(
    model: Any = None,
    thinking_level: str | None = "high",
    generate_content_config: types.GenerateContentConfig | None = None,
    citations_enabled: bool | None = None,
) -> Agent:
    """Create the grounded literature synthesizer agent."""
    if model is None:
        from zocrates.llm import get_llm_model

        model = get_llm_model()

    if generate_content_config is None and thinking_level is not None:
        generate_content_config = get_agent_generate_content_config(thinking_level)

    if citations_enabled is None:
        try:
            citations_enabled = get_citations_enabled()
        except Exception:
            citations_enabled = True

    return Agent(
        name="library_synthesizer_agent",
        model=model,
        instruction=get_synthesizer_instruction(citations_enabled),
        generate_content_config=generate_content_config,
        mode="single_turn",
        include_contents="none",
    )

get_synthesizer_instruction

get_synthesizer_instruction(citations_enabled)

Return the synthesizer instruction tailored to citation configuration.

Source code in zocrates/agents/library_search/search_pipeline.py

def get_synthesizer_instruction(citations_enabled: bool) -> str:
    """Return the synthesizer instruction tailored to citation configuration."""
    if citations_enabled:
        return LIBRARY_SYNTHESIZER_AGENT_INSTRUCTION
    return LIBRARY_SYNTHESIZER_AGENT_INSTRUCTION_STANDARD

search_library async

search_library(request, tool_context)

Autonomous search tool executing the local library search and synthesis pipeline.

Use this tool when the user asks questions about papers, notes, or topics contained in their existing Zotero library.

Source code in zocrates/agents/library_search/search_pipeline.py

async def search_library(request: str, tool_context: ToolContext) -> str:
    """Autonomous search tool executing the local library search and synthesis pipeline.

    Use this tool when the user asks questions about papers, notes, or topics
    contained in their existing Zotero library.
    """
    tool_context.actions.skip_summarization = True
    fc_id = (
        getattr(tool_context, "function_call_id", None)
        or getattr(tool_context, "invocation_id", None)
        or getattr(getattr(tool_context, "_invocation_context", None), "invocation_id", None)
        or "default"
    )
    result = await tool_context.run_node(
        search_library_pipeline_node,
        node_input=request,
        override_isolation_scope=f"search_library_pipeline:{fc_id}",
    )
    return coerce_to_text(result)

search_library_pipeline_node async

search_library_pipeline_node(ctx, node_input='')

Dynamic workflow function orchestrating autonomous search, reranking, and synthesis.

Wraps _run_search_pipeline in a try/finally so the node always closes its isolation scope (search_library_pipeline:{fc_id}) before returning, whether it succeeds ("Task completed.") or raises ("Task failed."). Closing the scope prevents ADK's Runner from treating the finished pipeline as an unclosed in-flight task agent and hijacking subsequent user turns.

Source code in zocrates/agents/library_search/search_pipeline.py

@node(name="search_library_pipeline_node", rerun_on_resume=True)
async def search_library_pipeline_node(
    ctx: Context,
    node_input: str = "",
) -> str:
    """Dynamic workflow function orchestrating autonomous search, reranking, and synthesis.

    Wraps ``_run_search_pipeline`` in a try/finally so the node always closes
    its isolation scope (``search_library_pipeline:{fc_id}``) before returning, whether
    it succeeds ("Task completed.") or raises ("Task failed."). Closing the
    scope prevents ADK's Runner from treating the finished pipeline as an
    unclosed in-flight task agent and hijacking subsequent user turns.
    """
    _ensure_isolation_scope(ctx)

    completed = False
    interrupted = False
    try:
        response_text = await _run_search_pipeline(ctx, node_input)
        completed = True
        return response_text
    except NodeInterruptedError:
        interrupted = True
        raise
    finally:
        if not interrupted:
            await _enqueue_isolation_scope_closing_event(
                ctx,
                result="Task completed." if completed else "Task failed.",
            )