🤝 Contributing¶

We'd love your help making Spector even better! Whether you're fixing a bug, adding a feature, improving docs, or optimizing performance — every contribution matters. This page covers everything you need to get started.

🚀 Development Setup¶

📋 Prerequisites¶

🏗️ First-Time Setup¶

# Fork and clone
git clone https://github.com/<your-username>/spector.git
cd spector

# Verify JDK
java -version   # Should show 25+

# Build the project
mvn clean compile

# Run the full test suite (316+ tests)
mvn test

# Verify SIMD support
java --add-modules jdk.incubator.vector -cp spector-core/target/classes \
  com.spectrayan.spector.core.SimdCapability

📦 Module Structure¶

graph LR
    subgraph "🔬 Foundation"
        core["spector-core<br/>SIMD kernels"]
        commons["spector-commons<br/>Chunkers, readers"]
        storage["spector-storage<br/>Off-heap stores"]
    end

    subgraph "📊 Search"
        index["spector-index<br/>HNSW, IVF-PQ, BM25"]
        query["spector-query<br/>Hybrid + RRF"]
    end

    subgraph "🧠 Intelligence"
        providerapi["spector-provider-api<br/>Provider SPI"]
        providers["spector-providers<br/>AI Providers"]
        gpu["spector-gpu<br/>CUDA via Panama"]
    end

    subgraph "⚡ Applications"
        engine["spector-engine<br/>Unified facade"]
        server["spector-synapse<br/>REST / Spring Web"]
        cluster["spector-synapse<br/>Distributed coordination"]
        cli["spector-cli<br/>CLI tool"]
        client["spector-client<br/>Java SDK"]
        spring["spector-spring<br/>Spring AI"]
    end

    subgraph "📈 Quality"
        bench["spector-bench<br/>JMH benchmarks"]
    end

🧪 Running Tests¶

# Full suite
mvn test

# Single module
mvn test -pl spector-core

# Single test class
mvn test -pl spector-core -Dtest=DotProductTest

# With JMH benchmarks
mvn -pl spector-bench exec:java

📝 Code Style¶

Java Conventions¶

⚡ Performance Rules¶

• No allocations in hot paths — Reuse buffers, use slice-based APIs

• Branchless SIMD — Use VectorMask for tail handling, no scalar fallback

• Benchmark before/after — Performance PRs must include JMH results

🏗️ Architecture Rules¶

• Respect module boundaries — Follow the dependency graph, no circular dependencies

• Interface-first — Add interfaces before implementations

• Zero-copy — Prefer MemorySegment slices over array copies

🌿 Branch Naming¶

feat/add-quantization-support
fix/hnsw-concurrent-insert-race
perf/simd-avx512-unroll-loop
refactor/storage-arena-lifecycle
docs/api-usage-examples

💬 Commit Messages¶

Follow Conventional Commits:

feat(core): add AVX-512 double-pump dot product kernel
fix(index): prevent HNSW neighbor list corruption under concurrent insert
perf(storage): use bulk MemorySegment.copy for vector reads
refactor(query): extract RRF into standalone utility class
docs: add benchmark results to README
test(index): add property tests for HNSW persistence round-trip

✅ Testing Requirements¶

All new features require tests. The project uses:

Test Categories¶

Property-Based Tests Example¶

@Property(tries = 100)
void hnswPersistenceRoundTrip(@ForAll @Size(min=10, max=1000) List<float[]> vectors) {
    // Build index, persist, reload, verify identical search results
}

🔄 Pull Request Process¶

1. Create a branch from main with appropriate naming
2. Make changes with tests
3. Ensure all tests pass — mvn test
4. Fill out the PR template
5. Link related issues — Closes #123 or Fixes #456
6. One approval required from a maintainer
7. Squash merge to keep history clean

✅ PR Checklist¶

• Code follows the project's coding standards

• Tests added/updated for the change

• Javadoc updated for public API changes

• No hardcoded secrets or credentials

• Commit messages follow Conventional Commits

• JMH benchmarks included (if performance-related)

• No circular module dependencies introduced

🐛 Reporting Issues¶

Bug Reports¶

Use the Bug Report template:

• Steps to reproduce

• Expected vs actual behavior

• JDK version and SIMD capability output

• Relevant logs or stack traces

💡 Feature Requests¶

Use the Feature Request template:

• Problem you're solving

• Proposed solution

• Alternatives considered

💬 Getting Help¶

🔗 See Also¶

• Architecture Overview — System design

• Core Concepts — Algorithms and data structures

• Performance Tuning — Benchmark methodology