# Contributing Guide Thank you for your interest in OpenViking! We welcome contributions of all kinds: - Bug reports - Feature requests - Documentation improvements - Code contributions --- ## Development Setup ### Prerequisites - **Python**: 3.10+ - **Go**: 1.22+ (Required only for Go SDK development under `sdk/go`) - **Rust**: 1.91.1+ (Required for source builds because the bundled `ov` CLI is built during packaging) - **C++ Compiler**: GCC 9+ or Clang 11+ (Required for building core extensions, must support C++17) - **CMake**: 3.12+ #### Platform-Specific Native Build Tools - **Linux**: Install `build-essential`; some environments may also require `pkg-config` - **macOS**: Install Xcode Command Line Tools (`xcode-select --install`) - **Windows**: Install CMake and MinGW for local native builds #### Supported Platforms (Pre-compiled Wheels) OpenViking provides pre-compiled **Wheel** packages for the following environments: - **Windows**: x86_64 - **macOS**: x86_64, arm64 (Apple Silicon) - **Linux**: x86_64, arm64 (manylinux) For other platforms (e.g., FreeBSD), the package will be automatically compiled from source during installation via `pip`. Ensure you have the [Prerequisites](#prerequisites) installed. ### 1. Fork and Clone ```bash git clone https://github.com/YOUR_USERNAME/openviking.git cd openviking ``` ### 2. Install Dependencies We recommend using `uv` for Python environment management: ```bash # Install uv (if not installed) curl -LsSf https://astral.sh/uv/install.sh | sh # Sync dependencies and create virtual environment uv sync --all-extras source .venv/bin/activate # Linux/macOS # or .venv\Scripts\activate # Windows ``` #### Local Development & Native Rebuilds OpenViking defaults to `binding-client` mode for AGFS/RAGFS, which requires pre-built native artifacts. If you modify the **RAGFS Rust binding**, 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: ```bash uv pip install -e . --force-reinstall ``` This command ensures that `setup.py` is re-executed, triggering rebuilds for AGFS/RAGFS, the bundled `ov` CLI, and the C++ components. ### 3. Configure Environment Create a configuration file `~/.openviking/ov.conf`: ```json { "embedding": { "dense": { "provider": "volcengine", "api_key": "your-api-key", "model": "doubao-embedding-vision-251215", "api_base": "https://ark.cn-beijing.volces.com/api/v3", "dimension": 1024, "input": "multimodal" } }, "vlm": { "api_key": "your-api-key", "model": "doubao-seed-2-0-lite-260428", "api_base": "https://ark.cn-beijing.volces.com/api/v3" } } ``` Set the environment variable: ```bash export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf ``` ### 4. Verify Installation ```python import asyncio import openviking as ov async def main(): client = ov.AsyncOpenViking(path="./test_data") await client.initialize() print("OpenViking initialized successfully!") await client.close() asyncio.run(main()) ``` ### 5. Build Rust CLI (Optional) The Rust CLI (`ov`) provides a high-performance command-line client for interacting with OpenViking Server. Even 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. ```bash # Build and install from source cargo install --path crates/ov_cli # Or install the published npm CLI package (downloads pre-built binary) npm i -g @openviking/cli ``` After installation, run `ov --help` to see all available commands. CLI connection config goes in `~/.openviking/ovcli.conf`. --- ## Project Structure ``` openviking/ ├── pyproject.toml # Project configuration ├── Cargo.toml # Rust workspace configuration ├── third_party/ # Third-party dependencies │ ├── krl/ # Native retrieval dependency │ ├── leveldb-1.23/ # Embedded key-value storage dependency │ └── spdlog-1.14.1/ # Native logging dependency │ ├── openviking/ # Python SDK │ ├── async_client.py # AsyncOpenViking client │ ├── sync_client.py # SyncOpenViking client │ ├── client/ # Local and HTTP client implementations │ ├── console/ # Standalone console UI and proxy service │ ├── core/ # Core data models and directory abstractions │ ├── message/ # Session message and part models │ ├── models/ # Embedding and VLM backends │ ├── parse/ # Resource parsers and detectors │ ├── resource/ # Resource processing and watch management │ ├── retrieve/ # Retrieval system │ ├── server/ # HTTP server │ ├── service/ # Shared service layer │ ├── session/ # Session management and compression │ ├── storage/ # Storage layer │ ├── telemetry/ # Operation telemetry │ ├── trace/ # Trace and runtime tracing helpers │ ├── utils/ # Utilities and configuration helpers │ └── prompts/ # Prompt templates │ ├── crates/ # Rust components │ ├── ragfs/ # Rust implementation of AGFS │ ├── ragfs-python/ # Python binding for RAGFS │ └── ov_cli/ # Rust CLI client │ ├── src/ # CLI source code │ └── install.sh # Deprecated stub (use npm package; see Install) │ ├── src/ # C++ extension sources (Python abi3) │ ├── tests/ # Test suite │ ├── client/ # Client tests │ ├── console/ # Console tests │ ├── core/ # Core logic tests │ ├── parse/ # Parser tests │ ├── resource/ # Resource processing tests │ ├── retrieve/ # Retrieval tests │ ├── server/ # Server tests │ ├── service/ # Service layer tests │ ├── session/ # Session tests │ ├── storage/ # Storage tests │ ├── telemetry/ # Telemetry tests │ ├── vectordb/ # Vector database tests │ └── integration/ # End-to-end tests │ └── docs/ # Documentation ├── en/ # English docs └── zh/ # Chinese docs ``` --- ## Code Style We use the following tools to maintain code consistency: | Tool | Purpose | Config | |------|---------|--------| | **Ruff** | Linting, Formatting, Import sorting | `pyproject.toml` | | **mypy** | Type checking | `pyproject.toml` | ### Running Checks ```bash # Format code ruff format openviking/ # Lint ruff check openviking/ # Type check mypy openviking/ ``` ### Style Guidelines 1. **Line width**: 100 characters 2. **Indentation**: 4 spaces 3. **Strings**: Prefer double quotes 4. **Type hints**: Encouraged but not required 5. **Docstrings**: Required for public APIs (1-2 lines max) --- ## Testing ### Running Tests ```bash # Run all tests pytest # Run specific test module pytest tests/client/ -v pytest tests/server/ -v pytest tests/parse/ -v # Run specific test file pytest tests/client/test_lifecycle.py # Run specific test pytest tests/client/test_lifecycle.py::TestClientInitialization::test_initialize_success # Run by keyword pytest -k "search" -v # Run with coverage pytest --cov=openviking --cov-report=term-missing ``` ### Writing Tests Tests are organized in subdirectories under `tests/`. The project uses `asyncio_mode = "auto"`, so async tests do **not** need the `@pytest.mark.asyncio` decorator: ```python # tests/client/test_example.py from openviking import AsyncOpenViking class TestAsyncOpenViking: async def test_initialize(self, uninitialized_client: AsyncOpenViking): await uninitialized_client.initialize() assert uninitialized_client._service is not None await uninitialized_client.close() async def test_add_resource(self, client: AsyncOpenViking, sample_markdown_file): result = await client.add_resource( path=str(sample_markdown_file), reason="test document" ) assert "root_uri" in result assert result["root_uri"].startswith("viking://") ``` Common fixtures are defined in `tests/conftest.py`, including `client` (initialized `AsyncOpenViking`), `uninitialized_client`, `temp_dir`, `sample_markdown_file`, and more. --- ## Maintainer Routing and Contribution Entry ### Contributor-Facing Module Map If you are not sure where your question, issue, or PR belongs, start with this table: | Domain | Area | Primary Contact | |--------|------|-----------------| | Integration | Bot | `@yeshion23333` | | Integration | OpenClaw Plugin | `@Mijamind719`, `@wlff123` | | Platform | Framework / Multi-tenant / Resources / Session | `@qin-ctx` | | Platform | Incremental / Scheduled Update | `@myysy` | | Knowledge | Memory | `@chenjw` | | Knowledge | Retrieval / Directory Semantics | `@zhoujh01` | | Storage & Security | Virtual FS / File Encryption | `@chuanbao666`, `@baojun-zhang` | If the area is still unclear, mention one of the cross-module maintainers listed below. ### Maintainer Routing Map Use this table when routing issues, PRs, or design questions to a more specific owner: | Domain | Subarea | Representative Paths or Topics | Primary Contact | Backup / Cross-Module | |--------|---------|--------------------------------|-----------------|-----------------------| | Integration | Bot Runtime | `bot/vikingbot`, `bot/bridge`, deployment scripts, bot docs | `@yeshion23333` | `@chenjw` | | Integration | OpenClaw Plugin | `examples/openclaw-plugin`, installation, remote mode, compatibility | `@Mijamind719`, `@wlff123` | `@LinQiang391` | | Platform | Server & Multi-tenant | `openviking/server`, `openviking/service`, auth, identity, admin, tenant boundary | `@qin-ctx` | `@MaojiaSheng` | | Platform | Resource & Session Lifecycle | `openviking/resource`, `openviking/session`, resource ingestion, session lifecycle | `@qin-ctx` | `@MaojiaSheng` | | Platform | Incremental & Scheduled Update | `openviking/resource/watch_manager.py`, `openviking/resource/watch_scheduler.py` | `@myysy` | `@qin-ctx` | | Knowledge | Memory Engine | `openviking/session/memory`, `memory_extractor.py`, `memory_deduplicator.py` | `@chenjw` | `@qin-ctx` | | Knowledge | Retrieval & Directory Semantics | `openviking/retrieve`, intent analysis, hierarchical retrieval, directory semantics | `@zhoujh01` | `@qin-ctx` | | Storage & Security | VFS / AGFS Path Semantics | `openviking/storage`, `openviking/pyagfs`, filesystem behavior, path semantics | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` | | Storage & Security | Encryption & Data Safety | `openviking/crypto`, file encryption, storage safety | `@chuanbao666`, `@baojun-zhang` | `@zhoujh01` | For areas without a stable owner yet, cross-module maintainers will help route the request first. ### Cross-Module Maintainers - `@MaojiaSheng` - `@qin-ctx` - `@zhoujh01` Cross-module maintainers help with issue routing, cross-cutting design questions, and fallback review support. ### How to Ask for Help - If you already know the affected module, mention it in the issue or PR description. - If you are unsure about the module, describe the use case and affected behavior first. - If you want to work on an issue, leave a comment before starting, especially for cross-module changes. - If your PR spans multiple areas, call out the primary affected domain in the description. ### Contribution Entry Labels Issue templates already classify reports such as `bug`, `enhancement`, and `question`. Maintainers may also use the following labels to make contribution entry clearer: | Label | Meaning | |-------|---------| | `good first issue` | Newcomer-friendly work with clear scope and acceptance criteria | | `help wanted` | Tasks that benefit from contributors who already know the codebase or review style | | `needs-design` | Work that needs maintainer clarification before implementation | | `needs-review` | Pull requests waiting for the first review round | ### Contributor Growth Path The project uses a practical contribution path so contributors can see what “next step” looks like: | Stage | Typical Signals | Common Next Step | |-------|------------------|------------------| | New Contributor | First issue or first PR, often docs, tests, or scoped fixes | Start with `good first issue` items and get familiar with local workflow | | Active Contributor | One or more merged contributions | Pick up `help wanted` work in an area you already touched | | Module Contributor | Repeated contributions in the same subarea | Help with triage, reproduction, docs, or review comments in that area | | Backup Reviewer Candidate | Stable contribution record in one subarea | Help with first-pass review, routing, and contributor support | ## Contribution Workflow ### 1. Create a Branch ```bash git checkout main git pull origin main git checkout -b feature/your-feature-name ``` Branch naming conventions: - `feature/xxx` - New features - `fix/xxx` - Bug fixes - `docs/xxx` - Documentation updates - `refactor/xxx` - Code refactoring ### 2. Make Changes - Follow code style guidelines - Add tests for new functionality - Update documentation as needed ### 3. Commit Changes ```bash git add . git commit -m "feat: add new parser for xlsx files" ``` ### 4. Push and Create PR ```bash git push origin feature/your-feature-name ``` Then create a Pull Request on GitHub. --- ## Commit Convention We follow [Conventional Commits](https://www.conventionalcommits.org/): ``` ():