Bitnet

.cursor/rules/bitnet-benchmark-analysis.mdc

@@ -0,0 +1,67 @@
+---
+description: "Guidance on interpreting benchmark results and tracking regressions in the BitNet project."
+globs: pkg/bitnet/**/*.go
+alwaysApply: false
+---
+
+# Benchmark Analysis
+
+**Purpose:** Provide a clear method for interpreting benchmark outputs and monitoring performance over time.
+
+## Key Metrics
+
+1. **Ops/sec** (`b.NsPerOp()`)
+
+   * Inverse of nanoseconds per operation.
+   * Higher is better; indicates throughput.
+
+2. **Bytes/op** (`b.AllocedBytesPerOp()`)
+
+   * Average memory allocated per operation.
+   * Lower is better; fewer allocations.
+
+3. **Allocs/op** (`b.AllocsPerOp()`)
+
+   * Number of memory allocations per operation.
+   * Lower is better; indicates allocation churn.
+
+## Reading `go test -timeout 30s ./pkg/bitnet/... -bench` Output
+
+Example:
+
+```text
+BenchmarkTensor_Get-8       10000000               200 ns/op             512 B/op          4 allocs/op
+```
+
+* `200 ns/op`: average time per operation
+* `512 B/op`: bytes allocated
+* `4 allocs/op`: number of allocations
+
+## Regression Detection
+
+1. **Baseline Tracking**
+
+   * Record baseline metrics in a file (e.g., `benchmarks_baseline.md`).
+2. **Automated Comparison**
+
+   * In CI, compare current benchmark against baseline.
+   * Fail build if deviations exceed threshold:
+
+     * Time regression > 10%
+     * Allocations increase > 1 alloc/op
+3. **Historical Trends**
+
+   * Store benchmark CSV outputs across commits.
+   * Generate trend graphs (e.g., via Python scripts).
+
+## Reporting
+
+* Document anomalies in GitHub issue or PR.
+* Include before/after metrics in PR description.
+* Use benchmarks to guide optimization efforts.
+
+## Continuous Monitoring
+
+* Integrate benchmark runs in nightly builds.
+* Alert on regressions via Slack or email.
+* Review trends weekly to catch slow drift.

.cursor/rules/bitnet-benchmark-categories.mdc

@@ -0,0 +1,71 @@
+---
+description: "Define categories of benchmarks for the BitNet project to ensure focused and comparable measurements."
+globs: pkg/bitnet/**/*.go
+alwaysApply: false
+---
+
+# Benchmark Categories
+
+**Purpose:** Classify benchmarks by their semantic focus so teams can compare like with like.
+
+## 1. Creation Benchmarks
+
+Measure cost of allocating or initializing a component.
+
+```go
+func BenchmarkTensor_Create(b *testing.B) {
+  for i := 0; i < b.N; i++ {
+    NewTensor(100)
+  }
+}
+```
+
+## 2. Operation Benchmarks
+
+Measure runtime of core operations on an existing instance.
+
+```go
+func BenchmarkTensor_Get(b *testing.B) {
+  tensor := NewTensor(1000)
+  b.ResetTimer()
+  for i := 0; i < b.N; i++ {
+    tensor.Get(i % 1000)
+  }
+}
+```
+
+## 3. Composite / Sub-operation Benchmarks
+
+Combine multiple operations or simulate realistic sequences.
+
+```go
+func BenchmarkTensor_Sequential(b *testing.B) {
+  tensor := NewTensor(1000)
+  b.Run("GetSet", func(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+      tensor.Set(1.23, i%1000)
+      tensor.Get(i%1000)
+    }
+  })
+}
+```
+
+## 4. Memory & Allocation Benchmarks
+
+Measure allocations and memory footprint per operation.
+
+```go
+func BenchmarkAlloc_1024(b *testing.B) {
+  b.ReportAllocs()
+  for i := 0; i < b.N; i++ {
+    _ = make([]byte, 1024)
+  }
+}
+```
+
+## Best Practices
+
+* Single semantic focus per benchmark.
+* Use realistic sizes and patterns.
+* Report allocations with `b.ReportAllocs()`.
+* Reset timers after setup (`b.ResetTimer()`).

.cursor/rules/bitnet-benchmark-invocation.mdc

@@ -0,0 +1,53 @@
+---
+description: "Specify how to invoke and profile benchmarks in the BitNet project."
+globs: pkg/bitnet/**/*.go
+alwaysApply: false
+---
+
+# Running and Profiling Benchmarks
+
+**Purpose:** Standardize commands to execute benchmarks and collect profiling data.
+
+## Basic Benchmark Run
+
+Execute all benchmarks in the module:
+
+```bash
+go test -timeout 30s -bench=. ./pkg/bitnet/...
+```
+
+## Memory Allocation Profiling
+
+Include memory statistics per operation:
+
+```bash
+go test -timeout 30s -bench=. -benchmem ./pkg/bitnet/...
+```
+
+## CPU Profiling
+
+Generate a CPU profile for offline analysis:
+
+```bash
+go test -timeout 30s -bench=. -cpuprofile=cpu.prof ./pkg/bitnet/...
+```
+
+## Memory Profiling
+
+Produce a memory profile file:
+
+```bash
+go test -timeout 30s -bench=. -memprofile=mem.prof ./pkg/bitnet/...
+```
+
+## Profiling Visualization
+
+After generating profiles, visualize with `go tool pprof`:
+
+```bash
+# Visualize CPU profile on local web server
+go tool pprof -http=:8080 cpu.prof
+
+# Visualize memory profile
+go tool pprof -http=:8081 mem.prof
+```

.cursor/rules/bitnet-benchmarks.mdc

@@ -0,0 +1,43 @@
+---
+description: "Enforce benchmark file organization and naming conventions for the BitNet project."
+globs: pkg/bitnet/**/*.go
+alwaysApply: false
+---
+# Benchmark Naming & File Layout
+
+**Purpose:** Keep benchmarks discoverable and consistent across packages.
+
+## File placement
+- Benchmarks live alongside unit tests in `*_test.go` files under the same package.
+
+```
+pkg/bitnet/
++- mycomponent.go
++- mycomponent_test.go   # must contain both unit and benchmark tests
+```
+
+## Benchmark function names
+- Must start with `Benchmark` followed by `<Type>_<Operation>`
+- Use `_` to separate semantic units; avoid camel-case after the prefix.
+
+```go
+func BenchmarkTensor_Create(b *testing.B) { ... }
+func BenchmarkTensor_Get(b *testing.B)    { ... }
+func BenchmarkTensor_Set(b *testing.B)    { ... }
+```
+
+## Sub-benchmarks
+
+When you need multiple scenarios in one function, use `b.Run`:
+
+```go
+func BenchmarkTensor_Create(b *testing.B) {
+  for _, size := range []int{100, 1_000, 10_000} {
+    b.Run(fmt.Sprintf("%d", size), func(b *testing.B) {
+      for i := 0; i < b.N; i++ {
+        NewTensor(size)
+      }
+    })
+  }
+}
+```

.cursor/rules/bitnet-branching-strategy.mdc

@@ -0,0 +1,48 @@
+---
+description: "Define branch creation and naming conventions for the BitNet project to ensure consistent workflows."
+globs: pkg/bitnet/**
+alwaysApply: true
+---
+
+# Branching Strategy
+
+**Purpose:** Standardize branch creation to link code to issues and maintain clarity.
+
+## Base Branch
+
+* All feature branches originate from `bitnet`.
+
+## Creating a Branch
+
+* Use GitHub CLI for consistency:
+
+  ```bash
+  gh issue develop <ISSUE_NUMBER> \
+    --base bitnet \
+    --name feat/bitnet-<ISSUE_NUMBER>-<short-description> \
+    --checkout
+  ```
+
+## Naming Convention
+
+* Prefix with `feat/bitnet-` for features, `fix/bitnet-` for bug fixes.
+* Format: `{type}/bitnet-{issue_number}-{short-description}`
+
+  * Example: `feat/bitnet-173-add-tokenizer`
+
+## Listing Branches
+
+* To list branches tied to an issue:
+
+  ```bash
+  gh issue develop --list <ISSUE_NUMBER>
+  ```
+
+## Deleting After Merge
+
+* Once merged, delete local and remote branches:
+
+  ```bash
+  git branch -d feat/bitnet-173-add-tokenizer
+  gh pr close <PR_NUMBER>
+  ```

.cursor/rules/bitnet-development-process.mdc

@@ -0,0 +1,87 @@
+---
+description: "This rule describes the overall development process for the BitNet project, including coding standards, workflows, and best practices for contributors."
+globs: pkg/bitnet/**
+alwaysApply: false
+---
+# BitNet Development Process Rule
+
+This rule describes the overall development process for the BitNet project, including coding standards, workflows, and best practices for contributors.
+
+# Development Process Guidelines
+
+## Code Changes Process
+1. **Test-First Development**
+   - Write unit tests before implementation
+   - Include benchmarks for performance-critical code
+   - Document test cases and expected results
+   - Follow TDD practices
+
+2. **Testing Requirements**
+   - Run all tests in `pkg/bitnet/*`
+   - Ensure 100% test coverage for new code
+   - Verify existing tests still pass
+   - Include edge cases and error conditions
+
+3. **Performance Testing**
+   - Run benchmarks for all changes
+   - Check memory allocations
+   - Monitor CPU usage
+   - Compare against performance thresholds
+
+4. **Code Quality**
+   - Fix all linter errors
+   - Address memory allocation issues
+   - Optimize CPU-heavy operations
+   - Document optimizations
+
+## Git Workflow
+1. **Commit Guidelines**
+   - Make small, focused commits
+   - Use semantic commit messages
+   - Reference related issues/PRs
+   - Keep commits atomic
+
+2. **PR Management**
+   - Create draft PRs for work in progress
+   - Mark PRs as ready when complete
+   - Include test results in PR description
+   - Link related issues
+
+3. **Review Process**
+   - Address review comments promptly
+   - Update tests if needed
+   - Rerun benchmarks after changes
+   - Keep PR up to date
+
+## Automation
+1. **Test Automation**
+   ```bash
+   # Run all tests
+   go test -timeout 30s ./pkg/bitnet/... -v
+
+   # Run benchmarks
+   ./scripts/run_benchmarks.sh
+
+   # Check coverage
+   go test -timeout 30s ./pkg/bitnet/... -coverprofile=coverage.out
+   ```
+
+2. **Performance Checks**
+   ```bash
+   # Run memory profiling
+   go test -timeout 30s -bench=. -benchmem -memprofile=mem.prof ./pkg/bitnet/...
+
+   # Run CPU profiling
+   go test -timeout 30s -bench=. -cpuprofile=cpu.prof ./pkg/bitnet/...
+   ```
+
+## Related Files
+- [scripts/run_benchmarks.sh](mdc:scripts/run_benchmarks.sh): Benchmark automation
+- [pkg/bitnet/tensor/tensor_test.go](mdc:pkg/bitnet/tensor/tensor_test.go): Test examples
+- [.cursor/rules/bitnet-tdd.mdc](mdc:.cursor/rules/bitnet-tdd.mdc): TDD practices
+
+## Related Rules
+- [bitnet-tdd.mdc](mdc:.cursor/rules/bitnet-tdd.mdc): Test-Driven Development
+- [bitnet-performance.mdc](mdc:.cursor/rules/bitnet-performance.mdc): Performance requirements
+- [bitnet-benchmarks.mdc](mdc:.cursor/rules/bitnet-benchmarks.mdc): Benchmarking guidelines
+- [bitnet-pr-updates.mdc](mdc:.cursor/rules/bitnet-pr-updates.mdc): PR update process