Overview
TheTemporalExtraction class extracts facts with explicit temporal information, capturing when events occurred, their duration, and temporal relationships between entities. This enables time-aware knowledge representation.
Class: TemporalExtraction
Constructor
The language model instance used for temporal extraction
Optional global configuration containing:
seed(int): Random seed for reproducibilitytemperature(float): LLM temperature parameter
Methods
batch_openie()
Extract temporal facts from multiple chunks using multi-threaded processing.Parameters
Dictionary of chunks to process. Each key is a chunk ID, and each value contains:
metadata(dict): Temporal metadata for constructing the passage- Other ChunkInfo fields (see OpenIE documentation)
Returns
A dictionary ofTemporalRawOutput objects:
Temporal extraction results containing:
chunk_id(str): The chunk identifierverbatim(str): Original passage textfacts(List[dict]): List of temporal facts, each containing:subject(str): The entity the fact is aboutpredicate(str): The relationship or actionobject(str): The target entity or valuetemporal_qualifier(str): Time information (date, duration, or temporal relation)
response(str): Raw LLM responsemetadata(dict): Token usage and processing information
Example Usage
Extraction Process
Temporal Fact Structure
Each extracted fact contains four components:- Subject: The entity the fact is about
- Predicate: The action, relationship, or state
- Object: The target entity, value, or description
- Temporal Qualifier: Time information in various formats:
- Specific dates: “2024-01-15”, “January 2024”
- Date ranges: “from 2020 to 2023”, “2020-2023”
- Relative times: “last week”, “two years ago”
- Durations: “for 3 months”, “since 2020”
- Temporal relations: “before graduation”, “after the meeting”
Prompt Template
Uses thetemporal_extraction prompt template which instructs the LLM to:
- Identify temporal expressions in the text
- Associate time information with facts
- Normalize temporal references when possible
- Handle various temporal formats and granularities
Passage Construction
Usesmake_chunk_content("temporal", metadata) to format input:
- Structures temporal context appropriately
- Preserves timestamp information from metadata
- Formats content for temporal extraction
Temporal Qualifier Types
Absolute Time
- Specific dates: “2024-03-15”
- Specific times: “2024-03-15 14:30:00”
- Year-month: “March 2024”
- Year only: “2024”
Relative Time
- Past references: “yesterday”, “last week”, “2 days ago”
- Future references: “tomorrow”, “next month”, “in 3 weeks”
- Current references: “today”, “this week”, “currently”
Duration
- Explicit duration: “for 5 years”, “during 3 months”
- Open-ended: “since 2020”, “until now”
- Bounded: “from 2020 to 2023”, “between Jan and Mar”
Temporal Relations
- Sequential: “before X”, “after Y”, “during Z”
- Simultaneous: “while X”, “at the same time as Y”
- Frequency: “every Monday”, “twice a year”
Performance Considerations
- Parallel processing: Default
max_workers=8for ThreadPoolExecutor - Single-stage extraction: Extracts complete temporal facts in one pass
- JSON mode: Structured output for reliable parsing
- Progress tracking: Real-time token usage and cache hit metrics
- Efficient threading: Balances concurrency with API rate limits
Error Handling
- Automatic JSON repair for truncated responses
- Graceful handling of malformed temporal expressions
- Returns empty fact lists on extraction failure
- Preserves error information in metadata
- Logs warnings for debugging
- Replaces null values with empty strings
Use Cases
Time-Aware Knowledge Graphs
Event Timeline Construction
Temporal Question Answering
Historical Analysis
Integration with Memory Systems
Temporal extraction enables:- Episodic memory: Link events to specific times
- Semantic memory: Track knowledge validity periods
- Autobiographical memory: Create personal timelines
- Context-aware retrieval: Filter by temporal constraints
- Memory decay modeling: Weight facts by recency