Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Both POST /v1/rag/answer/agent and POST /v1/rag/orchestrate support two visualization tools:
ToolPurpose
analyze_filing_risksExtract risk keyword signals from any SEC filing using the Loughran-McDonald lexicon
generate_chartProduce an interactive Plotly JSON chart, emitted as a chart SSE event
Charts are rendered automatically when the client receives a chart SSE event — no frontend preprocessing required beyond calling Plotly.newPlot().

​
analyze_filing_risks

Runs the Loughran-McDonald financial risk lexicon across all indexed text chunks for a specific filing. Returns keyword frequencies, per-thousand-word density, top trigger terms, a composite risk score, and the highest-risk category.

​
Input

{
  "name": "analyze_filing_risks",
  "arguments": {
    "accession_number": "0000320193-25-000123",
    "section": "risk factors"
  }
}
ParameterTypeRequiredDescription
accession_numberstringYesFiling accession number from search_filings or research_sec_filing
sectionstringNoIsolate a specific section before counting: "risk factors", "legal proceedings", "liquidity". Omit to analyse the full filing.

​
Output

Risk Analysis — APPLE INC (0000320193-25-000123)
Section: risk factors | Total words analysed: 18,420

Category         Count   Density (‰)   Top terms
─────────────────────────────────────────────────
Litigation         167        9.1      lawsuit×52, litigation×44, class action×28, settlement×21, proceedings×22
Regulatory          98        5.3      compliance×31, investigation×24, enforcement×18, violation×15, fine×10
Market              67        3.6      volatility×22, competition×19, macroeconomic×14, tariff×8, interest rate×4
Operational         52        2.8      supply chain×18, cybersecurity×16, disruption×11, breach×7
Governance          28        1.5      internal control×12, material weakness×9, related party×7
Liquidity           34        1.8      credit rating×14, debt×12, going concern×8

Composite Risk Score: 7.8 / 10
Highest-risk category: Litigation

​
Risk score formula

The composite score (0–10) is a weighted sum of keyword counts per category, normalised by total word count and scaled: 
score = min(
  sum(count[cat] × weight[cat] for cat in categories) / 50,
  10.0
)
Category weights: Governance=1.5, Litigation=1.4, Liquidity=1.3, Regulatory=1.2, Operational=1.0, Market=0.9.

​
Risk lexicon categories

lawsuit, litigation, proceeding, arbitration, damages, class action, settlement, subpoena, plaintiff, defendant, injunction, verdict, indemnification, judgment, appeal
liquidity, insolvency, cash flow, working capital, default, covenant, going concern, indebtedness, refinancing, credit rating, downgrade, maturity, solvency, liquidity risk, cash position
compliance, fine, penalty, sanction, investigation, enforcement, violation, remediation, examination, corrective action, regulatory action, non-compliance, audit finding, regulatory change, regulatory risk
volatility, inflation, recession, interest rate, currency, tariff, macroeconomic, downturn, competitive pressure, pricing pressure, foreign exchange, market risk, demand risk, commodity price, geopolitical
supply chain, disruption, outage, cybersecurity, breach, recall, shortage, single source, concentration risk, dependency, operational failure, system failure, key personnel, natural disaster, pandemic
restatement, material weakness, internal control, whistleblower, fraud, misconduct, departure, related party, going concern, material error, audit committee, corporate governance, conflict of interest, ethical violation, executive compensation

​
generate_chart

Generates an interactive Plotly chart and appends it to the SSE stream as a chart event. The agent references the chart in its final answer as [Chart 1], [Chart 2], etc.

​
Chart SSE event

{
  "type": "chart",
  "chart_id": "chart_1",
  "title": "Litigation Risk vs Revenue — $AAPL",
  "chart_type": "dual_axis",
  "plotly": {
    "data": [...],
    "layout": {...}
  }
}
Pass plotly.data and plotly.layout directly to Plotly.newPlot().

​
Chart types

​
dual_axis — Risk vs financial metric correlation

The primary chart for financial risk analysis. Bars show risk keyword counts on the right Y-axis; lines show financial metrics (revenue, earnings) on the left Y-axis — both on a shared time axis with unified hover tooltips. Best for: Showing that risk keyword spikes precede or coincide with revenue drops. 
{
  "chart_type": "dual_axis",
  "title": "Litigation Risk vs Revenue — $AAPL",
  "spec": {
    "x": ["FY2022", "FY2023", "FY2024", "FY2025"],
    "bar_series": [
      { "name": "Litigation Mentions", "data": [118, 134, 151, 167], "color": "#ef4444" }
    ],
    "line_series": [
      { "name": "Revenue ($B)", "data": [394, 383, 391, 400], "color": "#3b82f6" }
    ],
    "y1_label": "Revenue ($B)",
    "y2_label": "Litigation Mentions",
    "ticker": "AAPL"
  }
}
Spec fields:
FieldTypeDescription
xlist[str]Shared X-axis labels (years, quarters, or dates)
bar_series[{name, data, color?}]Bar traces — plotted on the right axis
line_series[{name, data, color?}]Line traces — plotted on the left axis
y1_labelstrLeft axis label
y2_labelstrRight axis label
tickerstr?Appended to title as — $TICKER

​
bar — Risk category breakdown

Horizontal grouped bar chart. Use to show relative risk exposure across the six Loughran-McDonald categories. 
{
  "chart_type": "bar",
  "title": "Apple Risk Category Breakdown — 10-K 2025",
  "spec": {
    "categories": ["Litigation", "Regulatory", "Market", "Liquidity", "Operational", "Governance"],
    "counts": [167, 98, 67, 34, 52, 28],
    "x_label": "Keyword Mentions",
    "subtitle": "Source: Apple 10-K, filed Nov 2025 | Loughran-McDonald lexicon"
  }
}
Spec fields:
FieldTypeDescription
categorieslist[str]Category labels (Y-axis)
countslist[number]Keyword counts per category
x_labelstr?X-axis label
subtitlestr?Small annotation below the chart
Multi-line time series chart. Use for tracking a single metric (or multiple metrics) over time. 
{
  "chart_type": "line",
  "title": "Risk Score Trend — $AAPL vs $MSFT",
  "spec": {
    "series": [
      { "name": "Apple",     "x": ["FY2022","FY2023","FY2024","FY2025"], "y": [6.1, 6.8, 7.2, 7.8], "color": "#3b82f6" },
      { "name": "Microsoft", "x": ["FY2022","FY2023","FY2024","FY2025"], "y": [5.4, 5.9, 6.3, 6.7], "color": "#10b981" }
    ],
    "x_label": "Fiscal Year",
    "y_label": "Composite Risk Score (0–10)"
  }
}
Spec fields:
FieldTypeDescription
series[{name, x, y, color?, dash?}]Line traces. dash: "solid" (default), "dash", "dot"
x_labelstr?X-axis label
y_labelstr?Y-axis label

​
heatmap — Risk intensity matrix

2D heatmap of risk intensity (rows = risk categories, columns = years/quarters). Use for a quick cross-year risk overview. 
{
  "chart_type": "heatmap",
  "title": "Apple Risk Heatmap — 2022–2025",
  "spec": {
    "x_labels": ["FY2022", "FY2023", "FY2024", "FY2025"],
    "y_labels": ["Litigation", "Regulatory", "Market", "Liquidity", "Operational", "Governance"],
    "z_matrix": [
      [118, 134, 151, 167],
      [ 72,  81,  89,  98],
      [ 54,  60,  63,  67],
      [ 28,  30,  32,  34],
      [ 41,  44,  48,  52],
      [ 21,  23,  26,  28]
    ],
    "color_scale": "Reds"
  }
}
Spec fields:
FieldTypeDescription
x_labelslist[str]Column labels (e.g. years)
y_labelslist[str]Row labels (e.g. risk categories)
z_matrixlist[list[number]]2D value matrix — rows align with y_labels, columns with x_labels
color_scalestr?Plotly colorscale: "Reds" (default), "YlOrRd", "RdBu_r"

​
Frontend rendering (React + Plotly.js)

import Plot from 'react-plotly.js';

interface ChartEvent {
  type: 'chart';
  chart_id: string;
  title: string;
  chart_type: string;
  plotly: { data: Plotly.Data[]; layout: Partial<Plotly.Layout> };
}

function ChartRenderer({ event }: { event: ChartEvent }) {
  return (
    <Plot
      data={event.plotly.data}
      layout={{
        ...event.plotly.layout,
        autosize: true,
        margin: { l: 60, r: 60, t: 60, b: 60 },
      }}
      style={{ width: '100%', height: '400px' }}
      useResizeHandler
    />
  );
}
Install: npm install react-plotly.js plotly.js

​
Boilerplate score

When calling analyze_filing_risks across multiple filings for the same company, the underlying extraction engine also computes a boilerplate score — the Jaccard similarity of character 3-gram sets between the current and previous filing’s risk text. A score > 0.85 indicates the company copied its risk factor language word-for-word between filings — a common pattern when risks haven’t actually changed. A score < 0.50 indicates significantly new or revised risk language worth reading carefully. This metric is surfaced in advanced risk comparisons and is used internally to weight YoY delta calculations. 
1. research_sec_filing (query="risk factors for [company]", form_types=["10-K"])
        ↓ returns accession_number
2. analyze_filing_risks (accession_number=..., section="risk factors")
        ↓ returns category counts, density, risk_score, highest_risk_category
3. generate_chart (chart_type="bar", categories=[...], counts=[...])
        ↓ emits chart SSE event → render with Plotly.newPlot()
4. generate_chart (chart_type="dual_axis", bar_series=risk_counts, line_series=revenue)
        ↓ correlation chart — bar=risk keywords (right axis), line=revenue (left axis)
For multi-year trend analysis, repeat steps 1–2 for each filing year, then combine the results in a single dual_axis or heatmap chart.