Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

feat(perplexity): migrate Sonar integration to the Agent API (#1019)

Sk35ff7b054998
diff --git a/CONFIGURATION.md b/CONFIGURATION.md
index 33143f91..4e2c6e36 100644
--- a/CONFIGURATION.md
+++ b/CONFIGURATION.md
@@ -160,7 +160,7 @@ python3 skills/last30days/scripts/last30days.py "MCP servers" \
| Bluesky | `BSKY_HANDLE` + `BSKY_APP_PASSWORD` | Bluesky items | yes (app password at bsky.app) |
| TruthSocial | `TRUTHSOCIAL_TOKEN` | TruthSocial items | yes |
| Web search | one of: `BRAVE_API_KEY`, `EXA_API_KEY`, `SERPER_API_KEY`, `PARALLEL_API_KEY` | `--auto-resolve` and Step 2 supplements | Brave has a free tier; native WebSearch on Claude Code / Codex / Gemini works as a fallback |
-| Perplexity Sonar / Search API / Deep Research | `PERPLEXITY_API_KEY` (preferred) or `OPENROUTER_API_KEY` (Sonar fallback) | `INCLUDE_SOURCES=perplexity`; `--deep-research` flag (~$0.90/query) | no |
+| Perplexity Agent API / Search API / Deep Research | `PERPLEXITY_API_KEY` (preferred) or `OPENROUTER_API_KEY` (Sonar fallback) | `INCLUDE_SOURCES=perplexity`; `--deep-research` uses background Agent API with a direct key or synchronous Sonar through OpenRouter | no |
| Caption-free transcription | `GROQ_API_KEY` (free tier, preferred) or `OPENAI_API_KEY` (paid backstop); requires `ffmpeg` | Whisper transcription for audio/video without captions (groundwork: module shipped, not yet auto-invoked by the engine) | Groq free tier is generous; needs ffmpeg installed |
| Jobs / careers pages | none for public ATS pages; web backend improves fallback discovery | `--hiring-signals` and strong Hiring Signals in standard company reports | yes |
| Apify (alternate scraper) | `APIFY_API_TOKEN` | fallback for Reddit/TikTok/Instagram when ScrapeCreators is exhausted | yes (limited) |
@@ -191,8 +191,10 @@ INCLUDE_SOURCES=tiktok,instagram
# Add perplexity to INCLUDE_SOURCES when you want the paid Perplexity source.
# PERPLEXITY_API_KEY=<your-perplexity-key>
# INCLUDE_SOURCES=tiktok,instagram,perplexity
-# LAST30DAYS_PERPLEXITY_MODE=sonar # sonar | search | both
-# LAST30DAYS_PERPLEXITY_MODEL=sonar-pro # sonar | sonar-pro | sonar-reasoning-pro
+# LAST30DAYS_PERPLEXITY_MODE=agent # agent | search | both; sonar is a legacy alias
+# LAST30DAYS_PERPLEXITY_AGENT_MODEL=perplexity/sonar
+# LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS=5
+# LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS=4096 # required for anthropic/*
# X authentication (one option only)
AUTH_TOKEN=<your-auth-token>
@@ -220,33 +222,44 @@ After editing: `chmod 600 ~/.config/last30days/.env` (or `chmod 600 .claude/last
### Perplexity source modes
-Perplexity is a paid opt-in source. A direct `PERPLEXITY_API_KEY` unlocks first-party Perplexity features. `OPENROUTER_API_KEY` remains a Sonar compatibility fallback only; Perplexity Search API and async Deep Research call Perplexity directly.
+Perplexity is a paid opt-in source. A direct `PERPLEXITY_API_KEY` enables the Agent API, Search API, and background Deep Research. Existing `OPENROUTER_API_KEY` installs remain compatible through synchronous Sonar: `perplexity/sonar-pro` for normal synthesis and `perplexity/sonar-deep-research` for `--deep-research`. Search API and Agent API features still require the direct key.
`LAST30DAYS_PERPLEXITY_MODE` controls normal `perplexity` source runs:
| Value | Behavior | Calls |
|---|---|---|
-| `sonar` (default) | Sonar synthesis plus citations. | one Sonar call |
-| `search` | Raw ranked Search API rows; best when you want source aggregation over prose. | one Search API call |
-| `both` | Sonar synthesis plus raw ranked Search API rows, deduped by URL. | one Search API call and one Sonar call |
+| `agent` (default) | Direct key: controlled Agent API synthesis with required `web_search`. OpenRouter-only: synchronous Sonar fallback. | at most one paid synthesis call per last30days run |
+| `sonar` | Direct key: deprecated alias for `agent`. OpenRouter-only: synchronous Sonar fallback. | at most one paid synthesis call per last30days run |
+| `search` | Direct key: raw ranked Search API rows. OpenRouter-only: falls back to synchronous Sonar. | at most one paid call per last30days run |
+| `both` | Direct key: Agent synthesis plus Search rows. OpenRouter-only: falls back to synchronous Sonar. | direct: at most two paid calls; OpenRouter: at most one |
-`--deep-research` ignores `LAST30DAYS_PERPLEXITY_MODE` and uses `sonar-deep-research`. With `PERPLEXITY_API_KEY`, it submits to Perplexity's async Sonar endpoint and polls with a hard wall-clock timeout. The async request uses a deterministic idempotency key derived from the request body. If the request is still running at timeout, fails remotely, or polling hits a transport/rate-limit error after the async id exists, the raw artifact records the async request id, idempotency key, last status, lifecycle timestamps returned by Perplexity, poll count, and timeout/error fields so you can inspect or resume by id outside the run. With only `OPENROUTER_API_KEY`, it keeps the OpenRouter synchronous fallback.
+With a direct key, normal `agent` mode uses the controlled `last30days-controlled-web-search/v1` profile: `perplexity/sonar`, a bounded `max_steps`, a local instruction, and only the configured `web_search` tool. It forces that tool for citation-critical grounding. It does not enable sandbox, file, finance, MCP, or function tools. OpenRouter fallback keeps the older OpenAI-compatible Sonar request and does not claim Agent API controls.
+
+The engine routes every normal Perplexity mode through one whole-topic planner subquery per command, including competitor fanout, and does not repeat it during thin-source retries. A generic source-fetch override cannot raise this paid-call cap.
+
+`LAST30DAYS_PERPLEXITY_AGENT_PRESET` is a separate explicit opt-in for a mutable Perplexity preset (`fast`, `low`, `medium`, or `high`). Presets can change their model, prompt, tools, cost, and output behavior. The engine still supplies its configured `web_search` tool so date, domain, location, result-count, and context constraints merge with the preset; other preset tools can remain enabled. Do not set this variable when you need the controlled profile. The engine never selects a preset automatically for normal runs.
+
+`--deep-research` requires a normal positional topic and ignores `LAST30DAYS_PERPLEXITY_MODE`. With a direct key it starts at most one Agent API background run with the explicit dynamic `high` preset. With only OpenRouter it preserves the older synchronous `perplexity/sonar-deep-research` fallback. It cannot be combined with discovery, drill, cached-only, competitor, or vs-mode. This is a separate paid action. The engine caps it at one planner subquery and does not repeat it during thin-source retries. Direct background runs merge the configured `web_search` constraints with the preset, but the provider controls its other tools and can change them. A local timeout stops waiting but does not stop a direct remote run. Direct artifacts retain the served model, response ID, provider status, incomplete reason, poll count, timeout, and safe error metadata; OpenRouter artifacts retain the served model, response ID, usage, and citation count. Neither stores request headers or raw tool traces.
Perplexity-specific env vars:
| Env var | Default | Applies to | Notes |
|---|---|---|---|
-| `LAST30DAYS_PERPLEXITY_MODE` | `sonar` | normal Perplexity source runs | `sonar`, `search`, or `both`; `search` and `both` require `PERPLEXITY_API_KEY`. |
-| `LAST30DAYS_PERPLEXITY_MODEL` | `sonar-pro` | direct Sonar only | Supported: `sonar`, `sonar-pro`, `sonar-reasoning-pro`. `--deep-research` forces `sonar-deep-research`. |
-| `LAST30DAYS_PERPLEXITY_MAX_RESULTS` | `10` | Search API | Clamped to Perplexity's 1..20 range. |
-| `LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE` | provider default | Search API | `low`, `medium`, or `high`; omitted unless set. |
-| `LAST30DAYS_PERPLEXITY_SEARCH_MODE` | provider default | direct Sonar | `web`, `academic`, or `sec`. |
-| `LAST30DAYS_PERPLEXITY_DOMAIN_FILTER` | unset | Search API and direct Sonar | Comma-separated domains, max 20. |
-| `LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER` | unset | Search API and direct Sonar | Comma-separated ISO 639-1 language codes, max 20. |
-| `LAST30DAYS_PERPLEXITY_COUNTRY` | unset | Search API | Two-letter country code such as `US`. |
-| `LAST30DAYS_PERPLEXITY_RECENCY_FILTER` | unset | Search API and direct Sonar | `hour`, `day`, `week`, `month`, or `year`. |
-| `LAST30DAYS_PERPLEXITY_REASONING_EFFORT` | unset | direct Sonar | `minimal`, `low`, `medium`, or `high`. |
-| `LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS` | `600` | direct async Deep Research | Wall-clock polling deadline. |
+| `LAST30DAYS_PERPLEXITY_MODE` | `agent` | normal Perplexity source runs | `agent`, `search`, or `both`; `sonar` remains a deprecated alias for `agent`. |
+| `LAST30DAYS_PERPLEXITY_AGENT_MODEL` | `perplexity/sonar` | controlled Agent profile | Explicit Agent model for normal synthesis. |
+| `LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS` | `5` | controlled Agent profile | Clamped to the last30days safety range 1..15. |
+| `LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS` | `4096` for `anthropic/*` models | controlled Agent profile | Required for explicit Anthropic models; clamped to the last30days safety range 1..32768. |
+| `LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS` | `120` | controlled Agent profile | Synchronous request timeout, clamped to 1..600 seconds. |
+| `LAST30DAYS_PERPLEXITY_AGENT_PRESET` | unset | normal Agent runs | Explicit mutable preset only: `fast`, `low`, `medium`, or `high`. It replaces the controlled profile for that run. |
+| `LAST30DAYS_PERPLEXITY_MAX_RESULTS` | `10` | Search API and all Agent `web_search` requests | Clamped to 1..20. |
+| `LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE` | provider default | Search API and all Agent `web_search` requests | `low`, `medium`, or `high`; omitted unless set. |
+| `LAST30DAYS_PERPLEXITY_DOMAIN_FILTER` | unset | Search API and all Agent `web_search` requests | Comma-separated domains, max 20. |
+| `LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER` | unset | Search API only | Comma-separated ISO 639-1 language codes. Agent API has no equivalent. |
+| `LAST30DAYS_PERPLEXITY_COUNTRY` | unset | Search API and all Agent `web_search` requests | Two-letter country code such as `US`. |
+| `LAST30DAYS_PERPLEXITY_RECENCY_FILTER` | unset | Search API and all Agent `web_search` requests | `hour`, `day`, `week`, `month`, or `year`; exact date filters take precedence. |
+| `LAST30DAYS_PERPLEXITY_REASONING_EFFORT` | unset | controlled Agent profile | `minimal`, `low`, `medium`, or `high`. |
+| `LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS` | `600` | direct Agent API background Deep Research | Wall-clock polling deadline; remote work can continue after a local timeout. OpenRouter fallback is synchronous. |
+| `LAST30DAYS_PERPLEXITY_MODEL` / `LAST30DAYS_PERPLEXITY_SEARCH_MODE` | unset | legacy Sonar config | Retained for config-file compatibility. They do not select an Agent API preset or search mode. |
### Encrypted credential sources (Keychain / pass)
@@ -358,7 +371,7 @@ An explicit `--register` wins over `LAST30DAYS_REGISTER`; the environment/config
1. **Gemini** - `GOOGLE_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_GENAI_API_KEY`
2. **OpenAI** - `OPENAI_API_KEY` only. Codex ChatGPT auth at `~/.codex/auth.json` is intentionally not used as an OpenAI provider credential.
3. **xAI** - `XAI_API_KEY`
-4. **OpenRouter** - `OPENROUTER_API_KEY` (Sonar fallback for the Perplexity source / `--deep-research`; also usable as a reasoning provider)
+4. **OpenRouter** - `OPENROUTER_API_KEY` (reasoning provider, auto-resolve, and synchronous Sonar fallback for the Perplexity source)
5. **Local / deterministic** - always available, lowest quality
When you invoke `/last30days` from Claude Code, Codex, or Gemini, the host model **is** the reasoning provider for plan + synthesis - you don't need any of the keys above unless you also run the script headlessly (cron, CI, watchlist).
diff --git a/README.de.md b/README.de.md
index 2d47fd1a..923f04e7 100644
--- a/README.de.md
+++ b/README.de.md
@@ -81,7 +81,7 @@ Wenn du dich mit einem CEO triffst: Hast du alle Tweets und YouTube-Transkripte
| **Pinterest** | Visuelle Entdeckung. Pins, gespeicherte Beiträge und Kommentare zu Produkten und Ideen. |
| **Xiaohongshu (RED)** | Chinesische Signale zu Lifestyle, Produkten und Creators. Wird ausdrücklich mit `--search xhs` angefordert, wenn lokal ein eingeloggtes x-mcp-Browser-Plugin oder ein `xiaohongshu-mcp`-Dienst läuft. |
| **Bluesky** | Die dezentrale soziale Ebene. AT-Protocol-Beiträge aus der Abwanderung nach Twitter. |
-| **Perplexity** | Belegte Sonar-Synthese, Rohtreffer der Search API und Deep Research. |
+| **Perplexity** | Gesteuerte Agent-API-Synthese, OpenRouter-Sonar-Fallback, Rohtreffer der Search API und explizite Deep Research. |
| **Web** | Die redaktionelle Berichterstattung, die Blog-Vergleiche. Ein Signal von vielen, nicht das einzige. |
Die Community steuert laufend weitere bei. Truth Social und andere Nischenquellen stecken bereits in der Engine, weitere folgen.
@@ -295,7 +295,7 @@ Diese Plattformen haben nichts miteinander zu tun. X weiß nicht, was Reddit den
| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube-Kommentare | Ein ScrapeCreators-Schlüssel | 10.000 kostenlose Aufrufe, danach nutzungsabhängig |
| Xiaohongshu (RED) | Ein eingeloggtes x-mcp-Browser-Plugin oder einen `xiaohongshu-mcp`-Dienst laufen lassen und die Quelle mit `--search xhs` pro Durchlauf oder `INCLUDE_SOURCES=xiaohongshu` in `.env` zuschalten; last30days probiert automatisch `http://localhost:18060` und danach `http://host.docker.internal:18060`, oder du setzt `XIAOHONGSHU_API_BASE` für eine eigene URL | Kein last30days-API-Schlüssel nötig; hängt von deinem lokalen Browser-Session-Dienst ab |
| DripStack (Premium-Finanznewsletter) | Zuschaltbar: `--search dripstack` pro Durchlauf, oder `INCLUDE_SOURCES=dripstack` in `.env` | Kein Schlüssel; kostenlose öffentliche Such-API |
-| Perplexity Sonar / Search API / Deep Research | Ein Perplexity-Schlüssel, oder ein OpenRouter-Schlüssel als Sonar-Fallback | Nutzungsabhängig |
+| Perplexity Agent API / Search API / Deep Research | Ein Perplexity-Schlüssel, oder ein OpenRouter-Schlüssel als Sonar-Fallback | Nutzungsabhängig; ein direkter Schlüssel aktiviert Agent API und Deep Research im Hintergrund |
| Websuche | Ein Brave-Search-Schlüssel | 2.000 kostenlose Anfragen pro Monat |
### macOS Keychain (optional)
diff --git a/README.es.md b/README.es.md
index deae6b7f..9e3b0ae4 100644
--- a/README.es.md
+++ b/README.es.md
@@ -81,7 +81,7 @@ Si te vas a reunir con un CEO, ¿te has leído todos sus tuits y todas sus trans
| **Pinterest** | Descubrimiento visual. Pines, guardados y comentarios sobre productos e ideas. |
| **Xiaohongshu (RED)** | Señales chinas sobre estilo de vida, productos y creadores. Se pide de forma explícita con `--search xhs` cuando tienes corriendo en local un plugin de navegador x-mcp con sesión iniciada o un servicio `xiaohongshu-mcp`. |
| **Bluesky** | La capa social descentralizada. Publicaciones de AT Protocol surgidas de la migración posterior a Twitter. |
-| **Perplexity** | La síntesis fundamentada de Sonar, los resultados en bruto de la Search API y Deep Research. |
+| **Perplexity** | Síntesis controlada con la Agent API, alternativa Sonar mediante OpenRouter, resultados en bruto de la Search API y Deep Research explícita. |
| **Web** | La cobertura editorial, las comparativas de los blogs. Una señal entre muchas, no la única. |
La comunidad no para de sumar fuentes. Truth Social y otras fuentes de nicho ya están en el motor, y vienen más.
@@ -295,7 +295,7 @@ Estas plataformas no tienen ninguna relación entre sí. X no sabe lo que piensa
| TikTok + Instagram + Threads + Pinterest + LinkedIn + comentarios de YouTube | Una clave de ScrapeCreators | 10.000 llamadas gratis y luego pago por uso |
| Xiaohongshu (RED) | Ten corriendo un plugin de navegador x-mcp con sesión iniciada o un servicio `xiaohongshu-mcp`, y activa la fuente con `--search xhs` por ejecución o con `INCLUDE_SOURCES=xiaohongshu` en `.env`; last30days prueba automáticamente `http://localhost:18060` y después `http://host.docker.internal:18060`, o usa `XIAOHONGSHU_API_BASE` para una URL propia | No hace falta clave de API de last30days; depende de tu servicio local de sesión de navegador |
| DripStack (boletines financieros premium) | Opcional: `--search dripstack` por ejecución, o `INCLUDE_SOURCES=dripstack` en `.env` | Sin clave; API de búsqueda pública y gratuita |
-| Perplexity Sonar / Search API / Deep Research | Una clave de Perplexity, o una clave de OpenRouter como alternativa para Sonar | Pago por uso |
+| Perplexity Agent API / Search API / Deep Research | Una clave de Perplexity, o una clave de OpenRouter como alternativa para Sonar | Pago por uso; una clave directa habilita la Agent API y Deep Research en segundo plano |
| Búsqueda web | Una clave de Brave Search | 2.000 consultas gratis al mes |
### Llavero de macOS (opcional)
diff --git a/README.fr.md b/README.fr.md
index 1700699e..9bb6b320 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -81,7 +81,7 @@ Si vous rencontrez un PDG, avez-vous lu tous ses tweets et toutes ses transcript
| **Pinterest** | La découverte visuelle. Épingles, enregistrements et commentaires sur des produits et des idées. |
| **Xiaohongshu (RED)** | Les signaux chinois sur le lifestyle, les produits et les créateurs. À demander explicitement avec `--search xhs` quand un plugin de navigateur x-mcp connecté ou un service `xiaohongshu-mcp` tourne en local. |
| **Bluesky** | La couche sociale décentralisée. Les posts AT Protocol issus de la migration post-Twitter. |
-| **Perplexity** | La synthèse Sonar sourcée, les résultats bruts de la Search API et Deep Research. |
+| **Perplexity** | Une synthèse contrôlée avec l’Agent API, un repli Sonar via OpenRouter, les résultats bruts de la Search API et Deep Research explicite. |
| **Web** | La couverture éditoriale, les comparatifs de blogs. Un signal parmi d'autres, pas le seul. |
La communauté en ajoute sans cesse. Truth Social et d'autres sources de niche sont déjà dans le moteur, et d'autres arrivent.
@@ -295,7 +295,7 @@ Ces plateformes n'ont aucune relation entre elles. X ignore ce que pense Reddit.
| TikTok + Instagram + Threads + Pinterest + LinkedIn + commentaires YouTube | Une clé ScrapeCreators | 10 000 appels gratuits, puis paiement à l'usage |
| Xiaohongshu (RED) | Faites tourner un plugin de navigateur x-mcp connecté ou un service `xiaohongshu-mcp`, puis activez la source avec `--search xhs` pour une exécution ou `INCLUDE_SOURCES=xiaohongshu` dans `.env` ; last30days teste automatiquement `http://localhost:18060` puis `http://host.docker.internal:18060`, ou utilisez `XIAOHONGSHU_API_BASE` pour une URL personnalisée | Aucune clé API last30days ; dépend de votre service local de session de navigateur |
| DripStack (newsletters financières premium) | Sur activation : `--search dripstack` pour une exécution, ou `INCLUDE_SOURCES=dripstack` dans `.env` | Aucune clé ; API de recherche publique et gratuite |
-| Perplexity Sonar / Search API / Deep Research | Une clé Perplexity, ou une clé OpenRouter en repli pour Sonar | Paiement à l'usage |
+| Perplexity Agent API / Search API / Deep Research | Une clé Perplexity, ou une clé OpenRouter en repli pour Sonar | Paiement à l'usage ; une clé directe active l’Agent API et Deep Research en arrière-plan |
| Recherche web | Une clé Brave Search | 2 000 requêtes gratuites par mois |
### Trousseau macOS (facultatif)
diff --git a/README.ja.md b/README.ja.md
index f6516acb..696b3429 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -81,7 +81,7 @@ CEOと会うとして、直近30日間のツイートと YouTube の文字起こ
| **Pinterest** | ビジュアル起点の発見。プロダクトやアイデアに対するピン・保存・コメント。 |
| **Xiaohongshu(RED)** | 中国のライフスタイル・プロダクト・クリエイターのシグナル。ログイン済みの x-mcp ブラウザプラグイン、または `xiaohongshu-mcp` サービスがローカルで動いているときに、`--search xhs` で明示的に指定して使います。 |
| **Bluesky** | 分散型のソーシャル層。Twitter 以後の移住で生まれた AT Protocol の投稿です。 |
-| **Perplexity** | 根拠付きの Sonar による統合、Search API の生の結果、そして Deep Research。 |
+| **Perplexity** | 制御された Agent API の統合、OpenRouter の Sonar フォールバック、Search API の生の結果、明示的な Deep Research。 |
| **Web** | 編集記事や、ブログの比較記事。数あるシグナルの1つであって、唯一のものではありません。 |
コミュニティが今も情報源を増やし続けています。Truth Social をはじめとするニッチな情報源もすでにエンジンに入っていて、さらに追加予定です。
@@ -294,7 +294,7 @@ Reddit(コメント込み)、Hacker News、Polymarket、GitHub はすぐに使
| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube のコメント | ScrapeCreators のキー | 1万リクエストまで無料、以降は従量課金 |
| Xiaohongshu(RED) | ログイン済みの x-mcp ブラウザプラグインか `xiaohongshu-mcp` サービスを動かしたうえで、実行ごとに `--search xhs` を付けるか `.env` に `INCLUDE_SOURCES=xiaohongshu` を設定して有効化します。last30days は `http://localhost:18060`、次に `http://host.docker.internal:18060` の順に自動で接続を試し、独自のURLを使う場合は `XIAOHONGSHU_API_BASE` を指定します | last30days 側のAPIキーは不要。ローカルのブラウザセッションのサービス次第です |
| DripStack(有料の金融ニュースレター) | 任意で有効化: 実行ごとに `--search dripstack`、または `.env` に `INCLUDE_SOURCES=dripstack` | キー不要。無料の公開検索APIを使います |
-| Perplexity Sonar / Search API / Deep Research | Perplexity のキー、または Sonar の代替として OpenRouter のキー | 従量課金 |
+| Perplexity Agent API / Search API / Deep Research | Perplexity のキー、または Sonar の代替として OpenRouter のキー | 従量課金。直接キーで Agent API とバックグラウンド Deep Research が有効になります |
| ウェブ検索 | Brave Search のキー | 月2,000クエリまで無料 |
### macOS のキーチェーン(任意)
diff --git a/README.md b/README.md
index b2e656a5..25410cfc 100644
--- a/README.md
+++ b/README.md
@@ -81,7 +81,7 @@ If you're meeting with a CEO, have you read all their tweets and YouTube transcr
| **Pinterest** | Visual discovery. Pins, saves, and comments on products and ideas. |
| **Xiaohongshu (RED)** | Chinese lifestyle, product, and creator signals. Requested explicitly with `--search xhs` when a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service is running locally. |
| **Bluesky** | The decentralized social layer. AT Protocol posts from the post-Twitter migration. |
-| **Perplexity** | Grounded Sonar synthesis, raw Search API rows, and Deep Research. |
+| **Perplexity** | Controlled Agent API synthesis, OpenRouter Sonar fallback, raw Search API rows, and explicit Deep Research. |
| **Web** | The editorial coverage, the blog comparisons. One signal of many, not the only one. |
Community contributors keep adding more. Truth Social and other niche sources are in the engine with more on the way.
@@ -294,7 +294,7 @@ These platforms don't have relationships with each other. X doesn't know what Re
| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube comments | ScrapeCreators key | 10,000 free calls, then PAYG |
| Xiaohongshu (RED) | Run a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service and opt in with `--search xhs` per run or `INCLUDE_SOURCES=xiaohongshu` in `.env`; last30days auto-probes `http://localhost:18060` then `http://host.docker.internal:18060`, or use `XIAOHONGSHU_API_BASE` for a custom URL | No last30days API key; depends on your local browser-session service |
| DripStack (premium financial newsletters) | Opt-in: `--search dripstack` per run, or `INCLUDE_SOURCES=dripstack` in `.env` | No key; free public search API |
-| Perplexity Sonar / Search API / Deep Research | Perplexity key, or OpenRouter key as Sonar fallback | Pay as you go |
+| Perplexity Agent API / Search API / Deep Research | Perplexity key, or OpenRouter key as Sonar fallback | Pay as you go; a direct key enables Agent API and background Deep Research |
| Web search | Brave Search key | 2,000 free queries/month |
### macOS Keychain (optional)
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 7a79fceb..344ea594 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -81,7 +81,7 @@ Se você vai se reunir com um CEO, já leu todos os tweets e todas as transcriç
| **Pinterest** | Descoberta visual. Pins, itens salvos e comentários sobre produtos e ideias. |
| **Xiaohongshu (RED)** | Sinais chineses sobre estilo de vida, produtos e criadores. É pedido explicitamente com `--search xhs` quando há um plugin de navegador x-mcp logado ou um serviço `xiaohongshu-mcp` rodando localmente. |
| **Bluesky** | A camada social descentralizada. Publicações do AT Protocol vindas da migração pós-Twitter. |
-| **Perplexity** | A síntese fundamentada do Sonar, os resultados brutos da Search API e o Deep Research. |
+| **Perplexity** | Síntese controlada da Agent API, alternativa Sonar via OpenRouter, resultados brutos da Search API e Deep Research explícito. |
| **Web** | A cobertura editorial, as comparações de blog. Um sinal entre muitos, não o único. |
A comunidade não para de acrescentar fontes. Truth Social e outras fontes de nicho já estão no motor, e vêm mais por aí.
@@ -295,7 +295,7 @@ Essas plataformas não têm relação nenhuma entre si. O X não sabe o que o Re
| TikTok + Instagram + Threads + Pinterest + LinkedIn + comentários do YouTube | Uma chave do ScrapeCreators | 10.000 chamadas gratuitas e depois pagamento por uso |
| Xiaohongshu (RED) | Deixe rodando um plugin de navegador x-mcp logado ou um serviço `xiaohongshu-mcp` e habilite a fonte com `--search xhs` por execução ou com `INCLUDE_SOURCES=xiaohongshu` no `.env`; o last30days testa automaticamente `http://localhost:18060` e depois `http://host.docker.internal:18060`, ou use `XIAOHONGSHU_API_BASE` para uma URL própria | Não precisa de chave de API do last30days; depende do seu serviço local de sessão de navegador |
| DripStack (newsletters financeiras premium) | Opcional: `--search dripstack` por execução, ou `INCLUDE_SOURCES=dripstack` no `.env` | Sem chave; API de busca pública e gratuita |
-| Perplexity Sonar / Search API / Deep Research | Uma chave do Perplexity, ou uma chave do OpenRouter como alternativa para o Sonar | Pagamento por uso |
+| Perplexity Agent API / Search API / Deep Research | Uma chave do Perplexity, ou uma chave do OpenRouter como alternativa para o Sonar | Pagamento por uso; uma chave direta ativa a Agent API e o Deep Research em segundo plano |
| Busca na web | Uma chave do Brave Search | 2.000 consultas gratuitas por mês |
### Keychain do macOS (opcional)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index d8010894..a1e98b07 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -84,7 +84,7 @@ Google 聚合编辑选出的内容,`/last30days` 搜索真实的人。
| **Pinterest** | 视觉发现:围绕产品和创意的 Pin、收藏与评论。 |
| **小红书(RED)** | 来自中国生活方式、产品和创作者的信号。当本机运行已登录的 x-mcp 浏览器插件或 `xiaohongshu-mcp` 服务时,通过 `--search xhs` 显式启用。 |
| **Bluesky** | 去中心化的社交内容层,搜索 Twitter 用户迁移后产生的 AT Protocol 帖子。 |
-| **Perplexity** | 基于来源的 Sonar 综合结果、原始 Search API 数据和 Deep Research。 |
+| **Perplexity** | 受控 Agent API 综合结果、OpenRouter Sonar 回退、原始 Search API 数据和显式 Deep Research。 |
| **Web** | 编辑报道和博客对比。它只是众多信号之一,而不是唯一来源。 |
社区贡献者仍在不断加入更多平台。Truth Social 等垂直来源已经进入引擎,更多来源也在路上。
@@ -293,7 +293,7 @@ Reddit(含评论)、Hacker News、Polymarket 和 GitHub 无需任何配置
| TikTok + Instagram + Threads + Pinterest + LinkedIn + YouTube 评论 | ScrapeCreators 密钥 | 前 10,000 次调用免费,之后按量付费 |
| 小红书(RED) | 运行已登录的 x-mcp 浏览器插件或 `xiaohongshu-mcp` 服务,并在单次运行中通过 `--search xhs` 启用,或在 `.env` 中设置 `INCLUDE_SOURCES=xiaohongshu`;last30days 会依次自动探测 `http://localhost:18060` 和 `http://host.docker.internal:18060`,也可通过 `XIAOHONGSHU_API_BASE` 指定自定义地址 | last30days 不需要 API 密钥;依赖本地浏览器会话服务 |
| DripStack(付费金融通讯) | 每次运行通过 `--search dripstack` 启用,或在 `.env` 中设置 `INCLUDE_SOURCES=dripstack` | 无需密钥;公共搜索 API 免费 |
-| Perplexity Sonar / Search API / Deep Research | Perplexity 密钥,或作为 Sonar 回退方案的 OpenRouter 密钥 | 按量付费 |
+| Perplexity Agent API / Search API / Deep Research | Perplexity 密钥,或作为 Sonar 回退方案的 OpenRouter 密钥 | 按量付费;直接密钥启用 Agent API 和后台 Deep Research |
| Web 搜索 | Brave Search 密钥 | 每月 2,000 次免费查询 |
### macOS Keychain(可选)
diff --git a/changelog.d/+perplexity-agent-api.changed.md b/changelog.d/+perplexity-agent-api.changed.md
new file mode 100644
index 00000000..5c0eee55
--- /dev/null
+++ b/changelog.d/+perplexity-agent-api.changed.md
@@ -0,0 +1 @@
+Direct Perplexity keys now use the Agent API for controlled synthesis and explicit Deep Research. Controlled synthesis forces grounded web search and supports explicit Anthropic Agent models with a bounded output budget, while Deep Research starts at most one paid background run per command and preserves safe polling and incomplete-run receipts. Existing OpenRouter-only installs keep the synchronous Sonar and Sonar Deep Research fallbacks.
diff --git a/skills/last30days/SKILL.md b/skills/last30days/SKILL.md
index 3040fbc8..8075423a 100644
--- a/skills/last30days/SKILL.md
+++ b/skills/last30days/SKILL.md
@@ -702,7 +702,7 @@ The magic of /last30days is Reddit comments + X posts together - and both are fr
- After adding your key, set `INCLUDE_SOURCES=tiktok,instagram` to turn on the popular ones. (Threads, Pinterest, and LinkedIn are also available via `INCLUDE_SOURCES=threads,pinterest,linkedin` for power users.)
**Other optional sources (add anytime):**
-- `PERPLEXITY_API_KEY=xxx` (or `OPENROUTER_API_KEY=xxx`) - AI-synthesized research with citations; set `INCLUDE_SOURCES=perplexity`.
+- `PERPLEXITY_API_KEY=xxx` - preferred Agent/Search API path with citations; set `INCLUDE_SOURCES=perplexity`. Existing `OPENROUTER_API_KEY` installs keep the synchronous Sonar fallback.
- `XIAOHONGSHU_API_BASE=http://localhost:18060` - Xiaohongshu/RED via a logged-in x-mcp browser plugin or `xiaohongshu-mcp` service; optional unless the local service runs on a custom URL. Opt in per run with `--search xhs`, or persistently via `INCLUDE_SOURCES=xiaohongshu`.
- DripStack (premium financial newsletter search) is opt-in only: per run with `--search dripstack`, or persistently via `INCLUDE_SOURCES=dripstack`. Free public search API, no key; never active without the opt-in.
- `BSKY_HANDLE=you.bsky.social` + `BSKY_APP_PASSWORD=xxx` - Bluesky (free app password).
@@ -767,7 +767,7 @@ SKILL_DIR="<absolute path of the directory containing the SKILL.md you just Read
**Local corpus source:** If the user asks to include their own notes/documents, preserve each supplied directory as a repeatable `--corpus <dir>` engine flag. `LAST30DAYS_CORPUS_DIRS` activates persistent registered directories automatically. Do not WebSearch, upload, quote into a hosted request, or otherwise expose those paths or contents. Corpus retrieval is an offline source lane; its candidates also bypass remote reranker/fun-scoring prompts and use deterministic local scoring. The engine renders matches under the 🔒 **From your files** badge. The normal recency window uses file modification time; add `--corpus-all-time` only when the user explicitly asks to include older files. Corpus evidence is excluded from `--publish-html`, `library feed --publish`, and agent JSON by default. `LAST30DAYS_CORPUS_IN_EXPORT=1` is the explicit agent-JSON privacy opt-in; never enable it on the user's behalf. When a corpus is configured alongside `LAST30DAYS_API_KEY`/`LAST30DAYS_API_BASE`, the engine deliberately bypasses the hosted backend and runs locally.
-**Perplexity source:** use it only when the user asks for Perplexity, Deep Research, or paid grounded synthesis, or when `perplexity` is already enabled in `INCLUDE_SOURCES` / `--search`. Direct `PERPLEXITY_API_KEY` supports Sonar synthesis, Search API rows, and async Deep Research. `OPENROUTER_API_KEY` is only a Sonar fallback. Normal runs default to `LAST30DAYS_PERPLEXITY_MODE=sonar`; use `search` for raw ranked web rows, `both` for synthesis plus rows, and `--deep-research` for `sonar-deep-research` with a 600s default wall timeout. A local Deep Research timeout is not a failed API key; inspect the raw artifact's async request id/status and resume by id if needed.
+**Perplexity source:** use it only when the user asks for Perplexity, Deep Research, or paid grounded synthesis, or when `perplexity` is already enabled in `INCLUDE_SOURCES` / `--search`. Prefer `PERPLEXITY_API_KEY`: normal runs use the controlled Agent API path, `search` returns raw Search API rows, and `both` combines them. Existing `OPENROUTER_API_KEY` installs stay compatible through one synchronous Sonar call; `search` and `both` fall back to Sonar because those direct APIs need a Perplexity key. Every normal mode is capped at one whole-topic planner subquery per command, including competitor fanout, and is not repeated during thin-source retries. With a direct key, normal Agent mode supplies only `web_search`, forces it for citation-critical grounding, uses a bounded step count, and supplies a local instruction. `sonar` remains a deprecated direct-key alias for `agent`. `LAST30DAYS_PERPLEXITY_AGENT_PRESET` is an explicit direct-key choice only; never set it for the user. `--deep-research` requires a normal positional topic. A direct key starts at most one paid `high`-preset background run with a 600-second default wall timeout; OpenRouter preserves the synchronous `perplexity/sonar-deep-research` fallback. It cannot be combined with discovery, drill, cached-only, competitor, or vs-mode. A local timeout does not stop a direct remote run. Report safe model and response metadata, but never expose request headers or raw tool traces.
**Reddit backend pin:** Reddit defaults to the free keyless backend. When `SCRAPECREATORS_API_KEY` is available, ScrapeCreators Reddit **search** backfills only if that free path returns **no items** (empty-only — a thin but non-empty free scrape does not spend credits). If the user wants paid coverage on thin free runs, tell them to set `LAST30DAYS_REDDIT_SC_MIN_ITEMS=<N>` (backfill when free yield is below N). If they say public Reddit is shallow, bot-gated, or missing nested comments, tell them they can set `LAST30DAYS_REDDIT_BACKEND=scrapecreators` alongside `SCRAPECREATORS_API_KEY` to make ScrapeCreators primary and keep the free path as fallback. Do not set either automatically for normal runs.
diff --git a/skills/last30days/scripts/last30days.py b/skills/last30days/scripts/last30days.py
index e544cd16..12f80f60 100644
--- a/skills/last30days/scripts/last30days.py
+++ b/skills/last30days/scripts/last30days.py
@@ -119,6 +119,42 @@ def resolve_requested_sources(args_search: str | None, config: dict) -> list[str
return None
+def add_deep_research_source(
+ requested_sources: list[str] | None,
+) -> list[str] | None:
+ """Add Perplexity without replacing the default-source sentinel.
+
+ ``None`` means that the planner can use the normal configured source set.
+ Deep Research enables Perplexity through ``INCLUDE_SOURCES`` separately, so
+ converting this sentinel to ``["perplexity"]`` would suppress every normal
+ source.
+ """
+ if requested_sources is None:
+ return None
+ if "perplexity" in requested_sources:
+ return requested_sources
+ return [*requested_sources, "perplexity"]
+
+
+def enable_deep_research_source(config: dict) -> None:
+ """Enable the exact Perplexity token or reject a hard exclusion."""
+ excluded = {
+ token.strip().lower()
+ for token in str(config.get("EXCLUDE_SOURCES") or "").split(",")
+ if token.strip()
+ }
+ if "perplexity" in excluded:
+ raise ValueError(
+ "--deep-research conflicts with EXCLUDE_SOURCES=perplexity"
+ )
+
+ include = str(config.get("INCLUDE_SOURCES") or "")
+ tokens = [token.strip() for token in include.split(",") if token.strip()]
+ if "perplexity" not in {token.lower() for token in tokens}:
+ tokens.append("perplexity")
+ config["INCLUDE_SOURCES"] = ",".join(tokens)
+
+
def plan_has_explicit_trustpilot_domain(comp_plan: dict | None) -> bool:
"""True when any --competitors-plan entry pins a trustpilot_domain."""
if not comp_plan:
@@ -681,7 +717,7 @@ def build_parser() -> argparse.ArgumentParser:
help="Web search backend (default: auto, tries Brave then Exa then Serper then Parallel; "
"keyless forces the zero-key DuckDuckGo/SearXNG floor)")
parser.add_argument("--deep-research", action="store_true",
- help="Use Perplexity Deep Research (~$0.90/query) for in-depth analysis. Requires PERPLEXITY_API_KEY or OPENROUTER_API_KEY.")
+ help="Use at most one Perplexity Deep Research run. Direct PERPLEXITY_API_KEY uses the Agent API background path; OPENROUTER_API_KEY keeps the synchronous Sonar fallback; cannot be combined with competitor or vs-mode.")
parser.add_argument("--hiring-signals", action="store_true",
help="Analyze public jobs/careers postings as evidence-backed company focus signals.")
parser.add_argument("--plan", help="JSON query plan (skips internal LLM planner). Can be a JSON string or a file path.")
@@ -2964,6 +3000,13 @@ def _main(
# Bare --discover (no domain) is global trending, so the dispatch keys on
# "flag present" (is not None), never on the domain string's truthiness.
+ if args.deep_research and not topic:
+ sys.stderr.write(
+ "[last30days] --deep-research requires a normal positional topic; "
+ "it cannot be combined with discovery, drill, or cached-only modes.\n"
+ )
+ return 2
+
if args.discover is not None:
if topic:
sys.stderr.write(
@@ -3083,6 +3126,41 @@ def _main(
if args.lookback_days is None:
args.lookback_days = 30
+ if args.deep_research and not args.diagnose:
+ from lib import planner as _planner
+
+ if not (
+ config.get("PERPLEXITY_API_KEY")
+ or config.get("OPENROUTER_API_KEY")
+ ):
+ print(
+ "Error: --deep-research requires PERPLEXITY_API_KEY or "
+ "OPENROUTER_API_KEY",
+ file=sys.stderr,
+ )
+ return 1
+ comparison_requested = any(
+ value is not None
+ for value in (
+ args.competitors,
+ args.competitors_list,
+ args.competitors_plan,
+ )
+ ) or len(_planner._comparison_entities(topic, uncapped=True)) >= 2
+ if comparison_requested:
+ sys.stderr.write(
+ "Error: --deep-research cannot be combined with competitor or vs-mode. "
+ "It permits one paid Deep Research run per user action; run each topic "
+ "separately.\n"
+ )
+ return 2
+ config["_deep_research"] = True
+ try:
+ enable_deep_research_source(config)
+ except ValueError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 2
+
# Reject a misspelled configured register before remote submission or any
# local source retrieval. Excluded modes resolve to default and remain
# unaffected by the register setting.
@@ -3114,6 +3192,7 @@ def _main(
and env.read_secret_env("LAST30DAYS_API_KEY")
and os.environ.get("LAST30DAYS_API_BASE")
and not resolved_corpus_dirs
+ and not args.deep_research
):
if _freshness_enabled(args, config):
if args.verify_freshness is True:
@@ -3148,6 +3227,8 @@ def _main(
return hosted.run_hosted(topic, depth, **hosted_kwargs)
requested_sources = resolve_requested_sources(args.search, config)
+ if args.deep_research:
+ requested_sources = add_deep_research_source(requested_sources)
# Explicit --trustpilot-domain is user intent: activate the opt-in source
# before diagnose/run so the flag cannot silently no-op (#873). Auto-resolve
# hints are applied later and must not call this path.
@@ -3166,6 +3247,11 @@ def _main(
print(json.dumps(diag, indent=2, sort_keys=True))
return 0
+ # Competitor sub-runs shallow-copy this config. The shared object makes the
+ # paid Perplexity cap command-wide and thread-safe across that fanout. Keep
+ # this runtime-only object out of the safe diagnose configuration contract.
+ config["_perplexity_paid_budget"] = pipeline.PaidSourceBudget()
+
if not topic:
parser.print_usage(sys.stderr)
return 2
@@ -3187,7 +3273,11 @@ def _main(
sys.stderr.write(refuse_msg)
return 2
- if args.emit == "html" and synthesis_md is not None:
+ if (
+ args.emit == "html"
+ and synthesis_md is not None
+ and not args.deep_research
+ ):
cached = _load_last_report_cache(
topic,
ttl_seconds=_report_cache_ttl_seconds(config),
@@ -3356,17 +3446,6 @@ def _main(
f"{','.join(original_github_repos)} -> {','.join(github_repos)}\n"
)
- # --deep-research: auto-enable perplexity source and set deep flag
- if args.deep_research:
- if not (config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY")):
- print("Error: --deep-research requires PERPLEXITY_API_KEY or OPENROUTER_API_KEY", file=sys.stderr)
- sys.exit(1)
- config["_deep_research"] = True
- # Auto-enable perplexity in INCLUDE_SOURCES
- include = config.get("INCLUDE_SOURCES") or ""
- if "perplexity" not in include.lower():
- config["INCLUDE_SOURCES"] = f"{include},perplexity" if include else "perplexity"
-
# Polymarket disambiguation: if user passed --polymarket-keywords,
# store on config so the polymarket adapter can filter matches.
if args.polymarket_keywords:
@@ -3410,6 +3489,10 @@ def _main(
comp_explicit=comp_explicit,
comp_plan=comp_plan,
)
+ if comp_enabled:
+ config["_perplexity_paid_budget"] = pipeline.PaidSourceBudget(
+ owner=topic,
+ )
# Plan alone with zero peers (empty/invalid JSON object, or all entries
# skipped) must not fall through to discover-N with a misleading abort.
diff --git a/skills/last30days/scripts/lib/doctor.py b/skills/last30days/scripts/lib/doctor.py
index 19c71156..6e255d53 100644
--- a/skills/last30days/scripts/lib/doctor.py
+++ b/skills/last30days/scripts/lib/doctor.py
@@ -687,8 +687,13 @@ def _truthsocial_record(config):
def _perplexity_record(config):
- requires = "PERPLEXITY_API_KEY or OPENROUTER_API_KEY + INCLUDE_SOURCES=perplexity"
- has_key = bool(config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY"))
+ requires = (
+ "PERPLEXITY_API_KEY or OPENROUTER_API_KEY + "
+ "INCLUDE_SOURCES=perplexity"
+ )
+ has_direct_key = bool(config.get("PERPLEXITY_API_KEY"))
+ has_openrouter_key = bool(config.get("OPENROUTER_API_KEY"))
+ has_key = has_direct_key or has_openrouter_key
include = env.include_sources(config)
if not has_key:
return _record(
@@ -699,7 +704,15 @@ def _perplexity_record(config):
),
)
if "perplexity" in include:
- return _record(status=health.OK, requires=requires)
+ return _record(
+ status=health.OK,
+ requires=requires,
+ note=(
+ "direct Agent/Search APIs"
+ if has_direct_key
+ else "OpenRouter Sonar compatibility fallback"
+ ),
+ )
return _record(
status="opt-in", requires=requires,
fix="add perplexity to INCLUDE_SOURCES (or request it via --search perplexity)",
diff --git a/skills/last30days/scripts/lib/env.py b/skills/last30days/scripts/lib/env.py
index dcfa8645..9004ced2 100644
--- a/skills/last30days/scripts/lib/env.py
+++ b/skills/last30days/scripts/lib/env.py
@@ -517,8 +517,15 @@ def get_config(policy: ConfigLoadPolicy | None = None) -> dict[str, Any]:
('SERPER_API_KEY', None),
('OPENROUTER_API_KEY', None),
('PERPLEXITY_API_KEY', None),
- ('LAST30DAYS_PERPLEXITY_MODE', 'sonar'),
+ ('LAST30DAYS_PERPLEXITY_MODE', 'agent'),
+ # Legacy Sonar setting. Retain it during migration so existing env
+ # files load, but the Agent adapter does not map it to a dynamic preset.
('LAST30DAYS_PERPLEXITY_MODEL', None),
+ ('LAST30DAYS_PERPLEXITY_AGENT_MODEL', None),
+ ('LAST30DAYS_PERPLEXITY_AGENT_PRESET', None),
+ ('LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS', None),
+ ('LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS', None),
+ ('LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS', '120'),
('LAST30DAYS_PERPLEXITY_MAX_RESULTS', None),
('LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE', None),
('LAST30DAYS_PERPLEXITY_SEARCH_MODE', None),
diff --git a/skills/last30days/scripts/lib/http.py b/skills/last30days/scripts/lib/http.py
index c0828ab5..7f1e21c0 100644
--- a/skills/last30days/scripts/lib/http.py
+++ b/skills/last30days/scripts/lib/http.py
@@ -417,6 +417,16 @@ class HTTPError(Exception):
)
+class DeadlineExceeded(HTTPError):
+ """The caller's shared wall deadline expired across request retries."""
+
+ def __init__(self):
+ super().__init__(
+ "Request deadline exceeded",
+ outcome_state=health.TIMEOUT,
+ )
+
+
@contextmanager
def capture_failures():
"""Capture terminal request failures in the current retrieval context.
@@ -551,10 +561,11 @@ def request(
headers: Optional[Dict[str, str]] = None,
json_data: Optional[Dict[str, Any]] = None,
params: Optional[Dict[str, Any]] = None,
- timeout: int = DEFAULT_TIMEOUT,
+ timeout: float = DEFAULT_TIMEOUT,
retries: int = MAX_RETRIES,
max_429_retries: int = MAX_429_RETRIES,
raw: bool = False,
+ deadline_monotonic: float | None = None,
) -> Union[Dict[str, Any], str]:
"""Make an HTTP request and return JSON response.
@@ -569,6 +580,8 @@ def request(
retries: Number of retries on failure
max_429_retries: Maximum 429 retries before giving up (separate cap)
raw: If True, return raw response text instead of parsed JSON
+ deadline_monotonic: Optional absolute monotonic deadline shared by all
+ attempts and retry delays.
Returns:
Parsed JSON response as dict, or raw text string if raw=True.
@@ -627,17 +640,77 @@ def request(
_fixture_record(fixture_request, error=error, redactions=fixture_redactions)
_raise(error)
+ def deadline_error() -> HTTPError:
+ return DeadlineExceeded()
+
+ def sleep_before_retry(delay: float) -> bool:
+ """Sleep only when the full delay fits inside the caller's deadline."""
+ nonlocal last_error
+ if deadline_monotonic is not None:
+ remaining = deadline_monotonic - time.monotonic()
+ if remaining <= 0 or delay >= remaining:
+ last_error = deadline_error()
+ return False
+ time.sleep(delay)
+ return True
+
+ def open_and_read(request_timeout: float) -> tuple[int, str]:
+ with urllib.request.urlopen(req, timeout=request_timeout) as response:
+ return response.status, response.read().decode('utf-8')
+
+ def open_and_read_before_deadline(
+ request_timeout: float,
+ ) -> tuple[int, str]:
+ """Stop waiting at the wall deadline, even during DNS or body reads."""
+ if deadline_monotonic is None:
+ return open_and_read(request_timeout)
+ remaining = deadline_monotonic - time.monotonic()
+ if remaining <= 0:
+ raise deadline_error()
+ future: Future = Future()
+
+ def worker() -> None:
+ try:
+ future.set_result(open_and_read(request_timeout))
+ except BaseException as exc:
+ future.set_exception(exc)
+
+ threading.Thread(target=worker, daemon=True).start()
+ try:
+ return future.result(timeout=remaining)
+ except TimeoutError as exc:
+ # A worker-side socket TimeoutError is a transport failure, not
+ # proof that the command-wide wall deadline expired. Re-read a
+ # completed future so its original exception reaches the normal
+ # transport classifier below.
+ if future.done():
+ return future.result()
+ raise deadline_error() from exc
+
while attempt < effective_retries:
+ request_timeout = timeout
+ if deadline_monotonic is not None:
+ remaining = deadline_monotonic - time.monotonic()
+ if remaining <= 0:
+ last_error = deadline_error()
+ break
+ request_timeout = min(timeout, remaining)
try:
- with urllib.request.urlopen(req, timeout=timeout) as response:
- body = response.read().decode('utf-8')
- log(f"Response: {response.status} ({len(body)} bytes)")
- if raw:
- _fixture_record(fixture_request, value=body, redactions=fixture_redactions)
- return body
- parsed = json.loads(body) if body else {}
- _fixture_record(fixture_request, value=parsed, redactions=fixture_redactions)
- return parsed
+ response_status, body = open_and_read_before_deadline(request_timeout)
+ if (
+ deadline_monotonic is not None
+ and time.monotonic() >= deadline_monotonic
+ ):
+ raise_recorded(deadline_error())
+ log(f"Response: {response_status} ({len(body)} bytes)")
+ if raw:
+ _fixture_record(fixture_request, value=body, redactions=fixture_redactions)
+ return body
+ parsed = json.loads(body) if body else {}
+ _fixture_record(fixture_request, value=parsed, redactions=fixture_redactions)
+ return parsed
+ except DeadlineExceeded as exc:
+ raise_recorded(exc)
except urllib.error.HTTPError as e:
body = None
try:
@@ -676,7 +749,8 @@ def request(
log(f"Rate limited (429). Waiting {delay:.1f}s before retry {attempt + 2}/{retries}")
else:
delay = RETRY_DELAY * (2 ** attempt)
- time.sleep(delay)
+ if not sleep_before_retry(delay):
+ break
else:
# Caller's original retry budget exhausted; an earlier DNS
# failure may have widened `effective_retries`, but that
@@ -712,11 +786,13 @@ def request(
f"DNS resolution failure (attempt {dns_attempts}); "
f"retrying in {delay:.1f}s"
)
- time.sleep(delay)
+ if not sleep_before_retry(delay):
+ break
elif attempt < retries - 1:
# Non-DNS URLError (e.g. ConnectionRefused) respects the
# caller's original retry budget, not the DNS-widened bound.
- time.sleep(RETRY_DELAY * (attempt + 1))
+ if not sleep_before_retry(RETRY_DELAY * (attempt + 1)):
+ break
else:
# Caller's original retry budget exhausted; an earlier DNS
# failure widening `effective_retries` does not carry over
@@ -739,7 +815,8 @@ def request(
)
if attempt < retries - 1:
# Socket errors respect the caller's original retry budget.
- time.sleep(RETRY_DELAY * (attempt + 1))
+ if not sleep_before_retry(RETRY_DELAY * (attempt + 1)):
+ break
else:
# Original budget exhausted; DNS widening doesn't apply here.
break
diff --git a/skills/last30days/scripts/lib/perplexity.py b/skills/last30days/scripts/lib/perplexity.py
index ef52b6ce..09383c09 100644
--- a/skills/last30days/scripts/lib/perplexity.py
+++ b/skills/last30days/scripts/lib/perplexity.py
@@ -1,135 +1,101 @@
-"""Perplexity Sonar, Search API, and Deep Research.
+"""Perplexity Agent API, Search API, and OpenRouter compatibility integration.
-Direct Perplexity keys are preferred so the source can use first-party Search
-API results and async Deep Research. OpenRouter remains a Sonar compatibility
-fallback when no direct Perplexity key is configured.
+The Perplexity source is paid and opt-in. A direct key uses a controlled Agent
+API request with only web search enabled. Direct Deep Research uses an Agent
+API background run with the dynamic high preset. When no direct Perplexity key
+exists, OpenRouter preserves the legacy synchronous Sonar fallback.
"""
from __future__ import annotations
-import hashlib
-import json
-import random
-import sys
import time
from datetime import datetime
+from typing import Any
from urllib.parse import urlparse
-from . import http, log
+from . import health, http, log
OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
-PERPLEXITY_URL = "https://api.perplexity.ai/v1/sonar"
+PERPLEXITY_AGENT_URL = "https://api.perplexity.ai/v1/agent"
PERPLEXITY_SEARCH_URL = "https://api.perplexity.ai/search"
-PERPLEXITY_ASYNC_URL = "https://api.perplexity.ai/v1/async/sonar"
-OPENROUTER_MODEL_SONAR_PRO = "perplexity/sonar-pro"
-OPENROUTER_MODEL_DEEP_RESEARCH = "perplexity/sonar-deep-research"
-PERPLEXITY_MODEL_SONAR = "sonar"
-PERPLEXITY_MODEL_SONAR_PRO = "sonar-pro"
-PERPLEXITY_MODEL_REASONING_PRO = "sonar-reasoning-pro"
-PERPLEXITY_MODEL_DEEP_RESEARCH = "sonar-deep-research"
-PERPLEXITY_MODE_SONAR = "sonar"
+PERPLEXITY_MODE_AGENT = "agent"
+PERPLEXITY_MODE_SONAR = "sonar" # Direct-key alias and OpenRouter artifact mode.
PERPLEXITY_MODE_SEARCH = "search"
PERPLEXITY_MODE_BOTH = "both"
+PERPLEXITY_DEFAULT_AGENT_TIMEOUT_SECONDS = 120
PERPLEXITY_DEFAULT_DEEP_TIMEOUT_SECONDS = 600
PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS = 5.0
PERPLEXITY_DEEP_MAX_POLL_DELAY_SECONDS = 60.0
-DIRECT_MODELS = {
- PERPLEXITY_MODEL_SONAR,
- PERPLEXITY_MODEL_SONAR_PRO,
- PERPLEXITY_MODEL_REASONING_PRO,
- PERPLEXITY_MODEL_DEEP_RESEARCH,
-}
+PERPLEXITY_DEFAULT_AGENT_MODEL = "perplexity/sonar"
+OPENROUTER_MODEL_SONAR_PRO = "perplexity/sonar-pro"
+OPENROUTER_MODEL_DEEP_RESEARCH = "perplexity/sonar-deep-research"
+PERPLEXITY_DEFAULT_ANTHROPIC_MAX_OUTPUT_TOKENS = 4096
+PERPLEXITY_CONTROLLED_PROFILE = "last30days-controlled-web-search/v1"
+PERPLEXITY_PRESET_PROFILE = "perplexity-agent-preset"
+AGENT_PRESETS = {"fast", "low", "medium", "high"}
DIRECT_MODES = {
- PERPLEXITY_MODE_SONAR,
+ PERPLEXITY_MODE_AGENT,
PERPLEXITY_MODE_SEARCH,
PERPLEXITY_MODE_BOTH,
}
SEARCH_CONTEXT_SIZES = {"low", "medium", "high"}
SEARCH_RECENCY_FILTERS = {"hour", "day", "week", "month", "year"}
-SONAR_SEARCH_MODES = {"web", "academic", "sec"}
REASONING_EFFORTS = {"minimal", "low", "medium", "high"}
+CONTROLLED_AGENT_INSTRUCTIONS = (
+ "Use the supplied web search tool for current, source-grounded research. "
+ "Keep the answer concise. Cite source-backed claims in the answer. "
+ "Do not use tools other than those supplied in this request."
+)
+
-class AsyncDeepResearchTimeout(TimeoutError):
- def __init__(self, metadata: dict):
- timeout_seconds = metadata.get("asyncTimeoutSeconds") or "unknown"
- super().__init__(f"Async Deep Research exceeded {timeout_seconds}s wall timeout")
+class AgentBackgroundTimeout(TimeoutError):
+ def __init__(self, metadata: dict[str, Any]):
+ timeout_seconds = metadata.get("backgroundTimeoutSeconds") or "unknown"
+ super().__init__(f"Agent background run exceeded {timeout_seconds}s wall timeout")
self.metadata = metadata
-class AsyncDeepResearchFailed(RuntimeError):
- def __init__(self, metadata: dict):
- message = metadata.get("asyncErrorMessage") or "Async Deep Research failed"
- super().__init__(str(message))
+class AgentBackgroundFailed(RuntimeError):
+ def __init__(self, metadata: dict[str, Any]):
+ detail = metadata.get("backgroundErrorMessage") or "Agent background run failed"
+ super().__init__(str(detail))
self.metadata = metadata
-class AsyncDeepResearchPollError(RuntimeError):
- def __init__(self, metadata: dict):
- message = metadata.get("asyncPollError") or "Async Deep Research poll failed"
- super().__init__(str(message))
+class AgentBackgroundPollError(RuntimeError):
+ def __init__(self, metadata: dict[str, Any]):
+ detail = metadata.get("backgroundPollError") or "Agent background poll failed"
+ super().__init__(str(detail))
self.metadata = metadata
-def _log(msg: str):
- log.source_log("Perplexity", msg, tty_only=False)
+def _log(message: str) -> None:
+ log.source_log("Perplexity", message, tty_only=False)
def _domain(url: str) -> str:
return urlparse(url).netloc.strip().lower()
-def _provider(config: dict, deep: bool) -> tuple[str, str, str, str] | None:
- """Return (provider, api_key, url, model), preferring direct Perplexity."""
- if config.get("PERPLEXITY_API_KEY"):
- model = _direct_model(config, deep)
- url = PERPLEXITY_ASYNC_URL if deep else PERPLEXITY_URL
- return "perplexity", config["PERPLEXITY_API_KEY"], url, model
- if config.get("OPENROUTER_API_KEY"):
- model = OPENROUTER_MODEL_DEEP_RESEARCH if deep else OPENROUTER_MODEL_SONAR_PRO
- return "openrouter", config["OPENROUTER_API_KEY"], OPENROUTER_URL, model
- return None
-
-
-def _config_text(config: dict, key: str) -> str:
+def _config_text(config: dict[str, Any], key: str) -> str:
return str(config.get(key) or "").strip()
def _csv_values(raw: str, limit: int | None = None) -> list[str]:
values = [part.strip() for part in raw.split(",") if part.strip()]
- # values[:None] already returns the whole list, so no None guard is needed.
return values[:limit]
-def _direct_model(config: dict, deep: bool) -> str:
- if deep:
- return PERPLEXITY_MODEL_DEEP_RESEARCH
- model = _config_text(config, "LAST30DAYS_PERPLEXITY_MODEL") or PERPLEXITY_MODEL_SONAR_PRO
- if model not in DIRECT_MODELS:
- _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODEL={model!r}; using sonar-pro")
- return PERPLEXITY_MODEL_SONAR_PRO
- if model == PERPLEXITY_MODEL_DEEP_RESEARCH:
- return PERPLEXITY_MODEL_SONAR_PRO
- return model
-
-
-def _mode(config: dict, provider: str, deep: bool) -> str:
- if deep:
- return PERPLEXITY_MODE_SONAR
- mode = (_config_text(config, "LAST30DAYS_PERPLEXITY_MODE") or PERPLEXITY_MODE_SONAR).lower()
- if mode not in DIRECT_MODES:
- _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODE={mode!r}; using sonar")
- return PERPLEXITY_MODE_SONAR
- if provider != "perplexity" and mode != PERPLEXITY_MODE_SONAR:
- _log("Search API modes require PERPLEXITY_API_KEY; using OpenRouter Sonar fallback")
- return PERPLEXITY_MODE_SONAR
- return mode
-
-
-def _positive_int(raw: object, default: int, min_value: int, max_value: int | None = None) -> int:
+def _positive_int(
+ raw: object,
+ default: int,
+ min_value: int,
+ max_value: int | None = None,
+) -> int:
try:
value = int(str(raw).strip())
except (TypeError, ValueError):
@@ -149,44 +115,13 @@ def _mmddyyyy(date: str | None) -> str | None:
return None
-def _usage(data: dict) -> dict:
+def _usage(data: dict[str, Any]) -> dict[str, Any]:
usage = data.get("usage")
return usage if isinstance(usage, dict) else {}
-def _idempotency_key(json_data: dict) -> str:
- payload = json.dumps(json_data, sort_keys=True, separators=(",", ":"))
- digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:32]
- return f"last30days:{digest}"
-
-
-def _async_metadata(
- data: dict,
- request_id: str,
- timeout_seconds: int,
- idempotency_key: str,
- poll_count: int,
- local_status: str,
-) -> dict:
- metadata = {
- "async": True,
- "asyncRequestId": request_id,
- "asyncStatus": data.get("status"),
- "asyncTimeoutSeconds": timeout_seconds,
- "asyncIdempotencyKey": idempotency_key,
- "asyncPollCount": poll_count,
- "asyncLocalStatus": local_status,
- "asyncCreatedAt": data.get("created_at"),
- "asyncStartedAt": data.get("started_at"),
- "asyncCompletedAt": data.get("completed_at"),
- "asyncFailedAt": data.get("failed_at"),
- "asyncErrorMessage": data.get("error_message"),
- }
- return {k: v for k, v in metadata.items() if v is not None}
-
-
-def _error_artifact(exc: Exception) -> dict:
- artifact = {
+def _error_artifact(exc: Exception) -> dict[str, Any]:
+ artifact: dict[str, Any] = {
"error": type(exc).__name__,
"message": str(exc)[:200],
}
@@ -195,86 +130,127 @@ def _error_artifact(exc: Exception) -> dict:
return artifact
-def _empty_async_sonar_artifact(
- provider: str,
- model: str,
- deep: bool,
- query: str,
- data: dict,
- async_artifact: dict,
- error: str,
- message: str,
-) -> dict:
- if not async_artifact:
- return {}
- artifact = {
- "label": "perplexity",
- "provider": provider,
- "mode": PERPLEXITY_MODE_SONAR,
- "endpoint": "async-sonar",
- "model": model,
- "deep": deep,
- "query": query,
- "error": error,
- "synthesisLength": 0,
- "citationCount": 0,
- "usage": _usage(data),
- **async_artifact,
- }
- if not artifact.get("asyncErrorMessage"):
- artifact["asyncErrorMessage"] = message
- return artifact
+def _provider(config: dict[str, Any]) -> tuple[str, str] | None:
+ """Prefer direct Perplexity, then preserve the OpenRouter Sonar fallback."""
+ api_key = _config_text(config, "PERPLEXITY_API_KEY")
+ if api_key:
+ return "perplexity", api_key
+ openrouter_key = _config_text(config, "OPENROUTER_API_KEY")
+ if openrouter_key:
+ return "openrouter", openrouter_key
+ return None
-def _build_sonar_payload(prompt: str, model: str, date_range: tuple[str, str], config: dict) -> dict:
- payload = {
- "model": model,
- "messages": [{"role": "user", "content": prompt}],
- }
+def _mode(config: dict[str, Any], deep: bool, provider: str) -> str:
+ if deep:
+ return (
+ PERPLEXITY_MODE_AGENT
+ if provider == "perplexity"
+ else PERPLEXITY_MODE_SONAR
+ )
- from_date, to_date = date_range
- web_options: dict[str, object] = {}
- search_mode = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_MODE").lower()
- if search_mode in SONAR_SEARCH_MODES:
- web_options["search_mode"] = search_mode
+ mode = (
+ _config_text(config, "LAST30DAYS_PERPLEXITY_MODE")
+ or PERPLEXITY_MODE_AGENT
+ ).lower()
+ if provider == "openrouter":
+ if mode in {PERPLEXITY_MODE_SEARCH, PERPLEXITY_MODE_BOTH}:
+ _log(
+ f"LAST30DAYS_PERPLEXITY_MODE={mode} requires PERPLEXITY_API_KEY; "
+ "using the OpenRouter Sonar fallback"
+ )
+ return PERPLEXITY_MODE_SONAR
+ if mode == PERPLEXITY_MODE_SONAR:
+ _log(
+ "LAST30DAYS_PERPLEXITY_MODE=sonar is deprecated; "
+ "using the Agent API controlled profile"
+ )
+ return PERPLEXITY_MODE_AGENT
+ if mode not in DIRECT_MODES:
+ _log(f"Unsupported LAST30DAYS_PERPLEXITY_MODE={mode!r}; using agent")
+ return PERPLEXITY_MODE_AGENT
+ return mode
- domains = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"), limit=20)
- if domains:
- web_options["search_domain_filter"] = domains
- languages = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"), limit=20)
- if languages:
- web_options["search_language_filter"] = languages
+def _agent_preset(config: dict[str, Any], deep: bool) -> str | None:
+ if deep:
+ return "high"
- recency = _config_text(config, "LAST30DAYS_PERPLEXITY_RECENCY_FILTER").lower()
- if recency in SEARCH_RECENCY_FILTERS:
- web_options["search_recency_filter"] = recency
+ preset = _config_text(config, "LAST30DAYS_PERPLEXITY_AGENT_PRESET").lower()
+ if not preset:
+ return None
+ if preset in AGENT_PRESETS:
+ return preset
+ _log(
+ "Unsupported LAST30DAYS_PERPLEXITY_AGENT_PRESET="
+ f"{preset!r}; using the controlled profile"
+ )
+ return None
- after = _mmddyyyy(from_date)
- before = _mmddyyyy(to_date)
- if after:
- web_options["search_after_date_filter"] = after
- if before:
- web_options["search_before_date_filter"] = before
- if web_options:
- payload["web_search_options"] = web_options
+def _agent_model(config: dict[str, Any]) -> str:
+ legacy_model = _config_text(config, "LAST30DAYS_PERPLEXITY_MODEL")
+ if legacy_model:
+ _log(
+ "LAST30DAYS_PERPLEXITY_MODEL is a legacy Sonar setting and is "
+ "ignored by the Agent API; set LAST30DAYS_PERPLEXITY_AGENT_MODEL "
+ "for an explicit Agent model"
+ )
+ return (
+ _config_text(config, "LAST30DAYS_PERPLEXITY_AGENT_MODEL")
+ or PERPLEXITY_DEFAULT_AGENT_MODEL
+ )
- effort = _config_text(config, "LAST30DAYS_PERPLEXITY_REASONING_EFFORT").lower()
- if effort in REASONING_EFFORTS:
- payload["reasoning_effort"] = effort
- return payload
+def _agent_timeout(config: dict[str, Any]) -> int:
+ return _positive_int(
+ config.get("LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS"),
+ PERPLEXITY_DEFAULT_AGENT_TIMEOUT_SECONDS,
+ 1,
+ 600,
+ )
+
+
+def _safe_error_message(data: dict[str, Any]) -> str | None:
+ error = data.get("error")
+ if isinstance(error, str):
+ return error[:200]
+ if isinstance(error, dict):
+ for key in ("message", "detail", "code"):
+ value = error.get(key)
+ if isinstance(value, str) and value:
+ return value[:200]
+ return None
+
+
+def _safe_incomplete_reason(data: dict[str, Any]) -> str | None:
+ details = data.get("incomplete_details")
+ if not isinstance(details, dict):
+ return None
+ reason = details.get("reason")
+ return reason[:100] if isinstance(reason, str) and reason else None
-def _build_search_payload(query: str, date_range: tuple[str, str], config: dict) -> dict:
+def _build_search_payload(
+ query: str,
+ date_range: tuple[str, str],
+ config: dict[str, Any],
+) -> dict[str, Any]:
from_date, to_date = date_range
- payload: dict[str, object] = {
+ payload: dict[str, Any] = {
"query": query,
- "max_results": _positive_int(config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"), 10, 1, 20),
+ "max_results": _positive_int(
+ config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"),
+ 10,
+ 1,
+ 20,
+ ),
}
- context_size = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE").lower()
+ context_size = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE",
+ ).lower()
if context_size in SEARCH_CONTEXT_SIZES:
payload["search_context_size"] = context_size
@@ -282,11 +258,17 @@ def _build_search_payload(query: str, date_range: tuple[str, str], config: dict)
if len(country) == 2:
payload["country"] = country
- domains = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"), limit=20)
+ domains = _csv_values(
+ _config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"),
+ limit=20,
+ )
if domains:
payload["search_domain_filter"] = domains
- languages = _csv_values(_config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"), limit=20)
+ languages = _csv_values(
+ _config_text(config, "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER"),
+ limit=20,
+ )
if languages:
payload["search_language_filter"] = languages
@@ -298,152 +280,499 @@ def _build_search_payload(query: str, date_range: tuple[str, str], config: dict)
payload["search_before_date_filter"] = before
# Perplexity Search API rejects search_recency_filter when explicit
- # published-date filters are present. last30days already passes an exact
- # date range, so prefer that and keep recency only for undated callers.
- recency = _config_text(config, "LAST30DAYS_PERPLEXITY_RECENCY_FILTER").lower()
+ # published-date filters are present. Preserve the upstream fix.
+ recency = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER",
+ ).lower()
if recency in SEARCH_RECENCY_FILTERS and not (after or before):
payload["search_recency_filter"] = recency
return payload
-def _append_citation(citations: list[dict], seen_urls: set[str], citation: dict) -> None:
- url = (citation.get("url") or "").strip()
- if not url or url in seen_urls:
+def _build_web_search_tool(
+ date_range: tuple[str, str],
+ config: dict[str, Any],
+) -> dict[str, Any]:
+ from_date, to_date = date_range
+ tool: dict[str, Any] = {
+ "type": "web_search",
+ "max_results": _positive_int(
+ config.get("LAST30DAYS_PERPLEXITY_MAX_RESULTS"),
+ 10,
+ 1,
+ 20,
+ ),
+ }
+
+ context_size = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE",
+ ).lower()
+ if context_size in SEARCH_CONTEXT_SIZES:
+ tool["search_context_size"] = context_size
+
+ country = _config_text(config, "LAST30DAYS_PERPLEXITY_COUNTRY").upper()
+ if len(country) == 2:
+ tool["user_location"] = {"country": country}
+
+ filters: dict[str, Any] = {}
+ domains = _csv_values(
+ _config_text(config, "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER"),
+ limit=20,
+ )
+ if domains:
+ filters["search_domain_filter"] = domains
+
+ after = _mmddyyyy(from_date)
+ before = _mmddyyyy(to_date)
+ if after:
+ filters["search_after_date_filter"] = after
+ if before:
+ filters["search_before_date_filter"] = before
+
+ recency = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER",
+ ).lower()
+ if recency in SEARCH_RECENCY_FILTERS and not (after or before):
+ filters["search_recency_filter"] = recency
+ if filters:
+ tool["filters"] = filters
+
+ language_filter = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER",
+ )
+ if language_filter:
+ _log(
+ "LAST30DAYS_PERPLEXITY_LANGUAGE_FILTER has no Agent API "
+ "equivalent and applies only to Search API mode"
+ )
+ search_mode = _config_text(config, "LAST30DAYS_PERPLEXITY_SEARCH_MODE").lower()
+ if search_mode and search_mode != "web":
+ _log(
+ "LAST30DAYS_PERPLEXITY_SEARCH_MODE has no Agent API equivalent; "
+ "using web search"
+ )
+
+ return tool
+
+
+def _safe_request(payload: dict[str, Any]) -> dict[str, Any]:
+ request: dict[str, Any] = {}
+ for key in (
+ "model",
+ "preset",
+ "max_steps",
+ "max_output_tokens",
+ "background",
+ ):
+ if key in payload:
+ request[key] = payload[key]
+ reasoning = payload.get("reasoning")
+ if isinstance(reasoning, dict) and isinstance(reasoning.get("effort"), str):
+ request["reasoning"] = {"effort": reasoning["effort"]}
+ tool_choice = payload.get("tool_choice")
+ if tool_choice == {"type": "web_search"}:
+ request["tool_choice"] = tool_choice
+ tools = payload.get("tools")
+ if isinstance(tools, list):
+ request["tools"] = [
+ {
+ key: tool[key]
+ for key in (
+ "type",
+ "max_results",
+ "search_context_size",
+ "user_location",
+ "filters",
+ )
+ if key in tool
+ }
+ for tool in tools
+ if isinstance(tool, dict) and tool.get("type") == "web_search"
+ ]
+ return request
+
+
+def _build_agent_payload(
+ prompt: str,
+ date_range: tuple[str, str],
+ config: dict[str, Any],
+ deep: bool,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+ preset = _agent_preset(config, deep)
+ if preset:
+ payload = {
+ "preset": preset,
+ "input": prompt,
+ # A supplied web_search tool merges with a preset's tools. This
+ # preserves the user's date, domain, location, and result bounds
+ # without claiming to disable any other dynamic-preset tools.
+ "tools": [_build_web_search_tool(date_range, config)],
+ }
+ if deep:
+ payload["background"] = True
+ return payload, {
+ "profile": PERPLEXITY_PRESET_PROFILE,
+ "preset": preset,
+ "dynamicPreset": True,
+ "request": _safe_request(payload),
+ }
+
+ payload: dict[str, Any] = {
+ "model": _agent_model(config),
+ "instructions": CONTROLLED_AGENT_INSTRUCTIONS,
+ "input": prompt,
+ "tools": [_build_web_search_tool(date_range, config)],
+ "tool_choice": {"type": "web_search"},
+ "max_steps": _positive_int(
+ config.get("LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS"),
+ 5,
+ 1,
+ 15,
+ ),
+ }
+ if str(payload["model"]).lower().startswith("anthropic/"):
+ payload["max_output_tokens"] = _positive_int(
+ config.get("LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS"),
+ PERPLEXITY_DEFAULT_ANTHROPIC_MAX_OUTPUT_TOKENS,
+ 1,
+ 32768,
+ )
+ effort = _config_text(
+ config,
+ "LAST30DAYS_PERPLEXITY_REASONING_EFFORT",
+ ).lower()
+ if effort in REASONING_EFFORTS:
+ payload["reasoning"] = {"effort": effort}
+ return payload, {
+ "profile": PERPLEXITY_CONTROLLED_PROFILE,
+ "model": payload["model"],
+ "dynamicPreset": False,
+ "request": _safe_request(payload),
+ }
+
+
+def _append_citation(
+ citations: list[dict[str, Any]],
+ seen_urls: set[str],
+ citation: dict[str, Any],
+) -> None:
+ url = str(citation.get("url") or "").strip()
+ if not url:
return
+ if url in seen_urls:
+ # Message annotations commonly carry only a URL and title. Merge the
+ # later search_results item instead of discarding its snippet/date.
+ for existing in citations:
+ if existing.get("url") != url:
+ continue
+ for key in ("title", "snippet", "date"):
+ if not existing.get(key) and citation.get(key):
+ existing[key] = citation[key]
+ return
seen_urls.add(url)
- citations.append({
- "url": url,
- "title": citation.get("title") or "",
- "snippet": citation.get("snippet") or "",
- "date": citation.get("date"),
- })
+ citations.append(
+ {
+ "url": url,
+ "title": citation.get("title") or "",
+ "snippet": citation.get("snippet") or "",
+ "date": citation.get("date"),
+ }
+ )
+
+
+def _append_annotations(
+ citations: list[dict[str, Any]],
+ seen_urls: set[str],
+ annotations: Any,
+) -> None:
+ if not isinstance(annotations, list):
+ return
+ for annotation in annotations:
+ if not isinstance(annotation, dict):
+ continue
+ citation = annotation.get("url_citation")
+ if not isinstance(citation, dict):
+ citation = annotation
+ _append_citation(citations, seen_urls, citation)
-def _extract_citations(data: dict, choice: dict) -> list[dict]:
- """Extract citations from direct Perplexity and OpenRouter response shapes."""
- citations: list[dict] = []
+def _extract_agent_citations(data: dict[str, Any]) -> list[dict[str, Any]]:
+ citations: list[dict[str, Any]] = []
seen_urls: set[str] = set()
- search_results_by_url: dict[str, dict] = {}
+ for result in data.get("results") or []:
+ if isinstance(result, dict):
+ _append_citation(citations, seen_urls, result)
+
+ output = data.get("output")
+ if not isinstance(output, list):
+ return citations
+
+ for item in output:
+ if not isinstance(item, dict):
+ continue
+ item_type = item.get("type")
+ if item_type == "search_results":
+ for result in item.get("results") or []:
+ if isinstance(result, dict):
+ _append_citation(citations, seen_urls, result)
+ continue
+ if item_type != "message":
+ continue
+ _append_annotations(citations, seen_urls, item.get("annotations"))
+ content = item.get("content")
+ if not isinstance(content, list):
+ continue
+ for part in content:
+ if isinstance(part, dict):
+ _append_annotations(citations, seen_urls, part.get("annotations"))
+
+ return citations
+
+
+def _extract_openrouter_citations(
+ data: dict[str, Any],
+ choice: dict[str, Any],
+) -> list[dict[str, Any]]:
+ """Read the legacy OpenAI-compatible Sonar citation shapes."""
+ citations: list[dict[str, Any]] = []
+ seen_urls: set[str] = set()
+ search_results: dict[str, dict[str, Any]] = {}
for result in data.get("search_results") or []:
if not isinstance(result, dict):
continue
- url = (result.get("url") or "").strip()
+ url = str(result.get("url") or "").strip()
if not url:
continue
- search_results_by_url[url] = result
+ search_results[url] = result
_append_citation(citations, seen_urls, result)
for url in data.get("citations") or []:
if not isinstance(url, str):
continue
- result = search_results_by_url.get(url, {})
- _append_citation(citations, seen_urls, {
- "url": url,
- "title": result.get("title") or _domain(url),
- "snippet": result.get("snippet") or "",
- "date": result.get("date"),
- })
-
- annotations = choice.get("message", {}).get("annotations", [])
- for ann in annotations or []:
- if not isinstance(ann, dict):
- continue
- url_citation = ann.get("url_citation", {})
- if not isinstance(url_citation, dict):
- continue
- _append_citation(citations, seen_urls, {
- "url": url_citation.get("url") or "",
- "title": url_citation.get("title") or "",
- })
+ result = search_results.get(url, {})
+ _append_citation(
+ citations,
+ seen_urls,
+ {
+ "url": url,
+ "title": result.get("title") or _domain(url),
+ "snippet": result.get("snippet") or "",
+ "date": result.get("date"),
+ },
+ )
+ message = choice.get("message")
+ if isinstance(message, dict):
+ _append_annotations(citations, seen_urls, message.get("annotations"))
return citations
-def _poll_async_sonar(json_data: dict, headers: dict, config: dict) -> tuple[dict, dict]:
+def _output_types(data: dict[str, Any]) -> list[str]:
+ output = data.get("output")
+ if not isinstance(output, list):
+ return []
+ return [
+ item["type"]
+ for item in output
+ if isinstance(item, dict) and isinstance(item.get("type"), str)
+ ]
+
+
+def _output_text(data: dict[str, Any]) -> str:
+ direct = data.get("output_text")
+ if isinstance(direct, str) and direct.strip():
+ return direct
+
+ parts: list[str] = []
+ output = data.get("output")
+ if not isinstance(output, list):
+ return ""
+ for item in output:
+ if not isinstance(item, dict) or item.get("type") != "message":
+ continue
+ content = item.get("content")
+ if isinstance(content, str):
+ parts.append(content)
+ continue
+ if not isinstance(content, list):
+ continue
+ for part in content:
+ if not isinstance(part, dict):
+ continue
+ if part.get("type") not in {"output_text", "text"}:
+ continue
+ text = part.get("text")
+ if isinstance(text, str):
+ parts.append(text)
+ return "".join(parts).strip()
+
+
+def _background_metadata(
+ data: dict[str, Any],
+ response_id: str,
+ timeout_seconds: int,
+ poll_count: int,
+ local_status: str,
+) -> dict[str, Any]:
+ metadata: dict[str, Any] = {
+ "background": True,
+ "responseId": response_id,
+ "backgroundStatus": data.get("status"),
+ "servedModel": data.get("model"),
+ "usage": _usage(data),
+ "outputTypes": _output_types(data),
+ "backgroundTimeoutSeconds": timeout_seconds,
+ "backgroundPollCount": poll_count,
+ "backgroundLocalStatus": local_status,
+ }
+ message = _safe_error_message(data)
+ if message:
+ metadata["backgroundErrorMessage"] = message
+ incomplete_reason = _safe_incomplete_reason(data)
+ if incomplete_reason:
+ metadata["incompleteReason"] = incomplete_reason
+ return {key: value for key, value in metadata.items() if value is not None}
+
+
+def _log_deep_receipt(artifact: dict[str, Any]) -> None:
+ """Expose the safe Deep receipt to slash-command and CLI consumers."""
+ fields = (
+ ("model", artifact.get("servedModel")),
+ ("response_id", artifact.get("responseId")),
+ ("provider_status", artifact.get("backgroundStatus") or artifact.get("status")),
+ ("local_status", artifact.get("backgroundLocalStatus")),
+ ("incomplete_reason", artifact.get("incompleteReason")),
+ ("polls", artifact.get("backgroundPollCount")),
+ ("timeout_seconds", artifact.get("backgroundTimeoutSeconds")),
+ )
+ rendered = " ".join(
+ f"{key}={value}"
+ for key, value in fields
+ if value is not None
+ )
+ _log(f"Deep Research receipt: {rendered or 'unavailable'}")
+
+
+def _poll_agent_background(
+ payload: dict[str, Any],
+ headers: dict[str, str],
+ config: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
timeout_seconds = _positive_int(
config.get("LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS"),
PERPLEXITY_DEFAULT_DEEP_TIMEOUT_SECONDS,
1,
None,
)
- idempotency_key = _idempotency_key(json_data)
created = http.post(
- PERPLEXITY_ASYNC_URL,
- {"request": json_data, "idempotency_key": idempotency_key},
+ PERPLEXITY_AGENT_URL,
+ payload,
headers=headers,
timeout=30,
- retries=2,
+ retries=1,
)
- request_id = created.get("id")
- if not request_id:
- raise http.HTTPError("Async Deep Research response missing id")
+ response_id = created.get("id")
+ if not isinstance(response_id, str) or not response_id:
+ raise http.HTTPError("Agent background response missing id")
- deadline = time.monotonic() + timeout_seconds
- poll_url = f"{PERPLEXITY_ASYNC_URL}/{request_id}"
- delay = PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS
- last_status = created.get("status")
+ terminal = {"completed", "failed", "cancelled", "incomplete"}
+ status = str(created.get("status") or "").lower()
+ data = created
poll_count = 0
- last_data = created
- if last_status:
- _log(f"Deep Research async status: {last_status}")
+ if status:
+ _log(f"Agent background status: {status}")
- while time.monotonic() < deadline:
+ deadline = time.monotonic() + timeout_seconds
+ delay = PERPLEXITY_DEEP_INITIAL_POLL_DELAY_SECONDS
+ while status not in terminal:
+ if time.monotonic() >= deadline:
+ raise AgentBackgroundTimeout(
+ _background_metadata(
+ data,
+ response_id,
+ timeout_seconds,
+ poll_count,
+ "PENDING_REMOTE",
+ )
+ )
try:
- data = http.get(poll_url, headers=headers, timeout=30, retries=2)
- except http.HTTPError as e:
- metadata = _async_metadata(
- last_data, request_id, timeout_seconds, idempotency_key, poll_count + 1,
+ data = http.get(
+ f"{PERPLEXITY_AGENT_URL}/{response_id}",
+ headers=headers,
+ timeout=30,
+ retries=2,
+ deadline_monotonic=deadline,
+ )
+ except http.HTTPError as exc:
+ if isinstance(exc, http.DeadlineExceeded) or time.monotonic() >= deadline:
+ raise AgentBackgroundTimeout(
+ _background_metadata(
+ data,
+ response_id,
+ timeout_seconds,
+ poll_count + 1,
+ "PENDING_REMOTE",
+ )
+ ) from exc
+ metadata = _background_metadata(
+ data,
+ response_id,
+ timeout_seconds,
+ poll_count + 1,
"POLL_ERROR",
)
- metadata["asyncPollError"] = str(e)
- if e.status_code is not None:
- metadata["asyncPollStatusCode"] = e.status_code
- raise AsyncDeepResearchPollError(metadata)
+ metadata["backgroundPollError"] = str(exc)[:200]
+ if exc.status_code is not None:
+ metadata["backgroundPollStatusCode"] = exc.status_code
+ raise AgentBackgroundPollError(metadata) from exc
+
poll_count += 1
- last_data = data
- status = data.get("status")
- if status and status != last_status:
- _log(f"Deep Research async status: {status}")
- last_status = status
- if status == "COMPLETED":
- response = data.get("response")
- if not isinstance(response, dict):
- metadata = _async_metadata(
- data, request_id, timeout_seconds, idempotency_key, poll_count,
- "FAILED_REMOTE",
- )
- metadata["asyncErrorMessage"] = "Async Deep Research completed without response"
- raise AsyncDeepResearchFailed(metadata)
- return response, _async_metadata(
- data, request_id, timeout_seconds, idempotency_key, poll_count,
- "COMPLETED_REMOTE",
- )
- if status == "FAILED":
- raise AsyncDeepResearchFailed(_async_metadata(
- data, request_id, timeout_seconds, idempotency_key, poll_count,
- "FAILED_REMOTE",
- ))
+ next_status = str(data.get("status") or "").lower()
+ if next_status and next_status != status:
+ _log(f"Agent background status: {next_status}")
+ status = next_status
remaining = deadline - time.monotonic()
if remaining <= 0:
+ raise AgentBackgroundTimeout(
+ _background_metadata(
+ data,
+ response_id,
+ timeout_seconds,
+ poll_count,
+ "PENDING_REMOTE",
+ )
+ )
+ if status in terminal:
break
- jitter = random.uniform(0, 2)
- time.sleep(min(delay + jitter, max(0.1, remaining)))
+ time.sleep(min(delay, remaining))
delay = min(delay * 1.5, PERPLEXITY_DEEP_MAX_POLL_DELAY_SECONDS)
- raise AsyncDeepResearchTimeout(_async_metadata(
- last_data, request_id, timeout_seconds, idempotency_key, poll_count,
- "PENDING_REMOTE",
- ))
+ metadata = _background_metadata(
+ data,
+ response_id,
+ timeout_seconds,
+ poll_count,
+ "COMPLETED_REMOTE" if status == "completed" else "TERMINAL_REMOTE",
+ )
+ if status == "completed":
+ return data, metadata
+ if not status:
+ metadata["backgroundErrorMessage"] = "Agent background response has no status"
+ raise AgentBackgroundFailed(metadata)
def _search_api(
query: str,
date_range: tuple[str, str],
- config: dict,
+ config: dict[str, Any],
api_key: str,
-) -> tuple[list[dict], dict]:
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
from_date, to_date = date_range
headers = {
"Authorization": f"Bearer {api_key}",
@@ -452,33 +781,41 @@ def _search_api(
payload = _build_search_payload(query, date_range, config)
_log(f"Querying Perplexity Search API for '{query}' ({from_date} to {to_date})")
- data = http.post(PERPLEXITY_SEARCH_URL, payload, headers=headers, timeout=30)
+ data = http.post(
+ PERPLEXITY_SEARCH_URL,
+ payload,
+ headers=headers,
+ timeout=30,
+ retries=1,
+ )
results = data.get("results") or []
if not isinstance(results, list):
results = []
- items = []
- for i, result in enumerate(results):
+ items: list[dict[str, Any]] = []
+ for index, result in enumerate(results):
if not isinstance(result, dict):
continue
- url = (result.get("url") or "").strip()
+ url = str(result.get("url") or "").strip()
if not url:
continue
- items.append({
- "id": f"PXS{i + 1}",
- "title": result.get("title") or _domain(url),
- "url": url,
- "source_domain": _domain(url),
- "snippet": result.get("snippet") or "",
- "date": result.get("date"),
- "relevance": max(0.55, 0.85 - (i * 0.03)),
- "why_relevant": f"Ranked by Perplexity Search API for '{query}'",
- "engagement": {},
- "metadata": {
- "last_updated": result.get("last_updated"),
- "perplexity_search_id": data.get("id"),
- },
- })
+ items.append(
+ {
+ "id": f"PXS{index + 1}",
+ "title": result.get("title") or _domain(url),
+ "url": url,
+ "source_domain": _domain(url),
+ "snippet": result.get("snippet") or "",
+ "date": result.get("date"),
+ "relevance": max(0.55, 0.85 - (index * 0.03)),
+ "why_relevant": f"Ranked by Perplexity Search API for '{query}'",
+ "engagement": {},
+ "metadata": {
+ "last_updated": result.get("last_updated"),
+ "perplexity_search_id": data.get("id"),
+ },
+ }
+ )
artifact = {
"label": "perplexity",
@@ -487,11 +824,7 @@ def _search_api(
"endpoint": "search",
"query": query,
"resultCount": len(items),
- "request": {
- k: v
- for k, v in payload.items()
- if k not in {"query"}
- },
+ "request": {key: value for key, value in payload.items() if key != "query"},
"responseId": data.get("id"),
"serverTime": data.get("server_time"),
}
@@ -499,133 +832,339 @@ def _search_api(
return items, artifact
-def _sonar_search(
+def _agent_failure_artifact(
+ query: str,
+ deep: bool,
+ selection: dict[str, Any],
+ *,
+ error: str,
+ metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+ return {
+ "label": "perplexity",
+ "provider": "perplexity",
+ "mode": PERPLEXITY_MODE_AGENT,
+ "endpoint": "agent-background" if deep else "agent",
+ "deep": deep,
+ "query": query,
+ "error": error,
+ "synthesisLength": 0,
+ "citationCount": 0,
+ **selection,
+ **(metadata or {}),
+ }
+
+
+def _agent_result(
query: str,
date_range: tuple[str, str],
- config: dict,
- provider: str,
- api_key: str,
- url: str,
- model: str,
deep: bool,
-) -> tuple[list[dict], dict]:
- from_date, to_date = date_range
- timeout = 120 if deep else 30
+ data: dict[str, Any],
+ selection: dict[str, Any],
+ background_metadata: dict[str, Any] | None = None,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ _, to_date = date_range
+ status = str(data.get("status") or "").lower()
+ if status and status != "completed":
+ metadata: dict[str, Any] = {
+ "responseId": data.get("id"),
+ "status": data.get("status"),
+ "servedModel": data.get("model"),
+ "usage": _usage(data),
+ "outputTypes": _output_types(data),
+ }
+ message = _safe_error_message(data)
+ if message:
+ metadata["agentErrorMessage"] = message
+ incomplete_reason = _safe_incomplete_reason(data)
+ if incomplete_reason:
+ metadata["incompleteReason"] = incomplete_reason
+ if background_metadata:
+ metadata.update(background_metadata)
+ return [], _agent_failure_artifact(
+ query,
+ deep,
+ selection,
+ error=status,
+ metadata=metadata,
+ )
- if deep:
- print("[Perplexity] Using Deep Research (~$0.90/query)", file=sys.stderr)
+ synthesis = _output_text(data)
+ citations = _extract_agent_citations(data)
+ if not synthesis:
+ _log("Empty Agent API synthesis")
+ return [], _agent_failure_artifact(
+ query,
+ deep,
+ selection,
+ error="empty_synthesis",
+ metadata={
+ "responseId": data.get("id"),
+ "status": data.get("status"),
+ "servedModel": data.get("model"),
+ "usage": _usage(data),
+ "outputTypes": _output_types(data),
+ **(background_metadata or {}),
+ },
+ )
+
+ _log(f"Got Agent API synthesis ({len(synthesis)} chars) with {len(citations)} citations")
+ title_mode = "Deep Research" if deep else "Agent"
+ items: list[dict[str, Any]] = [
+ {
+ "id": "PX1",
+ "title": f"Perplexity {title_mode}: {query}",
+ "url": "",
+ "source_domain": "perplexity.ai",
+ "snippet": synthesis[:2000],
+ "date": to_date,
+ "relevance": 0.9,
+ "why_relevant": f"AI synthesis of recent activity for '{query}'",
+ "engagement": {"citations": len(citations)},
+ "metadata": {
+ "citations": citations,
+ "usage": _usage(data),
+ "perplexity_response_id": data.get("id"),
+ },
+ }
+ ]
+ for index, citation in enumerate(citations):
+ items.append(
+ {
+ "id": f"PX{index + 2}",
+ "title": citation["title"] or _domain(citation["url"]),
+ "url": citation["url"],
+ "source_domain": _domain(citation["url"]),
+ "snippet": citation.get("snippet") or "",
+ "date": citation.get("date"),
+ "relevance": 0.7,
+ "why_relevant": f"Cited in Perplexity synthesis for '{query}'",
+ "engagement": {"citations": 1},
+ "metadata": {"citations": [citation]},
+ }
+ )
+ artifact: dict[str, Any] = {
+ "label": "perplexity",
+ "provider": "perplexity",
+ "mode": PERPLEXITY_MODE_AGENT,
+ "endpoint": "agent-background" if deep else "agent",
+ "deep": deep,
+ "query": query,
+ "synthesisLength": len(synthesis),
+ "citationCount": len(citations),
+ "responseId": data.get("id"),
+ "status": data.get("status"),
+ "servedModel": data.get("model"),
+ "usage": _usage(data),
+ "outputTypes": _output_types(data),
+ **selection,
+ }
+ if background_metadata:
+ artifact.update(background_metadata)
+ return items, artifact
+
+
+def _agent_search(
+ query: str,
+ date_range: tuple[str, str],
+ config: dict[str, Any],
+ api_key: str,
+ deep: bool,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ from_date, to_date = date_range
prompt = (
f"What has been happening with {query} between {from_date} and {to_date}? "
"Include specific dates, names, numbers, and sources."
)
-
+ payload, selection = _build_agent_payload(prompt, date_range, config, deep)
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
+ _log(f"Querying Perplexity Agent API for '{query}' ({from_date} to {to_date})")
- json_data = _build_sonar_payload(prompt, model, date_range, config)
- if provider != "perplexity":
- json_data.pop("web_search_options", None)
- json_data.pop("reasoning_effort", None)
+ try:
+ if deep:
+ data, background_metadata = _poll_agent_background(payload, headers, config)
+ else:
+ data = http.post(
+ PERPLEXITY_AGENT_URL,
+ payload,
+ headers=headers,
+ timeout=_agent_timeout(config),
+ retries=1,
+ )
+ background_metadata = None
+ except AgentBackgroundTimeout as exc:
+ _log(f"Agent background request timed out: {exc}")
+ return [], _agent_failure_artifact(
+ query,
+ deep,
+ selection,
+ error="timeout",
+ metadata=exc.metadata,
+ )
+ except AgentBackgroundFailed as exc:
+ _log(f"Agent background request failed: {exc}")
+ return [], _agent_failure_artifact(
+ query,
+ deep,
+ selection,
+ error="failed",
+ metadata=exc.metadata,
+ )
+ except AgentBackgroundPollError as exc:
+ _log(f"Agent background poll failed: {exc}")
+ return [], _agent_failure_artifact(
+ query,
+ deep,
+ selection,
+ error="poll_error",
+ metadata=exc.metadata,
+ )
- _log(f"Querying {provider} {model} for '{query}' ({from_date} to {to_date})")
+ return _agent_result(
+ query,
+ date_range,
+ deep,
+ data,
+ selection,
+ background_metadata,
+ )
- async_artifact = {}
- if provider == "perplexity" and deep:
- data, async_artifact = _poll_async_sonar(json_data, headers, config)
- else:
- data = http.post(url, json_data, headers=headers, timeout=timeout)
-
- # Parse response
- choices = data.get("choices", [])
- if not choices:
- _log("No choices in response")
- return [], _empty_async_sonar_artifact(
- provider, model, deep, query, data, async_artifact,
- "empty_choices",
- "Async Deep Research completed without choices",
- )
+
+def _openrouter_sonar_search(
+ query: str,
+ date_range: tuple[str, str],
+ api_key: str,
+ deep: bool,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ """Preserve the pre-Agent OpenRouter Sonar compatibility path."""
+ from_date, to_date = date_range
+ model = (
+ OPENROUTER_MODEL_DEEP_RESEARCH
+ if deep
+ else OPENROUTER_MODEL_SONAR_PRO
+ )
+ prompt = (
+ f"What has been happening with {query} between {from_date} and {to_date}? "
+ "Include specific dates, names, numbers, and sources."
+ )
+ payload = {
+ "model": model,
+ "messages": [{"role": "user", "content": prompt}],
+ }
+ headers = {
+ "Authorization": f"Bearer {api_key}",
+ "Content-Type": "application/json",
+ }
+ _log(f"Querying OpenRouter {model} for '{query}' ({from_date} to {to_date})")
+ data = http.post(
+ OPENROUTER_URL,
+ payload,
+ headers=headers,
+ timeout=120 if deep else 30,
+ retries=1,
+ )
+
+ choices = data.get("choices")
+ if not isinstance(choices, list) or not choices:
+ return [], {
+ "label": "perplexity",
+ "provider": "openrouter",
+ "mode": PERPLEXITY_MODE_SONAR,
+ "endpoint": "openrouter-chat-completions",
+ "model": model,
+ "deep": deep,
+ "query": query,
+ "error": "empty_choices",
+ "responseId": data.get("id"),
+ "servedModel": data.get("model") or model,
+ "usage": _usage(data),
+ }
choice = choices[0] if isinstance(choices[0], dict) else {}
message = choice.get("message")
message = message if isinstance(message, dict) else {}
- synthesis = message.get("content") or ""
- if not isinstance(synthesis, str):
- synthesis = ""
+ synthesis = message.get("content")
+ synthesis = synthesis if isinstance(synthesis, str) else ""
if not synthesis:
- _log("Empty synthesis content")
- return [], _empty_async_sonar_artifact(
- provider, model, deep, query, data, async_artifact,
- "empty_synthesis",
- "Async Deep Research completed with empty synthesis",
- )
-
- citations = _extract_citations(data, choice)
-
- _log(f"Got synthesis ({len(synthesis)} chars) with {len(citations)} citations")
-
- # Build items list
- items = []
-
- # Primary item: the synthesis itself
- snippet = synthesis[:2000]
- items.append({
- "id": "PX1",
- "title": f"Perplexity {'Deep Research' if deep else 'Sonar'}: {query}",
- "url": "",
- "source_domain": "perplexity.ai",
- "snippet": snippet,
- "date": to_date,
- "relevance": 0.9,
- "why_relevant": f"AI synthesis of recent activity for '{query}'",
- "engagement": {"citations": len(citations)},
- "metadata": {
- "citations": citations,
+ return [], {
+ "label": "perplexity",
+ "provider": "openrouter",
+ "mode": PERPLEXITY_MODE_SONAR,
+ "endpoint": "openrouter-chat-completions",
+ "model": model,
+ "deep": deep,
+ "query": query,
+ "error": "empty_synthesis",
+ "responseId": data.get("id"),
+ "servedModel": data.get("model") or model,
"usage": _usage(data),
- **async_artifact,
- },
- })
-
- # Individual items for each citation
- for i, cit in enumerate(citations):
- items.append({
- "id": f"PX{i + 2}",
- "title": cit["title"] or _domain(cit["url"]),
- "url": cit["url"],
- "source_domain": _domain(cit["url"]),
- "snippet": cit.get("snippet") or "",
- "date": cit.get("date"),
- "relevance": 0.7,
- "why_relevant": f"Cited in Perplexity synthesis for '{query}'",
- "engagement": {"citations": 1},
- "metadata": {"citations": [cit]},
- })
+ }
- artifact = {
+ citations = _extract_openrouter_citations(data, choice)
+ title_mode = "Deep Research" if deep else "Sonar"
+ items: list[dict[str, Any]] = [
+ {
+ "id": "PX1",
+ "title": f"Perplexity {title_mode}: {query}",
+ "url": "",
+ "source_domain": "perplexity.ai",
+ "snippet": synthesis[:2000],
+ "date": to_date,
+ "relevance": 0.9,
+ "why_relevant": f"AI synthesis of recent activity for '{query}'",
+ "engagement": {"citations": len(citations)},
+ "metadata": {
+ "citations": citations,
+ "usage": _usage(data),
+ "openrouter_response_id": data.get("id"),
+ },
+ }
+ ]
+ for index, citation in enumerate(citations):
+ items.append(
+ {
+ "id": f"PX{index + 2}",
+ "title": citation["title"] or _domain(citation["url"]),
+ "url": citation["url"],
+ "source_domain": _domain(citation["url"]),
+ "snippet": citation.get("snippet") or "",
+ "date": citation.get("date"),
+ "relevance": 0.7,
+ "why_relevant": f"Cited in Perplexity synthesis for '{query}'",
+ "engagement": {"citations": 1},
+ "metadata": {"citations": [citation]},
+ }
+ )
+
+ return items, {
"label": "perplexity",
- "provider": provider,
+ "provider": "openrouter",
"mode": PERPLEXITY_MODE_SONAR,
- "endpoint": "async-sonar" if async_artifact else "sonar",
+ "endpoint": "openrouter-chat-completions",
"model": model,
"deep": deep,
"query": query,
"synthesisLength": len(synthesis),
"citationCount": len(citations),
+ "responseId": data.get("id"),
+ "servedModel": data.get("model") or model,
"usage": _usage(data),
- **async_artifact,
}
- return items, artifact
-
-def _merge_sonar_and_search(sonar_items: list[dict], search_items: list[dict]) -> list[dict]:
- if not sonar_items:
+def _merge_agent_and_search(
+ agent_items: list[dict[str, Any]],
+ search_items: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ if not agent_items:
return search_items
- merged = sonar_items[:1]
+ merged = agent_items[:1]
seen_urls = {item.get("url") for item in merged if item.get("url")}
- for item in [*search_items, *sonar_items[1:]]:
+ for item in [*search_items, *agent_items[1:]]:
url = item.get("url")
if url and url in seen_urls:
continue
@@ -635,111 +1174,147 @@ def _merge_sonar_and_search(sonar_items: list[dict], search_items: list[dict]) -
return merged
+def _top_level_failure(
+ query: str,
+ mode: str,
+ deep: bool,
+ exc: Exception,
+ provider: str = "perplexity",
+) -> dict[str, Any]:
+ artifact = _error_artifact(exc)
+ if provider == "openrouter":
+ endpoint = "openrouter-chat-completions"
+ elif deep:
+ endpoint = "agent-background"
+ elif mode == PERPLEXITY_MODE_SEARCH:
+ endpoint = "search"
+ else:
+ endpoint = "agent"
+ artifact.update(
+ {
+ "label": "perplexity",
+ "provider": provider,
+ "mode": mode,
+ "endpoint": endpoint,
+ "deep": deep,
+ "query": query,
+ }
+ )
+ return artifact
+
+
def search(
query: str,
date_range: tuple[str, str],
- config: dict,
+ config: dict[str, Any],
deep: bool = False,
-) -> tuple[list[dict], dict]:
- """Search via Perplexity Sonar Pro or Deep Research.
-
- Args:
- query: Search topic
- date_range: (from_date, to_date) as YYYY-MM-DD strings
- config: Must contain PERPLEXITY_API_KEY or OPENROUTER_API_KEY
- deep: Use Deep Research model (~$0.90/query) instead of Sonar Pro
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+ """Search through Perplexity's Agent API or raw Search API.
- Returns:
- Tuple of (items list, artifact dict).
+ Normal synthesis uses the controlled Agent profile. Search API mode remains
+ available for raw ranked rows. Deep Research is a dynamic high-preset
+ background run and requires an explicit --deep-research invocation.
"""
- resolved = _provider(config, deep)
+ resolved = _provider(config)
if not resolved:
- _log("No PERPLEXITY_API_KEY or OPENROUTER_API_KEY configured, skipping")
+ _log(
+ "No PERPLEXITY_API_KEY or OPENROUTER_API_KEY configured, skipping"
+ )
return [], {}
- provider, api_key, url, model = resolved
- mode = _mode(config, provider, deep)
+ provider, api_key = resolved
+ mode = _mode(config, deep, provider)
try:
+ if provider == "openrouter":
+ result = _openrouter_sonar_search(
+ query,
+ date_range,
+ api_key,
+ deep,
+ )
+ if deep:
+ _log_deep_receipt(result[1])
+ return result
if mode == PERPLEXITY_MODE_SEARCH:
return _search_api(query, date_range, config, api_key)
if mode == PERPLEXITY_MODE_BOTH:
- search_items: list[dict] = []
- sonar_items: list[dict] = []
- search_artifact: dict = {}
- sonar_artifact: dict = {}
+ search_items: list[dict[str, Any]] = []
+ agent_items: list[dict[str, Any]] = []
+ search_artifact: dict[str, Any] = {}
+ agent_artifact: dict[str, Any] = {}
try:
- search_items, search_artifact = _search_api(query, date_range, config, api_key)
- except Exception as e:
- _log(f"Search API leg failed in both mode: {e}")
- search_artifact = _error_artifact(e)
+ search_items, search_artifact = _search_api(
+ query,
+ date_range,
+ config,
+ api_key,
+ )
+ except Exception as exc:
+ _log(f"Search API leg failed in both mode: {exc}")
+ search_artifact = _error_artifact(exc)
try:
- sonar_items, sonar_artifact = _sonar_search(
- query, date_range, config, provider, api_key, url, model, deep
+ agent_items, agent_artifact = _agent_search(
+ query,
+ date_range,
+ config,
+ api_key,
+ deep=False,
)
- except Exception as e:
- _log(f"Sonar leg failed in both mode: {e}")
- sonar_artifact = _error_artifact(e)
- items = _merge_sonar_and_search(sonar_items, search_items)
+ except Exception as exc:
+ _log(f"Agent API leg failed in both mode: {exc}")
+ agent_artifact = _error_artifact(exc)
+ items = _merge_agent_and_search(agent_items, search_items)
return items, {
"label": "perplexity",
"provider": "perplexity",
"mode": PERPLEXITY_MODE_BOTH,
"query": query,
"search": search_artifact,
- "sonar": sonar_artifact,
+ "agent": agent_artifact,
"itemCount": len(items),
}
- return _sonar_search(query, date_range, config, provider, api_key, url, model, deep)
- except http.HTTPError as e:
- if e.status_code == 401:
+ result = _agent_search(query, date_range, config, api_key, deep)
+ if deep:
+ _log_deep_receipt(result[1])
+ return result
+ except http.HTTPError as exc:
+ if exc.status_code == 401:
_log(f"Invalid {provider} API key (401)")
- elif e.status_code == 429:
+ elif exc.status_code == 429:
_log(f"Rate limited by {provider} (429)")
else:
- _log(f"HTTP error: {e}")
- return [], {}
- except AsyncDeepResearchTimeout as e:
- _log(f"Request timed out: {e}")
- return [], {
- "label": "perplexity",
- "provider": provider,
- "mode": PERPLEXITY_MODE_SONAR,
- "endpoint": "async-sonar",
- "model": model,
- "deep": deep,
- "query": query,
- "error": "timeout",
- **e.metadata,
- }
- except AsyncDeepResearchFailed as e:
- _log(f"Deep Research failed: {e}")
- return [], {
- "label": "perplexity",
- "provider": provider,
- "mode": PERPLEXITY_MODE_SONAR,
- "endpoint": "async-sonar",
- "model": model,
- "deep": deep,
- "query": query,
- "error": "failed",
- **e.metadata,
- }
- except AsyncDeepResearchPollError as e:
- _log(f"Deep Research poll failed: {e}")
- return [], {
- "label": "perplexity",
- "provider": provider,
- "mode": PERPLEXITY_MODE_SONAR,
- "endpoint": "async-sonar",
- "model": model,
- "deep": deep,
- "query": query,
- "error": "poll_error",
- **e.metadata,
- }
- except TimeoutError as e:
- _log(f"Request timed out: {e}")
- return [], {"label": "perplexity", "provider": provider, "error": "timeout"}
- except Exception as e:
- _log(f"Request failed: {e}")
- return [], {}
+ _log(f"HTTP error: {exc}")
+ artifact = _top_level_failure(
+ query,
+ mode,
+ deep,
+ exc,
+ provider=provider,
+ )
+ if deep:
+ _log_deep_receipt(artifact)
+ return [], artifact
+ except TimeoutError as exc:
+ _log(f"Request timed out: {exc}")
+ artifact = _top_level_failure(
+ query,
+ mode,
+ deep,
+ exc,
+ provider=provider,
+ )
+ if deep:
+ _log_deep_receipt(artifact)
+ return [], artifact
+ except Exception as exc:
+ _log(f"Request failed: {exc}")
+ artifact = _top_level_failure(
+ query,
+ mode,
+ deep,
+ exc,
+ provider=provider,
+ )
+ if deep:
+ _log_deep_receipt(artifact)
+ return [], artifact
diff --git a/skills/last30days/scripts/lib/pipeline.py b/skills/last30days/scripts/lib/pipeline.py
index 5c40da43..7dba5e9e 100644
--- a/skills/last30days/scripts/lib/pipeline.py
+++ b/skills/last30days/scripts/lib/pipeline.py
@@ -108,6 +108,49 @@ MAX_SOURCE_FETCHES: dict[str, int] = {
"x": 2, "jobs": 1, "linkedin": 1, "stocktwits": 1, "trustpilot": 1, "amazon": 1,
}
+_FAILURE_SPECIFICITY = {
+ health.AUTH_FAILED: 0,
+ health.RATE_LIMITED: 1,
+ health.SCHEMA_DRIFT: 2,
+ health.TIMEOUT: 3,
+ health.UNREACHABLE: 4,
+ health.ERROR: 5,
+}
+
+
+@dataclass
+class PaidSourceBudget:
+ """Command-wide, thread-safe budget for paid source adapter calls."""
+
+ used: int = 0
+ owner: str | None = None
+ _lock: Any = field(default_factory=threading.Lock, repr=False)
+
+ def try_consume(self, limit: int, *, claimant: str | None = None) -> bool:
+ with self._lock:
+ if self.owner is not None and claimant != self.owner:
+ return False
+ if self.used >= limit:
+ return False
+ self.used += 1
+ return True
+
+
+def _source_fetch_cap(source: str, config: dict[str, Any]) -> int | None:
+ """Return the effective per-run cap for one source.
+
+ Every Perplexity adapter call is paid, and ``both`` performs two paid POSTs.
+ A generic fetch-cap override must not multiply either normal or Deep
+ Research mode across planner subqueries.
+ """
+ override = config.get("_max_source_fetches")
+ if source == "perplexity":
+ return 1 if override is None else min(1, int(override))
+ cap = MAX_SOURCE_FETCHES.get(source)
+ if cap is not None and override is not None:
+ return int(override)
+ return cap
+
def _resolve_depth_settings(depth: str, config: dict[str, Any]) -> dict[str, int]:
"""Depth profile with optional CLI cap overrides applied (issue #716).
@@ -140,7 +183,11 @@ RELATED_HANDLE_COUNT_PER = 3
def _has_perplexity_provider(config: dict[str, Any]) -> bool:
- return bool(config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY"))
+ # Prefer direct Agent/Search APIs, but preserve the synchronous OpenRouter
+ # Sonar fallback for existing installs.
+ return bool(
+ config.get("PERPLEXITY_API_KEY") or config.get("OPENROUTER_API_KEY")
+ )
MOCK_AVAILABLE_SOURCES = [
"reddit",
@@ -264,7 +311,7 @@ def available_sources(
available.append("grounding")
if requested_sources and "jobs" in requested_sources:
available.append("jobs")
- # Perplexity Sonar: opt-in additive source via INCLUDE_SOURCES=perplexity
+ # Perplexity Agent API: opt-in additive source via INCLUDE_SOURCES=perplexity
if _has_perplexity_provider(config) and (
"perplexity" in include_sources or (requested_sources and "perplexity" in requested_sources)
):
@@ -2070,6 +2117,17 @@ def run(
plan.source_weights["corpus"] = 1.0
plan.source_weights = planner._normalize_weights(plan.source_weights)
+ # Add the paid-only Perplexity lane after all normal-source safety nets.
+ # This preserves the planner's primary subquery, gives the bounded paid
+ # call the whole user topic, and prevents grounding, jobs, or corpus from
+ # being attached to the dedicated lane.
+ _ensure_perplexity_in_plan(
+ plan,
+ topic,
+ available,
+ force=bool(config.get("_deep_research")),
+ )
+
# Always-on planner trace. Emits one summary line plus one per subquery
# so retrieval-breadth failures like the 2026-04-19 Hermes Agent Use Cases
# disaster are visible without --debug. Stderr only; does not leak into
@@ -2290,16 +2348,31 @@ def run(
# Enforce per-source fetch cap. A CLI override (issue #716) raises
# the cap for capped sources so every X subquery in a multi-angle
# --plan fetches, instead of only the first two.
- cap = MAX_SOURCE_FETCHES.get(source)
- _cap_override = config.get("_max_source_fetches")
- if cap is not None and _cap_override is not None:
- # `is not None` so --max-source-fetches 0 (disable fetching a
- # capped source) is honored instead of falling back to default.
- cap = int(_cap_override)
+ cap = _source_fetch_cap(source, config)
if cap is not None:
+ if cap <= 0:
+ continue
current = source_fetch_count.get(source, 0)
if current >= cap:
continue
+ shared_paid_budget = config.get("_perplexity_paid_budget")
+ if (
+ source == "perplexity"
+ and isinstance(shared_paid_budget, PaidSourceBudget)
+ and not shared_paid_budget.try_consume(
+ cap,
+ claimant=topic,
+ )
+ ):
+ bundle.artifacts.setdefault("paid_source_budget", {})[
+ "perplexity"
+ ] = {
+ "state": "skipped-budget",
+ "attempted": False,
+ "owner": shared_paid_budget.owner,
+ "claimant": topic,
+ }
+ continue
source_fetch_count[source] = current + 1
bundle.mark_attempted(source)
futures[
@@ -3034,6 +3107,46 @@ def _ensure_jobs_in_plan(
subquery.sources.append("jobs")
+def _ensure_perplexity_in_plan(
+ plan: schema.QueryPlan,
+ topic: str,
+ available: list[str],
+ *,
+ force: bool,
+) -> None:
+ """Route a bounded paid Perplexity action through the whole topic.
+
+ Deep Research forces its explicit lane. Normal modes are rerouted only when
+ the sanitized plan already selected Perplexity.
+ """
+ if "perplexity" not in available:
+ return
+ planned = any(
+ "perplexity" in subquery.sources for subquery in plan.subqueries
+ )
+ if not force and not planned:
+ return
+ retained: list[schema.SubQuery] = []
+ for subquery in plan.subqueries:
+ sources = [
+ source for source in subquery.sources if source != "perplexity"
+ ]
+ if sources:
+ retained.append(replace(subquery, sources=sources))
+ retained.append(
+ schema.SubQuery(
+ label="deep-research" if force else "perplexity-whole-topic",
+ search_query=topic,
+ ranking_query=f"What current source-grounded evidence matters for {topic}?",
+ sources=["perplexity"],
+ weight=1.0,
+ ),
+ )
+ plan.subqueries = planner._normalize_subquery_weights(retained)
+ plan.source_weights.setdefault("perplexity", 1.0)
+ plan.source_weights = planner._normalize_weights(plan.source_weights)
+
+
def _company_topic_likely(topic: str) -> bool:
text = topic.strip()
if not text:
@@ -3201,22 +3314,45 @@ def _legacy_artifact_outcome(
explicit = artifact.get("_source_outcome")
if isinstance(explicit, dict):
return explicit
- if source == "perplexity" and artifact.get("error"):
- error = str(artifact["error"])
- detail = str(
- artifact.get("asyncErrorMessage")
- or artifact.get("message")
- or error
- )
- state = (
- health.TIMEOUT
- if error.lower() == "timeout"
- else http.classify_failure(
- status_code=artifact.get("statusCode"),
- message=f"{error}: {detail}",
+ if source == "perplexity":
+ candidates: list[tuple[str | None, dict[str, Any]]] = [(None, artifact)]
+ if artifact.get("mode") == "both":
+ for leg in ("search", "agent"):
+ value = artifact.get(leg)
+ if isinstance(value, dict):
+ candidates.append((leg, value))
+ outcomes: list[dict[str, Any]] = []
+ for leg, candidate in candidates:
+ if not candidate.get("error"):
+ continue
+ error = str(candidate["error"])
+ detail = str(
+ candidate.get("backgroundErrorMessage")
+ or candidate.get("backgroundPollError")
+ or candidate.get("agentErrorMessage")
+ or candidate.get("asyncErrorMessage")
+ or candidate.get("message")
+ or error
+ )
+ if leg:
+ detail = f"{leg} leg: {detail}"
+ status_code = candidate.get("statusCode")
+ if status_code is None:
+ status_code = candidate.get("backgroundPollStatusCode")
+ state = (
+ health.TIMEOUT
+ if error.lower() == "timeout"
+ else http.classify_failure(
+ status_code=status_code,
+ message=f"{error}: {detail}",
+ )
+ )
+ outcomes.append(_outcome_artifact(state, detail)["_source_outcome"])
+ if outcomes:
+ return min(
+ outcomes,
+ key=lambda outcome: _FAILURE_SPECIFICITY.get(outcome["state"], 9),
)
- )
- return _outcome_artifact(state, detail)["_source_outcome"]
if (
source == "grounding"
and artifact.get("reason") == "keyless-search-unavailable"
@@ -3240,14 +3376,6 @@ def _resolve_stream_outcome(
# Pick the most specific failure rather than the last-appended one:
# parallel workers append in nondeterministic order, and an auth failure
# must not be masked by a later 429 (wrong doctor prescription).
- _FAILURE_SPECIFICITY = {
- health.AUTH_FAILED: 0,
- health.RATE_LIMITED: 1,
- health.SCHEMA_DRIFT: 2,
- health.TIMEOUT: 3,
- health.UNREACHABLE: 4,
- health.ERROR: 5,
- }
failure = min(
failures,
key=lambda f: _FAILURE_SPECIFICITY.get(f.outcome_state, 9),
@@ -3795,7 +3923,7 @@ def _retry_thin_sources(
# MAX_SOURCE_FETCHES and re-resolving WITHOUT the caller's
# --trustpilot-domain (a lookalike-misattribution path). Its thin result
# is its normal success state; never retry it here.
- _skip = (skip_sources or set()) | {"trustpilot"}
+ _skip = (skip_sources or set()) | {"trustpilot", "perplexity"}
thin_sources = [
source
for source in planned_sources
@@ -4905,4 +5033,3 @@ def _mock_stream_results(source: str, subquery: schema.SubQuery) -> tuple[list[d
"resultCount": 1,
}
return payloads.get(source, []), {}
-
diff --git a/tests/test_cli_v3.py b/tests/test_cli_v3.py
index 2ec657dd..4714fa65 100644
--- a/tests/test_cli_v3.py
+++ b/tests/test_cli_v3.py
@@ -2,6 +2,7 @@
import contextlib
import json
import io
+import os
import shutil
import tempfile
import subprocess
@@ -131,7 +132,7 @@ class CliV3Tests(unittest.TestCase):
)
self.assertIn("threads", available)
- def test_explicit_perplexity_search_uses_openrouter_key_without_include_sources(self):
+ def test_explicit_perplexity_search_uses_openrouter_fallback(self):
available = cli.pipeline.available_sources(
{"OPENROUTER_API_KEY": "test-key", "INCLUDE_SOURCES": ""},
requested_sources=["perplexity"],
@@ -179,6 +180,38 @@ class CliV3Tests(unittest.TestCase):
)
self.assertIn("LAST30DAYS_DEFAULT_SEARCH", str(exc.exception))
+ def test_deep_research_preserves_default_source_selection(self):
+ self.assertIsNone(cli.add_deep_research_source(None))
+
+ def test_deep_research_extends_an_explicit_source_selection(self):
+ self.assertEqual(
+ ["reddit", "perplexity"],
+ cli.add_deep_research_source(["reddit"]),
+ )
+ self.assertEqual(
+ ["reddit", "perplexity"],
+ cli.add_deep_research_source(["reddit", "perplexity"]),
+ )
+
+ def test_deep_research_enables_exact_include_token(self):
+ config = {"INCLUDE_SOURCES": "notperplexity,reddit"}
+
+ cli.enable_deep_research_source(config)
+
+ self.assertEqual(
+ ["notperplexity", "reddit", "perplexity"],
+ config["INCLUDE_SOURCES"].split(","),
+ )
+
+ def test_deep_research_rejects_exact_exclusion(self):
+ config = {"EXCLUDE_SOURCES": "reddit,Perplexity"}
+
+ with self.assertRaisesRegex(
+ ValueError,
+ "conflicts with EXCLUDE_SOURCES=perplexity",
+ ):
+ cli.enable_deep_research_source(config)
+
def test_build_parser_accepts_days_alias_and_preserves_topic_tokens(self):
parser = cli.build_parser()
args, extra = parser.parse_known_args(["--days", "7", "biosecurity", "ai", "agents"])
@@ -194,6 +227,162 @@ class CliV3Tests(unittest.TestCase):
self.assertEqual("keyless", args.web_backend)
self.assertEqual([], extra)
+ def test_deep_research_help_keeps_openrouter_fallback(self):
+ parser = cli.build_parser()
+ action = next(
+ candidate
+ for candidate in parser._actions
+ if "--deep-research" in candidate.option_strings
+ )
+ self.assertIn("PERPLEXITY_API_KEY", action.help)
+ self.assertIn("OPENROUTER_API_KEY", action.help)
+ self.assertIn("cannot be combined with competitor or vs-mode", action.help)
+
+ def test_deep_research_rejects_modes_without_a_positional_topic(self):
+ for argv in (
+ ["last30days.py", "--discover", "agents", "--deep-research"],
+ ["last30days.py", "--drill", "cluster-1", "--deep-research"],
+ ):
+ with self.subTest(argv=argv), mock.patch.object(
+ cli.env,
+ "get_config",
+ return_value={},
+ ), mock.patch.object(
+ cli,
+ "_run_discover",
+ ) as discover_mock, mock.patch.object(
+ cli,
+ "_run_drill",
+ ) as drill_mock, mock.patch.dict(
+ os.environ,
+ {"LAST30DAYS_SKIP_PREFLIGHT": "1"},
+ clear=False,
+ ), mock.patch.object(sys, "argv", argv):
+ stderr = io.StringIO()
+ with redirect_stderr(stderr):
+ rc = cli.main()
+
+ self.assertEqual(2, rc)
+ discover_mock.assert_not_called()
+ drill_mock.assert_not_called()
+ self.assertIn("requires a normal positional topic", stderr.getvalue())
+
+ def test_deep_research_rejects_competitor_fanout_before_pipeline_run(self):
+ diag = {
+ "available_sources": ["perplexity"],
+ "providers": {"google": False, "openai": False, "xai": False},
+ "x_backend": None,
+ "bird_installed": True,
+ "bird_authenticated": False,
+ "bird_username": None,
+ "native_web_backend": None,
+ }
+ with mock.patch.object(
+ cli.env,
+ "get_config",
+ return_value={"PERPLEXITY_API_KEY": "pplx-test"},
+ ), mock.patch.object(
+ cli.pipeline,
+ "diagnose",
+ return_value=diag,
+ ) as diagnose_mock, mock.patch.object(
+ cli.pipeline,
+ "run",
+ ) as run_mock, mock.patch.object(
+ cli.ui,
+ "ProgressDisplay",
+ return_value=mock.Mock(),
+ ), mock.patch.object(
+ sys,
+ "argv",
+ [
+ "last30days.py",
+ "Alpha",
+ "vs",
+ "Beta",
+ "--mock",
+ "--deep-research",
+ ],
+ ):
+ stderr = io.StringIO()
+ with redirect_stderr(stderr):
+ rc = cli.main()
+
+ self.assertEqual(2, rc)
+ diagnose_mock.assert_not_called()
+ run_mock.assert_not_called()
+ self.assertIn(
+ "one paid Deep Research run per user action",
+ stderr.getvalue(),
+ )
+
+ def test_openrouter_deep_research_bypasses_hosted_and_adds_source(self):
+ report = self.make_report(topic="why AI safety matters")
+ diag = {
+ "available_sources": ["reddit", "perplexity"],
+ "providers": {"google": False, "openai": False, "xai": False},
+ "x_backend": None,
+ "bird_installed": True,
+ "bird_authenticated": False,
+ "bird_username": None,
+ "native_web_backend": None,
+ }
+ with mock.patch.object(
+ cli.env,
+ "get_config",
+ return_value={"OPENROUTER_API_KEY": "openrouter-test"},
+ ), mock.patch.object(
+ cli.env,
+ "read_secret_env",
+ return_value="hosted-test-key",
+ ), mock.patch.object(
+ cli.pipeline,
+ "diagnose",
+ return_value=diag,
+ ), mock.patch.object(
+ cli.pipeline,
+ "run",
+ return_value=report,
+ ) as run_mock, mock.patch(
+ "lib.hosted.run_hosted",
+ ) as hosted_mock, mock.patch.object(
+ cli.ui,
+ "ProgressDisplay",
+ return_value=mock.Mock(),
+ ), mock.patch.object(
+ cli,
+ "emit_output",
+ return_value="# rendered",
+ ), mock.patch.dict(
+ os.environ,
+ {
+ "LAST30DAYS_API_BASE": "https://hosted.example.test",
+ "LAST30DAYS_SKIP_PREFLIGHT": "1",
+ },
+ clear=False,
+ ), mock.patch.object(
+ sys,
+ "argv",
+ [
+ "last30days.py",
+ "why",
+ "AI",
+ "safety",
+ "matters",
+ "--deep-research",
+ "--search",
+ "reddit",
+ ],
+ ):
+ with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+ rc = cli.main()
+
+ self.assertEqual(0, rc)
+ hosted_mock.assert_not_called()
+ requested_sources = run_mock.call_args.kwargs["requested_sources"]
+ self.assertEqual(["reddit", "perplexity"], requested_sources)
+ self.assertTrue(run_mock.call_args.kwargs["config"]["_deep_research"])
+
def test_build_parser_still_accepts_other_web_backend_values(self):
parser = cli.build_parser()
for value in ("auto", "brave", "exa", "serper", "parallel", "none"):
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
index b523194f..5aa8b0a0 100644
--- a/tests/test_doctor.py
+++ b/tests/test_doctor.py
@@ -202,6 +202,30 @@ class KeylessEnvironment(unittest.TestCase):
self.assertIn("last30days doctor", out)
+class PerplexityKeyBoundary(unittest.TestCase):
+ def test_openrouter_only_enables_sonar_fallback(self):
+ record = _build(
+ {
+ "OPENROUTER_API_KEY": "dummy-openrouter-secret-000",
+ "INCLUDE_SOURCES": "perplexity",
+ }
+ )["sources"]["perplexity"]
+
+ self.assertEqual("ok", record["status"])
+ self.assertIn("PERPLEXITY_API_KEY", record["requires"])
+ self.assertIn("OPENROUTER_API_KEY", record["requires"])
+
+ def test_direct_perplexity_key_with_opt_in_is_ready(self):
+ record = _build(
+ {
+ "PERPLEXITY_API_KEY": "dummy-perplexity-secret-000",
+ "INCLUDE_SOURCES": "perplexity",
+ }
+ )["sources"]["perplexity"]
+
+ self.assertEqual("ok", record["status"])
+
+
class GitHubAuthDetection(unittest.TestCase):
"""GitHub doctor auth must mirror the real fetcher token source."""
diff --git a/tests/test_env_v3.py b/tests/test_env_v3.py
index 1544c5bc..7d4d1882 100644
--- a/tests/test_env_v3.py
+++ b/tests/test_env_v3.py
@@ -50,6 +50,11 @@ class EnvV3Tests(unittest.TestCase):
overrides = {
"LAST30DAYS_PERPLEXITY_MODE": "search",
"LAST30DAYS_PERPLEXITY_MODEL": "sonar-reasoning-pro",
+ "LAST30DAYS_PERPLEXITY_AGENT_MODEL": "perplexity/sonar",
+ "LAST30DAYS_PERPLEXITY_AGENT_PRESET": "low",
+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "4",
+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS": "8192",
+ "LAST30DAYS_PERPLEXITY_AGENT_TIMEOUT_SECONDS": "120",
"LAST30DAYS_PERPLEXITY_MAX_RESULTS": "3",
"LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE": "low",
"LAST30DAYS_PERPLEXITY_SEARCH_MODE": "academic",
diff --git a/tests/test_http_v3.py b/tests/test_http_v3.py
index 3702df01..29af27e0 100644
--- a/tests/test_http_v3.py
+++ b/tests/test_http_v3.py
@@ -1,5 +1,6 @@
import urllib.error
import unittest
+import time
from unittest.mock import patch, MagicMock
from lib import http
@@ -38,6 +39,91 @@ class Test429RetryLimit(unittest.TestCase):
self.assertEqual(mock_urlopen.call_count, 3)
+ @patch("lib.http.urllib.request.urlopen")
+ @patch("lib.http.time.sleep")
+ @patch("lib.http.time.monotonic", side_effect=[0.0, 0.5, 0.5])
+ def test_shared_deadline_stops_retry_before_backoff_crosses_it(
+ self,
+ _mock_monotonic,
+ mock_sleep,
+ mock_urlopen,
+ ):
+ mock_urlopen.side_effect = urllib.error.HTTPError(
+ "http://example.com", 500, "Internal Server Error", {}, None
+ )
+
+ with self.assertRaises(http.HTTPError) as caught:
+ http.request(
+ "GET",
+ "http://example.com",
+ retries=3,
+ deadline_monotonic=1.0,
+ )
+
+ self.assertEqual(http.health.TIMEOUT, caught.exception.outcome_state)
+ self.assertEqual(1, mock_urlopen.call_count)
+ mock_sleep.assert_not_called()
+
+ @patch("lib.http.urllib.request.urlopen")
+ @patch("lib.http.time.monotonic", side_effect=[0.0, 0.5, 1.5])
+ def test_shared_deadline_rejects_response_that_finishes_late(
+ self,
+ _mock_monotonic,
+ mock_urlopen,
+ ):
+ mock_urlopen.return_value = _mock_response()
+
+ with self.assertRaises(http.DeadlineExceeded):
+ http.request(
+ "GET",
+ "http://example.com",
+ retries=1,
+ deadline_monotonic=1.0,
+ )
+
+ @patch("lib.http.urllib.request.urlopen")
+ def test_shared_deadline_stops_waiting_during_slow_body_read(
+ self,
+ mock_urlopen,
+ ):
+ response = _mock_response()
+
+ def slow_read():
+ time.sleep(0.2)
+ return b'{"ok": true}'
+
+ response.read.side_effect = slow_read
+ mock_urlopen.return_value = response
+ started = time.monotonic()
+
+ with self.assertRaises(http.DeadlineExceeded):
+ http.request(
+ "GET",
+ "http://example.com",
+ retries=1,
+ deadline_monotonic=started + 0.02,
+ )
+
+ self.assertLess(time.monotonic() - started, 0.12)
+
+ @patch("lib.http.urllib.request.urlopen")
+ def test_worker_socket_timeout_is_not_wall_deadline_expiration(
+ self,
+ mock_urlopen,
+ ):
+ mock_urlopen.side_effect = TimeoutError("early socket timeout")
+
+ with self.assertRaises(http.HTTPError) as caught:
+ http.request(
+ "GET",
+ "http://example.com",
+ retries=1,
+ deadline_monotonic=time.monotonic() + 600,
+ )
+
+ self.assertNotIsInstance(caught.exception, http.DeadlineExceeded)
+ self.assertEqual(http.health.TIMEOUT, caught.exception.outcome_state)
+
def _mock_response(body: str = '{"ok": true}', status: int = 200):
resp = MagicMock()
diff --git a/tests/test_last_run_state.py b/tests/test_last_run_state.py
index 3efb47be..2491539f 100644
--- a/tests/test_last_run_state.py
+++ b/tests/test_last_run_state.py
@@ -185,6 +185,43 @@ class LastRunStateTests(unittest.TestCase):
self.assertIn("Cached synthesis body.", stdout.getvalue())
self.assertIn("Reusing cached report data", stderr.getvalue())
+ def test_deep_research_bypasses_html_synthesis_cache(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ config_dir = Path(tmp) / "config"
+ synthesis_path = Path(tmp) / "synthesis.md"
+ synthesis_path.write_text("# Cached synthesis", encoding="utf-8")
+ with mock.patch.object(cli.env, "CONFIG_DIR", config_dir):
+ cli._write_last_run("OpenClaw", _report("OpenClaw"))
+
+ fresh_report = _report("OpenClaw")
+ config = {"OPENROUTER_API_KEY": "or-test"}
+ with mock.patch.object(cli.env, "CONFIG_DIR", config_dir), \
+ mock.patch.object(cli.env, "get_config", return_value=config), \
+ mock.patch.object(cli.pipeline, "diagnose", return_value=_diag()), \
+ mock.patch.object(cli.pipeline, "run", return_value=fresh_report) as run_mock, \
+ mock.patch.object(cli.ui, "ProgressDisplay"), \
+ mock.patch.object(cli, "_load_last_report_cache") as cache_mock, \
+ mock.patch.object(sys, "argv", [
+ "last30days.py",
+ "OpenClaw",
+ "--deep-research",
+ "--emit=html",
+ "--synthesis-file",
+ str(synthesis_path),
+ ]), \
+ mock.patch.dict(
+ os.environ,
+ {"LAST30DAYS_SKIP_PREFLIGHT": "1"},
+ clear=False,
+ ):
+ with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+ rc = cli.main()
+
+ self.assertEqual(0, rc)
+ cache_mock.assert_not_called()
+ run_mock.assert_called_once()
+ self.assertTrue(run_mock.call_args.kwargs["config"]["_deep_research"])
+
def test_html_synthesis_reuses_cached_comparison_reports(self):
with tempfile.TemporaryDirectory() as tmp:
config_dir = Path(tmp) / "config"
diff --git a/tests/test_perplexity.py b/tests/test_perplexity.py
index bba4cbc5..7e983a21 100644
--- a/tests/test_perplexity.py
+++ b/tests/test_perplexity.py
@@ -4,106 +4,387 @@ from unittest.mock import patch
from lib import perplexity
-class PerplexityProviderTests(unittest.TestCase):
- def test_direct_perplexity_key_wins_and_parses_search_results(self):
- response = {
- "choices": [{"message": {"content": "Direct synthesis"}}],
- "citations": ["https://example.com/a"],
- "search_results": [
+def _agent_response(
+ text: str = "Agent synthesis",
+ *,
+ response_id: str = "agent-1",
+ status: str = "completed",
+ model: str = "perplexity/sonar",
+ citations: list[dict] | None = None,
+ include_output_text: bool = True,
+) -> dict:
+ citation_parts = [
+ {
+ "type": "output_text",
+ "text": text,
+ "annotations": [
{
- "title": "Example A",
- "url": "https://example.com/a",
- "date": "2026-06-01",
- "snippet": "Direct source snippet",
- "source": "web",
+ "url_citation": {
+ "url": citation["url"],
+ "title": citation.get("title", ""),
+ }
}
+ for citation in citations or []
],
}
+ ]
+ response = {
+ "id": response_id,
+ "status": status,
+ "model": model,
+ "output": [
+ {"type": "message", "content": citation_parts},
+ {"type": "search_results", "results": citations or []},
+ ],
+ "usage": {"total_tokens": 123},
+ }
+ if include_output_text:
+ response["output_text"] = text
+ return response
+
+
+class PerplexityAgentTests(unittest.TestCase):
+ def test_controlled_agent_uses_direct_key_and_explicit_web_search(self):
+ citations = [
+ {
+ "title": "Example A",
+ "url": "https://example.com/a",
+ "date": "2026-06-01",
+ "snippet": "Direct source snippet",
+ }
+ ]
+ response = _agent_response("Direct synthesis", citations=citations)
+ config = {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "OPENROUTER_API_KEY": "or-test",
+ "LAST30DAYS_PERPLEXITY_MAX_RESULTS": "3",
+ "LAST30DAYS_PERPLEXITY_SEARCH_CONTEXT_SIZE": "low",
+ "LAST30DAYS_PERPLEXITY_COUNTRY": "us",
+ "LAST30DAYS_PERPLEXITY_DOMAIN_FILTER": "example.com,example.org",
+ "LAST30DAYS_PERPLEXITY_RECENCY_FILTER": "year",
+ "LAST30DAYS_PERPLEXITY_REASONING_EFFORT": "high",
+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "4",
+ }
with patch("lib.perplexity.http.post", return_value=response) as post:
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
- {
- "PERPLEXITY_API_KEY": "pplx-test",
- "OPENROUTER_API_KEY": "or-test",
- },
+ config,
)
url, payload = post.call_args.args[:2]
headers = post.call_args.kwargs["headers"]
- self.assertEqual(perplexity.PERPLEXITY_URL, url)
+ tool = payload["tools"][0]
+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, url)
self.assertEqual("Bearer pplx-test", headers["Authorization"])
- self.assertEqual("sonar-pro", payload["model"])
+ self.assertEqual(1, post.call_args.kwargs["retries"])
+ self.assertEqual("perplexity/sonar", payload["model"])
+ self.assertIn("input", payload)
+ self.assertIn("instructions", payload)
+ self.assertEqual(4, payload["max_steps"])
+ self.assertEqual({"effort": "high"}, payload["reasoning"])
+ self.assertEqual({"type": "web_search"}, payload["tool_choice"])
+ self.assertEqual("web_search", tool["type"])
+ self.assertEqual(3, tool["max_results"])
+ self.assertEqual("low", tool["search_context_size"])
+ self.assertEqual({"country": "US"}, tool["user_location"])
self.assertEqual(
- "05/01/2026",
- payload["web_search_options"]["search_after_date_filter"],
+ ["example.com", "example.org"],
+ tool["filters"]["search_domain_filter"],
)
+ self.assertEqual("05/01/2026", tool["filters"]["search_after_date_filter"])
+ self.assertEqual("06/01/2026", tool["filters"]["search_before_date_filter"])
+ self.assertNotIn("search_recency_filter", tool["filters"])
+ self.assertNotIn("preset", payload)
+
+ self.assertEqual("perplexity", artifact["provider"])
+ self.assertEqual("agent", artifact["mode"])
+ self.assertEqual("agent", artifact["endpoint"])
+ self.assertEqual("perplexity/sonar", artifact["model"])
+ self.assertEqual(perplexity.PERPLEXITY_CONTROLLED_PROFILE, artifact["profile"])
+ self.assertFalse(artifact["dynamicPreset"])
+ self.assertEqual("agent-1", artifact["responseId"])
+ self.assertEqual("perplexity/sonar", artifact["servedModel"])
+ self.assertEqual(["message", "search_results"], artifact["outputTypes"])
+ self.assertNotIn("input", artifact["request"])
+ self.assertNotIn("instructions", artifact["request"])
+ self.assertEqual({"effort": "high"}, artifact["request"]["reasoning"])
self.assertEqual(
- "06/01/2026",
- payload["web_search_options"]["search_before_date_filter"],
+ {"type": "web_search"},
+ artifact["request"]["tool_choice"],
)
- self.assertEqual("perplexity", artifact["provider"])
- self.assertEqual("sonar-pro", artifact["model"])
self.assertEqual("Example A", items[1]["title"])
self.assertEqual("Direct source snippet", items[1]["snippet"])
- def test_direct_model_config_selects_supported_sonar_model(self):
- response = {
- "choices": [{"message": {"content": "Reasoned synthesis"}}],
- "citations": [],
- "search_results": [],
- }
+ def test_legacy_sonar_mode_is_an_agent_alias(self):
+ response = _agent_response()
with patch("lib.perplexity.http.post", return_value=response) as post:
_, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
{
"PERPLEXITY_API_KEY": "pplx-test",
- "LAST30DAYS_PERPLEXITY_MODEL": "sonar-reasoning-pro",
- "LAST30DAYS_PERPLEXITY_REASONING_EFFORT": "high",
+ "LAST30DAYS_PERPLEXITY_MODE": "sonar",
+ "LAST30DAYS_PERPLEXITY_MODEL": "sonar-pro",
+ },
+ )
+
+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args.args[0])
+ self.assertEqual(1, post.call_args.kwargs["retries"])
+ self.assertEqual("perplexity/sonar", post.call_args.args[1]["model"])
+ self.assertEqual("agent", artifact["mode"])
+
+ def test_controlled_agent_max_steps_clamps_to_local_safety_limit(self):
+ payload, _ = perplexity._build_agent_payload(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"LAST30DAYS_PERPLEXITY_AGENT_MAX_STEPS": "100"},
+ deep=False,
+ )
+
+ self.assertEqual(15, payload["max_steps"])
+
+ def test_explicit_anthropic_model_gets_required_output_token_budget(self):
+ payload, selection = perplexity._build_agent_payload(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {
+ "LAST30DAYS_PERPLEXITY_AGENT_MODEL": "anthropic/claude-sonnet-4-6",
+ "LAST30DAYS_PERPLEXITY_AGENT_MAX_OUTPUT_TOKENS": "8192",
+ },
+ deep=False,
+ )
+
+ self.assertEqual(8192, payload["max_output_tokens"])
+ self.assertEqual(8192, selection["request"]["max_output_tokens"])
+
+ def test_non_anthropic_model_omits_output_token_override(self):
+ payload, _ = perplexity._build_agent_payload(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {},
+ deep=False,
+ )
+
+ self.assertNotIn("max_output_tokens", payload)
+
+ def test_explicit_agent_preset_is_marked_dynamic(self):
+ response = _agent_response(model="openai/gpt-5.6-luna")
+ with patch("lib.perplexity.http.post", return_value=response) as post:
+ _, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "LAST30DAYS_PERPLEXITY_AGENT_PRESET": "low",
},
)
payload = post.call_args.args[1]
- self.assertEqual("sonar-reasoning-pro", payload["model"])
- self.assertEqual("high", payload["reasoning_effort"])
- self.assertEqual("sonar-reasoning-pro", artifact["model"])
+ self.assertEqual("low", payload["preset"])
+ self.assertIn("input", payload)
+ self.assertNotIn("model", payload)
+ self.assertEqual("web_search", payload["tools"][0]["type"])
+ self.assertEqual(10, payload["tools"][0]["max_results"])
+ self.assertTrue(artifact["dynamicPreset"])
+ self.assertEqual("low", artifact["preset"])
+ self.assertEqual("openai/gpt-5.6-luna", artifact["servedModel"])
+ self.assertEqual(perplexity.PERPLEXITY_PRESET_PROFILE, artifact["profile"])
+
+ def test_agent_falls_back_to_message_output_when_output_text_is_missing(self):
+ citations = [
+ {
+ "title": "Example A",
+ "url": "https://example.com/a",
+ "snippet": "Direct source snippet",
+ }
+ ]
+ response = _agent_response(
+ "Message-only synthesis",
+ citations=citations,
+ include_output_text=False,
+ )
+ with patch("lib.perplexity.http.post", return_value=response):
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"PERPLEXITY_API_KEY": "pplx-test"},
+ )
+
+ self.assertEqual("Message-only synthesis", items[0]["snippet"])
+ self.assertEqual(1, artifact["citationCount"])
- def test_openrouter_fallback_uses_openrouter_models_and_annotations(self):
+ def test_malformed_agent_output_returns_safe_empty_artifact(self):
response = {
+ "id": "agent-empty",
+ "status": "completed",
+ "model": "perplexity/sonar",
+ "output": [{"type": "function_call", "arguments": "untrusted trace"}],
+ "usage": {"total_tokens": 2},
+ }
+ with patch("lib.perplexity.http.post", return_value=response):
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"PERPLEXITY_API_KEY": "pplx-test"},
+ )
+
+ self.assertEqual([], items)
+ self.assertEqual("empty_synthesis", artifact["error"])
+ self.assertEqual("perplexity/sonar", artifact["servedModel"])
+ self.assertEqual(["function_call"], artifact["outputTypes"])
+ self.assertNotIn("arguments", artifact)
+
+ def test_sync_terminal_failure_keeps_safe_response_metadata(self):
+ response = {
+ "id": "agent-failed",
+ "status": "failed",
+ "error": {"message": "Provider safely rejected this request"},
+ "output": [{"type": "function_call", "arguments": "raw tool trace"}],
+ "usage": {"total_tokens": 7},
+ }
+ with patch("lib.perplexity.http.post", return_value=response):
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"PERPLEXITY_API_KEY": "pplx-test"},
+ )
+
+ self.assertEqual([], items)
+ self.assertEqual("failed", artifact["error"])
+ self.assertEqual("agent-failed", artifact["responseId"])
+ self.assertEqual("failed", artifact["status"])
+ self.assertEqual("Provider safely rejected this request", artifact["agentErrorMessage"])
+ self.assertEqual({"total_tokens": 7}, artifact["usage"])
+ self.assertEqual(["function_call"], artifact["outputTypes"])
+ self.assertNotIn("arguments", artifact)
+
+ def test_sync_incomplete_response_keeps_safe_reason(self):
+ response = {
+ "id": "agent-incomplete",
+ "status": "incomplete",
+ "incomplete_details": {"reason": "max_output_tokens"},
+ "output": [],
+ "usage": {"total_tokens": 11},
+ }
+ with patch("lib.perplexity.http.post", return_value=response):
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"PERPLEXITY_API_KEY": "pplx-test"},
+ )
+
+ self.assertEqual([], items)
+ self.assertEqual("incomplete", artifact["error"])
+ self.assertEqual("max_output_tokens", artifact["incompleteReason"])
+ self.assertNotIn("incomplete_details", artifact)
+
+ def test_openrouter_only_config_uses_sonar_fallback(self):
+ response = {
+ "id": "openrouter-1",
+ "model": "perplexity/sonar-pro",
"choices": [
{
"message": {
- "content": "OpenRouter synthesis",
+ "content": "OpenRouter fallback synthesis",
"annotations": [
{
"url_citation": {
- "url": "https://example.com/b",
- "title": "Example B",
+ "url": "https://example.com/openrouter",
+ "title": "OpenRouter citation",
}
}
],
}
}
],
+ "usage": {"total_tokens": 42},
}
- with patch("lib.perplexity.http.post", return_value=response) as post:
+ with patch("lib.perplexity.http.post", return_value=response) as post, patch(
+ "lib.perplexity.http.get"
+ ) as get:
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
{"OPENROUTER_API_KEY": "or-test"},
- deep=True,
)
url, payload = post.call_args.args[:2]
- headers = post.call_args.kwargs["headers"]
self.assertEqual(perplexity.OPENROUTER_URL, url)
- self.assertEqual("Bearer or-test", headers["Authorization"])
- self.assertEqual("perplexity/sonar-deep-research", payload["model"])
- self.assertEqual(120, post.call_args.kwargs["timeout"])
+ self.assertEqual("perplexity/sonar-pro", payload["model"])
+ self.assertEqual("Bearer or-test", post.call_args.kwargs["headers"]["Authorization"])
+ self.assertEqual(1, post.call_args.kwargs["retries"])
+ get.assert_not_called()
+ self.assertEqual("openrouter", artifact["provider"])
+ self.assertEqual("sonar", artifact["mode"])
+ self.assertEqual("openrouter-chat-completions", artifact["endpoint"])
+ self.assertEqual("OpenRouter fallback synthesis", items[0]["snippet"])
+ self.assertEqual("OpenRouter citation", items[1]["title"])
+
+ def test_openrouter_search_mode_degrades_to_sonar_fallback(self):
+ response = {
+ "id": "openrouter-2",
+ "model": "perplexity/sonar-pro",
+ "choices": [{"message": {"content": "Fallback synthesis"}}],
+ }
+ with patch("lib.perplexity.http.post", return_value=response) as post:
+ _, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {
+ "OPENROUTER_API_KEY": "or-test",
+ "LAST30DAYS_PERPLEXITY_MODE": "search",
+ },
+ )
+
+ self.assertEqual(perplexity.OPENROUTER_URL, post.call_args.args[0])
+ self.assertEqual("openrouter", artifact["provider"])
+ self.assertEqual("sonar", artifact["mode"])
+
+ def test_openrouter_deep_research_keeps_synchronous_legacy_fallback(self):
+ response = {
+ "id": "openrouter-deep-1",
+ "model": "perplexity/sonar-deep-research",
+ "choices": [{"message": {"content": "Deep fallback synthesis"}}],
+ }
+ with patch("lib.perplexity.http.post", return_value=response) as post, patch(
+ "lib.perplexity.http.get"
+ ) as get:
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"OPENROUTER_API_KEY": "or-test"},
+ deep=True,
+ )
+
+ self.assertEqual(perplexity.OPENROUTER_URL, post.call_args.args[0])
+ self.assertEqual(
+ "perplexity/sonar-deep-research",
+ post.call_args.args[1]["model"],
+ )
+ get.assert_not_called()
+ self.assertEqual("Deep fallback synthesis", items[0]["snippet"])
+ self.assertTrue(artifact["deep"])
+ self.assertEqual("openrouter", artifact["provider"])
+
+ def test_openrouter_failure_keeps_typed_source_receipt(self):
+ with patch(
+ "lib.perplexity.http.post",
+ side_effect=perplexity.http.HTTPError(
+ "HTTP 429: Too Many Requests",
+ status_code=429,
+ ),
+ ):
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"OPENROUTER_API_KEY": "or-test"},
+ )
+
+ self.assertEqual([], items)
self.assertEqual("openrouter", artifact["provider"])
- self.assertEqual("perplexity/sonar-deep-research", artifact["model"])
- self.assertEqual("Example B", items[1]["title"])
+ self.assertEqual("openrouter-chat-completions", artifact["endpoint"])
+ self.assertEqual(429, artifact["statusCode"])
def test_search_api_mode_returns_ranked_rows_with_filters(self):
response = {
@@ -138,11 +419,13 @@ class PerplexityProviderTests(unittest.TestCase):
url, payload = post.call_args.args[:2]
self.assertEqual(perplexity.PERPLEXITY_SEARCH_URL, url)
+ self.assertEqual(1, post.call_args.kwargs["retries"])
self.assertEqual("test topic", payload["query"])
self.assertEqual(3, payload["max_results"])
self.assertEqual("low", payload["search_context_size"])
self.assertEqual("US", payload["country"])
self.assertEqual(["example.com", "example.org"], payload["search_domain_filter"])
+ self.assertEqual(["en"], payload["search_language_filter"])
self.assertEqual("05/01/2026", payload["search_after_date_filter"])
self.assertEqual("06/01/2026", payload["search_before_date_filter"])
self.assertNotIn("search_recency_filter", payload)
@@ -179,21 +462,19 @@ class PerplexityProviderTests(unittest.TestCase):
},
],
}
- sonar_response = {
- "choices": [{"message": {"content": "Sonar synthesis"}}],
- "citations": ["https://example.com/a"],
- "search_results": [
+ agent_response = _agent_response(
+ citations=[
{
"title": "Citation result",
"url": "https://example.com/a",
"snippet": "Citation row",
"date": "2026-05-15",
}
- ],
- }
+ ]
+ )
with patch(
"lib.perplexity.http.post",
- side_effect=[search_response, sonar_response],
+ side_effect=[search_response, agent_response],
) as post:
items, artifact = perplexity.search(
"test topic",
@@ -205,14 +486,16 @@ class PerplexityProviderTests(unittest.TestCase):
)
self.assertEqual(perplexity.PERPLEXITY_SEARCH_URL, post.call_args_list[0].args[0])
- self.assertEqual(perplexity.PERPLEXITY_URL, post.call_args_list[1].args[0])
+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args_list[1].args[0])
self.assertEqual("both", artifact["mode"])
self.assertEqual(3, artifact["itemCount"])
self.assertEqual("perplexity.ai", items[0]["source_domain"])
urls = [item["url"] for item in items if item["url"]]
self.assertEqual(["https://example.com/a", "https://example.com/unique"], urls)
+ self.assertIn("agent", artifact)
+ self.assertNotIn("sonar", artifact)
- def test_both_mode_keeps_search_rows_when_sonar_leg_fails(self):
+ def test_both_mode_keeps_search_rows_when_agent_leg_fails(self):
search_response = {
"id": "search-1",
"results": [
@@ -242,35 +525,26 @@ class PerplexityProviderTests(unittest.TestCase):
self.assertEqual("Raw result", items[0]["title"])
self.assertEqual(1, artifact["itemCount"])
- self.assertEqual("HTTPError", artifact["sonar"]["error"])
- self.assertEqual(500, artifact["sonar"]["statusCode"])
-
- def test_direct_deep_research_uses_async_api_and_wall_timeout_config(self):
- create_response = {"id": "async-1", "status": "CREATED", "created_at": 123}
- complete_response = {
- "id": "async-1",
- "status": "COMPLETED",
- "created_at": 123,
- "started_at": 124,
- "completed_at": 130,
- "response": {
- "choices": [{"message": {"content": "Deep synthesis"}}],
- "citations": ["https://example.com/deep"],
- "search_results": [
- {
- "title": "Deep citation",
- "url": "https://example.com/deep",
- "snippet": "Deep snippet",
- }
- ],
- "usage": {
- "total_tokens": 123,
- "cost": {"total_cost": 0.12},
- },
- },
- }
- with patch("lib.perplexity.http.post", return_value=create_response) as post, \
- patch("lib.perplexity.http.get", return_value=complete_response) as get:
+ self.assertEqual("HTTPError", artifact["agent"]["error"])
+ self.assertEqual(500, artifact["agent"]["statusCode"])
+
+ def test_deep_research_uses_agent_background_high_preset(self):
+ created = {"id": "agent-deep-1", "status": "queued"}
+ completed = _agent_response(
+ "Deep synthesis",
+ response_id="agent-deep-1",
+ citations=[
+ {
+ "title": "Deep citation",
+ "url": "https://example.com/deep",
+ "snippet": "Deep snippet",
+ }
+ ],
+ )
+ with patch("lib.perplexity.http.post", return_value=created) as post, patch(
+ "lib.perplexity.http.get",
+ return_value=completed,
+ ) as get:
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
@@ -281,36 +555,38 @@ class PerplexityProviderTests(unittest.TestCase):
deep=True,
)
- self.assertEqual(perplexity.PERPLEXITY_ASYNC_URL, post.call_args.args[0])
+ self.assertEqual(perplexity.PERPLEXITY_AGENT_URL, post.call_args.args[0])
+ payload = post.call_args.args[1]
+ self.assertEqual(1, post.call_args.kwargs["retries"])
+ self.assertEqual("high", payload["preset"])
+ self.assertTrue(payload["background"])
+ self.assertNotIn("model", payload)
+ tool = payload["tools"][0]
+ self.assertEqual("web_search", tool["type"])
+ self.assertEqual(10, tool["max_results"])
+ self.assertEqual("05/01/2026", tool["filters"]["search_after_date_filter"])
+ self.assertEqual("06/01/2026", tool["filters"]["search_before_date_filter"])
self.assertEqual(
- perplexity.PERPLEXITY_ASYNC_URL,
- perplexity._provider({"PERPLEXITY_API_KEY": "pplx-test"}, deep=True)[2],
+ f"{perplexity.PERPLEXITY_AGENT_URL}/agent-deep-1",
+ get.call_args.args[0],
)
- create_payload = post.call_args.args[1]
- self.assertEqual("sonar-deep-research", create_payload["request"]["model"])
- self.assertTrue(create_payload["idempotency_key"].startswith("last30days:"))
- self.assertEqual(f"{perplexity.PERPLEXITY_ASYNC_URL}/async-1", get.call_args.args[0])
- self.assertEqual("async-sonar", artifact["endpoint"])
- self.assertEqual(True, artifact["async"])
- self.assertEqual(300, artifact["asyncTimeoutSeconds"])
- self.assertEqual(create_payload["idempotency_key"], artifact["asyncIdempotencyKey"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(123, artifact["asyncCreatedAt"])
- self.assertEqual(124, artifact["asyncStartedAt"])
- self.assertEqual(130, artifact["asyncCompletedAt"])
+ self.assertEqual("agent-background", artifact["endpoint"])
+ self.assertTrue(artifact["background"])
+ self.assertEqual(300, artifact["backgroundTimeoutSeconds"])
+ self.assertEqual(1, artifact["backgroundPollCount"])
+ self.assertEqual("COMPLETED_REMOTE", artifact["backgroundLocalStatus"])
+ self.assertEqual("high", artifact["preset"])
+ self.assertTrue(artifact["dynamicPreset"])
self.assertEqual(123, items[0]["metadata"]["usage"]["total_tokens"])
- def test_direct_deep_research_timeout_returns_empty_result(self):
- with patch("lib.perplexity.http.post", return_value={"id": "async-1", "status": "CREATED", "created_at": 123}), \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "IN_PROGRESS",
- "created_at": 123,
- "started_at": 124,
- }), \
- patch("lib.perplexity.time.monotonic", side_effect=[0, 0, 2, 2]), \
- patch("lib.perplexity.time.sleep"):
+ def test_deep_research_timeout_preserves_background_response_id(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ) as post, patch(
+ "lib.perplexity.time.monotonic",
+ side_effect=[0, 1],
+ ), patch("lib.perplexity.http.get") as get:
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
@@ -321,189 +597,195 @@ class PerplexityProviderTests(unittest.TestCase):
deep=True,
)
+ post.assert_called_once()
+ get.assert_not_called()
self.assertEqual([], items)
self.assertEqual("timeout", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("IN_PROGRESS", artifact["asyncStatus"])
- self.assertEqual(1, artifact["asyncTimeoutSeconds"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual("PENDING_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(123, artifact["asyncCreatedAt"])
- self.assertEqual(124, artifact["asyncStartedAt"])
-
- def test_direct_deep_research_failed_status_returns_failure_artifact(self):
- with patch("lib.perplexity.http.post", return_value={"id": "async-1", "status": "CREATED"}), \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "FAILED",
- "failed_at": 130,
- "error_message": "provider failure",
- }):
+ self.assertEqual("agent-deep-1", artifact["responseId"])
+ self.assertEqual("queued", artifact["backgroundStatus"])
+ self.assertEqual(1, artifact["backgroundTimeoutSeconds"])
+ self.assertEqual(0, artifact["backgroundPollCount"])
+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])
+
+ def test_deep_research_nonterminal_poll_after_deadline_is_timeout(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ), patch(
+ "lib.perplexity.http.get",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ) as get, patch(
+ "lib.perplexity.time.monotonic",
+ side_effect=[0.0, 0.5, 1.5],
+ ):
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
- {"PERPLEXITY_API_KEY": "pplx-test"},
+ {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",
+ },
deep=True,
)
self.assertEqual([], items)
- self.assertEqual("failed", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("FAILED", artifact["asyncStatus"])
- self.assertEqual("FAILED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(130, artifact["asyncFailedAt"])
- self.assertEqual("provider failure", artifact["asyncErrorMessage"])
-
- def test_direct_deep_research_poll_error_preserves_async_id(self):
- with patch("lib.perplexity.http.post", return_value={
- "id": "async-1",
- "status": "CREATED",
- "created_at": 123,
- }), \
- patch("lib.perplexity.http.get", side_effect=perplexity.http.HTTPError(
- "HTTP 429: Too Many Requests",
- status_code=429,
- )):
+ self.assertEqual("timeout", artifact["error"])
+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])
+ self.assertEqual(1, artifact["backgroundPollCount"])
+ self.assertEqual(1.0, get.call_args.kwargs["deadline_monotonic"])
+
+ def test_deep_research_poll_retry_deadline_is_timeout_not_poll_error(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ), patch(
+ "lib.perplexity.http.get",
+ side_effect=perplexity.http.DeadlineExceeded(),
+ ), patch(
+ "lib.perplexity.time.monotonic",
+ side_effect=[0.0, 0.5],
+ ):
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
- {"PERPLEXITY_API_KEY": "pplx-test"},
+ {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",
+ },
deep=True,
)
self.assertEqual([], items)
- self.assertEqual("poll_error", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("CREATED", artifact["asyncStatus"])
- self.assertEqual("POLL_ERROR", artifact["asyncLocalStatus"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual(429, artifact["asyncPollStatusCode"])
-
- def test_direct_deep_research_malformed_completed_preserves_async_id(self):
- with patch("lib.perplexity.http.post", return_value={
- "id": "async-1",
- "status": "CREATED",
- "created_at": 123,
- }), \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "COMPLETED",
- "created_at": 123,
- "completed_at": 130,
- "response": None,
- }):
+ self.assertEqual("timeout", artifact["error"])
+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])
+ self.assertEqual(1, artifact["backgroundPollCount"])
+
+ def test_deep_research_early_transport_timeout_is_poll_error(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ), patch(
+ "lib.perplexity.http.get",
+ side_effect=perplexity.http.HTTPError(
+ "URL Error: timed out",
+ outcome_state=perplexity.health.TIMEOUT,
+ ),
+ ), patch(
+ "lib.perplexity.time.monotonic",
+ side_effect=[0.0, 10.0, 10.0],
+ ):
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
- {"PERPLEXITY_API_KEY": "pplx-test"},
+ {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "600",
+ },
deep=True,
)
self.assertEqual([], items)
- self.assertEqual("failed", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("COMPLETED", artifact["asyncStatus"])
- self.assertEqual("FAILED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual(130, artifact["asyncCompletedAt"])
- self.assertEqual(
- "Async Deep Research completed without response",
- artifact["asyncErrorMessage"],
- )
+ self.assertEqual("poll_error", artifact["error"])
+ self.assertEqual("POLL_ERROR", artifact["backgroundLocalStatus"])
- def test_direct_deep_research_empty_choices_preserves_async_id(self):
- with patch("lib.perplexity.http.post", return_value={
- "id": "async-1",
- "status": "CREATED",
- "created_at": 123,
- }) as post, \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "COMPLETED",
- "created_at": 123,
- "completed_at": 130,
- "response": {
- "choices": [],
- "usage": {"total_tokens": 321},
- },
- }):
+ def test_deep_research_terminal_poll_after_deadline_is_timeout(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ), patch(
+ "lib.perplexity.http.get",
+ return_value={"id": "agent-deep-1", "status": "completed"},
+ ), patch(
+ "lib.perplexity.time.monotonic",
+ side_effect=[0.0, 0.5, 1.5],
+ ):
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
- {"PERPLEXITY_API_KEY": "pplx-test"},
+ {
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "LAST30DAYS_PERPLEXITY_DEEP_TIMEOUT_SECONDS": "1",
+ },
deep=True,
)
self.assertEqual([], items)
- self.assertEqual("empty_choices", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("COMPLETED", artifact["asyncStatus"])
- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual(130, artifact["asyncCompletedAt"])
- self.assertEqual(
- post.call_args.args[1]["idempotency_key"],
- artifact["asyncIdempotencyKey"],
- )
- self.assertEqual(321, artifact["usage"]["total_tokens"])
- self.assertEqual(
- "Async Deep Research completed without choices",
- artifact["asyncErrorMessage"],
- )
-
- def test_direct_deep_research_empty_synthesis_preserves_async_id(self):
- with patch("lib.perplexity.http.post", return_value={
- "id": "async-1",
- "status": "CREATED",
- "created_at": 123,
- }) as post, \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "COMPLETED",
- "created_at": 123,
- "completed_at": 130,
- "response": {
- "choices": [{"message": {"content": ""}}],
- },
- }):
- items, artifact = perplexity.search(
+ self.assertEqual("timeout", artifact["error"])
+ self.assertEqual("completed", artifact["backgroundStatus"])
+ self.assertEqual("PENDING_REMOTE", artifact["backgroundLocalStatus"])
+
+ def test_deep_research_terminal_failures_are_recorded(self):
+ for status in ("failed", "cancelled", "incomplete"):
+ response = {
+ "id": "agent-deep-1",
+ "status": status,
+ "model": "openai/gpt-5.6-sol",
+ "usage": {"total_tokens": 17},
+ "output": [{"type": "message", "content": []}],
+ }
+ if status == "incomplete":
+ response["incomplete_details"] = {"reason": "max_output_tokens"}
+ with self.subTest(status=status), patch(
+ "lib.perplexity.http.post",
+ return_value=response,
+ ) as post, patch("lib.perplexity.http.get") as get:
+ items, artifact = perplexity.search(
+ "test topic",
+ ("2026-05-01", "2026-06-01"),
+ {"PERPLEXITY_API_KEY": "pplx-test"},
+ deep=True,
+ )
+
+ post.assert_called_once()
+ get.assert_not_called()
+ self.assertEqual([], items)
+ self.assertEqual("failed", artifact["error"])
+ self.assertEqual(status, artifact["backgroundStatus"])
+ self.assertEqual("TERMINAL_REMOTE", artifact["backgroundLocalStatus"])
+ self.assertEqual("openai/gpt-5.6-sol", artifact["servedModel"])
+ self.assertEqual({"total_tokens": 17}, artifact["usage"])
+ self.assertEqual(["message"], artifact["outputTypes"])
+ if status == "incomplete":
+ self.assertEqual("max_output_tokens", artifact["incompleteReason"])
+
+ def test_deep_research_logs_safe_receipt_for_cli_consumers(self):
+ response = {
+ "id": "agent-deep-1",
+ "status": "incomplete",
+ "model": "openai/gpt-5.6-sol",
+ "incomplete_details": {"reason": "max_output_tokens"},
+ }
+ with patch("lib.perplexity.http.post", return_value=response), patch(
+ "lib.perplexity._log",
+ ) as logger:
+ perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
{"PERPLEXITY_API_KEY": "pplx-test"},
deep=True,
)
- self.assertEqual([], items)
- self.assertEqual("empty_synthesis", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("COMPLETED", artifact["asyncStatus"])
- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(1, artifact["asyncPollCount"])
- self.assertEqual(130, artifact["asyncCompletedAt"])
- self.assertEqual(
- post.call_args.args[1]["idempotency_key"],
- artifact["asyncIdempotencyKey"],
- )
- self.assertEqual(
- "Async Deep Research completed with empty synthesis",
- artifact["asyncErrorMessage"],
+ receipt = next(
+ call.args[0]
+ for call in logger.call_args_list
+ if call.args and call.args[0].startswith("Deep Research receipt:")
)
+ self.assertIn("model=openai/gpt-5.6-sol", receipt)
+ self.assertIn("response_id=agent-deep-1", receipt)
+ self.assertIn("provider_status=incomplete", receipt)
+ self.assertIn("incomplete_reason=max_output_tokens", receipt)
- def test_direct_deep_research_malformed_choice_preserves_async_id(self):
- with patch("lib.perplexity.http.post", return_value={
- "id": "async-1",
- "status": "CREATED",
- "created_at": 123,
- }) as post, \
- patch("lib.perplexity.http.get", return_value={
- "id": "async-1",
- "status": "COMPLETED",
- "created_at": 123,
- "completed_at": 130,
- "response": {
- "choices": [None],
- },
- }):
+ def test_deep_research_poll_error_preserves_response_id(self):
+ with patch(
+ "lib.perplexity.http.post",
+ return_value={"id": "agent-deep-1", "status": "queued"},
+ ), patch(
+ "lib.perplexity.http.get",
+ side_effect=perplexity.http.HTTPError(
+ "HTTP 429: Too Many Requests",
+ status_code=429,
+ ),
+ ):
items, artifact = perplexity.search(
"test topic",
("2026-05-01", "2026-06-01"),
@@ -512,14 +794,12 @@ class PerplexityProviderTests(unittest.TestCase):
)
self.assertEqual([], items)
- self.assertEqual("empty_synthesis", artifact["error"])
- self.assertEqual("async-1", artifact["asyncRequestId"])
- self.assertEqual("COMPLETED", artifact["asyncStatus"])
- self.assertEqual("COMPLETED_REMOTE", artifact["asyncLocalStatus"])
- self.assertEqual(
- post.call_args.args[1]["idempotency_key"],
- artifact["asyncIdempotencyKey"],
- )
+ self.assertEqual("poll_error", artifact["error"])
+ self.assertEqual("agent-deep-1", artifact["responseId"])
+ self.assertEqual("queued", artifact["backgroundStatus"])
+ self.assertEqual("POLL_ERROR", artifact["backgroundLocalStatus"])
+ self.assertEqual(1, artifact["backgroundPollCount"])
+ self.assertEqual(429, artifact["backgroundPollStatusCode"])
def test_missing_keys_skip_without_http(self):
with patch("lib.perplexity.http.post") as post:
@@ -532,3 +812,7 @@ class PerplexityProviderTests(unittest.TestCase):
post.assert_not_called()
self.assertEqual([], items)
self.assertEqual({}, artifact)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_pipeline_v3.py b/tests/test_pipeline_v3.py
index f0b13879..82b4c592 100644
--- a/tests/test_pipeline_v3.py
+++ b/tests/test_pipeline_v3.py
@@ -3,6 +3,7 @@ import unittest
from unittest.mock import patch
from lib import health
+from lib import fanout
from lib import http
from lib import pipeline
from lib import schema
@@ -250,6 +251,14 @@ class PipelineV3Tests(unittest.TestCase):
class TestSourceFetchCap(unittest.TestCase):
+ def test_paid_budget_rejects_non_owner_before_owner_claims(self):
+ paid_budget = pipeline.PaidSourceBudget(owner="main")
+
+ self.assertFalse(paid_budget.try_consume(1, claimant="peer"))
+ self.assertEqual(0, paid_budget.used)
+ self.assertTrue(paid_budget.try_consume(1, claimant="main"))
+ self.assertEqual(1, paid_budget.used)
+
"""X source fetch count must be capped by MAX_SOURCE_FETCHES."""
def test_x_capped_in_max_source_fetches(self):
@@ -261,6 +270,50 @@ class TestSourceFetchCap(unittest.TestCase):
self.assertIn("jobs", pipeline.MAX_SOURCE_FETCHES)
self.assertEqual(pipeline.MAX_SOURCE_FETCHES["jobs"], 1)
+ def test_perplexity_paid_call_cap_cannot_be_raised_by_generic_override(self):
+ self.assertEqual(
+ 1,
+ pipeline._source_fetch_cap(
+ "perplexity",
+ {"_max_source_fetches": 10},
+ ),
+ )
+ self.assertEqual(
+ 0,
+ pipeline._source_fetch_cap(
+ "perplexity",
+ {"_max_source_fetches": 0},
+ ),
+ )
+
+ def test_deep_research_lane_is_isolated_and_does_not_replace_primary(self):
+ primary = schema.SubQuery(
+ label="primary",
+ search_query="narrow angle",
+ ranking_query="narrow angle",
+ sources=["reddit", "grounding", "perplexity"],
+ )
+ plan = schema.QueryPlan(
+ intent="general",
+ freshness_mode="balanced_recent",
+ cluster_mode="story",
+ raw_topic="whole topic",
+ subqueries=[primary],
+ source_weights={"reddit": 1.0, "grounding": 1.0, "perplexity": 1.0},
+ )
+
+ pipeline._ensure_perplexity_in_plan(
+ plan,
+ "whole topic",
+ ["reddit", "grounding", "perplexity"],
+ force=True,
+ )
+
+ self.assertEqual("primary", plan.subqueries[0].label)
+ self.assertEqual(["reddit", "grounding"], plan.subqueries[0].sources)
+ self.assertEqual("deep-research", plan.subqueries[-1].label)
+ self.assertEqual(["perplexity"], plan.subqueries[-1].sources)
+
def test_cap_logic_limits_source_submissions(self):
"""Verify the cap logic skips submissions beyond the limit."""
subquery_sources = [
@@ -335,6 +388,196 @@ class TestSourceFetchCap(unittest.TestCase):
self.assertEqual([], x_calls)
self.assertGreater(len(reddit_calls), 0)
+ @patch("lib.pipeline._retrieve_stream")
+ def test_deep_research_subquery_fanout_submits_once(self, mock_retrieve):
+ mock_retrieve.return_value = ([], {})
+ plan = {
+ "intent": "comparison",
+ "freshness_mode": "balanced_recent",
+ "cluster_mode": "debate",
+ "subqueries": [
+ {
+ "label": f"angle-{index}",
+ "search_query": f"topic angle {index}",
+ "ranking_query": f"topic angle {index}",
+ "sources": ["perplexity"],
+ }
+ for index in range(3)
+ ],
+ "source_weights": {"perplexity": 1.0},
+ }
+
+ pipeline.run(
+ topic="whole topic",
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "_deep_research": True,
+ "_max_source_fetches": 10,
+ },
+ depth="default",
+ requested_sources=["reddit", "perplexity"],
+ mock=True,
+ external_plan=plan,
+ )
+
+ perplexity_calls = [
+ call
+ for call in mock_retrieve.call_args_list
+ if call.kwargs.get("source") == "perplexity"
+ ]
+ self.assertEqual(1, len(perplexity_calls))
+ self.assertEqual(
+ "whole topic",
+ perplexity_calls[0].kwargs["subquery"].search_query,
+ )
+
+ @patch("lib.pipeline._retrieve_stream")
+ def test_normal_perplexity_subquery_fanout_submits_once(self, mock_retrieve):
+ mock_retrieve.return_value = ([], {})
+ plan = {
+ "intent": "comparison",
+ "freshness_mode": "balanced_recent",
+ "cluster_mode": "debate",
+ "subqueries": [
+ {
+ "label": f"angle-{index}",
+ "search_query": f"topic angle {index}",
+ "ranking_query": f"topic angle {index}",
+ "sources": ["perplexity"],
+ }
+ for index in range(4)
+ ],
+ "source_weights": {"perplexity": 1.0},
+ }
+
+ pipeline.run(
+ topic="whole topic",
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "_max_source_fetches": 10,
+ },
+ depth="default",
+ requested_sources=["perplexity"],
+ mock=True,
+ external_plan=plan,
+ )
+
+ perplexity_calls = [
+ call
+ for call in mock_retrieve.call_args_list
+ if call.kwargs.get("source") == "perplexity"
+ ]
+ self.assertEqual(1, len(perplexity_calls))
+ self.assertEqual(
+ "whole topic",
+ perplexity_calls[0].kwargs["subquery"].search_query,
+ )
+
+ @patch("lib.pipeline._retrieve_stream")
+ def test_shared_paid_budget_caps_competitor_subruns(self, mock_retrieve):
+ mock_retrieve.return_value = ([], {})
+ paid_budget = pipeline.PaidSourceBudget()
+ plan = {
+ "intent": "general",
+ "freshness_mode": "balanced_recent",
+ "cluster_mode": "story",
+ "subqueries": [
+ {
+ "label": "primary",
+ "search_query": "entity angle",
+ "ranking_query": "entity angle",
+ "sources": ["perplexity"],
+ }
+ ],
+ "source_weights": {"perplexity": 1.0},
+ }
+
+ for entity in ("main", "peer-a", "peer-b"):
+ pipeline.run(
+ topic=entity,
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "_perplexity_paid_budget": paid_budget,
+ },
+ depth="quick",
+ requested_sources=["perplexity"],
+ mock=True,
+ external_plan=plan,
+ internal_subrun=True,
+ )
+
+ perplexity_calls = [
+ call
+ for call in mock_retrieve.call_args_list
+ if call.kwargs.get("source") == "perplexity"
+ ]
+ self.assertEqual(1, len(perplexity_calls))
+ self.assertEqual(1, paid_budget.used)
+
+ @patch("lib.pipeline._retrieve_stream")
+ def test_shared_paid_budget_is_reserved_for_main_competitor_topic(
+ self,
+ mock_retrieve,
+ ):
+ mock_retrieve.return_value = ([], {})
+ paid_budget = pipeline.PaidSourceBudget(owner="main")
+ barrier = threading.Barrier(3)
+ plan = {
+ "intent": "general",
+ "freshness_mode": "balanced_recent",
+ "cluster_mode": "story",
+ "subqueries": [
+ {
+ "label": "primary",
+ "search_query": "entity angle",
+ "ranking_query": "entity angle",
+ "sources": ["perplexity"],
+ }
+ ],
+ "source_weights": {"perplexity": 1.0},
+ }
+
+ def run_entity(entity):
+ barrier.wait()
+ return pipeline.run(
+ topic=entity,
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ "_perplexity_paid_budget": paid_budget,
+ },
+ depth="quick",
+ requested_sources=["perplexity"],
+ mock=True,
+ external_plan=plan,
+ internal_subrun=True,
+ )
+
+ results = fanout.run_competitor_fanout(
+ main_topic="main",
+ main_runner=lambda: run_entity("main"),
+ competitors=["peer-a", "peer-b"],
+ competitor_runner=run_entity,
+ )
+
+ perplexity_calls = [
+ call
+ for call in mock_retrieve.call_args_list
+ if call.kwargs.get("source") == "perplexity"
+ ]
+ self.assertEqual(1, len(perplexity_calls))
+ self.assertEqual("main", perplexity_calls[0].kwargs["topic"])
+ self.assertEqual(1, paid_budget.used)
+ for entity, report in results[1:]:
+ receipt = report.artifacts["paid_source_budget"]["perplexity"]
+ self.assertEqual("skipped-budget", receipt["state"])
+ self.assertFalse(receipt["attempted"])
+ self.assertEqual("main", receipt["owner"])
+ self.assertEqual(entity, receipt["claimant"])
+
class TestRateLimitSharing(unittest.TestCase):
"""429 signals should be shared across subqueries."""
@@ -1361,6 +1604,41 @@ class TestThinSourceRetry(unittest.TestCase):
)
mock_retrieve.assert_not_called()
+ def test_perplexity_is_not_retried_when_results_are_thin(self):
+ plan = schema.QueryPlan(
+ intent="general",
+ freshness_mode="balanced_recent",
+ cluster_mode="story",
+ raw_topic="AI safety",
+ subqueries=[
+ schema.SubQuery(
+ label="primary",
+ search_query="AI safety",
+ ranking_query="AI safety",
+ sources=["perplexity"],
+ )
+ ],
+ source_weights={"perplexity": 1.0},
+ )
+ bundle = schema.RetrievalBundle()
+
+ with patch("lib.pipeline._retrieve_stream") as mock_retrieve:
+ pipeline._retry_thin_sources(
+ topic="AI safety",
+ bundle=bundle,
+ plan=plan,
+ config={},
+ depth="default",
+ date_range=("2026-02-15", "2026-03-17"),
+ runtime=_make_runtime(),
+ mock=False,
+ rate_limited_sources=set(),
+ rate_limit_lock=threading.Lock(),
+ settings=pipeline.DEPTH_SETTINGS["default"],
+ )
+
+ mock_retrieve.assert_not_called()
+
class TestErrorCleanup(unittest.TestCase):
"""Source errors should be cleared when the source has items from other subqueries."""
@@ -1713,6 +1991,37 @@ class TestExcludeSources(unittest.TestCase):
class TestPerplexityAvailability(unittest.TestCase):
+ def test_agent_background_failure_uses_safe_provider_detail(self):
+ outcome = pipeline._legacy_artifact_outcome(
+ "perplexity",
+ {
+ "error": "failed",
+ "backgroundErrorMessage": "Provider reported an incomplete run",
+ },
+ )
+
+ self.assertEqual(health.ERROR, outcome["state"])
+ self.assertEqual("Provider reported an incomplete run", outcome["detail"])
+
+ def test_agent_background_poll_429_is_rate_limited(self):
+ outcome = pipeline._legacy_artifact_outcome(
+ "perplexity",
+ {
+ "error": "poll_error",
+ "backgroundPollError": "HTTP 429: Too Many Requests",
+ "backgroundPollStatusCode": 429,
+ },
+ )
+
+ self.assertEqual(health.RATE_LIMITED, outcome["state"])
+ self.assertEqual("HTTP 429: Too Many Requests", outcome["detail"])
+
+ def test_perplexity_source_available_with_openrouter_fallback(self):
+ sources = pipeline.available_sources(
+ {"OPENROUTER_API_KEY": "test-key", "INCLUDE_SOURCES": "perplexity"}
+ )
+ self.assertIn("perplexity", sources)
+
def test_perplexity_source_not_available_with_direct_key_without_opt_in(self):
sources = pipeline.available_sources({"PERPLEXITY_API_KEY": "test-key"})
self.assertNotIn("perplexity", sources)
diff --git a/tests/test_render_v3.py b/tests/test_render_v3.py
index 3a2e6ba4..83a386f0 100644
--- a/tests/test_render_v3.py
+++ b/tests/test_render_v3.py
@@ -370,7 +370,7 @@ class OutputEnvelopeTests(unittest.TestCase):
return schema.SourceItem(
item_id=item_id,
source="perplexity",
- title=f"Perplexity Sonar Pro: test topic ({item_id})",
+ title=f"Perplexity Agent: test topic ({item_id})",
body="AI synthesis body.",
url="",
container="perplexity.ai",
@@ -1654,7 +1654,7 @@ class TestSourceUrlsAreClickable(unittest.TestCase):
empty_url_item = schema.SourceItem(
item_id="i3",
source="perplexity",
- title="Perplexity Sonar Pro: test topic",
+ title="Perplexity Agent: test topic",
body="AI synthesis body.",
url="",
container="perplexity.ai",
diff --git a/tests/test_source_outcomes.py b/tests/test_source_outcomes.py
index 98f1f69f..27bbca48 100644
--- a/tests/test_source_outcomes.py
+++ b/tests/test_source_outcomes.py
@@ -339,6 +339,91 @@ def test_pipeline_records_clean_empty_source_as_no_results():
assert "x" not in report.errors_by_source
+def _perplexity_plan():
+ return {
+ "intent": "general",
+ "freshness_mode": "balanced_recent",
+ "cluster_mode": "story",
+ "subqueries": [
+ {
+ "label": "primary",
+ "search_query": "test topic",
+ "ranking_query": "test topic",
+ "sources": ["perplexity"],
+ }
+ ],
+ "source_weights": {"perplexity": 1.0},
+ }
+
+
+def test_pipeline_records_both_mode_semantic_leg_failure_as_partial():
+ raw_item = {
+ "id": "PXS1",
+ "title": "Search result",
+ "url": "https://example.com/result",
+ "snippet": "Raw search evidence",
+ "date": "2026-08-10",
+ "relevance": 0.8,
+ "why_relevant": "Perplexity Search result",
+ "engagement": {},
+ }
+ artifact = {
+ "mode": "both",
+ "search": {"mode": "search"},
+ "agent": {
+ "error": "failed",
+ "agentErrorMessage": "Provider rejected synthesis",
+ },
+ "itemCount": 1,
+ }
+ with patch("lib.pipeline._retrieve_stream_impl", return_value=([raw_item], artifact)):
+ report = pipeline.run(
+ topic="test topic",
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ },
+ depth="quick",
+ requested_sources=["perplexity"],
+ mock=True,
+ external_plan=_perplexity_plan(),
+ )
+
+ outcome = report.source_status["perplexity"]
+ assert outcome.state == schema.PARTIAL
+ assert outcome.items_returned == 1
+ assert outcome.detail == "agent leg: Provider rejected synthesis"
+
+
+def test_pipeline_records_both_mode_semantic_failure_without_items():
+ artifact = {
+ "mode": "both",
+ "search": {"mode": "search"},
+ "agent": {
+ "error": "failed",
+ "agentErrorMessage": "Provider rejected synthesis",
+ },
+ "itemCount": 0,
+ }
+ with patch("lib.pipeline._retrieve_stream_impl", return_value=([], artifact)):
+ report = pipeline.run(
+ topic="test topic",
+ config={
+ "LAST30DAYS_REASONING_PROVIDER": "gemini",
+ "PERPLEXITY_API_KEY": "pplx-test",
+ },
+ depth="quick",
+ requested_sources=["perplexity"],
+ mock=True,
+ external_plan=_perplexity_plan(),
+ )
+
+ outcome = report.source_status["perplexity"]
+ assert outcome.state == health.ERROR
+ assert outcome.items_returned == 0
+ assert outcome.detail == "agent leg: Provider rejected synthesis"
+
+
def test_pipeline_preserves_typed_http_failure():
plan = {
"intent": "general",