> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Run options-focused investment debate

> Run a complete debate with enhanced options context.

Same 3-agent (Bull/Bear/Arbiter) workflow as the standard debate, but
the agents receive additional options-specific context:

- **IV surface**: Term structure shape, skew ratio, ATM IV percentile
- **Options flow**: Unusual activity, signal direction and strength
- **Options confluence**: Standalone options score (0-100)
- **Strategy recommendation**: Best options strategy for current setup
- **Quality gates**: Spread quality, IV floor, theta drag, OI minimum

The bull agent frames options as opportunity (cheap vol, favorable skew).
The bear agent challenges with options risks (IV crush, theta drag, liquidity).
The arbiter integrates options confluence alongside equity confluence.

## Performance

Same as standard debate: 15-30 seconds.



## OpenAPI

````yaml /api/openapi.json post /api/graph/v1/options/debate/{symbol}
openapi: 3.1.0
info:
  title: Sequency Graph API
  description: >

    # Sequency Graph-Native Trading API


    Graph-native API for trading intelligence, built on FalkorDB.


    ## Features


    - **Screener**: Filter stocks using graph-native queries with relationship
    expansion

    - **Stock Detail**: Complete stock context with all relationships

    - **Confluence Scoring**: Setup quality assessment with weighted components

    - **Strategy Matching**: Find matching options strategies via graph
    traversal

    - **Market Context**: Current market-wide context for trading decisions


    ## Data Sources


    All data is sourced from the FalkorDB knowledge graph, populated by:

    - Pattern detector (Go) - Technical indicators, patterns

    - Graph sync service - Levels, volume profiles, news, day classification
  version: 1.0.0
servers: []
security: []
paths:
  /api/graph/v1/options/debate/{symbol}:
    post:
      tags:
        - Debate
      summary: Run options-focused investment debate
      description: >-
        Run a complete debate with enhanced options context.


        Same 3-agent (Bull/Bear/Arbiter) workflow as the standard debate, but

        the agents receive additional options-specific context:


        - **IV surface**: Term structure shape, skew ratio, ATM IV percentile

        - **Options flow**: Unusual activity, signal direction and strength

        - **Options confluence**: Standalone options score (0-100)

        - **Strategy recommendation**: Best options strategy for current setup

        - **Quality gates**: Spread quality, IV floor, theta drag, OI minimum


        The bull agent frames options as opportunity (cheap vol, favorable
        skew).

        The bear agent challenges with options risks (IV crush, theta drag,
        liquidity).

        The arbiter integrates options confluence alongside equity confluence.


        ## Performance


        Same as standard debate: 15-30 seconds.
      operationId: run_options_debate_api_graph_v1_options_debate__symbol__post
      parameters:
        - name: symbol
          in: path
          required: true
          schema:
            type: string
            title: Symbol
        - name: timeframe
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/app__models__debate__Timeframe'
            description: Trading timeframe
            default: swing
          description: Trading timeframe
        - name: risk_appetite
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RiskAppetite'
            description: Risk appetite level
            default: moderate
          description: Risk appetite level
        - name: model
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              LLM model override (e.g. 'gpt-5.2', 'grok-4-1-fast-reasoning').
              None = default.
            title: Model
          description: >-
            LLM model override (e.g. 'gpt-5.2', 'grok-4-1-fast-reasoning'). None
            = default.
      responses:
        '200':
          description: Options debate completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateResponse'
        '404':
          description: Symbol not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '504':
          description: Debate timeout
components:
  schemas:
    app__models__debate__Timeframe:
      type: string
      enum:
        - day
        - swing
        - position
        - investment
      title: Timeframe
      description: Trading timeframe for debate context.
    RiskAppetite:
      type: string
      enum:
        - conservative
        - moderate
        - aggressive
      title: RiskAppetite
      description: Risk appetite level for position sizing guidance.
    DebateResponse:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When debate completed
        request:
          $ref: '#/components/schemas/DebateRequest'
          description: Original request parameters
        debate_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Debate Id
          description: UUID of persisted debate run
        bull_thesis:
          $ref: '#/components/schemas/BullishThesis'
          description: Bull agent thesis
        bear_thesis:
          $ref: '#/components/schemas/BearishThesis'
          description: Bear agent counter-thesis
        verdict:
          $ref: '#/components/schemas/ArbiterVerdict'
          description: Arbiter final verdict
        market_context:
          $ref: '#/components/schemas/MarketDataContext'
          description: Market data context used in debate
        total_duration_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Duration Ms
          description: Total debate duration in milliseconds
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
          description: Total tokens consumed across all agents
        validation_passed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Validation Passed
          description: Whether all critical validations passed
        validation_blocked:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Validation Blocked
          description: True if debate was not persisted due to validation failure
        quality_score:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Quality Score
          description: Overall quality score (0-100)
        validation_issues:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Validation Issues
          description: List of validation issues found
        historical_analogs_status:
          anyOf:
            - type: string
              enum:
                - unavailable
                - empty
                - found
            - type: 'null'
          title: Historical Analogs Status
          description: Status of historical analog retrieval
        proposed_cards:
          items:
            $ref: '#/components/schemas/ProposedActionCard'
          type: array
          title: Proposed Cards
        no_viable_plays:
          type: boolean
          title: No Viable Plays
          default: false
        no_viable_plays_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: No Viable Plays Reason
      type: object
      required:
        - symbol
        - request
        - bull_thesis
        - bear_thesis
        - verdict
        - market_context
      title: DebateResponse
      description: Complete debate response with all agent outputs.
      example:
        bear_thesis:
          confidence: 58
          headline: Extended valuation and earnings risk
          strength: MODERATE
          symbol: NVDA
        bull_thesis:
          confidence: 72
          headline: Strong momentum with volume confirmation
          strength: STRONG
          symbol: NVDA
        request:
          include_historical: true
          risk_appetite: moderate
          symbol: NVDA
          timeframe: swing
          verbose: false
        symbol: NVDA
        timestamp: '2026-01-29T10:30:00Z'
        verdict:
          confidence: 65
          deciding_factors:
            - Technical momentum outweighs valuation concern
            - FPT suggests favorable timing
          key_risk: Earnings in 2 weeks
          timing_recommendation: Enter on pullback to support
          verdict: BUY
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DebateRequest:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        timeframe:
          $ref: '#/components/schemas/app__models__debate__Timeframe'
          description: Trading timeframe
          default: swing
        risk_appetite:
          $ref: '#/components/schemas/RiskAppetite'
          description: Risk appetite level
          default: moderate
        include_historical:
          type: boolean
          title: Include Historical
          description: Include historical analog search
          default: true
        verbose:
          type: boolean
          title: Verbose
          description: Include full agent narratives in response
          default: false
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            LLM model ID override (e.g. 'gpt-5.2', 'grok-4-1-fast-reasoning').
            All three agents use this model. None = default.
      type: object
      required:
        - symbol
      title: DebateRequest
      description: Request to initiate a debate analysis.
    BullishThesis:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When thesis was generated
        headline:
          type: string
          maxLength: 100
          title: Headline
          description: One-line bullish thesis headline
        narrative:
          type: string
          title: Narrative
          description: Full bullish narrative (2-4 paragraphs)
        key_catalysts:
          items:
            type: string
          type: array
          maxItems: 5
          minItems: 1
          title: Key Catalysts
          description: Top catalysts supporting bullish view
        evidence:
          items:
            $ref: '#/components/schemas/EvidenceItem'
          type: array
          minItems: 1
          title: Evidence
          description: Evidence items supporting the thesis
        historical_analogs:
          items:
            $ref: '#/components/schemas/app__models__debate__HistoricalAnalog'
          type: array
          title: Historical Analogs
          description: Similar historical setups with positive outcomes
        suggested_entry:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Suggested Entry
          description: Suggested entry price
        target_price:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Target Price
          description: Primary price target
        stop_loss:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Stop Loss
          description: Suggested stop loss level
        confidence:
          type: number
          maximum: 100
          minimum: 0
          title: Confidence
          description: Thesis confidence score (0-100)
        strength:
          $ref: '#/components/schemas/ThesisStrength'
          description: Qualitative strength assessment
        model_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Used
          description: LLM model used for generation
        tokens_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens Used
          description: Total tokens consumed
      type: object
      required:
        - symbol
        - headline
        - narrative
        - key_catalysts
        - evidence
        - confidence
        - strength
      title: BullishThesis
      description: |-
        Bullish thesis generated by Bull Agent.

        Uses inductive reasoning to build a case from evidence patterns.
    BearishThesis:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When counter-thesis was generated
        headline:
          type: string
          maxLength: 100
          title: Headline
          description: One-line bearish thesis headline
        narrative:
          type: string
          title: Narrative
          description: Full bearish narrative challenging bull case
        bull_thesis_weaknesses:
          items:
            type: string
          type: array
          maxItems: 5
          minItems: 1
          title: Bull Thesis Weaknesses
          description: Specific weaknesses in the bull thesis
        risk_factors:
          items:
            $ref: '#/components/schemas/RiskFactor'
          type: array
          minItems: 1
          title: Risk Factors
          description: Identified risk factors
        evidence:
          items:
            $ref: '#/components/schemas/EvidenceItem'
          type: array
          minItems: 1
          title: Evidence
          description: Evidence supporting bearish view
        historical_analogs:
          items:
            $ref: '#/components/schemas/app__models__debate__HistoricalAnalog'
          type: array
          title: Historical Analogs
          description: Similar historical setups with negative outcomes
        bear_case_target:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Bear Case Target
          description: Downside price target if bear case plays out
        probability_of_failure:
          type: number
          maximum: 100
          minimum: 0
          title: Probability Of Failure
          description: Estimated probability bull thesis fails (0-100)
        confidence:
          type: number
          maximum: 100
          minimum: 0
          title: Confidence
          description: Counter-thesis confidence score (0-100)
        strength:
          $ref: '#/components/schemas/ThesisStrength'
          description: Qualitative strength assessment
        model_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Used
          description: LLM model used for generation
        tokens_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tokens Used
          description: Total tokens consumed
      type: object
      required:
        - symbol
        - headline
        - narrative
        - bull_thesis_weaknesses
        - risk_factors
        - evidence
        - probability_of_failure
        - confidence
        - strength
      title: BearishThesis
      description: |-
        Bearish counter-thesis generated by Bear Agent.

        Uses inversion reasoning to challenge bull thesis and find risks.
    ArbiterVerdict:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When verdict was rendered
        verdict:
          $ref: '#/components/schemas/Verdict'
          description: Final verdict on trade viability
        confidence:
          type: number
          maximum: 100
          minimum: 0
          title: Confidence
          description: Verdict confidence score (0-100)
        bull_thesis_strength:
          type: number
          maximum: 100
          minimum: 0
          title: Bull Thesis Strength
          description: Bull thesis strength assessment (0-100)
        bear_thesis_strength:
          type: number
          maximum: 100
          minimum: 0
          title: Bear Thesis Strength
          description: Bear thesis strength assessment (0-100)
        thesis_balance:
          type: string
          enum:
            - bull_dominant
            - balanced
            - bear_dominant
          title: Thesis Balance
          description: Which thesis dominates the analysis
        deciding_factors:
          items:
            type: string
          type: array
          maxItems: 5
          minItems: 1
          title: Deciding Factors
          description: Key factors that determined the verdict
        unresolved_concerns:
          items:
            type: string
          type: array
          title: Unresolved Concerns
          description: Concerns that couldn't be fully resolved
        timing_recommendation:
          type: string
          title: Timing Recommendation
          description: Timing guidance based on FPT analysis
        position_size_modifier:
          type: number
          maximum: 2
          minimum: 0
          title: Position Size Modifier
          description: Position size multiplier (1.0 = standard)
          default: 1
        key_risk:
          type: string
          title: Key Risk
          description: Single most important risk to monitor
        invalidation_level:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Invalidation Level
          description: Price level that would invalidate the thesis
        executive_summary:
          type: string
          maxLength: 500
          title: Executive Summary
          description: Concise summary for action card
        conviction_narrative:
          anyOf:
            - type: string
            - type: 'null'
          title: Conviction Narrative
          description: >-
            1-2 sentence conviction narrative for the ConvictionTile. Summarize
            why conviction is high/low based on the component analysis.
        trade_direction:
          anyOf:
            - type: string
            - type: 'null'
          title: Trade Direction
          description: 'Trade direction: LONG, SHORT, or NEUTRAL'
        long_entry:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Long Entry
          description: Long entry price level
        long_stop:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Long Stop
          description: Long stop loss level
        long_target:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Long Target
          description: Long price target
        long_risk_reward:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Long Risk Reward
          description: Long trade risk/reward ratio
        long_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Long Rationale
          description: Rationale for long setup
        short_entry:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Short Entry
          description: Short/put entry price level
        short_stop:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Short Stop
          description: Short/put stop loss level
        short_target:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Short Target
          description: Short/put price target
        short_risk_reward:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Short Risk Reward
          description: Short/put risk/reward ratio
        short_instrument:
          anyOf:
            - type: string
            - type: 'null'
          title: Short Instrument
          description: 'Short instrument: PUT or SHORT_EQUITY'
        short_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Short Rationale
          description: Rationale for short/put setup
        day_trade_recommendation:
          anyOf:
            - type: string
            - type: 'null'
          title: Day Trade Recommendation
          description: >-
            Specific day trade recommendation (e.g., 'BUY PUTS at $X with stop
            $Y, target $Z')
        swing_trade_recommendation:
          anyOf:
            - type: string
            - type: 'null'
          title: Swing Trade Recommendation
          description: Specific swing trade recommendation
        orb_structure:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb Structure
          description: ORB structure informing the decision
        orb_signal_strength:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb Signal Strength
          description: 'ORB signal strength: strong, moderate, weak'
        fpt_to_target_days:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Fpt To Target Days
          description: FPT median days to target
        fpt_probability:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Fpt Probability
          description: FPT probability of reaching target
        optimal_timeframe:
          anyOf:
            - type: string
            - type: 'null'
          title: Optimal Timeframe
          description: 'Optimal timeframe for trade: day, swing, position'
        recommended_contract:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Recommended Contract
          description: Recommended options contract (call for LONG, put for SHORT)
        alternative_contracts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Alternative Contracts
          description: Alternative contract options (max 2)
        contract_selection_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Selection Rationale
          description: Why this contract was selected or why unavailable
        model_used:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Used
          description: LLM model used for arbitration
        total_tokens_used:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens Used
          description: Total tokens across all agents
      type: object
      required:
        - symbol
        - verdict
        - confidence
        - bull_thesis_strength
        - bear_thesis_strength
        - thesis_balance
        - deciding_factors
        - timing_recommendation
        - key_risk
        - executive_summary
      title: ArbiterVerdict
      description: >-
        Final verdict from Arbiter agent.


        Synthesizes bull and bear arguments with FPT timing into actionable
        guidance.
    MarketDataContext:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Stock ticker symbol
        current_price:
          type: number
          minimum: 0
          title: Current Price
          description: Current price
        change_pct:
          type: number
          title: Change Pct
          description: Day change percentage
        volume_vs_avg:
          type: number
          minimum: 0
          title: Volume Vs Avg
          description: Volume relative to 20-day avg
        bullish_confluence:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bullish Confluence
          description: Bullish confluence score
        bearish_confluence:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bearish Confluence
          description: Bearish confluence score
        ib_high:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Ib High
          description: Initial Balance high (9:30-10:30 ET)
        ib_low:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Ib Low
          description: Initial Balance low (9:30-10:30 ET)
        session_high:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Session High
          description: Session high (9:30 AM - now)
        session_low:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Session Low
          description: Session low (9:30 AM - now)
        session_open:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Session Open
          description: Session opening price (9:30 AM)
        orb_5m_high:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 5M High
          description: 5-minute ORB high (9:30-9:35 ET)
        orb_5m_low:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 5M Low
          description: 5-minute ORB low (9:30-9:35 ET)
        orb_15m_high:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 15M High
          description: 15-minute ORB high (9:30-9:45 ET)
        orb_15m_low:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 15M Low
          description: 15-minute ORB low (9:30-9:45 ET)
        orb_30m_high:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 30M High
          description: 30-minute ORB high (9:30-10:00 ET)
        orb_30m_low:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Orb 30M Low
          description: 30-minute ORB low (9:30-10:00 ET)
        orb_5m_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb 5M Status
          description: >-
            5m ORB status:
            inside|breakout_up|breakout_down|failed_breakout_up|failed_breakout_down
        orb_15m_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb 15M Status
          description: >-
            15m ORB status:
            inside|breakout_up|breakout_down|failed_breakout_up|failed_breakout_down
        orb_30m_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb 30M Status
          description: >-
            30m ORB status:
            inside|breakout_up|breakout_down|failed_breakout_up|failed_breakout_down
        orb_structure:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb Structure
          description: >-
            Derived ORB structure:
            bull_trap|bear_trap|breakout_held_up|breakout_held_down|range_bound
        orb_directional_bias:
          anyOf:
            - type: string
            - type: 'null'
          title: Orb Directional Bias
          description: 'ORB directional bias: bullish|bearish|neutral'
        pattern_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Pattern Description
          description: Current pattern description
        key_levels:
          items:
            type: string
          type: array
          title: Key Levels
          description: Key support/resistance levels
        fpt_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Fpt Summary
          description: FPT timing summary
        timeframe_fit:
          anyOf:
            - type: string
            - type: 'null'
          title: Timeframe Fit
          description: Best timeframe for trade
        news_sentiment_score:
          anyOf:
            - type: number
              maximum: 1
              minimum: -1
            - type: 'null'
          title: News Sentiment Score
          description: Aggregated news sentiment score (-1 to 1)
        news_sentiment_label:
          anyOf:
            - type: string
            - type: 'null'
          title: News Sentiment Label
          description: Sentiment classification (Bullish, Bearish, Neutral, etc.)
        news_articles_analyzed:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: News Articles Analyzed
          description: Number of relevant articles analyzed
        news_top_headlines:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: News Top Headlines
          description: Top recent headlines for context
        news_scoring_method:
          anyOf:
            - type: string
            - type: 'null'
          title: News Scoring Method
          description: 'Scoring method used: finbert, claude_refined, keyword'
        news_sentiment_context:
          anyOf:
            - type: string
            - type: 'null'
          title: News Sentiment Context
          description: Claude reasoning summary for context-aware sentiment
        earnings_days_until:
          anyOf:
            - type: integer
            - type: 'null'
          title: Earnings Days Until
          description: Days until next earnings announcement
        earnings_cleared:
          type: boolean
          title: Earnings Cleared
          description: True if recent earnings have been digested (>3 days ago)
          default: true
        earnings_surprise_category:
          anyOf:
            - type: string
            - type: 'null'
          title: Earnings Surprise Category
          description: >-
            Last earnings surprise category (BLOWOUT_BEAT, SOLID_BEAT, INLINE,
            MISS, BLOWOUT_MISS)
        earnings_consecutive_beats:
          anyOf:
            - type: integer
            - type: 'null'
          title: Earnings Consecutive Beats
          description: Number of consecutive earnings beats (negative = misses)
        earnings_beat_rate_8q:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Earnings Beat Rate 8Q
          description: Beat rate over last 8 quarters (0-1)
        earnings_surprise_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Earnings Surprise Pct
          description: Last EPS surprise percentage
        pe_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Pe Ratio
          description: P/E ratio (TTM)
        forward_pe:
          anyOf:
            - type: number
            - type: 'null'
          title: Forward Pe
          description: Forward P/E ratio
        profit_margin:
          anyOf:
            - type: number
            - type: 'null'
          title: Profit Margin
          description: Profit margin (decimal, e.g. 0.25 = 25%)
        revenue_growth_yoy:
          anyOf:
            - type: number
            - type: 'null'
          title: Revenue Growth Yoy
          description: Revenue growth YoY (decimal)
        earnings_growth_yoy:
          anyOf:
            - type: number
            - type: 'null'
          title: Earnings Growth Yoy
          description: Earnings growth YoY (decimal)
        debt_to_equity:
          anyOf:
            - type: number
            - type: 'null'
          title: Debt To Equity
          description: Debt to equity ratio
        analyst_consensus:
          anyOf:
            - type: string
            - type: 'null'
          title: Analyst Consensus
          description: Analyst consensus (Strong Buy, Buy, Hold, Sell, Strong Sell)
        analyst_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Analyst Score
          description: Weighted analyst score (1-5, 5=Strong Buy)
        analyst_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Analyst Count
          description: Number of covering analysts
        analyst_target_upside:
          anyOf:
            - type: number
            - type: 'null'
          title: Analyst Target Upside
          description: Analyst target upside percentage
        insider_sentiment:
          anyOf:
            - type: string
            - type: 'null'
          title: Insider Sentiment
          description: Insider sentiment (buying, selling, neutral)
        pulse_bull:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Pulse Bull
          description: 'Pulse bullish score (0-100): real-time intraday conviction'
        pulse_bear:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Pulse Bear
          description: 'Pulse bearish score (0-100): real-time intraday conviction'
        pulse_net:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Pulse Net
          description: 'Pulse net score (-100 to +100): pulse_bull - pulse_bear'
        pulse_bias:
          anyOf:
            - type: string
            - type: 'null'
          title: Pulse Bias
          description: >-
            Pulse directional bias:
            STRONG_LONG/MOD_LONG/NEUTRAL/MOD_SHORT/STRONG_SHORT
        pricing_edge_bull:
          anyOf:
            - type: number
              maximum: 10
              minimum: 0
            - type: 'null'
          title: Pricing Edge Bull
          description: Pricing edge bull score (0-10, from binomial pricer)
        greek_alignment_bull:
          anyOf:
            - type: number
              maximum: 10
              minimum: 0
            - type: 'null'
          title: Greek Alignment Bull
          description: Greek alignment bull score (0-10, based on VIX regime)
        bullish_confluence_v5:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bullish Confluence V5
          description: V5 bullish confluence score (0-100). None when v5 unavailable.
        bearish_confluence_v5:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bearish Confluence V5
          description: V5 bearish confluence score (0-100). None when v5 unavailable.
        net_confluence_v5:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Net Confluence V5
          description: V5 net confluence (-100 to +100). None when v5 unavailable.
        confluence_version:
          anyOf:
            - type: string
              enum:
                - v5
                - v5_partial
                - v4.3.1
                - v4.2
                - v5_reconstructed
                - v5_partial_reconstructed
                - v4.3.1_reconstructed
                - v4.2_reconstructed
                - reconstructed_unknown
            - type: 'null'
          title: Confluence Version
          description: >-
            Confluence generation that produced
            bullish/bearish/net_confluence_v5. Derived at the orchestrator
            boundary from stock.confluence_v5 completeness — see orchestrator.py
            edits. NOT a passthrough of Stock.scoring_version (which is a public
            API field whose values must stay stable). Used by
            debate_outcome_writer to emit a row-level lineage tag into
            ClickHouse. Tracks confluence ONLY — not
            Pulse/Momentum/Entry/Conviction. Adding a new generation requires
            updating this Literal first. The `*_reconstructed` and
            `reconstructed_unknown` variants are emitted by the nightly Pass 3
            filler (signal_outcome_filler.py); they preserve source-generation
            lineage when score_history carries it (post-#491) or fall back to
            `reconstructed_unknown`. The bare legacy `reconstructed` literal is
            intentionally NOT in this Literal — new code must not emit it.
        lineage_warnings:
          items:
            type: string
          type: array
          title: Lineage Warnings
          description: >-
            Lineage contamination warnings (#527). Empty list = no warnings
            detected. Vocabulary frozen at
            api/app/services/debate/lineage_warnings.py.
        bullish_entry_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Bullish Entry Score
          description: Bullish entry score 0-100 (intraday timing)
        bearish_entry_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Bearish Entry Score
          description: Bearish entry score 0-100 (intraday timing)
        net_entry_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Net Entry Score
          description: 'Net entry score (-100 to +100): bullish - bearish'
        entry_score_completeness:
          anyOf:
            - type: number
            - type: 'null'
          title: Entry Score Completeness
          description: Entry score completeness 0.0-1.0
        entry_gates_passed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Entry Gates Passed
          description: Whether all entry quality gates passed
        entry_failed_gates:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Entry Failed Gates
          description: List of failed entry quality gate names
        entry_gex_modifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Entry Gex Modifier
          description: 'GEX regime modifier: long_gamma, short_gamma, or empty'
        gex_regime:
          anyOf:
            - type: string
            - type: 'null'
          title: Gex Regime
          description: 'GEX regime: positive, negative, or neutral'
        gex_proximity:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Gex Proximity
          description: GEX proximity to gamma flip strike (0-1, 1=at flip)
        net_vanna:
          anyOf:
            - type: number
            - type: 'null'
          title: Net Vanna
          description: Net vanna exposure (dollar value)
        net_charm:
          anyOf:
            - type: number
            - type: 'null'
          title: Net Charm
          description: Net charm exposure (dollar value)
        iv_slope_direction:
          anyOf:
            - type: string
            - type: 'null'
          title: Iv Slope Direction
          description: 'IV slope direction: rising, falling, or stable'
        daily_expected_move:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Daily Expected Move
          description: Daily expected move as percentage (from ATM IV)
        options_confluence_score:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Options Confluence Score
          description: Standalone options confluence score (0-100)
        best_options_strategy:
          anyOf:
            - type: string
            - type: 'null'
          title: Best Options Strategy
          description: Best options strategy recommendation
        iv_percentile:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Iv Percentile
          description: IV percentile vs 52-week range (0-100)
        iv_rank:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Iv Rank
          description: IV rank vs 52-week high/low (0-100)
        put_call_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Put Call Ratio
          description: Put/call volume ratio
        unusual_options_activity:
          type: boolean
          title: Unusual Options Activity
          description: Flagged for unusual options activity
          default: false
        theta_drag_15d:
          anyOf:
            - type: number
            - type: 'null'
          title: Theta Drag 15D
          description: 15-day theta drag as % of premium
        iv_surface_shape:
          anyOf:
            - type: string
            - type: 'null'
          title: Iv Surface Shape
          description: 'IV term structure shape: contango, backwardation, flat, humped'
        iv_skew_ratio:
          anyOf:
            - type: number
            - type: 'null'
          title: Iv Skew Ratio
          description: Put/call IV skew ratio (>1 = put premium)
        options_flow_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Options Flow Summary
          description: Summary of recent options flow signals
        dte_scores:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Dte Scores
          description: Top 3 expirations with DTE evaluator scores
        best_dte:
          anyOf:
            - type: integer
            - type: 'null'
          title: Best Dte
          description: Highest-scoring expiration's DTE
        best_dte_composite:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Best Dte Composite
          description: Best expiration's composite score (0-100)
        best_dte_edge_ratio:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Best Dte Edge Ratio
          description: Best expiration's edge ratio sub-score
        best_dte_rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Best Dte Rationale
          description: 1-sentence natural language summary of best DTE
        dte_evaluation_timeframe:
          anyOf:
            - type: string
            - type: 'null'
          title: Dte Evaluation Timeframe
          description: Timeframe used for DTE evaluation
        dte_crosses_catalyst:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Dte Crosses Catalyst
          description: Whether best DTE crosses earnings/FOMC/OPEX
        conviction_confidence:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Confidence
          description: >-
            Conviction confidence % (0-100): how reliable the confluence scores
            are
        acceptance_gates_passing:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Acceptance Gates Passing
          description: Whether all scoring acceptance gates are currently passing
        acceptance_gates_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Acceptance Gates Summary
          description: Brief summary of acceptance gate results (e.g. '5/6 gates passing')
        acceptance_failed_gates:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Acceptance Failed Gates
          description: Names of failing acceptance gates, if any
        cot_equity_crowding_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Cot Equity Crowding State
          description: >-
            ES Leveraged Fund positioning:
            crowded_long/extended_long/neutral/extended_short/crowded_short
        cot_equity_crowding_pctile:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cot Equity Crowding Pctile
          description: ES Leveraged Fund net positioning 3-year percentile rank
        cot_equity_direction:
          anyOf:
            - type: string
            - type: 'null'
          title: Cot Equity Direction
          description: 'ES Leveraged Fund positioning direction: building/unwinding/stable'
        cot_vol_supply_demand_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Cot Vol Supply Demand State
          description: 'VIX Dealer positioning: normal/elevated_demand/stress_absorption'
        cot_vol_supply_demand_pctile:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cot Vol Supply Demand Pctile
          description: VIX Dealer net positioning 3-year percentile rank
        cot_nq_es_spread_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Cot Nq Es Spread State
          description: 'NQ-ES Leveraged Fund spread: growth_crowded/neutral/value_rotation'
        cot_max_riskon_flag:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cot Max Riskon Flag
          description: True when ES crowded long AND VIX AM at max short-vol carry
        cot_report_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Cot Report Date
          description: COT report date (Tuesday positions) as ISO date string
        peer_div_composite:
          anyOf:
            - type: number
            - type: 'null'
          title: Peer Div Composite
          description: Peer divergence composite score (0-100)
        peer_div_signal:
          anyOf:
            - type: string
            - type: 'null'
          title: Peer Div Signal
          description: >-
            Peer divergence signal label (e.g. STRONG_DIVERGENCE,
            MILD_DIVERGENCE, ALIGNED)
        peer_div_peers_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Peer Div Peers Count
          description: Number of local peers analyzed in diffusion graph
        peer_div_weight_config:
          anyOf:
            - type: string
            - type: 'null'
          title: Peer Div Weight Config
          description: Scale coverage description for the diffusion weight configuration
      type: object
      required:
        - symbol
        - current_price
        - change_pct
        - volume_vs_avg
      title: MarketDataContext
      description: Market data context provided to debate agents.
    ProposedActionCard:
      properties:
        rank:
          type: integer
          title: Rank
        direction:
          type: string
          title: Direction
        instrument_type:
          type: string
          title: Instrument Type
        instrument_symbol:
          type: string
          title: Instrument Symbol
        timeframe:
          type: string
          title: Timeframe
        entry_price:
          type: number
          title: Entry Price
        stop_loss:
          type: number
          title: Stop Loss
        targets:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Targets
        risk_reward:
          type: number
          title: Risk Reward
        pop:
          type: number
          title: Pop
        pop_source:
          type: string
          title: Pop Source
        pop_sample_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pop Sample Size
        pop_ci_lower:
          anyOf:
            - type: number
            - type: 'null'
          title: Pop Ci Lower
        pop_ci_upper:
          anyOf:
            - type: number
            - type: 'null'
          title: Pop Ci Upper
        rationale:
          type: string
          title: Rationale
        strategy:
          anyOf:
            - type: string
            - type: 'null'
          title: Strategy
        strike:
          anyOf:
            - type: number
            - type: 'null'
          title: Strike
        expiration:
          anyOf:
            - type: string
            - type: 'null'
          title: Expiration
        dte:
          anyOf:
            - type: integer
            - type: 'null'
          title: Dte
        delta:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta
        theta:
          anyOf:
            - type: number
            - type: 'null'
          title: Theta
        iv:
          anyOf:
            - type: number
            - type: 'null'
          title: Iv
        open_interest:
          anyOf:
            - type: integer
            - type: 'null'
          title: Open Interest
        premium_stop_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Premium Stop Pct
        spread_net_debit:
          anyOf:
            - type: number
            - type: 'null'
          title: Spread Net Debit
        estimated_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Estimated Cost
        slippage_estimate:
          anyOf:
            - type: number
            - type: 'null'
          title: Slippage Estimate
        iv_crush_warning:
          anyOf:
            - type: string
            - type: 'null'
          title: Iv Crush Warning
        earnings_warning:
          anyOf:
            - type: string
            - type: 'null'
          title: Earnings Warning
        after_hours_estimate:
          type: boolean
          title: After Hours Estimate
          default: false
        generated_at:
          type: string
          title: Generated At
      type: object
      required:
        - rank
        - direction
        - instrument_type
        - instrument_symbol
        - timeframe
        - entry_price
        - stop_loss
        - risk_reward
        - pop
        - pop_source
        - rationale
        - generated_at
      title: ProposedActionCard
      description: A single proposed trade from the debate system.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    EvidenceItem:
      properties:
        factor:
          type: string
          title: Factor
          description: Evidence category (e.g., 'technical', 'momentum')
        observation:
          type: string
          title: Observation
          description: Specific observation or data point
        weight:
          type: number
          maximum: 1
          minimum: 0
          title: Weight
          description: Relative importance weight (0-1)
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
          description: Data source (e.g., 'confluence_score', 'fpt_analysis')
      type: object
      required:
        - factor
        - observation
        - weight
      title: EvidenceItem
      description: Single piece of evidence supporting a thesis.
    app__models__debate__HistoricalAnalog:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Symbol of historical analog
        date:
          type: string
          title: Date
          description: Date of historical setup
        similarity_score:
          type: number
          maximum: 1
          minimum: 0
          title: Similarity Score
          description: Similarity to current setup (0-1)
        outcome:
          type: string
          title: Outcome
          description: How the historical setup resolved
        return_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Return Pct
          description: Return percentage from historical trade
      type: object
      required:
        - symbol
        - date
        - similarity_score
        - outcome
      title: HistoricalAnalog
      description: Historical setup similar to current situation.
    ThesisStrength:
      type: string
      enum:
        - WEAK
        - MODERATE
        - STRONG
        - COMPELLING
      title: ThesisStrength
      description: Qualitative assessment of thesis strength.
    RiskFactor:
      properties:
        category:
          type: string
          title: Category
          description: Risk category (e.g., 'volatility', 'event', 'technical')
        description:
          type: string
          title: Description
          description: Description of the risk
        severity:
          type: string
          enum:
            - low
            - medium
            - high
            - critical
          title: Severity
          description: Risk severity level
        mitigation:
          anyOf:
            - type: string
            - type: 'null'
          title: Mitigation
          description: Suggested mitigation strategy
      type: object
      required:
        - category
        - description
        - severity
      title: RiskFactor
      description: Risk factor identified by Bear agent.
    Verdict:
      type: string
      enum:
        - STRONG_BUY
        - BUY
        - HOLD
        - AVOID
        - SHORT
      title: Verdict
      description: Arbiter verdict on trade viability.

````