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 Prospectuses / IPO Filings (S-1) templates - ShareholderStructure (AutoGraph) - ownership hierarchies - ProceedsUsage (AutoList) - fund allocation - CompanyHistoryTimeline (AutoTemporalGraph) - corporate milestones

yuxizheb8bbf0561ea3
diff --git a/hyperextract/templates/en/finance/company_history_timeline.py b/hyperextract/templates/en/finance/company_history_timeline.py
new file mode 100644
index 0000000..76fd9f8
--- /dev/null
+++ b/hyperextract/templates/en/finance/company_history_timeline.py
@@ -0,0 +1,203 @@
+"""Company History Timeline - Chronological extraction of corporate milestones.
+
+Extracts founding events, funding rounds, major pivots, and key milestones
+from prospectuses and company histories for due diligence and history mapping.
+"""
+
+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 CorporateEntity(BaseModel):
+ """
+ An entity involved in corporate history milestones.
+ """
+
+ name: str = Field(
+ description="Name of the entity (e.g., company name, founder, investor, acquiree)."
+ )
+ entity_type: str = Field(
+ description="Type: 'Company', 'Founder', 'Investor', 'Acquiree', 'Partner', 'Regulator'."
+ )
+ description: Optional[str] = Field(
+ None, description="Role or context (e.g., 'Series A lead', 'Acquired subsidiary')."
+ )
+
+
+class CorporateMilestoneEdge(BaseModel):
+ """
+ A corporate milestone event with temporal context.
+ """
+
+ source: str = Field(description="The acting entity name.")
+ target: str = Field(description="The affected entity or milestone target.")
+ event_type: str = Field(
+ description="Type: 'Founding', 'Funding Round', 'Acquisition', 'Product Launch', "
+ "'IPO', 'Pivot', 'Partnership', 'Expansion', 'Restructuring', 'Key Hire'."
+ )
+ start_timestamp: Optional[str] = Field(
+ None,
+ description="Date of the milestone (e.g., '2015-06', 'March 2018', '2020').",
+ )
+ end_timestamp: Optional[str] = Field(
+ None,
+ description="End date if applicable (e.g., acquisition closing date).",
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Details of the milestone (e.g., '$50M Series B led by Sequoia').",
+ )
+ financial_details: Optional[str] = Field(
+ None,
+ description="Financial terms when available (e.g., valuation, deal size).",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a due diligence analyst. Extract corporate history milestones and the entities "
+ "involved from this prospectus or company history document.\n\n"
+ "Rules:\n"
+ "- Identify founding events, funding rounds, acquisitions, pivots, and key hires.\n"
+ "- Extract specific dates or time periods for each milestone.\n"
+ "- Capture financial details (valuations, deal sizes) when mentioned.\n"
+ "- Maintain chronological accuracy."
+)
+
+_NODE_PROMPT = (
+ "You are a due diligence analyst. Extract all entities (Nodes) involved in corporate history.\n\n"
+ "Extraction Rules:\n"
+ "- Identify the company, founders, investors, acquired companies, and partners.\n"
+ "- Classify each entity by type.\n"
+ "- DO NOT extract events at this stage."
+)
+
+_EDGE_PROMPT = (
+ "You are a due diligence analyst. Given the entities, extract corporate milestones (Edges) with dates.\n\n"
+ "Extraction Rules:\n"
+ "- Connect entities through milestone events.\n"
+ "- Extract specific dates or time periods.\n"
+ "- Capture financial details (deal sizes, valuations).\n"
+ "- Classify each milestone by type.\n"
+ "- Only create edges between nodes that exist in the provided lists."
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class CompanyHistoryTimeline(
+ AutoTemporalGraph[CorporateEntity, CorporateMilestoneEdge]
+):
+ """
+ Applicable to: S-1 Prospectuses (Business section), Company About pages,
+ Due Diligence reports, Corporate History summaries, Investor Presentations.
+
+ Template for chronologically extracting corporate milestones from prospectuses
+ and company histories. Enables due diligence timeline construction and
+ corporate evolution tracking.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> history = CompanyHistoryTimeline(llm_client=llm, embedder=embedder)
+ >>> text = "Founded in 2015 by John Doe. Raised $10M Series A in 2017..."
+ >>> history.feed_text(text)
+ >>> history.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 Company History Timeline template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for milestone 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=CorporateEntity,
+ edge_schema=CorporateMilestoneEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}|{x.event_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 company history timeline using OntoSight.
+
+ Args:
+ top_k_nodes_for_search (int): Number of entities to retrieve. Default 3.
+ top_k_edges_for_search (int): Number of milestones to retrieve. Default 3.
+ top_k_nodes_for_chat (int): Entities for chat context. Default 3.
+ top_k_edges_for_chat (int): Milestones for chat context. Default 3.
+ """
+
+ def node_label_extractor(node: CorporateEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: CorporateMilestoneEdge) -> str:
+ date = f" [{edge.start_timestamp}]" if edge.start_timestamp else ""
+ return f"{edge.event_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/proceeds_usage.py b/hyperextract/templates/en/finance/proceeds_usage.py
new file mode 100644
index 0000000..b9e9b12
--- /dev/null
+++ b/hyperextract/templates/en/finance/proceeds_usage.py
@@ -0,0 +1,146 @@
+"""Proceeds Usage - Extracts fund allocation details from prospectuses.
+
+Extracts project names, allocated amounts, and estimated timelines for IPO
+proceeds or debt offering fund usage for post-IPO monitoring.
+"""
+
+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 AutoList
+
+# ==============================================================================
+# 1. Schema Definitions
+# ==============================================================================
+
+
+class ProceedsItem(BaseModel):
+ """
+ A single use-of-proceeds allocation item.
+ """
+
+ use_category: str = Field(
+ description="Category of fund usage (e.g., 'R&D Investment', 'Debt Repayment', 'Working Capital', "
+ "'Acquisitions', 'Capital Expenditures', 'General Corporate Purposes')."
+ )
+ project_name: Optional[str] = Field(
+ None,
+ description="Specific project or initiative name (e.g., 'New Data Center in Virginia', 'Platform 2.0 Development').",
+ )
+ allocated_amount: Optional[str] = Field(
+ None,
+ description="Amount allocated (e.g., '$150 million', 'approximately 30% of net proceeds').",
+ )
+ percentage_of_proceeds: Optional[str] = Field(
+ None,
+ description="Percentage of total proceeds (e.g., '30%', 'approximately one-third').",
+ )
+ timeline: Optional[str] = Field(
+ None,
+ description="Expected deployment timeline (e.g., '12-18 months', 'FY2025-2026').",
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Detailed description of how funds will be used.",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are an IPO analyst. Extract all use-of-proceeds allocations from this prospectus "
+ "or offering document.\n\n"
+ "Rules:\n"
+ "- Extract every distinct fund usage category and specific project.\n"
+ "- Capture allocated amounts and percentages.\n"
+ "- Extract deployment timelines when stated.\n"
+ "- Preserve detailed descriptions of how funds will be used.\n"
+ "- Extract EVERY allocation independently as a separate item.\n\n"
+ "### Source Text:\n"
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class ProceedsUsage(AutoList[ProceedsItem]):
+ """
+ Applicable to: S-1 Prospectuses (Use of Proceeds section), Debt Offering Memoranda,
+ Secondary Offering Prospectuses, SPAC Proxy Statements.
+
+ Template for extracting fund allocation details from prospectuses and offering
+ documents. Each allocation is captured as an independent item for post-IPO
+ monitoring and proceeds tracking.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> proceeds = ProceedsUsage(llm_client=llm, embedder=embedder)
+ >>> prospectus = "We intend to use approximately $150M for R&D, $100M for debt repayment..."
+ >>> proceeds.feed_text(prospectus)
+ >>> proceeds.show()
+ """
+
+ 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 Proceeds Usage template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for proceeds 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 AutoList.
+ """
+ super().__init__(
+ item_schema=ProceedsItem,
+ llm_client=llm_client,
+ embedder=embedder,
+ prompt=_PROMPT,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ **kwargs,
+ )
+
+ def show(
+ self,
+ *,
+ top_k_for_search: int = 3,
+ top_k_for_chat: int = 3,
+ ) -> None:
+ """
+ Visualize the proceeds usage list.
+
+ Args:
+ top_k_for_search (int): Items for search. Default 3.
+ top_k_for_chat (int): Items for chat context. Default 3.
+ """
+
+ def label_extractor(item: ProceedsItem) -> str:
+ amount = f": {item.allocated_amount}" if item.allocated_amount else ""
+ return f"{item.use_category}{amount}"
+
+ super().show(
+ item_label_extractor=label_extractor,
+ top_k_for_search=top_k_for_search,
+ top_k_for_chat=top_k_for_chat,
+ )
diff --git a/hyperextract/templates/en/finance/shareholder_structure.py b/hyperextract/templates/en/finance/shareholder_structure.py
new file mode 100644
index 0000000..d3f80f4
--- /dev/null
+++ b/hyperextract/templates/en/finance/shareholder_structure.py
@@ -0,0 +1,205 @@
+"""Shareholder Structure - Extracts ownership hierarchies from prospectuses.
+
+Maps shareholder percentages, controlling paths, and parent-subsidiary relations
+from S-1 filings and proxy statements for ultimate controller analysis.
+"""
+
+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 OwnershipEntity(BaseModel):
+ """
+ An entity in the ownership structure.
+ """
+
+ name: str = Field(
+ description="Name of the entity (e.g., person, fund, holding company, trust)."
+ )
+ entity_type: str = Field(
+ description="Type: 'Individual', 'Institutional Investor', 'Holding Company', 'Venture Capital', "
+ "'Private Equity', 'Trust', 'Government Entity', 'Issuing Company'."
+ )
+ description: Optional[str] = Field(
+ None,
+ description="Additional details (e.g., 'Co-founder and CEO', 'Series B lead investor').",
+ )
+
+
+class OwnershipEdge(BaseModel):
+ """
+ An ownership or control relationship between entities.
+ """
+
+ source: str = Field(description="The owner/parent entity name.")
+ target: str = Field(description="The owned/subsidiary entity name.")
+ relationship_type: str = Field(
+ description="Type: 'Direct Ownership', 'Indirect Ownership', 'Beneficial Ownership', "
+ "'Voting Control', 'Board Seat', 'Parent-Subsidiary'."
+ )
+ ownership_percentage: Optional[str] = Field(
+ None,
+ description="Percentage ownership (e.g., '15.3%', '51%', 'Controlling interest').",
+ )
+ share_class: Optional[str] = Field(
+ None,
+ description="Class of shares (e.g., 'Class A', 'Class B (10x voting)', 'Preferred Series C').",
+ )
+ shares_held: Optional[str] = Field(
+ None,
+ description="Number of shares held (e.g., '45,000,000 shares').",
+ )
+ voting_power: Optional[str] = Field(
+ None,
+ description="Voting power percentage if different from ownership (e.g., '65% voting power').",
+ )
+ lock_up_period: Optional[str] = Field(
+ None,
+ description="Post-IPO lock-up period if applicable (e.g., '180 days').",
+ )
+
+
+# ==============================================================================
+# 2. Prompts
+# ==============================================================================
+
+_PROMPT = (
+ "You are a corporate governance analyst. Extract the ownership structure including shareholders, "
+ "holding companies, and their ownership relationships from this prospectus or proxy filing.\n\n"
+ "Rules:\n"
+ "- Identify all significant shareholders (5%+ beneficial owners).\n"
+ "- Extract ownership percentages and share classes.\n"
+ "- Map parent-subsidiary and holding company structures.\n"
+ "- Note dual-class voting structures and voting power differentials.\n"
+ "- Capture lock-up periods and post-IPO restrictions."
+)
+
+_NODE_PROMPT = (
+ "You are a corporate governance analyst. Extract all ownership entities (Nodes).\n\n"
+ "Extraction Rules:\n"
+ "- Identify individuals, institutional investors, holding companies, and trusts.\n"
+ "- Identify the issuing company itself.\n"
+ "- Classify each entity by type.\n"
+ "- DO NOT extract ownership relationships at this stage."
+)
+
+_EDGE_PROMPT = (
+ "You are a corporate governance analyst. Given the entities, extract ownership "
+ "and control relationships (Edges).\n\n"
+ "Extraction Rules:\n"
+ "- Connect owners to their holdings.\n"
+ "- Extract ownership percentages and share classes.\n"
+ "- Note voting power differentials.\n"
+ "- Capture lock-up periods.\n"
+ "- Only create edges between nodes that exist in the provided lists."
+)
+
+# ==============================================================================
+# 3. Template Class
+# ==============================================================================
+
+
+class ShareholderStructure(AutoGraph[OwnershipEntity, OwnershipEdge]):
+ """
+ Applicable to: S-1 Prospectuses, Proxy Statements (DEF 14A), Schedule 13D/G filings,
+ Annual Reports (Beneficial Ownership sections), IPO Filings.
+
+ Template for extracting and mapping corporate ownership structures. Enables
+ ultimate controller analysis, voting power assessment, and post-IPO lock-up tracking.
+
+ Example Usage:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> ownership = ShareholderStructure(llm_client=llm, embedder=embedder)
+ >>> prospectus = "The following table sets forth beneficial ownership: CEO holds 15.3%..."
+ >>> ownership.feed_text(prospectus)
+ >>> ownership.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 Shareholder Structure template.
+
+ Args:
+ llm_client (BaseChatModel): The LLM for ownership 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=OwnershipEntity,
+ edge_schema=OwnershipEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}--({x.relationship_type})-->{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 shareholder structure 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 relationships to retrieve. Default 3.
+ top_k_nodes_for_chat (int): Entities for chat context. Default 3.
+ top_k_edges_for_chat (int): Relationships for chat context. Default 3.
+ """
+
+ def node_label_extractor(node: OwnershipEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: OwnershipEdge) -> str:
+ pct = f" {edge.ownership_percentage}" if edge.ownership_percentage else ""
+ return f"{edge.relationship_type}{pct}"
+
+ 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/company_history_timeline.py b/hyperextract/templates/zh/finance/company_history_timeline.py
new file mode 100644
index 0000000..bc7f707
--- /dev/null
+++ b/hyperextract/templates/zh/finance/company_history_timeline.py
@@ -0,0 +1,195 @@
+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 CorporateEntity(BaseModel):
+ """
+ 参与公司历史里程碑的实体。
+ """
+
+ name: str = Field(
+ description="实体名称(例如公司名称、创始人、投资者、被收购方)。"
+ )
+ entity_type: str = Field(
+ description='类型:"公司"、"创始人"、"投资者"、"被收购方"、"合作伙伴"、"监管机构"。'
+ )
+ description: Optional[str] = Field(
+ None, description="角色或背景信息(例如'A 轮领投方'、'被收购子公司')。"
+ )
+
+
+class CorporateMilestoneEdge(BaseModel):
+ """
+ 带有时间上下文的公司里程碑事件。
+ """
+
+ source: str = Field(description="发起方实体名称。")
+ target: str = Field(description="受影响的实体或里程碑目标。")
+ event_type: str = Field(
+ description='类型:"创立"、"融资轮次"、"收购"、"产品发布"、'
+ '"IPO"、"战略转型"、"合作"、"扩张"、"重组"、"关键人才引进"。'
+ )
+ start_timestamp: Optional[str] = Field(
+ None,
+ description="里程碑日期(例如'2015-06'、'2018 年 3 月'、'2020')。",
+ )
+ end_timestamp: Optional[str] = Field(
+ None,
+ description="结束日期(如适用,例如收购完成日期)。",
+ )
+ description: Optional[str] = Field(
+ None,
+ description="里程碑详情(例如'红杉资本领投 5000 万美元 B 轮融资')。",
+ )
+ financial_details: Optional[str] = Field(
+ None,
+ description="财务条款(如有,例如估值、交易规模)。",
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是尽职调查分析师。从本招股说明书或公司历史文档中提取公司历史里程碑及相关实体。\n\n"
+ "规则:\n"
+ "- 识别创立事件、融资轮次、收购、战略转型和关键人才引进。\n"
+ "- 提取每个里程碑的具体日期或时间段。\n"
+ "- 捕捉财务细节(估值、交易规模)(如有提及)。\n"
+ "- 保持时间顺序的准确性。"
+)
+
+_NODE_PROMPT = (
+ "你是尽职调查分析师。提取公司历史中涉及的所有实体(节点)。\n\n"
+ "提取规则:\n"
+ "- 识别公司、创始人、投资者、被收购公司和合作伙伴。\n"
+ "- 按类型对每个实体进行分类。\n"
+ "- 此阶段不提取事件。"
+)
+
+_EDGE_PROMPT = (
+ "你是尽职调查分析师。在获得实体清单的基础上,提取带有日期的公司里程碑(边)。\n\n"
+ "提取规则:\n"
+ "- 通过里程碑事件连接实体。\n"
+ "- 提取具体日期或时间段。\n"
+ "- 捕捉财务细节(交易规模、估值)。\n"
+ "- 按类型对每个里程碑进行分类。\n"
+ "- 仅在提供的列表中存在的节点之间创建边。"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class CompanyHistoryTimeline(
+ AutoTemporalGraph[CorporateEntity, CorporateMilestoneEdge]
+):
+ """
+ 适用文档: S-1 招股说明书(业务部分)、公司简介页面、
+ 尽职调查报告、公司历史摘要、投资者演示材料。
+
+ 模板用于从招股说明书和公司历史中按时间顺序提取公司里程碑。支持尽职调查
+ 时间线构建和企业演进跟踪。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> history = CompanyHistoryTimeline(llm_client=llm, embedder=embedder)
+ >>> text = "公司于 2015 年由张三创立。2017 年完成 1000 万美元 A 轮融资..."
+ >>> history.feed_text(text)
+ >>> history.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=CorporateEntity,
+ edge_schema=CorporateMilestoneEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}|{x.event_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: CorporateEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: CorporateMilestoneEdge) -> str:
+ date = f" [{edge.start_timestamp}]" if edge.start_timestamp else ""
+ return f"{edge.event_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/proceeds_usage.py b/hyperextract/templates/zh/finance/proceeds_usage.py
new file mode 100644
index 0000000..7416af1
--- /dev/null
+++ b/hyperextract/templates/zh/finance/proceeds_usage.py
@@ -0,0 +1,138 @@
+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 AutoList
+
+# ==============================================================================
+# 1. Schema 定义
+# ==============================================================================
+
+
+class ProceedsItem(BaseModel):
+ """
+ 单项募集资金用途分配条目。
+ """
+
+ use_category: str = Field(
+ description="资金用途类别(例如'研发投入'、'偿还债务'、'营运资金'、"
+ "'收购'、'资本支出'、'一般企业用途')。"
+ )
+ project_name: Optional[str] = Field(
+ None,
+ description="具体项目或计划名称(例如'弗吉尼亚新数据中心'、'平台 2.0 开发')。",
+ )
+ allocated_amount: Optional[str] = Field(
+ None,
+ description="分配金额(例如'1.5 亿美元'、'约占净募集资金的 30%')。",
+ )
+ percentage_of_proceeds: Optional[str] = Field(
+ None,
+ description="占总募集资金的百分比(例如'30%'、'约三分之一')。",
+ )
+ timeline: Optional[str] = Field(
+ None,
+ description="预计资金使用时间表(例如'12-18 个月'、'2025-2026 财年')。",
+ )
+ description: Optional[str] = Field(
+ None,
+ description="资金具体使用方式的详细说明。",
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是 IPO 分析师。从本招股说明书或发行文件中提取所有募集资金用途分配信息。\n\n"
+ "规则:\n"
+ "- 提取每一项资金用途类别和具体项目。\n"
+ "- 捕捉分配金额和百分比。\n"
+ "- 提取资金使用时间表(如有说明)。\n"
+ "- 保留资金使用方式的详细描述。\n"
+ "- 将每项分配作为独立条目提取。\n\n"
+ "### 原文:\n"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class ProceedsUsage(AutoList[ProceedsItem]):
+ """
+ 适用文档: S-1 招股说明书(募集资金用途部分)、债券发行备忘录、
+ 二次发行招股说明书、SPAC 委托声明书。
+
+ 模板用于从招股说明书和发行文件中提取资金分配明细。每项分配作为独立条目捕捉,
+ 便于 IPO 后监控和资金用途跟踪。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> proceeds = ProceedsUsage(llm_client=llm, embedder=embedder)
+ >>> prospectus = "我们拟将约 1.5 亿美元用于研发,1 亿美元用于偿还债务..."
+ >>> proceeds.feed_text(prospectus)
+ >>> proceeds.show()
+ """
+
+ 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: AutoList 的其他参数。
+ """
+ super().__init__(
+ item_schema=ProceedsItem,
+ llm_client=llm_client,
+ embedder=embedder,
+ prompt=_PROMPT,
+ chunk_size=chunk_size,
+ chunk_overlap=chunk_overlap,
+ max_workers=max_workers,
+ verbose=verbose,
+ **kwargs,
+ )
+
+ def show(
+ self,
+ *,
+ top_k_for_search: int = 3,
+ top_k_for_chat: int = 3,
+ ) -> None:
+ """
+ 可视化募集资金用途列表。
+
+ Args:
+ top_k_for_search (int): 检索的条目数。默认 3。
+ top_k_for_chat (int): 对话上下文中的条目数。默认 3。
+ """
+
+ def label_extractor(item: ProceedsItem) -> str:
+ amount = f": {item.allocated_amount}" if item.allocated_amount else ""
+ return f"{item.use_category}{amount}"
+
+ super().show(
+ item_label_extractor=label_extractor,
+ top_k_for_search=top_k_for_search,
+ top_k_for_chat=top_k_for_chat,
+ )
diff --git a/hyperextract/templates/zh/finance/shareholder_structure.py b/hyperextract/templates/zh/finance/shareholder_structure.py
new file mode 100644
index 0000000..eabb863
--- /dev/null
+++ b/hyperextract/templates/zh/finance/shareholder_structure.py
@@ -0,0 +1,198 @@
+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 OwnershipEntity(BaseModel):
+ """
+ 股权结构中的实体。
+ """
+
+ name: str = Field(
+ description="实体名称(例如个人、基金、控股公司、信托)。"
+ )
+ entity_type: str = Field(
+ description='类型:"个人"、"机构投资者"、"控股公司"、"风险投资"、'
+ '"私募股权"、"信托"、"政府实体"、"发行公司"。'
+ )
+ description: Optional[str] = Field(
+ None,
+ description="附加信息(例如'联合创始人兼 CEO'、'B 轮领投机构')。",
+ )
+
+
+class OwnershipEdge(BaseModel):
+ """
+ 实体之间的持股或控制关系。
+ """
+
+ source: str = Field(description="持有方/母公司实体名称。")
+ target: str = Field(description="被持有方/子公司实体名称。")
+ relationship_type: str = Field(
+ description='类型:"直接持股"、"间接持股"、"实益所有权"、'
+ '"投票权控制"、"董事会席位"、"母子公司"。'
+ )
+ ownership_percentage: Optional[str] = Field(
+ None,
+ description="持股比例(例如'15.3%'、'51%'、'控股权')。",
+ )
+ share_class: Optional[str] = Field(
+ None,
+ description="股份类别(例如'A 类普通股'、'B 类(10 倍投票权)'、'C 轮优先股')。",
+ )
+ shares_held: Optional[str] = Field(
+ None,
+ description="持有股份数量(例如'45,000,000 股')。",
+ )
+ voting_power: Optional[str] = Field(
+ None,
+ description="投票权百分比(若与持股比例不同,例如'65% 投票权')。",
+ )
+ lock_up_period: Optional[str] = Field(
+ None,
+ description="IPO 后锁定期(如适用,例如'180 天')。",
+ )
+
+
+# ==============================================================================
+# 2. 提示词 (Prompts)
+# ==============================================================================
+
+_PROMPT = (
+ "你是公司治理分析师。从本招股说明书或委托声明文件中提取股权结构,包括股东、"
+ "控股公司及其持股关系。\n\n"
+ "规则:\n"
+ "- 识别所有重要股东(5% 以上实益所有人)。\n"
+ "- 提取持股比例和股份类别。\n"
+ "- 映射母子公司和控股公司结构。\n"
+ "- 注意双重股权结构和投票权差异。\n"
+ "- 捕捉锁定期和 IPO 后限制条款。"
+)
+
+_NODE_PROMPT = (
+ "你是公司治理分析师。提取所有股权实体(节点)。\n\n"
+ "提取规则:\n"
+ "- 识别个人、机构投资者、控股公司和信托。\n"
+ "- 识别发行公司本身。\n"
+ "- 按类型对每个实体进行分类。\n"
+ "- 此阶段不提取持股关系。"
+)
+
+_EDGE_PROMPT = (
+ "你是公司治理分析师。在获得实体清单的基础上,提取持股和控制关系(边)。\n\n"
+ "提取规则:\n"
+ "- 将持有方连接到其持有的资产。\n"
+ "- 提取持股比例和股份类别。\n"
+ "- 注意投票权差异。\n"
+ "- 捕捉锁定期。\n"
+ "- 仅在提供的列表中存在的节点之间创建边。"
+)
+
+# ==============================================================================
+# 3. 模板类
+# ==============================================================================
+
+
+class ShareholderStructure(AutoGraph[OwnershipEntity, OwnershipEdge]):
+ """
+ 适用文档: S-1 招股说明书、委托声明书(DEF 14A)、Schedule 13D/G 申报文件、
+ 年度报告(实益所有权部分)、IPO 申报文件。
+
+ 模板用于提取和映射公司股权结构。支持最终控制人分析、投票权评估和
+ IPO 后锁定期跟踪。
+
+ 使用示例:
+ >>> from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+ >>> llm = ChatOpenAI(model="gpt-4o")
+ >>> embedder = OpenAIEmbeddings()
+ >>> ownership = ShareholderStructure(llm_client=llm, embedder=embedder)
+ >>> prospectus = "下表列示实益所有权情况:CEO 持有 15.3%..."
+ >>> ownership.feed_text(prospectus)
+ >>> ownership.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: AutoGraph 的其他参数。
+ """
+ super().__init__(
+ node_schema=OwnershipEntity,
+ edge_schema=OwnershipEdge,
+ node_key_extractor=lambda x: x.name.strip().lower(),
+ edge_key_extractor=lambda x: (
+ f"{x.source.strip().lower()}--({x.relationship_type})-->{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: OwnershipEntity) -> str:
+ return f"{node.name} ({node.entity_type})"
+
+ def edge_label_extractor(edge: OwnershipEdge) -> str:
+ pct = f" {edge.ownership_percentage}" if edge.ownership_percentage else ""
+ return f"{edge.relationship_type}{pct}"
+
+ 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,
+ )