Workflows

End-to-end recipes for common Disclosure Alpha tasks.

Audience: Users who know their goal and want a copy-paste path. Before you start: Installation and SEC EDGAR Setup for EDGAR-backed examples.

Score one ticker and read the JSON (CLI)

Goal: Get a headline score and component breakdown for one company.

export SEC_USER_AGENT="YourName your@email.com"
disclosure-alpha score --ticker AAPL --fiscal-year 2025 --form 10-K \
  | jq '{overall: .scores.overall_disclosure_risk_score, coverage: .scores.score_coverage_ratio, components: .scores.components}'

Sample output

    "extraction_confs": [
      0.35,
      0.35
    ],
    "diff_confs": [
      0.2,
      0.2
    ],
    "extraction_warnings": [],
    "required_sections_present": true,
    "has_prior": false
  },
  "scores": {
    "overall_disclosure_risk_score": 33.159052,
    "score_coverage_ratio": 0.7778,
    "confidence_score": 0.3426,
    "missing_components": [
      "disclosure_change_score",
      "event_severity_score"
    ],
    "components": {
      "risk_factor_intensity_score": 60.0,

(Shape matches live CLI output; values differ by filing.)

How to read it

  • overall_disclosure_risk_score — headline 0–100; see Understanding Scores

  • score_coverage_ratio — how many headline components were computed

  • missing_components — often missing MD&A or no prior filing for change score

If something looks wrong

FAQ and Troubleshooting and CLI Guide.

Batch panel screen (HTTP)

Goal: Score up to 25 tickers in one request for a screener or dashboard.

Start the API:

export SEC_USER_AGENT="YourName your@email.com"
disclosure-alpha-api

Screen tickers:

curl -s -X POST "http://localhost:8000/v1/panel/disclosure-matrix" \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["AAPL", "MSFT", "GOOGL"],
    "fiscal_year": 2025,
    "form_type": "10-K"
  }' | jq '.results[] | {ticker, status, overall: .scores.overall_disclosure_risk_score}'

Sample output

{
  "results": [
    {
      "ticker": "AAPL",
      "status": "ok",
      "filing": {
        "ticker": "AAPL",
        "fiscal_year": 2025,
        "form_type": "10-K"
      },
      "scores": {
        "overall_disclosure_risk_score": 33.159052,
        "score_coverage_ratio": 0.7778,
        "confidence_score": 0.3426,
        "missing_components": [
          "disclosure_change_score",
          "event_severity_score"
        ],
        "components": {
          "risk_factor_intensity_score": 60.0,
          "disclosure_change_score": null,
          "mdna_uncertainty_score": 26.726221,
          "legal_regulatory_risk_score": 37.6724,
          "liquidity_stress_score": 4.030477,
          "boilerplate_risk_score": 42.528733,
          "internal_controls_risk_score": 3.4483,
          "event_severity_score": null,
          "specificity_quality_score": 36.2069,
          "tone_negativity_score": 5.2956,
          "cybersecurity_incident_risk_score": null,
          "event_materiality_score": null
        }
      }
    },
    {
      "ticker": "BAD",
      "status": "error",
      "error": "No 10-K for BAD FY2025"
    }
  ],
  "summary": {
    "ok": 1,
    "failed": 1
  },
  "versions": {
    "scoring_model_version": "deterministic_scoring_v2"
  }
}

How to read it

  • results[].status — "ok" or "error" per ticker; the request does not fail-fast

  • results[].scores — same score shape as CLI when status is ok

  • summary — count of successes vs failures

If something looks wrong

Panel 422 (>25 tickers) and per-ticker errors: FAQ and Troubleshooting.

Notebook: score and inspect components (Python)

Goal: Explore component scores interactively in a notebook.

import os
os.environ["SEC_USER_AGENT"] = "YourName your@email.com"

from disclosure_alpha import score_filing_ticker

result = score_filing_ticker("AAPL", 2025, form_type="10-K")
scores = result.scores
print(scores.overall_disclosure_risk_score, scores.score_coverage_ratio)
for name, value in scores.components.__dict__.items():
    if value is not None:
        print(f"{name}: {value:.1f}")

Sample output

Use the scores block from Understanding Scores as a reference for field names.

How to read it

  • Sort components by value to see which language signals dominate

  • Compare specificity_quality_score separately — higher is better (inverse of most components)

  • Request provenance from result.to_dict()["scores"]["provenance"] for audit trails

If something looks wrong

FAQ and Troubleshooting.

Agent workflow: MCP analyst vs builder

Goal: Wire Disclosure Alpha into an MCP client.

Analyst — your agent knows tickers, not raw HTML:

disclosure-alpha-mcp-analyst

Tools: list_company_filings_tool, score_company_filing_tool.

Builder — your agent has filing HTML and needs pipeline steps:

disclosure-alpha-mcp-builder

Tools: extract_sections_tool, compute_section_metrics_tool_wrapper, score_filing_html_tool_wrapper, etc.

Configure SEC_USER_AGENT in env. See MCP Guide.

Local HTML only (no EDGAR)

Goal: Score offline with current and prior HTML files.

disclosure-alpha score --html filing.html --form 10-K \
  --prior-html prior.html \
  | jq '.scores.overall_disclosure_risk_score'

With prior HTML, disclosure_change_score populates when matching sections exist:

{
  "overall_disclosure_risk_score": 33.10187,
  "score_coverage_ratio": 1.0,
  "confidence_score": 0.6729,
  "missing_components": [],
  "components": {
    "risk_factor_intensity_score": 56.2975,
    "disclosure_change_score": 38.6268,
    "mdna_uncertainty_score": 26.726221,
    "legal_regulatory_risk_score": 30.317069,
    "liquidity_stress_score": 4.030477,
    "boilerplate_risk_score": 42.528733,

No network or SEC_USER_AGENT required when both files are local.