Skip to content

Commit 5a2a5a1

Browse files
sbharatjoshisbharatjoshi
committed
docs: add open-source repo files (LICENSE, NOTICE, CoC, CONTRIBUTING, SECURITY, README, CI, templates)
1 parent 0ab8607 commit 5a2a5a1

14 files changed

Lines changed: 808 additions & 8 deletions

‎.github/FUNDING.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# These are supported funding model platforms
2+
3+
github: [spectrayan]

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve Spector-Search
4+
title: ''
5+
labels: 'bug'
6+
assignees: ''
7+
8+
---
9+
10+
**Describe the bug**
11+
A clear and concise description of what the bug is.
12+
13+
**To Reproduce**
14+
Steps to reproduce the behavior:
15+
1. Configure engine with '...'
16+
2. Ingest documents with '...'
17+
3. Search for '...'
18+
4. See error
19+
20+
**Expected behavior**
21+
A clear and concise description of what you expected to happen.
22+
23+
**Environment:**
24+
- OS: [e.g. Ubuntu 22.04, Windows 11, macOS 14]
25+
- JDK version: [e.g. OpenJDK 25]
26+
- SIMD capability: [e.g. S_256_BIT / AVX2]
27+
- Spector-Search version: [e.g. 0.1.0]
28+
29+
**Logs / Stack Traces**
30+
If applicable, add relevant log output or stack traces.
31+
32+
**Additional context**
33+
Add any other context about the problem here (e.g. dataset size, vector dimensions, similarity function used).

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea for Spector-Search
4+
title: ''
5+
labels: 'enhancement'
6+
assignees: ''
7+
8+
---
9+
10+
**Is your feature request related to a problem? Please describe.**
11+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12+
13+
**Describe the solution you'd like**
14+
A clear and concise description of what you want to happen.
15+
16+
**Describe alternatives you've considered**
17+
A clear and concise description of any alternative solutions or features you've considered.
18+
19+
**Module(s) affected**
20+
Which module(s) would this feature impact? (e.g. spector-core, spector-index, spector-server)
21+
22+
**Additional context**
23+
Add any other context, benchmarks, or research papers about the feature request here.

‎.github/ISSUE_TEMPLATE/performance_report.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: Performance report
3+
about: Report a performance regression or suggest an optimization
4+
title: '[PERF] '
5+
labels: 'performance'
6+
assignees: ''
7+
8+
---
9+
10+
**Describe the performance issue**
11+
What operation is slow or regressed? (e.g. HNSW search, vector ingestion, BM25 scoring)
12+
13+
**Benchmark data**
14+
Please include JMH or timing results:
15+
- **Before:** [ops/s or latency]
16+
- **After:** [ops/s or latency]
17+
- **Dataset:** [size, dimensions, similarity function]
18+
19+
**Environment:**
20+
- OS: [e.g. Ubuntu 22.04]
21+
- JDK version: [e.g. OpenJDK 25]
22+
- CPU: [e.g. Intel i9-13900K, Apple M3 Pro]
23+
- SIMD capability: [e.g. S_512_BIT / AVX-512]
24+
- RAM: [e.g. 64 GB]
25+
26+
**Proposed optimization**
27+
If you have ideas for improvement, describe them here.
28+
29+
**Additional context**
30+
Add any JMH output, flame graphs, or profiler screenshots.

‎.github/dependabot.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# To get started with Dependabot version updates, you'll need to specify which
2+
# package ecosystems to update and where the package manifests are located.
3+
version: 2
4+
updates:
5+
- package-ecosystem: "maven"
6+
directory: "/"
7+
schedule:
8+
interval: "weekly"
9+
labels:
10+
- "dependencies"
11+
open-pull-requests-limit: 10
12+
groups:
13+
jackson:
14+
patterns:
15+
- "com.fasterxml.jackson*"
16+
testing:
17+
patterns:
18+
- "org.junit*"
19+
- "org.assertj*"
20+
logging:
21+
patterns:
22+
- "org.slf4j*"
23+
- "ch.qos.logback*"
24+
25+
- package-ecosystem: "github-actions"
26+
directory: "/"
27+
schedule:
28+
interval: "weekly"
29+
labels:
30+
- "dependencies"
31+
- "ci"

‎.github/pull_request_template.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
## Description
2+
<!-- Describe your changes in detail -->
3+
<!-- Include motivation and context if it's a new feature -->
4+
5+
## Related Issue
6+
<!-- Link to the issue here: "Closes #123" -->
7+
8+
## Type of Change
9+
<!-- Check the relevant option -->
10+
- [ ] Bug fix (non-breaking change which fixes an issue)
11+
- [ ] New feature (non-breaking change which adds functionality)
12+
- [ ] Performance improvement (change that improves throughput or latency)
13+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
14+
- [ ] Documentation update
15+
16+
## Module(s) Affected
17+
<!-- Check all that apply -->
18+
- [ ] `spector-core` (SIMD kernels)
19+
- [ ] `spector-storage` (Panama storage)
20+
- [ ] `spector-index` (HNSW / BM25)
21+
- [ ] `spector-query` (query orchestration)
22+
- [ ] `spector-engine` (engine facade)
23+
- [ ] `spector-server` (REST API)
24+
- [ ] `spector-bench` (benchmarks)
25+
26+
## Checklist
27+
- [ ] My code follows the code style of this project
28+
- [ ] I have added Javadoc for all public classes/methods
29+
- [ ] I have added tests to cover my changes
30+
- [ ] All new and existing tests passed (`mvn test`)
31+
- [ ] No hardcoded secrets or credentials are included
32+
- [ ] JMH benchmark results included (if performance-related)

‎.github/workflows/ci.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
name: Build & Test (JDK ${{ matrix.java }})
13+
14+
strategy:
15+
matrix:
16+
java: [ '25' ]
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Set up JDK ${{ matrix.java }}
23+
uses: actions/setup-java@v4
24+
with:
25+
java-version: ${{ matrix.java }}
26+
distribution: 'temurin'
27+
cache: 'maven'
28+
29+
- name: Build & Test
30+
run: mvn -B clean verify --no-transfer-progress
31+
32+
- name: Upload test results
33+
if: always()
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: test-results-jdk${{ matrix.java }}
37+
path: '**/target/surefire-reports/*.xml'
38+
retention-days: 7

‎CHANGELOG.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- **spector-core:** SIMD-accelerated kernels for DotProduct, CosineSimilarity, and EuclideanDistance using Java Vector API
12+
- **spector-core:** `VectorOps` utility (magnitude, normalize, scale, add, subtract) — all SIMD-accelerated
13+
- **spector-core:** `SimilarityFunction` enum with pluggable strategy dispatch
14+
- **spector-core:** `SimdCapability` runtime ISA detection and reporting
15+
- **spector-storage:** Off-heap `InMemoryVectorStore` backed by Panama `MemorySegment` + `Arena`
16+
- **spector-storage:** File-backed `MappedVectorStore` via memory-mapped I/O
17+
- **spector-storage:** `VectorStoreLayout` for contiguous vector memory arithmetic
18+
- **spector-storage:** `DocumentStore` for metadata (title, content, tags)
19+
- **spector-index:** HNSW approximate nearest-neighbor index with multi-layer graph
20+
- **spector-index:** `NeighborQueue` bounded binary heap for candidate tracking
21+
- **spector-index:** BM25 inverted index with Okapi BM25 scoring (k1=1.2, b=0.75)
22+
- **spector-index:** `StandardAnalyzer` text pipeline (tokenize → lowercase → stop words)
23+
- **spector-query:** `ReciprocalRankFusion` for zero-config score merging
24+
- **spector-query:** `HybridSearchOrchestrator` with virtual-thread parallel fan-out
25+
- **spector-engine:** `SpectorEngine` unified facade with lifecycle management
26+
- **spector-engine:** `SpectorConfig` immutable configuration with builder-style API
27+
- **spector-server:** Javalin REST API with virtual threads (`/health`, `/api/v1/status`, `/api/v1/ingest`, `/api/v1/search`)
28+
- 212 tests across all modules, all passing
29+
30+
### Technical Decisions
31+
- Java 25 with `jdk.incubator.vector` for SIMD
32+
- `FloatVector.SPECIES_PREFERRED` for ISA-agnostic code
33+
- `ReentrantLock` everywhere (no `synchronized`) to avoid virtual thread pinning
34+
- Panama `MemorySegment` for zero-GC vector storage
35+
- `Executors.newVirtualThreadPerTaskExecutor()` for hybrid search fan-out

‎CODE_OF_CONDUCT.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
support@spectrayan.com. All complaints will be reviewed and investigated promptly
64+
and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series of
86+
actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or permanent
93+
ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within the
113+
community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
Community Impact Guidelines were inspired by
122+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123+
124+
For answers to common questions about this code of conduct, see the FAQ at
125+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126+
[https://www.contributor-covenant.org/translations][translations].
127+
128+
[homepage]: https://www.contributor-covenant.org
129+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130+
[Mozilla CoC]: https://github.com/mozilla/diversity
131+
[FAQ]: https://www.contributor-covenant.org/faq
132+
[translations]: https://www.contributor-covenant.org/translations

0 commit comments

Comments
 (0)