avanza-mcp 1.0.0__py3-none-any.whl

avanza_mcp/models/fund.py

@@ -0,0 +1,246 @@
+"""Fund-related Pydantic models."""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# Standard model config for all models
+MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,
+    str_strip_whitespace=True,
+    validate_assignment=True,
+    extra="allow",  # Don't fail on extra fields from API
+)
+
+
+class FundPerformance(BaseModel):
+    """Fund performance metrics over various time periods."""
+
+    model_config = MODEL_CONFIG
+
+    today: Decimal | None = Field(None, description="Performance today (%)")
+    one_week: Decimal | None = Field(None, alias="oneWeek", description="1 week return (%)")
+    one_month: Decimal | None = Field(
+        None, alias="oneMonth", description="1 month return (%)"
+    )
+    three_months: Decimal | None = Field(
+        None, alias="threeMonths", description="3 month return (%)"
+    )
+    this_year: Decimal | None = Field(
+        None, alias="thisYear", description="Year to date return (%)"
+    )
+    one_year: Decimal | None = Field(None, alias="oneYear", description="1 year return (%)")
+    three_years: Decimal | None = Field(
+        None, alias="threeYears", description="3 year return (%)"
+    )
+    five_years: Decimal | None = Field(
+        None, alias="fiveYears", description="5 year return (%)"
+    )
+    ten_years: Decimal | None = Field(
+        None, alias="tenYears", description="10 year return (%)"
+    )
+
+
+class FundFee(BaseModel):
+    """Fund fee information."""
+
+    model_config = MODEL_CONFIG
+
+    ongoing_charges: Decimal | None = Field(
+        None, alias="ongoingCharges", description="Ongoing charges (%)"
+    )
+    entry_charge: Decimal | None = Field(
+        None, alias="entryCharge", description="Entry fee (%)"
+    )
+    exit_charge: Decimal | None = Field(None, alias="exitCharge", description="Exit fee (%)")
+
+
+class ChartDataPoint(BaseModel):
+    """Data point for portfolio allocation charts."""
+
+    model_config = MODEL_CONFIG
+
+    name: str | None = None
+    y: float | None = None
+
+
+class FundInfo(BaseModel):
+    """Detailed fund information."""
+
+    model_config = MODEL_CONFIG
+
+    # Basic info
+    id: str | None = Field(None, description="Fund ID")
+    name: str = Field(..., description="Fund name")
+    isin: str | None = Field(None, description="ISIN identifier")
+    description: str | None = Field(None, description="Fund description")
+
+    # Price and NAV
+    nav: Decimal | None = Field(None, description="Net Asset Value")
+    nav_date: date | None = Field(None, alias="navDate", description="NAV date")
+    currency: str = Field(default="SEK", description="Fund currency")
+
+    # Performance
+    development: FundPerformance | None = Field(
+        None, description="Performance over time periods"
+    )
+    change_since_three_months: Decimal | None = Field(
+        None, alias="changeSinceThreeMonths", description="3 month change (%)"
+    )
+    change_since_one_year: Decimal | None = Field(
+        None, alias="changeSinceOneYear", description="1 year change (%)"
+    )
+
+    # Risk metrics
+    risk: int | None = Field(None, description="Risk level (1-7)")
+    risk_level: str | None = Field(None, alias="riskLevel", description="Risk category")
+    rating: int | None = Field(None, description="Rating (e.g., Morningstar)")
+    standard_deviation: Decimal | None = Field(
+        None, alias="standardDeviation", description="Standard deviation"
+    )
+    sharpe_ratio: Decimal | None = Field(
+        None, alias="sharpeRatio", description="Sharpe ratio"
+    )
+
+    # Fees
+    fee: FundFee | None = Field(None, description="Fee information")
+
+    # Fund characteristics
+    fund_company: str | None = Field(None, alias="fundCompany", description="Fund company")
+    fund_type_name: str | None = Field(
+        None, alias="fundTypeName", description="Fund type"
+    )
+    category: str | None = Field(None, description="Fund category")
+    aum: Decimal | None = Field(
+        None, alias="capital", description="Assets under management"
+    )
+    start_date: date | None = Field(None, alias="startDate", description="Fund inception date")
+
+    # Trading
+    tradeable: bool = Field(default=True, description="Whether fund is tradeable")
+    buy_fee: Decimal | None = Field(None, alias="buyFee", description="Buy fee (%)")
+    sell_fee: Decimal | None = Field(None, alias="sellFee", description="Sell fee (%)")
+    prospectus: str | None = Field(None, description="Prospectus URL")
+
+    # Portfolio allocations
+    country_chart_data: list[ChartDataPoint] = Field(
+        default_factory=list,
+        alias="countryChartData",
+        description="Geographic allocation by country",
+    )
+    sector_chart_data: list[ChartDataPoint] = Field(
+        default_factory=list,
+        alias="sectorChartData",
+        description="Sector allocation",
+    )
+    holding_chart_data: list[ChartDataPoint] = Field(
+        default_factory=list,
+        alias="holdingChartData",
+        description="Top holdings",
+    )
+    portfolio_date: date | None = Field(
+        None, alias="portfolioDate", description="Date of portfolio data"
+    )
+
+    # Timestamps
+    last_updated: datetime | None = Field(
+        None, alias="lastUpdated", description="Last update time"
+    )
+
+
+# === Models for additional fund endpoints ===
+
+
+class ProductInvolvement(BaseModel):
+    """Product involvement information for sustainability metrics."""
+
+    model_config = MODEL_CONFIG
+
+    product: str
+    productDescription: str
+    value: float
+    name: str
+
+
+class SustainabilityGoal(BaseModel):
+    """UN Sustainable Development Goal information."""
+
+    model_config = MODEL_CONFIG
+
+    goalId: int | None = None
+    goalName: str | None = None
+    goalDescription: str | None = None
+
+
+class FundSustainability(BaseModel):
+    """Fund sustainability and ESG metrics."""
+
+    model_config = MODEL_CONFIG
+
+    lowCarbon: bool | None = None
+    esgScore: float | None = None
+    environmentalScore: float | None = None
+    socialScore: float | None = None
+    governanceScore: float | None = None
+    controversyScore: float | None = None
+    carbonSolutionsInvolvement: float | None = None
+    productInvolvements: list[ProductInvolvement] = []
+    sustainabilityRating: int | None = None
+    sustainabilityRatingCategoryName: str | None = None
+    oilSandsExtractionInvolvement: float | None = None
+    arcticOilAndGasExplorationInvolvement: float | None = None
+    thermalCoalPowerGenerationInvolvement: float | None = None
+    thermalCoalInvolvement: float | None = None
+    oilAndGasProductionInvolvement: float | None = None
+    environmentalRating: int | None = None
+    socialRating: int | None = None
+    governanceRating: int | None = None
+    svanen: bool | None = None
+    euArticleType: dict | str | None = None  # Can be dict with 'value' and 'name' or string
+    aumCoveredCarbon: float | None = None
+    fossilFuelInvolvement: float | None = None
+    carbonRiskScore: float | None = None
+    sustainabilityDevelopmentGoals: list[SustainabilityGoal] = []
+
+
+class FundChartDataPoint(BaseModel):
+    """Single data point in fund chart."""
+
+    model_config = MODEL_CONFIG
+
+    x: int  # timestamp
+    y: float  # value (typically percentage)
+
+
+class FundChart(BaseModel):
+    """Fund chart data with historical performance."""
+
+    model_config = MODEL_CONFIG
+
+    id: str
+    dataSerie: list[FundChartDataPoint]
+    name: str | None = None
+    fromDate: str | None = None
+    toDate: str | None = None
+
+
+class FundChartPeriod(BaseModel):
+    """Fund performance for a specific time period."""
+
+    model_config = MODEL_CONFIG
+
+    timePeriod: str
+    change: float
+    startDate: str
+
+
+class FundDescription(BaseModel):
+    """Fund description and category information."""
+
+    model_config = MODEL_CONFIG
+
+    response: str
+    heading: str
+    detailedCategoryDescription: str

avanza_mcp/models/search.py

@@ -0,0 +1,123 @@
+"""Search result models matching Avanza API response structure."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# Standard model config for all models
+MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,
+    str_strip_whitespace=True,
+    validate_assignment=True,
+    extra="allow",  # Don't fail on extra fields from API
+)
+
+
+class SearchPrice(BaseModel):
+    """Price information for a search result."""
+
+    model_config = MODEL_CONFIG
+
+    last: str | None = None
+    currency: str | None = None
+    todayChangePercent: str | None = None
+    todayChangeValue: str | None = None
+    todayChangeDirection: int = 0
+    threeMonthsAgoChangePercent: str | None = None
+    threeMonthsAgoChangeDirection: int = 0
+    spread: str | None = None
+
+
+class StockSector(BaseModel):
+    """Stock sector classification."""
+
+    model_config = MODEL_CONFIG
+
+    id: int
+    level: int
+    name: str
+    englishName: str
+    highlightedName: str | None = None
+
+
+class FundTag(BaseModel):
+    """Fund classification tag."""
+
+    model_config = MODEL_CONFIG
+
+    title: str
+    category: str
+    tagCategory: str
+    highlightedTitle: str | None = None
+
+
+class SearchHit(BaseModel):
+    """Individual search result from the Avanza API."""
+
+    model_config = MODEL_CONFIG
+
+    type: str
+    title: str
+    highlightedTitle: str
+    description: str
+    highlightedDescription: str
+    path: str | None = None
+    flagCode: str | None = None
+    orderBookId: str | None = None  # May be None for certain instrument types
+    urlSlugName: str
+    tradeable: bool
+    sellable: bool
+    buyable: bool
+    price: SearchPrice | None = None  # May be None for certain instrument types
+    stockSectors: list[StockSector] = Field(default_factory=list)
+    fundTags: list[FundTag] = Field(default_factory=list)
+    marketPlaceName: str
+    subType: str | None = None
+    highlightedSubType: str = ""
+
+
+class TypeFacet(BaseModel):
+    """Facet count for an instrument type."""
+
+    model_config = MODEL_CONFIG
+
+    type: str
+    count: int
+
+
+class SearchFacets(BaseModel):
+    """Search result facets with type counts."""
+
+    model_config = MODEL_CONFIG
+
+    types: list[TypeFacet]
+
+
+class SearchFilter(BaseModel):
+    """Applied search filters."""
+
+    model_config = MODEL_CONFIG
+
+    types: list[str] = Field(default_factory=list)
+
+
+class SearchPagination(BaseModel):
+    """Pagination information."""
+
+    model_config = MODEL_CONFIG
+
+    size: int
+    # Using field alias since 'from' is a Python keyword
+    from_: int = Field(alias="from")
+
+
+class SearchResponse(BaseModel):
+    """Complete search API response from Avanza."""
+
+    model_config = MODEL_CONFIG
+
+    totalNumberOfHits: int
+    hits: list[SearchHit]
+    searchQuery: str
+    searchFilter: SearchFilter
+    facets: SearchFacets
+    pagination: SearchPagination

avanza_mcp/models/stock.py

@@ -0,0 +1,268 @@
+"""Stock-related Pydantic models matching Avanza API."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# Standard model config for all models
+MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,
+    str_strip_whitespace=True,
+    validate_assignment=True,
+    extra="allow",  # Don't fail on extra fields from API
+)
+
+
+class Quote(BaseModel):
+    """Real-time stock quote data."""
+
+    model_config = MODEL_CONFIG
+
+    buy: float | None = None
+    sell: float | None = None
+    last: float | None = None
+    highest: float | None = None
+    lowest: float | None = None
+    change: float | None = None
+    changePercent: float | None = None
+    spread: float | None = None
+    timeOfLast: int | None = None
+    totalValueTraded: float | None = None
+    totalVolumeTraded: float | None = None
+    updated: int | None = None
+    volumeWeightedAveragePrice: float | None = None
+    isRealTime: bool | None = None
+
+
+class Listing(BaseModel):
+    """Stock listing information."""
+
+    model_config = MODEL_CONFIG
+
+    shortName: str
+    tickerSymbol: str | None = None
+    countryCode: str | None = None
+    currency: str
+    marketPlaceCode: str | None = None
+    marketPlaceName: str
+    tickSizeListId: str | None = None
+    marketTradesAvailable: bool | None = None
+
+
+class MarketPlace(BaseModel):
+    """Market place information."""
+
+    model_config = MODEL_CONFIG
+
+    marketOpen: bool
+    tradingTime: str | None = None
+    closingTime: str | None = None
+    country: str | None = None
+    name: str | None = None
+
+
+class ShareInfo(BaseModel):
+    """Share value information."""
+
+    model_config = MODEL_CONFIG
+
+    value: float
+    currency: str
+
+
+class ReportInfo(BaseModel):
+    """Company report information."""
+
+    model_config = MODEL_CONFIG
+
+    date: str
+    reportType: str
+
+
+class Sector(BaseModel):
+    """Stock sector classification."""
+
+    model_config = MODEL_CONFIG
+
+    sectorId: str
+    sectorName: str
+
+
+class KeyIndicators(BaseModel):
+    """Stock key financial indicators."""
+
+    model_config = MODEL_CONFIG
+
+    numberOfOwners: int | None = None
+    reportDate: str | None = None
+    volatility: float | None = None
+    beta: float | None = None
+    priceEarningsRatio: float | None = None
+    priceSalesRatio: float | None = None
+    evEbitRatio: float | None = None
+    returnOnEquity: float | None = None
+    returnOnTotalAssets: float | None = None
+    equityRatio: float | None = None
+    capitalTurnover: float | None = None
+    operatingProfitMargin: float | None = None
+    netMargin: float | None = None
+    marketCapital: ShareInfo | None = None
+    equityPerShare: ShareInfo | None = None
+    turnoverPerShare: ShareInfo | None = None
+    earningsPerShare: ShareInfo | None = None
+    dividendsPerYear: int | None = None
+    nextReport: ReportInfo | None = None
+    previousReport: ReportInfo | None = None
+    directYield: float | None = None
+
+
+class HistoricalClosingPrices(BaseModel):
+    """Historical closing prices."""
+
+    model_config = MODEL_CONFIG
+
+    oneDay: float | None = None
+    oneWeek: float | None = None
+    oneMonth: float | None = None
+    threeMonths: float | None = None
+    startOfYear: float | None = None
+    oneYear: float | None = None
+    threeYears: float | None = None
+    fiveYears: float | None = None
+    start: float | None = None
+
+
+class Company(BaseModel):
+    """Company information."""
+
+    model_config = MODEL_CONFIG
+
+    name: str | None = None
+    description: str | None = None
+    ceo: str | None = None
+    chairman: str | None = None
+    url: str | None = None
+    marketCapital: ShareInfo | None = None
+
+
+class StockInfo(BaseModel):
+    """Complete stock information from Avanza API."""
+
+    model_config = MODEL_CONFIG
+
+    orderbookId: str
+    name: str
+    isin: str | None = None
+    instrumentId: str | None = None
+    sectors: list[Sector] = []
+    tradable: str | None = None
+    listing: Listing
+    marketPlace: MarketPlace | None = None
+    historicalClosingPrices: HistoricalClosingPrices | None = None
+    keyIndicators: KeyIndicators | None = None
+    quote: Quote
+    type: str | None = None
+    company: Company | None = None
+    relatedStocks: list | None = None
+    dividends: list | None = None
+
+
+# === Models for additional endpoints ===
+
+
+class OHLCDataPoint(BaseModel):
+    """OHLC (Open, High, Low, Close) data point for price charts."""
+
+    model_config = MODEL_CONFIG
+
+    timestamp: int
+    open: float
+    close: float
+    low: float
+    high: float
+    totalVolumeTraded: int
+
+
+class ChartMetadata(BaseModel):
+    """Metadata for price chart responses."""
+
+    model_config = MODEL_CONFIG
+
+    resolution: str | dict | None = None  # Can be string or dict
+
+
+class StockChart(BaseModel):
+    """Stock price chart data with OHLC values."""
+
+    model_config = MODEL_CONFIG
+
+    ohlc: list[OHLCDataPoint]
+    metadata: ChartMetadata | None = None
+    from_: int | str | None = Field(None, alias="from")  # 'from' is a Python keyword
+    to: int | str | None = None  # Can be int or date string
+    previousClosingPrice: float | None = None
+
+
+class MarketplaceInfo(BaseModel):
+    """Marketplace status and trading hours."""
+
+    model_config = MODEL_CONFIG
+
+    marketOpen: bool
+    timeLeftMs: int | None = None
+    openingTime: str | None = None
+    todayClosingTime: str | None = None
+    normalClosingTime: str | None = None
+
+
+class BrokerTradeSummary(BaseModel):
+    """Summary of broker trades for a stock."""
+
+    model_config = MODEL_CONFIG
+
+    brokerCode: str
+    sellVolume: int
+    buyVolume: int
+    netBuyVolume: int
+    brokerName: str
+
+
+class Trade(BaseModel):
+    """Individual trade information."""
+
+    model_config = MODEL_CONFIG
+
+    buyer: str
+    seller: str
+    dealTime: int
+    price: float
+    volume: int
+    matchedOnMarket: bool
+    cancelled: bool
+
+
+class OrderSide(BaseModel):
+    """Buy or sell side of an order."""
+
+    model_config = MODEL_CONFIG
+
+    price: float
+    volume: int
+    priceString: str
+
+
+class OrderLevel(BaseModel):
+    """Single level in the order book depth."""
+
+    model_config = MODEL_CONFIG
+
+    buySide: OrderSide | None = None
+    sellSide: OrderSide | None = None
+
+
+class OrderDepth(BaseModel):
+    """Order book depth showing buy and sell orders."""
+
+    model_config = MODEL_CONFIG
+
+    receivedTime: int | None = None  # May be None when market is closed
+    levels: list[OrderLevel] = []  # Empty list when no order book data available

avanza_mcp/prompts/__init__.py

@@ -0,0 +1,6 @@
+"""MCP prompts for Avanza API."""
+
+# Import to register prompts via decorators
+from . import analysis  # noqa: F401
+
+__all__ = ["analysis"]