detectkit 0.59.0__tar.gz → 0.60.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.59.0
+Version: 0.60.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,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
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
 - **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.60.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
+- **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
 - **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.60.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.60.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.59.0 → detectkit-0.60.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.60.0}/detectkit/cli/assets/claude/rules/project.md

@@ -116,10 +116,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 +175,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.60.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.60.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.60.0}/detectkit/config/profile.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Any
 
 import yaml
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 from detectkit.database.clickhouse_manager import ClickHouseDatabaseManager
 from detectkit.database.manager import BaseDatabaseManager
@@ -23,44 +23,68 @@ class ProfileConfig(BaseModel):
     environment (dev, prod, etc.).
 
     Attributes:
-        type: Database type ("clickhouse", "postgres", "mysql", "mariadb")
-        host: Database host
-        port: Database port
-        user: Database user
-        password: Database password
+        type: Database type ("clickhouse", "postgres", "mysql", "mariadb", "duckdb")
+        host: Database host (unused for DuckDB — it is an in-process, file-backed
+            database with no network endpoint)
+        port: Database port (unused for DuckDB; required for every other backend)
+        user: Database user (unused for DuckDB)
+        password: Database password (unused for DuckDB)
+        database: Connection-target database (PostgreSQL/MySQL/MariaDB; unused
+            for DuckDB — use `path` instead)
+        path: Path to the DuckDB database file, or ":memory:" for a transient
+            in-process database (DuckDB only)
         internal_database: Database/schema for internal tables
-        internal_schema: Schema for internal tables (PostgreSQL only)
+        internal_schema: Schema for internal tables (PostgreSQL/DuckDB only)
         data_database: Database for user data tables
-        data_schema: Schema for user data (PostgreSQL only)
+        data_schema: Schema for user data (PostgreSQL/DuckDB only)
         settings: Additional database-specific settings
     """
 
     type: str = Field(..., description="Database type")
-    host: str = Field(default="localhost", description="Database host")
-    port: int = Field(..., description="Database port")
-    user: str = Field(default="default", description="Database user")
-    password: str = Field(default="", description="Database password")
+    host: str = Field(default="localhost", description="Database host (unused for DuckDB)")
+    # No default: required for every backend except DuckDB (enforced below by
+    # `_validate_port_required`, since DuckDB has no network port at all).
+    port: int | None = Field(default=None, description="Database port (unused for DuckDB)")
+    user: str = Field(default="default", description="Database user (unused for DuckDB)")
+    password: str = Field(default="", description="Database password (unused for DuckDB)")
 
     # Connection-target database. Required for PostgreSQL (the database to
     # connect to, inside which internal_schema/data_schema live); optional for
-    # MySQL/MariaDB; unused for ClickHouse.
+    # MySQL/MariaDB; unused for ClickHouse and DuckDB.
     database: str | None = Field(
         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.
+    path: str | None = Field(
+        default=None,
+        description="Database file path, or ':memory:' for a transient in-process 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"
+        ),
+    )
+
     # Internal location for _dtk_* tables
     internal_database: str | None = Field(
         default=None, description="Database for internal tables (ClickHouse/MySQL/MariaDB)"
     )
     internal_schema: str | None = Field(
-        default=None, description="Schema for internal tables (PostgreSQL)"
+        default=None, description="Schema for internal tables (PostgreSQL/DuckDB)"
     )
 
     # Data location for user tables
     data_database: str | None = Field(
         default=None, description="Database for user data tables (ClickHouse/MySQL/MariaDB)"
     )
-    data_schema: str | None = Field(default=None, description="Schema for user data (PostgreSQL)")
+    data_schema: str | None = Field(
+        default=None, description="Schema for user data (PostgreSQL/DuckDB)"
+    )
 
     settings: dict[str, Any] = Field(
         default_factory=dict, description="Additional database settings"
@@ -70,7 +94,7 @@ class ProfileConfig(BaseModel):
     @classmethod
     def validate_type(cls, v: str) -> str:
         """Validate database type."""
-        allowed_types = {"clickhouse", "postgres", "mysql", "mariadb"}
+        allowed_types = {"clickhouse", "postgres", "mysql", "mariadb", "duckdb"}
         if v not in allowed_types:
             raise ValueError(
                 f"Invalid database type: {v}. " f"Allowed types: {', '.join(allowed_types)}"
@@ -79,12 +103,21 @@ class ProfileConfig(BaseModel):
 
     @field_validator("port")
     @classmethod
-    def validate_port(cls, v: int) -> int:
-        """Validate port number."""
+    def validate_port(cls, v: int | None) -> int | None:
+        """Validate port number (when set — DuckDB profiles may omit it)."""
+        if v is None:
+            return v
         if not (1 <= v <= 65535):
             raise ValueError(f"Port must be between 1 and 65535, got {v}")
         return v
 
+    @model_validator(mode="after")
+    def _validate_port_required(self) -> "ProfileConfig":
+        """Every backend but DuckDB needs a port; DuckDB has no network endpoint."""
+        if self.type != "duckdb" and self.port is None:
+            raise ValueError(f"port is required for database type '{self.type}'")
+        return self
+
     def get_internal_location(self) -> str:
         """
         Get internal location (database or schema).
@@ -107,6 +140,10 @@ class ProfileConfig(BaseModel):
             if not self.internal_database:
                 raise ValueError("internal_database must be set for MySQL/MariaDB")
             return self.internal_database
+        elif self.type == "duckdb":
+            # Mirrors DuckDBDatabaseManager's own default (unlike PostgreSQL,
+            # an unset internal_schema doesn't need to be an error here).
+            return self.internal_schema or "detectkit"
         else:
             raise ValueError(f"Unsupported database type: {self.type}")
 
@@ -132,6 +169,10 @@ class ProfileConfig(BaseModel):
             if not self.data_database:
                 raise ValueError("data_database must be set for MySQL/MariaDB")
             return self.data_database
+        elif self.type == "duckdb":
+            # Mirrors DuckDBDatabaseManager's own default data_schema ("main",
+            # DuckDB's always-present default schema).
+            return self.data_schema or "main"
         else:
             raise ValueError(f"Unsupported database type: {self.type}")
 
@@ -144,10 +185,14 @@ class ProfileConfig(BaseModel):
 
         Raises:
             ValueError: If the database type is unsupported, or required
-                connection fields (e.g. PostgreSQL ``database``) are missing
+                connection fields (e.g. PostgreSQL ``database``, DuckDB
+                ``path``) are missing
             ImportError: If the backend's driver is not installed
         """
         if self.type == "clickhouse":
+            # `port` is guaranteed non-None here by `_validate_port_required`
+            # (every type but "duckdb" requires it at construction time).
+            assert self.port is not None
             return ClickHouseDatabaseManager(
                 host=self.host,
                 port=self.port,
@@ -165,6 +210,7 @@ class ProfileConfig(BaseModel):
                     "PostgreSQL profiles must set 'database' (the database to "
                     "connect to, inside which internal_schema/data_schema live)"
                 )
+            assert self.port is not None
             return PostgresDatabaseManager(
                 host=self.host,
                 port=self.port,
@@ -180,6 +226,7 @@ class ProfileConfig(BaseModel):
             # connect time and adjusts the upsert SQL it generates accordingly.
             from detectkit.database.mysql_manager import MySQLDatabaseManager
 
+            assert self.port is not None
             return MySQLDatabaseManager(
                 host=self.host,
                 port=self.port,
@@ -190,6 +237,26 @@ class ProfileConfig(BaseModel):
                 data_database=self.get_data_location(),
                 settings=self.settings,
             )
+        elif self.type == "duckdb":
+            # In-process, file-backed database: host/port/user/password/database
+            # are meaningless for it and are simply not read here (rather than
+            # rejected — `host`/`user`/`password` always carry non-empty
+            # defaults, so rejecting them would punish every duckdb profile).
+            from detectkit.database.duckdb_manager import DuckDBDatabaseManager
+
+            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)"
+                )
+            return DuckDBDatabaseManager(
+                path=self.path,
+                internal_schema=self.get_internal_location(),
+                data_schema=self.get_data_location(),
+                read_only=self.read_only,
+                settings=self.settings,
+            )
         else:
             raise ValueError(f"Unsupported database type: {self.type}")