Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

feat: add Financial News & Market Commentary templates - MarketSentimentModel (AutoModel) - sentiment snapshot - FinancialEventCausalGraph (AutoGraph) - event impact chains - MultiSourceSentimentHypergraph (AutoHypergraph) - cross-source fusion - MarketNarrativeTimeline (AutoTemporalGraph) - narrative evolution

yuxizhe29b460c608ae
diff --git a/hyperextract/templates/README.md b/hyperextract/templates/README.md
index b1894e4..eed1db1 100644
--- a/hyperextract/templates/README.md
+++ b/hyperextract/templates/README.md
@@ -63,7 +63,7 @@ The default choice for unstructured text that doesn't fit a specific industry.
### 2. `finance` (Finance)
Optimized for complex financial relationships, market sentiment, and temporal events.
-* **SEC Filings (10-K / 10-Q / 8-K)**: Standardized regulatory filings containing financial statements, management discussion, risk factors, and material event disclosures with complex document structures (tables, narratives, exhibits). *(Ref: [Financial Report Chunking for RAG, Yepes et al. 2024](https://arxiv.org/abs/2402.05131))*
+* **SEC Filings (10-K / 10-Q / 8-K)**: Standardized regulatory filings containing financial statements, management discussion, risk factors, and material event disclosures with complex document structures (tables, narratives, exhibits).
| Template Name | Primitive | Description | Typical Use Case |
| :--- | :--- | :--- | :--- |
@@ -91,7 +91,7 @@ Optimized for complex financial relationships, market sentiment, and temporal ev
| **`ProceedsUsage`** | `AutoList` | **Fund Usage**. Details project names, allocated amounts, and estimated timelines for proceeds. | Post-IPO monitoring |
| **`CompanyHistoryTimeline`** | `AutoTemporalGraph` | **Corporate Milestones**. Chronological extraction of founding, funding rounds, and major pivots. | Due diligence, history mapping |
-* **Earnings Call Transcripts**: Quarterly conference calls where management presents financial results and answers analyst questions, containing forward-looking guidance and sentiment signals. *(Ref: [HybridRAG, Sarmah et al. 2024](https://arxiv.org/abs/2408.04948))*
+* **Earnings Call Transcripts**: Quarterly conference calls where management presents financial results and answers analyst questions, containing forward-looking guidance and sentiment signals.
| Template Name | Primitive | Description | Typical Use Case |
| :--- | :--- | :--- | :--- |
@@ -100,7 +100,7 @@ Optimized for complex financial relationships, market sentiment, and temporal ev
| **`AnalystQAGraph`** | `AutoGraph` | **Q&A Interaction Map**. Maps analyst questions to management responses, capturing concerns raised and commitments made. | Analyst focus analysis, commitment tracking |
| **`CallSentimentHypergraph`** | `AutoHypergraph` | **Topic-Sentiment Analysis**. Models multi-dimensional sentiment: `{Topic (Revenue/Margin/Guidance), Speaker, Sentiment, Driving Factor}` across the call. | Sentiment-driven trading signals, tone shift detection |
-* **Financial News & Market Commentary**: News articles, analyst commentaries, and social media posts conveying market sentiment, event impact, and forward-looking opinions about financial instruments or markets. *(Ref: [Survey of LLMs for Financial Applications, Nie et al. 2024](https://arxiv.org/abs/2406.11903))*
+* **Financial News & Market Commentary**: News articles, analyst commentaries, and social media posts conveying market sentiment, event impact, and forward-looking opinions about financial instruments or markets.
| Template Name | Primitive | Description | Typical Use Case |
| :--- | :--- | :--- | :--- |
diff --git a/hyperextract/templates/README_ZH.md b/hyperextract/templates/README_ZH.md
index 0084a56..f0179fb 100644
--- a/hyperextract/templates/README_ZH.md
+++ b/hyperextract/templates/README_ZH.md
@@ -91,7 +91,7 @@
| **`ProceedsUsage`** | `AutoList` | **募资投向**。详细提取募投项目的名称、计划金额分配及预计时间表。 | 投后管理、资金使用合规 |
| **`CompanyHistoryTimeline`** | `AutoTemporalGraph` | **公司大事记**。按时间轴提取公司成立以来的融资、并购、管理层变更等里程碑。 | 投研尽调、企业图鉴 |
-* **财报电话会议 (Earnings Call Transcripts)**:管理层按季度发布的业绩说明会实录,包含财务数据解读、前瞻性指引及分析师问答,蕴含丰富的情感信号与预期信息。 *(参考: [HybridRAG, Sarmah et al. 2024](https://arxiv.org/abs/2408.04948))*
+* **财报电话会议 (Earnings Call Transcripts)**:管理层按季度发布的业绩说明会实录,包含财务数据解读、前瞻性指引及分析师问答,蕴含丰富的情感信号与预期信息。
| 模板名称 | 底层原语 | 描述 | 典型应用场景 |
| :--- | :--- | :--- | :--- |
@@ -100,7 +100,7 @@
| **`AnalystQAGraph`** | `AutoGraph` | **问答互动图谱**。映射分析师提问与管理层回答的对应关系,捕捉被关注的焦点问题及管理层承诺。 | 分析师关注点分析、承诺追踪 |
| **`CallSentimentHypergraph`** | `AutoHypergraph` | **话题-情感分析超图**。建模多维情感信号:`{话题(营收/利润率/指引), 发言人, 情感倾向, 驱动因素}` 的复杂关联。 | 情感驱动交易信号、基调变化检测 |
-* **金融新闻与市场评论 (Financial News & Market Commentary)**:传递市场情绪、事件影响及前瞻性观点的新闻报道、分析师评论及社交媒体帖子。 *(参考: [Survey of LLMs for Financial Applications, Nie et al. 2024](https://arxiv.org/abs/2406.11903))*
+* **金融新闻与市场评论 (Financial News & Market Commentary)**:传递市场情绪、事件影响及前瞻性观点的新闻报道、分析师评论及社交媒体帖子。
| 模板名称 | 底层原语 | 描述 | 典型应用场景 |
| :--- | :--- | :--- | :--- |
diff --git a/hyperextract/templates/en/finance/financial_event_causal_graph.py b/hyperextract/templates/en/finance/financial_event_causal_graph.py
new file mode 100644
index 0000000..8d78bab
--- /dev/null
+++ b/hyperextract/templates/en/finance/financial_event_causal_graph.py
@@ -0,0 +1,198 @@
+"""Financial Event Causal Graph - Maps financial events to market reactions.
+
+Maps financial events to affected entities and downstream market reactions
+(e.g., "Fed rate hike -> Bank sector rally -> Bond yield rise") for event-driven strategy.
+"""
+
+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 AutoGraph
+
+# ==============================================================================
+# 1. Schema Definitions
+# ==============================================================================
+
+
+class FinancialEventNode(BaseModel):
+ """
+ A financial event, market entity, or reaction in an event chain.
+ """
+
+ name: str = Field(
+ description="Name of the event or entity (e.g., 'Fed Rate Hike', 'Bank Sector', 'USD Strengthening')."
+ )
+ node_type: str = Field(
+ description="Type: 'Event', 'Entity', 'Market Reaction', 'Policy', 'Economic Indicator', 'Sector'."
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Context or details about the event/entity.",
+ )
+
+
+class EventCausalEdge(BaseModel):
+ """
+ A causal link from a financial event to a market reaction.
+ """
+
+ source: str = Field(description="The cause event or entity name.")
+ target: str = Field(description="The effect or downstream reaction name.")
+ causal_mechanism: str = Field(
+ description="How the source causes the target effect "
+ "(e.g., 'higher rates reduce borrowing costs sensitivity')."
+ )
+ direction: str = Field(
+ description="Impact direction: 'Positive', 'Negative', 'Ambiguous'."
+ )
+ magnitude: Optional[str] = Field(
+ None,
+ description="Stated or implied magnitude (e.g., 'S&P 500 rose 2%', '50bps impact').",
+ )
+ timing: Optional[str] = Field(
+ None,
+ description="Timing of the reaction: 'Immediate', 'Same-day', 'Multi-day', 'Lagged'.",
+ )
+ confidence: Optional[str] = Field(
+ None,
+ description="Confidence in causal link: 'Established', 'Likely', 'Speculative'.",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a macro strategist and financial news analyst. Extract financial events, affected "
+ "market entities, and the causal chains connecting them from this news or commentary.\n\n"
+ "Rules:\n"
+ "- Identify triggering events (policy decisions, earnings, economic data releases).\n"
+ "- Identify affected entities (sectors, stocks, indices, commodities).\n"
+ "- Map the causal chains from events to market reactions.\n"
+ "- Capture the magnitude and timing of reactions.\n"
+ "- Note the confidence level in each causal link."
+)
+
+_NODE_PROMPT = (
+ "You are a macro strategist. Extract all financial events, entities, and market reactions (Nodes).\n\n"
+ "Extraction Rules:\n"
+ "- Identify triggering events and policy decisions.\n"
+ "- Identify market sectors, indices, and commodities.\n"
+ "- Identify market reactions and price movements.\n"
+ "- DO NOT establish causal relationships at this stage."
+)
+
+_EDGE_PROMPT = (
+ "You are a macro strategist. Given the events and entities, extract causal chains (Edges).\n\n"
+ "Extraction Rules:\n"
+ "- Connect events to their downstream market effects.\n"
+ "- Describe the causal mechanism at each link.\n"
+ "- Note impact direction, magnitude, and timing.\n"
+ "- Only create edges between nodes that exist in the provided lists."
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class FinancialEventCausalGraph(AutoGraph[FinancialEventNode, EventCausalEdge]):
+ """
+ Applicable to: Financial News Articles, Market Commentary, Macro Strategy Notes,
+ Economic Data Releases, Central Bank Communications, Geopolitical News.
+
+ Template for mapping financial events to their downstream market reactions.
+ Enables event-driven strategy development and macro impact analysis by
+ extracting causal chains from news and commentary.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> causal = FinancialEventCausalGraph(llm_client=llm, embedder=embedder)
+ >>> news = "The Fed raised rates by 25bps, sending bank stocks higher while tech sold off..."
+ >>> causal.feed_text(news)
+ >>> causal.show()
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ extraction_mode: str = "one_stage",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """
+ Initialize the Financial Event Causal Graph template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for event-chain extraction.
+ embedder (Embeddings): Embedding model for deduplication.
+ extraction_mode (str): "one_stage" or "two_stage".
+ chunk_size (int): Max characters per chunk.
+ chunk_overlap (int): Overlap between chunks.
+ max_workers (int): Parallel processing workers.
+ verbose (bool): Enable progress logging.
+ **kwargs: Additional arguments for AutoGraph.
+ """
+ super().__init__(
+ node_schema=FinancialEventNode,
+ edge_schema=EventCausalEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}--({x.direction})-->{x.target.strip().lower()}"
+ ),
+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ prompt=_PROMPT,
+ prompt_for_node_extraction=_NODE_PROMPT,
+ prompt_for_edge_extraction=_EDGE_PROMPT,
+ **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 event causal graph using OntoSight.
+
+ Args:
+ top_k_nodes_for_search (int): Number of events/entities to retrieve. Default 3.
+ top_k_edges_for_search (int): Number of causal links to retrieve. Default 3.
+ top_k_nodes_for_chat (int): Events/entities for chat context. Default 3.
+ top_k_edges_for_chat (int): Causal links for chat context. Default 3.
+ """
+
+ def node_label_extractor(node: FinancialEventNode) -> str:
+ return f"{node.name} ({node.node_type})"
+
+ def edge_label_extractor(edge: EventCausalEdge) -> str:
+ mag = f" [{edge.magnitude}]" if edge.magnitude else ""
+ return f"[{edge.direction}]{mag} {edge.causal_mechanism[:50]}"
+
+ 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/en/finance/market_narrative_timeline.py b/hyperextract/templates/en/finance/market_narrative_timeline.py
new file mode 100644
index 0000000..84a6982
--- /dev/null
+++ b/hyperextract/templates/en/finance/market_narrative_timeline.py
@@ -0,0 +1,208 @@
+"""Market Narrative Timeline - Tracks how market narratives evolve over time.
+
+Tracks how market narratives and dominant themes evolve over time (e.g., shift
+from "inflation fear" to "soft landing hope") for thematic investing and regime detection.
+"""
+
+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 NarrativeEntity(BaseModel):
+ """
+ A market narrative, theme, or market entity involved in narrative evolution.
+ """
+
+ name: str = Field(
+ description="Name of the narrative or entity (e.g., 'Inflation Fear', 'Soft Landing Hope', 'S&P 500', 'Fed Policy')."
+ )
+ entity_type: str = Field(
+ description="Type: 'Narrative', 'Theme', 'Market Index', 'Asset Class', 'Policy Regime', 'Economic Phase'."
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Explanation of the narrative or theme.",
+ )
+
+
+class NarrativeShiftEdge(BaseModel):
+ """
+ A narrative shift or evolution event with temporal context.
+ """
+
+ source: str = Field(description="The prior narrative or triggering entity name.")
+ target: str = Field(description="The emerging narrative or affected entity name.")
+ shift_type: str = Field(
+ description="Type: 'Replaced By', 'Evolved Into', 'Triggered', 'Dominated By', "
+ "'Coexists With', 'Undermined By'."
+ )
+ start_timestamp: Optional[str] = Field(
+ None,
+ description="When the shift began (e.g., '2024-03', 'March 2024', 'Q1 2024').",
+ )
+ end_timestamp: Optional[str] = Field(
+ None,
+ description="When the shift completed or the new narrative became dominant.",
+ )
+ catalyst: Optional[str] = Field(
+ None,
+ description="Event or data point that triggered the shift (e.g., 'CPI print of 2.4%').",
+ )
+ market_impact: Optional[str] = Field(
+ None,
+ description="How the narrative shift affected markets (e.g., 'rotation from value to growth').",
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Detailed explanation of the narrative transition.",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a thematic investing strategist. Extract market narratives, dominant themes, "
+ "and how they evolve over time from this financial commentary.\n\n"
+ "Rules:\n"
+ "- Identify dominant market narratives and themes (e.g., 'inflation fear', 'AI boom').\n"
+ "- Track how narratives shift, replace, or evolve into new ones.\n"
+ "- Extract specific dates or periods when shifts occurred.\n"
+ "- Capture the catalysts triggering narrative changes.\n"
+ "- Note market impact of narrative shifts."
+)
+
+_NODE_PROMPT = (
+ "You are a thematic investing strategist. Extract all narratives, themes, and market entities (Nodes).\n\n"
+ "Extraction Rules:\n"
+ "- Identify dominant narratives and investment themes.\n"
+ "- Identify market indices, asset classes, and policy regimes.\n"
+ "- DO NOT extract narrative shifts at this stage."
+)
+
+_EDGE_PROMPT = (
+ "You are a thematic investing strategist. Given the narratives and entities, extract "
+ "narrative shifts and evolution events (Edges) with dates.\n\n"
+ "Extraction Rules:\n"
+ "- Connect narratives through their evolution (replaced by, evolved into, etc.).\n"
+ "- Extract specific dates or periods.\n"
+ "- Capture catalysts and market impact.\n"
+ "- Only create edges between nodes that exist in the provided lists."
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class MarketNarrativeTimeline(
+ AutoTemporalGraph[NarrativeEntity, NarrativeShiftEdge]
+):
+ """
+ Applicable to: Market Commentary, Macro Strategy Notes, Financial News Archives,
+ Investment Outlook Reports, Quarterly Market Reviews.
+
+ Template for tracking how market narratives and dominant themes evolve over time.
+ Enables thematic investing, regime detection, and narrative momentum analysis.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> narrative = MarketNarrativeTimeline(llm_client=llm, embedder=embedder)
+ >>> commentary = "Markets shifted from inflation fear to soft landing hope in Q2 2024..."
+ >>> narrative.feed_text(commentary)
+ >>> narrative.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 Market Narrative Timeline template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for narrative extraction.
+ embedder (Embeddings): Embedding model for deduplication.
+ observation_time (str): Reference time for resolving relative dates.
+ extraction_mode (str): "one_stage" or "two_stage".
+ chunk_size (int): Max characters per chunk.
+ chunk_overlap (int): Overlap between chunks.
+ max_workers (int): Parallel processing workers.
+ verbose (bool): Enable progress logging.
+ **kwargs: Additional arguments for AutoTemporalGraph.
+ """
+ super().__init__(
+ node_schema=NarrativeEntity,
+ edge_schema=NarrativeShiftEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}|{x.shift_type.lower()}|{x.target.strip().lower()}"
+ ),
+ time_in_edge_extractor=lambda x: 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 market narrative timeline using OntoSight.
+
+ Args:
+ top_k_nodes_for_search (int): Number of narratives to retrieve. Default 3.
+ top_k_edges_for_search (int): Number of shifts to retrieve. Default 3.
+ top_k_nodes_for_chat (int): Narratives for chat context. Default 3.
+ top_k_edges_for_chat (int): Shifts for chat context. Default 3.
+ """
+
+ def node_label_extractor(node: NarrativeEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: NarrativeShiftEdge) -> str:
+ date = f" [{edge.start_timestamp}]" if edge.start_timestamp else ""
+ return f"{edge.shift_type}{date}"
+
+ 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/en/finance/market_sentiment_model.py b/hyperextract/templates/en/finance/market_sentiment_model.py
new file mode 100644
index 0000000..034b218
--- /dev/null
+++ b/hyperextract/templates/en/finance/market_sentiment_model.py
@@ -0,0 +1,141 @@
+"""Market Sentiment Model - Extracts sentiment snapshots from financial news.
+
+Extracts sentiment polarity (Bullish/Bearish/Neutral), mentioned entities,
+and expected price impact from financial news for real-time sentiment feeds.
+"""
+
+from typing import Optional, List, Any
+from pydantic import BaseModel, Field
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from ontomem.merger import MergeStrategy
+from hyperextract.types import AutoModel
+
+# ==============================================================================
+# 1. Schema Definitions
+# ==============================================================================
+
+
+class MarketSentimentSnapshot(BaseModel):
+ """
+ A structured sentiment snapshot from financial news or market commentary.
+ """
+
+ headline: Optional[str] = Field(
+ None, description="Headline or title of the news article/commentary."
+ )
+ source: Optional[str] = Field(
+ None, description="Publication or source (e.g., 'Bloomberg', 'Reuters', 'CNBC')."
+ )
+ publication_date: Optional[str] = Field(
+ None, description="Date of publication."
+ )
+ overall_sentiment: Optional[str] = Field(
+ None,
+ description="Overall sentiment: 'Bullish', 'Bearish', 'Neutral', 'Mixed'.",
+ )
+ sentiment_confidence: Optional[str] = Field(
+ None,
+ description="Confidence in sentiment assessment: 'High', 'Medium', 'Low'.",
+ )
+ mentioned_tickers: Optional[List[str]] = Field(
+ None,
+ description="Stock tickers mentioned (e.g., ['AAPL', 'MSFT', 'GOOGL']).",
+ )
+ mentioned_sectors: Optional[List[str]] = Field(
+ None,
+ description="Sectors referenced (e.g., ['Technology', 'Financials', 'Energy']).",
+ )
+ key_events: Optional[List[str]] = Field(
+ None,
+ description="Key events driving sentiment (e.g., ['Fed rate decision', 'NVDA earnings beat']).",
+ )
+ expected_impact: Optional[str] = Field(
+ None,
+ description="Expected price/market impact (e.g., 'Near-term upside for tech', 'Sector rotation likely').",
+ )
+ time_horizon: Optional[str] = Field(
+ None,
+ description="Implied time horizon: 'Intraday', 'Short-term', 'Medium-term', 'Long-term'.",
+ )
+ contrarian_signals: Optional[List[str]] = Field(
+ None,
+ description="Any contrarian or dissenting views noted.",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a financial sentiment analyst. Extract the sentiment snapshot from this financial "
+ "news article or market commentary.\n\n"
+ "Rules:\n"
+ "- Determine the overall sentiment polarity (Bullish/Bearish/Neutral/Mixed).\n"
+ "- Identify all mentioned tickers and sectors.\n"
+ "- Extract key events driving the sentiment.\n"
+ "- Assess expected market impact and time horizon.\n"
+ "- Note any contrarian or dissenting views.\n\n"
+ "### Source Text:\n"
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class MarketSentimentModel(AutoModel[MarketSentimentSnapshot]):
+ """
+ Applicable to: Financial News Articles, Market Commentary, Analyst Blogs,
+ Trading Desk Notes, Market Wrap-ups, Pre-market Briefings.
+
+ Template for extracting a structured sentiment snapshot from financial news.
+ Produces a single consolidated sentiment view per article for real-time
+ sentiment feeds and trading signal generation.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> sentiment = MarketSentimentModel(llm_client=llm, embedder=embedder)
+ >>> news = "Tech stocks rallied sharply after NVDA reported record earnings..."
+ >>> sentiment.feed_text(news)
+ >>> print(sentiment.data)
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """
+ Initialize the Market Sentiment Model template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for sentiment extraction.
+ embedder (Embeddings): Embedding model for indexing.
+ chunk_size (int): Max characters per chunk.
+ chunk_overlap (int): Overlap between chunks.
+ max_workers (int): Parallel processing workers.
+ verbose (bool): Enable progress logging.
+ **kwargs: Additional arguments for AutoModel.
+ """
+ super().__init__(
+ data_schema=MarketSentimentSnapshot,
+ llm_client=llm_client,
+ embedder=embedder,
+ strategy_or_merger=MergeStrategy.LLM.BALANCED,
+ prompt=_PROMPT,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ **kwargs,
+ )
diff --git a/hyperextract/templates/en/finance/multi_source_sentiment_hypergraph.py b/hyperextract/templates/en/finance/multi_source_sentiment_hypergraph.py
new file mode 100644
index 0000000..387c90f
--- /dev/null
+++ b/hyperextract/templates/en/finance/multi_source_sentiment_hypergraph.py
@@ -0,0 +1,210 @@
+"""Multi-Source Sentiment Hypergraph - Integrates sentiment signals from multiple sources.
+
+Integrates sentiment signals from multiple sources: {News Article, Social Media Post,
+Analyst Note} -> Aggregated Sentiment -> Affected Entity for ensemble scoring.
+"""
+
+from typing import Optional, List, 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 AutoHypergraph
+
+# ==============================================================================
+# 1. Schema Definitions
+# ==============================================================================
+
+
+class SentimentSource(BaseModel):
+ """
+ A source of sentiment signal or an affected market entity.
+ """
+
+ name: str = Field(
+ description="Name of the source or entity (e.g., 'Bloomberg Article', 'Analyst Note from GS', 'AAPL', 'Tech Sector')."
+ )
+ source_type: str = Field(
+ description="Type: 'News Article', 'Analyst Note', 'Social Media', 'Market Data', 'Company Filing', "
+ "'Affected Entity', 'Sector', 'Index'."
+ )
+ sentiment_signal: Optional[str] = Field(
+ None,
+ description="Individual sentiment from this source: 'Bullish', 'Bearish', 'Neutral'.",
+ )
+ credibility: Optional[str] = Field(
+ None,
+ description="Source credibility assessment: 'Tier 1', 'Tier 2', 'Unverified'.",
+ )
+
+
+class AggregatedSentiment(BaseModel):
+ """
+ An aggregated sentiment signal fusing multiple sources for an affected entity.
+ """
+
+ fusion_name: str = Field(
+ description="Descriptive name (e.g., 'AAPL Bullish Consensus from 3 Sources')."
+ )
+ participating_sources: List[str] = Field(
+ description="Names of all sources and affected entities in this fusion."
+ )
+ aggregated_polarity: str = Field(
+ description="Fused sentiment: 'Strong Bullish', 'Bullish', 'Neutral', 'Bearish', 'Strong Bearish', 'Conflicting'."
+ )
+ agreement_level: str = Field(
+ description="Source agreement: 'Unanimous', 'Majority', 'Split', 'Contradictory'."
+ )
+ affected_entity: Optional[str] = Field(
+ None,
+ description="Primary entity the sentiment applies to (ticker or sector).",
+ )
+ signal_strength: Optional[str] = Field(
+ None,
+ description="Overall signal strength for trading: 'Actionable', 'Informational', 'Noise'.",
+ )
+ conflicting_views: Optional[str] = Field(
+ None,
+ description="Summary of any dissenting or conflicting sentiment signals.",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a multi-source sentiment fusion analyst. Extract sentiment signals from different "
+ "sources and create aggregated sentiment views.\n\n"
+ "Rules:\n"
+ "- Identify each distinct source of sentiment (news, analyst notes, social media).\n"
+ "- Extract the individual sentiment signal from each source.\n"
+ "- Create aggregated sentiment hyperedges connecting sources to affected entities.\n"
+ "- Assess agreement level across sources.\n"
+ "- Note conflicting views and signal strength."
+)
+
+_NODE_PROMPT = (
+ "You are a sentiment fusion analyst. Extract all sentiment sources and affected entities (Nodes).\n\n"
+ "Extraction Rules:\n"
+ "- Identify news articles, analyst notes, and social media posts.\n"
+ "- Identify affected entities (tickers, sectors, indices).\n"
+ "- Capture individual sentiment from each source.\n"
+ "- DO NOT create aggregated views at this stage."
+)
+
+_EDGE_PROMPT = (
+ "You are a sentiment fusion analyst. Given the sources and entities, create aggregated "
+ "sentiment fusions (Hyperedges).\n\n"
+ "Extraction Rules:\n"
+ "- Each hyperedge connects multiple sources to an affected entity.\n"
+ "- Assess the aggregated sentiment polarity and agreement level.\n"
+ "- Evaluate signal strength for trading purposes.\n"
+ "- Note any conflicting views.\n"
+ "- Only reference elements that exist in the provided lists."
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class MultiSourceSentimentHypergraph(
+ AutoHypergraph[SentimentSource, AggregatedSentiment]
+):
+ """
+ Applicable to: Financial News feeds, Analyst Report collections,
+ Social Media streams, Multi-source Market Intelligence.
+
+ Template for integrating sentiment signals from multiple sources. Uses
+ hyperedges to connect multiple sources to aggregated sentiment views,
+ enabling ensemble sentiment scoring and fake signal filtering.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> fusion = MultiSourceSentimentHypergraph(llm_client=llm, embedder=embedder)
+ >>> text = "Bloomberg reports tech rally. Meanwhile, GS upgrades AAPL. Twitter sentiment bullish."
+ >>> fusion.feed_text(text)
+ >>> fusion.show()
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ extraction_mode: str = "two_stage",
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """
+ Initialize the Multi-Source Sentiment Hypergraph template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for sentiment fusion.
+ embedder (Embeddings): Embedding model for deduplication.
+ extraction_mode (str): "one_stage" or "two_stage".
+ chunk_size (int): Max characters per chunk.
+ chunk_overlap (int): Overlap between chunks.
+ max_workers (int): Parallel processing workers.
+ verbose (bool): Enable progress logging.
+ **kwargs: Additional arguments for AutoHypergraph.
+ """
+ super().__init__(
+ node_schema=SentimentSource,
+ edge_schema=AggregatedSentiment,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: x.fusion_name.strip().lower(),
+ nodes_in_edge_extractor=lambda x: tuple(
+ s.strip().lower() for s in x.participating_sources
+ ),
+ llm_client=llm_client,
+ embedder=embedder,
+ 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 multi-source sentiment hypergraph using OntoSight.
+
+ Args:
+ top_k_nodes_for_search (int): Number of sources to retrieve. Default 3.
+ top_k_edges_for_search (int): Number of fusions to retrieve. Default 3.
+ top_k_nodes_for_chat (int): Sources for chat context. Default 3.
+ top_k_edges_for_chat (int): Fusions for chat context. Default 3.
+ """
+
+ def node_label_extractor(node: SentimentSource) -> str:
+ signal = f" [{node.sentiment_signal}]" if node.sentiment_signal else ""
+ return f"{node.name} ({node.source_type}){signal}"
+
+ def edge_label_extractor(edge: AggregatedSentiment) -> str:
+ return f"[{edge.aggregated_polarity}] {edge.fusion_name}"
+
+ 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/financial_event_causal_graph.py b/hyperextract/templates/zh/finance/financial_event_causal_graph.py
new file mode 100644
index 0000000..fab42ff
--- /dev/null
+++ b/hyperextract/templates/zh/finance/financial_event_causal_graph.py
@@ -0,0 +1,197 @@
+"""金融事件因果图谱 - 将金融事件映射到市场反应。
+
+将金融事件映射到受影响的实体和下游市场反应
+(例如"美联储加息 -> 银行板块上涨 -> 债券收益率上升"),用于事件驱动策略。
+"""
+
+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 AutoGraph
+
+# ==============================================================================
+# 1. Schema 定义
+# ==============================================================================
+
+
+class FinancialEventNode(BaseModel):
+ """
+ 事件链中的金融事件、市场实体或市场反应。
+ """
+
+ name: str = Field(
+ description='事件或实体的名称(例如"美联储加息"、"银行板块"、"美元走强")。'
+ )
+ node_type: str = Field(
+ description='类型:"事件"、"实体"、"市场反应"、"政策"、"经济指标"、"板块"。'
+ )
+ description: Optional[str] = Field(
+ None,
+ description='关于该事件/实体的背景或详细信息。',
+ )
+
+
+class EventCausalEdge(BaseModel):
+ """
+ 从金融事件到市场反应的因果关系。
+ """
+
+ source: str = Field(description='原因事件或实体名称。')
+ target: str = Field(description='结果或下游反应名称。')
+ causal_mechanism: str = Field(
+ description='原因如何导致目标效果'
+ '(例如"更高利率降低借贷成本敏感性")。'
+ )
+ direction: str = Field(
+ description='影响方向:"正面"、"负面"、"不确定"。'
+ )
+ magnitude: Optional[str] = Field(
+ None,
+ description='陈述或隐含的幅度(例如"标普 500 上涨 2%"、"50 个基点的影响")。',
+ )
+ timing: Optional[str] = Field(
+ None,
+ description='反应时间:"即时"、"当日"、"多日"、"滞后"。',
+ )
+ confidence: Optional[str] = Field(
+ None,
+ description='因果关系的置信度:"已确立"、"可能"、"推测性"。',
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是宏观策略师和财经新闻分析师。从这篇新闻或评论中提取金融事件、受影响的市场实体"
+ "以及连接它们的因果链。\n\n"
+ "规则:\n"
+ "- 识别触发事件(政策决议、财报、经济数据发布)。\n"
+ "- 识别受影响的实体(板块、个股、指数、大宗商品)。\n"
+ "- 映射从事件到市场反应的因果链。\n"
+ "- 捕捉反应的幅度和时间。\n"
+ "- 记录每条因果关系的置信度。"
+)
+
+_NODE_PROMPT = (
+ "你是宏观策略师。提取所有金融事件、实体和市场反应(节点)。\n\n"
+ "提取规则:\n"
+ "- 识别触发事件和政策决议。\n"
+ "- 识别市场板块、指数和大宗商品。\n"
+ "- 识别市场反应和价格变动。\n"
+ "- 此阶段不建立因果关系。"
+)
+
+_EDGE_PROMPT = (
+ "你是宏观策略师。在获得事件和实体清单的基础上,提取因果链(边)。\n\n"
+ "提取规则:\n"
+ "- 将事件连接到其下游市场效果。\n"
+ "- 描述每条链路的因果机制。\n"
+ "- 记录影响方向、幅度和时间。\n"
+ "- 仅在提供的列表中存在的节点之间创建边。"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class FinancialEventCausalGraph(AutoGraph[FinancialEventNode, EventCausalEdge]):
+ """
+ 适用文档: 财经新闻文章、市场评论、宏观策略报告、经济数据发布、
+ 央行沟通文件、地缘政治新闻。
+
+ 模板用于将金融事件映射到其下游市场反应。通过从新闻和评论中提取因果链,
+ 支持事件驱动策略开发和宏观影响分析。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> causal = FinancialEventCausalGraph(llm_client=llm, embedder=embedder)
+ >>> news = "美联储加息 25 个基点,推动银行股上涨,同时科技股遭到抛售..."
+ >>> causal.feed_text(news)
+ >>> causal.show()
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ extraction_mode: str = "one_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): 用于去重的嵌入模型。
+ extraction_mode (str): "one_stage" 或 "two_stage"。
+ chunk_size (int): 每个分块的最大字符数。
+ chunk_overlap (int): 分块之间的重叠。
+ max_workers (int): 并行处理工作线程数。
+ verbose (bool): 是否启用进度日志。
+ **kwargs: AutoGraph 的其他参数。
+ """
+ super().__init__(
+ node_schema=FinancialEventNode,
+ edge_schema=EventCausalEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}--({x.direction})-->{x.target.strip().lower()}"
+ ),
+ nodes_in_edge_extractor=lambda x: (x.source.strip(), x.target.strip()),
+ llm_client=llm_client,
+ embedder=embedder,
+ extraction_mode=extraction_mode,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ prompt=_PROMPT,
+ prompt_for_node_extraction=_NODE_PROMPT,
+ prompt_for_edge_extraction=_EDGE_PROMPT,
+ **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: FinancialEventNode) -> str:
+ return f"{node.name} ({node.node_type})"
+
+ def edge_label_extractor(edge: EventCausalEdge) -> str:
+ mag = f" [{edge.magnitude}]" if edge.magnitude else ""
+ return f"[{edge.direction}]{mag} {edge.causal_mechanism[:50]}"
+
+ 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/market_narrative_timeline.py b/hyperextract/templates/zh/finance/market_narrative_timeline.py
new file mode 100644
index 0000000..3bead98
--- /dev/null
+++ b/hyperextract/templates/zh/finance/market_narrative_timeline.py
@@ -0,0 +1,206 @@
+"""市场叙事时间线 - 追踪市场叙事随时间的演变。
+
+追踪市场叙事和主导主题随时间的演变(例如从"通胀恐惧"转向"软着陆希望"),
+用于主题投资和市场体制识别。
+"""
+
+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 NarrativeEntity(BaseModel):
+ """
+ 参与叙事演变的市场叙事、主题或市场实体。
+ """
+
+ name: str = Field(
+ description='叙事或实体的名称(例如"通胀恐惧"、"软着陆希望"、"标普 500"、"美联储政策")。'
+ )
+ entity_type: str = Field(
+ description='类型:"叙事"、"主题"、"市场指数"、"资产类别"、"政策体制"、"经济阶段"。'
+ )
+ description: Optional[str] = Field(
+ None,
+ description='对该叙事或主题的解释。',
+ )
+
+
+class NarrativeShiftEdge(BaseModel):
+ """
+ 具有时间背景的叙事转变或演变事件。
+ """
+
+ source: str = Field(description='先前的叙事或触发实体名称。')
+ target: str = Field(description='新兴叙事或受影响实体名称。')
+ shift_type: str = Field(
+ description='类型:"被替代"、"演变为"、"触发了"、"主导了"、'
+ '"共存于"、"被削弱"。'
+ )
+ start_timestamp: Optional[str] = Field(
+ None,
+ description='转变开始时间(例如"2024-03"、"2024年3月"、"2024年第一季度")。',
+ )
+ end_timestamp: Optional[str] = Field(
+ None,
+ description='转变完成或新叙事成为主导的时间。',
+ )
+ catalyst: Optional[str] = Field(
+ None,
+ description='触发转变的事件或数据点(例如"CPI 数据为 2.4%")。',
+ )
+ market_impact: Optional[str] = Field(
+ None,
+ description='叙事转变如何影响市场(例如"从价值股轮动到成长股")。',
+ )
+ description: Optional[str] = Field(
+ None,
+ description='叙事转变的详细解释。',
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是主题投资策略师。从这篇财经评论中提取市场叙事、主导主题以及它们随时间的演变。\n\n"
+ "规则:\n"
+ "- 识别主导市场叙事和主题(例如'通胀恐惧'、'AI 热潮')。\n"
+ "- 追踪叙事如何转变、替代或演变为新的叙事。\n"
+ "- 提取转变发生的具体日期或时间段。\n"
+ "- 捕捉触发叙事变化的催化剂。\n"
+ "- 记录叙事转变的市场影响。"
+)
+
+_NODE_PROMPT = (
+ "你是主题投资策略师。提取所有叙事、主题和市场实体(节点)。\n\n"
+ "提取规则:\n"
+ "- 识别主导叙事和投资主题。\n"
+ "- 识别市场指数、资产类别和政策体制。\n"
+ "- 此阶段不提取叙事转变。"
+)
+
+_EDGE_PROMPT = (
+ "你是主题投资策略师。在获得叙事和实体清单的基础上,提取叙事转变和演变事件(边),"
+ "附带日期。\n\n"
+ "提取规则:\n"
+ "- 通过叙事的演变连接它们(被替代、演变为等)。\n"
+ "- 提取具体日期或时间段。\n"
+ "- 捕捉催化剂和市场影响。\n"
+ "- 仅在提供的列表中存在的节点之间创建边。"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class MarketNarrativeTimeline(
+ AutoTemporalGraph[NarrativeEntity, NarrativeShiftEdge]
+):
+ """
+ 适用文档: 市场评论、宏观策略报告、财经新闻档案、投资展望报告、季度市场回顾。
+
+ 模板用于追踪市场叙事和主导主题随时间的演变。支持主题投资、
+ 市场体制识别和叙事动量分析。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> narrative = MarketNarrativeTimeline(llm_client=llm, embedder=embedder)
+ >>> commentary = "市场在 2024 年第二季度从通胀恐惧转向软着陆希望..."
+ >>> narrative.feed_text(commentary)
+ >>> narrative.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"。
+ chunk_size (int): 每个分块的最大字符数。
+ chunk_overlap (int): 分块之间的重叠。
+ max_workers (int): 并行处理工作线程数。
+ verbose (bool): 是否启用进度日志。
+ **kwargs: AutoTemporalGraph 的其他参数。
+ """
+ super().__init__(
+ node_schema=NarrativeEntity,
+ edge_schema=NarrativeShiftEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}|{x.shift_type.lower()}|{x.target.strip().lower()}"
+ ),
+ time_in_edge_extractor=lambda x: 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: NarrativeEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: NarrativeShiftEdge) -> str:
+ date = f" [{edge.start_timestamp}]" if edge.start_timestamp else ""
+ return f"{edge.shift_type}{date}"
+
+ 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/market_sentiment_model.py b/hyperextract/templates/zh/finance/market_sentiment_model.py
new file mode 100644
index 0000000..85eb5d9
--- /dev/null
+++ b/hyperextract/templates/zh/finance/market_sentiment_model.py
@@ -0,0 +1,138 @@
+"""市场情绪模型 - 从财经新闻中提取情绪快照。
+
+从财经新闻中提取情绪极性(看涨/看跌/中性)、提及的实体和预期价格影响,
+用于实时情绪数据流。
+"""
+
+from typing import Optional, List, Any
+from pydantic import BaseModel, Field
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.embeddings import Embeddings
+from ontomem.merger import MergeStrategy
+from hyperextract.types import AutoModel
+
+# ==============================================================================
+# 1. Schema 定义
+# ==============================================================================
+
+
+class MarketSentimentSnapshot(BaseModel):
+ """
+ 从财经新闻或市场评论中提取的结构化情绪快照。
+ """
+
+ headline: Optional[str] = Field(
+ None, description='新闻文章/评论的标题。'
+ )
+ source: Optional[str] = Field(
+ None, description='出版物或来源(例如"彭博社"、"路透社"、"CNBC")。'
+ )
+ publication_date: Optional[str] = Field(
+ None, description='发布日期。'
+ )
+ overall_sentiment: Optional[str] = Field(
+ None,
+ description='整体情绪:"看涨"、"看跌"、"中性"、"混合"。',
+ )
+ sentiment_confidence: Optional[str] = Field(
+ None,
+ description='情绪评估的置信度:"高"、"中"、"低"。',
+ )
+ mentioned_tickers: Optional[List[str]] = Field(
+ None,
+ description="提及的股票代码(例如 ['AAPL', 'MSFT', 'GOOGL'])。",
+ )
+ mentioned_sectors: Optional[List[str]] = Field(
+ None,
+ description="涉及的行业板块(例如 ['科技', '金融', '能源'])。",
+ )
+ key_events: Optional[List[str]] = Field(
+ None,
+ description="驱动情绪的关键事件(例如 ['美联储利率决议', 'NVDA 财报超预期'])。",
+ )
+ expected_impact: Optional[str] = Field(
+ None,
+ description='预期的价格/市场影响(例如"科技股短期上行"、"板块轮动可能性大")。',
+ )
+ time_horizon: Optional[str] = Field(
+ None,
+ description='隐含时间范围:"盘中"、"短期"、"中期"、"长期"。',
+ )
+ contrarian_signals: Optional[List[str]] = Field(
+ None,
+ description='任何逆向或不同意见的观点。',
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是金融情绪分析师。从这篇财经新闻文章或市场评论中提取情绪快照。\n\n"
+ "规则:\n"
+ "- 判断整体情绪极性(看涨/看跌/中性/混合)。\n"
+ "- 识别所有提及的股票代码和行业板块。\n"
+ "- 提取驱动情绪的关键事件。\n"
+ "- 评估预期市场影响和时间范围。\n"
+ "- 记录任何逆向或不同意见的观点。\n\n"
+ "### 源文本:\n"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class MarketSentimentModel(AutoModel[MarketSentimentSnapshot]):
+ """
+ 适用文档: 财经新闻文章、市场评论、分析师博客、交易台笔记、市场总结、盘前简报。
+
+ 模板用于从财经新闻中提取结构化情绪快照。为每篇文章生成一个综合情绪视图,
+ 用于实时情绪数据流和交易信号生成。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> sentiment = MarketSentimentModel(llm_client=llm, embedder=embedder)
+ >>> news = "科技股在 NVDA 公布创纪录财报后大幅上涨..."
+ >>> sentiment.feed_text(news)
+ >>> print(sentiment.data)
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ chunk_size: int = 2048,
+ chunk_overlap: int = 256,
+ max_workers: int = 10,
+ verbose: bool = False,
+ **kwargs: Any,
+ ):
+ """
+ 初始化市场情绪模型模板。
+
+ Args:
+ llm_client (BaseChatModel): 用于情绪提取的 LLM。
+ embedder (Embeddings): 用于索引的嵌入模型。
+ chunk_size (int): 每个分块的最大字符数。
+ chunk_overlap (int): 分块之间的重叠。
+ max_workers (int): 并行处理工作线程数。
+ verbose (bool): 是否启用进度日志。
+ **kwargs: AutoModel 的其他参数。
+ """
+ super().__init__(
+ data_schema=MarketSentimentSnapshot,
+ llm_client=llm_client,
+ embedder=embedder,
+ strategy_or_merger=MergeStrategy.LLM.BALANCED,
+ prompt=_PROMPT,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ **kwargs,
+ )
diff --git a/hyperextract/templates/zh/finance/multi_source_sentiment_hypergraph.py b/hyperextract/templates/zh/finance/multi_source_sentiment_hypergraph.py
new file mode 100644
index 0000000..ad1bdaf
--- /dev/null
+++ b/hyperextract/templates/zh/finance/multi_source_sentiment_hypergraph.py
@@ -0,0 +1,206 @@
+"""多源情绪超图 - 整合多个来源的情绪信号。
+
+整合多个来源的情绪信号:{新闻文章, 社交媒体帖子, 分析师报告}
+-> 聚合情绪 -> 受影响实体,用于集成评分。
+"""
+
+from typing import Optional, List, 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 AutoHypergraph
+
+# ==============================================================================
+# 1. Schema 定义
+# ==============================================================================
+
+
+class SentimentSource(BaseModel):
+ """
+ 情绪信号的来源或受影响的市场实体。
+ """
+
+ name: str = Field(
+ description='来源或实体的名称(例如"彭博社文章"、"高盛分析师报告"、"AAPL"、"科技板块")。'
+ )
+ source_type: str = Field(
+ description='类型:"新闻文章"、"分析师报告"、"社交媒体"、"市场数据"、"公司公告"、'
+ '"受影响实体"、"板块"、"指数"。'
+ )
+ sentiment_signal: Optional[str] = Field(
+ None,
+ description='该来源的个别情绪:"看涨"、"看跌"、"中性"。',
+ )
+ credibility: Optional[str] = Field(
+ None,
+ description='来源可信度评估:"一级"、"二级"、"未验证"。',
+ )
+
+
+class AggregatedSentiment(BaseModel):
+ """
+ 融合多个来源的聚合情绪信号,针对受影响实体。
+ """
+
+ fusion_name: str = Field(
+ description='描述性名称(例如"AAPL 来自 3 个来源的看涨共识")。'
+ )
+ participating_sources: List[str] = Field(
+ description='参与此融合的所有来源和受影响实体的名称。'
+ )
+ aggregated_polarity: str = Field(
+ description='融合情绪:"强烈看涨"、"看涨"、"中性"、"看跌"、"强烈看跌"、"冲突"。'
+ )
+ agreement_level: str = Field(
+ description='来源一致性:"一致"、"多数"、"分裂"、"矛盾"。'
+ )
+ affected_entity: Optional[str] = Field(
+ None,
+ description='情绪适用的主要实体(股票代码或板块)。',
+ )
+ signal_strength: Optional[str] = Field(
+ None,
+ description='交易用的整体信号强度:"可操作"、"参考性"、"噪音"。',
+ )
+ conflicting_views: Optional[str] = Field(
+ None,
+ description='任何不同或冲突的情绪信号摘要。',
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是多源情绪融合分析师。从不同来源提取情绪信号并创建聚合情绪视图。\n\n"
+ "规则:\n"
+ "- 识别每个不同的情绪来源(新闻、分析师报告、社交媒体)。\n"
+ "- 提取每个来源的个别情绪信号。\n"
+ "- 创建连接来源到受影响实体的聚合情绪超边。\n"
+ "- 评估各来源之间的一致性。\n"
+ "- 记录冲突观点和信号强度。"
+)
+
+_NODE_PROMPT = (
+ "你是情绪融合分析师。提取所有情绪来源和受影响实体(节点)。\n\n"
+ "提取规则:\n"
+ "- 识别新闻文章、分析师报告和社交媒体帖子。\n"
+ "- 识别受影响实体(股票代码、板块、指数)。\n"
+ "- 捕捉每个来源的个别情绪。\n"
+ "- 此阶段不创建聚合视图。"
+)
+
+_EDGE_PROMPT = (
+ "你是情绪融合分析师。在获得来源和实体清单的基础上,创建聚合情绪融合(超边)。\n\n"
+ "提取规则:\n"
+ "- 每条超边连接多个来源到一个受影响实体。\n"
+ "- 评估聚合情绪极性和一致性水平。\n"
+ "- 评估交易用途的信号强度。\n"
+ "- 记录任何冲突观点。\n"
+ "- 仅引用提供列表中存在的元素。"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class MultiSourceSentimentHypergraph(
+ AutoHypergraph[SentimentSource, AggregatedSentiment]
+):
+ """
+ 适用文档: 财经新闻流、分析师报告合集、社交媒体数据流、多源市场情报。
+
+ 模板用于整合多个来源的情绪信号。使用超边将多个来源连接到聚合情绪视图,
+ 支持集成情绪评分和虚假信号过滤。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> fusion = MultiSourceSentimentHypergraph(llm_client=llm, embedder=embedder)
+ >>> text = "彭博社报道科技股上涨。同时高盛上调 AAPL 评级。推特情绪看涨。"
+ >>> fusion.feed_text(text)
+ >>> fusion.show()
+ """
+
+ def __init__(
+ self,
+ llm_client: BaseChatModel,
+ embedder: Embeddings,
+ *,
+ 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): 用于去重的嵌入模型。
+ extraction_mode (str): "one_stage" 或 "two_stage"。
+ chunk_size (int): 每个分块的最大字符数。
+ chunk_overlap (int): 分块之间的重叠。
+ max_workers (int): 并行处理工作线程数。
+ verbose (bool): 是否启用进度日志。
+ **kwargs: AutoHypergraph 的其他参数。
+ """
+ super().__init__(
+ node_schema=SentimentSource,
+ edge_schema=AggregatedSentiment,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: x.fusion_name.strip().lower(),
+ nodes_in_edge_extractor=lambda x: tuple(
+ s.strip().lower() for s in x.participating_sources
+ ),
+ llm_client=llm_client,
+ embedder=embedder,
+ 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: SentimentSource) -> str:
+ signal = f" [{node.sentiment_signal}]" if node.sentiment_signal else ""
+ return f"{node.name} ({node.source_type}){signal}"
+
+ def edge_label_extractor(edge: AggregatedSentiment) -> str:
+ return f"[{edge.aggregated_polarity}] {edge.fusion_name}"
+
+ 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,
+ )