id: sec-8k-filing-watcher
namespace: company.team
inputs:
- id: tickers
type: ARRAY
itemType: STRING
displayName: Tickers to watch
description: US-listed companies to watch, by ticker symbol. Tickers not in
SEC's ticker list are skipped with a warning.
defaults:
- AAPL
- MSFT
- NVDA
- JPM
- PFE
- id: lookback_days
type: INT
displayName: First-run lookback (days)
description: For a ticker with no saved marker yet (the first run, or a newly
added ticker), only 8-Ks filed in this many past days are processed.
defaults: 7
min: 1
max: 365
- id: max_filings
type: INT
displayName: Maximum filings per run
description: Oldest filings are processed first. Anything over the cap is left
for the next run, so nothing is skipped.
defaults: 20
min: 1
max: 200
# Docker Desktop (Mac, Windows) resolves host.docker.internal to the host. On Linux, either add
# `extra_hosts: ["host.docker.internal:host-gateway"]` to the Kestra service in docker-compose.yml
# or use the host's IP (for example the Docker bridge, http://172.17.0.1:11434). Ollama on Linux
# listens on localhost only by default: set OLLAMA_HOST=0.0.0.0:11434 (`sudo systemctl edit ollama`)
# and keep port 11434 closed to the outside. Ollama in the same Compose project: http://ollama:11434.
- id: ollama_endpoint
type: STRING
displayName: Ollama endpoint
description: Base URL where Ollama listens, without a trailing slash. The
default reaches Ollama on the host from Kestra in Docker Desktop (Mac,
Windows); on Linux see the blueprint's Prerequisites.
defaults: http://host.docker.internal:11434
- id: model
type: STRING
displayName: Ollama model
description: A model already pulled into Ollama. qwen2.5:1.5b returned valid
JSON and a correct sentiment on all 5 test filings, at about 5 seconds
each on a laptop.
defaults: qwen2.5:1.5b
tasks:
- id: fetch_new_filings
type: io.kestra.plugin.scripts.python.Script
description: >
Find 8-Ks filed since each ticker's marker, then download each one's main
document and its Exhibit 99. Only form 8-K is watched; amendments (8-K/A)
and other forms are ignored.
containerImage: python:3.13.16-slim-trixie
timeout: PT10M
env:
# SEC requires a User-Agent that names you and gives a contact email. Set it once in the KV store.
USER_AGENT: "{{ kv('SEC_EDGAR_USER_AGENT', errorOnMissing=false) ?? '' }}"
TICKERS: "{{ inputs.tickers | toJson }}"
MARKERS: "{{ (kv(flow.id ~ '_markers', errorOnMissing=false) ?? {}) | toJson }}"
LOOKBACK_DAYS: "{{ inputs.lookback_days }}"
MAX_FILINGS: "{{ inputs.max_filings }}"
outputFiles:
- filings.json
script: |
import datetime, html, json, os, re, sys, time, urllib.request
user_agent = os.environ["USER_AGENT"].strip()
if "@" not in user_agent:
sys.exit("Set the KV key SEC_EDGAR_USER_AGENT in this namespace to your name or company and a "
"contact email, for example 'Jane Doe jane.doe@example.com'. SEC blocks unidentified tools.")
def get(url):
time.sleep(0.15) # SEC allows at most 10 requests per second
request = urllib.request.Request(url, headers={"User-Agent": user_agent, "Accept-Encoding": "identity"})
return urllib.request.urlopen(request, timeout=30).read()
def to_text(raw):
page = re.sub(r"(?is)<(script|style|ix:header).*?</\1>", " ", raw.decode("utf-8", "ignore"))
return re.sub(r"\s+", " ", html.unescape(re.sub(r"(?s)<[^>]+>", " ", page))).strip()
markers = json.loads(os.environ["MARKERS"]) or {}
since = (datetime.date.today() - datetime.timedelta(days=int(os.environ["LOOKBACK_DAYS"]))).isoformat()
ciks = {row["ticker"]: row["cik_str"] for row in json.loads(get("https://www.sec.gov/files/company_tickers.json")).values()}
new = []
for ticker in json.loads(os.environ["TICKERS"]):
ticker = ticker.strip().upper()
if ticker not in ciks:
print(f"WARNING: {ticker} is not in SEC's ticker list, skipped")
continue
cik = ciks[ticker]
submissions = json.loads(get(f"https://data.sec.gov/submissions/CIK{cik:010d}.json"))
recent = submissions["filings"]["recent"]
marker = markers.get(str(cik))
for row in (dict(zip(recent, values)) for values in zip(*recent.values())):
if row["form"] != "8-K":
continue
if (marker and row["acceptanceDateTime"] <= marker) or (not marker and row["filingDate"] < since):
continue
new.append({"ticker": ticker, "cik": cik, "company": submissions["name"],
**{key: row[key] for key in ("accessionNumber", "filingDate", "acceptanceDateTime", "items", "primaryDocument")}})
new.sort(key=lambda filing: filing["acceptanceDateTime"]) # oldest first; the rest waits for the next run
new = new[: int(os.environ["MAX_FILINGS"])]
for filing in new:
folder = f"https://www.sec.gov/Archives/edgar/data/{filing['cik']}/{filing['accessionNumber'].replace('-', '')}"
# The index headers give each document's official type, e.g. EX-99.1, whatever the file is called.
headers = html.unescape(get(f"{folder}/{filing['accessionNumber']}-index-headers.html").decode("utf-8", "ignore"))
documents = re.findall(r"<TYPE>([^<\s]+)\s*<SEQUENCE>[^<]*<FILENAME>([^<\s]+)", headers)
exhibit = next((name for kind, name in documents
if kind.upper().startswith("EX-99") and name.endswith((".htm", ".html", ".txt"))), None)
body = to_text(get(f"{folder}/{filing['primaryDocument']}"))
if exhibit:
body += " EXHIBIT 99: " + to_text(get(f"{folder}/{exhibit}"))
start = re.search(r"Item\s+\d\.\d\d", body)
# 8,000 characters keeps prompt and answer inside Ollama's default 4,096-token context.
filing.update(url=f"{folder}/{filing['primaryDocument']}", exhibit=exhibit,
text=body[start.start() if start else 0:][:8000])
print(f"{filing['ticker']} {filing['filingDate']} items {filing['items']} exhibit {exhibit or '-'}")
json.dump(new, open("filings.json", "w"))
print("::" + json.dumps({"outputs": {"count": len(new), "accessions": [f["accessionNumber"] for f in new]}}) + "::")
- id: nothing_new
type: io.kestra.plugin.core.log.Log
description: Say so explicitly when there is nothing to do, so a quiet run is
not mistaken for a broken one.
runIf: "{{ outputs.fetch_new_filings.vars.count == 0 }}"
message: No new 8-K filings for {{ inputs.tickers | join(', ') }}.
- id: summarize_each
type: io.kestra.plugin.core.flow.Loop
description: One LLM call per filing. One at a time, because a single local
Ollama works through requests one by one anyway.
runIf: "{{ outputs.fetch_new_filings.vars.count > 0 }}"
values: "{{ outputs.fetch_new_filings.vars.accessions }}"
concurrencyLimit: 1
tasks:
- id: summarize
type: io.kestra.plugin.ai.completion.ChatCompletion
description: >
Summarize the filing and rate its sentiment for shareholders. Item
numbers are not asked for: they come from EDGAR. The Ollama provider
does not apply maxToken, so the timeout is what stops a runaway
answer; allowFailure lets the other filings continue.
timeout: PT2M
allowFailure: true
provider:
type: io.kestra.plugin.ai.provider.Ollama
modelName: "{{ inputs.model }}"
endpoint: "{{ inputs.ollama_endpoint }}"
configuration:
temperature: 0.0
responseFormat:
type: JSON
# Workaround for a plugin-ai bug: the properties reach Ollama in HashMap order, not YAML
# order. Ollama writes the fields in that order, and the summary must come first: rating
# sentiment before writing the summary gave long summaries and wrong ratings in testing,
# and an instruction in the prompt does not change it. With these two names the HashMap
# order is right; check_and_report flags every answer if that ever changes.
jsonSchema:
type: object
required:
- summary
- sentiment
properties:
summary:
type: string
sentiment:
type: string
enum:
- positive
- neutral
- negative
messages:
- type: SYSTEM
content: >
You read SEC Form 8-K filings. Return JSON with summary (one or
two sentences, at most 60 words, on what happened) and sentiment
for shareholders (positive, neutral or negative).
- type: USER
content: >-
{% set filing =
read(outputs.fetch_new_filings.outputFiles['filings.json'])
| jq('.[] | select(.accessionNumber == "' ~ item.value ~ '")') | first %}
FILING: {{ filing.text }}
outputs:
- id: accession
type: STRING
value: "{{ item.value }}"
- id: answer
type: STRING
description: The model's JSON answer, or null if the call failed or timed out.
value: "{{ (outputs.summarize.jsonOutput ?? null) | toJson }}"
- id: ollama_status
type: io.kestra.plugin.core.http.Request
description: >
List the models Ollama has, from the same place the LLM calls are made. If
every call failed, check_and_report uses this to tell an outage (retry
later) from genuine timeouts.
runIf: "{{ outputs.fetch_new_filings.vars.count > 0 }}"
uri: "{{ inputs.ollama_endpoint }}/api/tags"
timeout: PT15S
allowFailure: true
- id: check_and_report
type: io.kestra.plugin.scripts.python.Script
description: >
Check every answer against its filing, write the report, and compute the
new markers. An answer is flagged (and its sentiment withheld) if the
sentiment is not positive, neutral or negative, the summary is not 5 to 80
words, a dollar amount or percentage in it is not in the filing, or the
model rated sentiment before writing the summary. These checks catch
invented numbers, not every mistake: a small model can still join two true
facts wrongly, so the report links each filing. Sentiment is a coarse
triage label: an earnings release with a loss and raised guidance can come
back as positive.
runIf: "{{ outputs.fetch_new_filings.vars.count > 0 }}"
containerImage: python:3.13.16-slim-trixie
timeout: PT5M
inputFiles:
filings.json: "{{ outputs.fetch_new_filings.outputFiles['filings.json'] }}"
env:
ANSWERS: "{{ outputs.summarize_each.outputs | toJson }}"
MARKERS: "{{ (kv(flow.id ~ '_markers', errorOnMissing=false) ?? {}) | toJson }}"
OLLAMA_TAGS: "{{ outputs.ollama_status.body ?? '' }}"
OLLAMA_ENDPOINT: "{{ inputs.ollama_endpoint }}"
MODEL: "{{ inputs.model }}"
outputFiles:
- report.md
- results.json
script: |
import json, os, re, sys
ITEM_NAMES = {
"1.01": "Entry into a Material Definitive Agreement", "1.02": "Termination of a Material Definitive Agreement",
"1.03": "Bankruptcy or Receivership", "1.04": "Mine Safety", "1.05": "Material Cybersecurity Incidents",
"2.01": "Completion of Acquisition or Disposition of Assets", "2.02": "Results of Operations and Financial Condition",
"2.03": "Creation of a Direct Financial Obligation", "2.04": "Triggering Events That Accelerate a Financial Obligation",
"2.05": "Costs of Exit or Disposal Activities", "2.06": "Material Impairments",
"3.01": "Delisting or Failure to Meet a Listing Rule", "3.02": "Unregistered Sales of Equity Securities",
"3.03": "Material Modification to Rights of Security Holders", "4.01": "Change in Certifying Accountant",
"4.02": "Non-Reliance on Previously Issued Financial Statements", "5.01": "Change in Control",
"5.02": "Departure or Appointment of Directors or Officers", "5.03": "Amendments to Articles or Bylaws",
"5.04": "Suspension of Trading Under Employee Benefit Plans", "5.05": "Amendments to the Code of Ethics",
"5.06": "Change in Shell Company Status", "5.07": "Shareholder Vote Results", "5.08": "Shareholder Director Nominations",
"7.01": "Regulation FD Disclosure", "8.01": "Other Events", "9.01": "Financial Statements and Exhibits",
}
SCALE = {"thousand": 1e3, "million": 1e6, "billion": 1e9, "trillion": 1e12}
DOLLARS = re.compile(r"\$\s?(\d[\d,]*(?:\.\d+)?)(?:\s?(thousand|million|billion|trillion))?", re.I)
PERCENTS = re.compile(r"(\d+(?:\.\d+)?)\s?(?:%|percent\b)", re.I)
def amounts(text):
# "$15 billion" and "$15,000,000,000" are the same amount
return {round(float(n.replace(",", "")) * SCALE.get(unit.lower(), 1), 2) for n, unit in DOLLARS.findall(text)}
def percents(text):
return {float(n) for n in PERCENTS.findall(text)}
filings = json.load(open("filings.json"))
answers = {row["outputs"]["accession"]: json.loads(row["outputs"]["answer"]) for row in json.loads(os.environ["ANSWERS"])}
if not any(answers.values()):
# Every call failed. If Ollama or the model is missing, stop before the markers move,
# so the same filings are retried once Ollama is back.
try:
models = [m["name"] for m in json.loads(os.environ["OLLAMA_TAGS"])["models"]]
ready = os.environ["MODEL"] in models or os.environ["MODEL"] + ":latest" in models
except (ValueError, KeyError, TypeError):
ready = False
if not ready:
sys.exit(f"No answer from {os.environ['MODEL']} at {os.environ['OLLAMA_ENDPOINT']}: Ollama is down "
"or the model is not pulled. Markers were not moved, so these filings will be retried.")
results, markers = [], json.loads(os.environ["MARKERS"]) or {}
for filing in filings:
answer, problems = answers.get(filing["accessionNumber"]), []
if answer is None:
status = "summary_unavailable"
else:
summary, sentiment = str(answer.get("summary", "")).strip(), answer.get("sentiment")
if next(iter(answer), None) != "summary":
# The answer keeps the order the model wrote it in (see the comment on jsonSchema).
problems.append("the model rated sentiment before writing the summary; the schema "
"field order changed, see the blueprint description")
if sentiment not in ("positive", "neutral", "negative"):
problems.append(f"sentiment {sentiment!r} is not positive, neutral or negative")
if not 5 <= len(summary.split()) <= 80:
problems.append(f"summary has {len(summary.split())} words")
invented = amounts(summary) - amounts(filing["text"])
if invented:
problems.append("dollar amounts not in the filing: " + ", ".join(f"${a:,.2f}" for a in sorted(invented)))
invented = percents(summary) - percents(filing["text"])
if invented:
problems.append("percentages not in the filing: " + ", ".join(f"{p:g}%" for p in sorted(invented)))
status = "flagged" if problems else "ok"
results.append({
"ticker": filing["ticker"], "company": filing["company"], "filing_date": filing["filingDate"],
"accession": filing["accessionNumber"], "url": filing["url"],
"items": [{"item": i, "name": ITEM_NAMES.get(i, "Unknown item")} for i in filing["items"].split(",") if i],
"status": status, "problems": problems,
"summary": answer.get("summary") if answer else None,
# an invalid sentiment is never passed on as if it were valid
"sentiment": answer.get("sentiment") if status == "ok" else None,
})
# Markers move for every processed filing, including flagged and unavailable ones (see description).
cik = str(filing["cik"])
markers[cik] = max(markers.get(cik, ""), filing["acceptanceDateTime"])
lines = [f"# New 8-K filings ({len(results)})", ""]
for r in results:
items = "; ".join(f"{i['item']} {i['name']}" for i in r["items"])
lines += [f"## {r['ticker']}: {r['company']}, filed {r['filing_date']}", "", f"- Items (from EDGAR): {items}"]
if r["status"] == "ok":
lines += [f"- Sentiment: {r['sentiment']}", f"- Summary: {r['summary']}"]
elif r["status"] == "flagged":
lines += [f"- FLAGGED, not verified: {'; '.join(r['problems'])}", f"- Unverified summary: {r['summary']}"]
else:
lines += ["- Summary unavailable: the model call failed or timed out."]
lines += [f"- Filing: {r['url']}", ""]
open("report.md", "w").write("\n".join(lines))
json.dump(results, open("results.json", "w"), indent=2)
counts = {s: sum(r["status"] == s for r in results) for s in ("ok", "flagged", "summary_unavailable")}
print(f"{counts['ok']} ok, {counts['flagged']} flagged, {counts['summary_unavailable']} without a summary")
print("::" + json.dumps({"outputs": {"markers": markers, **counts}}) + "::")
# Markers advance past every processed filing, including those whose call timed out. At temperature 0
# a filing that makes the model run away tends to do it again, so retrying it every 30 minutes would
# never succeed; the cost is that a summary lost to a timeout is not recovered automatically (edit or
# delete this KV pair to reprocess). An outage is different: if every call failed and Ollama is
# unreachable or the model is not pulled, check_and_report fails before this task, and the filings
# are retried on the next run.
- id: save_markers
type: io.kestra.plugin.core.kv.Set
description: Remember the newest processed filing per company, so the next run
only picks up newer ones.
runIf: "{{ outputs.fetch_new_filings.vars.count > 0 }}"
key: "{{ flow.id }}_markers"
kvType: JSON
value: "{{ outputs.check_and_report.vars.markers | toJson }}"
- id: show_report
type: io.kestra.plugin.core.log.Log
runIf: "{{ outputs.fetch_new_filings.vars.count > 0 }}"
level: "{{ outputs.check_and_report.vars.flagged +
outputs.check_and_report.vars.summary_unavailable > 0 ? 'WARN' : 'INFO'
}}"
message: "{{ read(outputs.check_and_report.outputFiles['report.md']) }}"
outputs:
# Not required: a run with no new filings, or one that stops early, has no report.
- id: new_filings
type: INT
required: false
value: "{{ outputs.fetch_new_filings.vars.count }}"
- id: flagged
type: INT
required: false
value: "{{ outputs.check_and_report.vars.flagged +
outputs.check_and_report.vars.summary_unavailable }}"
- id: report
type: FILE
required: false
description: Markdown report, one section per filing.
value: "{{ outputs.check_and_report.outputFiles['report.md'] }}"
- id: results
type: FILE
required: false
description: The same results as JSON, for a downstream flow.
value: "{{ outputs.check_and_report.outputFiles['results.json'] }}"
triggers:
- id: every_30_minutes
type: io.kestra.plugin.core.trigger.Schedule
description: EDGAR accepts 8-Ks on business days between 6:00 and 22:00 New York
time. Enable after setting SEC_EDGAR_USER_AGENT.
cron: "*/30 6-22 * * 1-5"
timezone: America/New_York
# Missed runs need no catch-up: the markers make the next run pick up everything filed meanwhile.
recoverMissedSchedules: NONE
disabled: true