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.
SlackTargetConfig	Config for the built-in Slack incoming-webhook target.
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

# 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: ""
  # Slack incoming-webhook delivery target (server-side, dispatched by the poller).
  slack:
    # Enable Slack delivery.
    enabled: false
    # Env var name holding the Slack incoming-webhook URL (also supports <VAR>_FILE).
    webhook_url_env: CORVIX_SLACK_WEBHOOK_URL

# 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

slack: SlackTargetConfig

class corvix.config.NotificationsDetectConfig

Controls which records qualify for notification events.

include_read: bool = False

min_score: float = 0.0

class corvix.config.SlackTargetConfig

Config for the built-in Slack incoming-webhook target.

The webhook URL is read from webhook_url_env (also supports the <VAR>_FILE convention) so the secret never lives in corvix.yaml.

enabled: bool = False

webhook_url_env: str = 'CORVIX_SLACK_WEBHOOK_URL'

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]