feat: competitive intelligence & historical pattern matching layer

services/shared/schemas.py

@@ -15,6 +15,7 @@ class DocumentType(str, Enum):
     FILING = "filing"
     TRANSCRIPT = "transcript"
     PRESS_RELEASE = "press_release"
+    MACRO_EVENT = "macro_event"
 
 
 class SourceType(str, Enum):
@@ -71,6 +72,37 @@ class TrendWindow(str, Enum):
     NINETY_DAY = "90d"
 
 
+class ImpactType(str, Enum):
+    SUPPLY_DISRUPTION = "supply_disruption"
+    DEMAND_SHIFT = "demand_shift"
+    COST_INCREASE = "cost_increase"
+    REGULATORY_PRESSURE = "regulatory_pressure"
+    CURRENCY_IMPACT = "currency_impact"
+    COMMODITY_SHOCK = "commodity_shock"
+    TRADE_BARRIER = "trade_barrier"
+    GEOPOLITICAL_RISK = "geopolitical_risk"
+
+
+class SeverityLevel(str, Enum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class MarketPositionTier(str, Enum):
+    GLOBAL_LEADER = "global_leader"
+    MULTINATIONAL = "multinational"
+    REGIONAL = "regional"
+    DOMESTIC = "domestic"
+
+
+class EstimatedDuration(str, Enum):
+    SHORT_TERM = "short_term"
+    MEDIUM_TERM = "medium_term"
+    LONG_TERM = "long_term"
+
+
 # --- Document Intelligence ---
 
 class CompanyImpact(BaseModel):
@@ -182,6 +214,63 @@ class Recommendation(BaseModel):
     generated_at: datetime = Field(default_factory=datetime.utcnow)
 
 
+# --- Global News Interpolation ---
+
+class GlobalEventSchema(BaseModel):
+    event_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    event_types: List[ImpactType] = Field(default_factory=list)
+    severity: SeverityLevel = SeverityLevel.LOW
+    affected_regions: List[str] = Field(default_factory=list)
+    affected_sectors: List[str] = Field(default_factory=list)
+    affected_commodities: List[str] = Field(default_factory=list)
+    summary: str = ""
+    key_facts: List[str] = Field(default_factory=list)
+    estimated_duration: EstimatedDuration = EstimatedDuration.SHORT_TERM
+    confidence: float = Field(ge=0, le=1, default=0.5)
+    source_document_id: str = ""
+    model_metadata: ModelMetadata = Field(default_factory=ModelMetadata)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class MacroImpactRecordSchema(BaseModel):
+    event_id: str = ""
+    company_id: str = ""
+    ticker: str = ""
+    macro_impact_score: float = Field(ge=0, le=1, default=0.0)
+    impact_direction: str = "neutral"
+    contributing_factors: List[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0, le=1, default=0.5)
+    computed_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class ExposureProfileSchema(BaseModel):
+    company_id: str = ""
+    geographic_revenue_mix: dict[str, float] = Field(default_factory=dict)
+    supply_chain_regions: List[str] = Field(default_factory=list)
+    key_input_commodities: List[str] = Field(default_factory=list)
+    regulatory_jurisdictions: List[str] = Field(default_factory=list)
+    market_position_tier: MarketPositionTier = MarketPositionTier.REGIONAL
+    export_dependency_pct: float = Field(ge=0, le=1, default=0.0)
+    source: str = "manual"
+    confidence: float = Field(ge=0, le=1, default=1.0)
+    version: int = 1
+    active: bool = True
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class TrendProjectionSchema(BaseModel):
+    trend_window_id: str = ""
+    projected_direction: TrendDirection = TrendDirection.NEUTRAL
+    projected_strength: float = Field(ge=0, le=1, default=0.5)
+    projected_confidence: float = Field(ge=0, le=1, default=0.5)
+    projection_horizon: str = "7d"
+    driving_factors: List[str] = Field(default_factory=list)
+    macro_contribution_pct: float = Field(ge=0, le=1, default=0.0)
+    diverges_from_current: bool = False
+    computed_at: datetime = Field(default_factory=datetime.utcnow)
+
+
 # --- Document Metadata ---
 
 class StorageRefs(BaseModel):
@@ -204,3 +293,73 @@ class DocumentMetadata(BaseModel):
     language: str = "en"
     content_hash: str = ""
     storage_refs: StorageRefs = Field(default_factory=StorageRefs)
+
+
+# --- Competitive Intelligence & Historical Patterns ---
+
+
+class RelationshipType(str, Enum):
+    DIRECT_RIVAL = "direct_rival"
+    SAME_SECTOR = "same_sector"
+    OVERLAPPING_PRODUCTS = "overlapping_products"
+    SUPPLY_CHAIN_ADJACENT = "supply_chain_adjacent"
+
+
+class CatalystTier(str, Enum):
+    MAJOR_CORPORATE_DECISION = "major_corporate_decision"
+    ROUTINE_SIGNAL = "routine_signal"
+
+
+# Major corporate decision catalyst types (Req 11.1)
+MAJOR_DECISION_CATALYSTS: frozenset[str] = frozenset({
+    "m_and_a",
+    "legal",
+    "restructuring",
+    "leadership_change",
+    "strategic_pivot",
+    "buyback",
+    "dividend_change",
+})
+
+
+class CompetitorRelationshipSchema(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    company_a_id: str = ""
+    company_b_id: str = ""
+    relationship_type: RelationshipType = RelationshipType.DIRECT_RIVAL
+    strength: float = Field(ge=0, le=1, default=0.5)
+    bidirectional: bool = True
+    source: str = "manual"
+    active: bool = True
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class CompetitiveSignalRecordSchema(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    source_document_id: str = ""
+    source_ticker: str = ""
+    target_ticker: str = ""
+    catalyst_type: str = ""
+    pattern_confidence: float = Field(ge=0, le=1, default=0.0)
+    signal_direction: str = "neutral"
+    signal_strength: float = Field(ge=0, le=1, default=0.0)
+    relationship_strength: float = Field(ge=0, le=1, default=0.0)
+    computed_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+class HistoricalPatternSchema(BaseModel):
+    source_ticker: str = ""
+    target_ticker: str = ""
+    catalyst_type: str = ""
+    time_horizon: str = "7d"
+    sample_count: int = 0
+    bullish_pct: float = Field(ge=0, le=1, default=0.0)
+    bearish_pct: float = Field(ge=0, le=1, default=0.0)
+    avg_strength: float = Field(ge=0, le=1, default=0.0)
+    avg_time_to_resolution: float = 0.0
+    pattern_confidence: float = Field(ge=0, le=1, default=0.0)
+    data_start: Optional[datetime] = None
+    data_end: Optional[datetime] = None
+    tier: CatalystTier = CatalystTier.ROUTINE_SIGNAL
+    insufficient_data: bool = False