corvix.config.app
=================

.. py:module:: corvix.config.app

.. autoapi-nested-parse::

   AppConfig root model, auxiliary config classes, and load_config/write_default_config.



Attributes
----------

.. autoapisummary::

   corvix.config.app._POLLING_PER_PAGE_MIN
   corvix.config.app._POLLING_PER_PAGE_MAX
   corvix.config.app.DEFAULT_CONFIG


Classes
-------

.. autoapisummary::

   corvix.config.app.PollingConfig
   corvix.config.app.GitHubLatestCommentEnrichmentConfig
   corvix.config.app.GitHubPRStateEnrichmentConfig
   corvix.config.app.EnrichmentConfig
   corvix.config.app.StateConfig
   corvix.config.app.DatabaseConfig
   corvix.config.app.AppConfig


Functions
---------

.. autoapisummary::

   corvix.config.app._parse_polling
   corvix.config.app._parse_enrichment
   corvix.config.app._parse_state
   corvix.config.app._parse_database
   corvix.config.app.load_config
   corvix.config.app.write_default_config


Module Contents
---------------

.. py:data:: _POLLING_PER_PAGE_MIN
   :value: 1


.. py:data:: _POLLING_PER_PAGE_MAX
   :value: 50


.. py:class:: PollingConfig

   Polling behavior for ingestion.


   .. py:attribute:: interval_seconds
      :type:  int
      :value: 60



   .. py:attribute:: request_timeout_seconds
      :type:  float
      :value: 30.0



   .. py:attribute:: per_page
      :type:  int
      :value: 50



   .. py:attribute:: max_pages
      :type:  int
      :value: 5



   .. py:attribute:: all
      :type:  bool
      :value: False



   .. py:attribute:: participating
      :type:  bool
      :value: False



.. py:class:: GitHubLatestCommentEnrichmentConfig

   Config for enriching comment notifications with latest-comment metadata.


   .. py:attribute:: enabled
      :type:  bool
      :value: False



   .. py:attribute:: timeout_seconds
      :type:  float
      :value: 10.0



.. py:class:: GitHubPRStateEnrichmentConfig

   Config for enriching pull-request notifications with PR state.


   .. py:attribute:: enabled
      :type:  bool
      :value: False



   .. py:attribute:: timeout_seconds
      :type:  float
      :value: 10.0



.. py:class:: EnrichmentConfig

   Top-level enrichment configuration.


   .. py:attribute:: enabled
      :type:  bool
      :value: False



   .. py:attribute:: max_requests_per_cycle
      :type:  int
      :value: 25



   .. py:attribute:: github_latest_comment
      :type:  GitHubLatestCommentEnrichmentConfig


   .. py:attribute:: github_pr_state
      :type:  GitHubPRStateEnrichmentConfig


.. py:class:: StateConfig

   State/cache location for persisted notifications.


   .. py:attribute:: cache_file
      :type:  pathlib.Path


.. py:class:: DatabaseConfig

   PostgreSQL connection configuration.


   .. py:attribute:: url_env
      :type:  str
      :value: 'DATABASE_URL'



.. py:class:: AppConfig

   Top-level application config.


   .. py:attribute:: github
      :type:  corvix.config.github.GitHubConfig


   .. py:attribute:: enrichment
      :type:  EnrichmentConfig


   .. py:attribute:: polling
      :type:  PollingConfig


   .. py:attribute:: state
      :type:  StateConfig


   .. py:attribute:: scoring
      :type:  corvix.config.scoring.ScoringConfig


   .. py:attribute:: rules
      :type:  corvix.config.rules.RuleSet


   .. py:attribute:: dashboards
      :type:  list[corvix.config.dashboards.DashboardSpec]
      :value: []



   .. py:attribute:: database
      :type:  DatabaseConfig


   .. py:attribute:: notifications
      :type:  corvix.config.notifications.NotificationsConfig


   .. py:method:: resolve_cache_file() -> pathlib.Path

      Resolve the configured cache path.



.. py:data:: DEFAULT_CONFIG
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """github:
        accounts:
          - id: primary
            label: Primary
            token_env: GITHUB_TOKEN
            api_base_url: https://api.github.com
      
      # Optional enrichment providers that add context used by rules/dashboards.
      enrichment:
        # Master switch for all enrichment providers.
        enabled: false
        # Global request budget shared by providers each poll cycle.
        max_requests_per_cycle: 25
        # Adds github.latest_comment.* context for comment-based filtering.
        github_latest_comment:
          # Enable latest-comment metadata lookups.
          enabled: false
          # HTTP timeout per request made by this provider.
          timeout_seconds: 10
        # Adds github.pr_state.* context for PR-state/author filtering.
        github_pr_state:
          # Enable pull-request state metadata lookups.
          enabled: false
          # HTTP timeout per request made by this provider.
          timeout_seconds: 10
      
      # Polling behavior for fetching notifications from GitHub.
      polling:
        # Watch-loop delay between poll cycles, in seconds.
        interval_seconds: 60
        # HTTP timeout per GitHub API request, in seconds.
        request_timeout_seconds: 30
        # GitHub page size per request (valid range: 1-50).
        per_page: 50
        # Maximum pages to fetch per cycle to cap API usage.
        max_pages: 5
        # Include notifications from repositories you are not participating in.
        all: false
        # Restrict results to threads you participate in when true.
        participating: false
      
      # Legacy JSON cache path. Notifications are now stored in PostgreSQL (required);
      # this path is only read by the one-shot `corvix migrate-cache` upgrade command.
      state:
        # Legacy JSON cache path, used solely by `corvix migrate-cache`.
        cache_file: ~/.cache/corvix/notifications.json
      
      # Priority scoring model used when sort_by=score.
      scoring:
        # Points added to unread notifications.
        unread_bonus: 15
        # Points subtracted per hour since last update.
        age_decay_per_hour: 0.25
        # Extra points by GitHub reason (mention/review_requested/etc).
        reason_weights:
          mention: 50
          review_requested: 40
          assign: 30
          author: 10
        # Per-repository score adjustments (repo full_name -> points).
        repository_weights:
          your-org/critical-repo: 25
        # Score adjustments by subject type (Issue, PullRequest, etc).
        subject_type_weights:
          PullRequest: 10
        # Case-insensitive keyword boosts when title contains the key.
        title_keyword_weights:
          security: 20
          urgent: 15
      
      # Automation rules evaluated for each notification after scoring.
      rules:
        # Rules applied to all repositories.
        global:
          # Rule name appears in matched_rules for traceability.
          - name: mute-bot-noise
            # Match criteria: all provided fields must match.
            match:
              # Regex against notification title.
              title_regex: ".*\[bot\].*"
            # Actions to execute when the rule matches.
            actions:
              # mark_read marks a thread as read (dry-run unless apply_actions=true).
              - type: mark_read
            # Hide matching records from dashboards while still processing them.
            exclude_from_dashboards: true
        # Repository-specific rules map: repo full_name -> list of rules.
        per_repository:
          your-org/infra:
            - name: mute-chore-prs
              match:
                # Match when title contains any listed keyword.
                title_contains_any: ["chore", "deps"]
              actions:
                - type: mark_read
              exclude_from_dashboards: true
      
      # Event detection + delivery targets for user-facing notifications.
      notifications:
        # Master switch for event detection and dispatch.
        enabled: true
        # Controls which records qualify as notification events.
        detect:
          # Include read records in event detection when true.
          include_read: false
          # Minimum score threshold required for event emission.
          min_score: 0
        # In-tab browser delivery target (shown while dashboard tab is open).
        browser_tab:
          # Enable browser-tab deliveries.
          enabled: true
          # Max events sent to this target per poll cycle.
          max_per_cycle: 5
          # Per-thread delivery cooldown in seconds to suppress repeats.
          cooldown_seconds: 10
        # Background Web Push delivery target.
        web_push:
          # Enable Web Push delivery.
          enabled: false
          # Env var name containing VAPID public key.
          vapid_public_key_env: CORVIX_VAPID_PUBLIC_KEY
          # Env var name containing VAPID private key.
          vapid_private_key_env: CORVIX_VAPID_PRIVATE_KEY
          # Web Push contact subject (recommended: mailto:<team@example.com>).
          subject: ""
      
      # Dashboards rendered in UI; first entry is selected by default.
      dashboards:
        # Unique dashboard name used in routes and selector.
        - name: overview
          # Grouping key: none | repository | reason | subject_type.
          group_by: reason
          # Sort key: score | updated_at | repository | reason | subject_type | title.
          sort_by: updated_at
          # Sort order for selected sort_by field.
          descending: true
          # Include read records when true.
          include_read: true
          # Maximum records shown (<=0 means no truncation).
          max_items: 200
        - name: triage
          # Grouping key: none | repository | reason | subject_type.
          group_by: repository
          # Sort key: score | updated_at | repository | reason | subject_type | title.
          sort_by: score
          # Sort order for selected sort_by field.
          descending: true
          # Include read records when true.
          include_read: false
          # Maximum records shown (<=0 means no truncation).
          max_items: 100
          # Additional include filter (same schema as rule match).
          match:
            reason_in: ["mention", "review_requested", "assign"]
          # Exclusion filters applied after match/include checks.
          ignore_rules:
            - reason_in: ["comment"]
              context:
                # Dot path into enrichment context payload.
                - path: github.latest_comment.is_ci_only
                  # Predicate operator: equals | not_equals | contains | regex | in | exists.
                  op: equals
                  # Value compared by the operator.
                  value: true
      
      # Database settings (used by DB-backed storage/migrations/commands).
      database:
        # Env var holding SQLAlchemy database URL (also supports <VAR>_FILE).
        url_env: DATABASE_URL
      """

   .. raw:: html

      </details>



.. py:function:: _parse_polling(value: object) -> PollingConfig

.. py:function:: _parse_enrichment(value: object) -> EnrichmentConfig

.. py:function:: _parse_state(value: object) -> StateConfig

.. py:function:: _parse_database(value: object) -> DatabaseConfig

.. py:function:: load_config(path: pathlib.Path) -> AppConfig

   Load and validate YAML config from disk.


.. py:function:: write_default_config(path: pathlib.Path) -> None

   Write a starter configuration file.