[ { "path": ".clang-format", "content": "IndentWidth: 2\nTabWidth: 2\n\nLanguage: Cpp\nStandard: Cpp11\nBasedOnStyle: Google\n# indent\nAccessModifierOffset: -1\nContinuationIndentWidth: 4\n# align\nBreakBeforeTernaryOperators: true\nBreakBeforeBinaryOperators: false\nColumnLimit: 80\n# constructor\nBreakConstructorInitializersBeforeComma: false\nConstructorInitializerIndentWidth: 4\nConstructorInitializerAllOnOneLineOrOnePerLine: true\n# blocks\nAllowShortBlocksOnASingleLine: false\nAllowShortFunctionsOnASingleLine: false\nAllowShortIfStatementsOnASingleLine: false\nAllowShortLoopsOnASingleLine: false\nCpp11BracedListStyle: true\n# other\nAlwaysBreakTemplateDeclarations: true\nDerivePointerAlignment: false\nPointerAlignment: Left\n\n# clang 3.9+\nBreakStringLiterals: false\nSortIncludes: false\nReflowComments: true\n\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.yml", "content": "name: Bug Report\ndescription: Report a bug or unexpected behavior\ntitle: \"[Bug]: \"\nlabels: [\"bug\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for taking the time to report a bug! Please fill out the form below.\n\n - type: textarea\n id: description\n attributes:\n label: Bug Description\n description: A clear and concise description of what the bug is.\n placeholder: Describe the bug...\n validations:\n required: true\n\n - type: textarea\n id: reproduce\n attributes:\n label: Steps to Reproduce\n description: Steps to reproduce the behavior.\n placeholder: |\n 1. Initialize client with '...'\n 2. Call method '...'\n 3. See error\n validations:\n required: true\n\n - type: textarea\n id: expected\n attributes:\n label: Expected Behavior\n description: What did you expect to happen?\n validations:\n required: true\n\n - type: textarea\n id: actual\n attributes:\n label: Actual Behavior\n description: What actually happened?\n validations:\n required: true\n\n - type: textarea\n id: code\n attributes:\n label: Minimal Reproducible Example\n description: If applicable, provide a minimal code example that reproduces the issue.\n render: python\n\n - type: textarea\n id: logs\n attributes:\n label: Error Logs\n description: If applicable, paste any error messages or stack traces.\n render: shell\n\n - type: input\n id: version\n attributes:\n label: OpenViking Version\n description: What version of OpenViking are you using?\n placeholder: e.g., 0.1.0\n validations:\n required: true\n\n - type: input\n id: python-version\n attributes:\n label: Python Version\n description: What version of Python are you using?\n placeholder: e.g., 3.10.0\n validations:\n required: true\n\n - type: dropdown\n id: os\n attributes:\n label: Operating System\n options:\n - Linux\n - macOS\n - Windows\n - Other\n validations:\n required: true\n\n - type: dropdown\n id: backend\n attributes:\n label: Model Backend\n description: Which model backend are you using?\n options:\n - Volcengine (Doubao)\n - OpenAI\n - Other\n\n - type: textarea\n id: additional\n attributes:\n label: Additional Context\n description: Add any other context about the problem here.\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: Documentation\n url: https://www.openviking.ai/docs\n about: Check the documentation for guides and API reference\n - name: Lark Community\n url: https://applink.larkoffice.com/client/chat/chatter/add_by_link?link_token=dd9l9590-7e6e-49f5-bf41-18aef1ma06v3\n about: Join our Lark group for discussions and support\n - name: Questions & Discussions\n url: https://github.com/volcengine/OpenViking/discussions\n about: Ask questions and share ideas in GitHub Discussions\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yml", "content": "name: Feature Request\ndescription: Suggest a new feature or enhancement\ntitle: \"[Feature]: \"\nlabels: [\"enhancement\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Thanks for suggesting a feature! Please fill out the form below.\n\n - type: textarea\n id: problem\n attributes:\n label: Problem Statement\n description: Is your feature request related to a problem? Please describe.\n placeholder: A clear description of what the problem is. Ex. I'm always frustrated when...\n validations:\n required: true\n\n - type: textarea\n id: solution\n attributes:\n label: Proposed Solution\n description: Describe the solution you'd like.\n placeholder: A clear description of what you want to happen.\n validations:\n required: true\n\n - type: textarea\n id: alternatives\n attributes:\n label: Alternatives Considered\n description: Describe any alternative solutions or features you've considered.\n\n - type: dropdown\n id: area\n attributes:\n label: Feature Area\n description: Which area of OpenViking does this feature relate to?\n options:\n - Core (Client/Engine)\n - Filesystem Operations\n - Retrieval/Search\n - Session Management\n - Model Integration\n - Storage/VectorDB\n - CLI Tools\n - Documentation\n - Other\n validations:\n required: true\n\n - type: textarea\n id: use-case\n attributes:\n label: Use Case\n description: Describe the use case for this feature.\n placeholder: How would you use this feature in your project?\n validations:\n required: true\n\n - type: textarea\n id: code-example\n attributes:\n label: Example API (Optional)\n description: If applicable, provide an example of how the API might look.\n render: python\n\n - type: textarea\n id: additional\n attributes:\n label: Additional Context\n description: Add any other context, screenshots, or references about the feature request.\n\n - type: checkboxes\n id: contribution\n attributes:\n label: Contribution\n options:\n - label: I am willing to contribute to implementing this feature\n" }, { "path": ".github/ISSUE_TEMPLATE/question.yml", "content": "name: Question\ndescription: Ask a question about OpenViking usage\ntitle: \"[Question]: \"\nlabels: [\"question\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Have a question about OpenViking? We're here to help!\n\n - type: textarea\n id: question\n attributes:\n label: Your Question\n description: What would you like to know?\n placeholder: Describe your question clearly...\n validations:\n required: true\n\n - type: textarea\n id: context\n attributes:\n label: Context\n description: Provide any relevant context or background.\n placeholder: |\n - What are you trying to achieve?\n - What have you tried so far?\n\n - type: textarea\n id: code\n attributes:\n label: Code Example (Optional)\n description: If applicable, share relevant code.\n render: python\n\n - type: dropdown\n id: area\n attributes:\n label: Related Area\n options:\n - Installation / Setup\n - Configuration\n - API Usage\n - Retrieval / Search\n - Session Management\n - Performance\n - Other\n\n - type: checkboxes\n id: checked-docs\n attributes:\n label: Before Asking\n options:\n - label: I have checked the [documentation](https://www.openviking.ai/docs)\n required: true\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "## Description\n\n\n\n## Related Issue\n\n\n\n\n## Type of Change\n\n\n\n- [ ] Bug fix (non-breaking change that fixes an issue)\n- [ ] New feature (non-breaking change that adds functionality)\n- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)\n- [ ] Documentation update\n- [ ] Refactoring (no functional changes)\n- [ ] Performance improvement\n- [ ] Test update\n\n## Changes Made\n\n\n\n-\n-\n-\n\n## Testing\n\n\n\n- [ ] I have added tests that prove my fix is effective or that my feature works\n- [ ] New and existing unit tests pass locally with my changes\n- [ ] I have tested this on the following platforms:\n - [ ] Linux\n - [ ] macOS\n - [ ] Windows\n\n## Checklist\n\n- [ ] My code follows the project's coding style\n- [ ] I have performed a self-review of my code\n- [ ] I have commented my code, particularly in hard-to-understand areas\n- [ ] I have made corresponding changes to the documentation\n- [ ] My changes generate no new warnings\n- [ ] Any dependent changes have been merged and published\n\n## Screenshots (if applicable)\n\n\n\n## Additional Notes\n\n\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n # GitHub Actions 依赖更新\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n labels:\n - \"dependencies\"\n - \"github-actions\"\n\n # Python 依赖更新\n - package-ecosystem: \"pip\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n labels:\n - \"dependencies\"\n - \"python\"\n # 忽略主要版本更新，避免破坏性变更\n ignore:\n - dependency-name: \"*\"\n update-types: [\"version-update:semver-major\"]\n" }, { "path": ".github/workflows/_build.yml", "content": "name: 15. _Build Distribution\n\non:\n workflow_call:\n inputs:\n os_json:\n description: 'JSON string of runner labels to build on (ubuntu-24.04=x86_64, ubuntu-24.04-arm=aarch64, macos-14=arm64, macos-15-intel=x86_64, windows-latest=x86_64)'\n required: false\n type: string\n default: '[\"ubuntu-24.04\", \"ubuntu-24.04-arm\", \"macos-14\", \"macos-15-intel\", \"windows-latest\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n type: string\n default: '[\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"]'\n build_sdist:\n description: 'Whether to build source distribution'\n required: false\n type: boolean\n default: true\n build_wheels:\n description: 'Whether to build wheel distribution'\n required: false\n type: boolean\n default: true\n workflow_dispatch:\n inputs:\n build_sdist:\n description: 'Whether to build source distribution'\n required: false\n type: boolean\n default: true\n build_wheels:\n description: 'Whether to build wheel distribution'\n required: false\n type: boolean\n default: true\n os_json:\n description: 'JSON string of runner labels to build on (ubuntu-24.04=x86_64, ubuntu-24.04-arm=aarch64, macos-14=arm64, macos-15-intel=x86_64, windows-latest=x86_64)'\n required: false\n default: '[\"ubuntu-24.04\", \"ubuntu-24.04-arm\", \"macos-14\", \"macos-15-intel\", \"windows-latest\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n default: '[\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"]'\n\njobs:\n build-sdist:\n name: Build source distribution py3.12\n if: inputs.build_sdist\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@v6\n with:\n submodules: recursive\n fetch-depth: 0 # Required for setuptools_scm to detect version from git tags\n\n - name: Fetch all tags\n run: git fetch --force --tags\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.12'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Create venv\n run: uv venv\n\n - name: Install build dependencies\n run: uv pip install build setuptools_scm\n\n - name: Clean workspace (force ignore dirty)\n shell: bash\n run: |\n git reset --hard HEAD\n git clean -fd\n # For sdist, ensure local runtime binaries are not packaged even if present\n rm -rf openviking/bin openviking/lib third_party/agfs/bin || true\n rm -f openviking/storage/vectordb/*.so openviking/storage/vectordb/*.dylib openviking/storage/vectordb/*.dll openviking/storage/vectordb/*.exe || true\n rm -rf openviking/_version.py openviking.egg-info\n # Ignore uv.lock changes to avoid dirty state in setuptools_scm\n git update-index --assume-unchanged uv.lock || true\n\n - name: Debug Git and SCM\n shell: bash\n run: |\n echo \"=== Git Describe ===\"\n git describe --tags --long --dirty --always\n echo \"=== Setuptools SCM Version ===\"\n uv run --frozen python -m setuptools_scm\n echo \"=== Git Status (Ignored included) ===\"\n git status --ignored\n echo \"=== Check openviking/_version.py ===\"\n if [ -f openviking/_version.py ]; then cat openviking/_version.py; else echo \"Not found\"; fi\n\n - name: Build sdist\n run: uv run --frozen python -m build --sdist\n\n - name: Store the distribution packages\n uses: actions/upload-artifact@v7\n with:\n name: python-package-distributions-sdist\n path: dist/*.tar.gz\n\n - name: Display built sdist version\n continue-on-error: true\n run: |\n VERSION=$(ls dist/*.tar.gz | head -n 1 | xargs basename | sed -E 's/^[^-]+-(.+)\\.tar\\.gz$/\\1/')\n echo \"Build Version: $VERSION\"\n echo \"::notice::Build sdist Version: $VERSION\"\n\n build-linux:\n name: Build distribution on Linux ${{ matrix.arch }} (glibc 2.31) py${{ matrix.python-version }}\n # Run if Linux runners are requested (explicit labels or generic 'linux')\n if: >-\n inputs.build_wheels &&\n (\n contains(inputs.os_json, 'linux') ||\n contains(inputs.os_json, '\"ubuntu-24.04\"') ||\n contains(inputs.os_json, 'ubuntu-24.04-arm')\n )\n runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}\n container: ubuntu:20.04\n env:\n DEBIAN_FRONTEND: noninteractive\n TZ: Etc/UTC\n strategy:\n fail-fast: false\n matrix:\n python-version: ${{ fromJson(inputs.python_json) }}\n arch: ${{ contains(inputs.os_json, 'linux') && fromJson('[\"x86_64\",\"aarch64\"]') || (contains(inputs.os_json, '\"ubuntu-24.04\"') && contains(inputs.os_json, 'ubuntu-24.04-arm')) && fromJson('[\"x86_64\",\"aarch64\"]') || contains(inputs.os_json, 'ubuntu-24.04-arm') && fromJson('[\"aarch64\"]') || fromJson('[\"x86_64\"]') }}\n \n steps:\n - name: Install system dependencies (Linux)\n run: |\n # Replace archive.ubuntu.com with azure.archive.ubuntu.com for better stability in GH Actions\n sed -i 's/http:\\/\\/archive.ubuntu.com\\/ubuntu\\//http:\\/\\/azure.archive.ubuntu.com\\/ubuntu\\//g' /etc/apt/sources.list\n # Retry apt-get update\n for i in 1 2 3 4 5; do apt-get update && break || sleep 5; done\n apt-get install -y \\\n git ca-certificates cmake build-essential tzdata curl \\\n libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \\\n libffi-dev liblzma-dev libgdbm-dev libnss3-dev libncurses5-dev \\\n libncursesw5-dev tk-dev uuid-dev libexpat1-dev\n ln -fs /usr/share/zoneinfo/Etc/UTC /etc/localtime\n dpkg-reconfigure -f noninteractive tzdata\n\n - uses: actions/checkout@v6\n with:\n submodules: recursive\n fetch-depth: 0 # Required for setuptools_scm to detect version from git tags\n\n - name: Fetch all tags\n run: |\n git config --global --add safe.directory \"$GITHUB_WORKSPACE\"\n git fetch --force --tags\n\n - name: Build CPython (Dynamic Selection)\n run: |\n # Map short version to full version for our specific build environment\n PYTHON_VERSION=\"${{ matrix.python-version }}\"\n case \"$PYTHON_VERSION\" in\n \"3.9\") PYTHON_FULL=\"3.9.18\" ;;\n \"3.10\") PYTHON_FULL=\"3.10.13\" ;;\n \"3.11\") PYTHON_FULL=\"3.11.8\" ;;\n \"3.12\") PYTHON_FULL=\"3.12.2\" ;;\n \"3.13\") PYTHON_FULL=\"3.13.2\" ;;\n \"3.14\") PYTHON_FULL=\"3.14.3\" ;;\n *)\n echo \"Error: Unknown python version $PYTHON_VERSION\"\n exit 1\n ;;\n esac\n \n PYTHON_PREFIX=\"/opt/python/${PYTHON_FULL}\"\n PYTHON_BIN=\"${PYTHON_PREFIX}/bin/python${{ matrix.python-version }}\"\n if [ ! -x \"$PYTHON_BIN\" ]; then\n curl -fsSL -o /tmp/Python-${PYTHON_FULL}.tgz \\\n https://www.python.org/ftp/python/${PYTHON_FULL}/Python-${PYTHON_FULL}.tgz\n tar -xzf /tmp/Python-${PYTHON_FULL}.tgz -C /tmp\n cd /tmp/Python-${PYTHON_FULL}\n CFLAGS=\"-fPIC\" \\\n ./configure --prefix=\"${PYTHON_PREFIX}\" --with-ensurepip=install --enable-shared\n make -j\"$(nproc)\"\n make install\n fi\n echo \"PYTHON_BIN=${PYTHON_BIN}\" >> \"$GITHUB_ENV\"\n echo \"LD_LIBRARY_PATH=${PYTHON_PREFIX}/lib:${LD_LIBRARY_PATH}\" >> \"$GITHUB_ENV\"\n export LD_LIBRARY_PATH=\"${PYTHON_PREFIX}/lib:${LD_LIBRARY_PATH}\"\n \"$PYTHON_BIN\" -V\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.25.1'\n\n - name: Set up Rust\n uses: dtolnay/rust-toolchain@v1\n with:\n toolchain: stable\n targets: ${{ matrix.arch == 'aarch64' && 'aarch64-unknown-linux-gnu' || 'x86_64-unknown-linux-gnu' }}\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Create venv (Linux)\n run: uv venv --python \"$PYTHON_BIN\"\n\n - name: Seed pip (Linux)\n run: uv run python -m ensurepip --upgrade\n\n - name: Install dependencies\n run: uv sync --frozen\n\n - name: Install build dependencies\n run: uv pip install setuptools setuptools_scm pybind11 cmake wheel build\n\n - name: Build Rust CLI (Linux)\n run: cargo build --release --target ${{ matrix.arch == 'aarch64' && 'aarch64-unknown-linux-gnu' || 'x86_64-unknown-linux-gnu' }} -p ov_cli\n\n - name: Copy Rust CLI binary (Linux)\n run: |\n mkdir -p openviking/bin\n cp target/${{ matrix.arch == 'aarch64' && 'aarch64-unknown-linux-gnu' || 'x86_64-unknown-linux-gnu' }}/release/ov openviking/bin/\n chmod +x openviking/bin/ov\n - name: Clean workspace (force ignore dirty)\n shell: bash\n run: |\n git reset --hard HEAD\n git clean -fd\n rm -rf openviking/_version.py openviking.egg-info\n # Ignore uv.lock changes to avoid dirty state in setuptools_scm\n git update-index --assume-unchanged uv.lock || true\n\n - name: Debug Git and SCM\n shell: bash\n run: |\n echo \"=== Git Describe ===\"\n git describe --tags --long --dirty --always\n echo \"=== Setuptools SCM Version ===\"\n uv run --frozen python -m setuptools_scm\n echo \"=== Git Status (Ignored included) ===\"\n git status --ignored\n echo \"=== Check openviking/_version.py ===\"\n if [ -f openviking/_version.py ]; then cat openviking/_version.py; else echo \"Not found\"; fi\n\n - name: Build package (Wheel Only)\n run: uv run --frozen python -m build --wheel\n\n - name: Install patchelf (Linux)\n run: |\n PATCHELF_VERSION=0.18.0\n curl -fsSL -o /tmp/patchelf-${PATCHELF_VERSION}.tar.gz \\\n https://github.com/NixOS/patchelf/releases/download/${PATCHELF_VERSION}/patchelf-${PATCHELF_VERSION}.tar.gz\n tar -xzf /tmp/patchelf-${PATCHELF_VERSION}.tar.gz -C /tmp\n cd /tmp/patchelf-${PATCHELF_VERSION}\n ./configure\n make -j\"$(nproc)\"\n make install\n patchelf --version\n\n - name: Repair wheels (Linux)\n run: |\n uv pip install auditwheel\n # Repair wheels and output to a temporary directory\n uv run auditwheel repair dist/*.whl -w dist_fixed\n # Remove original non-compliant wheels\n rm dist/*.whl\n # Move repaired wheels back to dist\n mv dist_fixed/*.whl dist/\n rmdir dist_fixed\n\n - name: Store the distribution packages\n uses: actions/upload-artifact@v7\n with:\n name: python-package-distributions-linux-${{ matrix.arch }}-${{ matrix.python-version }}\n path: dist/\n\n - name: Display built wheel version\n continue-on-error: true\n run: |\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Build Version: $VERSION\"\n echo \"::notice::Build Wheel Version (Linux ${{ matrix.arch }} glibc 2.31 py${{ matrix.python-version }}): $VERSION\"\n\n build-other:\n name: Build non-Linux distributions\n # Run only when non-Linux runners are explicitly requested\n if: inputs.build_wheels && (contains(inputs.os_json, 'macos') || contains(inputs.os_json, 'windows'))\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n os: ${{ fromJson(inputs.os_json) }}\n python-version: ${{ fromJson(inputs.python_json) }}\n # Exclude ubuntu-24.04 from this matrix if it was passed in inputs\n exclude:\n - os: linux\n - os: ubuntu-24.04\n - os: ubuntu-24.04-arm\n\n steps:\n - uses: actions/checkout@v6\n with:\n submodules: recursive\n fetch-depth: 0 # Required for setuptools_scm to detect version from git tags\n\n - name: Fetch all tags\n run: git fetch --force --tags\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Configure macOS wheel architecture tag\n if: runner.os == 'macOS'\n shell: bash\n run: |\n if [[ \"${{ matrix.os }}\" == \"macos-14\" ]]; then\n TARGET_ARCH=\"arm64\"\n MACOS_VERSION=\"14.0\"\n elif [[ \"${{ matrix.os }}\" == \"macos-15-intel\" ]]; then\n TARGET_ARCH=\"x86_64\"\n MACOS_VERSION=\"15.0\"\n else\n echo \"Unsupported macOS runner for release wheels: ${{ matrix.os }}\"\n exit 1\n fi\n\n echo \"ARCHFLAGS=-arch ${TARGET_ARCH}\" >> \"$GITHUB_ENV\"\n echo \"CMAKE_OSX_ARCHITECTURES=${TARGET_ARCH}\" >> \"$GITHUB_ENV\"\n echo \"_PYTHON_HOST_PLATFORM=macosx-${MACOS_VERSION}-${TARGET_ARCH}\" >> \"$GITHUB_ENV\"\n echo \"Configured macOS wheel platform: macosx-${MACOS_VERSION}-${TARGET_ARCH}\"\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.25.1'\n\n - name: Set up Rust\n uses: dtolnay/rust-toolchain@v1\n with:\n toolchain: stable\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Install system dependencies (macOS)\n if: runner.os == 'macOS'\n run: brew install cmake\n\n - name: Install system dependencies (Windows)\n if: runner.os == 'Windows'\n run: |\n choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'\n choco install mingw\n\n - name: Install dependencies\n run: uv sync --frozen\n\n - name: Install build dependencies\n run: uv pip install setuptools setuptools_scm pybind11 cmake wheel build\n\n - name: Build Rust CLI (macOS/Windows)\n shell: bash\n run: |\n if [[ \"${{ matrix.os }}\" == \"windows-latest\" ]]; then\n cargo build --release --target x86_64-pc-windows-msvc -p ov_cli\n else\n cargo build --release -p ov_cli\n fi\n\n - name: Copy Rust CLI binary (macOS/Windows)\n shell: bash\n run: |\n mkdir -p openviking/bin\n if [[ \"${{ matrix.os }}\" == \"windows-latest\" ]]; then\n cp target/x86_64-pc-windows-msvc/release/ov.exe openviking/bin/\n else\n cp target/release/ov openviking/bin/\n chmod +x openviking/bin/ov\n fi\n - name: Clean workspace (force ignore dirty)\n shell: bash\n run: |\n git reset --hard HEAD\n git clean -fd\n rm -rf openviking/_version.py openviking.egg-info\n # Ignore uv.lock changes to avoid dirty state in setuptools_scm\n git update-index --assume-unchanged uv.lock || true\n\n - name: Debug Git and SCM\n shell: bash\n run: |\n echo \"=== Git Describe ===\"\n git describe --tags --long --dirty --always\n echo \"=== Setuptools SCM Version ===\"\n uv run --frozen python -m setuptools_scm\n echo \"=== Git Status (Ignored included) ===\"\n git status --ignored\n echo \"=== Check openviking/_version.py ===\"\n if [ -f openviking/_version.py ]; then cat openviking/_version.py; else echo \"Not found\"; fi\n\n - name: Build package (Wheel Only)\n run: uv run --frozen python -m build --wheel\n\n - name: Store the distribution packages\n uses: actions/upload-artifact@v7\n with:\n name: python-package-distributions-${{ matrix.os == 'macos-14' && 'macos-arm64' || matrix.os == 'macos-15-intel' && 'macos-x86_64' || matrix.os == 'windows-latest' && 'windows-x86_64' || matrix.os }}-${{ matrix.python-version }}\n path: dist/\n\n - name: Display built wheel version\n shell: bash\n continue-on-error: true\n run: |\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Build Version: $VERSION\"\n echo \"::notice::Build Wheel Version (${{ matrix.os == 'macos-14' && 'macOS arm64 (macos-14)' || matrix.os == 'macos-15-intel' && 'macOS x86_64 (macos-15-intel)' || matrix.os == 'windows-latest' && 'Windows x86_64 (windows-latest)' || matrix.os }} py${{ matrix.python-version }}): $VERSION\"\n\n verify-macos-14-wheel-on-macos-15:\n name: Verify macOS 14 arm64 wheel installs on macOS 15\n needs: [build-other]\n if: >-\n inputs.build_wheels &&\n contains(inputs.os_json, 'macos-14') &&\n contains(inputs.python_json, '3.12')\n runs-on: macos-15\n steps:\n - name: Set up Python 3.12\n uses: actions/setup-python@v6\n with:\n python-version: '3.12'\n\n - name: Download macOS arm64 wheel artifact\n uses: actions/download-artifact@v8\n with:\n name: python-package-distributions-macos-arm64-3.12\n path: dist/\n\n - name: Install built wheel\n shell: bash\n run: |\n python -m pip install --upgrade pip\n python -m pip install dist/*.whl\n\n - name: Smoke test native extension loading\n shell: bash\n run: |\n python - <<'PY'\n import importlib\n import importlib.util\n\n import openviking.storage.vectordb.engine as engine\n\n native_spec = importlib.util.find_spec(\"openviking.storage.vectordb.engine._native\")\n if native_spec is None or native_spec.origin is None:\n raise SystemExit(\"openviking storage native backend extension was not installed\")\n\n native_module = importlib.import_module(\"openviking.storage.vectordb.engine._native\")\n if engine.ENGINE_VARIANT != \"native\":\n raise SystemExit(\n f\"expected native engine variant on macOS arm64 wheel, got {engine.ENGINE_VARIANT}\"\n )\n\n print(f\"Loaded runtime engine variant {engine.ENGINE_VARIANT}\")\n print(f\"Loaded native extension from {native_spec.origin}\")\n print(f\"Imported backend module {native_module.__name__}\")\n PY\n" }, { "path": ".github/workflows/_codeql.yml", "content": "name: 14. _CodeQL Scan\n\non:\n workflow_call:\n workflow_dispatch:\n\njobs:\n analyze:\n name: Analyze\n runs-on: ubuntu-24.04\n permissions:\n actions: read\n contents: read\n security-events: write\n\n strategy:\n fail-fast: false\n matrix:\n language: [ 'python', 'cpp' ]\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n with:\n submodules: recursive\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.11'\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: 'stable'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Install system dependencies\n run: |\n sudo apt-get update\n sudo apt-get install -y cmake build-essential\n\n - name: Install dependencies\n run: |\n uv sync --frozen\n uv pip install setuptools pybind11 cmake wheel\n\n - name: Initialize CodeQL\n uses: github/codeql-action/init@v4\n with:\n languages: ${{ matrix.language }}\n queries: security-and-quality\n\n - name: Build extensions\n if: matrix.language == 'cpp'\n run: uv run python setup.py build_ext --inplace\n\n - name: Perform CodeQL Analysis\n uses: github/codeql-action/analyze@v4\n with:\n category: \"/language:${{ matrix.language }}\"\n" }, { "path": ".github/workflows/_lint.yml", "content": "name: 11. _Lint Checks\n\non:\n workflow_call:\n workflow_dispatch:\n\njobs:\n lint:\n runs-on: ubuntu-24.04\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0 # Required to calculate the git diff\n\n\n\n - name: Set up Python\n uses: actions/setup-python@v6\n with:\n python-version: '3.11'\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: 'stable'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Install dependencies\n run: uv sync --frozen --extra dev\n\n # --- NEW STEP: Get the list of changed files ---\n - name: Get changed files\n id: files\n run: |\n # Compare the PR head to the base branch\n echo \"changed_files=$(git diff --name-only --diff-filter=d origin/${{ github.base_ref }} HEAD | grep '\\.py$' | xargs)\" >> $GITHUB_OUTPUT\n\n # --- UPDATED STEPS: Use the file list ---\n - name: List files\n run: echo \"The changed files are ${{ steps.files.outputs.changed_files }}\"\n\n - name: Format with ruff (Changed files only)\n if: steps.files.outputs.changed_files != ''\n run: uv run ruff format --check ${{ steps.files.outputs.changed_files }} \n\n - name: Lint with ruff (Changed files only)\n if: steps.files.outputs.changed_files != ''\n run: uv run ruff check ${{ steps.files.outputs.changed_files }}\n\n - name: Type check with mypy (Changed files only)\n if: steps.files.outputs.changed_files != ''\n # Note: Running mypy on specific files may miss cross-file type errors\n run: uv run mypy ${{ steps.files.outputs.changed_files }}\n continue-on-error: true\n" }, { "path": ".github/workflows/_publish.yml", "content": "name: 16. _Publish Distribution\n\non:\n workflow_call:\n inputs:\n target:\n description: 'Publish Target'\n required: false\n type: string\n default: 'pypi' # Callers (like release.yml) typically want PyPI\n build_run_id:\n description: 'Build Workflow Run ID (Optional, defaults to current run)'\n required: false\n type: string\n default: ''\n workflow_dispatch:\n inputs:\n target:\n description: 'Select where to publish'\n required: true\n type: choice\n default: 'testpypi'\n options:\n - testpypi\n - pypi\n - both\n build_run_id:\n description: 'Build Workflow Run ID (Required for manual dispatch, find it in the Build run URL)'\n required: true\n type: string\n\njobs:\n permission-check:\n name: Check write permission\n runs-on: ubuntu-24.04\n permissions:\n contents: read\n outputs:\n allowed: ${{ steps.check.outputs.allowed }}\n steps:\n - name: Verify actor permission\n id: check\n uses: actions/github-script@v8\n with:\n script: |\n // Only check permission for manual dispatch\n if (context.eventName !== 'workflow_dispatch') {\n core.setOutput('allowed', 'true');\n return;\n }\n const { owner, repo } = context.repo;\n const actor = context.actor;\n const { data } = await github.rest.repos.getCollaboratorPermissionLevel({\n owner,\n repo,\n username: actor,\n });\n const perm = data.permission;\n core.info(`Actor ${actor} permission: ${perm}`);\n const allowed = ['admin', 'maintain', 'write'].includes(perm);\n core.setOutput('allowed', allowed ? 'true' : 'false');\n if (!allowed) {\n core.setFailed(`User ${actor} does not have write permission`);\n }\n\n publish-testpypi:\n name: Publish to TestPyPI\n needs: [permission-check]\n if: >-\n needs.permission-check.outputs.allowed == 'true' &&\n (inputs.target == 'testpypi' || inputs.target == 'both')\n runs-on: ubuntu-24.04\n environment:\n name: testpypi\n url: https://test.pypi.org/p/openviking\n permissions:\n id-token: write\n actions: read # Required for downloading artifacts from other runs\n\n steps:\n - name: Download all the dists (Same Run)\n if: inputs.build_run_id == ''\n uses: actions/download-artifact@v8\n with:\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Download all the dists (Cross Run)\n if: inputs.build_run_id != ''\n uses: actions/download-artifact@v8\n with:\n run-id: ${{ inputs.build_run_id }}\n github-token: ${{ secrets.GITHUB_TOKEN }}\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Publish distribution to TestPyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n repository-url: https://test.pypi.org/legacy/\n skip-existing: true\n verbose: true\n\n - name: Display published version\n run: |\n # Get version from the first wheel file found\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Published to TestPyPI (or already existed) with version: $VERSION\"\n echo \"::notice::Published to TestPyPI (or already existed) with version: $VERSION\"\n\n publish-pypi:\n name: Publish to PyPI\n needs: [permission-check]\n if: >-\n needs.permission-check.outputs.allowed == 'true' &&\n (inputs.target == 'pypi' || inputs.target == 'both')\n runs-on: ubuntu-24.04\n environment:\n name: pypi\n url: https://pypi.org/p/openviking\n permissions:\n id-token: write\n actions: read # Required for downloading artifacts from other runs\n\n steps:\n - name: Download all the dists (Same Run)\n if: inputs.build_run_id == ''\n uses: actions/download-artifact@v8\n with:\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Download all the dists (Cross Run)\n if: inputs.build_run_id != ''\n uses: actions/download-artifact@v8\n with:\n run-id: ${{ inputs.build_run_id }}\n github-token: ${{ secrets.GITHUB_TOKEN }}\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Publish distribution to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n skip-existing: true\n verbose: true\n\n - name: Display published version\n run: |\n # Get version from the first wheel file found\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Published to PyPI (or already existed) with version: $VERSION\"\n echo \"::notice::Published to PyPI (or already existed) with version: $VERSION\"\n" }, { "path": ".github/workflows/_test_full.yml", "content": "name: 13. _Test Suite (Full)\n\non:\n workflow_call:\n inputs:\n os_json:\n description: 'JSON string of OS to run on'\n required: false\n type: string\n default: '[\"ubuntu-24.04\", \"macos-14\", \"windows-latest\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n type: string\n default: '[\"3.10\", \"3.11\", \"3.12\", \"3.13\"]'\n workflow_dispatch:\n inputs:\n os_json:\n description: 'JSON string of OS to run on'\n required: false\n default: '[\"ubuntu-24.04\", \"macos-14\", \"windows-latest\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n default: '[\"3.10\", \"3.11\", \"3.12\", \"3.13\"]'\n\njobs:\n test:\n name: Full Test (${{ matrix.os }}, ${{ matrix.python-version }})\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n os: ${{ fromJson(inputs.os_json || '[\"ubuntu-24.04\", \"macos-14\", \"windows-latest\"]') }}\n python-version: ${{ fromJson(inputs.python_json || '[\"3.10\", \"3.11\", \"3.12\", \"3.13\"]') }}\n\n steps:\n - uses: actions/checkout@v6\n with:\n submodules: recursive\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v6\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.25.1'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Install system dependencies (Ubuntu)\n if: runner.os == 'Linux'\n run: |\n sudo apt-get update\n sudo apt-get install -y cmake build-essential\n\n - name: Install system dependencies (macOS)\n if: runner.os == 'macOS'\n run: brew install cmake\n\n - name: Install system dependencies (Windows)\n if: runner.os == 'Windows'\n run: |\n choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'\n choco install mingw\n\n - name: Add MinGW to PATH (Windows)\n if: runner.os == 'Windows'\n run: echo \"C:\\mingw64\\bin\" >> $env:GITHUB_PATH\n\n - name: Install Python dependencies\n run: uv sync --frozen --extra test\n\n - name: Install build dependencies\n run: uv pip install setuptools pybind11 cmake wheel\n\n - name: Build C++ extensions\n run: uv run python setup.py build_ext --inplace\n\n # TODO: Once unit tests are fixed, switch this back to running the full test suite\n # run: uv run pytest tests/ -v --cov=openviking --cov-report=term\n - name: Run Lite Integration Test (Temporary Replacement)\n shell: bash\n run: |\n export PYTHONPATH=$PYTHONPATH:$(pwd)\n uv run python tests/integration/test_quick_start_lite.py\n" }, { "path": ".github/workflows/_test_lite.yml", "content": "name: 12. _Test Suite (Lite)\n\non:\n workflow_call:\n inputs:\n os_json:\n description: 'JSON string of OS to run on'\n required: false\n type: string\n default: '[\"ubuntu-24.04\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n type: string\n default: '[\"3.10\"]'\n workflow_dispatch:\n inputs:\n os_json:\n description: 'JSON string of OS to run on'\n required: false\n default: '[\"ubuntu-24.04\"]'\n python_json:\n description: 'JSON string of Python versions'\n required: false\n default: '[\"3.10\"]'\n\njobs:\n test-lite:\n name: Lite Test (${{ matrix.os }}, ${{ matrix.python-version }})\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n os: ${{ fromJson(inputs.os_json) }}\n python-version: ${{ fromJson(inputs.python_json) }}\n\n steps:\n - uses: actions/checkout@v6\n with:\n submodules: recursive\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v6\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Set up Go\n uses: actions/setup-go@v6\n with:\n go-version: '1.25.1'\n\n - name: Install uv\n uses: astral-sh/setup-uv@v7\n with:\n enable-cache: true\n\n - name: Install system dependencies (Ubuntu)\n if: runner.os == 'Linux'\n run: |\n sudo apt-get update\n sudo apt-get install -y cmake build-essential\n\n - name: Install system dependencies (macOS)\n if: runner.os == 'macOS'\n run: brew install cmake\n\n - name: Install system dependencies (Windows)\n if: runner.os == 'Windows'\n run: |\n choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'\n choco install mingw\n\n - name: Add MinGW to PATH (Windows)\n if: runner.os == 'Windows'\n run: echo \"C:\\mingw64\\bin\" >> $env:GITHUB_PATH\n\n - name: Install Python dependencies\n run: uv sync --frozen --extra test\n\n - name: Install build dependencies\n run: uv pip install setuptools pybind11 cmake wheel\n\n - name: Build C++ extensions\n run: uv run python setup.py build_ext --inplace\n\n - name: Run Lite Integration Test (Quick Start)\n shell: bash\n run: |\n export PYTHONPATH=$PYTHONPATH:$(pwd)\n # Using bash shell ensures this works across platforms (including Windows via Git Bash)\n uv run python tests/integration/test_quick_start_lite.py\n" }, { "path": ".github/workflows/build-docker-image.yml", "content": "name: Build and Push Docker Image\n\non:\n workflow_dispatch:\n inputs:\n version:\n description: \"application version for OpenViking\"\n required: true\n type: string\n push:\n tags: [ \"v*.*.*\" ]\n\nenv:\n REGISTRY: ghcr.io\n IMAGE_NAME: ${{ github.repository }}\n\njobs:\n build-and-push-image:\n runs-on: ubuntu-24.04\n permissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n with:\n submodules: recursive\n\n - name: Log in to the Container registry\n uses: docker/login-action@v4\n with:\n registry: ${{ env.REGISTRY }}\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Extract metadata (tags, labels) for Docker\n id: meta\n uses: docker/metadata-action@v6\n with:\n images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v4\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v4\n\n - name: Build and push Docker image\n id: push\n uses: docker/build-push-action@v7\n with:\n context: .\n platforms: linux/amd64,linux/arm64\n push: ${{ github.ref_type == 'tag' || github.event_name == 'workflow_dispatch' }}\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n # fallback to 0.0.0 if no version is provided\n OPENVIKING_VERSION=${{ (github.event_name == 'workflow_dispatch' && github.event.inputs.version) || (github.ref_type == 'tag' && github.ref_name) || '0.0.0' }}\n" }, { "path": ".github/workflows/ci.yml", "content": "name: 02. Main Branch Checks\n\non:\n workflow_dispatch:\n push:\n branches: [ main ]\n paths-ignore:\n - 'docs/**'\n - '**.md'\n - 'LICENSE'\n - 'CONTRIBUTING.md'\n - '**.png'\n - '**.jpg'\n - '**.jpeg'\n - '**.gif'\n - '**.svg'\n - '.gitignore'\n - '.editorconfig'\n\npermissions:\n actions: read\n contents: read\n security-events: write\n\njobs:\n test-full:\n uses: ./.github/workflows/_test_full.yml\n\n security-scan:\n uses: ./.github/workflows/_codeql.yml\n" }, { "path": ".github/workflows/pr-review.yml", "content": "name: PR Review (Qodo)\n\non:\n pull_request_target:\n types: [opened, synchronize, reopened, ready_for_review]\n issue_comment:\n\njobs:\n pr_review:\n if: ${{ github.event.sender.type != 'Bot' }}\n runs-on: ubuntu-24.04\n permissions:\n issues: write\n pull-requests: write\n contents: write\n steps:\n # Checkout required so PR-Agent reads .pr_agent.toml from repo root.\n # All review rules, custom labels, ignore patterns, and tool configs\n # live in .pr_agent.toml — no inline extra_instructions needed here.\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: PR Agent\n uses: qodo-ai/pr-agent@main\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n OPENAI_KEY: ${{ secrets.DOUBAO_API_KEY }}\n OPENAI.API_BASE: \"https://ark.cn-beijing.volces.com/api/coding/v3\"\n config.model: \"ark-code-latest\"\n github_action_config.auto_review: \"true\"\n github_action_config.auto_describe: \"true\"\n github_action_config.auto_improve: \"true\"\n" }, { "path": ".github/workflows/pr.yml", "content": "name: 01. Pull Request Checks\n\non:\n workflow_dispatch:\n pull_request:\n branches: [ main, develop ]\n paths-ignore:\n - 'docs/**'\n - '**.md'\n - 'LICENSE'\n - 'CONTRIBUTING.md'\n - '**.png'\n - '**.jpg'\n - '**.jpeg'\n - '**.gif'\n - '**.svg'\n - '.gitignore'\n - '.editorconfig'\n\njobs:\n lint:\n uses: ./.github/workflows/_lint.yml\n\n test-lite:\n uses: ./.github/workflows/_test_lite.yml\n with:\n os_json: '[\"ubuntu-24.04\"]'\n python_json: '[\"3.10\"]'\n\n check-deps:\n runs-on: ubuntu-24.04\n outputs:\n deps_changed: ${{ steps.check.outputs.deps_changed }}\n steps:\n - uses: actions/checkout@v6\n with:\n fetch-depth: 0\n\n - name: Check for dependency changes\n id: check\n run: |\n git fetch origin ${{ github.base_ref }}\n \n # Define grep pattern for dependency files\n PATTERN=\"pyproject\\.toml|setup\\.py|uv\\.lock|src/CMakeLists\\.txt|third_party/|\\.github/workflows/_build\\.yml\"\n \n # Check for changes\n CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }} HEAD | grep -E \"$PATTERN\" || true)\n \n if [ -n \"$CHANGED_FILES\" ]; then\n echo \"Dependency changes detected:\"\n echo \"$CHANGED_FILES\"\n echo \"deps_changed=true\" >> $GITHUB_OUTPUT\n else\n echo \"No dependency changes detected.\"\n echo \"deps_changed=false\" >> $GITHUB_OUTPUT\n fi\n\n build:\n needs: check-deps\n if: ${{ needs.check-deps.outputs.deps_changed == 'true' }}\n uses: ./.github/workflows/_build.yml\n" }, { "path": ".github/workflows/release-vikingbot-first.yml", "content": "name: First Release to PyPI\n\non:\n workflow_dispatch: # 手动触发\n\njobs:\n release:\n runs-on: ubuntu-24.04\n defaults:\n run:\n working-directory: bot\n steps:\n - uses: actions/checkout@v6\n\n - uses: actions/setup-python@v6\n with:\n python-version: '3.11'\n\n - name: Install build dependencies\n run: pip install build\n\n - name: Build package\n run: python -m build\n\n - name: Publish to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n password: ${{ secrets.VIKINGBOT_PYPI_API_TOKEN }}\n packages-dir: bot/dist/\n" }, { "path": ".github/workflows/release.yml", "content": "name: 03. Release\n\non:\n release:\n types: [published]\n workflow_dispatch:\n inputs:\n target:\n description: 'Select where to publish'\n required: true\n type: choice\n default: 'testpypi'\n options:\n - none\n - testpypi\n - pypi\n - both\n build_sdist:\n description: 'Whether to build source distribution'\n required: false\n type: boolean\n default: true\n build_wheels:\n description: 'Whether to build wheel distribution'\n required: false\n type: boolean\n default: true\n os_json:\n description: 'JSON string of runner labels to build on (Manual only; ubuntu-24.04=x86_64, ubuntu-24.04-arm=aarch64, macos-14=arm64, macos-15-intel=x86_64, windows-latest=x86_64)'\n required: false\n type: string\n default: '[\"ubuntu-24.04\", \"ubuntu-24.04-arm\", \"macos-14\", \"macos-15-intel\", \"windows-latest\"]'\n python_json:\n description: 'JSON string of Python versions (Manual only)'\n required: false\n type: string\n default: '[\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"]'\n\npermissions:\n contents: write\n id-token: write\n actions: read\n\njobs:\n build:\n # Skip this workflow for CLI releases (tags starting with cli-)\n if: \"!startsWith(github.event.release.tag_name, 'cli-')\"\n uses: ./.github/workflows/_build.yml\n with:\n os_json: ${{ inputs.os_json || '[\"ubuntu-24.04\", \"ubuntu-24.04-arm\", \"macos-14\", \"macos-15-intel\", \"windows-latest\"]' }}\n python_json: ${{ inputs.python_json || '[\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"]' }}\n build_sdist: ${{ github.event_name == 'release' || inputs.build_sdist != false }}\n build_wheels: ${{ github.event_name == 'release' || inputs.build_wheels != false }}\n\n permission-check:\n name: Check write permission\n needs: [build]\n runs-on: ubuntu-24.04\n permissions:\n contents: read\n outputs:\n allowed: ${{ steps.check.outputs.allowed }}\n steps:\n - name: Verify actor permission\n id: check\n uses: actions/github-script@v8\n with:\n script: |\n // Only check permission for manual dispatch\n if (context.eventName !== 'workflow_dispatch') {\n core.setOutput('allowed', 'true');\n return;\n }\n const { owner, repo } = context.repo;\n const actor = context.actor;\n const { data } = await github.rest.repos.getCollaboratorPermissionLevel({\n owner,\n repo,\n username: actor,\n });\n const perm = data.permission;\n core.info(`Actor ${actor} permission: ${perm}`);\n const allowed = ['admin', 'maintain', 'write'].includes(perm);\n core.setOutput('allowed', allowed ? 'true' : 'false');\n if (!allowed) {\n core.setFailed(`User ${actor} does not have write permission`);\n }\n\n publish-testpypi:\n name: Publish to TestPyPI\n needs: [build, permission-check]\n if: >-\n needs.permission-check.outputs.allowed == 'true' &&\n (inputs.target == 'testpypi' || inputs.target == 'both')\n runs-on: ubuntu-24.04\n environment:\n name: testpypi\n url: https://test.pypi.org/p/openviking\n permissions:\n id-token: write\n actions: read\n steps:\n - name: Download all the dists (Same Run)\n uses: actions/download-artifact@v8\n with:\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Publish distribution to TestPyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n repository-url: https://test.pypi.org/legacy/\n skip-existing: true\n verbose: true\n\n - name: Display published version\n run: |\n # Get version from the first wheel file found\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Published to TestPyPI (or already existed) with version: $VERSION\"\n echo \"::notice::Published to TestPyPI (or already existed) with version: $VERSION\"\n\n publish-pypi:\n name: Publish to PyPI\n needs: [build, permission-check]\n if: >-\n needs.permission-check.outputs.allowed == 'true' &&\n (github.event_name == 'release' || inputs.target == 'pypi' || inputs.target == 'both')\n runs-on: ubuntu-24.04\n environment:\n name: pypi\n url: https://pypi.org/p/openviking\n permissions:\n id-token: write\n actions: read\n steps:\n - name: Download all the dists (Same Run)\n uses: actions/download-artifact@v8\n with:\n pattern: python-package-distributions-*\n path: dist/\n merge-multiple: true\n\n - name: Publish distribution to PyPI\n uses: pypa/gh-action-pypi-publish@release/v1\n with:\n skip-existing: true\n verbose: true\n\n - name: Display published version\n run: |\n # Get version from the first wheel file found\n VERSION=$(ls dist/*.whl | head -n 1 | xargs basename | cut -d- -f2)\n echo \"Published to PyPI (or already existed) with version: $VERSION\"\n echo \"::notice::Published to PyPI (or already existed) with version: $VERSION\"\n\n docker:\n name: Build and Push Docker Image\n needs: [build, permission-check]\n if: >-\n needs.permission-check.outputs.allowed == 'true' &&\n github.event_name == 'release'\n runs-on: ubuntu-24.04\n permissions:\n contents: read\n packages: write\n attestations: write\n id-token: write\n steps:\n - name: Checkout repository\n uses: actions/checkout@v6\n with:\n submodules: recursive\n\n - name: Log in to the Container registry\n uses: docker/login-action@v4\n with:\n registry: ghcr.io\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Extract metadata (tags, labels) for Docker\n id: meta\n uses: docker/metadata-action@v6\n with:\n images: ghcr.io/${{ github.repository }}\n\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v4\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v4\n\n - name: Build and push Docker image\n uses: docker/build-push-action@v7\n with:\n context: .\n platforms: linux/amd64,linux/arm64\n push: true\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n build-args: |\n OPENVIKING_VERSION=${{ github.event.release.tag_name }}\n" }, { "path": ".github/workflows/rust-cli.yml", "content": "name: Rust CLI Build\n\non:\n workflow_call:\n push:\n branches: [ main, feat/rust-cli ]\n paths:\n - 'crates/**'\n - 'Cargo.toml'\n - '.github/workflows/rust-cli.yml'\n tags:\n - 'cli@*' # Trigger release on tags starting with cli@\n pull_request:\n branches: [ main ]\n paths:\n - 'crates/**'\n - 'Cargo.toml'\n - '.github/workflows/rust-cli.yml'\n\njobs:\n build:\n name: Build ${{ matrix.target }}\n runs-on: ${{ matrix.os }}\n strategy:\n fail-fast: false\n matrix:\n include:\n - os: ubuntu-24.04\n target: x86_64-unknown-linux-gnu\n artifact_name: ov-linux-x86_64\n - os: ubuntu-24.04\n target: aarch64-unknown-linux-gnu\n artifact_name: ov-linux-aarch64\n - os: macos-15-intel\n target: x86_64-apple-darwin\n artifact_name: ov-macos-x86_64\n - os: macos-14\n target: aarch64-apple-darwin\n artifact_name: ov-macos-aarch64\n - os: windows-latest\n target: x86_64-pc-windows-msvc\n artifact_name: ov-windows-x86_64.exe\n\n steps:\n - uses: actions/checkout@v6\n\n - name: Install Rust\n uses: dtolnay/rust-toolchain@v1\n with:\n toolchain: stable\n targets: ${{ matrix.target }}\n\n - name: Install system dependencies (Linux)\n if: runner.os == 'Linux'\n run: |\n sudo apt-get update\n sudo apt-get install -y pkg-config libssl-dev\n\n - name: Install cross-compilation tools (Linux ARM64)\n if: matrix.target == 'aarch64-unknown-linux-gnu'\n run: |\n sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu\n echo \"CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc\" >> $GITHUB_ENV\n echo \"CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc\" >> $GITHUB_ENV\n echo \"CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++\" >> $GITHUB_ENV\n\n - name: Cache Cargo registry and index\n uses: actions/cache@v5\n with:\n path: |\n ~/.cargo/registry/index\n ~/.cargo/registry/cache\n ~/.cargo/git/db\n key: ${{ runner.os }}-cargo-${{ matrix.target }}-${{ hashFiles('**/Cargo.lock') }}\n restore-keys: |\n ${{ runner.os }}-cargo-${{ matrix.target }}-\n ${{ runner.os }}-cargo-\n\n - name: Cache build artifacts\n uses: actions/cache@v5\n with:\n path: target\n key: ${{ runner.os }}-target-${{ matrix.target }}-${{ hashFiles('**/Cargo.lock') }}-${{ hashFiles('crates/**/*.rs') }}\n restore-keys: |\n ${{ runner.os }}-target-${{ matrix.target }}-${{ hashFiles('**/Cargo.lock') }}-\n ${{ runner.os }}-target-${{ matrix.target }}-\n\n - name: Build CLI\n run: cargo build --release --target ${{ matrix.target }} -p ov_cli\n \n - name: Create compressed artifacts\n shell: bash\n run: |\n mkdir -p artifacts\n cd target/${{ matrix.target }}/release\n\n if [[ \"${{ matrix.os }}\" == \"windows-latest\" ]]; then\n # Windows: create zip\n 7z a ../../../artifacts/${{ matrix.artifact_name }}.zip ov.exe\n cd ../../../artifacts\n # Use PowerShell to get hash in correct format\n powershell -Command \"(Get-FileHash -Algorithm SHA256 '${{ matrix.artifact_name }}.zip').Hash.ToLower() + ' ${{ matrix.artifact_name }}.zip'\" > ${{ matrix.artifact_name }}.zip.sha256\n else\n # Unix: create tar.gz\n tar czf ../../../artifacts/${{ matrix.artifact_name }}.tar.gz ov\n cd ../../../artifacts\n # shasum format: \n shasum -a 256 ${{ matrix.artifact_name }}.tar.gz > ${{ matrix.artifact_name }}.tar.gz.sha256\n fi\n\n - name: Verify checksum format\n shell: bash\n run: |\n echo \"Contents of checksum file:\"\n cat artifacts/*.sha256\n echo \"\"\n echo \"Verifying checksum locally:\"\n cd artifacts\n if [[ \"${{ matrix.os }}\" == \"windows-latest\" ]]; then\n sha256sum -c *.sha256 || shasum -a 256 -c *.sha256 || echo \"Checksum verification skipped on Windows\"\n else\n shasum -a 256 -c *.sha256\n fi\n\n - name: Upload artifacts\n uses: actions/upload-artifact@v7\n with:\n name: ${{ matrix.artifact_name }}\n path: artifacts/*\n\n release:\n name: Create GitHub Release\n runs-on: ubuntu-24.04\n needs: build\n if: startsWith(github.ref, 'refs/tags/cli@')\n permissions:\n contents: write\n steps:\n - name: Checkout code\n uses: actions/checkout@v6\n\n - name: Get version from tag\n id: get_version\n run: echo \"version=${GITHUB_REF#refs/tags/cli@}\" >> $GITHUB_OUTPUT\n\n - name: Download all artifacts\n uses: actions/download-artifact@v8\n with:\n path: artifacts\n\n - name: Display artifact structure\n run: ls -R artifacts/\n\n - name: Create GitHub Release\n uses: softprops/action-gh-release@v2\n with:\n name: CLI v${{ steps.get_version.outputs.version }}\n body: |\n # OpenViking CLI v${{ steps.get_version.outputs.version }}\n\n ## Installation\n\n ### Quick Install (macOS/Linux)\n ```bash\n curl -fsSL https://raw.githubusercontent.com/${{ github.repository }}/refs/tags/cli@${{ steps.get_version.outputs.version }}/crates/ov_cli/install.sh | bash\n ```\n\n ### Manual Installation\n Download the appropriate binary for your platform below, extract it, and add it to your PATH.\n\n The CLI command is simply `ov`:\n ```bash\n # After extraction\n chmod +x ov # Unix only\n mv ov /usr/local/bin/ # or any directory in your PATH\n\n # Verify installation\n ov --version\n ```\n\n ### Checksums\n SHA256 checksums are provided for each binary for verification.\n\n ## Changes\n See the [commit history](https://github.com/${{ github.repository }}/commits/cli@${{ steps.get_version.outputs.version }}) for details.\n files: |\n artifacts/**/*.tar.gz\n artifacts/**/*.zip\n artifacts/**/*.sha256\n draft: false\n prerelease: ${{ contains(steps.get_version.outputs.version, 'alpha') || contains(steps.get_version.outputs.version, 'beta') || contains(steps.get_version.outputs.version, 'rc') }}\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/schedule.yml", "content": "name: 04. Weekly Security Scan\n\non:\n schedule:\n - cron: '0 0 * * 0' # Run at 00:00 on Sunday\n\npermissions:\n actions: read\n contents: read\n security-events: write\n\njobs:\n security-scan:\n uses: ./.github/workflows/_codeql.yml\n" }, { "path": ".gitignore", "content": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\nopenviking.egg-info/\ndata/\n\n# Rust\ntarget/\n**/*.rs.bk\n*.pdb\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\n.ruff_cache/\ncover/\ntest_data/\ntest_data_sync/\n\n# Virtual environments\n.env\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n*~\n\n# macOS\n.DS_Store\n.AppleDouble\n.LSOverride\n\n# Thumbnails\n._*\n\n# Files that might appear in the root of a volume\n.DocumentRevisions-V100\n.fseventsd\n.Spotlight-V100\n.TemporaryItems\n.Trashes\n.VolumeIcon.icns\n.com.apple.timemachine.donotpresent\n\n# Directories potentially created on remote AFP share\n.AppleDB\n.AppleDesktop\nNetwork Trash Folder\nTemporary Items\n.apdisk\n\n# OpenViking specific\n/data/*\n/demo_data/*\n/benchmark_data/*\n.claude\n.openviking\n*.code-workspace\n\n# AI Coding\nCLAUDE.md\n*.so\nAGENTS.md\n\n# Git worktrees\n.worktrees/\n\n# Logs\n*.log\nlogs/\n\n# Temporary files\n*.tmp\n*.temp\n.tmp/\nov.conf\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# pyenv\n.python-version\n\n# celery beat schedule file\ncelerybeat-schedule\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env.local\n.env.development.local\n.env.test.local\n.env.production.local\n\n# mkdocs documentation\n/site\ndocs/superpowers/\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\nopenviking/bin/\nthird_party/agfs/bin/\ntest_scripts/\nexamples/data/\nopenviking/_version.py\nspecs/\n.trae/\n" }, { "path": ".pr_agent.toml", "content": "# =============================================================================\n# Qodo PR-Agent Configuration for OpenViking\n# =============================================================================\n# OpenViking: polyglot (Python/TypeScript/Rust) context database for AI agents.\n# By ByteDance/Volcengine — Apache-2.0 licensed.\n#\n# Rules derived from: real bug history (PRs #505, #728, #749, #740/#745),\n# codebase conventions, CI pipeline (ruff, mypy, pytest), and Qodo best\n# practices (Rule System blog, 2.2 PR History, raw configuration.toml).\n#\n# Principle: edit only what you need (Qodo Tip #1). Every override here has\n# a documented reason tied to OpenViking's specific patterns.\n# =============================================================================\n\n# ---------------------------------------------------------------------------\n# Global Config\n# ---------------------------------------------------------------------------\n[config]\noutput_relevant_configurations = false\n# Use high reasoning for this complex polyglot codebase with subtle async/\n# concurrency bugs. Worth the extra latency for quality.\nreasoning_effort = \"high\"\n# More context around hunks helps the model understand memory pipeline flows\n# that often span multiple functions.\npatch_extra_lines_before = 8\npatch_extra_lines_after = 3\nallow_dynamic_context = true\n# Auto-detect language from PR content (Chinese contributors are common)\nresponse_language = \"en-US\"\n# Custom labels for OpenViking-specific PR categorization\nenable_custom_labels = true\n\n# ---------------------------------------------------------------------------\n# Ignore: skip generated/vendored/lock files from analysis\n# Reduces noise and token waste on files humans don't review.\n# ---------------------------------------------------------------------------\n[ignore]\nglob = [\n # Lock files (auto-generated, not human-authored)\n 'uv.lock',\n '*.lock',\n 'package-lock.json',\n # Third-party vendored code (not our responsibility)\n 'third_party/**',\n # Rust build artifacts\n 'target/**',\n # Test data fixtures (binary/large JSON blobs)\n 'db_test_*/**',\n 'test_data/**',\n 'test_data_sync/**',\n # Worktree scratch spaces\n '.worktrees/**',\n # Build support (C++ profiles, not core logic)\n 'build_support/**',\n]\n\n# ---------------------------------------------------------------------------\n# Auto-triggers on PR open\n# ---------------------------------------------------------------------------\n[github_app]\npr_commands = [\n \"/describe\",\n \"/review\",\n \"/improve --pr_code_suggestions.commitable_code_suggestions=false\",\n]\n\n# ---------------------------------------------------------------------------\n# Custom Labels: OpenViking-specific PR categorization\n# Each description is a conditional statement (Qodo best practice) so the\n# model knows exactly when to apply it.\n# ---------------------------------------------------------------------------\n[custom_labels.\"memory-pipeline\"]\ndescription = \"Apply when the PR modifies memory extraction, deduplication, archival, or any code in openviking/session/ that touches MemoryCategory, SessionCompressor, MemoryDeduplicator, or MemoryExtractor.\"\n\n[custom_labels.\"async-change\"]\ndescription = \"Apply when the PR modifies async/await patterns, changes commit() to commit_async(), adds asyncio.gather/TaskGroup usage, or modifies any coroutine in the session or storage layer.\"\n\n[custom_labels.\"embedding-vectorization\"]\ndescription = \"Apply when the PR modifies embedding models, vectorization logic, chunked vectorization, or VLM provider integrations in openviking/embedding/ or openviking/vlm/.\"\n\n[custom_labels.\"plugin-bot\"]\ndescription = \"Apply when the PR modifies TypeScript code in bot/ or examples/openclaw-plugin/, including hook handlers, process management, or client initialization.\"\n\n[custom_labels.\"api-breaking\"]\ndescription = \"Apply when the PR removes, renames, or changes the type of any public API parameter, REST endpoint, SDK method, or configuration key that external consumers depend on.\"\n\n[custom_labels.\"multi-tenant\"]\ndescription = \"Apply when the PR modifies authentication, authorization, account/user routing, root key handling, or RequestContext identity resolution.\"\n\n[custom_labels.\"retrieval\"]\ndescription = \"Apply when the PR modifies the retrieval pipeline: find, rerank, semantic search, or context level (L0/L1/L2) scoring logic.\"\n\n[custom_labels.\"rust-cli\"]\ndescription = \"Apply when the PR modifies Rust source files (src/*.rs) or Cargo.toml for the CLI tool.\"\n\n# ---------------------------------------------------------------------------\n# Review Tool\n# ---------------------------------------------------------------------------\n[pr_reviewer]\npersistent_comment = true\nfinal_update_message = true\n# Increased from default 3 → 8 because OpenViking PRs often span multiple\n# subsystems (Python core + TypeScript bot + config) with cross-cutting concerns.\nnum_max_findings = 8\nenable_intro_text = true\nenable_help_text = false\npublish_output_no_suggestions = true\n\n# --- Feature toggles (overrides from defaults) ---\nrequire_score_review = true # Score each PR 1-100 (disabled by default, useful for quality tracking)\nrequire_tests_review = true # Check if tests are present (default: true)\nrequire_estimate_effort_to_review = true # Effort estimate label (default: true)\nrequire_can_be_split_review = true # Flag large PRs that should be split (default: false → enabled)\nrequire_security_review = true # Dedicated security audit section (default: true)\nrequire_todo_scan = true # Surface TODO/FIXME/HACK in changed code (default: false → enabled)\nrequire_ticket_analysis_review = true # Check ticket compliance if linked\n\n# --- Labels ---\nenable_review_labels_security = true\nenable_review_labels_effort = true\n\nextra_instructions = \"\"\"\\\nYou are reviewing OpenViking — an agent-native context database.\nStack: Python 3.10+ core (FastAPI, pydantic, httpx, loguru), TypeScript bot\n(Vikingbot/OpenClaw plugin), Rust CLI, C++ extensions (AGFS).\n\n## Severity Classification (exactly ONE per finding)\n\n[Critical] — Blocks release. Security vulnerability, data loss/corruption, crash in\nproduction path, resource leak without cleanup, auth bypass.\n\n[Bug] — Must fix before merge. Logic error, behavioral regression, API contract\nviolation, race condition, missing await on coroutine, silent exception swallowing.\n\n[Perf] — Performance regression. O(n²)+ algorithmic complexity, unbounded collection\ngrowth, N+1 queries against VikingDB, redundant embedding/VLM API calls,\nunnecessary large object copies in hot paths.\n\n[Suggestion] — Recommended improvement. Missing tests, dead code, naming inconsistency,\npoor observability (missing telemetry/logging), unclear intent, unrelated changes in PR.\n\n## Rules (structured as: WHEN condition → THEN check → BECAUSE rationale)\n\n### PYTHON CORE (openviking/, openviking_cli/)\n\nR1. ASYNC DISCIPLINE\nWHEN code is inside an async function or coroutine\nTHEN verify all I/O calls use async variants (commit_async not commit,\n httpx.AsyncClient not requests, async for on streams)\nBECAUSE blocking calls in async context starve the event loop.\n Real bug: PR #728 replaced blocking commit() with commit_async().\n Also check: missing `await` on coroutine calls (silent bug — returns\n coroutine object instead of result).\n\nR2. MEMORY PIPELINE COMPLETENESS\nWHEN code touches MemoryCategory, MemoryExtractor, MemoryDeduplicator,\n SessionCompressor, or MemoryArchiver\nTHEN verify all 6 categories are handled: PREFERENCES, ENTITIES, PATTERNS,\n EVENTS, TOOLS, SKILLS. Check that match/if-elif chains on DedupDecision\n (KEEP/MERGE/DELETE/SKIP) are exhaustive.\nBECAUSE partial handling silently drops memories. The 6-category model is\n a core invariant of the extraction pipeline.\n\nR3. QUADRATIC REPROCESSING GUARD\nWHEN code enqueues items (SemanticMsg, embedding tasks) inside a loop that\n also processes the queue, or when a callback re-enqueues work\nTHEN flag as [Perf] or [Bug] — this pattern causes O(n²) reprocessing.\nBECAUSE PR #505 fixed exactly this: misdirected SemanticMsg enqueue inside\n a processing loop caused quadratic growth.\n\nR4. VLM/EMBEDDING API RESILIENCE\nWHEN code calls VLM providers (OpenAI, Doubao/Ark, Gemini) or embedding APIs\nTHEN verify: (a) timeout is set (ai_timeout or explicit), (b) retry/fallback\n exists for transient failures, (c) streaming responses handle partial\n failure gracefully, (d) JSON output uses json-repair not raw json.loads.\nBECAUSE PR #740 was reverted (#745) due to streaming response issues, then\n re-landed in #756 with proper handling. This is a repeat-risk area.\n\nR5. TYPE SAFETY\nWHEN new Python code is added or modified\nTHEN check: no bare `type: ignore` (must have explanation comment), consistent\n Optional[X] vs X|None style within each file, proper use of\n TYPE_CHECKING imports for circular dependency avoidance.\nBECAUSE CI enforces ruff + mypy on changed files. Suppressions without\n rationale hide real type errors.\n\nR6. LICENSE HEADERS\nWHEN a new .py file is created in openviking/ or openviking_cli/\nTHEN it MUST contain at the top:\n # Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.\n # SPDX-License-Identifier: Apache-2.0\nBECAUSE Apache-2.0 compliance requires headers on all source files.\n Every existing file in these directories follows this convention.\n\nR7. ERROR HANDLING\nWHEN code uses try/except\nTHEN verify: no bare `except:` or `except Exception:` without logging (loguru)\n or re-raising. Narrow exceptions to specific types where possible.\nBECAUSE PR #148f6e3 fixed overly broad `except Exception` to specific\n (ImportError, ModuleNotFoundError, AttributeError). Broad catches hide\n real bugs.\n\n### TYPESCRIPT / BOT (bot/, examples/openclaw-plugin/)\n\nR8. PLUGIN HOOK TIMEOUT\nWHEN code registers or modifies a hook handler (before_prompt_build,\n after_prompt_build, etc.) or calls getClient()\nTHEN verify the call has timeout protection (Promise.race with timeout,\n AbortController, or equivalent).\nBECAUSE PR #749 added timeout protection to getClient() after discovering\n hooks could hang indefinitely, blocking the entire bot.\n\nR9. PROCESS LIFECYCLE\nWHEN code spawns child processes or manages bot lifecycle\nTHEN verify: SIGTERM/SIGINT handlers exist, stdio streams are properly\n closed, and cleanup runs in all exit paths (including uncaught exceptions).\nBECAUSE the bot uses process-manager.ts for lifecycle; leaked processes or\n file descriptors degrade the host system.\n\n### CROSS-CUTTING\n\nR10. API BACKWARD COMPATIBILITY\nWHEN a PR modifies public interfaces (FastAPI endpoints, SDK client params,\n RequestContext fields, config keys in ov.conf)\nTHEN verify: existing params are not removed or renamed (only deprecated),\n new params have defaults, multi-tenant changes preserve single-tenant\n behavior as the default path.\nBECAUSE PR #767 added account/user params — these must be optional to avoid\n breaking existing single-tenant deployments.\n\nR11. CONCURRENCY SAFETY\nWHEN code modifies shared mutable state (dicts, lists, sets) in async\n functions, or uses _pending_semantic_changes or similar shared structures\nTHEN verify proper synchronization (asyncio.Lock, thread-safe collections)\n and that no produce-and-consume-in-same-loop pattern exists.\nBECAUSE the SessionCompressor._pending_semantic_changes dict is accessed\n from multiple async paths; unsynchronized access causes data races.\n\nR12. RETRIEVAL PIPELINE INTEGRITY\nWHEN code modifies find/rerank/search logic or ContextLevel scoring (L0/L1/L2)\nTHEN verify: rerank is optional (PR #754 fixed find-without-rerank), level-2\n scores are preserved through the pipeline, and search results maintain\n their ranking order.\nBECAUSE PR #754 fixed a bug where find() required rerank and level-2 scores\n were silently dropped.\n\nR13. TESTING REQUIREMENTS\nWHEN a PR fixes a bug → it MUST include a regression test or explicitly\n explain in the PR description why one is impractical.\nWHEN a PR adds a feature → it SHOULD include unit tests for the happy path\n and at least one error/edge case.\nWHEN a PR modifies embedding/VLM integration → verify test isolation (no\n hardcoded API keys — construct test keys dynamically as in PR #148f6e3).\nBECAUSE the repo uses pytest; test patterns should use fixtures, not globals.\n\nR14. DOCUMENTATION CONSISTENCY\nWHEN a PR modifies docs/ (en/ and zh/cn/ and ja/) or README files\nTHEN verify all language versions are updated consistently. Flag if only\n one language is updated when the content change is substantive.\nBECAUSE the repo maintains en/zh/ja translations (PR #755 added Japanese docs).\n\nR15. TELEMETRY & OBSERVABILITY\nWHEN code adds or modifies operations that call external services (VLM, embedding,\n VikingDB) or processes memories\nTHEN verify telemetry integration exists (get_current_telemetry pattern) and that\n timing/count metrics are recorded for the operation.\nBECAUSE PR #735 added memory extract telemetry breakdown — new operations\n should follow this pattern for production observability.\n\n## Output Format\nBe specific: reference exact variable names, function calls, line numbers.\nWhen suggesting a fix, include a minimal code block.\nMatch PR language (Chinese PR → Chinese review, English PR → English review).\n\"\"\"\n\n# ---------------------------------------------------------------------------\n# Improve Tool (code suggestions)\n# ---------------------------------------------------------------------------\n[pr_code_suggestions]\ncommitable_code_suggestions = false\npersistent_comment = true\nfocus_only_on_problems = true\n# Filter low-confidence suggestions. 0 = show all, 7+ = high quality only.\n# Set to 5 to balance signal-to-noise for this codebase.\nsuggestions_score_threshold = 5\n# Extended mode for thorough analysis of large PRs\nauto_extended_mode = true\nnum_code_suggestions_per_chunk = 4\nmax_number_of_calls = 3\nparallel_calls = true\n\nextra_instructions = \"\"\"\\\nFocus suggestions on these OpenViking-specific anti-patterns:\n\n1. BLOCKING IN ASYNC: Replace `commit()`, `requests.get()`, `time.sleep()` with\n `commit_async()`, `httpx.AsyncClient`, `asyncio.sleep()` inside async functions.\n\n2. QUADRATIC LOOPS: Simplify nested loops over memory categories or semantic queues.\n If an inner loop re-processes items already in the outer loop, suggest flattening\n or using a set-based approach.\n\n3. PROMPT CONSTRUCTION: Extract repeated LLM prompt strings into Jinja2 templates\n (the dependency exists in pyproject.toml). Inline f-string prompts over 5 lines\n should be templated.\n\n4. LOGGING: Replace `print()` with `logger = get_logger(__name__)` (loguru pattern\n used throughout the codebase). Include structured context in log messages.\n\n5. VALIDATION: Prefer pydantic models for API request/response validation over raw\n dicts. The codebase already depends on pydantic>=2.0.0.\n\n6. API RESILIENCE: Flag any VLM/embedding API call missing timeout or retry logic.\n Suggest wrapping with httpx timeout config or litellm retry patterns.\n\n7. RESOURCE CLEANUP: Ensure context managers (async with) are used for DB connections,\n HTTP clients, and file handles. Flag bare open() without context manager.\n\"\"\"\n\n# ---------------------------------------------------------------------------\n# Describe Tool\n# ---------------------------------------------------------------------------\n[pr_description]\ngenerate_ai_title = false\nuse_bullet_points = true\nadd_original_user_description = true\nenable_pr_type = true\nenable_pr_diagram = true\nenable_semantic_files_types = true\ncollapsible_file_list = 'adaptive'\ncollapsible_file_list_threshold = 8\nenable_large_pr_handling = true\ninclude_generated_by_header = true\npublish_labels = true\nfinal_update_message = true\n\nextra_instructions = \"\"\"\\\nFor OpenViking PRs, structure the description to include:\n- **Layer affected**: core (Python), bot (TypeScript), CLI (Rust), AGFS (C++/Go), or docs.\n- **Backward compatibility**: state whether existing APIs, config keys, or SDK params are affected.\n- **Memory pipeline impact**: if session/ is touched, list which of the 6 memory categories\n (PREFERENCES, ENTITIES, PATTERNS, EVENTS, TOOLS, SKILLS) are affected.\n- **Multi-tenant impact**: if auth/identity is touched, note whether single-tenant default is preserved.\n\"\"\"\n" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.14.14\n hooks:\n - id: ruff\n args: [ --fix ]\n - id: ruff-format\n" }, { "path": "CONTRIBUTING.md", "content": "# Contributing Guide\n\nThank you for your interest in OpenViking! We welcome contributions of all kinds:\n\n- Bug reports\n- Feature requests\n- Documentation improvements\n- Code contributions\n\n---\n\n## Development Setup\n\n### Prerequisites\n\n- **Python**: 3.10+\n- **Go**: 1.22+ (Required for building AGFS components from source)\n- **Rust**: 1.88+ (Required for source builds because the bundled `ov` CLI is built during packaging)\n- **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions, must support C++17)\n- **CMake**: 3.12+\n\n#### Platform-Specific Native Build Tools\n\n- **Linux**: Install `build-essential`; some environments may also require `pkg-config`\n- **macOS**: Install Xcode Command Line Tools (`xcode-select --install`)\n- **Windows**: Install CMake and MinGW for local native builds\n\n#### Supported Platforms (Pre-compiled Wheels)\n\nOpenViking provides pre-compiled **Wheel** packages for the following environments:\n\n- **Windows**: x86_64\n- **macOS**: x86_64, arm64 (Apple Silicon)\n- **Linux**: x86_64, arm64 (manylinux)\n\nFor other platforms (e.g., FreeBSD), the package will be automatically compiled from source during installation via `pip`. Ensure you have the [Prerequisites](#prerequisites) installed.\n\n### 1. Fork and Clone\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/openviking.git\ncd openviking\n```\n\n### 2. Install Dependencies\n\nWe recommend using `uv` for Python environment management:\n\n```bash\n# Install uv (if not installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Sync dependencies and create virtual environment\nuv sync --all-extras\nsource .venv/bin/activate # Linux/macOS\n# or .venv\\Scripts\\activate # Windows\n```\n\n#### Local Development & Native Rebuilds\n\nOpenViking defaults to `binding-client` mode for AGFS, which requires pre-built native artifacts. If you modify the **AGFS (Go)** code, the bundled **Rust CLI**, or the **C++ extensions**, or if the pre-built artifacts are not found, you need to re-compile and re-install them. Run the following command in the project root:\n\n```bash\nuv pip install -e . --force-reinstall\n```\n\nThis command ensures that `setup.py` is re-executed, triggering rebuilds for AGFS, the bundled `ov` CLI, and the C++ components.\n\n### 3. Configure Environment\n\nCreate a configuration file `~/.openviking/ov.conf`:\n\n```json\n{\n \"embedding\": {\n \"dense\": {\n \"provider\": \"volcengine\",\n \"api_key\": \"your-api-key\",\n \"model\": \"doubao-embedding-vision-250615\",\n \"api_base\": \"https://ark.cn-beijing.volces.com/api/v3\",\n \"dimension\": 1024,\n \"input\": \"multimodal\"\n }\n },\n \"vlm\": {\n \"api_key\": \"your-api-key\",\n \"model\": \"doubao-seed-2-0-pro-260215\",\n \"api_base\": \"https://ark.cn-beijing.volces.com/api/v3\"\n }\n}\n```\n\nSet the environment variable:\n\n```bash\nexport OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf\n```\n\n### 4. Verify Installation\n\n```python\nimport asyncio\nimport openviking as ov\n\nasync def main():\n client = ov.AsyncOpenViking(path=\"./test_data\")\n await client.initialize()\n print(\"OpenViking initialized successfully!\")\n await client.close()\n\nasyncio.run(main())\n```\n\n### 5. Build Rust CLI (Optional)\n\nThe Rust CLI (`ov`) provides a high-performance command-line client for interacting with OpenViking Server.\n\nEven if you do not plan to use `ov` directly, the Rust toolchain is still required when building OpenViking from source because packaging also builds the bundled CLI binary.\n\n```bash\n# Build and install from source\ncargo install --path crates/ov_cli\n\n# Or use the quick install script (downloads pre-built binary)\ncurl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash\n```\n\nAfter installation, run `ov --help` to see all available commands. CLI connection config goes in `~/.openviking/ovcli.conf`.\n\n---\n\n## Project Structure\n\n```\nopenviking/\n├── pyproject.toml # Project configuration\n├── Cargo.toml # Rust workspace configuration\n├── third_party/ # Third-party dependencies\n│ └── agfs/ # AGFS filesystem\n│\n├── openviking/ # Python SDK\n│ ├── async_client.py # AsyncOpenViking client\n│ ├── sync_client.py # SyncOpenViking client\n│ ├── client/ # Local and HTTP client implementations\n│ ├── console/ # Standalone console UI and proxy service\n│ ├── core/ # Core data models and directory abstractions\n│ ├── message/ # Session message and part models\n│ ├── models/ # Embedding and VLM backends\n│ ├── parse/ # Resource parsers and detectors\n│ ├── resource/ # Resource processing and watch management\n│ ├── retrieve/ # Retrieval system\n│ ├── server/ # HTTP server\n│ ├── service/ # Shared service layer\n│ ├── session/ # Session management and compression\n│ ├── storage/ # Storage layer\n│ ├── telemetry/ # Operation telemetry\n│ ├── trace/ # Trace and runtime tracing helpers\n│ ├── utils/ # Utilities and configuration helpers\n│ └── prompts/ # Prompt templates\n│\n├── crates/ # Rust components\n│ └── ov_cli/ # Rust CLI client\n│ ├── src/ # CLI source code\n│ └── install.sh # Quick install script\n│\n├── src/ # C++ extensions (pybind11)\n│\n├── tests/ # Test suite\n│ ├── client/ # Client tests\n│ ├── console/ # Console tests\n│ ├── core/ # Core logic tests\n│ ├── parse/ # Parser tests\n│ ├── resource/ # Resource processing tests\n│ ├── retrieve/ # Retrieval tests\n│ ├── server/ # Server tests\n│ ├── service/ # Service layer tests\n│ ├── session/ # Session tests\n│ ├── storage/ # Storage tests\n│ ├── telemetry/ # Telemetry tests\n│ ├── vectordb/ # Vector database tests\n│ └── integration/ # End-to-end tests\n│\n└── docs/ # Documentation\n ├── en/ # English docs\n └── zh/ # Chinese docs\n```\n\n---\n\n## Code Style\n\nWe use the following tools to maintain code consistency:\n\n| Tool | Purpose | Config |\n|------|---------|--------|\n| **Ruff** | Linting, Formatting, Import sorting | `pyproject.toml` |\n| **mypy** | Type checking | `pyproject.toml` |\n\n### Automated Checks (Recommended)\n\nWe use [pre-commit](https://pre-commit.com/) to automatically run these checks before every commit. This ensures your code always meets the standards without manual effort.\n\n1. **Install pre-commit**:\n ```bash\n pip install pre-commit\n ```\n\n2. **Install the git hooks**:\n ```bash\n pre-commit install\n ```\n\nNow, `ruff` (check & format) will run automatically when you run `git commit`. If any check fails, it may automatically fix the file. You just need to add the changes and commit again.\n\n### Running Checks\n\n```bash\n# Format code\nruff format openviking/\n\n# Lint\nruff check openviking/\n\n# Type check\nmypy openviking/\n```\n\n### Style Guidelines\n\n1. **Line width**: 100 characters\n2. **Indentation**: 4 spaces\n3. **Strings**: Prefer double quotes\n4. **Type hints**: Encouraged but not required\n5. **Docstrings**: Required for public APIs (1-2 lines max)\n\n---\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run specific test module\npytest tests/client/ -v\npytest tests/server/ -v\npytest tests/parse/ -v\n\n# Run specific test file\npytest tests/client/test_lifecycle.py\n\n# Run specific test\npytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success\n\n# Run by keyword\npytest -k \"search\" -v\n\n# Run with coverage\npytest --cov=openviking --cov-report=term-missing\n```\n\n### Writing Tests\n\nTests are organized in subdirectories under `tests/`. The project uses `asyncio_mode = \"auto\"`, so async tests do **not** need the `@pytest.mark.asyncio` decorator:\n\n```python\n# tests/client/test_example.py\nfrom openviking import AsyncOpenViking\n\n\nclass TestAsyncOpenViking:\n async def test_initialize(self, uninitialized_client: AsyncOpenViking):\n await uninitialized_client.initialize()\n assert uninitialized_client._service is not None\n await uninitialized_client.close()\n\n async def test_add_resource(self, client: AsyncOpenViking, sample_markdown_file):\n result = await client.add_resource(\n path=str(sample_markdown_file),\n reason=\"test document\"\n )\n assert \"root_uri\" in result\n assert result[\"root_uri\"].startswith(\"viking://\")\n```\n\nCommon fixtures are defined in `tests/conftest.py`, including `client` (initialized `AsyncOpenViking`), `uninitialized_client`, `temp_dir`, `sample_markdown_file`, and more.\n\n---\n\n## Contribution Workflow\n\n### 1. Create a Branch\n\n```bash\ngit checkout main\ngit pull origin main\ngit checkout -b feature/your-feature-name\n```\n\nBranch naming conventions:\n- `feature/xxx` - New features\n- `fix/xxx` - Bug fixes\n- `docs/xxx` - Documentation updates\n- `refactor/xxx` - Code refactoring\n\n### 2. Make Changes\n\n- Follow code style guidelines\n- Add tests for new functionality\n- Update documentation as needed\n\n### 3. Commit Changes\n\n```bash\ngit add .\ngit commit -m \"feat: add new parser for xlsx files\"\n```\n\n### 4. Push and Create PR\n\n```bash\ngit push origin feature/your-feature-name\n```\n\nThen create a Pull Request on GitHub.\n\n---\n\n## Commit Convention\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/):\n\n```\n(): \n\n\n\n