agentii-models 0.1.0__py3-none-any.whl

agentii_models/__init__.py

@@ -0,0 +1,60 @@
+"""agentii-models: Shared Pydantic v2 data models for Agentii and Agenzym."""
+
+# Instruments
+from .instruments import Instrument, EquityInstrument, OptionInstrument
+
+# Stocks
+from .stocks import StockTick, StockQuote, StockBar, StockSnapshot
+
+# Options
+from .options import Greeks, OptionQuote, OptionBar, OptionsChain
+
+# Analytics
+from .analytics import IVPoint, VolatilitySurface, OptionPricingResult, PayoffDiagram
+
+# Portfolio
+from .portfolio import StockPosition, OptionPosition, Portfolio
+
+# Orders
+from .orders import Order, Trade
+
+# Biotech
+from .biotech import CatalystEvent, FDADecision
+
+# Providers
+from .providers import MarketDataProvider, DataRouter
+
+__all__ = [
+    # Instruments
+    "Instrument",
+    "EquityInstrument",
+    "OptionInstrument",
+    # Stocks
+    "StockTick",
+    "StockQuote",
+    "StockBar",
+    "StockSnapshot",
+    # Options
+    "Greeks",
+    "OptionQuote",
+    "OptionBar",
+    "OptionsChain",
+    # Analytics
+    "IVPoint",
+    "VolatilitySurface",
+    "OptionPricingResult",
+    "PayoffDiagram",
+    # Portfolio
+    "StockPosition",
+    "OptionPosition",
+    "Portfolio",
+    # Orders
+    "Order",
+    "Trade",
+    # Biotech
+    "CatalystEvent",
+    "FDADecision",
+    # Providers
+    "MarketDataProvider",
+    "DataRouter",
+]

agentii_models/_base.py

@@ -0,0 +1,39 @@
+"""Base market data model shared by all market data types."""
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from .types import ProviderName, Symbol, Timestamp
+
+
+class BaseMarketData(BaseModel):
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+    )
+
+    symbol: Symbol
+    provider: ProviderName
+    timestamp_ns: Timestamp | None = None
+
+    @field_validator("symbol", mode="before")
+    @classmethod
+    def _validate_symbol(cls, v: str) -> str:
+        v = str(v).strip().upper()
+        if not v:
+            raise ValueError("symbol must be non-empty")
+        return v
+
+    @field_validator("provider", mode="before")
+    @classmethod
+    def _validate_provider(cls, v: str) -> str:
+        v = str(v).strip()
+        if not v:
+            raise ValueError("provider must be non-empty")
+        return v
+
+    @field_validator("timestamp_ns")
+    @classmethod
+    def _validate_timestamp_ns(cls, v: int | None) -> int | None:
+        if v is not None and v < 0:
+            raise ValueError("timestamp_ns must be non-negative")
+        return v

agentii_models/analytics.py

@@ -0,0 +1,87 @@
+"""Analytics models: IVPoint, VolatilitySurface, OptionPricingResult, PayoffDiagram.
+
+Structural reference: VeighNa vnpy_optionmaster/pricing/black_scholes.py
+- calculate_greeks(s, k, r, t, v, cp) → (price, delta, gamma, theta, vega)
+"""
+
+from datetime import date, datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from .enums import OptionType, PricingModel
+from .types import Price, ProviderName, Symbol
+
+
+class IVPoint(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    underlying_symbol: Symbol
+    strike: Price
+    expiration: date
+    option_type: OptionType
+    implied_volatility: float
+    timestamp: datetime
+    provider: ProviderName
+
+
+class VolatilitySurface(BaseModel):
+    """3D IV surface: strike × expiry × IV."""
+
+    model_config = ConfigDict(frozen=True)
+
+    underlying_symbol: Symbol
+    snapshot_time: datetime
+    provider: ProviderName
+    points: list[IVPoint]
+
+    def iv_at(self, strike: float, expiration: date) -> float | None:
+        for p in self.points:
+            if p.strike == strike and p.expiration == expiration:
+                return p.implied_volatility
+        return None
+
+    def smile(self, expiration: date) -> list[IVPoint]:
+        return sorted(
+            [p for p in self.points if p.expiration == expiration],
+            key=lambda p: p.strike,
+        )
+
+    def term_structure(self, strike: float) -> list[IVPoint]:
+        return sorted(
+            [p for p in self.points if p.strike == strike],
+            key=lambda p: p.expiration,
+        )
+
+
+class OptionPricingResult(BaseModel):
+    """Output of a pricing model calculation."""
+
+    model_config = ConfigDict(frozen=True)
+
+    model: PricingModel
+    theoretical_price: Price
+    delta: float
+    gamma: float
+    theta: float
+    vega: float
+    rho: float
+    implied_volatility: float
+    underlying_price: Price
+    strike: Price
+    risk_free_rate: float
+    time_to_expiry: float
+    option_type: OptionType
+
+
+class PayoffDiagram(BaseModel):
+    """Strategy payoff visualization data."""
+
+    model_config = ConfigDict(frozen=True)
+
+    strategy_name: str
+    underlying_symbol: Symbol
+    price_points: list[float]
+    payoff_values: list[float]
+    breakeven_points: list[float]
+    max_profit: float | None = None
+    max_loss: float | None = None

agentii_models/biotech.py

@@ -0,0 +1,59 @@
+"""Biotech-specific models: CatalystEvent, FDADecision."""
+
+from datetime import date, datetime
+
+from pydantic import BaseModel, ConfigDict, computed_field, field_validator
+
+from .enums import CatalystType, FDADecisionOutcome
+from .types import Price, Symbol
+
+
+class CatalystEvent(BaseModel):
+    event_id: str
+    symbol: Symbol
+    drug_name: str
+    indication: str
+    catalyst_type: CatalystType
+    event_date: date | None = None
+    date_is_estimated: bool = False
+    approval_probability: float | None = None
+    expected_move_pct: float | None = None
+    historical_precedent: str | None = None
+    source: str | None = None
+    notes: str | None = None
+    created_at: datetime
+    updated_at: datetime | None = None
+
+    @field_validator("approval_probability")
+    @classmethod
+    def _validate_probability(cls, v: float | None) -> float | None:
+        if v is not None and not (0.0 <= v <= 1.0):
+            raise ValueError("approval_probability must be between 0.0 and 1.0")
+        return v
+
+
+class FDADecision(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    decision_id: str
+    symbol: Symbol
+    drug_name: str
+    indication: str
+    outcome: FDADecisionOutcome
+    decision_date: date
+    catalyst_event_id: str | None = None
+    price_before: Price | None = None
+    price_after: Price | None = None
+    review_type: str | None = None
+    label_expansion: bool = False
+    advisory_committee_vote: str | None = None
+    crl_reasons: list[str] | None = None
+    source_url: str | None = None
+    decision_letter_url: str | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def actual_move_pct(self) -> float | None:
+        if self.price_before is not None and self.price_after is not None and self.price_before != 0:
+            return (self.price_after - self.price_before) / self.price_before * 100
+        return None

agentii_models/enums.py

@@ -0,0 +1,132 @@
+"""Shared enums for agentii-models."""
+
+from enum import Enum
+
+
+class AssetClass(str, Enum):
+    EQUITY = "equity"
+    OPTION = "option"
+    ETF = "etf"
+
+
+class Exchange(str, Enum):
+    NYSE = "NYSE"
+    NASDAQ = "NASDAQ"
+    CBOE = "CBOE"
+    AMEX = "AMEX"
+    ARCA = "ARCA"
+    BATS = "BATS"
+    IEX = "IEX"
+    OTC = "OTC"
+    OPRA = "OPRA"
+
+
+class OptionType(str, Enum):
+    CALL = "call"
+    PUT = "put"
+
+
+class OptionStyle(str, Enum):
+    AMERICAN = "american"
+    EUROPEAN = "european"
+
+
+class BarTimeframe(str, Enum):
+    TICK = "tick"
+    SEC_1 = "1s"
+    MIN_1 = "1min"
+    MIN_5 = "5min"
+    MIN_15 = "15min"
+    MIN_30 = "30min"
+    HOUR_1 = "1h"
+    HOUR_4 = "4h"
+    DAY_1 = "1d"
+    WEEK_1 = "1w"
+    MONTH_1 = "1mo"
+
+
+class MarketSession(str, Enum):
+    PRE_MARKET = "pre"
+    REGULAR = "regular"
+    POST_MARKET = "post"
+
+
+class OrderSide(str, Enum):
+    BUY = "buy"
+    SELL = "sell"
+
+
+class OrderType(str, Enum):
+    MARKET = "market"
+    LIMIT = "limit"
+    STOP = "stop"
+    STOP_LIMIT = "stop_limit"
+    TRAILING_STOP = "trailing_stop"
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    ACCEPTED = "accepted"
+    PARTIALLY_FILLED = "partially_filled"
+    FILLED = "filled"
+    CANCELLED = "cancelled"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+
+
+class TimeInForce(str, Enum):
+    DAY = "day"
+    GTC = "gtc"
+    IOC = "ioc"
+    FOK = "fok"
+    OPG = "opg"
+    CLS = "cls"
+
+
+class CatalystType(str, Enum):
+    PDUFA = "pdufa"
+    ADCOM = "adcom"
+    PHASE_1 = "phase_1"
+    PHASE_2 = "phase_2"
+    PHASE_3 = "phase_3"
+    NDA_FILING = "nda_filing"
+    BLA_FILING = "bla_filing"
+    CONFERENCE = "conference"
+    EARNINGS = "earnings"
+    DATA_READOUT = "data_readout"
+    PRIORITY_REVIEW = "priority_review"
+    BREAKTHROUGH = "breakthrough"
+
+
+class FDADecisionOutcome(str, Enum):
+    APPROVED = "approved"
+    CRL = "crl"
+    TENTATIVE_APPROVAL = "tentative_approval"
+    REFUSED_TO_FILE = "refused_to_file"
+    WITHDRAWN = "withdrawn"
+    PENDING = "pending"
+
+
+class DataFeed(str, Enum):
+    """Alpaca data feed source. Affects data quality, latency, and cost."""
+
+    SIP = "sip"
+    IEX = "iex"
+    OTC = "otc"
+    BOATS = "boats"
+
+
+class Adjustment(str, Enum):
+    """Price adjustment type for historical bars.
+    Critical for 10-year historical data accuracy."""
+
+    RAW = "raw"
+    SPLIT = "split"
+    DIVIDEND = "dividend"
+    ALL = "all"
+
+
+class PricingModel(str, Enum):
+    BLACK_SCHOLES = "black_scholes"
+    BLACK_76 = "black_76"
+    BINOMIAL_TREE = "binomial_tree"

agentii_models/instruments.py

@@ -0,0 +1,85 @@
+"""Instrument hierarchy: Instrument, EquityInstrument, OptionInstrument."""
+
+import re
+from datetime import date
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, computed_field, field_validator
+
+from .enums import AssetClass, Exchange, OptionType, OptionStyle
+from .types import Symbol
+
+# OCC symbol: 1-6 uppercase letters (right-padded with spaces to 6), 6-digit date YYMMDD, C or P, 8-digit strike
+_OCC_PATTERN = re.compile(r"^[A-Z]{1,6}\s*\d{6}[CP]\d{8}$")
+
+
+class Instrument(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    symbol: Symbol
+    asset_class: AssetClass
+    exchange: Exchange
+    name: str
+    currency: str = "USD"
+
+
+class EquityInstrument(Instrument):
+    asset_class: Literal[AssetClass.EQUITY] = AssetClass.EQUITY
+
+    sector: str | None = None
+    industry: str | None = None
+    market_cap: float | None = None
+    has_fda_pipeline: bool = False
+    clinical_stage: str | None = None
+    is_biotech: bool = False
+
+
+class OptionInstrument(Instrument):
+    asset_class: Literal[AssetClass.OPTION] = AssetClass.OPTION
+
+    underlying_symbol: Symbol
+    strike_price: float
+    expiration_date: date
+    option_type: OptionType
+    option_style: OptionStyle = OptionStyle.AMERICAN
+    contract_size: int = 100
+
+    @field_validator("symbol")
+    @classmethod
+    def _validate_occ_symbol(cls, v: str) -> str:
+        if not _OCC_PATTERN.match(v):
+            raise ValueError(
+                f"Invalid OCC symbol format: '{v}'. "
+                "Expected: 1-6 uppercase letters + 6-digit date YYMMDD + C/P + 8-digit strike"
+            )
+        return v
+
+    @field_validator("strike_price")
+    @classmethod
+    def _validate_strike(cls, v: float) -> float:
+        if v <= 0:
+            raise ValueError("strike_price must be positive")
+        return v
+
+    @field_validator("contract_size")
+    @classmethod
+    def _validate_contract_size(cls, v: int) -> int:
+        if v <= 0:
+            raise ValueError("contract_size must be positive")
+        return v
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def days_to_expiry(self) -> int:
+        return (self.expiration_date - date.today()).days
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def is_expired(self) -> bool:
+        return self.expiration_date < date.today()
+
+    def moneyness(self, underlying_price: float) -> float:
+        """Return strike / underlying price ratio."""
+        if underlying_price <= 0:
+            raise ValueError("underlying_price must be positive")
+        return self.strike_price / underlying_price

agentii_models/options.py

@@ -0,0 +1,245 @@
+"""Options models: Greeks, OptionQuote, OptionBar, OptionsChain.
+
+Provider field mapping (Alpaca Snapshot → agentii-models):
+    latestQuote.bp → bid, latestQuote.bs → bid_size,
+    latestQuote.ap → ask, latestQuote.as → ask_size,
+    latestTrade.p → last_trade_price, latestTrade.s → last_trade_size,
+    greeks.delta → delta, greeks.gamma → gamma, greeks.theta → theta,
+    greeks.vega → vega, greeks.rho → rho,
+    impliedVolatility → implied_volatility, openInterest → open_interest
+
+Provider field mapping (Polygon Snapshot → agentii-models):
+    last_quote.bid → bid, last_quote.ask → ask,
+    last_trade.price → last_trade_price, last_trade.size → last_trade_size,
+    greeks.delta → delta, greeks.gamma → gamma, greeks.theta → theta,
+    greeks.vega → vega, implied_volatility → implied_volatility,
+    open_interest → open_interest
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, computed_field, field_validator
+
+from ._base import BaseMarketData
+from .enums import BarTimeframe, OptionType
+from .types import Price, ProviderName, Symbol, Volume
+
+_INTERDAY_TIMEFRAMES = frozenset({BarTimeframe.DAY_1, BarTimeframe.WEEK_1, BarTimeframe.MONTH_1})
+
+
+class Greeks(BaseModel):
+    """Position-level Greeks container for aggregation.
+    Used by OptionPosition.position_greeks and Portfolio.net_greeks.
+    NOT embedded on OptionQuote (those are flat fields)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    delta: float = 0.0
+    gamma: float = 0.0
+    theta: float = 0.0
+    vega: float = 0.0
+    rho: float = 0.0
+    implied_volatility: float = 0.0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def is_complete(self) -> bool:
+        return all(
+            v != 0.0
+            for v in (self.delta, self.gamma, self.theta, self.vega, self.rho, self.implied_volatility)
+        )
+
+
+class OptionQuote(BaseMarketData):
+    """Real-time option contract quote with flat Greeks. Full OpenBB 35+ field set — all Optional."""
+
+    # Identity
+    underlying_symbol: Symbol
+    contract_symbol: Symbol
+    expiration: date
+    dte: int | None = None
+    strike: Price
+    option_type: OptionType
+    contract_size: int = 100
+
+    # Pricing — bid/ask
+    bid: Price | None = None
+    bid_size: Volume | None = None
+    bid_exchange: str | None = None
+    bid_time: datetime | None = None
+    ask: Price | None = None
+    ask_size: Volume | None = None
+    ask_exchange: str | None = None
+    ask_time: datetime | None = None
+    mark: Price | None = None
+
+    # OHLC
+    open: Price | None = None
+    high: Price | None = None
+    low: Price | None = None
+    close: Price | None = None
+    open_bid: Price | None = None
+    open_ask: Price | None = None
+    bid_high: Price | None = None
+    ask_high: Price | None = None
+    bid_low: Price | None = None
+    ask_low: Price | None = None
+    close_size: Volume | None = None
+    close_time: datetime | None = None
+    close_bid: Price | None = None
+    close_bid_size: Volume | None = None
+    close_bid_time: datetime | None = None
+    close_ask: Price | None = None
+    close_ask_size: Volume | None = None
+    close_ask_time: datetime | None = None
+
+    # Trade
+    last_trade_price: Price | None = None
+    last_trade_size: Volume | None = None
+    last_trade_time: datetime | None = None
+    tick: str | None = None
+
+    # Change
+    prev_close: Price | None = None
+    change: float | None = None
+    change_percent: float | None = None
+
+    # Volume / OI
+    volume: Volume | None = None
+    open_interest: int | None = None
+
+    # Greeks — FLAT on quote (not nested)
+    implied_volatility: float | None = None
+    delta: float | None = None
+    gamma: float | None = None
+    theta: float | None = None
+    vega: float | None = None
+    rho: float | None = None
+    theoretical_price: Price | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def mid_price(self) -> float | None:
+        if self.bid is not None and self.ask is not None:
+            return (self.bid + self.ask) / 2
+        return None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def spread(self) -> float | None:
+        if self.bid is not None and self.ask is not None:
+            return self.ask - self.bid
+        return None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def has_greeks(self) -> bool:
+        return all(
+            v is not None
+            for v in (self.delta, self.gamma, self.theta, self.vega, self.rho, self.implied_volatility)
+        )
+
+
+class OptionBar(BaseMarketData):
+    """OHLCV bar for a single option contract."""
+
+    contract_symbol: Symbol
+    underlying_symbol: Symbol
+    date: date | datetime
+    timeframe: BarTimeframe
+    open: Price
+    high: Price
+    low: Price
+    close: Price
+    volume: Volume | None = None
+    open_interest: int | None = None
+    vwap: Price | None = None
+    trade_count: int | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def is_intraday(self) -> bool:
+        return self.timeframe not in _INTERDAY_TIMEFRAMES
+
+
+class OptionsChain(BaseModel):
+    """Full chain snapshot for a single underlying.
+    Stores contracts as list[OptionQuote] (per-contract objects)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    underlying_symbol: Symbol
+    snapshot_time: datetime
+    provider: ProviderName
+    contracts: list[OptionQuote]
+
+    def filter(
+        self,
+        option_type: OptionType | None = None,
+        expiration: date | None = None,
+        min_strike: float | None = None,
+        max_strike: float | None = None,
+        min_volume: int | None = None,
+        min_open_interest: int | None = None,
+    ) -> list[OptionQuote]:
+        result = self.contracts
+        if option_type is not None:
+            result = [c for c in result if c.option_type == option_type]
+        if expiration is not None:
+            result = [c for c in result if c.expiration == expiration]
+        if min_strike is not None:
+            result = [c for c in result if c.strike >= min_strike]
+        if max_strike is not None:
+            result = [c for c in result if c.strike <= max_strike]
+        if min_volume is not None:
+            result = [c for c in result if c.volume is not None and c.volume >= min_volume]
+        if min_open_interest is not None:
+            result = [c for c in result if c.open_interest is not None and c.open_interest >= min_open_interest]
+        return result
+
+    def by_expiry(self, expiration: date) -> list[OptionQuote]:
+        return [c for c in self.contracts if c.expiration == expiration]
+
+    def expirations(self) -> list[date]:
+        return sorted({c.expiration for c in self.contracts})
+
+    def strikes(self, expiration: date | None = None) -> list[float]:
+        contracts = self.contracts if expiration is None else self.by_expiry(expiration)
+        return sorted({c.strike for c in contracts})
+
+    def atm_strike(self, underlying_price: float) -> float | None:
+        all_strikes = self.strikes()
+        if not all_strikes:
+            return None
+        return min(all_strikes, key=lambda s: abs(s - underlying_price))
+
+    def near_term_expiry(self) -> date | None:
+        today = date.today()
+        future = [e for e in self.expirations() if e >= today]
+        return future[0] if future else None
+
+    def to_dataframe(self) -> Any:
+        """Convert contracts to a pandas DataFrame. Requires pandas."""
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError("pandas is required for to_dataframe(). Install with: pip install pandas")
+        return pd.DataFrame([c.model_dump() for c in self.contracts])
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def call_count(self) -> int:
+        return sum(1 for c in self.contracts if c.option_type == OptionType.CALL)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def put_count(self) -> int:
+        return sum(1 for c in self.contracts if c.option_type == OptionType.PUT)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_contracts(self) -> int:
+        return len(self.contracts)