corvix.config

Corvix configuration package.

This package exposes every public name that was previously in the monolithic corvix/config.py module so that all existing imports continue to work without modification.

Sub-modules:

• config.rules — MatchCriteria, ContextPredicate, Rule, RuleSet, RuleAction

• config.dashboards — DashboardSpec + dashboard helpers

• config.scoring — ScoringConfig

• config.notifications — NotificationsConfig and delivery-target configs

• config.github — GitHubAccountConfig, GitHubConfig

• config.app — AppConfig, auxiliary configs, load_config, write_default_config

Submodules

• corvix.config._utils
• corvix.config.app
• corvix.config.dashboards
• corvix.config.github
• corvix.config.notifications
• corvix.config.rules
• corvix.config.scoring

Attributes

DEFAULT_CONFIG
NO_FILTERS_DASHBOARD_NAME
DEFAULT_GITHUB_API_BASE_URL

Classes

AppConfig	Top-level application config.
DatabaseConfig	PostgreSQL connection configuration.
EnrichmentConfig	Top-level enrichment configuration.
GitHubLatestCommentEnrichmentConfig	Config for enriching comment notifications with latest-comment metadata.
GitHubPRStateEnrichmentConfig	Config for enriching pull-request notifications with PR state.
PollingConfig	Polling behavior for ingestion.
StateConfig	State/cache location for persisted notifications.
DashboardSpec	Dashboard configuration for sorting, grouping, and filtering.
GitHubAccountConfig	One GitHub account configuration for multi-account polling.
GitHubConfig	GitHub API configuration.
BrowserTabTargetConfig	Config for in-tab browser notification delivery.
NotificationsConfig	Top-level notifications configuration.
NotificationsDetectConfig	Controls which records qualify for notification events.
WebPushTargetConfig	Config for background Web Push notification delivery (phase 2).
ContextPredicate	Predicate evaluated against enriched notification context.
MatchCriteria	Filter fields for rules and dashboards.
Rule	Global or repository-scoped automation rule.
RuleAction	Action emitted when a rule matches.
RuleSet	Collection of global and per-repository rules.
ScoringConfig	Configurable scoring model for notifications.

Functions

load_config(→ AppConfig)	Load and validate YAML config from disk.
write_default_config(→ None)	Write a starter configuration file.
available_dashboards(→ list[DashboardSpec])	Return configured dashboards plus the built-in rule-free dashboard.
default_dashboard(→ DashboardSpec)	Return the fallback dashboard used when config defines none.
is_no_filters_dashboard(→ bool)	Return whether the dashboard is the hardcoded rule-free dashboard.
no_filters_dashboard(→ DashboardSpec)	Return the hardcoded dashboard that bypasses config-driven filtering.

Package Contents

corvix.config.DEFAULT_CONFIG = Multiline-String

Show Value

"""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
"""

class corvix.config.AppConfig

Top-level application config.

github: corvix.config.github.GitHubConfig

enrichment: EnrichmentConfig

polling: PollingConfig

state: StateConfig

scoring: corvix.config.scoring.ScoringConfig

rules: corvix.config.rules.RuleSet

dashboards: list[corvix.config.dashboards.DashboardSpec] = []

database: DatabaseConfig

notifications: corvix.config.notifications.NotificationsConfig

resolve_cache_file() → pathlib.Path

Resolve the configured cache path.

class corvix.config.DatabaseConfig

PostgreSQL connection configuration.

url_env: str = 'DATABASE_URL'

class corvix.config.EnrichmentConfig

Top-level enrichment configuration.

enabled: bool = False

max_requests_per_cycle: int = 25

github_latest_comment: GitHubLatestCommentEnrichmentConfig

github_pr_state: GitHubPRStateEnrichmentConfig

class corvix.config.GitHubLatestCommentEnrichmentConfig

Config for enriching comment notifications with latest-comment metadata.

enabled: bool = False

timeout_seconds: float = 10.0

class corvix.config.GitHubPRStateEnrichmentConfig

Config for enriching pull-request notifications with PR state.

enabled: bool = False

timeout_seconds: float = 10.0

class corvix.config.PollingConfig

Polling behavior for ingestion.

interval_seconds: int = 60

request_timeout_seconds: float = 30.0

per_page: int = 50

max_pages: int = 5

all: bool = False

participating: bool = False

class corvix.config.StateConfig

State/cache location for persisted notifications.

cache_file: pathlib.Path

corvix.config.load_config(path: pathlib.Path) → AppConfig

Load and validate YAML config from disk.

corvix.config.write_default_config(path: pathlib.Path) → None

Write a starter configuration file.

corvix.config.NO_FILTERS_DASHBOARD_NAME = 'no filters'

class corvix.config.DashboardSpec

Dashboard configuration for sorting, grouping, and filtering.

name: str

group_by: str = 'none'

sort_by: str = 'score'

descending: bool = True

include_read: bool = False

max_items: int = 100

match: corvix.config.rules.MatchCriteria

ignore_rules: list[corvix.config.rules.MatchCriteria] = []

corvix.config.available_dashboards(dashboards: list[DashboardSpec]) → list[DashboardSpec]

Return configured dashboards plus the built-in rule-free dashboard.

corvix.config.default_dashboard() → DashboardSpec

Return the fallback dashboard used when config defines none.

corvix.config.is_no_filters_dashboard(dashboard: DashboardSpec) → bool

Return whether the dashboard is the hardcoded rule-free dashboard.

corvix.config.no_filters_dashboard() → DashboardSpec

Return the hardcoded dashboard that bypasses config-driven filtering.

corvix.config.DEFAULT_GITHUB_API_BASE_URL = 'https://api.github.com'

class corvix.config.GitHubAccountConfig

One GitHub account configuration for multi-account polling.

id: str

label: str

token_env: str

api_base_url: str = 'https://api.github.com'

class corvix.config.GitHubConfig

GitHub API configuration.

accounts: list[GitHubAccountConfig] = []

property token_env: str

Backward-compatible shortcut to first account token env.

property api_base_url: str

Backward-compatible shortcut to first account API base URL.

class corvix.config.BrowserTabTargetConfig

Config for in-tab browser notification delivery.

enabled: bool = True

max_per_cycle: int = 5

cooldown_seconds: int = 10

class corvix.config.NotificationsConfig

Top-level notifications configuration.

enabled: bool = True

detect: NotificationsDetectConfig

browser_tab: BrowserTabTargetConfig

web_push: WebPushTargetConfig

class corvix.config.NotificationsDetectConfig

Controls which records qualify for notification events.

include_read: bool = False

min_score: float = 0.0

class corvix.config.WebPushTargetConfig

Config for background Web Push notification delivery (phase 2).

enabled: bool = False

vapid_public_key_env: str = 'CORVIX_VAPID_PUBLIC_KEY'

vapid_private_key_env: str = 'CORVIX_VAPID_PRIVATE_KEY'

subject: str = ''

class corvix.config.ContextPredicate

Predicate evaluated against enriched notification context.

path: str

op: str

value: object | None = None

case_insensitive: bool = False

class corvix.config.MatchCriteria

Filter fields for rules and dashboards.

repository_in: list[str] = []

repository_glob: list[str] = []

reason_in: list[str] = []

subject_type_in: list[str] = []

title_contains_any: list[str] = []

title_regex: str | None = None

unread: bool | None = None

min_score: float | None = None

max_age_hours: float | None = None

context: list[ContextPredicate] = []

class corvix.config.Rule

Global or repository-scoped automation rule.

name: str

match: MatchCriteria

actions: list[RuleAction] = []

exclude_from_dashboards: bool = False

class corvix.config.RuleAction

Action emitted when a rule matches.

action_type: str

class corvix.config.RuleSet

Collection of global and per-repository rules.

global_rules: list[Rule] = []

per_repository: dict[str, list[Rule]]

class corvix.config.ScoringConfig

Configurable scoring model for notifications.

unread_bonus: float = 15.0

age_decay_per_hour: float = 0.25

reason_weights: dict[str, float]

repository_weights: dict[str, float]

subject_type_weights: dict[str, float]

title_keyword_weights: dict[str, float]