# AUTO-GENERATED from OpenAPI spec — DO NOT EDIT
# Regenerate: python scripts/regenerate.py
# Source: https://api.thesma.dev/openapi.json
# Generated: 2026-03-16T07:56:29Z
# generated by datamodel-codegen:
#   filename:  tmpmfrj231g.json
#   timestamp: 2026-03-16T07:56:28+00:00

from __future__ import annotations

from datetime import date
from enum import Enum
from typing import Annotated, Any

from pydantic import AwareDatetime, BaseModel, ConfigDict, Field


class BeneficialOwnershipItem(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number for the filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the subject company.
    """
    filer_name: Annotated[str, Field(title="Filer Name")]
    """
    Name of the beneficial owner filing the schedule.
    """
    filer_cik: Annotated[str | None, Field(title="Filer Cik")] = None
    """
    CIK of the filer, if available.
    """
    schedule_type: Annotated[str, Field(title="Schedule Type")]
    """
    SEC schedule type (e.g. 'SC 13D', 'SC 13G/A').
    """
    filing_date: Annotated[date, Field(title="Filing Date")]
    """
    Date the schedule was filed with the SEC.
    """
    event_date: Annotated[date | None, Field(title="Event Date")] = None
    """
    Date of the event that triggered the filing.
    """
    shares_held: Annotated[float | None, Field(title="Shares Held")] = None
    """
    Total shares beneficially owned.
    """
    percent_of_class: Annotated[float | None, Field(title="Percent Of Class")] = None
    """
    Percentage of the class of securities beneficially owned.
    """
    sole_voting_power: Annotated[float | None, Field(title="Sole Voting Power")] = None
    """
    Number of shares with sole voting power.
    """
    shared_voting_power: Annotated[float | None, Field(title="Shared Voting Power")] = None
    """
    Number of shares with shared voting power.
    """
    sole_dispositive_power: Annotated[float | None, Field(title="Sole Dispositive Power")] = None
    """
    Number of shares with sole dispositive power.
    """
    shared_dispositive_power: Annotated[float | None, Field(title="Shared Dispositive Power")] = None
    """
    Number of shares with shared dispositive power.
    """
    purpose_of_transaction: Annotated[str | None, Field(title="Purpose Of Transaction")] = None
    """
    Stated purpose of the transaction or holding.
    """
    source_of_funds: Annotated[str | None, Field(title="Source Of Funds")] = None
    """
    Source of funds used for the acquisition.
    """
    is_amendment: Annotated[bool, Field(title="Is Amendment")]
    """
    Whether this filing is an amendment to a prior schedule.
    """
    original_accession_number: Annotated[str | None, Field(title="Original Accession Number")] = None
    """
    Accession number of the original filing, if this is an amendment.
    """
    is_group_filing: Annotated[bool, Field(title="Is Group Filing")]
    """
    Whether the filing is made on behalf of a group.
    """
    group_member_count: Annotated[int | None, Field(title="Group Member Count")] = None
    """
    Number of members in the filing group, if a group filing.
    """


class CommitteeDetail(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Name of the board committee.
    """
    is_chair: Annotated[bool, Field(title="Is Chair")]
    """
    Whether this board member chairs the committee.
    """


class CompanyTier(Enum):
    sp500 = "sp500"
    russell1000 = "russell1000"
    russell2000 = "russell2000"
    other = "other"


class CompanyListItem(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key, zero-padded to 10 digits.
    """
    ticker: Annotated[str | None, Field(title="Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Company name as registered with the SEC.
    """
    sic_code: Annotated[str | None, Field(title="Sic Code")] = None
    """
    Standard Industrial Classification code.
    """
    company_tier: Annotated[CompanyTier, Field(title="Company Tier")]
    """
    Index membership tier.
    """
    state_fips: Annotated[str | None, Field(title="State Fips")] = None
    """
    2-digit state FIPS code.
    """
    county_fips: Annotated[str | None, Field(title="County Fips")] = None
    """
    5-digit county FIPS code.
    """


class ChangeType(Enum):
    new = "new"
    exited = "exited"
    increased = "increased"
    decreased = "decreased"
    unchanged = "unchanged"


class CompanyPositionChange(BaseModel):
    fund_cik: Annotated[str, Field(title="Fund Cik")]
    """
    CIK of the institutional fund that changed its position.
    """
    fund_name: Annotated[str | None, Field(title="Fund Name")] = None
    """
    Name of the institutional fund.
    """
    change_type: Annotated[ChangeType, Field(title="Change Type")]
    """
    Type of position change between quarters.
    """
    current_shares: Annotated[float | None, Field(title="Current Shares")] = None
    """
    Number of shares held in the current quarter.
    """
    previous_shares: Annotated[float | None, Field(title="Previous Shares")] = None
    """
    Number of shares held in the previous quarter.
    """
    share_delta: Annotated[float | None, Field(title="Share Delta")] = None
    """
    Change in share count between quarters (current minus previous).
    """
    pct_change: Annotated[float | None, Field(title="Pct Change")] = None
    """
    Percentage change in share count from previous quarter (25.0 = 25% increase).
    """
    current_market_value: Annotated[float | None, Field(title="Current Market Value")] = None
    """
    Current market value in USD.
    """
    previous_market_value: Annotated[float | None, Field(title="Previous Market Value")] = None
    """
    Previous quarter market value in USD.
    """
    quarter: Annotated[str, Field(title="Quarter")]
    """
    Quarter label for this position change (e.g. '2024-Q3').
    """
    previous_quarter: Annotated[str | None, Field(title="Previous Quarter")] = None
    """
    Previous quarter label (e.g. '2024-Q2'). Null for new positions.
    """


class CompanyRef(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key for the company.
    """
    ticker: Annotated[str | None, Field(title="Ticker")] = None
    """
    Stock ticker symbol.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Company name.
    """


class CountyFipsConfidence(Enum):
    high = "high"
    medium = "medium"
    low = "low"


class CompanyResponse(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key, zero-padded to 10 digits.
    """
    ticker: Annotated[str | None, Field(title="Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Company name as registered with the SEC.
    """
    sic_code: Annotated[str | None, Field(title="Sic Code")] = None
    """
    Standard Industrial Classification code.
    """
    sic_description: Annotated[str | None, Field(title="Sic Description")] = None
    """
    Human-readable SIC industry description.
    """
    fiscal_year_end: Annotated[str | None, Field(title="Fiscal Year End")] = None
    """
    Fiscal year end date in MMDD format.
    """
    company_tier: Annotated[CompanyTier, Field(title="Company Tier")]
    """
    Index membership tier.
    """
    state_fips: Annotated[str | None, Field(title="State Fips")] = None
    """
    2-digit state FIPS code (e.g. '06' for California).
    """
    county_fips: Annotated[str | None, Field(title="County Fips")] = None
    """
    5-digit county FIPS code (e.g. '06037' for LA County).
    """
    county_fips_confidence: Annotated[CountyFipsConfidence | None, Field(title="County Fips Confidence")] = None
    """
    Confidence of county FIPS mapping from ZIP code.
    """
    hq_state: Annotated[str | None, Field(title="Hq State")] = None
    """
    EDGAR business address state code (2-letter USPS).
    """
    hq_city: Annotated[str | None, Field(title="Hq City")] = None
    """
    EDGAR business address city name.
    """
    filings_url: Annotated[str, Field(title="Filings Url")]
    """
    URL to retrieve this company's filings.
    """
    financials_url: Annotated[str, Field(title="Financials Url")]
    """
    URL to retrieve this company's financial statements.
    """


class CompanySummary(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key, zero-padded to 10 digits.
    """
    ticker: Annotated[str | None, Field(title="Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Company name as registered with the SEC.
    """


class ComparisonPlace(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    FIPS code.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Place name.
    """
    value: Annotated[float | None, Field(title="Value")] = None
    """
    Metric value, null if suppressed.
    """
    moe: Annotated[float | None, Field(title="Moe")] = None
    """
    Margin of error.
    """
    suppressed: Annotated[bool, Field(title="Suppressed")]
    """
    Whether this value was suppressed.
    """


class CompensationDetail(BaseModel):
    salary: Annotated[float | None, Field(title="Salary")] = None
    """
    Salary in USD as reported in the proxy statement.
    """
    bonus: Annotated[float | None, Field(title="Bonus")] = None
    """
    Bonus in USD as reported in the proxy statement.
    """
    stock_awards: Annotated[float | None, Field(title="Stock Awards")] = None
    """
    Stock awards in USD as reported in the proxy statement.
    """
    option_awards: Annotated[float | None, Field(title="Option Awards")] = None
    """
    Option awards in USD as reported in the proxy statement.
    """
    non_equity_incentive: Annotated[float | None, Field(title="Non Equity Incentive")] = None
    """
    Non-equity incentive plan compensation in USD.
    """
    other: Annotated[float | None, Field(title="Other")] = None
    """
    All other compensation in USD.
    """
    total: Annotated[float | None, Field(title="Total")] = None
    """
    Total compensation in USD.
    """


class DataQualityReportCreate(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    filing_type: Annotated[str, Field(title="Filing Type")]
    issue_type: Annotated[str, Field(title="Issue Type")]
    severity: Annotated[str, Field(title="Severity")]
    description: Annotated[str, Field(max_length=5000, title="Description")]
    field: Annotated[str | None, Field(title="Field")] = None
    expected_value: Annotated[str | None, Field(title="Expected Value")] = None
    actual_value: Annotated[str | None, Field(title="Actual Value")] = None
    detected_by: Annotated[str | None, Field(title="Detected By")] = None
    detected_at: Annotated[AwareDatetime | None, Field(title="Detected At")] = None


class DataQualityReportResponse(BaseModel):
    id: Annotated[int, Field(title="Id")]
    user_id: Annotated[str, Field(title="User Id")]
    accession_number: Annotated[str, Field(title="Accession Number")]
    filing_type: Annotated[str, Field(title="Filing Type")]
    issue_type: Annotated[str, Field(title="Issue Type")]
    severity: Annotated[str, Field(title="Severity")]
    description: Annotated[str, Field(title="Description")]
    field: Annotated[str | None, Field(title="Field")]
    expected_value: Annotated[str | None, Field(title="Expected Value")]
    actual_value: Annotated[str | None, Field(title="Actual Value")]
    detected_by: Annotated[str | None, Field(title="Detected By")]
    detected_at: Annotated[AwareDatetime, Field(title="Detected At")]
    status: Annotated[str, Field(title="Status")]
    resolution_reason: Annotated[str | None, Field(title="Resolution Reason")]
    created_at: Annotated[AwareDatetime, Field(title="Created At")]
    updated_at: Annotated[AwareDatetime, Field(title="Updated At")]


class DataQualityReportUpdate(BaseModel):
    status: Annotated[str, Field(title="Status")]
    resolution_reason: Annotated[str | None, Field(title="Resolution Reason")] = None


class DataResponseCompanyResponse(BaseModel):
    data: CompanyResponse


class DataResponseDataQualityReportResponse(BaseModel):
    data: DataQualityReportResponse


class EntityResponse(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number of the filing.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC filing type (e.g. '10-K', '10-Q').
    """
    filed_at: Annotated[AwareDatetime, Field(title="Filed At")]
    """
    Filing date.
    """
    entity_text: Annotated[str, Field(title="Entity Text")]
    """
    The extracted entity text (e.g. 'Apple Inc.', '$4.2 billion').
    """
    entity_type: Annotated[str, Field(title="Entity Type")]
    """
    Entity type label: ORG, MONEY, DATE, PERCENT, PERSON.
    """
    start_char: Annotated[int, Field(title="Start Char")]
    """
    Character offset start in section content.
    """
    end_char: Annotated[int, Field(title="End Char")]
    """
    Character offset end in section content.
    """


class EventCategory(BaseModel):
    name: Annotated[str, Field(title="Name")]
    description: Annotated[str, Field(title="Description")]
    filing_count: Annotated[int, Field(title="Filing Count")]


class EventItem(BaseModel):
    model_config = ConfigDict(
        extra="allow",
    )


class EventListItem(BaseModel):
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    SEC accession number for the 8-K filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the company that filed the 8-K.
    """
    company_name: Annotated[str | None, Field(title="Company Name")] = None
    """
    Name of the filing company.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Ticker symbol of the filing company.
    """
    filed_at: Annotated[AwareDatetime, Field(title="Filed At")]
    """
    Date and time the 8-K was filed with the SEC.
    """
    items: Annotated[list[EventItem], Field(title="Items")]
    """
    List of 8-K item codes reported in this filing.
    """
    category: Annotated[str, Field(title="Category")]
    """
    Primary event category derived from item codes (e.g. earnings, ma, leadership).
    """
    filing_url: Annotated[str, Field(title="Filing Url")]
    """
    API URL to the filing detail endpoint.
    """


class ExtractionConfidence(Enum):
    high = "high"
    medium = "medium"
    low = "low"


class ExecutiveCompensationItem(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Name of the executive.
    """
    title: Annotated[str | None, Field(title="Title")] = None
    """
    Title or role of the executive.
    """
    compensation: CompensationDetail
    """
    Detailed compensation breakdown.
    """
    extraction_confidence: Annotated[ExtractionConfidence, Field(title="Extraction Confidence")]
    """
    Confidence level of the data extraction from the proxy filing.
    """


class FieldMeta(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Canonical field name (e.g. 'revenue').
    """
    description: Annotated[str, Field(title="Description")]
    """
    Short human-readable description of the field.
    """
    bank_specific: Annotated[bool, Field(title="Bank Specific")]
    """
    True if only populated for bank/financial institution filings.
    """


class ContentType(Enum):
    text_html = "text/html"
    text_plain = "text/plain"


class FilingContentResponse(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number uniquely identifying this filing.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC form type (e.g. '10-K', '10-Q', '8-K').
    """
    content_type: Annotated[ContentType | None, Field(title="Content Type")] = "text/plain"
    """
    MIME type of the content field.
    """
    content: Annotated[str, Field(title="Content")]
    """
    Cleaned filing content with HTML markup removed.
    """
    source_url: Annotated[str, Field(title="Source Url")]
    """
    EDGAR URL the content was fetched from.
    """


class ParseStatus(Enum):
    pending = "pending"
    parsed = "parsed"
    failed = "failed"
    unsupported = "unsupported"


class FilingDetailResponse(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number uniquely identifying this filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key of the filing company.
    """
    company_name: Annotated[str, Field(title="Company Name")]
    """
    Company name as registered with the SEC.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC form type (e.g. '10-K', '10-Q', '8-K').
    """
    filed_at: Annotated[AwareDatetime, Field(title="Filed At")]
    """
    Date and time the filing was submitted to EDGAR.
    """
    period_of_report: Annotated[date | None, Field(title="Period Of Report")] = None
    """
    Reporting period end date, if applicable.
    """
    is_amendment: Annotated[bool, Field(title="Is Amendment")]
    """
    True if this filing amends a previous submission.
    """
    supersedes: Annotated[str | None, Field(title="Supersedes")] = None
    """
    Accession number of the immediately prior filing in the amendment chain.
    """
    is_superseded: Annotated[bool, Field(title="Is Superseded")]
    """
    True if a later amendment has replaced this filing.
    """
    is_latest_for_period: Annotated[bool, Field(title="Is Latest For Period")]
    """
    True if this is the most current filing for its reporting period.
    """
    raw_url: Annotated[str | None, Field(title="Raw Url")] = None
    """
    EDGAR URL to the original filing document.
    """
    parse_status: Annotated[ParseStatus, Field(title="Parse Status")]
    """
    Current parsing status of the filing.
    """
    financials_available: Annotated[bool, Field(title="Financials Available")]
    """
    True if financial statements have been extracted from this filing.
    """
    content_url: Annotated[str, Field(title="Content Url")]
    """
    URL to retrieve the cleaned filing content.
    """


class FilingListItem(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number uniquely identifying this filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key of the filing company.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC form type (e.g. '10-K', '10-Q', '8-K').
    """
    filed_at: Annotated[AwareDatetime, Field(title="Filed At")]
    """
    Date and time the filing was submitted to EDGAR.
    """
    period_of_report: Annotated[date | None, Field(title="Period Of Report")] = None
    """
    Reporting period end date, if applicable.
    """
    is_amendment: Annotated[bool, Field(title="Is Amendment")]
    """
    True if this filing amends a previous submission.
    """
    is_superseded: Annotated[bool, Field(title="Is Superseded")]
    """
    True if a later amendment has replaced this filing.
    """
    is_latest_for_period: Annotated[bool, Field(title="Is Latest For Period")]
    """
    True if this is the most current filing for its reporting period.
    """
    detail_url: Annotated[str, Field(title="Detail Url")]
    """
    URL to retrieve the full filing detail.
    """


class Statement(Enum):
    income = "income"
    balance_sheet = "balance-sheet"
    cash_flow = "cash-flow"


class Period(Enum):
    annual = "annual"
    quarterly = "quarterly"


class PositionType(Enum):
    equity = "equity"
    debt = "debt"
    option = "option"
    other = "other"


class Discretion(Enum):
    sole = "sole"
    shared = "shared"
    defined = "defined"
    other = "other"


class FundHoldingListItem(BaseModel):
    held_company_name: Annotated[str, Field(title="Held Company Name")]
    """
    Name of the company whose shares are held.
    """
    cusip: Annotated[str, Field(title="Cusip")]
    """
    CUSIP identifier for the held security.
    """
    held_company_cik: Annotated[str | None, Field(title="Held Company Cik")] = None
    """
    SEC Central Index Key of the held company, if resolved.
    """
    held_company_ticker: Annotated[str | None, Field(title="Held Company Ticker")] = None
    """
    Trading ticker of the held company, if available.
    """
    shares: Annotated[float, Field(title="Shares")]
    """
    Number of shares held.
    """
    market_value: Annotated[float, Field(title="Market Value")]
    """
    Market value in USD.
    """
    position_type: Annotated[PositionType, Field(title="Position Type")]
    """
    Type of investment position.
    """
    discretion: Annotated[Discretion | None, Field(title="Discretion")] = None
    """
    Type of investment discretion reported.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source 13F filing.
    """


class FundListItem(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key of the fund.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Fund name as registered with the SEC.
    """
    holdings_url: Annotated[str, Field(title="Holdings Url")]
    """
    URL to retrieve this fund's holdings.
    """


class FundPositionChange(BaseModel):
    held_company_name: Annotated[str, Field(title="Held Company Name")]
    """
    Name of the company whose shares changed.
    """
    cusip: Annotated[str, Field(title="Cusip")]
    """
    CUSIP identifier for the security.
    """
    held_company_cik: Annotated[str | None, Field(title="Held Company Cik")] = None
    """
    CIK of the held company, if resolved.
    """
    held_company_ticker: Annotated[str | None, Field(title="Held Company Ticker")] = None
    """
    Ticker of the held company, if available.
    """
    change_type: Annotated[ChangeType, Field(title="Change Type")]
    """
    Type of position change between quarters.
    """
    current_shares: Annotated[float | None, Field(title="Current Shares")] = None
    """
    Number of shares held in the current quarter.
    """
    previous_shares: Annotated[float | None, Field(title="Previous Shares")] = None
    """
    Number of shares held in the previous quarter.
    """
    share_delta: Annotated[float | None, Field(title="Share Delta")] = None
    """
    Change in share count between quarters (current minus previous).
    """
    pct_change: Annotated[float | None, Field(title="Pct Change")] = None
    """
    Percentage change in share count from previous quarter (25.0 = 25% increase).
    """
    current_market_value: Annotated[float | None, Field(title="Current Market Value")] = None
    """
    Current market value in USD.
    """
    previous_market_value: Annotated[float | None, Field(title="Previous Market Value")] = None
    """
    Previous quarter market value in USD.
    """
    quarter: Annotated[str, Field(title="Quarter")]
    """
    Quarter label for this position change (e.g. '2024-Q3').
    """
    previous_quarter: Annotated[str | None, Field(title="Previous Quarter")] = None
    """
    Previous quarter label (e.g. '2024-Q2'). Null for new positions.
    """


class GeographyLevel(BaseModel):
    level: Annotated[str, Field(title="Level")]
    """
    Geographic level name (e.g. nation, state, county).
    """
    count: Annotated[int, Field(title="Count")]
    """
    Number of places at this level.
    """


class HolderListItem(BaseModel):
    fund_cik: Annotated[str, Field(title="Fund Cik")]
    """
    SEC Central Index Key of the holding fund.
    """
    fund_name: Annotated[str | None, Field(title="Fund Name")] = None
    """
    Fund name as registered with the SEC.
    """
    shares: Annotated[float, Field(title="Shares")]
    """
    Number of shares held.
    """
    market_value: Annotated[float, Field(title="Market Value")]
    """
    Market value in USD.
    """
    discretion: Annotated[Discretion | None, Field(title="Discretion")] = None
    """
    Type of investment discretion reported.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source 13F filing.
    """


class Ownership(Enum):
    direct = "direct"
    indirect = "indirect"


class InsiderHoldingItem(BaseModel):
    security_type: Annotated[str, Field(title="Security Type")]
    """
    Type of security held (e.g. 'Common Stock', 'Stock Option').
    """
    shares: Annotated[float | None, Field(title="Shares")] = None
    """
    Number of shares or units held.
    """
    ownership: Annotated[Ownership, Field(title="Ownership")]
    """
    Whether the insider owns the shares directly or indirectly.
    """
    is_derivative: Annotated[bool, Field(title="Is Derivative")]
    """
    True if this is a derivative security (e.g. option, warrant).
    """
    exercise_date: Annotated[date | None, Field(title="Exercise Date")] = None
    """
    Exercise date for derivative securities, if applicable.
    """
    expiration_date: Annotated[date | None, Field(title="Expiration Date")] = None
    """
    Expiration date for derivative securities, if applicable.
    """
    underlying_shares: Annotated[float | None, Field(title="Underlying Shares")] = None
    """
    Number of underlying shares for derivative securities.
    """


class Relationship(Enum):
    ceo = "ceo"
    cfo = "cfo"
    c_suite = "c_suite"
    officer = "officer"
    director = "director"
    ten_percent_owner = "ten_percent_owner"
    other = "other"


class InsiderHoldingPerson(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Full name of the insider.
    """
    title: Annotated[str | None, Field(title="Title")] = None
    """
    Officer title or role description, if reported.
    """
    relationship: Annotated[Relationship, Field(title="Relationship")]
    """
    Normalised relationship to the issuing company.
    """
    holdings: Annotated[list[InsiderHoldingItem], Field(title="Holdings")]
    """
    Securities held by this insider.
    """


class InsiderPerson(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Full name of the insider.
    """
    title: Annotated[str | None, Field(title="Title")] = None
    """
    Officer title or role description, if reported.
    """
    relationship: Annotated[Relationship, Field(title="Relationship")]
    """
    Normalised relationship to the issuing company.
    """


class InsiderTradeListItem(BaseModel):
    person: InsiderPerson
    """
    Insider who executed the transaction.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key of the issuing company.
    """
    company_name: Annotated[str | None, Field(title="Company Name")] = None
    """
    Company name as registered with the SEC.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    transaction_date: Annotated[date, Field(title="Transaction Date")]
    """
    Date the transaction was executed.
    """
    type: Annotated[str, Field(title="Type")]
    """
    Transaction type (e.g. 'purchase', 'sale', 'grant', 'exercise').
    """
    security: Annotated[str, Field(title="Security")]
    """
    Description of the security transacted (e.g. 'Common Stock').
    """
    shares: Annotated[float, Field(title="Shares")]
    """
    Number of shares involved in the transaction.
    """
    price_per_share: Annotated[float | None, Field(title="Price Per Share")] = None
    """
    Price per share in USD, if reported.
    """
    total_value: Annotated[float | None, Field(title="Total Value")] = None
    """
    Total transaction value in USD.
    """
    shares_after: Annotated[float | None, Field(title="Shares After")] = None
    """
    Insider's share count after the transaction.
    """
    ownership: Annotated[Ownership, Field(title="Ownership")]
    """
    Whether the insider owns the shares directly or indirectly.
    """
    is_planned_trade: Annotated[bool | None, Field(title="Is Planned Trade")] = None
    """
    True if the trade was made under a Rule 10b5-1 plan.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source Form 4 filing.
    """
    filing_url: Annotated[str, Field(title="Filing Url")]
    """
    URL to retrieve the source filing detail.
    """


class LatestYear(BaseModel):
    acs1: Annotated[int | None, Field(title="Acs1")] = None
    """
    Latest year available for ACS 1-year.
    """
    acs5: Annotated[int | None, Field(title="Acs5")] = None
    """
    Latest year available for ACS 5-year.
    """


class MetricInfo(BaseModel):
    canonical_name: Annotated[str, Field(title="Canonical Name")]
    """
    Machine-readable metric identifier.
    """
    display_name: Annotated[str, Field(title="Display Name")]
    """
    Human-readable metric name.
    """
    category: Annotated[str, Field(title="Category")]
    """
    Metric category.
    """
    unit: Annotated[str, Field(title="Unit")]
    """
    Unit of measurement.
    """


class MetricSummary(BaseModel):
    canonical_name: Annotated[str, Field(title="Canonical Name")]
    """
    Machine-readable metric identifier.
    """
    display_name: Annotated[str, Field(title="Display Name")]
    """
    Human-readable metric name.
    """
    category: Annotated[str, Field(title="Category")]
    """
    Metric category (e.g. income, housing).
    """
    unit: Annotated[str, Field(title="Unit")]
    """
    Unit of measurement (dollars, percent, people, etc.).
    """
    is_computed: Annotated[bool, Field(title="Is Computed")]
    """
    Whether this metric is derived from other Census variables.
    """
    notes: Annotated[str | None, Field(title="Notes")] = None
    """
    Additional notes about this metric.
    """
    latest_year: LatestYear


class MetricValue(BaseModel):
    canonical_name: Annotated[str, Field(title="Canonical Name")]
    """
    Machine-readable metric identifier.
    """
    display_name: Annotated[str, Field(title="Display Name")]
    """
    Human-readable metric name.
    """
    category: Annotated[str, Field(title="Category")]
    """
    Metric category.
    """
    value: Annotated[float | None, Field(title="Value")] = None
    """
    Metric value, null if suppressed.
    """
    moe: Annotated[float | None, Field(title="Moe")] = None
    """
    Margin of error.
    """
    unit: Annotated[str, Field(title="Unit")]
    """
    Unit of measurement.
    """
    suppressed: Annotated[bool, Field(title="Suppressed")]
    """
    Whether this value was suppressed by the Census Bureau.
    """


class PaginationMeta(BaseModel):
    page: Annotated[int, Field(title="Page")]
    per_page: Annotated[int, Field(title="Per Page")]
    total: Annotated[int, Field(title="Total")]


class ParentInfo(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    Parent FIPS code.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Parent place name.
    """
    level: Annotated[str, Field(title="Level")]
    """
    Parent geographic level.
    """


class Confidence(Enum):
    high = "high"
    medium = "medium"


class PayRatioItem(BaseModel):
    ceo_compensation: Annotated[float | None, Field(title="Ceo Compensation")] = None
    """
    CEO total compensation in USD.
    """
    median_employee_compensation: Annotated[float | None, Field(title="Median Employee Compensation")] = None
    """
    Median employee total compensation in USD.
    """
    ratio: Annotated[float, Field(title="Ratio")]
    """
    CEO-to-median employee pay ratio (e.g. 287.0 means 287:1).
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year for the pay ratio data.
    """
    confidence: Annotated[Confidence, Field(title="Confidence")]
    """
    Confidence level of the pay ratio extraction.
    """


class PlaceDetail(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    FIPS code for this place.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Place name.
    """
    level: Annotated[str, Field(title="Level")]
    """
    Geographic level (nation, state, county, metro, zip, tract).
    """
    parent_fips: Annotated[str | None, Field(title="Parent Fips")] = None
    """
    FIPS code of the parent geography.
    """
    parent_name: Annotated[str | None, Field(title="Parent Name")] = None
    """
    Name of the parent geography.
    """
    population: Annotated[int | None, Field(title="Population")] = None
    """
    Population count.
    """
    area_sq_mi: Annotated[float | None, Field(title="Area Sq Mi")] = None
    """
    Land area in square miles.
    """
    lat: Annotated[float | None, Field(title="Lat")] = None
    """
    Latitude of the place centroid.
    """
    lon: Annotated[float | None, Field(title="Lon")] = None
    """
    Longitude of the place centroid.
    """
    children_levels: Annotated[list[str], Field(title="Children Levels")]
    """
    Valid child geographic levels for breakdown queries.
    """


class PlaceSummary(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    FIPS code for this place.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Place name.
    """
    level: Annotated[str, Field(title="Level")]
    """
    Geographic level (nation, state, county, metro, zip, tract).
    """
    parent_fips: Annotated[str | None, Field(title="Parent Fips")] = None
    """
    FIPS code of the parent geography.
    """
    population: Annotated[int | None, Field(title="Population")] = None
    """
    Population count.
    """


class ProxyVoteItem(BaseModel):
    proposal_number: Annotated[str, Field(title="Proposal Number")]
    """
    Proposal number as listed in the proxy statement.
    """
    proposal_type: Annotated[str, Field(title="Proposal Type")]
    """
    Type of proposal (e.g. director_election, say_on_pay).
    """
    description: Annotated[str, Field(title="Description")]
    """
    Description of the proposal.
    """
    nominee_name: Annotated[str | None, Field(title="Nominee Name")] = None
    """
    Name of the nominee, for director election proposals.
    """
    votes_for: Annotated[float | None, Field(title="Votes For")] = None
    """
    Number of votes cast in favour of the proposal.
    """
    votes_against: Annotated[float | None, Field(title="Votes Against")] = None
    """
    Number of votes cast against the proposal.
    """
    votes_abstain: Annotated[float | None, Field(title="Votes Abstain")] = None
    """
    Number of abstention votes.
    """
    votes_broker_non_vote: Annotated[float | None, Field(title="Votes Broker Non Vote")] = None
    """
    Number of broker non-votes on the proposal.
    """
    approval_pct: Annotated[float | None, Field(title="Approval Pct")] = None
    """
    Percentage of votes cast in favour of the proposal.
    """
    outcome: Annotated[str | None, Field(title="Outcome")] = None
    """
    Voting outcome (e.g. passed, failed).
    """


class RatioMetadata(BaseModel):
    filing_accession: Annotated[str | None, Field(title="Filing Accession")] = None
    """
    Accession number of the filing used to compute the ratios.
    """


class RatioTimeSeriesPoint(BaseModel):
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year of this data point.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter (1-4) for quarterly data, null for annual.
    """
    value: Annotated[float | None, Field(title="Value")] = None
    """
    Ratio value for this period. Units depend on the ratio requested.
    """


class RatioTimeSeriesResponse(BaseModel):
    company: CompanySummary
    """
    Company identification details.
    """
    ratio: Annotated[str, Field(title="Ratio")]
    """
    Name of the ratio being charted.
    """
    period: Annotated[Period, Field(title="Period")]
    """
    Reporting period type.
    """
    series: Annotated[list[RatioTimeSeriesPoint], Field(title="Series")]
    """
    Chronologically ordered data points.
    """


class RatioValues(BaseModel):
    gross_margin: Annotated[float | None, Field(title="Gross Margin")] = None
    """
    Gross margin as a percentage (64.82 = 64.82%). Computed from revenue and cost of goods sold.
    """
    operating_margin: Annotated[float | None, Field(title="Operating Margin")] = None
    """
    Operating margin as a percentage (20.5 = 20.5%). Computed from operating income and revenue.
    """
    net_margin: Annotated[float | None, Field(title="Net Margin")] = None
    """
    Net margin as a percentage (15.3 = 15.3%). Computed from net income and revenue.
    """
    return_on_equity: Annotated[float | None, Field(title="Return On Equity")] = None
    """
    Return on equity as a percentage (25.0 = 25.0%). Computed from net income and equity.
    """
    return_on_assets: Annotated[float | None, Field(title="Return On Assets")] = None
    """
    Return on assets as a percentage (10.5 = 10.5%). Computed from net income and total assets.
    """
    debt_to_equity: Annotated[float | None, Field(title="Debt To Equity")] = None
    """
    Total debt divided by total equity (1.5 = 1.5x leverage).
    """
    current_ratio: Annotated[float | None, Field(title="Current Ratio")] = None
    """
    Current assets divided by current liabilities (2.0 = 2.0x coverage).
    """
    interest_coverage: Annotated[float | None, Field(title="Interest Coverage")] = None
    """
    Operating income divided by interest expense (5.0 = 5.0x coverage).
    """
    revenue_growth_yoy: Annotated[float | None, Field(title="Revenue Growth Yoy")] = None
    """
    Year-over-year revenue growth as a percentage (12.5 = 12.5% growth).
    """
    net_income_growth_yoy: Annotated[float | None, Field(title="Net Income Growth Yoy")] = None
    """
    Year-over-year net income growth as a percentage (8.3 = 8.3% growth).
    """
    eps_growth_yoy: Annotated[float | None, Field(title="Eps Growth Yoy")] = None
    """
    Year-over-year earnings per share growth as a percentage (10.0 = 10.0% growth).
    """


class ScreenerFinancials(BaseModel):
    revenue: Annotated[float | None, Field(title="Revenue")] = None
    """
    Total revenue (USD) for the company's latest annual fiscal year.
    """
    net_income: Annotated[float | None, Field(title="Net Income")] = None
    """
    Net income (USD) for the company's latest annual fiscal year.
    """
    eps_diluted: Annotated[float | None, Field(title="Eps Diluted")] = None
    """
    Diluted earnings per share (USD). Uses weighted average diluted share count.
    """
    common_shares_outstanding: Annotated[float | None, Field(title="Common Shares Outstanding")] = None
    """
    Balance sheet period-end common shares outstanding.
    """
    total_equity: Annotated[float | None, Field(title="Total Equity")] = None
    """
    Total stockholders' equity (USD).
    """
    dividends_paid: Annotated[float | None, Field(title="Dividends Paid")] = None
    """
    Cash dividends paid (USD). Negative values indicate cash outflow, per SEC cash flow statement sign convention.
    """
    institutional_ownership_pct: Annotated[float | None, Field(title="Institutional Ownership Pct")] = None
    """
    Percentage of common shares held by 13F-reporting institutions. Values above 100% are valid.
    """


class ScreenerResultItem(BaseModel):
    cik: Annotated[str, Field(title="Cik")]
    """
    SEC Central Index Key, zero-padded to 10 digits.
    """
    ticker: Annotated[str | None, Field(title="Ticker")] = None
    """
    Trading ticker symbol, if available.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Company name as registered with the SEC.
    """
    company_tier: Annotated[CompanyTier, Field(title="Company Tier")]
    """
    Index membership tier.
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year of the most recent annual ratio data for this company.
    """
    financials: ScreenerFinancials
    """
    Raw financial fields from the company's latest annual fiscal year.
    """
    ratios: RatioValues
    """
    Computed financial ratios for this company.
    """


class SearchPaginationMeta(BaseModel):
    page: Annotated[int, Field(title="Page")]
    per_page: Annotated[int, Field(title="Per Page")]
    total: Annotated[None, Field(title="Total")] = None
    has_more: Annotated[bool, Field(title="Has More")]


class SearchResult(BaseModel):
    chunk_text: Annotated[str, Field(title="Chunk Text")]
    """
    The text content of the matched chunk.
    """
    similarity_score: Annotated[float, Field(title="Similarity Score")]
    """
    Cosine similarity score (0 to 1).
    """
    word_count: Annotated[int, Field(title="Word Count")]
    """
    Word count of the chunk.
    """
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number of the filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the filing company.
    """
    company_name: Annotated[str, Field(title="Company Name")]
    """
    Name of the filing company.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Ticker symbol of the filing company.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC filing type (e.g. '10-K', '10-Q').
    """
    filed_at: Annotated[AwareDatetime, Field(title="Filed At")]
    """
    Filing date.
    """
    section_type: Annotated[str, Field(title="Section Type")]
    """
    Section type (e.g. 'item_1a', 'item_7').
    """
    section_title: Annotated[str | None, Field(title="Section Title")] = None
    """
    Human-readable section title.
    """
    fiscal_year: Annotated[int | None, Field(title="Fiscal Year")] = None
    """
    Fiscal year of the filing.
    """


class SectionChangeResponse(BaseModel):
    current_accession_number: Annotated[str, Field(title="Current Accession Number")]
    """
    Accession number of the current filing.
    """
    previous_accession_number: Annotated[str, Field(title="Previous Accession Number")]
    """
    Accession number of the previous filing.
    """
    current_filed_at: Annotated[AwareDatetime, Field(title="Current Filed At")]
    """
    Filing date of the current filing.
    """
    previous_filed_at: Annotated[AwareDatetime, Field(title="Previous Filed At")]
    """
    Filing date of the previous filing.
    """
    similarity_score: Annotated[float, Field(title="Similarity Score")]
    """
    Overall cosine similarity between the two sections (0 to 1).
    """
    paragraphs_added: Annotated[int, Field(title="Paragraphs Added")]
    """
    Count of new paragraphs in current filing.
    """
    paragraphs_removed: Annotated[int, Field(title="Paragraphs Removed")]
    """
    Count of paragraphs dropped from previous filing.
    """
    paragraphs_modified: Annotated[int, Field(title="Paragraphs Modified")]
    """
    Count of paragraphs present in both but materially changed.
    """
    paragraphs_unchanged: Annotated[int, Field(title="Paragraphs Unchanged")]
    """
    Count of paragraphs that are unchanged or trivially edited.
    """
    change_summary: Annotated[dict[str, Any], Field(title="Change Summary")]
    """
    Per-paragraph diff details with typed change entries.
    """


class SectionType(Enum):
    item_1 = "item_1"
    item_10 = "item_10"
    item_11 = "item_11"
    item_12 = "item_12"
    item_13 = "item_13"
    item_14 = "item_14"
    item_15 = "item_15"
    item_1a = "item_1a"
    item_1b = "item_1b"
    item_1c = "item_1c"
    item_2 = "item_2"
    item_3 = "item_3"
    item_4 = "item_4"
    item_5 = "item_5"
    item_6 = "item_6"
    item_7 = "item_7"
    item_7a = "item_7a"
    item_8 = "item_8"
    item_9 = "item_9"
    item_9a = "item_9a"
    item_9b = "item_9b"
    item_9c = "item_9c"


class SentimentLabel(Enum):
    positive = "positive"
    negative = "negative"
    neutral = "neutral"


class SectionDetail(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number of the parent filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the filing company.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC filing type (e.g. '10-K', '10-Q').
    """
    filed_at: Annotated[AwareDatetime | None, Field(title="Filed At")] = None
    """
    Date and time the filing was submitted to the SEC.
    """
    period_of_report: Annotated[date | None, Field(title="Period Of Report")] = None
    """
    Period end date covered by the filing.
    """
    section_type: Annotated[SectionType, Field(title="Section Type")]
    """
    Section identifier (e.g. 'item_1a', 'item_7').
    """
    section_title: Annotated[str | None, Field(title="Section Title")] = None
    """
    Human-readable section title.
    """
    word_count: Annotated[int, Field(title="Word Count")]
    """
    Number of words in the section text.
    """
    fiscal_year: Annotated[int | None, Field(title="Fiscal Year")] = None
    """
    Fiscal year of the filing.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter of the filing (1-4).
    """
    extraction_confidence: Annotated[float | None, Field(title="Extraction Confidence")] = None
    """
    Confidence score for the section extraction (0.0–1.0).
    """
    sentiment_score: Annotated[float | None, Field(title="Sentiment Score")] = None
    """
    FinBERT composite score (-1 to 1). NULL if not yet scored.
    """
    sentiment_label: Annotated[SentimentLabel | None, Field(title="Sentiment Label")] = None
    """
    Sentiment classification label.
    """
    lm_positive: Annotated[int | None, Field(title="Lm Positive")] = None
    """
    Loughran-McDonald positive word count.
    """
    lm_negative: Annotated[int | None, Field(title="Lm Negative")] = None
    """
    Loughran-McDonald negative word count.
    """
    lm_uncertainty: Annotated[int | None, Field(title="Lm Uncertainty")] = None
    """
    Loughran-McDonald uncertainty word count.
    """
    lm_litigious: Annotated[int | None, Field(title="Lm Litigious")] = None
    """
    Loughran-McDonald litigious word count.
    """
    lm_constraining: Annotated[int | None, Field(title="Lm Constraining")] = None
    """
    Loughran-McDonald constraining word count.
    """
    content: Annotated[str, Field(title="Content")]
    """
    Full extracted text content of the section.
    """
    content_type: Annotated[str | None, Field(title="Content Type")] = "text/plain"
    """
    MIME type of the content.
    """
    company_name: Annotated[str | None, Field(title="Company Name")] = None
    """
    Name of the filing company.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Ticker symbol of the filing company.
    """
    content_url: Annotated[str, Field(title="Content Url")]


class SectionListItem(BaseModel):
    section_type: Annotated[SectionType, Field(title="Section Type")]
    """
    Section identifier (e.g. 'item_1a', 'item_7').
    """
    section_title: Annotated[str | None, Field(title="Section Title")] = None
    """
    Human-readable section title.
    """
    word_count: Annotated[int, Field(title="Word Count")]
    """
    Number of words in the section text.
    """
    fiscal_year: Annotated[int | None, Field(title="Fiscal Year")] = None
    """
    Fiscal year of the filing.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter of the filing (1-4).
    """
    extraction_confidence: Annotated[float | None, Field(title="Extraction Confidence")] = None
    """
    Confidence score for the section extraction (0.0–1.0).
    """
    content_url: Annotated[str, Field(title="Content Url")]
    """
    API URL to retrieve the full section text.
    """
    content: Annotated[str | None, Field(title="Content")] = None
    """
    Full section text, included only when requested via the include parameter.
    """


class SectionSummary(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number of the parent filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the filing company.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC filing type (e.g. '10-K', '10-Q').
    """
    filed_at: Annotated[AwareDatetime | None, Field(title="Filed At")] = None
    """
    Date and time the filing was submitted to the SEC.
    """
    period_of_report: Annotated[date | None, Field(title="Period Of Report")] = None
    """
    Period end date covered by the filing.
    """
    section_type: Annotated[SectionType, Field(title="Section Type")]
    """
    Section identifier (e.g. 'item_1a', 'item_7').
    """
    section_title: Annotated[str | None, Field(title="Section Title")] = None
    """
    Human-readable section title.
    """
    word_count: Annotated[int, Field(title="Word Count")]
    """
    Number of words in the section text.
    """
    fiscal_year: Annotated[int | None, Field(title="Fiscal Year")] = None
    """
    Fiscal year of the filing.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter of the filing (1-4).
    """
    extraction_confidence: Annotated[float | None, Field(title="Extraction Confidence")] = None
    """
    Confidence score for the section extraction (0.0–1.0).
    """
    sentiment_score: Annotated[float | None, Field(title="Sentiment Score")] = None
    """
    FinBERT composite score (-1 to 1). NULL if not yet scored.
    """
    sentiment_label: Annotated[SentimentLabel | None, Field(title="Sentiment Label")] = None
    """
    Sentiment classification label.
    """
    lm_positive: Annotated[int | None, Field(title="Lm Positive")] = None
    """
    Loughran-McDonald positive word count.
    """
    lm_negative: Annotated[int | None, Field(title="Lm Negative")] = None
    """
    Loughran-McDonald negative word count.
    """
    lm_uncertainty: Annotated[int | None, Field(title="Lm Uncertainty")] = None
    """
    Loughran-McDonald uncertainty word count.
    """
    lm_litigious: Annotated[int | None, Field(title="Lm Litigious")] = None
    """
    Loughran-McDonald litigious word count.
    """
    lm_constraining: Annotated[int | None, Field(title="Lm Constraining")] = None
    """
    Loughran-McDonald constraining word count.
    """
    content_url: Annotated[str, Field(title="Content Url")]


class SourceVariable(BaseModel):
    variable_code: Annotated[str, Field(title="Variable Code")]
    """
    Census API variable code (e.g. B19013_001E).
    """
    dataset: Annotated[str, Field(title="Dataset")]
    """
    Dataset this variable belongs to (acs1 or acs5).
    """
    role: Annotated[str, Field(title="Role")]
    """
    Role of this variable (estimate, moe, numerator, denominator).
    """
    valid_from: Annotated[int, Field(title="Valid From")]
    """
    First year this variable code is valid.
    """
    valid_to: Annotated[int | None, Field(title="Valid To")] = None
    """
    Last year this variable code is valid, or null if still current.
    """


class StatementFields(BaseModel):
    fields: Annotated[list[FieldMeta], Field(title="Fields")]
    """
    Canonical fields for this statement type.
    """


class Source(Enum):
    companyfacts = "companyfacts"
    ixbrl = "ixbrl"
    mixed = "mixed"


class StatementMetadata(BaseModel):
    source: Annotated[Source, Field(title="Source")]
    """
    Data source used for this statement.
    """
    data_completeness: Annotated[int, Field(title="Data Completeness")]
    """
    Number of canonical fields with non-null values.
    """
    expected_fields: Annotated[int, Field(title="Expected Fields")]
    """
    Total expected fields for this statement type.
    """
    source_tags: Annotated[dict[str, str], Field(title="Source Tags")]
    """
    Mapping of canonical field names to original XBRL tags.
    """


class SurveyYears(BaseModel):
    from_: Annotated[int, Field(alias="from", title="From")]
    """
    First year of the survey period.
    """
    to: Annotated[int, Field(title="To")]
    """
    Last year of the survey period.
    """


class TimeSeriesPoint(BaseModel):
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year of this data point.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter (1-4) for quarterly data, null for annual.
    """
    value: Annotated[float, Field(title="Value")]
    """
    Metric value for this period, in the currency specified on the parent response.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source filing.
    """


class TimeSeriesResponse(BaseModel):
    company: CompanySummary
    """
    Company identification details.
    """
    metric: Annotated[str, Field(title="Metric")]
    """
    Canonical field name being charted (e.g. 'revenue').
    """
    period: Annotated[Period, Field(title="Period")]
    """
    Reporting period type.
    """
    currency: Annotated[str, Field(title="Currency")]
    """
    ISO 4217 currency code for monetary values (e.g. 'USD').
    """
    series: Annotated[list[TimeSeriesPoint], Field(title="Series")]
    """
    Chronologically ordered data points.
    """


class ValidationError(BaseModel):
    loc: Annotated[list[str | int], Field(title="Location")]
    msg: Annotated[str, Field(title="Message")]
    type: Annotated[str, Field(title="Error Type")]
    input: Annotated[Any | None, Field(title="Input")] = None
    ctx: Annotated[dict[str, Any] | None, Field(title="Context")] = None


class WebhookCreateRequest(BaseModel):
    url: Annotated[str, Field(title="Url")]
    events: Annotated[list[str], Field(title="Events")]
    filing_types: Annotated[list[str] | None, Field(title="Filing Types")] = None
    description: Annotated[str | None, Field(title="Description")] = None


class Event(Enum):
    filing_processed = "filing.processed"
    filing_corrected = "filing.corrected"


class WebhookCreateResponse(BaseModel):
    id: Annotated[str, Field(title="Id")]
    """
    Unique identifier for the webhook subscription.
    """
    url: Annotated[str, Field(title="Url")]
    """
    HTTPS URL where webhook payloads are delivered.
    """
    events: Annotated[list[Event], Field(title="Events")]
    """
    Event types this subscription listens for.
    """
    filing_types: Annotated[list[str] | None, Field(title="Filing Types")] = None
    """
    Filing types to filter events by. Null means all filing types.
    """
    is_active: Annotated[bool, Field(title="Is Active")]
    """
    Whether the subscription is currently active.
    """
    consecutive_failure_count: Annotated[int, Field(title="Consecutive Failure Count")]
    """
    Number of consecutive delivery failures. Resets to 0 on success or reactivation.
    """
    description: Annotated[str | None, Field(title="Description")] = None
    """
    Optional description of the webhook subscription.
    """
    created_at: Annotated[AwareDatetime, Field(title="Created At")]
    """
    Timestamp when the subscription was created.
    """
    updated_at: Annotated[AwareDatetime, Field(title="Updated At")]
    """
    Timestamp when the subscription was last updated.
    """
    secret: Annotated[str, Field(title="Secret")]
    """
    HMAC signing secret for verifying webhook payloads. Only returned on creation.
    """


class WebhookDeliveryResponse(BaseModel):
    id: Annotated[str, Field(title="Id")]
    """
    Unique identifier for the delivery attempt.
    """
    subscription_id: Annotated[str | None, Field(title="Subscription Id")] = None
    """
    ID of the webhook subscription this delivery belongs to.
    """
    event_type: Annotated[str, Field(title="Event Type")]
    """
    Event type that triggered this delivery.
    """
    payload: Annotated[dict[str, Any], Field(title="Payload")]
    """
    Full JSON payload that was sent to the webhook URL.
    """
    status: Annotated[str, Field(title="Status")]
    """
    Delivery status (e.g. delivered, failed, pending).
    """
    http_status: Annotated[int | None, Field(title="Http Status")] = None
    """
    HTTP status code returned by the webhook endpoint.
    """
    attempt_count: Annotated[int, Field(title="Attempt Count")]
    """
    Number of delivery attempts made so far.
    """
    next_retry_at: Annotated[AwareDatetime | None, Field(title="Next Retry At")] = None
    """
    Scheduled time for the next delivery retry, if applicable.
    """
    created_at: Annotated[AwareDatetime, Field(title="Created At")]
    """
    Timestamp when the delivery was first queued.
    """
    completed_at: Annotated[AwareDatetime | None, Field(title="Completed At")] = None
    """
    Timestamp when the delivery succeeded or was abandoned.
    """


class WebhookResponse(BaseModel):
    id: Annotated[str, Field(title="Id")]
    """
    Unique identifier for the webhook subscription.
    """
    url: Annotated[str, Field(title="Url")]
    """
    HTTPS URL where webhook payloads are delivered.
    """
    events: Annotated[list[Event], Field(title="Events")]
    """
    Event types this subscription listens for.
    """
    filing_types: Annotated[list[str] | None, Field(title="Filing Types")] = None
    """
    Filing types to filter events by. Null means all filing types.
    """
    is_active: Annotated[bool, Field(title="Is Active")]
    """
    Whether the subscription is currently active.
    """
    consecutive_failure_count: Annotated[int, Field(title="Consecutive Failure Count")]
    """
    Number of consecutive delivery failures. Resets to 0 on success or reactivation.
    """
    description: Annotated[str | None, Field(title="Description")] = None
    """
    Optional description of the webhook subscription.
    """
    created_at: Annotated[AwareDatetime, Field(title="Created At")]
    """
    Timestamp when the subscription was created.
    """
    updated_at: Annotated[AwareDatetime, Field(title="Updated At")]
    """
    Timestamp when the subscription was last updated.
    """


class WebhookUpdateRequest(BaseModel):
    url: Annotated[str | None, Field(title="Url")] = None
    events: Annotated[list[str] | None, Field(title="Events")] = None
    filing_types: Annotated[list[str] | None, Field(title="Filing Types")] = None
    is_active: Annotated[bool | None, Field(title="Is Active")] = None
    description: Annotated[str | None, Field(title="Description")] = None


class BoardMemberItem(BaseModel):
    name: Annotated[str, Field(title="Name")]
    """
    Name of the board member.
    """
    age: Annotated[int | None, Field(title="Age")] = None
    """
    Age of the board member as reported.
    """
    tenure_years: Annotated[int | None, Field(title="Tenure Years")] = None
    """
    Number of years serving on the board.
    """
    is_independent: Annotated[bool | None, Field(title="Is Independent")] = None
    """
    Whether the board member is classified as independent.
    """
    committees: Annotated[list[str] | None, Field(title="Committees")] = None
    """
    List of committee names this board member serves on.
    """
    committee_details: Annotated[list[CommitteeDetail] | None, Field(title="Committee Details")] = None
    """
    Committee memberships with chair designation.
    """


class BoardResponse(BaseModel):
    company: CompanyRef
    """
    Company reference.
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year for the board data.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    SEC accession number of the source DEF 14A filing.
    """
    members: Annotated[list[BoardMemberItem], Field(title="Members")]
    """
    List of board members, ordered alphabetically by name.
    """


class BreakdownData(BaseModel):
    parent: ParentInfo
    """
    Parent place info.
    """
    metric: MetricInfo
    """
    Metric metadata.
    """
    child_level: Annotated[str, Field(title="Child Level")]
    """
    Geographic level of child places.
    """
    year: Annotated[int, Field(title="Year")]
    """
    Data year.
    """
    dataset: Annotated[str, Field(title="Dataset")]
    """
    Dataset (acs1 or acs5).
    """
    survey_years: SurveyYears | None = None
    """
    Survey period (ACS 5-year only).
    """
    places: Annotated[list[ComparisonPlace], Field(title="Places")]
    """
    Child place values.
    """


class BreakdownResponse(BaseModel):
    data: BreakdownData
    pagination: PaginationMeta


class CensusTimeSeriesPoint(BaseModel):
    year: Annotated[int, Field(title="Year")]
    """
    Data year.
    """
    value: Annotated[float | None, Field(title="Value")] = None
    """
    Metric value, null if suppressed.
    """
    moe: Annotated[float | None, Field(title="Moe")] = None
    """
    Margin of error.
    """
    suppressed: Annotated[bool, Field(title="Suppressed")]
    """
    Whether this value was suppressed.
    """
    survey_years: SurveyYears | None = None
    """
    Survey period (ACS 5-year only).
    """


class ComparisonData(BaseModel):
    metric: MetricInfo
    """
    Metric metadata.
    """
    year: Annotated[int, Field(title="Year")]
    """
    Data year.
    """
    dataset: Annotated[str, Field(title="Dataset")]
    """
    Dataset (acs1 or acs5).
    """
    survey_years: SurveyYears | None = None
    """
    Survey period (ACS 5-year only).
    """
    places: Annotated[list[ComparisonPlace], Field(title="Places")]
    """
    Place values.
    """


class ComparisonResponse(BaseModel):
    data: ComparisonData
    pagination: PaginationMeta


class CompensationResponse(BaseModel):
    company: CompanyRef
    """
    Company reference.
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year for the compensation data.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    SEC accession number of the source DEF 14A filing.
    """
    executives: Annotated[list[ExecutiveCompensationItem], Field(title="Executives")]
    """
    List of executives and their compensation, ordered by total compensation descending.
    """
    pay_ratio: PayRatioItem | None = None
    """
    CEO-to-median pay ratio data, if available in the filing.
    """


class DataResponseBoardResponse(BaseModel):
    data: BoardResponse


class DataResponseCompensationResponse(BaseModel):
    data: CompensationResponse


class DataResponseFilingContentResponse(BaseModel):
    data: FilingContentResponse


class DataResponseFilingDetailResponse(BaseModel):
    data: FilingDetailResponse


class DataResponsePlaceDetail(BaseModel):
    data: PlaceDetail


class DataResponseRatioTimeSeriesResponse(BaseModel):
    data: RatioTimeSeriesResponse


class DataResponseSectionChangeResponse(BaseModel):
    data: SectionChangeResponse


class DataResponseSectionDetail(BaseModel):
    data: SectionDetail


class DataResponseTimeSeriesResponse(BaseModel):
    data: TimeSeriesResponse


class DataResponseWebhookCreateResponse(BaseModel):
    data: WebhookCreateResponse


class DataResponseWebhookResponse(BaseModel):
    data: WebhookResponse


class DataResponseListEventCategory(BaseModel):
    data: Annotated[list[EventCategory], Field(title="Data")]


class DataResponseListGeographyLevel(BaseModel):
    data: Annotated[list[GeographyLevel], Field(title="Data")]


class DataResponseListMetricSummary(BaseModel):
    data: Annotated[list[MetricSummary], Field(title="Data")]


class DataResponseListWebhookResponse(BaseModel):
    data: Annotated[list[WebhookResponse], Field(title="Data")]


class FieldsResponse(BaseModel):
    income: StatementFields
    """
    Income statement fields.
    """
    balance_sheet: StatementFields
    """
    Balance sheet fields.
    """
    cash_flow: StatementFields
    """
    Cash flow statement fields.
    """


class FinancialStatementResponse(BaseModel):
    company: CompanySummary
    """
    Company identification details.
    """
    statement: Annotated[Statement, Field(title="Statement")]
    """
    Statement type using API-facing hyphenated values.
    """
    period: Annotated[Period, Field(title="Period")]
    """
    Reporting period type.
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year of the reported statement.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter (1-4) for quarterly statements, null for annual.
    """
    fiscal_year_end: Annotated[str | None, Field(title="Fiscal Year End")] = None
    """
    Period end date in YYYY-MM-DD format.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source filing.
    """
    currency: Annotated[str, Field(title="Currency")]
    """
    ISO 4217 currency code for monetary values (e.g. 'USD').
    """
    line_items: Annotated[dict[str, float | None], Field(title="Line Items")]
    """
    Canonical field name to value mapping. Individual field units vary (revenue in currency units, shares as counts).

    **Income statement fields**: revenue, cost_of_revenue, gross_profit, operating_expenses, research_and_development, selling_general_admin, operating_income, interest_expense, interest_income, pre_tax_income, income_tax_expense, net_income, eps_basic, eps_diluted, shares_basic, shares_diluted.

    **Balance sheet fields**: total_assets, current_assets, cash_and_equivalents, accounts_receivable, inventory, non_current_assets, property_plant_equipment, goodwill, intangible_assets, total_liabilities, current_liabilities, accounts_payable, short_term_debt, non_current_liabilities, long_term_debt, total_equity, common_shares_outstanding.

    **Cash flow fields**: operating_cash_flow, investing_cash_flow, financing_cash_flow, net_change_in_cash, capital_expenditures, dividends_paid, share_repurchases.

    **Bank-specific fields** (income statement, populated only for bank/financial institution filings): net_interest_income, interest_and_dividend_income, noninterest_income, provision_for_credit_losses, noninterest_expense.

    Use GET /v1/us/sec/financials/fields for machine-readable field metadata.
    """
    metadata: StatementMetadata
    """
    Data quality and source metadata.
    """


class HTTPValidationError(BaseModel):
    detail: Annotated[list[ValidationError] | None, Field(title="Detail")] = None


class InsiderHoldingListItem(BaseModel):
    person: InsiderHoldingPerson
    """
    Insider and their holdings.
    """
    filing_date: Annotated[date, Field(title="Filing Date")]
    """
    Date the Form 4 was filed with the SEC.
    """
    filing_accession: Annotated[str, Field(title="Filing Accession")]
    """
    Accession number of the source Form 4 filing.
    """


class MetricDetail(BaseModel):
    canonical_name: Annotated[str, Field(title="Canonical Name")]
    """
    Machine-readable metric identifier.
    """
    display_name: Annotated[str, Field(title="Display Name")]
    """
    Human-readable metric name.
    """
    category: Annotated[str, Field(title="Category")]
    """
    Metric category (e.g. income, housing).
    """
    unit: Annotated[str, Field(title="Unit")]
    """
    Unit of measurement (dollars, percent, people, etc.).
    """
    is_computed: Annotated[bool, Field(title="Is Computed")]
    """
    Whether this metric is derived from other Census variables.
    """
    moe_formula_type: Annotated[str | None, Field(title="Moe Formula Type")] = None
    """
    MOE formula type (direct, ratio, proportion, etc.).
    """
    notes: Annotated[str | None, Field(title="Notes")] = None
    """
    Additional notes about this metric.
    """
    latest_year: LatestYear
    source_variables: Annotated[list[SourceVariable], Field(title="Source Variables")]
    """
    Census API variables that map to this metric.
    """


class PaginatedResponseBeneficialOwnershipItem(BaseModel):
    data: Annotated[list[BeneficialOwnershipItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseCompanyListItem(BaseModel):
    data: Annotated[list[CompanyListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseCompanyPositionChange(BaseModel):
    data: Annotated[list[CompanyPositionChange], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseDataQualityReportResponse(BaseModel):
    data: Annotated[list[DataQualityReportResponse], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseEntityResponse(BaseModel):
    data: Annotated[list[EntityResponse], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseEventListItem(BaseModel):
    data: Annotated[list[EventListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseFilingListItem(BaseModel):
    data: Annotated[list[FilingListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseFundHoldingListItem(BaseModel):
    data: Annotated[list[FundHoldingListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseFundListItem(BaseModel):
    data: Annotated[list[FundListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseFundPositionChange(BaseModel):
    data: Annotated[list[FundPositionChange], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseHolderListItem(BaseModel):
    data: Annotated[list[HolderListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseInsiderHoldingListItem(BaseModel):
    data: Annotated[list[InsiderHoldingListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseInsiderTradeListItem(BaseModel):
    data: Annotated[list[InsiderTradeListItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponsePlaceSummary(BaseModel):
    data: Annotated[list[PlaceSummary], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseProxyVoteItem(BaseModel):
    data: Annotated[list[ProxyVoteItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseScreenerResultItem(BaseModel):
    data: Annotated[list[ScreenerResultItem], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseSectionSummary(BaseModel):
    data: Annotated[list[SectionSummary], Field(title="Data")]
    pagination: PaginationMeta


class PaginatedResponseWebhookDeliveryResponse(BaseModel):
    data: Annotated[list[WebhookDeliveryResponse], Field(title="Data")]
    pagination: PaginationMeta


class PlaceMetrics(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    FIPS code.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Place name.
    """
    level: Annotated[str, Field(title="Level")]
    """
    Geographic level.
    """
    year: Annotated[int, Field(title="Year")]
    """
    Data year.
    """
    dataset: Annotated[str, Field(title="Dataset")]
    """
    Dataset (acs1 or acs5).
    """
    survey_years: SurveyYears | None = None
    """
    Survey period (ACS 5-year only).
    """
    metrics: Annotated[list[MetricValue], Field(title="Metrics")]
    """
    Metric values.
    """


class RatioResponse(BaseModel):
    company: CompanySummary
    """
    Company identification details.
    """
    period: Annotated[Period, Field(title="Period")]
    """
    Reporting period type.
    """
    fiscal_year: Annotated[int, Field(title="Fiscal Year")]
    """
    Fiscal year of the reported ratios.
    """
    fiscal_quarter: Annotated[int | None, Field(title="Fiscal Quarter")] = None
    """
    Fiscal quarter (1-4) for quarterly ratios, null for annual.
    """
    ratios: RatioValues
    """
    Computed financial ratios for this period.
    """
    metadata: RatioMetadata
    """
    Source metadata for the ratio computation.
    """


class SearchPaginatedResponse(BaseModel):
    data: Annotated[list[SearchResult], Field(title="Data")]
    pagination: SearchPaginationMeta


class SectionList(BaseModel):
    accession_number: Annotated[str, Field(title="Accession Number")]
    """
    SEC accession number of the filing.
    """
    cik: Annotated[str, Field(title="Cik")]
    """
    CIK of the filing company.
    """
    company_name: Annotated[str | None, Field(title="Company Name")] = None
    """
    Name of the filing company.
    """
    company_ticker: Annotated[str | None, Field(title="Company Ticker")] = None
    """
    Ticker symbol of the filing company.
    """
    filing_type: Annotated[str, Field(title="Filing Type")]
    """
    SEC filing type (e.g. '10-K', '10-Q').
    """
    filed_at: Annotated[AwareDatetime | None, Field(title="Filed At")] = None
    """
    Date and time the filing was submitted to the SEC.
    """
    period_of_report: Annotated[date | None, Field(title="Period Of Report")] = None
    """
    Period end date covered by the filing.
    """
    sections: Annotated[list[SectionListItem], Field(title="Sections")]
    """
    List of extracted sections for this filing.
    """


class TimeSeries(BaseModel):
    fips: Annotated[str, Field(title="Fips")]
    """
    FIPS code.
    """
    name: Annotated[str, Field(title="Name")]
    """
    Place name.
    """
    metric: MetricInfo
    """
    Metric metadata.
    """
    dataset: Annotated[str, Field(title="Dataset")]
    """
    Dataset (acs1 or acs5).
    """
    series: Annotated[list[CensusTimeSeriesPoint], Field(title="Series")]
    """
    Time series data points.
    """


class DataResponseFieldsResponse(BaseModel):
    data: FieldsResponse


class DataResponseFinancialStatementResponse(BaseModel):
    data: FinancialStatementResponse


class DataResponseMetricDetail(BaseModel):
    data: MetricDetail


class DataResponsePlaceMetrics(BaseModel):
    data: PlaceMetrics


class DataResponseRatioResponse(BaseModel):
    data: RatioResponse


class DataResponseSectionList(BaseModel):
    data: SectionList


class DataResponseTimeSeries(BaseModel):
    data: TimeSeries
