Herramienta de línea de comandos para informes de investigación de acciones

Una herramienta de línea de comandos que genera un informe estructurado de investigación de acciones para cualquier ticker público usando la Agent API de Perplexity y la herramienta incorporada finance_search.

finance_search devuelve datos de mercado estructurados —cotizaciones, finanzas, transcripciones de ganancias, comparaciones con pares, estimaciones de analistas— para que el modelo pueda redactar un informe basado en números, no solo en narrativa. La herramienta está diseñada específicamente para flujos de trabajo de inversores agénticos.

Características

• Un comando produce un informe de 6 secciones: instantánea, descripción general del negocio, trayectoria financiera, últimas ganancias, contexto de pares, riesgos, conclusión.
• Usa la herramienta finance_search de la Agent API para fundamentos estructurados, cotizaciones y transcripciones de llamadas de ganancias.
• Tres configuraciones preestablecidas que coinciden con las recomendaciones oficiales de finance_search:
  • quote — solo precio/cotización en vivo, el más rápido y económico
  • single — búsqueda histórica de una sola empresa con contexto web
  • research — informe completo de varios pasos entre empresas (predeterminado)
• Imprime URL de fuentes financieras de Perplexity listas para citar junto con el informe.
• Reporta el recuento de invocaciones de finance_search y el costo total de la solicitud.
• La bandera --json emite la respuesta bruta de la Agent API para pipelines posteriores.

Requisitos previos

• Python 3.9+
• Una clave API de Perplexity con acceso a la Agent API. finance_search está actualmente en beta; consulta la documentación de Finance Search para conocer la disponibilidad.

Instalación

cd docs/examples/equity-research-brief
pip install -r requirements.txt
chmod +x equity_research_brief.py

Configuración de la clave API

export PERPLEXITY_API_KEY="your-api-key-here"

También puedes pasar la clave a través de --api-key, o colocarla en un archivo .pplx_api_key en el directorio de trabajo.

Inicio rápido

Genera un informe de investigación completo sobre NVIDIA:

./equity_research_brief.py NVDA

Uso

./equity_research_brief.py TICKER [--config {quote,single,research}] [--json] [--api-key KEY]

Solo una cotización en vivo (la más económica, ~1 llamada a la herramienta)

./equity_research_brief.py AAPL --config quote

Búsqueda histórica de una sola empresa con contexto web

./equity_research_brief.py MSFT --config single

Informe de investigación completo de varios pasos (predeterminado)

./equity_research_brief.py NVDA --config research

Emitir JSON bruto de la Agent API

./equity_research_brief.py TSLA --json | jq '.usage.cost'

Referencia de configuración

Estas configuraciones se toman directamente de las configuraciones recomendadas de finance_search.

Ejemplo de salida (truncado)

## 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

Análisis del código

El script hace tres cosas:

1. Realiza una única llamada a la Agent API con finance_search habilitado.

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,
)

El modelo decide qué categorías de finance_search buscar (cotización, finanzas, transcripción, etc.) basándose en el prompt. No necesitas seleccionar campos manualmente.

2. Recorre response.output para extraer tanto el texto del asistente como los bloques estructurados de finance_results.

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. Muestra el costo y las URL de las fuentes financieras junto con la prosa. Las páginas financieras de Perplexity devueltas en result.sources son enlaces estables y listos para citar, útiles cuando el informe es consumido por humanos o por un pipeline RAG posterior.

Guía de prompting

finance_search funciona mejor cuando el prompt solicita un resultado de negocio, no formas de datos específicas. El prompt del sistema instruye al modelo a:

• ser cuantitativo y atribuir números al período correcto (por ejemplo, FY2025, Q3 FY26)
• nunca inventar números; si finance_search no devuelve un campo, decirlo explícitamente
• formatear la salida en Markdown limpio

Este patrón está documentado en la guía de prompting de finance_search.

Precios

finance_search se factura a $5 por cada 1,000 invocaciones, separado del uso de tokens del modelo. Cada configuración preestablecida tiene diferentes características de costo:

• quote: típicamente 1 invocación, ~$0.007 por informe
• single: 1–3 invocaciones + tokens GPT-5.5
• research: 3–6 invocaciones + tokens Claude Opus

Consulta la página de precios de Perplexity para conocer las tarifas actuales.

Limitaciones

• finance_search está actualmente en beta y puede que no esté habilitado en todas las claves API.
• Los resultados dependen de la cobertura de datos financieros de Perplexity; los tickers oscuros o no estadounidenses pueden devolver menos datos estructurados.
• Esto no es asesoramiento de inversión. La sección "Conclusión" se enmarca explícitamente como opinión analítica, no como una recomendación.

Recursos

• Inicio rápido de la Agent API
• Herramienta Finance Search
• Descripción general de las herramientas de la Agent API
• SDK de Python de Perplexity