When to use

• Need to find papers in an OpenReview venue that match one or more ideas/topics.

Dependencies

• embed-papers must be installed and available in PATH.

- Check with: command -v embed-papers - Install with: pip install embed-papers

• OpenReview must be reachable.
• OPENAIAPIKEY is required to compute embeddings of the papers (cached) or the search intent (not cached).

- Check with: printenv OPENAIAPIKEY - If missing and embeddings are required: stop and tell the user how to set it (immediate stop).

Inputs from user

• Venue (one of):

- venueid (preferred), e.g. ICLR.cc/2024/Conference - OR {conference, year} to derive venueid as {CONF}.cc/{YEAR}/Conference, e.g. NeurIPS, 2025

• Search intent (one of):

- query (string of ideas) - OR examples (list of {title, abstract} objects)

• Optional:

- top_k (default: 100) for retrieval breadth

CLI contract (how to interpret tool output)

• Success envelope: { ok: true, schema_version: "1", command, data }
• Error envelope: { ok: false, schema_version: "1", command, error: { type, message } }
• Always parse stdout as JSON.
• Treat any ok=false as a terminal error unless the error section below says otherwise.

HARD CONSTRAINT (TOOLS):

• Do NOT call Read/Glob/Grep on any cache/embedding files or directories (e.g. anything under .cache/ or any path containing "cache", "embedding", "paper", "atlas").
• Treat caches as opaque implementation details. Never inspect them “just to check”.
• If you need cache status, ONLY use embed-papers warm-cache and rely on its JSON stdout.
• If a command outputs a cache path, DO NOT open it; proceed using the CLI utilities.

Pipeline

1. Resolve venue_id

- If the user gave {conference, year}, build: {CONF}.cc/{YEAR}/Conference - If ambiguous, ask a single clarifying question (conference acronym + year).

1. Crawl venue metadata (idempotent)

- Run: - embed-papers crawl --venue-id "<venueid>" --skip-if-exists - Record: - data.outputfile - data.total

1. Ensure embeddings are available (cache)

- Run: - embed-papers warm-cache --venue-id "<venueid>" - If this fails due to missing API key, stop and instruct the user to set OPENAIAPI_KEY. - This command also computes the embedding if no cache is found. - You MUST NOT access the cache. - You MUST use the package's provided utility.

1. Search (choose based on user input)

- Query mode: - embed-papers search --venue-id "<venueid>" --query "<query>" --top-k <topk> - Examples mode: - If needed, write a temporary JSON file containing: - [{"title":"...","abstract":"..."}, ...] - Then run: - embed-papers search --venue-id "<venueid>" --examples-file "<tmp.json>" --top-k <topk>

1. Organize results (post-processing)

- Group primarily by primary_area (if present). - Within groups, prefer papers with clear overlap to the query/examples. - For each recommended paper, add agent judgment notes: - why it matches - what seems novel/different - caveats (weak match, missing abstract, unclear claims, etc.)

Report requirements (Markdown only)

• Output is a Markdown report only (no raw JSON).
• Keep the final recommendation list short: 5-10 papers max.
• Do not output a full ranked list or appendix by default (only if the user asks).

What I'd start with

• Begin this section with a short, casual sentence (lowercase is fine).

- Example: "here's what i recommend you to read as a beginning."

• Then list 5-10 papers.
• Each item must include:

- Title (bold) - OpenReview link - 1-2 sentence rationale (fit + why it matters, use italic to emphasis)

How I organized it

• Briefly explain grouping logic and where judgment calls were applied.
• Note missing metadata (e.g., missing abstracts) when relevant.

Why these stand out

• Use informal labels in the narrative (no formal rubric), e.g.:

- "the obvious hits" - "the surprisingly relevant ones" - "the quirky but promising picks"

Error handling

• NoPapersFoundError

- Likely invalid venue_id; suggest the pattern {CONF}.cc/{YEAR}/Conference and ask for the correct venue.

• CacheMissRequiresApiKeyError

- Instruct the user to set OPENAIAPIKEY and retry.

• OpenReviewRequestError / EmbeddingRequestError

- Suggest retrying, reducing load (smaller top_k), or trying later (rate limits / transient failures).