sibyl AGENTS.md

Sibyl — Agent Guide

This file helps AI agents (Claude Code, Cursor, etc.) use Sibyl effectively via MCP.

Setup

pip install sibyl-research
# Optional local cross-encoder ranking:
pip install 'sibyl-research[rerank]'
# Optional experimental one-shot reports and report export:
pip install 'sibyl-research[report]'
# Retrieval-provider mode (recommended) needs NO key — you do the reasoning:
claude mcp add sibyl -- sibyl-mcp
# For the experimental research() tool, add a provider key so sibyl's own model runs it:
claude mcp add sibyl -e DEEPSEEK_API_KEY=sk-... -- sibyl-mcp --profile report

Core boundary — Sibyl retrieves, the host reasons

Recommended: YOU (the host model) research; sibyl only retrieves. This is keyless and gives the best quality, because YOUR reasoning is applied to real evidence — a mid-tier model doing the synthesis fabricates on hard questions, whereas you can cross-reference sources and abstain when they don't answer.

# structured retrieval for an agent pipeline (Loop/Argus-style):
gather_bundle("Serbian quarterfinalist 2018 Madrid Open men's singles")
→ consume ranked sources[].evidence[] passages; cite each by citation_id.
→ inspect content_origin; treat search_snippet evidence as a lead, not full text.
→ compare content_cluster_id; matching clusters are not independent corroboration.
→ inspect status and diagnostics before synthesis; relevance defaults to lexical_v1.
→ optional: ranker="flashrank"; inspect ranking_method and ranking_warning for fallback.
→ query_term_coverage is a recall hint, not proof of factual sufficiency.
→ quality_score=null means source quality has not been computed.

# readable retrieval for a conversational host:
gather_sources("Serbian quarterfinalist 2018 Madrid Open men's singles")
gather_sources("2018 Madrid Open men's singles draw results")   # call again with sub-queries
→ read the returned [Source N] blocks, cross-reference, answer WITH citations.
→ if the sources don't contain it, gather more or say you don't know — never guess.

# bounded workflow for a dependent or multi-part question:
gather_evidence(question="In what year was the company that created CUDA founded?")
→ if next_action is decompose_query, call again with loop_id and one atomic query.
→ finish with the synthesis-ready supporting E-step IDs.
→ synthesize only after the loop status is ready; the host still does all reasoning.