> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Equity Research Brief

> Generate institutional-grade equity research briefs from any public ticker using the Perplexity Agent API and the built-in finance_search tool.

# Equity Research Brief

A command-line tool that generates a structured equity research brief for any public ticker using Perplexity's [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) and the built-in [`finance_search`](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) tool.

`finance_search` returns structured market data — quotes, financials, earnings transcripts, peer comparisons, analyst estimates — so the model can compose a report grounded in numbers, not just narrative. The tool is purpose-built for agentic investor workflows.

## Features

* One command produces a 6-section brief: snapshot, business overview, financial trajectory, latest earnings, peer context, risks, bottom line
* Uses the Agent API's `finance_search` tool for structured fundamentals, quotes, and earnings-call transcripts
* Three preset configurations matching the official `finance_search` recommendations:
  * `quote` — live price/quote only, fastest and cheapest
  * `single` — single-company historical lookup with web context
  * `research` — full multi-step cross-company brief (default)
* Prints citation-ready Perplexity finance source URLs alongside the brief
* Reports `finance_search` invocation count and total request cost
* `--json` flag emits the raw Agent API response for downstream pipelines

## Prerequisites

* Python 3.9+
* A Perplexity API key with Agent API access. `finance_search` is currently in beta — see the [Finance Search docs](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) for availability.

## Installation

```bash theme={null}
cd docs/examples/equity-research-brief
pip install -r requirements.txt
chmod +x equity_research_brief.py
```

## API Key Setup

```bash theme={null}
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

Generate a full research brief on NVIDIA:

```bash theme={null}
./equity_research_brief.py NVDA
```

## Usage

```bash theme={null}
./equity_research_brief.py TICKER [--config {quote,single,research}] [--json] [--api-key KEY]
```

### Just a live quote (cheapest, \~1 tool call)

```bash theme={null}
./equity_research_brief.py AAPL --config quote
```

### Single-company historical lookup with web context

```bash theme={null}
./equity_research_brief.py MSFT --config single
```

### Full multi-step research brief (default)

```bash theme={null}
./equity_research_brief.py NVDA --config research
```

### Emit raw Agent API JSON

```bash theme={null}
./equity_research_brief.py TSLA --json | jq '.usage.cost'
```

## Configuration Reference

| Config     | Model                       | Tools                                         | Max steps | Best for                              |
| ---------- | --------------------------- | --------------------------------------------- | --------- | ------------------------------------- |
| `quote`    | `perplexity/sonar`          | `finance_search`                              | 1         | Live prices, quotes, fastest path     |
| `single`   | `openai/gpt-5.5`            | `web_search` + `finance_search` + `fetch_url` | 5         | One-company historical fundamentals   |
| `research` | `anthropic/claude-opus-4-7` | `web_search` + `finance_search` + `fetch_url` | 10        | Multi-company comparisons, full brief |

These configurations are taken directly from the [`finance_search` recommended configurations](https://docs.perplexity.ai/docs/agent-api/tools/finance-search).

## Example Output (truncated)

```
## 1. Snapshot

- **Price:** $200.23 (as of 2026-05-01 14:10 UTC)
- **Market cap:** $4.87T
- **P/E (TTM):** 40.86
- **52-week range:** $110.82 – $216.83

## 2. Business overview

NVIDIA designs accelerated computing platforms — GPUs, networking, and full-stack
software — used in AI training and inference, gaming, professional visualization,
and automotive. Data Center is the dominant revenue line.

## 3. Financial trajectory
| FY    | Revenue     | Operating margin | Net income |
| ----- | ----------- | ---------------- | ---------- |
| FY25  | $130.5B     | 62.4%            | $72.9B     |
...

---
finance_search: 4 invocation(s) across categories [earnings_history, financials, profile, quote]

Finance sources:
  - https://www.perplexity.ai/finance/NVDA
  - https://www.perplexity.ai/finance/NVDA/earnings?eventId=409967
  - ...

Cost: 0.2817 USD
```

## Code Walkthrough

The script does three things:

**1. Issue a single Agent API call with `finance_search` enabled.**

```python theme={null}
from perplexity import Perplexity

client = Perplexity()
response = client.responses.create(
    model="anthropic/claude-opus-4-7",
    instructions=SYSTEM_PROMPT,
    input=BRIEF_TEMPLATE.format(ticker="NVDA"),
    tools=[
        {"type": "web_search"},
        {"type": "finance_search"},
        {"type": "fetch_url"},
    ],
    max_output_tokens=4096,
    max_steps=10,
)
```

The model decides which `finance_search` categories to fetch (quote, financials, transcript, etc.) based on the prompt. You don't need to hand-pick fields.

**2. Walk `response.output` to extract both the assistant text and the structured `finance_results` blocks.**

```python theme={null}
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 cost and finance source URLs alongside the prose.** The Perplexity finance pages returned in `result.sources` are stable, citation-ready links — useful when the brief is consumed by humans or by a downstream RAG pipeline.

## Prompting Guidance

`finance_search` works best when the prompt asks for a business outcome, not for specific data shapes. The system prompt instructs the model to:

* be quantitative and attribute numbers to the right period (e.g. `FY2025`, `Q3 FY26`)
* never invent numbers — if `finance_search` doesn't return a field, say so explicitly
* format the output in clean Markdown

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. Each preset has different cost characteristics:

* `quote`: typically 1 invocation, \~\$0.007 per brief
* `single`: 1–3 invocations + GPT-5.5 tokens
* `research`: 3–6 invocations + Claude Opus tokens

See [Perplexity Pricing](https://docs.perplexity.ai/docs/getting-started/pricing) for current rates.

## Limitations

* `finance_search` is currently in beta and may not be enabled on all API keys
* Results depend on Perplexity's finance data coverage; obscure or non-US tickers may return less structured data
* This is not investment advice. The "Bottom line" section is explicitly framed as analytical opinion, not a recommendation

## Resources

* [Agent API Quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart)
* [Finance Search Tool](https://docs.perplexity.ai/docs/agent-api/tools/finance-search)
* [Web Search Tool](https://docs.perplexity.ai/docs/agent-api/tools/web-search)
* [Perplexity Python SDK](https://pypi.org/project/perplexityai/)