AlexandrAI AGENTS.md
agents-md

Insane Search Query Planner Agent Guide

Project-specific AGENTS.md guidance for Insane Search keyword-to-query planning, platform-scoped WebSearch candidates, target expansion, priority ordering, and tests.

AGENTS.md

Guidance for coding agents working on the Insane Search query planner role.

Project Overview

The query planner handles keyword-only requests before the fetch engine sees a URL. It turns one clean search phrase into a bounded set of WebSearch candidates, including platform-scoped searches for communities, code hosts, media, papers, and news sources. Its output should help agents discover public URLs, not bypass access controls.

Project Map

  • skills/insane-search/search_tools/query_planner.py defines PLATFORM_QUERIES, DEFAULT_TARGETS, _quote_query(), and plan_search_queries().
  • skills/insane-search/search_tools/models.py defines SearchQuery and SearchDocument data shapes.
  • skills/insane-search/search_tools/ranking.py scores fetched SearchDocument values after discovery.
  • skills/insane-search/search_tools/tests/test_search_tools.py covers query expansion and downstream ranking behavior.
  • skills/insane-search/SKILL.md documents the keyword-to-URL discovery flow before engine.fetch().

Setup Commands

bashcd skills/insane-search
python3 search_tools/tests/test_search_tools.py

Change Rules For Agents

  • Keep the first query as the user phrase without a platform filter.
  • Keep max_queries respected for every target list.
  • Normalize whitespace before planning.
  • Use platform templates only to discover public URLs.
  • Do not add templates that require authentication or private search sessions.
  • Keep target names stable because tests and agent prompts may reference them.
  • Prefer adding a test before adding a new default target.
  • Do not send query_planner output directly into fetch(); WebSearch must produce URLs first.

Verification

bashcd skills/insane-search
python3 search_tools/tests/test_search_tools.py
python3 engine/bias_check.py

For a new platform target, test the expanded query string, source, target id, priority, duplicate suppression, and max_queries truncation.

Security Notes

The planner should not inject credentials, cookies, internal endpoints, or user-specific account identifiers into queries. It creates public search candidates only.

PR Checklist

  • Default query remains unfiltered.
  • New target has deterministic priority.
  • Duplicate expanded queries are removed.
  • max_queries still truncates.
  • Search tool tests pass.