> ## 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.

# Translate natural language to screener filters

> Translate a natural language query into structured screener filters.

Uses an LLM to interpret trading queries like "oversold tech stocks with high volume"
and returns ScreenerRequest-compatible filters.



## OpenAPI

````yaml /api/openapi.json post /api/graph/v1/screener/nl
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/screener/nl:
    post:
      tags:
        - Screener
      summary: Translate natural language to screener filters
      description: >-
        Translate a natural language query into structured screener filters.


        Uses an LLM to interpret trading queries like "oversold tech stocks with
        high volume"

        and returns ScreenerRequest-compatible filters.
      operationId: nl_to_screener_api_graph_v1_screener_nl_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLScreenerRequest'
        required: true
      responses:
        '200':
          description: Translated screener filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLScreenerResponse'
        '422':
          description: Validation error
        '502':
          description: LLM translation failed
components:
  schemas:
    NLScreenerRequest:
      properties:
        query:
          type: string
          maxLength: 500
          minLength: 1
          title: Query
          description: Natural language screener query
        regime_context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Regime Context
          description: Optional current market regime context for informed translation
      type: object
      required:
        - query
      title: NLScreenerRequest
      description: Request body for natural language screener translation.
    NLScreenerResponse:
      properties:
        filters:
          $ref: '#/components/schemas/ScreenerRequest-Output'
          description: Translated screener filters
        explanation:
          type: string
          title: Explanation
          description: Human-readable explanation of the translation
      type: object
      required:
        - filters
        - explanation
      title: NLScreenerResponse
      description: Response from NL screener translation.
    ScreenerRequest-Output:
      properties:
        filters:
          anyOf:
            - $ref: '#/components/schemas/Filters'
            - type: 'null'
        include:
          anyOf:
            - $ref: '#/components/schemas/IncludeOptions'
            - type: 'null'
        sort:
          anyOf:
            - $ref: '#/components/schemas/SortOptions'
            - type: 'null'
        pagination:
          anyOf:
            - $ref: '#/components/schemas/app__models__screener__Pagination'
            - type: 'null'
      additionalProperties: false
      type: object
      title: ScreenerRequest
      description: >-
        Screener request payload.


        Screen stocks using graph-native filters with optional relationship
        expansion.


        Example:
            ```json
            {
                "filters": {
                    "volume": {"adv30_usd_min": 50000000},
                    "technical": {"rsi_14": {"min": 30, "max": 70}}
                },
                "include": {"levels": true, "patterns": true},
                "sort": {"by": "dollar_volume", "order": "desc"},
                "pagination": {"limit": 50}
            }
            ```
      example:
        filters:
          technical:
            trend_stack: true
          volume:
            adv30_usd_min: 50000000
        include:
          levels: true
        pagination:
          limit: 50
        sort:
          by: dollar_volume
          order: desc
    Filters:
      properties:
        price:
          anyOf:
            - $ref: '#/components/schemas/PriceFilter'
            - type: 'null'
        volume:
          anyOf:
            - $ref: '#/components/schemas/VolumeFilter'
            - type: 'null'
        options:
          anyOf:
            - $ref: '#/components/schemas/OptionsFilter'
            - type: 'null'
        technical:
          anyOf:
            - $ref: '#/components/schemas/TechnicalFilter'
            - type: 'null'
        fundamental:
          anyOf:
            - $ref: '#/components/schemas/FundamentalFilter'
            - type: 'null'
        day_type:
          anyOf:
            - items:
                $ref: '#/components/schemas/app__models__screener__DayType'
              type: array
            - type: 'null'
          title: Day Type
          description: Filter by day type classification
        directional_bias:
          anyOf:
            - items:
                $ref: '#/components/schemas/DirectionalBias'
              type: array
            - type: 'null'
          title: Directional Bias
          description: 'Phase 15: Filter by directional bias classification'
        patterns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Patterns
          description: Filter by active pattern types
        confluence:
          anyOf:
            - $ref: '#/components/schemas/ConfluenceFilter'
            - type: 'null'
          description: Filter by V4 confluence scores
        pulse:
          anyOf:
            - $ref: '#/components/schemas/PulseFilter'
            - type: 'null'
          description: Filter by V4.5 Pulse scores
        dark_pool:
          anyOf:
            - $ref: '#/components/schemas/DarkPoolFilter'
            - type: 'null'
          description: Dark pool intelligence filters
        conviction:
          anyOf:
            - $ref: '#/components/schemas/ConvictionFilter'
            - type: 'null'
        earnings:
          anyOf:
            - $ref: '#/components/schemas/EarningsFilter'
            - type: 'null'
        price_events:
          anyOf:
            - $ref: '#/components/schemas/PriceEventFilter'
            - type: 'null'
          description: Filter by recent price events
        theme:
          anyOf:
            - $ref: '#/components/schemas/ThemeFilter'
            - type: 'null'
          description: Filter by thematic exposure (structural themes)
        max_intraday_decline:
          anyOf:
            - type: number
              maximum: 0
              minimum: -100
            - type: 'null'
          title: Max Intraday Decline
          description: >-
            Maximum intraday decline % to include (e.g., -7.0 excludes stocks
            down more than 7%)
        exclude_halted:
          type: boolean
          title: Exclude Halted
          description: Exclude halted stocks
          default: true
        symbols:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: Symbols
          description: Filter to specific symbols (max 50)
      additionalProperties: false
      type: object
      title: Filters
      description: All available screener filters.
    IncludeOptions:
      properties:
        levels:
          type: boolean
          title: Levels
          description: Include IntradayLevel data
          default: false
        volume_profile:
          type: boolean
          title: Volume Profile
          description: Include VolumeProfileSession data
          default: false
        patterns:
          type: boolean
          title: Patterns
          description: Include Pattern relationships
          default: false
        news:
          type: boolean
          title: News
          description: Include NewsEvent summary
          default: false
        day_classification:
          type: boolean
          title: Day Classification
          description: Include full DayClassification data
          default: false
        price_events:
          type: boolean
          title: Price Events
          description: Include recent price events (gaps, breakouts, MA crossovers, etc.)
          default: false
        session_price:
          type: boolean
          title: Session Price
          description: Include session-specific price data (change, open, low)
          default: false
        thematic_exposure:
          type: boolean
          title: Thematic Exposure
          description: Include structural theme exposures (EXPOSED_TO edges)
          default: false
      type: object
      title: IncludeOptions
      description: Options for including related data in response.
    SortOptions:
      properties:
        by:
          $ref: '#/components/schemas/SortField'
          description: Field to sort by
          default: dollar_volume
        order:
          type: string
          enum:
            - asc
            - desc
          title: Order
          description: Sort order
          default: desc
      type: object
      title: SortOptions
      description: Sorting options.
    app__models__screener__Pagination:
      properties:
        limit:
          type: integer
          maximum: 500
          minimum: 1
          title: Limit
          description: Maximum results to return
          default: 50
        offset:
          type: integer
          minimum: 0
          title: Offset
          description: Number of results to skip
          default: 0
      type: object
      title: Pagination
      description: Pagination options.
    PriceFilter:
      properties:
        min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Max
      additionalProperties: false
      type: object
      title: PriceFilter
      description: Price range filter.
    VolumeFilter:
      properties:
        adv30_usd_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Adv30 Usd Min
          description: Minimum 30-day average dollar volume
        dollar_volume_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Dollar Volume Min
          description: Minimum today's dollar volume
        rel_volume_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Rel Volume Min
          description: Minimum relative volume
        cvd_trend:
          anyOf:
            - type: string
              enum:
                - accumulating
                - distributing
                - neutral
            - type: 'null'
          title: Cvd Trend
          description: Filter by CVD trend classification
      additionalProperties: false
      type: object
      title: VolumeFilter
      description: Volume/liquidity filters.
    OptionsFilter:
      properties:
        chain_total_oi_min:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Chain Total Oi Min
          description: Minimum total open interest
        chain_volume_1d_min:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Chain Volume 1D Min
          description: Minimum today's options volume
        iv_percentile:
          anyOf:
            - $ref: '#/components/schemas/PriceFilter'
            - type: 'null'
          description: IV percentile range filter (0-100)
        put_call_ratio:
          anyOf:
            - $ref: '#/components/schemas/PriceFilter'
            - type: 'null'
          description: Put/call ratio range filter
      additionalProperties: false
      type: object
      title: OptionsFilter
      description: |-
        Options-related filters.

        Note: These filters require the options-collector pipeline to be active.
        Properties are written to graph vertices by Go collectors.
    TechnicalFilter:
      properties:
        rsi_14:
          anyOf:
            - $ref: '#/components/schemas/PriceFilter'
            - type: 'null'
          description: RSI(14) range filter
        trend_stack:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Trend Stack
          description: Filter for trend stack alignment (EMA9 > EMA20 > SMA50 > SMA200)
        compression:
          anyOf:
            - items:
                $ref: '#/components/schemas/CompressionType'
              type: array
            - type: 'null'
          title: Compression
          description: Filter for specific compression patterns
        atr_compression_max:
          anyOf:
            - type: number
            - type: 'null'
          title: Atr Compression Max
          description: Maximum ATR compression ratio
      additionalProperties: false
      type: object
      title: TechnicalFilter
      description: Technical indicator filters.
    FundamentalFilter:
      properties:
        market_cap_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Market Cap Min
        market_cap_max:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Market Cap Max
        sector:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Sector
          description: Filter by sectors
        exchange:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exchange
          description: Filter by exchanges
        fundamental_health_score_min:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Fundamental Health Score Min
          description: >-
            Minimum fundamental health score (0-100 integer, maps to letter
            grades)
        roe_min:
          anyOf:
            - type: number
            - type: 'null'
          title: Roe Min
          description: Minimum return on equity (%)
        dividend_yield_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Dividend Yield Min
          description: Minimum dividend yield (%)
      additionalProperties: false
      type: object
      title: FundamentalFilter
      description: Fundamental filters.
    app__models__screener__DayType:
      type: string
      enum:
        - trending
        - rotational
        - uncertain
      title: DayType
      description: Day type classification.
    DirectionalBias:
      type: string
      enum:
        - STRONG_LONG
        - MOD_LONG
        - NEUTRAL
        - MOD_SHORT
        - STRONG_SHORT
      title: DirectionalBias
      description: 'Phase 15: Directional bias from net_confluence thresholds.'
    ConfluenceFilter:
      properties:
        bullish_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bullish Min
          description: Minimum bullish confluence score (0-100)
        bearish_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Bearish Min
          description: Minimum bearish confluence score (0-100)
        net_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Net Min
          description: Minimum net confluence (-100 to +100)
        net_max:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Net Max
          description: Maximum net confluence (-100 to +100)
      additionalProperties: false
      type: object
      title: ConfluenceFilter
      description: >-
        Confluence scoring filters.


        Filter by V4 dual bull/bear confluence scores and net directional
        signal.
    PulseFilter:
      properties:
        net_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Net Min
          description: Minimum pulse net score (-100 to +100)
        net_max:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Net Max
          description: Maximum pulse net score (-100 to +100)
        bias:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Bias
          description: >-
            Filter by pulse bias: STRONG_LONG, MOD_LONG, NEUTRAL, MOD_SHORT,
            STRONG_SHORT
      additionalProperties: false
      type: object
      title: PulseFilter
      description: |-
        V4.5 Pulse score filters.

        Filter by real-time intraday conviction (Pulse) scores.
    DarkPoolFilter:
      properties:
        dark_pool_pct_min:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Dark Pool Pct Min
          description: Minimum dark pool % (0-1)
        dark_pool_pct_max:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Dark Pool Pct Max
          description: Maximum dark pool % (0-1)
        buy_sell_ratio_min:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Buy Sell Ratio Min
          description: Minimum buy/sell ratio
        buy_sell_ratio_max:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Buy Sell Ratio Max
          description: Maximum buy/sell ratio
        min_block_trades:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Block Trades
          description: Minimum block trade count
      additionalProperties: false
      type: object
      title: DarkPoolFilter
      description: Dark pool intelligence filters.
    ConvictionFilter:
      properties:
        conviction_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Min
        conviction_max:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Max
        conviction_confidence_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Confidence Min
        conviction_max_v5_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Max V5 Min
        conviction_max_v5_max:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conviction Max V5 Max
        conflict_min_v5_min:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conflict Min V5 Min
        conflict_min_v5_max:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Conflict Min V5 Max
      additionalProperties: false
      type: object
      title: ConvictionFilter
      description: Conviction score filters (v5 scoring architecture).
    EarningsFilter:
      properties:
        within_days:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Within Days
          description: Only stocks with earnings within N days. Requires earnings pipeline.
          x-data-status: pending
        cleared:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cleared
          description: Filter for stocks that have cleared earnings (>3 days past)
      additionalProperties: false
      type: object
      title: EarningsFilter
      description: |-
        Earnings-related filters.

        Note: These filters require the earnings-sync pipeline to be active.
    PriceEventFilter:
      properties:
        event_types:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Event Types
          description: >-
            Filter by event types (gap_up, gap_down, breakout_52w_high,
            golden_cross, etc.)
        min_severity:
          anyOf:
            - type: string
            - type: 'null'
          title: Min Severity
          description: 'Minimum severity level: low, medium, high, critical'
        days:
          anyOf:
            - type: integer
              maximum: 90
              minimum: 1
            - type: 'null'
          title: Days
          description: Events within N days (default 30, max 90)
          default: 30
      additionalProperties: false
      type: object
      title: PriceEventFilter
      description: |-
        Price event filters for Go pattern-detector events.

        Filter stocks by recent price events including gaps, breakouts,
        MA crossovers, volume events, and pattern triggers.
    ThemeFilter:
      properties:
        theme_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 30
            - type: 'null'
          title: Theme Ids
          description: >-
            Filter to stocks exposed to any of these themes (from
            VALID_THEME_IDS)
      additionalProperties: false
      type: object
      title: ThemeFilter
      description: Filter stocks by thematic exposure.
    SortField:
      type: string
      enum:
        - dollar_volume
        - adv30_usd
        - market_cap
        - confluence_score
        - rsi_14
        - iv_percentile
        - proximity_score
        - rel_volume
        - bullish_confluence
        - bearish_confluence
        - net_confluence
        - cvd_pct
        - bullish_entry_score
        - bearish_entry_score
        - net_entry_score
        - pattern_count
        - options_confluence_score
        - iv_rank
        - pricing_edge_bull
        - abs_net_confluence
        - pulse_net
        - abs_pulse_net
        - confluence_bull_v5
        - confluence_bear_v5
        - confluence_net_v5
        - momentum_health_v5
        - conviction_v5
        - conviction_max_v5
        - conviction_confidence_v5
        - conflict_min_v5
        - pulse_bull_v5
        - pulse_bear_v5
        - pulse_net_v5
        - entry_bull_v2
        - entry_bear_v2
        - options_confluence_v5
        - momentum_crowding_v5
        - news_sentiment_v5
        - dark_pool_pct
        - buy_sell_ratio
        - peer_divergence
        - fundamental_health_score
        - dividend_yield
        - roe
      title: SortField
      description: Available sort fields for screener.
    CompressionType:
      type: string
      enum:
        - nr7
        - bb_squeeze
        - vcp
        - inside_day
      title: CompressionType
      description: Volatility compression patterns.

````