diff --git a/.github/codeql/README.md b/.github/codeql/README.md
new file mode 100644
index 0000000..c84cbca
--- /dev/null
+++ b/.github/codeql/README.md
@@ -0,0 +1,131 @@
+# CodeQL Setup for deepiri-modelkit
+
+This folder contains the CodeQL configuration for security scanning in this service.
+
+## What each file does
+
+- `.github/workflows/codeql.yml`
+  - Defines when scans run and how GitHub Actions executes CodeQL.
+- `.github/codeql/codeql-config.yml`
+  - Defines what folders to include and ignore during analysis.
+
+## Workflow breakdown (`.github/workflows/codeql.yml`)
+
+### `name: CodeQL`
+The display name in the Actions tab.
+
+### `on.pull_request.branches` and `on.push.branches`
+```yaml
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+```
+Runs scans when PRs target `main` or `dev`, and when commits are pushed to `main` or `dev`.
+
+### `permissions`
+```yaml
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+```
+Uses least-privilege permissions. `security-events: write` is required so CodeQL can upload findings.
+
+### Language setup (current)
+```yaml
+with:
+  languages: python
+```
+This workflow currently runs analysis for Python.
+
+### Checkout step
+```yaml
+with:
+  fetch-depth: 0
+```
+- `fetch-depth: 0` keeps full git history (safe default for analysis and troubleshooting).
+
+### Initialize CodeQL
+```yaml
+uses: github/codeql-action/init@v3
+with:
+  config-file: ./.github/codeql/codeql-config.yml
+```
+Starts the CodeQL engine and loads `.github/codeql/codeql-config.yml`.
+
+### Analyze
+```yaml
+uses: github/codeql-action/analyze@v3
+```
+Executes queries and uploads results to GitHub Security.
+
+## Config breakdown (`.github/codeql/codeql-config.yml`)
+
+### `paths`
+The current include list is intentionally scoped to active service code:
+
+```yaml
+paths:
+  - src
+```
+
+### `paths-ignore`
+Generated and cache artifact paths are excluded to reduce noise and runtime:
+
+```yaml
+paths-ignore:
+  - '**/__pycache__/**'
+  - '**/.pytest_cache/**'
+  - '**/.mypy_cache/**'
+  - '**/.venv/**'
+  - '**/venv/**'
+  - '**/dist/**'
+  - '**/build/**'
+  - '**/*.min.js'
+```
+
+## Best practices
+
+1. Keep trigger scope intentional.
+   Use branch filters (`main`, `dev`) to control cost and noise.
+2. Keep language list explicit.
+   Only include languages with meaningful source code.
+3. Keep `paths` focused when used.
+   Include actively maintained production code first.
+4. Exclude generated/cache artifacts.
+   Keep build outputs and runtime caches in `paths-ignore`.
+5. Pin to stable major action versions.
+   `@v3` is the current stable major for CodeQL actions.
+6. Review alerts regularly.
+   Triage high/critical findings first and suppress only with documented reasoning.
+
+## Maintenance examples
+
+### Keep language scope aligned with this service
+This workflow currently analyzes Python only:
+
+```yaml
+with:
+  languages: python
+```
+
+Only change this value when this service adds production code in another supported language.
+
+### Include only specific top-level packages
+Add explicit `paths` only for directories that exist in this checkout.
+
+Example:
+
+```yaml
+paths:
+  - src
+```
+
+### Exclude another generated folder
+Add a glob to `paths-ignore`, for example:
+
+```yaml
+- '**/generated/**'
+```
diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml
new file mode 100644
index 0000000..8975aa8
--- /dev/null
+++ b/.github/codeql/codeql-config.yml
@@ -0,0 +1,16 @@
+name: deepiri-modelkit-codeql-config
+
+# Focus analysis on maintained source code for this service.
+paths:
+  - src
+
+# Exclude generated/build/cache artifacts.
+paths-ignore:
+  - '**/__pycache__/**'
+  - '**/.pytest_cache/**'
+  - '**/.mypy_cache/**'
+  - '**/.venv/**'
+  - '**/venv/**'
+  - '**/dist/**'
+  - '**/build/**'
+  - '**/*.min.js'
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..7594c2a
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,32 @@
+name: CodeQL
+
+on:
+  pull_request:
+    branches: [main, dev]
+  push:
+    branches: [main, dev]
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          config-file: ./.github/codeql/codeql-config.yml
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3