detectkit 0.59.0__tar.gz → 0.61.0__tar.gz

{detectkit-0.59.0/detectkit.egg-info → detectkit-0.61.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.59.0
+Version: 0.61.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -38,10 +38,13 @@ Provides-Extra: mysql
 Requires-Dist: pymysql>=1.0.0; extra == "mysql"
 Provides-Extra: mariadb
 Requires-Dist: pymysql>=1.0.0; extra == "mariadb"
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=1.1; extra == "duckdb"
 Provides-Extra: all-db
 Requires-Dist: clickhouse-driver>=0.2.0; extra == "all-db"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all-db"
 Requires-Dist: pymysql>=1.0.0; extra == "all-db"
+Requires-Dist: duckdb>=1.1; extra == "all-db"
 Provides-Extra: prophet
 Requires-Dist: prophet>=1.1.0; extra == "prophet"
 Provides-Extra: timesfm
@@ -55,6 +58,7 @@ Provides-Extra: all
 Requires-Dist: clickhouse-driver>=0.2.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
+Requires-Dist: duckdb>=1.1; extra == "all"
 Requires-Dist: prophet>=1.1.0; extra == "all"
 Requires-Dist: timesfm>=0.1.0; extra == "all"
 Requires-Dist: sqlglot>=20.0; extra == "all"
@@ -99,7 +103,8 @@ Dynamic: license-file
 - **@mentions** — tag users/groups in alerts, each channel formats natively
 - **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
-- **Database agnostic** — ClickHouse, PostgreSQL, MySQL
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
+- **Hybrid mode** — read metric SQL from a billed-per-query warehouse while all pipeline state lives in a cheap local database
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 - **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + three skills) so an assistant can scaffold metrics, configure databases, and file feedback upstream

{detectkit-0.59.0 → detectkit-0.61.0}/README.md

@@ -24,7 +24,8 @@
 - **@mentions** — tag users/groups in alerts, each channel formats natively
 - **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
-- **Database agnostic** — ClickHouse, PostgreSQL, MySQL
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
+- **Hybrid mode** — read metric SQL from a billed-per-query warehouse while all pipeline state lives in a cheap local database
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 - **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + three skills) so an assistant can scaffold metrics, configure databases, and file feedback upstream

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.59.0"
+__version__ = "0.61.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -14,7 +14,7 @@ conventions.
 **Database access for _you_ (recommended, not required).** detectkit itself
 connects to the database directly via its drivers — it **never** needs an MCP to
 run. But you assist far better with **read access to the same database** (e.g. a
-database MCP for the project's ClickHouse / PostgreSQL / MySQL / MariaDB): you can inspect
+database MCP for the project's ClickHouse / PostgreSQL / MySQL / MariaDB / DuckDB): you can inspect
 a metric's series, find real incidents to label for `dtk autotune`, sanity-check
 a metric query before running it, and confirm detections — instead of asking the
 user to run every query by hand. Without it, fall back to marking incidents

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/assets/claude/rules/metrics.md

@@ -11,6 +11,7 @@ keep them in sync. Detectors are covered in `detectors.md`, alerting in
 name: api_response_time        # required, unique across the project
 description: API p95 latency   # optional, shown in alerts
 profile: prod                  # optional, overrides project default_profile
+source_profile: warehouse      # optional — hybrid mode: source-DB profile for THIS metric's SQL (see below)
 enabled: true                  # optional, false → skipped by `dtk run`
 tags: [critical, api]          # optional, used by `--select tag:<t>`
 ai_context:                    # optional — OSI-compatible grounding (descriptive only)
@@ -67,6 +68,19 @@ false_alert_budget: 0.3        # optional — `dtk tune` target false-alert rate
 project-wide default; unset → project, then a built-in `0.5`. Tuning-only — it never
 affects the load/detect/alert pipeline.
 
+`source_profile` is **hybrid mode** for this one metric: the `profiles.yml`
+profile whose database runs *this metric's* SQL query, while `_dtk_*` state
+(datapoints, detections, task locks, alert state) stays in the active
+**state** profile — the one `dtk run` is already connected to for everything
+else. Overrides the project-wide `source_profile` (`project.md`); resolves
+**metric → project → unset** (unset on both = today's behavior — one profile
+for everything). Not the same field as `profile` above (`profile` is dead —
+not applied at runtime by `dtk run`; `source_profile` is live). Only the
+metric's **load** step ever connects to it — detect/alert and every other
+command don't — though every `dtk run` fail-fast validates the resolved name
+up front regardless of `--steps` (a typo exits 1 before any pipeline work).
+See the [Hybrid Mode guide](https://dtk.pipelab.dev/guides/hybrid-mode/).
+
 `ai_context` is **OSI-compatible grounding** you can add to any metric with **no
 OSI model needed** — the metric's business meaning (`instructions`), alternative
 names (`synonyms`) and example values (`examples`), mirroring the

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/assets/claude/rules/project.md

@@ -33,6 +33,7 @@ timeouts:                      # per-step, seconds
 alert_help_url: null           # optional, see below — "How to read this alert" link
 false_alert_budget: null       # optional — `dtk tune` target FDR (0,1]; per-metric override wins
 loading_delay: null            # optional — default data-maturity delay; per-metric override wins
+source_profile: null           # optional — hybrid mode: default source-DB profile; per-metric override wins
 
 error_alerting:                # optional, see below
   enabled: false
@@ -50,6 +51,26 @@ overrides it (`0` opts that metric out); see `metrics.md` for the full
 load/no-data behavior and the detection-latency trade-off. Only set this
 project-wide when your metrics genuinely share the same upstream schedule.
 
+`source_profile` is **hybrid mode**: a project-wide default `profiles.yml`
+profile whose database runs metric SQL, while *every* `_dtk_*` table
+(datapoints, detections, task locks, alert state) stays in the active
+**state** profile — the one `dtk run` is already connected to for everything
+else. A per-metric `source_profile` overrides it (`metrics.md`); resolves
+**metric → project → unset**, same precedence as `loading_delay`. Unset on
+both = today's behavior (one profile does everything). Only the LOAD step's
+metric-SQL query is affected — detect/alert and every other command
+(`dtk autotune`/`tune`/`ui`/`clean`/`unlock`) only ever touch the state
+profile. A source-side failure raises `SourceDatabaseError` (message leads
+with `source database (profile '<name>'): ...`), distinct from a plain
+exception for a state-side failure — useful for telling a warehouse outage
+apart from a state-DB outage in `error_alerting`'s `{error_type}` /
+`{error_message}`. `dtk run` validates every resolved `source_profile` name
+against `profiles.yml` before opening any connection (unknown name → exit
+`1`, no partial run). Full config example + operational caveats (connecting a
+profile always runs `CREATE DATABASE`/`SCHEMA IF NOT EXISTS` for its own
+`internal_*` location too, even a source-only one) in the [Hybrid Mode
+guide](https://dtk.pipelab.dev/guides/hybrid-mode/).
+
 ### `alert_help_url` — "How to read this alert" link
 
 Every default-rendered alert on every channel carries a `How to read this alert`
@@ -116,10 +137,12 @@ alert_channels:
 
 ### Database profiles
 
-> ClickHouse, PostgreSQL, MySQL and MariaDB are all fully supported.
+> ClickHouse, PostgreSQL, MySQL, MariaDB and DuckDB are all supported.
 > ClickHouse/MySQL/MariaDB use two *databases*; PostgreSQL connects to one
-> `database` and uses two *schemas*.
-> `dtk init --db-type {clickhouse,postgres,mysql,mariadb}` scaffolds the right shape.
+> `database` and uses two *schemas*; DuckDB is a single *file* (or `:memory:`
+> for tests) holding two *schemas*.
+> `dtk init --db-type {clickhouse,postgres,mysql,mariadb}` scaffolds the right
+> shape — DuckDB profiles are written by hand (not yet a `--db-type` choice).
 
 **ClickHouse**:
 ```yaml
@@ -173,6 +196,25 @@ auto-detected at connect (`SELECT VERSION()`), so MariaDB gets its own
 `VALUES()`-form upsert instead of MySQL 8.0.19's row-alias form.
 `pip install 'detectkit[mariadb]'`.
 
+**DuckDB** (embedded, single file; two schemas like PostgreSQL):
+```yaml
+profiles:
+  prod:
+    type: duckdb
+    path: /var/lib/detectkit/warehouse.duckdb   # required — file path, or ":memory:"
+    internal_schema: detectkit     # optional — _dtk_* tables (default: "detectkit")
+    data_schema: main              # optional — data queries (default: "main")
+    read_only: false               # optional (default: false)
+    settings: {}                   # optional — extra duckdb.connect() config options
+```
+> Single-writer: DuckDB allows only **one** read-write connection to the file
+> at a time — a `dtk ui`/`dtk tune` session left open will clash with a
+> separately spawned `dtk run` against the same file. Point a read-only
+> consumer at it with `read_only: true`.
+> `path: ":memory:"` has no on-disk state, so resume/idempotency breaks across
+> process restarts — use it for tests/scratch only, never a real project.
+> `pip install 'detectkit[duckdb]'`.
+
 ### Alert channels
 
 Defined once in `profiles.yml`, referenced by name in each metric's

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/assets/claude/skills/dtk-setup-project/SKILL.md

@@ -50,13 +50,17 @@ side by side, ask which one to set up.
 
 ## Step 1 — Pick the database backend
 
-**ClickHouse, PostgreSQL, MySQL and MariaDB are all fully supported.** Ask
+**ClickHouse, PostgreSQL, MySQL, MariaDB and DuckDB are all supported.** Ask
 which one the project uses (default to ClickHouse if unsure). `dtk init
 --db-type {clickhouse,postgres,mysql,mariadb}` scaffolds `profiles.yml` for the
-chosen backend. The location fields differ:
+chosen backend (DuckDB isn't a `--db-type` choice yet — write its profile by
+hand; see `project.md`). The location fields differ:
 - **ClickHouse** / **MySQL** / **MariaDB** — two *databases*: `internal_database` / `data_database`.
 - **PostgreSQL** — connect to a `database` (must already exist), then two
   *schemas*: `internal_schema` / `data_schema`.
+- **DuckDB** — a single **file** (`path`, or `":memory:"` for tests only),
+  then two *schemas*: `internal_schema` / `data_schema`. No host/port/user/
+  password — it's an embedded, single-writer database (see `project.md`).
 
 `type: mariadb` is an identical profile alias to `type: mysql` (same location
 fields; the vendor is auto-detected at connect). The metric query SQL dialect

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/commands/init.py

@@ -123,6 +123,15 @@ _COMMENTED_EXAMPLES = {
   #   password: ""
   #   internal_database: detectkit
   #   data_database: analytics
+""",
+    "duckdb": """  # Example DuckDB profile (in-process, single-file; no host/port/user/password)
+  # duckdb_dev:
+  #   type: duckdb
+  #   path: ./detectkit.duckdb   # or ':memory:' for a transient, tests-only DB
+  #   internal_schema: detectkit
+  #   data_schema: main
+  #   # Only ONE read-write connection at a time — don't point a scheduled
+  #   # `dtk run` and a long-lived `dtk ui` at the same file simultaneously.
 """,
 }
 
@@ -351,7 +360,10 @@ timeouts:
     # live under a top-level 'profiles:' mapping). The active dev/prod profiles
     # are scaffolded for the chosen --db-type; the other backends are included
     # as commented examples. See the per-database docs for connection details.
-    other_backends = [t for t in ("clickhouse", "postgres", "mysql") if t != db_type]
+    # "duckdb" is not a `--db-type` choice (there is no active/prod scaffold
+    # for it — an in-process file DB has no separate dev/prod endpoints), so
+    # it always shows up as a commented example, unlike the other backends.
+    other_backends = [t for t in ("clickhouse", "postgres", "mysql", "duckdb") if t != db_type]
     commented = "\n".join(_COMMENTED_EXAMPLES[t] for t in other_backends)
     profiles_config = (
         "# Database connection profiles\n\n"

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/cli/commands/run.py

@@ -13,7 +13,7 @@ from typing import Any
 
 import click
 
-from detectkit.config.metric_config import MetricConfig
+from detectkit.config.metric_config import MetricConfig, resolve_source_profile
 from detectkit.config.profile import ProfilesConfig
 from detectkit.config.project_config import ProjectConfig
 from detectkit.config.validator import (
@@ -326,6 +326,21 @@ def _run_impl(
         summary["error"] = f"Error loading profiles.yml: {e}"
         return 1
 
+    # Fail-fast: every selected metric's RESOLVED source_profile (hybrid
+    # mode) must name a real profile. This is a cheap name check — no
+    # connections opened — so a typo'd source_profile fails the whole run
+    # up front instead of surfacing deep inside whichever metric's LOAD step
+    # happens to hit it first.
+    source_profile_error = _validate_source_profiles(metrics, project_config, profiles_config)
+    if source_profile_error:
+        # A config typo, not an outage: exit 1 without paging error_alerting,
+        # consistent with the sibling config-error paths (bad selector,
+        # unparseable profiles.yml). The error alert channel is reserved for
+        # DB-down / DDL / runtime failures.
+        click.echo(click.style(f"Error: {source_profile_error}", fg="red", bold=True))
+        summary["error"] = f"Error: {source_profile_error}"
+        return 1
+
     # Create database manager
     try:
         db_manager = profiles_config.create_manager(profile)
@@ -372,84 +387,136 @@ def _run_impl(
         summary["error"] = f"Error initializing internal tables: {e}"
         return 1
 
+    # The active STATE profile's actual name (mirrors ProfilesConfig.get_profile's
+    # own None -> default_profile resolution) — lets the task manager recognize
+    # a metric's source_profile that happens to name the state profile itself,
+    # and reuse db_manager instead of opening a duplicate connection.
+    state_profile_name: str | None
+    if profile is not None:
+        state_profile_name = profile
+    else:
+        state_profile_name = getattr(profiles_config, "default_profile", None)
+
     # Create task manager
     task_manager = TaskManager(
         internal_manager=internal_manager,
         db_manager=db_manager,
         profiles_config=profiles_config,
         project_config=project_config,
+        state_profile_name=state_profile_name,
     )
 
-    # Process each metric
-    for index, (metric_path, config) in enumerate(metrics):
-        result = process_metric(
-            metric_path=metric_path,
-            config=config,
-            project_root=project_root,
-            task_manager=task_manager,
-            steps=step_list,
-            from_date=from_dt,
-            to_date=to_dt,
-            full_refresh=full_refresh,
-            force=force,
-        )
-        summary["metrics"].append(
-            {
-                "name": config.name,
-                "status": _status_str(result["status"]),
-                "steps_completed": [s.value for s in result["steps_completed"]],
-                "datapoints_loaded": result["datapoints_loaded"],
-                "anomalies_detected": result["anomalies_detected"],
-                "alerts_sent": result["alerts_sent"],
-                "error": result["error"],
-            }
-        )
-
-        # Project-level error alert was dispatched — stop processing the
-        # rest of the metrics. The DB / source is presumed unreachable;
-        # subsequent metrics would all fail with the same error.
-        if result.get("abort_run"):
-            click.echo(
-                click.style(
-                    "✗ Aborting run after project error alert. " "Remaining metrics skipped.",
-                    fg="red",
-                    bold=True,
-                )
+    try:
+        # Process each metric
+        for index, (metric_path, config) in enumerate(metrics):
+            result = process_metric(
+                metric_path=metric_path,
+                config=config,
+                project_root=project_root,
+                task_manager=task_manager,
+                steps=step_list,
+                from_date=from_dt,
+                to_date=to_dt,
+                full_refresh=full_refresh,
+                force=force,
+            )
+            summary["metrics"].append(
+                {
+                    "name": config.name,
+                    "status": _status_str(result["status"]),
+                    "steps_completed": [s.value for s in result["steps_completed"]],
+                    "datapoints_loaded": result["datapoints_loaded"],
+                    "anomalies_detected": result["anomalies_detected"],
+                    "alerts_sent": result["alerts_sent"],
+                    "error": result["error"],
+                }
             )
-            summary["aborted"] = True
-            for _, skipped_config in metrics[index + 1 :]:
-                summary["metrics"].append(
-                    {
-                        "name": skipped_config.name,
-                        "status": "skipped",
-                        "steps_completed": [],
-                        "datapoints_loaded": 0,
-                        "anomalies_detected": 0,
-                        "alerts_sent": 0,
-                        "error": None,
-                    }
-                )
-            break
 
-        # Optional: emit a self-contained HTML report from the freshly-persisted
-        # internal tables (values + bands + anomalies + replayed alerts).
-        if report_path is not None:
-            try:
-                emit_metric_report(
-                    config=config,
-                    project_root=project_root,
-                    internal_manager=internal_manager,
-                    report_path=report_path,
-                    project_name=getattr(project_config, "name", None),
-                    project_loading_delay=getattr(project_config, "loading_delay", None),
-                    from_dt=from_dt,
-                    to_dt=to_dt,
+            # Project-level error alert was dispatched — stop processing the
+            # rest of the metrics. The DB / source is presumed unreachable;
+            # subsequent metrics would all fail with the same error.
+            if result.get("abort_run"):
+                click.echo(
+                    click.style(
+                        "✗ Aborting run after project error alert. " "Remaining metrics skipped.",
+                        fg="red",
+                        bold=True,
+                    )
                 )
-            except Exception as report_error:  # never fail the run on a report
-                click.echo(click.style(f"  │ Report skipped: {report_error}", fg="yellow"))
-
-    failed = any(m["status"] == "failed" for m in summary["metrics"])
-    return 1 if (failed or summary["aborted"]) else 0
+                summary["aborted"] = True
+                for _, skipped_config in metrics[index + 1 :]:
+                    summary["metrics"].append(
+                        {
+                            "name": skipped_config.name,
+                            "status": "skipped",
+                            "steps_completed": [],
+                            "datapoints_loaded": 0,
+                            "anomalies_detected": 0,
+                            "alerts_sent": 0,
+                            "error": None,
+                        }
+                    )
+                break
+
+            # Optional: emit a self-contained HTML report from the freshly-persisted
+            # internal tables (values + bands + anomalies + replayed alerts).
+            if report_path is not None:
+                try:
+                    emit_metric_report(
+                        config=config,
+                        project_root=project_root,
+                        internal_manager=internal_manager,
+                        report_path=report_path,
+                        project_name=getattr(project_config, "name", None),
+                        project_loading_delay=getattr(project_config, "loading_delay", None),
+                        from_dt=from_dt,
+                        to_dt=to_dt,
+                    )
+                except Exception as report_error:  # never fail the run on a report
+                    click.echo(click.style(f"  │ Report skipped: {report_error}", fg="yellow"))
+
+        failed = any(m["status"] == "failed" for m in summary["metrics"])
+        return 1 if (failed or summary["aborted"]) else 0
+    finally:
+        # Close every pooled hybrid-mode SOURCE manager (never db_manager
+        # itself — this function owns that connection's lifecycle, and it
+        # was never explicitly closed here either, before or after hybrid
+        # mode existed). Duck-typed lookup: a test double standing in for
+        # TaskManager need not implement it.
+        close_sources = getattr(task_manager, "close_sources", None)
+        if close_sources is not None:
+            close_sources()
+
+
+def _validate_source_profiles(
+    metrics: list[tuple[Path, MetricConfig]],
+    project_config: ProjectConfig,
+    profiles_config: ProfilesConfig,
+) -> str | None:
+    """Cheap, connection-free check that every metric's RESOLVED
+    ``source_profile`` (hybrid mode) names a real profile.
+
+    Returns an error message naming every offending metric, or ``None`` when
+    every resolved name is either unset (no hybrid override) or a known
+    profile. Runs before any database manager is built.
+    """
+    project_source_profile = getattr(project_config, "source_profile", None)
+    known_profiles = getattr(profiles_config, "profiles", {}) or {}
+    unknown: dict[str, str] = {}
+    for _, config in metrics:
+        name = resolve_source_profile(
+            getattr(config, "source_profile", None), project_source_profile
+        )
+        if name is not None and name not in known_profiles:
+            unknown[config.name] = name
+    if not unknown:
+        return None
+    details = ", ".join(f"{m} -> '{p}'" for m, p in sorted(unknown.items()))
+    available = ", ".join(sorted(known_profiles.keys()))
+    return (
+        f"Unknown source_profile referenced by metric(s): {details}. "
+        f"Available profiles: {available}"
+    )
 
 
 def _resolve_report_path(report_path: str, project_root: Path, metric_name: str) -> Path:

{detectkit-0.59.0 → detectkit-0.61.0}/detectkit/config/metric_config.py

@@ -627,6 +627,8 @@ class MetricConfig(BaseModel):
         description: Optional metric description (supports multi-line text)
         tags: Optional list of tags for metric selection (e.g., ["critical", "api"])
         profile: Profile name to use (overrides default_profile from project config)
+        source_profile: Hybrid mode — profile whose database runs this metric's
+            SQL, while _dtk_* state stays in the active (state) profile
         query: Inline SQL query (mutually exclusive with query_file)
         query_file: Path to SQL file (mutually exclusive with query)
         query_columns: Column name mapping for query results
@@ -684,6 +686,22 @@ class MetricConfig(BaseModel):
     profile: str | None = Field(
         default=None, description="Profile name to use (overrides default_profile)"
     )
+    # Hybrid mode: run this metric's SQL against a different database than the
+    # one holding _dtk_* state. Unlike `profile` above (which is dead — only
+    # round-tripped by autotune's config emitter), this is live: the load step
+    # resolves it to a pooled `ProfilesConfig.create_manager(...)` and executes
+    # the metric's query through it, while every other step (detect/alert) and
+    # save_datapoints itself keep using the active state profile. Falls back to
+    # ProjectConfig.source_profile, then None (= use the state profile).
+    source_profile: str | None = Field(
+        default=None,
+        description=(
+            "profiles.yml profile whose database runs this metric's SQL; "
+            "_dtk_* state stays in the active (state) profile. Falls back to "
+            "the project-level source_profile, then to the state profile "
+            "itself."
+        ),
+    )
     query: str | None = Field(default=None, description="Inline SQL query")
     query_file: Path | None = Field(default=None, description="Path to SQL file")
     query_columns: QueryColumnsConfig | None = Field(
@@ -1054,6 +1072,24 @@ def resolve_loading_delay_seconds(
     return 0
 
 
+def resolve_source_profile(
+    metric_source_profile: str | None, project_source_profile: str | None
+) -> str | None:
+    """Resolve the profiles.yml profile that should run a metric's SQL:
+    metric -> project -> ``None``.
+
+    ``None`` means "run the SQL through the same connection detectkit is
+    already using for ``_dtk_*`` state" — i.e. hybrid mode is off for this
+    metric and the meaning of ``dtk run --profile`` / ``default_profile`` is
+    unchanged. The first configured value wins, mirroring
+    :func:`resolve_loading_delay_seconds`'s metric -> project precedence.
+    """
+    for value in (metric_source_profile, project_source_profile):
+        if value is not None:
+            return value
+    return None
+
+
 def resolve_grid_phase_seconds(loading_start_time: str | None, interval_seconds: int) -> int:
     """Phase of the metric's interval grid on the epoch clock, in ``[0, interval)``.