-
Notifications
You must be signed in to change notification settings - Fork 0
FE-554: Structured interview: scope phase #17
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
6b70932
feat: structured interview scope phase with SDK MCP tools
lunelson a9468e7
refactor: address ln-review findings for slice 4
lunelson 2ada68c
docs: ln-sync — reconcile SPEC.md and PLAN.md after slice 4
lunelson 013e2a2
add api-perplexity skill for Perplexity Search API retrieval
lunelson bd48158
spec/plan: record D22 (TanStack Query + SSE-driven invalidation for o…
lunelson a36f0d5
spec: add D22 oracle coverage — post-commit ordering, data-part encod…
lunelson abb5700
spec/plan: record D23-D25 (parts-based persistence, Data Parts, conte…
lunelson ba345f7
spec/plan: oracle design for D23-D25 — I17-I19, parts/scalar blind spot
lunelson File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,193 @@ | ||
| --- | ||
| name: api-perplexity | ||
| description: "Search the live web via Perplexity Search API. Use when you need current documentation, release notes, vendor pages, news, domain-constrained web search, or date/recency filtering. Not for local codebase search or stable docs already in context." | ||
| --- | ||
|
|
||
| # Perplexity Search API | ||
|
|
||
| Thin retrieval tool for live web search. The agent plans queries and interprets | ||
| results; this skill handles raw retrieval only. | ||
|
|
||
| **Endpoint:** `POST https://api.perplexity.ai/search` | ||
| **Auth:** `Authorization: Bearer $PERPLEXITY_API_KEY` | ||
| **Pricing:** $5.00 per 1K requests. No token-based charges. | ||
|
|
||
| ## When to Use | ||
|
|
||
| - Current docs, changelogs, release notes | ||
| - Vendor/library documentation lookup | ||
| - News and time-sensitive information | ||
| - Domain-constrained retrieval (e.g. only official docs sites) | ||
| - Date-filtered search (published/updated before or after a date) | ||
|
|
||
| ## When Not to Use | ||
|
|
||
| - Local codebase search (use Grep/finder) | ||
| - Stable docs already in context | ||
| - Page interaction or scraping (use browser tools) | ||
| - LLM-generated summaries (use Sonar API instead) | ||
|
|
||
| ## Request Schema | ||
|
|
||
| All fields except `query` are optional. | ||
|
|
||
| | Field | Type | Default | Notes | | ||
| |---|---|---|---| | ||
| | `query` | `string \| string[]` | — | **Required.** Up to 5 queries for batch. | | ||
| | `max_results` | `integer` | `10` | Range: 1–20 | | ||
| | `max_tokens` | `integer` | `10000` | Total content budget across all results | | ||
| | `max_tokens_per_page` | `integer` | `4096` | Per-page content extraction limit | | ||
| | `country` | `string` | — | ISO 3166-1 alpha-2 (e.g. `"US"`, `"DE"`) | | ||
| | `search_language_filter` | `string[]` | — | ISO 639-1 codes, max 20 (e.g. `["en"]`) | | ||
| | `search_domain_filter` | `string[]` | — | Max 20. Prefix `"-"` to deny (see below) | | ||
| | `search_recency_filter` | `string` | — | `"hour"` `"day"` `"week"` `"month"` `"year"` | | ||
| | `search_after_date_filter` | `string` | — | `MM/DD/YYYY` — results published after | | ||
| | `search_before_date_filter` | `string` | — | `MM/DD/YYYY` — results published before | | ||
| | `last_updated_after_filter` | `string` | — | `MM/DD/YYYY` — results updated after | | ||
| | `last_updated_before_filter` | `string` | — | `MM/DD/YYYY` — results updated before | | ||
|
|
||
| ### Domain Filter Rules | ||
|
|
||
| One array, two modes. **Cannot mix allow and deny in the same request.** | ||
|
|
||
| ```json | ||
| // Allowlist — only these domains | ||
| "search_domain_filter": ["docs.stripe.com", "stripe.com"] | ||
|
|
||
| // Denylist — exclude these domains (prefix with "-") | ||
| "search_domain_filter": ["-pinterest.com", "-reddit.com", "-quora.com"] | ||
| ``` | ||
|
|
||
| ## Response Schema | ||
|
|
||
| ```ts | ||
| { | ||
| id: string | ||
| server_time: string | null | ||
| results: Array<{ | ||
| title: string // page title | ||
| url: string // page URL | ||
| snippet: string // extracted content | ||
| date: string | null // publication date | ||
| last_updated: string | null | ||
| }> | ||
| } | ||
| ``` | ||
|
|
||
| **There is no `score` field.** Results are ranked by relevance — use list order | ||
| as rank. For single queries, `results` is a flat list. For multi-query batch, | ||
| results are grouped per query in submission order. | ||
|
|
||
| ## Query Strategy | ||
|
|
||
| 1. **Start narrow.** One precise query beats a broad one. | ||
| 2. **Use domain filters before broadening query text.** Constrain sources first. | ||
| 3. **Apply recency only when freshness matters.** Suppresses good evergreen content. | ||
| 4. **Use low token budgets for quick lookups.** `max_tokens_per_page: 512` for headlines. | ||
| 5. **Batch only for parallel angles.** Not for rephrasing the same question. | ||
| 6. **Prefer 3–5 results** unless broad recall is needed. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Basic search | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": "drizzle orm sqlite migration guide", | ||
| "max_results": 5 | ||
| }' | ||
| ``` | ||
|
|
||
| ### Domain-constrained with recency | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": "breaking changes v5", | ||
| "max_results": 5, | ||
| "search_domain_filter": ["docs.stripe.com"], | ||
| "search_recency_filter": "month" | ||
| }' | ||
| ``` | ||
|
|
||
| ### Date-filtered search | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": "vite 7 release", | ||
| "max_results": 5, | ||
| "search_after_date_filter": "01/01/2026" | ||
| }' | ||
| ``` | ||
|
|
||
| ### Lightweight extraction | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": "latest AI developments", | ||
| "max_results": 3, | ||
| "max_tokens": 3000, | ||
| "max_tokens_per_page": 512 | ||
| }' | ||
| ``` | ||
|
|
||
| ### Multi-query batch | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": [ | ||
| "temporal workflow determinism typescript", | ||
| "temporal activity heartbeat pattern" | ||
| ], | ||
| "max_results": 5, | ||
| "search_domain_filter": ["docs.temporal.io"] | ||
| }' | ||
| ``` | ||
|
|
||
| ### Denylist with language filter | ||
|
|
||
| ```bash | ||
| curl -X POST https://api.perplexity.ai/search \ | ||
| -H "Authorization: Bearer $PERPLEXITY_API_KEY" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "query": "react server components best practices", | ||
| "max_results": 5, | ||
| "search_domain_filter": ["-pinterest.com", "-w3schools.com"], | ||
| "search_language_filter": ["en"] | ||
| }' | ||
| ``` | ||
|
|
||
| ## Guardrails | ||
|
|
||
| - **Date format is `MM/DD/YYYY`** — not ISO 8601. | ||
| - **Domain filter is one array** — allow or deny, not both simultaneously. | ||
| - **No score field** — trust result order; do not threshold on numeric scores. | ||
| - **`max_tokens` is content budget, not pricing** — controls how much text is extracted, not cost. | ||
| - **Batch limit is 5 queries** per request. | ||
| - **Deduplicate by URL** when combining results from multiple searches. | ||
| - **Cite sources** — include URLs in any answer derived from search results. | ||
|
|
||
| ## Suggested Workflow | ||
|
|
||
| 1. Decide if the task needs live web retrieval (current info, external docs). | ||
| 2. Formulate 1–3 focused queries. Prefer domain filters over broad text. | ||
| 3. Run search with appropriate `max_results` and token budgets. | ||
| 4. Inspect top results — check URL relevance and snippet quality. | ||
| 5. If results are thin, refine: adjust query, broaden domains, relax recency. | ||
| 6. Synthesize answer from retained evidence. Cite URLs. Flag uncertainty when | ||
| only one source supports a claim. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PR metadata: the PR title doesn’t follow the repo naming rule for issue-scoped PRs (expected
FE-554: …per (Rule: AGENTS.md)); consider aligning it so stack/issue traceability stays consistent.Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.