vaultspec-rag 0.2.0a0__tar.gz

vaultspec_rag-0.2.0a0/.env.example

@@ -0,0 +1,49 @@
+# Copy this file to .env and fill in your values.
+# .env is gitignored — never commit real tokens.
+
+# HuggingFace access token — required for gated models (naver/splade-v3).
+# Get yours at https://huggingface.co/settings/tokens
+# Accept naver/splade-v3 terms at https://huggingface.co/naver/splade-v3
+HF_TOKEN=hf_...
+
+# ---------------------------------------------------------------------------
+# vaultspec-rag configuration
+# All settings follow the resolution order: CLI arg > env var > config default.
+# See config.py EnvVar enum for the authoritative list.
+# ---------------------------------------------------------------------------
+
+# Project root directory (default: git root or cwd).
+# CLI: --target
+# VAULTSPEC_RAG_ROOT=
+
+# RAG data root relative to project root (default: .vault/data/search-data).
+# CLI: --data-dir
+# VAULTSPEC_RAG_DATA_DIR=.vault/data/search-data
+
+# Qdrant storage subdirectory relative to data root (default: qdrant).
+# CLI: --qdrant-dir
+# VAULTSPEC_RAG_QDRANT_DIR=qdrant
+
+# Vault index metadata filename relative to data root (default: index_meta.json).
+# CLI: --index-meta
+# VAULTSPEC_RAG_INDEX_META=index_meta.json
+
+# Code index metadata filename relative to data root (default: code_index_meta.json).
+# CLI: --code-index-meta
+# VAULTSPEC_RAG_CODE_INDEX_META=code_index_meta.json
+
+# Service status directory — stores service.json and logs (default: ~/.vaultspec-rag).
+# CLI: --status-dir
+# VAULTSPEC_RAG_STATUS_DIR=~/.vaultspec-rag
+
+# Service log filename relative to status dir (default: service.log).
+# CLI: --log-file
+# VAULTSPEC_RAG_LOG_FILE=service.log
+
+# MCP server port (default: 8766).
+# CLI: --port
+# VAULTSPEC_RAG_PORT=8766
+
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: WARNING).
+# CLI: --verbose (INFO) / --debug (DEBUG)
+# VAULTSPEC_RAG_LOG_LEVEL=WARNING

vaultspec_rag-0.2.0a0/.gitattributes

@@ -0,0 +1,61 @@
+# Handle line endings automatically for files detected as text
+# and leave binary files untouched.
+* text=auto
+
+# Python files
+*.py      text eol=lf
+*.pyi     text eol=lf
+*.pyw     text eol=lf
+
+# Web files
+*.html    text eol=lf diff=html
+*.css     text eol=lf
+*.js      text eol=lf
+*.ts      text eol=lf
+*.tsx     text eol=lf
+*.json    text eol=lf
+
+# Documentation
+*.md      text eol=lf
+*.txt     text eol=lf
+
+# Data/Config
+*.yml     text eol=lf
+*.yaml    text eol=lf
+*.toml    text eol=lf
+*.xml     text eol=lf
+
+# Shell scripts
+*.sh      text eol=lf
+
+# Batch files
+*.bat     text eol=crlf
+
+# Binary files
+*.png     binary
+*.jpg     binary
+*.jpeg    binary
+*.gif     binary
+*.ico     binary
+*.mov     binary
+*.mp4     binary
+*.mp3     binary
+*.flv     binary
+*.fla     binary
+*.swf     binary
+*.gz      binary
+*.zip     binary
+*.7z      binary
+*.ttf     binary
+*.pyc     binary
+*.pyo     binary
+*.pyd     binary
+*.so      binary
+*.dll     binary
+*.exe     binary
+
+# >>> vaultspec-managed (do not edit this block) >>>
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+# <<< vaultspec-managed <<<

vaultspec_rag-0.2.0a0/.github/actionlint.yaml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - dev-runner

vaultspec_rag-0.2.0a0/.github/workflows/add-to-project.yml

@@ -0,0 +1,27 @@
+name: Add to Development Board
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  add-to-project:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v1
+        id: add
+        with:
+          project-url: https://github.com/users/wgergely/projects/3
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+
+      - name: Set target date to created_at + 30 days
+        env:
+          GH_TOKEN: ${{ secrets.ADD_TO_PROJECT_PAT }}
+        run: |
+          DEADLINE=$(date -d "+30 days" +%Y-%m-%d)
+          gh project item-edit \
+            --project-id PVT_kwHOAKyuWc4BS9uc \
+            --id ${{ steps.add.outputs.itemId }} \
+            --field-id PVTF_lAHOAKyuWc4BS9uczhAaFWg \
+            --date "$DEADLINE"
+

vaultspec_rag-0.2.0a0/.github/workflows/bootstrap-branch.yml

@@ -0,0 +1,40 @@
+name: Bootstrap Feature Branch
+
+on:
+  issues:
+    types: [opened, closed, reopened, edited]
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  bootstrap:
+    runs-on: [self-hosted, dev-runner]
+    # Skip edited events unless title or body changed
+    if: >-
+      github.event.action != 'edited' ||
+      github.event.changes.title != null ||
+      github.event.changes.body != null
+    concurrency:
+      group: bootstrap-issue-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    steps:
+      - name: Bootstrap local worktree
+        # SECURITY: All issue data passed via env vars, NOT ${{ }} interpolation
+        # in run blocks. Direct interpolation allows script injection via issue
+        # titles containing shell metacharacters.
+        env:
+          GITHUB_TOKEN: ${{ secrets.DEV_RUNNER_PAT }}
+          ISSUE_ACTION: ${{ github.event.action }}
+          ISSUE_REPO: ${{ github.repository }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+        run: |
+          /usr/local/bin/bootstrap.sh \
+            --action "$ISSUE_ACTION" \
+            --repo "$ISSUE_REPO" \
+            --issue "$ISSUE_NUMBER" \
+            --title "$ISSUE_TITLE" \
+            --body "$ISSUE_BODY"

vaultspec_rag-0.2.0a0/.github/workflows/ci.yml

@@ -0,0 +1,156 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  NO_COLOR: "1"
+  FORCE_COLOR: "0"
+
+jobs:
+  workflow-lint:
+    name: Workflow Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Lint GitHub Actions workflows
+        uses: docker://rhysd/actionlint:1.7.11
+
+  lint-and-type:
+    name: Lint, Type, Config, Link, and Markdown Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install lychee
+        uses: taiki-e/install-action@v2
+        with:
+          tool: lychee
+
+      - name: Install taplo
+        uses: taiki-e/install-action@v2
+        with:
+          tool: taplo-cli
+
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install dependencies
+        run: just dev deps sync
+
+      - name: Ruff
+        run: just dev lint python
+
+      - name: Ty
+        run: just dev lint type
+
+      - name: Taplo
+        run: just dev lint toml
+
+      - name: Lychee
+        run: just dev lint links
+
+      - name: Markdown
+        run: just dev lint markdown
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install dependencies
+        run: just dev deps sync
+
+      - name: Run tests
+        run: just dev test python
+
+  vault-audit:
+    name: Vault Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install dependencies
+        run: just dev deps sync
+
+      - name: Verify vault structure and links
+        run: uv run vaultspec-core vault check all
+
+  dependency-audit:
+    name: Dependency Audit (pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install just
+        uses: taiki-e/install-action@just
+
+      - name: Install dependencies
+        run: just dev deps sync
+
+      - name: Python dependency vulnerability audit
+        run: just dev audit deps

vaultspec_rag-0.2.0a0/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

vaultspec_rag-0.2.0a0/.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to publish (e.g. vaultspec-rag-v0.1.4)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 5
+
+  smoke-test:
+    name: Smoke Test
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_check.py
+
+      - name: Smoke test (sdist)
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_check.py
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: smoke-test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Publish to PyPI
+        run: uv publish --check-url https://pypi.org/simple/ dist/*

vaultspec_rag-0.2.0a0/.github/workflows/release-please.yml

@@ -0,0 +1,50 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Update uv.lock on release branch
+        if: steps.release.outputs.pr && !steps.release.outputs.release_created
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
+
+      - name: Regenerate lockfile
+        if: steps.release.outputs.pr && !steps.release.outputs.release_created
+        uses: astral-sh/setup-uv@v7
+
+      - name: Push updated lockfile
+        if: steps.release.outputs.pr && !steps.release.outputs.release_created
+        run: |
+          uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock is already up to date"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add uv.lock
+            git commit -m "chore: update uv.lock for release"
+            git push
+          fi

vaultspec_rag-0.2.0a0/.gitignore

@@ -0,0 +1,167 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# /lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Whitelist .vaultspec/lib
+!/.vaultspec/lib/
+!/.vaultspec/lib/**
+.vaultspec/lib/**/__pycache__/
+.vaultspec/lib/**/*.pyc
+.vaultspec/providers.json
+
+# Auto-generated temp files
+.vaultspec/.tmp/
+tmp/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.pytest*/
+.ruff*/
+.uv*/
+cover/
+test-events.jsonl
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+# .python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+
+# LanceDB vector store
+.lance/
+**/.lance/
+vault_index.json
+
+
+# Temporary reference files
+tmp-ref/
+
+# >>> vaultspec-managed (do not edit this block) >>>
+.agents/
+.claude/
+.codex/
+.gemini/
+.mcp.json
+.vault/.obsidian/
+.vault/.trash/
+.vault/data/
+.vault/logs/
+.vaultspec/
+.vaultspec/_snapshots/
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+# <<< vaultspec-managed <<<

vaultspec_rag-0.2.0a0/.mdformat.toml

@@ -0,0 +1,3 @@
+wrap = "keep"
+number = false
+end_of_line = "lf"