Add SpaceX (SPCX) financial briefing example using finance_search

docs/examples/spacex-spcx-briefing/README.mdx

@@ -0,0 +1,222 @@
+---
+title: SpaceX (SPCX) Financial Briefing
+description: Generate a quantitative SpaceX (NASDAQ: SPCX) financial briefing in a single Agent API call using the finance_search tool. Showcases segment, KPI, and backlog data for a newly-listed ticker.
+sidebar_position: 8
+keywords: [agent-api, finance-search, spcx, spacex, equity-research, ipo, segment-revenue, starlink, fiscal-ai]
+---
+
+# SpaceX (SPCX) Financial Briefing
+
+A focused, single-shot example showing how Perplexity's [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) and the [`finance_search`](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) tool ([launch announcement](https://www.perplexity.ai/hub/blog/introducing-finance-search-in-the-agent-api)) produce a quantitative briefing on a freshly-listed ticker — in this case **NASDAQ: SPCX**, Space Exploration Technologies Corp. (SpaceX), which filed its S-1 in May 2026.
+
+Most equity-research walkthroughs hit large-cap, mature tickers where every field is well-populated. `finance_search` is more interesting on a fresh listing: the moment Perplexity's finance data provider ([fiscal.ai](https://fiscal.ai)) flips the ticker on, the model can pull structured segment revenue (Connectivity / Space / AI), Starlink subscriber KPIs, satellites in orbit, and backlog directly out of the S-1 — no scraping, no PDF parsing.
+
+## Features
+
+- One Agent API call returns a 6-section briefing covering snapshot, FY2023–FY2025 P&L trajectory, FY2025 segment mix, Starlink KPIs, capacity & backlog, and a labeled bottom line
+- Uses the `finance_search` tool for structured quote, financials, segment, and KPI data — typically 4–7 invocations across four categories per run
+- Adds `web_search` + `fetch_url` so the model can corroborate figures against the SpaceX S-1 on SEC EDGAR
+- Surfaces the structured `finance_results` blocks, citation-ready Perplexity finance URLs, and total request cost alongside the prose
+- Handles the **recycled-ticker** edge case: `SPCX` was historically a small SPAC ETF. The system prompt explicitly tells the model that the SPCX symbol now maps to SpaceX so it doesn't refuse to write the briefing based on a stale display label. This pattern is reusable for any newly-listed company whose ticker was previously assigned to a different security.
+
+## Prerequisites
+
+- Python 3.9+
+- A Perplexity API key with Agent API access. See the [Finance Search docs](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) and the [launch announcement](https://www.perplexity.ai/hub/blog/introducing-finance-search-in-the-agent-api) for capabilities and coverage.
+
+## Installation
+
+```bash
+cd docs/examples/spacex-spcx-briefing
+pip install -r requirements.txt
+chmod +x spacex_spcx_briefing.py
+```
+
+## API Key Setup
+
+```bash
+export PERPLEXITY_API_KEY="your-api-key-here"
+```
+
+You can also pass the key via `--api-key`, or place it in a `.pplx_api_key` file in the working directory.
+
+## Quick Start
+
+```bash
+./spacex_spcx_briefing.py
+```
+
+That's the entire interface — no ticker argument needed; this example is purpose-built for SPCX.
+
+## Usage
+
+```bash
+./spacex_spcx_briefing.py [--model MODEL] [--max-output-tokens N] [--max-steps N] [--json] [--api-key KEY]
+```
+
+### Use a different Agent API model
+
+```bash
+./spacex_spcx_briefing.py --model anthropic/claude-opus-4-7
+```
+
+### Emit the raw Agent API response
+
+```bash
+./spacex_spcx_briefing.py --json | jq '.usage.cost'
+```
+
+### Lower the max-steps for a cheaper, narrower run
+
+```bash
+./spacex_spcx_briefing.py --max-steps 3
+```
+
+## Example Output (truncated)
+
+```
+## 1. Snapshot
+
+| Metric                | Latest finance_search value |
+|-----------------------|----------------------------:|
+| Latest price          | $22.08                      |
+| Day range             | $22.07–$22.10               |
+| Quote timestamp       | 2026-05-20 19:45:54 UTC     |
+
+## 2. FY2023–FY2025 P&L trajectory
+
+| Fiscal year | Revenue   | Gross margin | Operating margin | Net margin |
+|-------------|----------:|-------------:|-----------------:|-----------:|
+| FY2023      | $10.387B  | 41%          | (34%)            | (45%)      |
+| FY2024      | $14.015B  | 43%          | 3%               | 6%         |
+| FY2025      | $18.674B  | 49%          | (14%)            | (26%)      |
+
+Revenue compounded strongly from $10.387B in FY2023 to $18.674B in FY2025,
+gross margin expanded from 41% to 49%, but operating and net margins were
+volatile — profitable in FY2024, back to losses in FY2025.
+
+## 3. Segment mix (FY2025)
+
+| Segment        | Revenue   | % total | Adjusted EBITDA |
+|----------------|----------:|--------:|----------------:|
+| Connectivity   | $11.387B  | 61.0%   | $7.168B         |
+| Space          | $4.086B   | 21.9%   | $0.653B         |
+| AI             | $3.201B   | 17.1%   | $(1.237)B       |
+
+## 4. Starlink (Connectivity) KPIs (Q1 2026)
+
+| KPI                            | Value   |
+|--------------------------------|--------:|
+| Starlink subscribers           | 10.3M   |
+| Starlink ARPU                  | $66/mo  |
+| Satellites in orbit            | 9,600   |
+| Consumer revenue               | $2.148B |
+| Enterprise & government rev    | $1.109B |
+
+## 5. Capacity & backlog (FY2025)
+
+| Metric                           | Value    |
+|----------------------------------|---------:|
+| Total backlog                    | $28.4B   |
+| Backlog to be recognized in NTM  | 53%      |
+| Falcon launches                  | 165      |
+| Starship launches                | 5        |
+| Mass to orbit (metric tons)      | 2,213    |
+
+## 6. Bottom line
+
+Analytical opinion, not a recommendation: SPCX's FY2025 profile shows a
+scaled Connectivity-led business with $18.674B of revenue and 49% gross
+margin, but consolidated profitability remains burdened by Space and AI
+investment intensity, driving a $(4.937)B FY2025 net loss...
+
+---
+finance_search returned 7 structured block(s) across categories
+  [financials, kpis, quote, segments]
+
+Cost: 0.2852 USD
+```
+
+## Code Walkthrough
+
+The script issues one Agent API call with `finance_search`, `web_search`, and `fetch_url` enabled, and prints both the model's prose and the structured `finance_results` blocks the tool returned.
+
+### 1. Issue the Agent API call
+
+```python
+from perplexity import Perplexity
+
+client = Perplexity()
+response = client.responses.create(
+    model="openai/gpt-5.5",
+    instructions=SYSTEM_PROMPT,
+    input=USER_PROMPT,
+    tools=[
+        {"type": "finance_search"},
+        {"type": "web_search"},
+        {"type": "fetch_url"},
+    ],
+    max_output_tokens=4096,
+    max_steps=8,
+)
+```
+
+`max_steps=8` is intentional — the model needs several `finance_search` invocations (quote, FY2023 income statement, FY2024 income statement, FY2025 income statement, segments, KPIs) to fill the briefing. Without enough budget for steps, the model will return only a quote and leave the rest "not returned."
+
+### 2. Walk `response.output` for messages and finance results
+
+`response.output_text` doesn't work when the output mixes message and `finance_results` items — walk the list defensively:
+
+```python
+for item in response.output:
+    if item.type == "finance_results":
+        for r in item.results:
+            print(r.category, r.tickers, r.sources)
+    elif item.type == "message":
+        for block in item.content:
+            if block.type == "output_text":
+                print(block.text)
+```
+
+### 3. Surface citation-ready URLs and cost
+
+Each `finance_results` block exposes a `sources` list with stable Perplexity finance URLs (e.g. `https://www.perplexity.ai/finance/SPCX/financials?category=SEGMENTS`). The script prints these alongside the briefing — useful when the output is consumed by humans or by a downstream RAG pipeline. `response.usage.cost.total_cost` gives the all-in price for the run.
+
+## Prompting Guidance
+
+Two non-obvious prompt patterns are doing the heavy lifting here:
+
+**1. Disambiguate recycled tickers in the system prompt.** `SPCX` previously identified a small SPAC ETF. Without an explicit override, the model can latch onto the legacy display label and refuse to treat the segment / KPI rows as SpaceX's. The system prompt declares the ticker mapping up front and tells the model to trust `finance_search`:
+
+> "CRITICAL TICKER MAPPING: SPCX (NASDAQ: SPCX) is the ticker for Space Exploration Technologies Corp. ... The finance_search tool returns SpaceX S-1 data under the SPCX symbol — trust it."
+
+**2. Instruct the model to issue multiple finance_search calls.** Left alone, models often grab a single quote payload and stop. Stating "you MUST exercise finance_search multiple times" plus enumerating the categories (quote, income statement, segments, KPIs) reliably triggers 4–7 invocations across the four data areas.
+
+This pattern is documented in the [`finance_search` prompt guidance](https://docs.perplexity.ai/docs/agent-api/tools/finance-search#prompt-guidance).
+
+## Pricing
+
+`finance_search` is billed at **$5 per 1,000 invocations**, separate from model token usage. A representative run with `openai/gpt-5.5`:
+
+- ~7 `finance_search` invocations + a few `web_search` calls
+- ~$0.28 total cost end-to-end
+
+See [Perplexity Pricing](https://docs.perplexity.ai/docs/getting-started/pricing) for current rates.
+
+## Data Source
+
+Structured SPCX financial data returned by `finance_search` is sourced from [fiscal.ai](https://fiscal.ai), Perplexity's finance data provider. fiscal.ai covers 50,000+ public companies; SPCX coverage launched alongside the SpaceX S-1 filing in May 2026.
+
+## Limitations
+
+- Results depend on Perplexity's (and upstream fiscal.ai's) coverage of the ticker. Coverage and field availability for newly-listed tickers can evolve over the days following a filing.
+- This is not investment advice. The "Bottom line" section is explicitly framed as analytical opinion, not a recommendation.
+
+## Resources
+
+- [Introducing Finance Search in the Agent API](https://www.perplexity.ai/hub/blog/introducing-finance-search-in-the-agent-api) — launch announcement
+- [Agent API Quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart)
+- [Finance Search Tool](https://docs.perplexity.ai/docs/agent-api/tools/finance-search)
+- [Agent API Tools Overview](https://docs.perplexity.ai/docs/agent-api/tools)
+- [Perplexity Python SDK](https://github.com/ppl-ai/perplexity-python)
+- [Equity Research Brief example](../equity-research-brief/README.mdx) — generic ticker version of the same pattern

docs/examples/spacex-spcx-briefing/requirements.txt

@@ -0,0 +1 @@
+perplexityai>=0.6.0