How to Summarise Financial Reports with Semantic Kernel

Summarise financial reports inside a Semantic Kernel agent with EnConvert Distill, which returns schema-defined fields for up to 50 report URLs in one call

Get API key

A developer building a Semantic Kernel agent that analyses financial reports needs structured content from those documents before the agent can reason over revenue figures, segment results, or forward guidance. Financial reports served as PDFs or investor relations pages mix financial tables, footnotes, legal disclaimers, and formatted exhibit sections alongside the content, and fetching them directly returns dense layout markup with no clean extraction path. EnConvert Distill accepts a financial report URL that opens without signing in, applies a schema the plugin defines, and returns structured fields in one synchronous call. The agent gets schema-defined report content ready for downstream analysis with no format-specific parser.

Example

python
import asyncio
import os
from typing import Annotated

import requests
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import (
    OpenAIChatCompletion,
    OpenAIChatPromptExecutionSettings,
)
from semantic_kernel.contents import ChatHistory
from semantic_kernel.functions import kernel_function

# OpenAIChatCompletion reads OPENAI_API_KEY from the environment

BASE_URL = "https://api.enconvert.com/v2"
headers = {
    "X-API-Key": os.environ["ENCONVERT_API_KEY"],
    "Content-Type": "application/json",
}

# The fields the plugin returns. The response keys match these names exactly.
# Each description tells the extractor to copy figures as written and to leave a field
# empty rather than guess or calculate.
REPORT_SCHEMA = {
    "title": "The title of the report or filing",
    "company": "The name of the company that issued the report",
    "reporting_period": "The period the report covers, as written, such as fiscal year ended 28 September 2024",
    "revenue_summary": (
        "A two sentence summary of revenue as the report states it. Copy every figure exactly as "
        "written, with its currency, unit, and period. Never calculate or estimate a figure. "
        "Return an empty string if the report text is not on the page."
    ),
    "key_findings": (
        "The main results or conclusions the report states, as a list, with any figure copied "
        "exactly as written. Return an empty list if the report text is not on the page."
    ),
    "outlook": (
        "The forward looking statements or guidance the report states, as written. "
        "Return an empty string if none are stated."
    ),
}

def as_text(value) -> str:
    if isinstance(value, list):
        return "; ".join(str(item) for item in value) or "not stated"
    return str(value) if value else "not stated"

class FinancialReportPlugin:
    @kernel_function(
        name="summarise_financial_reports",
        description=(
            "Reads publicly accessible financial report pages and returns structured fields for "
            "each: title, company, reporting period, revenue summary, key findings, and outlook."
        ),
    )
    def summarise_financial_reports(
        self, urls: Annotated[list[str], "Report URLs to read, at most 50"]
    ) -> Annotated[str, "Structured fields for each report"]:
        if len(urls) > 50:
            return "Too many URLs. Distill accepts at most 50 per call."

        # One synchronous call: no job_id, no polling, no download step
        response = requests.post(
            f"{BASE_URL}/distill",
            headers=headers,
            json={"urls": urls, "schema": REPORT_SCHEMA},
            timeout=300,
        )

        # Distill runs on paid plans only, and the free tier returns 402
        if response.status_code == 402:
            return "Distill requires a paid plan."
        response.raise_for_status()

        reports = []
        for result in response.json()["results"]:
            if result["status"] != "completed":
                reports.append(f"Source: {result['url']}\nCould not be read ({result['status']}).")
                continue

            # A low render_quality can mean a paywall or an inaccessible page
            render_quality = result.get("render_quality", 1.0)
            if render_quality < 0.5:
                reports.append(
                    f"Source: {result['url']}\nLow render quality ({render_quality}), "
                    "likely a paywall or blocked page. Skipped."
                )
                continue

            data = result["data"]  # keys match REPORT_SCHEMA exactly

            # No company and no revenue text means the report itself was not read
            if not data.get("company") and not data.get("revenue_summary"):
                reports.append(f"Source: {result['url']}\nNo report text was found on the page.")
                continue

            reports.append(
                f"Source: {result['url']}\n"
                f"Title: {as_text(data['title'])}\n"
                f"Company: {as_text(data['company'])}\n"
                f"Period: {as_text(data['reporting_period'])}\n"
                f"Revenue: {as_text(data['revenue_summary'])}\n"
                f"Key findings: {as_text(data['key_findings'])}\n"
                f"Outlook: {as_text(data['outlook'])}"
            )
        return "\n\n---\n\n".join(reports)

async def main():
    kernel = Kernel()
    chat = OpenAIChatCompletion(ai_model_id="gpt-4.1")
    kernel.add_service(chat)
    kernel.add_plugin(FinancialReportPlugin(), plugin_name="financial_reports")

    # Auto function calling lets the model decide when to call the plugin
    settings = OpenAIChatPromptExecutionSettings(
        function_choice_behavior=FunctionChoiceBehavior.Auto()
    )

    history = ChatHistory()
    history.add_system_message(
        "You analyse financial reports. Use summarise_financial_reports to read the reports you "
        "need, quote figures exactly as the tool returns them, never calculate or fill a gap, and "
        "cite the report URL for every statement. This is a first pass, and a person must check "
        "every figure against the source before relying on it."
    )
    history.add_user_message(
        "Read https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm "
        "and https://www.sec.gov/Archives/edgar/data/789019/000095017024087843/msft-20240630.htm, "
        "then summarise revenue and the outlook for each, with the reporting period."
    )

    answer = await chat.get_chat_message_content(
        chat_history=history, settings=settings, kernel=kernel
    )
    print(answer)

asyncio.run(main())

What you get back

Distill returns schema-defined fields inline as structured JSON in the data object, with no polling and no job_id. The render_quality score lets the plugin detect a paywalled or blocked page before the agent reasons over incomplete content. Extracting structured data from a financial report PDF requires a PDF parser and format-specific post-processing to separate figures from footnotes, and SEC EDGAR's XBRL data covers only tagged fields rather than narrative sections, while Distill returns both from a report URL in a single call.

Get free API key — 500 ops per month, no card required. Note: Distill runs on paid plans. Free tier returns 402.