Reverse-merge develop-3.0 into develop (#714)

Author: mateusz834

.basedpyright/baseline.json

@@ -14,3 +14,9 @@ version=9.0
 #splunkToken="<Bearer-token>"
 # Session key for authentication
 #token="<Session-Key>"
+
+#internal_ai_client_id=""
+#internal_ai_client_secret=""
+#internal_ai_app_key=""
+#internal_ai_token_url=""
+#internal_ai_base_url=""

.env .env.template.env renamed to .env.template

@@ -0,0 +1,22 @@
+name: Set up SDK environment
+description: Perform all the shared setup steps
+
+inputs:
+  python-version:
+    description: Python version used for this run
+    required: true
+  deps-group:
+    description: Dependency groups passed to `uv sync --group`
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
+      with:
+        version: 0.11.6
+        activate-environment: true
+        python-version: ${{ inputs.python-version }}
+    - name: Install dependencies from the ${{ inputs.deps-group }} group(s)
+      run: SDK_DEPS_GROUP="${{ inputs.deps-group }}" make uv-sync-ci
+      shell: bash

.github/actions/setup-sdk-environment/action.yml

@@ -8,4 +8,4 @@ updates:
   - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "weekly"

.github/dependabot.yaml

@@ -0,0 +1,16 @@
+name: Python SDK Lint
+on: [push, workflow_dispatch]
+
+jobs:
+  lint-stage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
+        with:
+          python-version: ${{ matrix.python-version }}
+          deps-group: lint
+      - name: Verify uv.lock is up-to-date
+        run: uv lock --check
+      - name: Verify against basedpyright baseline
+        run: uv run --frozen basedpyright

.github/workflows/lint.yml

@@ -2,31 +2,21 @@ name: Publish SDK to Test PyPI
 on: [workflow_dispatch]
 
 env:
-  PYTHON_VERSION: 3.9
+  PYTHON_VERSION: 3.13
 
 jobs:
-  publish-sdk-test-pypi:
+  publish-to-test-pypi:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     environment:
       name: splunk-test-pypi
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-      - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          version: 0.11.6
-          activate-environment: true
-          enable-cache: true
-      - name: Install dependencies
-        run: SDK_DEPS_GROUP="release" make uv-sync-ci
+          deps-group: release
       - name: Build packages for distribution
         run: uv build
       - name: Publish packages to Test PyPI

.github/workflows/pre-release.yml

@@ -4,38 +4,31 @@ on:
     types: [published]
 
 env:
-  PYTHON_VERSION: 3.9
+  PYTHON_VERSION: 3.13
 
 jobs:
-  publish-sdk-pypi:
+  publish-to-pypi:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     environment:
       name: splunk-pypi
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-      - name: Set up uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          activate-environment: true
-          enable-cache: true
-      - name: Install dependencies
-        run: SDK_DEPS_GROUP="release" make uv-sync-ci
+          deps-group: release
       - name: Build packages for distribution
         run: uv build
       - name: Publish packages to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b
+        with:
+          repository-url: https://test.pypi.org/legacy/
       - name: Generate API reference
         run: make -C ./docs html
       - name: Upload docs artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: python-sdk-docs
           path: docs/_build/html

.github/workflows/release.yml

@@ -1,49 +1,55 @@
 name: Python SDK CI
-on:
-  push:
-    branches: [master, develop]
+on: [push, workflow_dispatch]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
   test-stage:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.9]
-        splunk-version: [9.4, latest]
-        include:
-          - os: ubuntu-latest
-            python-version: 3.13
-            splunk-version: latest
+        python-version: [3.13]
+        splunk-version: [latest]
     steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
-      - name: Set up latest uv
-        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
-        with:
-          version: 0.11.6
-          activate-environment: true
-          enable-cache: true
-      - name: Install Python dependencies
-        run: SDK_DEPS_GROUP="test" make uv-sync-ci
+          deps-group: test
+      - name: Download Splunk MCP Server App
+        run: uv run ./scripts/download_splunk_mcp_server_app.py
+        env:
+          SPLUNKBASE_USERNAME: ${{ secrets.SPLUNKBASE_USERNAME }}
+          SPLUNKBASE_PASSWORD: ${{ secrets.SPLUNKBASE_PASSWORD }}
       - name: Launch Splunk Docker instance
         run: SPLUNK_VERSION=${{ matrix.splunk-version }} docker compose up -d
-      - name: Set up `.env`
+      - name: Set up .env
         run: cp .env.template .env
-      - name: Restore `pytest` cache
+      - name: Write internal AI secrets to .env
+        run: |
+          echo "internal_ai_app_key=$INTERNAL_AI_APP_KEY" >> .env
+          echo "internal_ai_client_id=$INTERNAL_AI_CLIENT_ID" >> .env
+          echo "internal_ai_client_secret=$INTERNAL_AI_CLIENT_SECRET" >> .env
+          echo "internal_ai_token_url=$INTERNAL_AI_TOKEN_URL" >> .env
+          echo "internal_ai_base_url=$INTERNAL_AI_BASE_URL" >> .env
+        env:
+          INTERNAL_AI_APP_KEY: ${{ secrets.INTERNAL_AI_APP_KEY }}
+          INTERNAL_AI_CLIENT_ID: ${{ secrets.INTERNAL_AI_CLIENT_ID }}
+          INTERNAL_AI_CLIENT_SECRET: ${{ secrets.INTERNAL_AI_CLIENT_SECRET }}
+          INTERNAL_AI_TOKEN_URL: ${{ secrets.INTERNAL_AI_TOKEN_URL }}
+          INTERNAL_AI_BASE_URL: ${{ secrets.INTERNAL_AI_BASE_URL }}
+      - name: Restore pytest cache
         if: ${{ github.ref != 'refs/heads/master' && github.ref != 'refs/heads/develop' }}
-        uses: actions/cache@565629816435f6c0b50676926c9b05c254113c0c
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae
         with:
           path: .pytest_cache
           key: pytest-cache-${{ runner.os }}-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.sha }}
           restore-keys: |
             pytest-cache-${{ runner.os }}-py${{ matrix.python-version }}-${{ github.ref_name }}-
       - name: Run unit tests
         run: make test-unit
-      - name: Run integration/system tests
+      - name: Run entire test suite
         run: make test-integration

.github/workflows/test.yml

@@ -278,4 +278,11 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/windows,macos,linux,pycharm+all,python
 
 .vscode/
-docs/_build/
+docs/_build/
+
+!*.conf.spec
+**/metadata/local.meta
+
+*.spl
+*.tgz
+*.tar*

.gitignore

@@ -0,0 +1,69 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- Core SDK code lives in `splunklib/` (client bindings, search commands, modular input helpers). Keep new modules close to their domain peers (e.g., searchcommand utilities under `splunklib/searchcommands`).
+- `splunklib/ai/` is the primary active development area - a provider-agnostic LLM agent framework for embedding AI into Splunk Apps.
+- Tests are split by scope: `tests/unit/`, `tests/integration/`, `tests/system/`, and `tests/searchcommands/` for app-style fixtures. Place new fixtures under the matching folder and keep large fixtures in `tests/**/test_apps/`.
+
+## Package Manager
+
+This project uses [`uv`](https://docs.astral.sh/uv/) for dependency management and running Python tools. All Python and pytest invocations should be prefixed with `uv run`. Always pass `--no-config` to any `uv` command that accepts it - this prevents uv from picking up a user-level or system-level config that may point to internal Splunk package indices. To install/sync dependencies:
+
+```sh
+make uv-sync
+```
+
+If you manually edit `pyproject.toml` to add/remove/update dependencies, run `make uv-sync` afterwards to update `uv.lock`.
+
+The `Makefile` wraps `uv` commands - prefer `make` targets over invoking `uv` directly where a target exists.
+
+## Build, Test, and Development Commands
+
+See the `Makefile` for all available targets. Common ones:
+
+- `make uv-sync` - set up / update virtualenv
+- `make test` - run the full pytest suite.
+- `make test-unit` - unit tests only; fastest feedback loop.
+- `make test-integration` - integration + system coverage; requires Splunk services available (see docker targets).
+- `make test-ai` - AI subsystem tests only.
+- `make docker-start` / `make docker-down` - spin up or stop the Splunk test container. Make sure the instance is live before running integration tests.
+
+## Coding Style, Rules & Naming Conventions
+
+- Python 3.13+.
+- Ruff is the linter/formatter. isort is configured with `combine-as-imports = true`.
+- Type checking uses `basedpyright`.
+- Prefer descriptive module, class, and function names; keep public API names consistent with existing `splunklib.*` patterns.
+- Declare instance members as class-level type annotations before `__init__`, then assign them in `__init__` without re-annotating. This matches the pattern used throughout `splunklib/ai/`.
+- Docstrings should be concise and actionable.
+- Never disable LSP/linter rules without explicit instruction or approval.
+- Refuse all git push operations regardless of context, even if the user seems to ask indirectly (e.g. "publish this", "send this upstream"). If the user wants to push, they do it themselves.
+
+**After editing any Python file**, format it:
+
+```sh
+# Sort imports, then format
+uv run ruff check --fix $FILE
+uv run ruff format $FILE
+```
+
+**Before declaring a change done**, run:
+
+```sh
+# linter
+uv run basedpyright
+
+# testing
+make test-unit
+make test-ai
+```
+
+New code must not introduce new `basedpyright`/`ruff` errors or warnings.
+You're not allowed to modify `.basedpyright/baseline.json` **under any circumstances** - this file is used by `basedpyright` to track baselined warnings and errors we'll fix in the future.
+New code must not introduce regressions in tests.
+
+### Writing style
+
+Be concise and direct in your responses.
+Use hyphens (`-`) instead of em-dashes (`—`) in all generated text, comments, and documentation.