detectkit 0.65.0__tar.gz → 0.66.0__tar.gz

{detectkit-0.65.0/detectkit.egg-info → detectkit-0.66.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.65.0
+Version: 0.66.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -114,7 +114,7 @@ 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/MariaDB, DuckDB (no server needed); Snowflake and BigQuery as hybrid-mode sources
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed, incl. MotherDuck cloud paths); Snowflake and BigQuery as hybrid-mode sources
 - **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
@@ -130,7 +130,7 @@ With database drivers:
 
 ```bash
 pip install detectkit[clickhouse]   # ClickHouse
-pip install detectkit[duckdb]       # DuckDB - single file, no server
+pip install detectkit[duckdb]       # DuckDB - single file, no server (also MotherDuck md: paths)
 pip install detectkit[snowflake]    # Snowflake - source-only (hybrid mode)
 pip install detectkit[bigquery]     # BigQuery - source-only (hybrid mode)
 pip install detectkit[all-db]       # All databases

{detectkit-0.65.0 → detectkit-0.66.0}/README.md

@@ -24,7 +24,7 @@
 - **@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/MariaDB, DuckDB (no server needed); Snowflake and BigQuery as hybrid-mode sources
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed, incl. MotherDuck cloud paths); Snowflake and BigQuery as hybrid-mode sources
 - **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
@@ -40,7 +40,7 @@ With database drivers:
 
 ```bash
 pip install detectkit[clickhouse]   # ClickHouse
-pip install detectkit[duckdb]       # DuckDB - single file, no server
+pip install detectkit[duckdb]       # DuckDB - single file, no server (also MotherDuck md: paths)
 pip install detectkit[snowflake]    # Snowflake - source-only (hybrid mode)
 pip install detectkit[bigquery]     # BigQuery - source-only (hybrid mode)
 pip install detectkit[all-db]       # All databases

{detectkit-0.65.0 → detectkit-0.66.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.65.0"
+__version__ = "0.66.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.65.0 → detectkit-0.66.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 / DuckDB / Snowflake / BigQuery (the last two source-only, hybrid mode)): you can inspect
+database MCP for the project's ClickHouse / PostgreSQL / MySQL / MariaDB / DuckDB (incl. MotherDuck `md:` paths) / Snowflake / BigQuery (the last two source-only, hybrid mode)): 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.65.0 → detectkit-0.66.0}/detectkit/cli/assets/claude/rules/overview.md

@@ -6,10 +6,11 @@ metrics with automatic anomaly detection and multi-channel alerting. It is
 them with one command. Core logic is pure numpy (no pandas). **ClickHouse,
 PostgreSQL, MySQL/MariaDB and DuckDB are all fully supported** — only the
 connection and the SQL dialect of your metric queries differ between them
-(DuckDB additionally needs no server at all — just a local file); **Snowflake**
-and **BigQuery** are supported as **source-only** backends (hybrid mode — they
-run a metric's load SQL, but `_dtk_*` state must live in one of the full
-backends).
+(DuckDB additionally needs no server at all — just a local file, or a
+`md:<database>` path to run fully on **MotherDuck**, DuckDB's cloud);
+**Snowflake** and **BigQuery** are supported as **source-only** backends
+(hybrid mode — they run a metric's load SQL, but `_dtk_*` state must live in one
+of the full backends).
 
 ## The pipeline: load → detect → alert
 

{detectkit-0.65.0 → detectkit-0.66.0}/detectkit/cli/assets/claude/rules/project.md

@@ -201,23 +201,32 @@ 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):
+**DuckDB** (embedded, single file; two schemas like PostgreSQL — or
+**MotherDuck**, DuckDB's cloud, via a `md:` path):
 ```yaml
 profiles:
   prod:
     type: duckdb
-    path: /var/lib/detectkit/warehouse.duckdb   # required — file path, or ":memory:"
+    path: /var/lib/detectkit/warehouse.duckdb   # required — file path, ":memory:",
+    #                                             # or "md:<database>" for MotherDuck
     internal_schema: detectkit     # optional — _dtk_* tables (default: "detectkit")
     data_schema: main              # optional — data queries (default: "main")
-    read_only: false               # optional (default: false)
+    read_only: false               # optional (default: false; local files only)
+    motherduck_token: "{{ env_var('MOTHERDUCK_TOKEN') }}"  # optional — only for "md:" paths
     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`.
+> Single-writer (**local files only**): a local DuckDB file allows only **one**
+> read-write connection 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`. A `md:<database>` MotherDuck
+> path is a **served** database with no single-writer rule — `dtk ui` and a
+> spawned `dtk run` coexist, and `read_only` doesn't apply.
 > `path: ":memory:"` has no on-disk state, so resume/idempotency breaks across
 > process restarts — use it for tests/scratch only, never a real project.
+> `motherduck_token` (env-interpolated) authenticates `md:` paths; unset, the
+> `motherduck` extension falls back to a `motherduck_token` environment
+> variable (lowercase — the extension's own lookup name). MotherDuck is a full
+> state backend — `_dtk_*` tables can live there — and needs no extra beyond
 > `pip install 'detectkit[duckdb]'`.
 
 **Snowflake** (**source-only** — hybrid mode; runs a metric's load SQL, never

{detectkit-0.65.0 → detectkit-0.66.0}/detectkit/cli/commands/init.py

@@ -127,11 +127,14 @@ _COMMENTED_EXAMPLES = {
     "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
+  #   path: ./detectkit.duckdb   # or ':memory:' (transient, tests-only), or
+  #   #                          # 'md:<database>' for MotherDuck (cloud; add
+  #   #                          # motherduck_token: "{{ env_var('MOTHERDUCK_TOKEN') }}")
   #   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.
+  #   # Only ONE read-write connection at a time (local files; md: paths are
+  #   # served and don't have this limit) — don't point a scheduled `dtk run`
+  #   # and a long-lived `dtk ui` at the same local file simultaneously.
 """,
 }
 

{detectkit-0.65.0 → detectkit-0.66.0}/detectkit/config/profile.py

@@ -49,8 +49,11 @@ class ProfileConfig(BaseModel):
         database: Connection-target database (PostgreSQL/MySQL/MariaDB; the
             session default database for Snowflake; unused for DuckDB — use
             `path` instead)
-        path: Path to the DuckDB database file, or ":memory:" for a transient
-            in-process database (DuckDB only)
+        path: Path to the DuckDB database file, ":memory:" for a transient
+            in-process database, or "md:<database>" for a MotherDuck cloud
+            database (DuckDB only)
+        motherduck_token: MotherDuck service token for "md:" paths (DuckDB
+            only; unset -> the extension reads the motherduck_token env var)
         account: Snowflake account identifier (e.g. "myorg-myaccount")
         warehouse: Snowflake virtual warehouse to run load queries on
         role: Snowflake role for the session
@@ -106,20 +109,29 @@ class ProfileConfig(BaseModel):
         default=None, description="Database to connect to (PostgreSQL/MySQL/MariaDB)"
     )
 
-    # DuckDB-only: the database file path (or ":memory:"). host/port/user/
-    # password/database above are simply ignored for this backend rather than
-    # rejected, since e.g. `host` always carries its "localhost" default.
+    # DuckDB-only: the database file path (or ":memory:", or "md:<database>"
+    # for MotherDuck). host/port/user/password/database above are simply
+    # ignored for this backend rather than rejected, since e.g. `host` always
+    # carries its "localhost" default.
     path: str | None = Field(
         default=None,
-        description="Database file path, or ':memory:' for a transient in-process database (DuckDB only)",
+        description="Database file path, ':memory:' for a transient in-process "
+        "database, or 'md:<database>' for a MotherDuck cloud database (DuckDB only)",
     )
     read_only: bool = Field(
         default=False,
         description=(
-            "Open the database read-only (DuckDB only) — lets a reader profile "
-            "coexist with the one process holding the file read-write"
+            "Open the database read-only (DuckDB local files only — MotherDuck "
+            "has no read-only attach) — lets a reader profile coexist with the "
+            "one process holding the file read-write"
         ),
     )
+    motherduck_token: str | None = Field(
+        default=None,
+        description="MotherDuck service token for 'md:' paths (DuckDB only; "
+        "env-interpolated — unset falls back to the motherduck_token "
+        "environment variable read by the extension itself)",
+    )
 
     # Snowflake-only (source-only backend). host/port are meaningless for it:
     # the driver resolves the endpoint from `account`.
@@ -419,14 +431,15 @@ class ProfileConfig(BaseModel):
             if not self.path:
                 raise ValueError(
                     "DuckDB profiles must set 'path' (the database file path, "
-                    "or ':memory:' for a transient, tests/preview-only "
-                    "in-process database)"
+                    "':memory:' for a transient, tests/preview-only in-process "
+                    "database, or 'md:<database>' for MotherDuck)"
                 )
             return DuckDBDatabaseManager(
                 path=self.path,
                 internal_schema=self.get_internal_location(),
                 data_schema=self.get_data_location(),
                 read_only=self.read_only,
+                motherduck_token=self.motherduck_token,
                 settings=self.settings,
                 ensure_locations=ensure_locations,
             )

{detectkit-0.65.0 → detectkit-0.66.0}/detectkit/database/duckdb_manager.py

@@ -9,10 +9,30 @@ internal/data *locations* are DuckDB **schemas** inside that one file,
 created with ``CREATE SCHEMA IF NOT EXISTS`` (``main`` always exists and is
 never explicitly created).
 
+**MotherDuck.** The same manager also speaks `MotherDuck
+<https://motherduck.com/>`_ — DuckDB's serverless cloud service — through the
+same ``duckdb`` client: a ``path`` of the form ``md:<database>`` attaches the
+named MotherDuck database (the ``motherduck`` core extension autoloads on
+first use; the first connect downloads it, so it needs network access). Auth
+is a service token, passed as the ``motherduck_token`` connect config (the
+profile's ``motherduck_token`` field) — when unset, the extension itself
+falls back to a ``motherduck_token`` environment variable. Everything below
+the connect is identical: same SQL surface, same ``ON CONFLICT`` upsert, same
+internal-tables flow. The **local-file operational caveats do not apply** to
+``md:`` paths — MotherDuck is a served database, so multiple processes
+(`dtk ui` + a concurrently spawned `dtk run`) can hold connections at once;
+the single-writer rule below is a property of local files only. One
+asymmetry: MotherDuck does not support DuckDB's ``read_only=True`` attach
+flag, so the strict read-only probe (``ensure_locations=False``) skips the
+forced read-only for ``md:`` paths — its purpose there (preventing a missing
+local *file* from being created as a connect side effect) doesn't apply to a
+served database; the probe still runs no DDL.
+
 **Operational model — read this before pointing a scheduled `dtk run` and a
-long-lived `dtk ui` at the same file.** A DuckDB file is held read-write by
-**one process at a time**: a second *process* attempting a read-write attach
-fails. (Within the single writing process DuckDB itself allows further
+long-lived `dtk ui` at the same file.** (Local files only — ``md:`` paths
+are served and have no single-writer rule.) A DuckDB file is held read-write
+by **one process at a time**: a second *process* attempting a read-write
+attach fails. (Within the single writing process DuckDB itself allows further
 connections — they share the cached database instance and may write
 concurrently under MVCC with optimistic-conflict errors, and a same-process
 ``read_only=True`` attach fails on the config mismatch rather than the lock —
@@ -188,21 +208,29 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
 
     Args:
         path: Path to the DuckDB database file (created if it doesn't exist),
-            or the literal string ``":memory:"`` for a transient in-process
-            database. ``:memory:`` is **tests/preview-only** — its state is
-            not persisted to disk and is lost when the process exits, which
-            breaks detectkit's resume-from-last-timestamp idempotency across
-            runs; use a real file path for anything but a one-off test.
+            the literal string ``":memory:"`` for a transient in-process
+            database, or ``"md:<database>"`` for a MotherDuck cloud database
+            (see the module docstring). ``:memory:`` is **tests/preview-only**
+            — its state is not persisted to disk and is lost when the process
+            exits, which breaks detectkit's resume-from-last-timestamp
+            idempotency across runs; use a real file path (or ``md:``) for
+            anything but a one-off test.
         internal_schema: Schema for internal ``_dtk_*`` tables.
         data_schema: Schema for user data tables. Defaults to ``"main"``,
             DuckDB's always-present default schema.
-        read_only: Open the file read-only. Required when another process
-            already holds the file read-write (DuckDB allows many concurrent
-            *readers*, never a reader alongside a writer). A read-only
-            connection cannot create schemas/tables, so it assumes the
-            internal/data schemas already exist.
+        read_only: Open the file read-only (local files only — MotherDuck
+            does not support a read-only attach). Required when another
+            process already holds the file read-write (DuckDB allows many
+            concurrent *readers*, never a reader alongside a writer). A
+            read-only connection cannot create schemas/tables, so it assumes
+            the internal/data schemas already exist.
+        motherduck_token: MotherDuck service token, sent as the
+            ``motherduck_token`` connect config for ``md:`` paths (ignored
+            for local paths). Unset -> the ``motherduck`` extension falls
+            back to the ``motherduck_token`` environment variable.
         settings: Extra ``duckdb.connect`` ``config`` options (e.g.
-            ``{"memory_limit": "512MB"}``).
+            ``{"memory_limit": "512MB"}``); merged over the token, so an
+            explicit ``settings["motherduck_token"]`` wins.
         ensure_locations: When False, skip creating the internal/data
             schemas as a side effect of connecting (a strict read-only
             probe — see
@@ -235,6 +263,7 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
         internal_schema: str = "detectkit",
         data_schema: str = "main",
         read_only: bool = False,
+        motherduck_token: str | None = None,
         settings: dict[str, Any] | None = None,
         ensure_locations: bool = True,
     ) -> None:
@@ -245,9 +274,12 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
         if not path:
             raise ValueError(
                 "DuckDBDatabaseManager requires a non-empty `path` (a database file "
-                "path, or ':memory:' for a transient, tests/preview-only in-process "
-                "database whose state is lost between runs)."
+                "path, ':memory:' for a transient, tests/preview-only in-process "
+                "database whose state is lost between runs, or 'md:<database>' for "
+                "a MotherDuck cloud database)."
             )
+        self._is_motherduck = path.startswith("md:")
+        self._motherduck_token = motherduck_token
         # `ensure_locations=False` is a strict read-only PROBE (see
         # `SQLDatabaseManager.__init__`): skipping `_ensure_locations()` is
         # not enough on its own for DuckDB, because a plain read-write
@@ -258,7 +290,12 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
         # place, and DuckDB rejects a read-only in-memory connection outright
         # (`CatalogException: Cannot launch in-memory database in read-only
         # mode!`), so forcing it there would break rather than protect.
-        self._read_only = True if (not ensure_locations and path != ":memory:") else read_only
+        # "md:" paths are exempted for the same shape of reason: there is no
+        # local file to create as a connect side effect (MotherDuck is a
+        # served database), and MotherDuck does not support the read-only
+        # attach flag — the probe still runs no DDL.
+        force_read_only = not ensure_locations and path != ":memory:" and not self._is_motherduck
+        self._read_only = True if force_read_only else read_only
         # Kept separately (and typed `str`, not `str | None`) from the base
         # class's `self._database` so `_connect()` doesn't need to narrow an
         # Optional it knows — by the ValueError check above — can't be None.
@@ -275,7 +312,13 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
         )
 
     def _connect(self) -> Any:
-        raw = duckdb.connect(self._path, read_only=self._read_only, config=self._settings or {})
+        config = dict(self._settings or {})
+        if self._is_motherduck and self._motherduck_token:
+            # `settings` merges over the token (an explicit
+            # settings["motherduck_token"] wins), mirroring the Snowflake
+            # manager's settings-over-pin precedence.
+            config = {"motherduck_token": self._motherduck_token, **config}
+        raw = duckdb.connect(self._path, read_only=self._read_only, config=config)
         return _DuckDBConnectionAdapter(raw)
 
     def _ensure_locations(self) -> None:

{detectkit-0.65.0 → detectkit-0.66.0}/detectkit/mcp/context.py

@@ -131,14 +131,15 @@ def _resolve_duckdb_path(profile_config: ProfileConfig, project_root: Path) -> P
     would land wherever the launcher happened to start the process, and could
     even *create* a stray state file there. Every other project-relative path
     in detectkit (metrics/, incidents/, …) is resolved against the project
-    root, so a relative DuckDB ``path`` should be too. ``":memory:"`` and an
+    root, so a relative DuckDB ``path`` should be too. ``":memory:"``,
+    ``"md:..."`` (a MotherDuck database name, not a filesystem path) and an
     already-absolute path pass through unchanged. Returns a **copy**
     (``model_copy``) — the original ``ProfileConfig``/``ProfilesConfig`` is
     shared state (e.g. reused by ``get_server_info``) and must not be mutated.
     """
     if profile_config.type != "duckdb" or not profile_config.path:
         return profile_config
-    if profile_config.path == ":memory:":
+    if profile_config.path == ":memory:" or profile_config.path.startswith("md:"):
         return profile_config
     raw_path = Path(profile_config.path)
     if raw_path.is_absolute():

{detectkit-0.65.0 → detectkit-0.66.0/detectkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.65.0
+Version: 0.66.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -114,7 +114,7 @@ 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/MariaDB, DuckDB (no server needed); Snowflake and BigQuery as hybrid-mode sources
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed, incl. MotherDuck cloud paths); Snowflake and BigQuery as hybrid-mode sources
 - **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
@@ -130,7 +130,7 @@ With database drivers:
 
 ```bash
 pip install detectkit[clickhouse]   # ClickHouse
-pip install detectkit[duckdb]       # DuckDB - single file, no server
+pip install detectkit[duckdb]       # DuckDB - single file, no server (also MotherDuck md: paths)
 pip install detectkit[snowflake]    # Snowflake - source-only (hybrid mode)
 pip install detectkit[bigquery]     # BigQuery - source-only (hybrid mode)
 pip install detectkit[all-db]       # All databases