splunk · Ickerday · Dec 15, 2025 · Dec 15, 2025 · Dec 15, 2025 · Dec 15, 2025
diff --git a/.basedpyright/baseline.json b/.basedpyright/baseline.json
diff --git a/.env → .env.template b/.env → .env.template
@@ -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=""
diff --git a/.github/actions/setup-sdk-environment/action.yml b/.github/actions/setup-sdk-environment/action.yml
@@ -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
diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml
@@ -5,3 +5,7 @@ updates:
     target-branch: "develop"
     schedule:
       interval: "weekly"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/fossa.yml b/.github/workflows/fossa.yml
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -0,0 +1,16 @@
+name: Python SDK Lint
+on: [push, workflow_dispatch]
+
+jobs:
+  lint:
+    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
diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml
@@ -2,26 +2,23 @@ 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 source
-        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-      - name: Install dependencies
-        run: python -m pip install . --group build
+          deps-group: release
       - name: Build packages for distribution
-        run: python -m build
+        run: uv build
       - name: Publish packages to Test PyPI
         uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
         with:

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -4,32 +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 source
-        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e
-      - name: Set up Python ${{ env.PYTHON_VERSION }}
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-      - name: Install dependencies
-        run: python -m pip install . --group release
+          deps-group: release
       - name: Build packages for distribution
-        run: python -m build
+        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@330a01c490aca151604b8cf639adc76d48f6c5d4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
         with:
           name: python-sdk-docs
           path: docs/_build/html
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,39 +1,55 @@
-name: Python CI
+name: Python SDK CI
 on: [push, workflow_dispatch]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  run-test-suite:
+  test:
     runs-on: ${{ matrix.os }}
     strategy:
-      fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.9]
-        splunk-version: [9.4, latest]
-        include:
-          # Oldest possible configuration
-          # Last Ubuntu version with Python 3.7 binaries available
-          - os: ubuntu-22.04
-            python-version: 3.7
-            splunk-version: 9.1
-          # Latest possible configuration
-          - os: ubuntu-latest
-            python-version: 3.13
-            splunk-version: latest
+        python-version: [3.13]
+        splunk-version: [latest]
     steps:
-      - name: Checkout code
-        uses: actions/checkout@71cf2267d89c5cb81562390fa70a37fa40b1305e
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: ./.github/actions/setup-sdk-environment
+        with:
+          python-version: ${{ matrix.python-version }}
+          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: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c
+      - name: Set up .env
+        run: cp .env.template .env
+      - 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@27d5ce7f107fe9357f9df03efb73ab90386fccae
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: (Python 3.7) Install dependencies
-        if: ${{ matrix.python-version == '3.7' }}
-        run: python -m pip install python-dotenv pytest
-      - name: (Python >= 3.9) Install dependencies
-        if: ${{ matrix.python-version != '3.7' }}
-        run: python -m pip install . --group test
+          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 entire test suite
-        run: python -m pytest ./tests
+        run: make test-integration
diff --git a/.gitignore b/.gitignore
@@ -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*
diff --git a/AGENTS.md b/AGENTS.md
@@ -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.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+The core file containing repository guidelines for Agents is located in `AGENTS.md` file.
+Use this file as your guidelines.
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,31 @@
+ARG SPLUNK_VERSION=latest
+FROM splunk/splunk:${SPLUNK_VERSION}
+
+USER root
+
+# Copy splunk-mcp-server.tgz, we need to copy entire sdk since
+# splunk-mcp-server.tgz might not exist and we don't want to fail in such case.
+RUN mkdir /tmp/sdk
+COPY . /tmp/sdk
+RUN /bin/bash -c 'if [ -f /tmp/sdk/splunk-mcp-server.tgz ]; then cp /tmp/sdk/splunk-mcp-server.tgz /splunk-mcp-server.tgz; fi'
+RUN rm -rf /tmp/sdk
+
+RUN mkdir /tmp/sdk
+COPY ./pyproject.toml /tmp/sdk/pyproject.toml
+COPY ./uv.lock /tmp/sdk/uv.lock
+COPY ./splunklib /tmp/sdk/splunklib
+
+RUN mkdir /splunklib-deps
+RUN chown splunk:splunk /splunklib-deps
+RUN chown -R splunk:splunk /tmp/sdk
+RUN chown splunk:splunk /tmp/sdk
+
+USER splunk
+
+WORKDIR /tmp/sdk
+
+RUN /opt/splunk/bin/python3.13 -m venv .venv
+RUN /bin/bash -c "source .venv/bin/activate && LD_LIBRARY_PATH=/opt/splunk/lib python -m pip install '.[openai]' --target=/splunklib-deps"
+
+USER ${ANSIBLE_USER}
+WORKDIR /opt/splunk