autosearch-ai

Return a structured health snapshot for MCP clients. Includes version, registered tool count, required-tool status, channel counts by status, secrets-file presence (key NAMES only), and a cooldown summary from the runtime ChannelHealth. All values are redacted before return — no key VALUES, no cookies, no token text.

List available search modes with their channel guidance. Returns the built-in research modes (academic, news, chinese_ugc, developer, product) plus any user-defined custom modes from ~/.config/autosearch/custom_modes.json. Each mode includes: - key: mode identifier to pass to run_clarify as mode_hint - label_zh / label_en: display name - keywords: phrases that trigger auto-detection - channel_priority: recommended channels for this mode - channel_skip: channels to avoid for this mode

Run the autosearch clarifier on a user query, returning structured output. Part of the v2 tool-supplier architecture: the runtime AI uses this to decide whether to ask the user a clarifying question, and which channels / mode / rubrics to target if it proceeds. Autosearch does NOT run the full research pipeline here — it only produces the clarification envelope. Args: query: The user's research question, as-is. mode_hint: Optional preference for "fast" / "deep" / "comprehensive". If omitted, the clarifier picks. Returns: ClarifyToolResponse with: - need_clarification: True if runtime should ask the user first. - question: the clarifying question (if needed). - verification: acknowledgement text (if no clarification needed). - mode / query_type / rubrics / channel_priority / channel_skip as structured guidance for the runtime's next step.

Run a single autosearch channel and return raw evidence. Part of the v2 tool-supplier architecture: autosearch does NOT synthesize, compact, or summarize — the runtime AI reads the evidence list and decides what to do (quote, cite, follow up, ignore). Use `list_skills(group="channels")` to discover valid `channel_name` values. Args: channel_name: One of the autosearch channel skill names, e.g. "bilibili", "arxiv", "github", "xiaohongshu". query: The search text. rationale: Optional short rationale (defaults to `query` if empty). Used by some channels to tune ranking. k: Max number of Evidence items to return (latest first). Default 10. Returns: RunChannelResponse with `ok: bool`, `evidence: list[dict]` (up to k items; each evidence is already source_page-slimmed), `reason` populated on failure, and `count_total / count_returned`.

List autosearch skills with their frontmatter metadata. Part of the v2 tool-supplier architecture: the runtime AI calls this to discover what autosearch can do, then picks and invokes the leaf skills it needs. Returns static metadata only — this does not run any skill. See also: `autosearch:router` SKILL.md for how to pick groups before reading leaf skills. Args: group: Filter by group ("channels", "tools", "meta", "router"). Empty string = all groups. domain: Filter by domain tag (e.g. "chinese-ugc", "web-fetch", "academic"). Empty string = no domain filter. include_deprecated: If True, include skills marked `deprecated: true` in their frontmatter. Defaults to False so callers don't accidentally discover wave-3 removal targets.

Initialize a reflective search loop. Returns {state_id}.

Update loop state with evidence from run_channel. Returns state summary.

Get coverage gaps for this loop. Returns {state_id, gaps}.

Mark a topic as a coverage gap. Returns {state_id, gaps}.

Create a citation index for a research session. Returns {index_id}.

Add URL to citation index (idempotent). Returns {index_id, citation_number, url}.

Export citations as Markdown. Returns {index_id, markdown, count}.

Merge source citation index into target. Returns {merged_count, skipped_duplicates}.

Select 3-8 channels using group-first two-stage algorithm. Call after run_clarify to get a ranked channel list before run_channel. Returns {groups, channels, rationale}.

Run a query across multiple channels concurrently. Use when you want to search several channels in parallel for the same query. Returns {evidence_by_channel, summary, failed_channels, failed_channel_details, budget_used}.

Scan all configured channels and return their health status with fix hints. Returns a structured report grouped by tier: - tier 0: zero-config (works out of the box) - tier 1: needs API key - tier 2: needs login / cookie (run: autosearch login <platform>) Each channel includes a fix_hint — a one-line command to resolve the issue. Use this to diagnose which channels are missing API keys or credentials.

List all channels with their runtime availability status. Unlike list_skills (which returns SKILL.md metadata), list_channels returns the live status of each channel: whether it's usable right now based on the current environment's API keys and credentials. Args: status_filter: Optional filter — "ok", "warn", or "off". Empty string returns all channels. Returns: {total, ok_count, warn_count, off_count, channels: [{name, status, message, unmet_requires}]}

Extract winning query patterns from a run_channel trace. Pass the channel name, query, and result counts from a run_channel call. Returns a list of {query, channel, score} pattern dicts (empty if score < 0.5). Write results to the channel's patterns.jsonl to accumulate learning.

Generate n sub-questions covering different viewpoints on a topic. Viewpoints: user (practitioner), expert (domain), critic (skeptic), competitor (alternatives). n is clamped to [1, 4]. Returns list of {viewpoint, question} dicts.

Build a DAG from subtasks and return topologically sorted parallel batches. Each subtask dict: {id, description, depends_on?: [id, ...]}. Returns list of batches; subtasks in the same batch can run in parallel. Raises on unknown dependency references or cycles.

Filter evidence to items published within the last `days` days, newest first. Looks for date in keys: date, published_at, created_at, ts, timestamp. Items with no parseable date are excluded.

Trim evidence list to fit within token_budget, keeping highest-scored items. Token estimate: len(str(item)) // 4 per item. Items sorted by 'score' field descending before trimming.

Compress accumulated evidence into a compact research brief. Use this when a research session has accumulated many evidence items (from multiple run_channel calls) and the context is getting large. Deduplicates, reranks by relevance to query, and formats a brief summary. Args: evidence: Combined list of evidence dicts from run_channel / delegate_subtask. query: The original research question (used for relevance ranking). top_k: Max items to keep in the brief (default 5). Returns: { total_processed: int, kept: int, top_evidence: list[dict], source_coverage: {channel: count}, brief_text: "Markdown summary of key findings", }