Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.
feat: add FinancialDataTemporalGraph templates
yuxizhed6881a521f3b
diff --git a/hyperextract/templates/README.md b/hyperextract/templates/README.mdindex eed1db1..89c6e70 100644--- a/hyperextract/templates/README.md+++ b/hyperextract/templates/README.md@@ -72,6 +72,7 @@ Optimized for complex financial relationships, market sentiment, and temporal ev| **`FilingRiskFactorSet`** | `AutoSet` | **Risk Factor Registry**. Deduplicates and catalogs all risk factors disclosed across Item 1A, tracking additions and removals between filing periods. | Risk evolution monitoring, cross-company risk comparison || **`MaterialEventTimeline`** | `AutoTemporalGraph` | **8-K Event Timeline**. Chronologically extracts material events (executive changes, M&A announcements, restatements) from current reports. | Event-driven analysis, regulatory monitoring || **`SegmentPerformanceList`** | `AutoList` | **Segment Breakdown**. Extracts revenue, operating income, and key metrics by business segment or geographic region. | Segment-level valuation, geographic exposure analysis |+| **`FinancialDataTemporalGraph`** | `AutoTemporalGraph` | **Financial Data Timeline**. Builds a temporal graph of financial metrics across reporting periods, tracking how revenue, margins, segment contributions, and key ratios evolve over time. | Multi-period trend analysis, cross-period comparison, financial data lineage |* **Equity Research Reports**: Detailed analysis by analysts containing ratings, target prices, and investment logic.diff --git a/hyperextract/templates/README_ZH.md b/hyperextract/templates/README_ZH.mdindex f0179fb..3c5843f 100644--- a/hyperextract/templates/README_ZH.md+++ b/hyperextract/templates/README_ZH.md@@ -72,6 +72,7 @@| **`FilingRiskFactorSet`** | `AutoSet` | **风险因素登记册**。去重汇总 Item 1A 中披露的所有风险因素,跟踪各报告期的新增与删除变化。 | 风险演变监控、跨公司风险对标 || **`MaterialEventTimeline`** | `AutoTemporalGraph` | **重大事件时间轴**。按时间顺序提取 8-K 当期报告中的重大事件(高管变动、并购公告、财务重述等)。 | 事件驱动分析、合规监控 || **`SegmentPerformanceList`** | `AutoList` | **分部业绩明细**。按业务分部或地理区域提取营收、经营利润等关键指标。 | 分部估值、区域风险敞口分析 |+| **`FinancialDataTemporalGraph`** | `AutoTemporalGraph` | **财务数据时序图谱**。构建跨报告期的财务指标时序图谱,追踪营收、利润率、分部贡献及关键比率随时间的演变。 | 多期趋势分析、跨期对比、财务数据溯源 |* **股票研究报告 (Equity Research)**:分析师撰写的深度报告,包含评级、目标价及投资逻辑相关内容。diff --git a/hyperextract/templates/en/finance/__init__.py b/hyperextract/templates/en/finance/__init__.pyindex 8292945..fc3169e 100644--- a/hyperextract/templates/en/finance/__init__.py+++ b/hyperextract/templates/en/finance/__init__.py@@ -16,6 +16,7 @@ from .mda_narrative_graph import MDANarrativeGraphfrom .filing_risk_factor_set import FilingRiskFactorSetfrom .material_event_timeline import MaterialEventTimelinefrom .segment_performance_list import SegmentPerformanceList+from .financial_data_temporal_graph import FinancialDataTemporalGraph# Equity Research Reportsfrom .research_note_summary import ResearchNoteSummary@@ -52,6 +53,7 @@ __all__ = ["FilingRiskFactorSet","MaterialEventTimeline","SegmentPerformanceList",+ "FinancialDataTemporalGraph",# Equity Research"ResearchNoteSummary","FinancialForecast",diff --git a/hyperextract/templates/en/finance/financial_data_temporal_graph.py b/hyperextract/templates/en/finance/financial_data_temporal_graph.pynew file mode 100644index 0000000..aaf3408--- /dev/null+++ b/hyperextract/templates/en/finance/financial_data_temporal_graph.py@@ -0,0 +1,240 @@+"""Financial Data Temporal Graph - Tracks financial metrics across reporting periods.++Extracts financial entities (companies, segments, accounts) and their quantitative+relationships over time from SEC filings, enabling multi-period trend analysis,+segment-level tracking, and cross-period financial comparison.+"""++from typing import Optional, Any+from pydantic import BaseModel, Field+from langchain_core.language_models.chat_models import BaseChatModel+from langchain_core.embeddings import Embeddings+from hyperextract.types import AutoTemporalGraph++# ==============================================================================+# 1. Schema Definitions+# ==============================================================================+++class FinancialDataEntity(BaseModel):+ """+ A financial entity appearing in SEC filings: a company, business segment,+ or financial metric / line item.+ """++ name: str = Field(+ description="Canonical name of the entity (e.g., 'Apple Inc.', 'Cloud Services', 'Total Revenue', 'Net Income')."+ )+ entity_type: str = Field(+ description="Type: 'Company', 'Segment', 'FinancialMetric', 'AccountItem', 'ExternalFactor'."+ )+ description: Optional[str] = Field(+ None,+ description="Brief context (e.g., 'Consumer electronics segment', 'GAAP revenue recognition').",+ )+++class FinancialDataEdge(BaseModel):+ """+ A temporal financial relationship linking an entity to a metric or linking+ metrics to each other, always anchored to a specific reporting period.+ """++ source: str = Field(+ description="The reporting entity or contributing factor (e.g., 'Apple Inc.', 'Services Segment')."+ )+ target: str = Field(+ description="The financial metric or account item (e.g., 'Revenue', 'Operating Income')."+ )+ relationship: str = Field(+ description="Type: 'Reported', 'Contributed', 'Derived', 'YoY Change', 'Ratio', 'Impacted By'."+ )+ value: Optional[str] = Field(+ None,+ description="Reported amount or percentage (e.g., '$394.3 billion', '+7.8%', '45.6%').",+ )+ unit: Optional[str] = Field(+ None,+ description="Unit or currency if distinguishable (e.g., 'USD millions', 'percentage').",+ )+ fiscal_period: Optional[str] = Field(+ None,+ description="Fiscal period label (e.g., 'FY2024', 'Q3 2024', 'Year ended Dec 31, 2024').",+ )+ start_timestamp: Optional[str] = Field(+ None,+ description="Start date of the reporting period (e.g., '2024-01-01', 'January 1, 2024').",+ )+ end_timestamp: Optional[str] = Field(+ None,+ description="End date of the reporting period (e.g., '2024-12-31', 'December 31, 2024').",+ )+ description: Optional[str] = Field(+ None,+ description="Additional context such as comparison notes, restatement flags, or accounting treatment.",+ )+++# ==============================================================================+# 2. Prompts+# ==============================================================================++_PROMPT = (+ "You are a senior financial analyst specializing in multi-period SEC filing analysis. "+ "Extract financial entities and their quantitative relationships over time from the text.\n\n"+ "Rules:\n"+ "- Identify companies, business segments, and financial metrics/account items as entities.\n"+ "- For each reported figure, create an edge linking the reporting entity to the metric "+ "with the exact value and fiscal period.\n"+ "- Capture year-over-year changes, derived ratios, and segment contributions as separate edges.\n"+ "- Preserve exact dollar amounts and units as stated in the source.\n"+ "- Assign fiscal_period labels consistently (e.g., 'FY2024', 'Q3 2024').\n"+ "- Extract comparative data across multiple periods when available.\n"+ "- DO NOT compute values not explicitly stated in the text."+)++_NODE_PROMPT = (+ "You are a senior financial analyst. Extract all financial entities (Nodes) from the text.\n\n"+ "Extraction Rules:\n"+ "- Identify the filing company and any subsidiaries or related entities.\n"+ "- Identify business segments or geographic regions mentioned.\n"+ "- Identify financial metrics and account items (Revenue, Net Income, EPS, Total Assets, etc.).\n"+ "- Identify external factors explicitly mentioned as influencing financials (e.g., 'FX headwinds', 'Tariff impact').\n"+ "- Classify each entity by type: Company, Segment, FinancialMetric, AccountItem, ExternalFactor.\n"+ "- DO NOT extract dates, time periods, or numeric values as entities."+)++_EDGE_PROMPT = (+ "You are a senior financial analyst. Given the entities, extract all financial data relationships (Edges) "+ "with their temporal context.\n\n"+ "Extraction Rules:\n"+ "- For each reported figure, connect the reporting entity/segment to the relevant financial metric.\n"+ "- Include the exact value, unit, and fiscal period for every edge.\n"+ "- Extract year-over-year changes as separate edges (e.g., source='Revenue', target='Revenue Growth', "+ "relationship='YoY Change', value='+7.8%').\n"+ "- Extract segment contributions (e.g., source='Services', target='Revenue', "+ "relationship='Contributed', value='$85.2B').\n"+ "- Extract derived ratios explicitly stated (e.g., source='Gross Profit', target='Gross Margin', "+ "relationship='Ratio', value='45.6%').\n"+ "- Assign start_timestamp and end_timestamp based on the fiscal period boundaries.\n"+ "- Only create edges between nodes that exist in the provided entity list."+)++# ==============================================================================+# 3. Template Class+# ==============================================================================+++class FinancialDataTemporalGraph(+ AutoTemporalGraph[FinancialDataEntity, FinancialDataEdge]+):+ """+ Applicable to: SEC 10-K Annual Reports, 10-Q Quarterly Reports, 20-F Foreign Filings,+ Annual Reports with multi-period financial statements, Segment disclosures.++ Template for building a temporal knowledge graph of financial data from SEC filings.+ Unlike FilingFinancialSnapshot (a flat single-period extraction), this template+ preserves the **time dimension** — tracking how revenue, margins, segment contributions,+ and other metrics evolve across reporting periods. It models companies, segments,+ and financial metrics as nodes, and connects them through temporally-anchored edges+ carrying exact values and fiscal period labels.++ Example Usage:+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings+ >>> llm = ChatOpenAI(model="gpt-4o")+ >>> embedder = OpenAIEmbeddings()+ >>> graph = FinancialDataTemporalGraph(llm_client=llm, embedder=embedder)+ >>> filing = "For FY2024, Apple reported revenue of $394.3B, up 7.8% from $365.8B in FY2023..."+ >>> graph.feed_text(filing)+ >>> graph.show()+ """++ def __init__(+ self,+ llm_client: BaseChatModel,+ embedder: Embeddings,+ *,+ observation_time: str = "2024-01-01",+ extraction_mode: str = "two_stage",+ chunk_size: int = 2048,+ chunk_overlap: int = 256,+ max_workers: int = 10,+ verbose: bool = False,+ **kwargs: Any,+ ):+ """+ Initialize the Financial Data Temporal Graph template.++ Args:+ llm_client (BaseChatModel): The LLM for financial data extraction.+ embedder (Embeddings): Embedding model for deduplication and search.+ observation_time (str): Reference date for resolving relative time expressions.+ extraction_mode (str): "one_stage" or "two_stage" (default: "two_stage").+ chunk_size (int): Max characters per text chunk.+ chunk_overlap (int): Overlap between consecutive chunks.+ max_workers (int): Parallel processing workers.+ verbose (bool): Enable progress logging.+ **kwargs: Additional arguments for AutoTemporalGraph.+ """+ super().__init__(+ node_schema=FinancialDataEntity,+ edge_schema=FinancialDataEdge,+ node_key_extractor=lambda x: x.name.strip().lower(),+ edge_key_extractor=lambda x: (+ f"{x.source.strip().lower()}|{x.relationship.lower()}|{x.target.strip().lower()}"+ ),+ time_in_edge_extractor=lambda x: x.fiscal_period or x.start_timestamp or "",+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),+ llm_client=llm_client,+ embedder=embedder,+ observation_time=observation_time,+ extraction_mode=extraction_mode,+ prompt=_PROMPT,+ prompt_for_node_extraction=_NODE_PROMPT,+ prompt_for_edge_extraction=_EDGE_PROMPT,+ chunk_size=chunk_size,+ chunk_overlap=chunk_overlap,+ max_workers=max_workers,+ verbose=verbose,+ **kwargs,+ )++ def show(+ self,+ *,+ top_k_nodes_for_search: int = 3,+ top_k_edges_for_search: int = 3,+ top_k_nodes_for_chat: int = 3,+ top_k_edges_for_chat: int = 3,+ ) -> None:+ """+ Visualize the financial data temporal graph using OntoSight.++ Args:+ top_k_nodes_for_search (int): Number of entities to retrieve. Default 3.+ top_k_edges_for_search (int): Number of data edges to retrieve. Default 3.+ top_k_nodes_for_chat (int): Entities for chat context. Default 3.+ top_k_edges_for_chat (int): Data edges for chat context. Default 3.+ """++ def node_label_extractor(node: FinancialDataEntity) -> str:+ return f"{node.name} ({node.entity_type})"++ def edge_label_extractor(edge: FinancialDataEdge) -> str:+ parts = [edge.relationship]+ if edge.value:+ parts.append(edge.value)+ if edge.fiscal_period:+ parts.append(f"[{edge.fiscal_period}]")+ elif edge.start_timestamp:+ parts.append(f"[{edge.start_timestamp}]")+ return " ".join(parts)++ super().show(+ node_label_extractor=node_label_extractor,+ edge_label_extractor=edge_label_extractor,+ top_k_nodes_for_search=top_k_nodes_for_search,+ top_k_edges_for_search=top_k_edges_for_search,+ top_k_nodes_for_chat=top_k_nodes_for_chat,+ top_k_edges_for_chat=top_k_edges_for_chat,+ )diff --git a/hyperextract/templates/zh/finance/__init__.py b/hyperextract/templates/zh/finance/__init__.pyindex e5a5359..a6c7795 100644--- a/hyperextract/templates/zh/finance/__init__.py+++ b/hyperextract/templates/zh/finance/__init__.py@@ -16,6 +16,7 @@ from .mda_narrative_graph import MDANarrativeGraphfrom .filing_risk_factor_set import FilingRiskFactorSetfrom .material_event_timeline import MaterialEventTimelinefrom .segment_performance_list import SegmentPerformanceList+from .financial_data_temporal_graph import FinancialDataTemporalGraph# 股票研究报告from .research_note_summary import ResearchNoteSummary@@ -52,6 +53,7 @@ __all__ = ["FilingRiskFactorSet","MaterialEventTimeline","SegmentPerformanceList",+ "FinancialDataTemporalGraph",# 股票研究报告"ResearchNoteSummary","FinancialForecast",diff --git a/hyperextract/templates/zh/finance/financial_data_temporal_graph.py b/hyperextract/templates/zh/finance/financial_data_temporal_graph.pynew file mode 100644index 0000000..8084bad--- /dev/null+++ b/hyperextract/templates/zh/finance/financial_data_temporal_graph.py@@ -0,0 +1,233 @@+"""财务数据时序图谱 - 跨报告期追踪财务指标变化。++从 SEC 申报文件中提取财务实体(公司、分部、科目)及其跨期的+量化关系,支持多期趋势分析、分部级追踪和跨期财务对比。+"""++from typing import Optional, Any+from pydantic import BaseModel, Field+from langchain_core.language_models.chat_models import BaseChatModel+from langchain_core.embeddings import Embeddings+from hyperextract.types import AutoTemporalGraph++# ==============================================================================+# 1. Schema 定义+# ==============================================================================+++class FinancialDataEntity(BaseModel):+ """+ SEC 申报文件中出现的财务实体:公司、业务分部或财务指标/科目。+ """++ name: str = Field(+ description="实体的规范名称(例如 '苹果公司'、'云服务分部'、'营业收入'、'净利润')。"+ )+ entity_type: str = Field(+ description="类型:'公司'、'分部'、'财务指标'、'会计科目'、'外部因素'。"+ )+ description: Optional[str] = Field(+ None,+ description="简要背景说明(例如 '消费电子业务板块'、'GAAP 收入确认口径')。",+ )+++class FinancialDataEdge(BaseModel):+ """+ 锚定于特定报告期的时序财务关系,将实体与指标、指标与指标关联起来。+ """++ source: str = Field(+ description="报告主体或贡献因素(例如 '苹果公司'、'服务分部')。"+ )+ target: str = Field(+ description="财务指标或会计科目(例如 '营业收入'、'经营利润')。"+ )+ relationship: str = Field(+ description="关系类型:'报告'、'贡献'、'衍生'、'同比变化'、'比率'、'受影响于'。"+ )+ value: Optional[str] = Field(+ None,+ description="报告金额或百分比(例如 '3943亿美元'、'+7.8%'、'45.6%')。",+ )+ unit: Optional[str] = Field(+ None,+ description="金额单位或币种(例如 '百万美元'、'百分比')。",+ )+ fiscal_period: Optional[str] = Field(+ None,+ description="财务期间标签(例如 'FY2024'、'Q3 2024'、'截至2024年12月31日的年度')。",+ )+ start_timestamp: Optional[str] = Field(+ None,+ description="报告期开始日期(例如 '2024-01-01'、'2024年1月1日')。",+ )+ end_timestamp: Optional[str] = Field(+ None,+ description="报告期结束日期(例如 '2024-12-31'、'2024年12月31日')。",+ )+ description: Optional[str] = Field(+ None,+ description="补充说明,如对比备注、重述标记或会计处理方式等。",+ )+++# ==============================================================================+# 2. 提示词 (Prompts)+# ==============================================================================++_PROMPT = (+ "你是一位资深财务分析师,擅长多期 SEC 申报文件分析。"+ "从文本中提取财务实体及其跨时间的量化关系。\n\n"+ "规则:\n"+ "- 将公司、业务分部和财务指标/会计科目识别为实体。\n"+ "- 对每个报告数据,创建连接报告主体与指标的边,附带精确数值和财务期间。\n"+ "- 将同比变化、衍生比率和分部贡献分别作为独立的边提取。\n"+ "- 保留源文本中的精确金额和单位。\n"+ "- 统一使用一致的财务期间标签(例如 'FY2024'、'Q3 2024')。\n"+ "- 在可获取时提取多期对比数据。\n"+ "- 不要计算文本中未明确给出的数值。"+)++_NODE_PROMPT = (+ "你是一位资深财务分析师。从文本中提取所有财务实体(节点)。\n\n"+ "提取规则:\n"+ "- 识别申报公司及其子公司或关联方。\n"+ "- 识别文中提到的业务分部或地理区域。\n"+ "- 识别财务指标和会计科目(营业收入、净利润、每股收益、总资产等)。\n"+ "- 识别文中明确提及的影响财务的外部因素(例如 '汇率逆风'、'关税影响')。\n"+ "- 按类型分类:公司、分部、财务指标、会计科目、外部因素。\n"+ "- 不要将日期、时间期间或纯数值提取为实体。"+)++_EDGE_PROMPT = (+ "你是一位资深财务分析师。在获得实体清单的基础上,提取所有带时间上下文的财务数据关系(边)。\n\n"+ "提取规则:\n"+ "- 对每个报告数据,连接报告主体/分部与相应的财务指标。\n"+ "- 每条边必须包含精确数值、单位和财务期间。\n"+ "- 将同比变化单独提取为边(例如 source='营业收入', target='收入增长率', "+ "relationship='同比变化', value='+7.8%')。\n"+ "- 提取分部贡献(例如 source='服务分部', target='营业收入', "+ "relationship='贡献', value='852亿美元')。\n"+ "- 提取文中明确列出的衍生比率(例如 source='毛利润', target='毛利率', "+ "relationship='比率', value='45.6%')。\n"+ "- 根据财务期间的起止边界赋值 start_timestamp 和 end_timestamp。\n"+ "- 仅在提供的实体列表中存在的节点之间创建边。"+)++# ==============================================================================+# 3. 模板类+# ==============================================================================+++class FinancialDataTemporalGraph(+ AutoTemporalGraph[FinancialDataEntity, FinancialDataEdge]+):+ """+ 适用文档: SEC 10-K 年度报告、10-Q 季度报告、20-F 外国发行人年报、+ 包含多期财务报表的年度报告、分部披露。++ 模板用于从 SEC 申报文件构建财务数据时序知识图谱。+ 与 FilingFinancialSnapshot(单期扁平提取)不同,本模板保留了**时间维度**——+ 将公司、业务分部和财务指标建模为节点,通过带有精确数值和财务期间标签的+ 时序边进行连接,支持多期趋势分析和跨期对比。++ 使用示例:+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings+ >>> llm = ChatOpenAI(model="gpt-4o")+ >>> embedder = OpenAIEmbeddings()+ >>> graph = FinancialDataTemporalGraph(llm_client=llm, embedder=embedder)+ >>> filing = "FY2024年度,苹果公司报告营收3943亿美元,较FY2023年的3658亿美元增长7.8%..."+ >>> graph.feed_text(filing)+ >>> graph.show()+ """++ def __init__(+ self,+ llm_client: BaseChatModel,+ embedder: Embeddings,+ *,+ observation_time: str = "2024-01-01",+ extraction_mode: str = "two_stage",+ chunk_size: int = 2048,+ chunk_overlap: int = 256,+ max_workers: int = 10,+ verbose: bool = False,+ **kwargs: Any,+ ):+ """+ 初始化财务数据时序图谱模板。++ Args:+ llm_client (BaseChatModel): 用于财务数据提取的 LLM。+ embedder (Embeddings): 用于去重和语义检索的嵌入模型。+ observation_time (str): 用于解析相对时间表达式的参考日期。+ extraction_mode (str): "one_stage" 或 "two_stage"(默认 "two_stage")。+ chunk_size (int): 每个文本分块的最大字符数。+ chunk_overlap (int): 相邻分块之间的重叠字符数。+ max_workers (int): 并行处理工作线程数。+ verbose (bool): 是否启用进度日志。+ **kwargs: AutoTemporalGraph 的其他参数。+ """+ super().__init__(+ node_schema=FinancialDataEntity,+ edge_schema=FinancialDataEdge,+ node_key_extractor=lambda x: x.name.strip().lower(),+ edge_key_extractor=lambda x: (+ f"{x.source.strip().lower()}|{x.relationship.lower()}|{x.target.strip().lower()}"+ ),+ time_in_edge_extractor=lambda x: x.fiscal_period or x.start_timestamp or "",+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),+ llm_client=llm_client,+ embedder=embedder,+ observation_time=observation_time,+ extraction_mode=extraction_mode,+ prompt=_PROMPT,+ prompt_for_node_extraction=_NODE_PROMPT,+ prompt_for_edge_extraction=_EDGE_PROMPT,+ chunk_size=chunk_size,+ chunk_overlap=chunk_overlap,+ max_workers=max_workers,+ verbose=verbose,+ **kwargs,+ )++ def show(+ self,+ *,+ top_k_nodes_for_search: int = 3,+ top_k_edges_for_search: int = 3,+ top_k_nodes_for_chat: int = 3,+ top_k_edges_for_chat: int = 3,+ ) -> None:+ """+ 使用 OntoSight 可视化财务数据时序图谱。++ Args:+ top_k_nodes_for_search (int): 检索的实体数。默认 3。+ top_k_edges_for_search (int): 检索的数据边数。默认 3。+ top_k_nodes_for_chat (int): 对话上下文中的实体数。默认 3。+ top_k_edges_for_chat (int): 对话上下文中的数据边数。默认 3。+ """++ def node_label_extractor(node: FinancialDataEntity) -> str:+ return f"{node.name} ({node.entity_type})"++ def edge_label_extractor(edge: FinancialDataEdge) -> str:+ parts = [edge.relationship]+ if edge.value:+ parts.append(edge.value)+ if edge.fiscal_period:+ parts.append(f"[{edge.fiscal_period}]")+ elif edge.start_timestamp:+ parts.append(f"[{edge.start_timestamp}]")+ return " ".join(parts)++ super().show(+ node_label_extractor=node_label_extractor,+ edge_label_extractor=edge_label_extractor,+ top_k_nodes_for_search=top_k_nodes_for_search,+ top_k_edges_for_search=top_k_edges_for_search,+ top_k_nodes_for_chat=top_k_nodes_for_chat,+ top_k_edges_for_chat=top_k_edges_for_chat,+ )