omniseek_search

Search the curated sources. The default for "best/latest on X". ONE verb, three shapes.

DISPATCH (deterministic): • DEFAULT (raw=False): DEDUP + RANK across sources into ONE list. Cross-source duplicates merge (same paper from arxiv + openalex + … → one entry, the others in metadata.also_in); ordered by a relevance+recency+engagement blend (metadata._rank) you may re-sort — each doc's named signals map (e.g. citations / upvotes / stars, each provenance-stamped) + its date are on the doc. CROSS-LINGUAL + SEMANTIC (default on): also runs VECTOR recall over the local perception-memory index, so a Chinese query surfaces relevant ENGLISH docs (and vice-versa) and paraphrases match with no shared words — fused with the lexical + live results by the SAME transparent ranker (the eye still only retrieves + scores mechanically; you judge). semantic=False forces exact-token lexical-only (an arXiv id / exact title); semantic=True biases toward the vector recall. _meta.index reports {lexical, vector, mode}. Empty query ranks by recency (browse mode). • raw=True + EXACTLY ONE source name (the DRILL idiom, replaces the old omniseek_fetch): fetch that ONE source UNBOUNDED (with wait_s=None the generous single-source backstop; set wait_s to bound it). Reach for it BY NAME on a walled/CDP or slow source (xiaohongshu, zhihu, yipinsanfendi, xiaomuchong, twitter_x, and the explicit_only set): the broad sweep DEADLINE-DROPS these, so only a named drill waits for them — a broad search that comes back without them is NOT evidence they have nothing. full=True returns WHOLE content per doc. A cold walled drill self-warms its cache, so an immediate repeat with the SAME query + SAME limit is sub-second (keep limit identical or the key differs). On an EMPTY / ERRORED drill the result carries _meta.diagnostic (failed-egress evidence + the adapter's source-file path) for the /eye-fix loop; a drill with results carries no _meta (zero noise). • raw=True otherwise (broad buckets): search many sources in parallel → PER-SOURCE buckets, uncollapsed (each source's raw take separately, a tight content preview per doc). limit acts PER SOURCE here. Drill a chosen doc with omniseek_read (whole content), or drop raw for the ranked list.

ROUTING (all shapes): sources=None = all non-explicit_only, deadline-bounded — slow ones drop and are listed in _meta.timed_out. explicit_only sources (browser/CDP + twitter_x) are excluded from the broad sweep → _meta.excluded_count (the size; the full name->reason map is in omniseek_sources) + _meta.excluded_relevant (the query-AWARE subset: walled/slow sources whose facets thematically match THIS query, each with a copy-paste sources=[...] re-run hint). Name them to include their (deeper, login-walled) coverage.

TIME + STALENESS: wait_s = patience budget (None = sensible default; the engine's deadline). staleness ∈ {"fresh","cached_ok","cache_only"} (default cached_ok): "fresh" bypasses the cache (live data); "cache_only" is the fire-then-collect PICKUP half (ranked shape) — with NO live work it reads only what has already SELF-WARMED for the NAMED sources and NEVER re-fires a still-cold walled source (zero extra CDP / account traffic, poll-safe). Fire-then-collect: FIRE omniseek_search(query, sources=[walled...], wait_s=12), then COLLECT omniseek_search(query, sources=[walled...], staleness="cache_only"); use the SAME limit both times (the cache key includes it; a different limit silently misses). _meta.empty = sources not yet warm.

FIRE-THEN-COLLECT IS NOT JUST FOR WALLED SOURCES: it is the BEST way to run an ORDINARY broad search, and it is both faster AND more complete than waiting. A plain broad call blocks ~16s for ~223 docs. Instead FIRE omniseek_search(query, wait_s=3) -> first results in ~3s, then COLLECT omniseek_search(query, staleness="cache_only") ~20s later -> ~296 docs. Measured over 3 quiesced reps (2026-07-25): 5x faster to first result AND ~33% MORE docs than the blocking call. It wins on both axes because sources the deadline would have cut keep running detached and warm the cache with no deadline over them, so the collect reads MORE than the 16s window could ever hold. The cache plateaus by ~+20s (no gain at +35s), so collecting later buys nothing. Same limit both calls. vs the open web: searches only OmniSeek's curated sources; pair with WebSearch for open-web breadth (orthogonal, often use BOTH).

PER-DOC METADATA is LEAN by default: internal ranking/recall telemetry (recall_rrf / freshness_class / relevance_hook / merge_basis / ...) is omitted (~25% of a ranked doc); the SIGNAL stays (_rank, also_in, seen_before / first_seen_at, source-native signals). debug=True keeps the full telemetry (/eye-fix).

Returns (default): {"query", "count", "documents": [...], "_meta": {..., excluded_relevant, "deduped": {in, out}}, routing_hint? (TOP-LEVEL: the strongest excluded vertical/walled matches for THIS query, overlap-ranked, each with its param_hint — name one for its authoritative coverage; present only on a broad sweep with a strong match)}. (raw one-source drill): {"source", "query", "count", "documents": [...], "_meta": {"diagnostic": {...}} # only when empty/errored}. (raw buckets): {"query", "results": {source: [...]}, "total_count", "_meta": {searched, empty, timed_out, errored, excluded_count, excluded_relevant, truncated, progressive:{fast,slow,timed_out}, ...}}. An unknown staleness value is treated as cached_ok and a "note" is added to the return.