Fondamentali e SEC

Bilanci, indici fondamentali, utili, stime e fonti ufficiali SEC EDGAR (filing, XBRL storico, Form 4, 13F). La base per analisi e valutazioni.

get_income_statements

Cosa fa. Conto economico: ricavi, costi, utile netto su un periodo di rendicontazione.

Quando/come lo usa l’AI. Per valutare redditività ed efficienza operativa.

Parametri. ticker, period (annual/quarterly), limit.

Restituisce. Voci del conto economico.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_balance_sheets

Cosa fa. Stato patrimoniale: attività, passività e patrimonio netto a una data.

Quando/come lo usa l’AI. Per la posizione finanziaria e la solidità.

Parametri. ticker, period, limit.

Restituisce. Voci dello stato patrimoniale.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_cash_flow_statements

Cosa fa. Rendiconto finanziario: flussi operativi, di investimento e di finanziamento.

Quando/come lo usa l’AI. Per liquidità, generazione di cassa e qualità degli utili.

Parametri. ticker, period, limit.

Restituisce. Voci del rendiconto.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_all_financial_statements

Cosa fa. Tutti e tre i bilanci (CE, SP, rendiconto) in una sola chiamata.

Quando/come lo usa l’AI. Quando servono dati di bilancio completi: più efficiente di tre chiamate separate.

Parametri. ticker, period, limit.

Restituisce. I tre bilanci insieme.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_key_ratios

Cosa fa. Snapshot di indici chiave: P/E, market cap, margini, ROE, ROA, Piotroski, Altman Z, consenso analisti, massimo/minimo 52 settimane, azionariato, short float.

Quando/come lo usa l’AI. Punto di partenza per quasi ogni analisi fondamentale o di valutazione.

Parametri. ticker.

Restituisce. Snapshot di metriche e ratios.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_historical_key_ratios

Cosa fa. Indici storici per anno o trimestre: P/E, P/B, ROE, margini, EV/EBITDA.

Quando/come lo usa l’AI. Per trend di valutazione pluriennali ed espansione/contrazione dei multipli.

Parametri. ticker, period, limit.

Restituisce. Serie storica dei ratios.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_earnings

Cosa fa. Dati sugli utili: EPS/ricavi beat-miss, sorprese e storico delle pubblicazioni.

Quando/come lo usa l’AI. Intorno alle trimestrali o per la qualità degli utili.

Parametri. ticker.

Restituisce. Storico utili e sorprese.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_analyst_estimates

Cosa fa. Stime degli analisti: ricavi, EPS, target di prezzo e ripartizione buy/hold/sell.

Quando/come lo usa l’AI. Per consenso, target e previsioni di crescita.

Parametri. ticker.

Restituisce. Stime e rating di consenso.

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_sec_filings

Cosa fa. Elenca i filing SEC recenti (10-K, 10-Q, 8-K, Form 4…) con gli URL dei documenti.

Quando/come lo usa l’AI. Per fonti ufficiali e per ottenere l’URL da passare a get_sec_document.

Parametri. ticker, form_type (opzionale), limit.

Restituisce. Lista filing con URL.

Possibili errori / stati.

• Vuoto se la SEC non ha filing per quella società/forma.

get_sec_financials

Cosa fa. Dati di bilancio ufficiali XBRL da SEC EDGAR — 20 metriche: revenue, net_income, eps_diluted/basic, operating_income, gross_profit, operating_cash_flow, capex, total_assets, total_liabilities, stockholders_equity, current_assets/liabilities, cash, long_term_debt, depreciation, interest_expense, income_tax_expense, rd_expense, shares_outstanding.

Quando/come lo usa l’AI. Quando servono figure GAAP ufficiali o storico più lungo del DB (es. DCF, qualità utili).

Parametri. ticker, metric, period (annual/quarterly), limit.

Restituisce. Serie storica della metrica richiesta.

Possibili errori / stati.

• data_warning — i dati più recenti sono vecchi (es. 2014-2018): la società ha cambiato il concetto XBRL. Va segnalato all’utente.
• Supporto IFRS automatico: per gli ADR esteri (SONY, TSM, ASML…) ritenta col namespace ifrs-full (campo xbrl_namespace).
• Fallback ricavi automatico (ASC 606 → Revenues → SalesRevenueNet → IncludingAssessedTax → RevenueNotFromContractWithCustomer per le banche).

get_sec_document

Cosa fa. Legge il testo completo di un documento SEC (HTML o PDF) da www.sec.gov.

Quando/come lo usa l’AI. Per leggere MD&A, fattori di rischio o il testo integrale di un filing.

Parametri. url (dal filing), max_chars.

Restituisce. Testo del documento.

Possibili errori / stati.

• Errore se l’URL non è raggiungibile o non è un documento SEC valido.

get_sec_form4

Cosa fa. Estrae l’XML dei Form 4 da SEC EDGAR con i codici di transazione insider (P/S/A/M/F/D/G/J/C) che yfinance non fornisce.

Quando/come lo usa l’AI. Per l’attività insider precisa (acquisti reali di mercato vs esercizi opzioni vs award).

Parametri. ticker, limit.

Restituisce. Transazioni Form 4 con codici, azioni, prezzo, valore.

Possibili errori / stati.

• XML not accessible (...) — per quel filing l’XML non è leggibile: ripiega su get_sec_document con l’URL HTML preso da get_sec_filings.

get_insider_trades

Cosa fa. Attività insider dal DB locale (fonte yfinance): transazioni di dirigenti e amministratori.

Quando/come lo usa l’AI. Per uno sguardo rapido; per i codici SEC precisi preferisci get_sec_form4.

Parametri. ticker.

Restituisce. Acquisti/vendite insider (testo, senza codici SEC).

Possibili errori / stati.

• Nessun errore esplicito: se il ticker non è tracciato o non ci sono dati nel range, la risposta è vuota. L’agente può allora chiamare add_ticker (o add_crypto/add_future/add_fund/add_forex) e riprovare.

get_institutional_holdings

Cosa fa. Holdings istituzionali 13F: chi detiene un titolo (modo ticker) o il portafoglio di un fondo (modo filer).

Quando/come lo usa l’AI. Per l’azionariato istituzionale o per replicare il 13F di un gestore (Berkshire, BlackRock…).

Parametri. ticker oppure filer_name/filer_cik, limit.

Restituisce. Lista di detentori o di posizioni del filer.

Nota. Dati con lag ~45 giorni (i 13F si depositano dopo la fine del trimestre).