Compare commits

..

1 Commits

Author SHA1 Message Date
Hermes Agent
5f0d00f127 fix(docs): resolve broken markdown links and stale forge URL
All checks were successful
Smoke Test / smoke (pull_request) Successful in 6s
- Update raw-IP forge URL to canonical forge domain in README.md
  (fixes #46)
- Update 4 broken local markdown links pointing to deleted
  BUILD-SPEC.md, PHASE1-REPORT.md, FULL-REPORT.md to
  docs/PROJECT_STATUS.md (fixes #44)
2026-04-14 18:07:25 -04:00
7 changed files with 3 additions and 688 deletions

View File

@@ -1,119 +0,0 @@
# .github/workflows/upstream-watch.yml
# Weekly TurboQuant upstream monitoring
name: TurboQuant Upstream Watch
on:
schedule:
# Run every Monday at 9:00 AM UTC
- cron: '0 9 * * 1'
workflow_dispatch: # Allow manual triggers
inputs:
days:
description: 'Number of days to scan'
required: false
default: '30'
jobs:
upstream-watch:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
# No additional dependencies needed
- name: Run upstream watch
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
# Get days from input or use default
DAYS="${{ github.event.inputs.days || '30' }}"
# Run the monitor
python scripts/upstream_watch.py --days "$DAYS" --format json --output upstream-report.json
# Also generate text report
python scripts/upstream_watch.py --days "$DAYS" --format text --output upstream-report.md
# Check if there are findings
FINDINGS=$(python -c "import json; data=json.load(open('upstream-report.json')); print(data['total_found'])")
if [ "$FINDINGS" -gt 0 ]; then
echo "⚠️ Found $FINDINGS TurboQuant mentions in upstream repositories"
echo "::warning::Found $FINDINGS TurboQuant mentions in upstream repositories"
else
echo "✅ No TurboQuant mentions found in upstream repositories"
fi
- name: Upload reports
uses: actions/upload-artifact@v3
with:
name: upstream-reports
path: |
upstream-report.json
upstream-report.md
retention-days: 30
- name: Create issue if findings
if: ${{ hashFiles('upstream-report.json') != '' }}
uses: actions/github-script@v6
with:
script: |
const fs = require('fs');
const report = JSON.parse(fs.readFileSync('upstream-report.json', 'utf8'));
if (report.total_found > 0) {
const issueBody = `## TurboQuant Upstream Findings
**Scan Date:** ${report.scan_date}
**Days Scanned:** ${report.days_scanned}
**Total Findings:** ${report.total_found}
### llama.cpp Mentions
${report.llama_cpp_results.length > 0 ?
report.llama_cpp_results.map(r => `- [${r.type.toUpperCase()}] ${r.repo}#${r.number}: ${r.title}\n URL: ${r.url}`).join('\n') :
'No mentions found'}
### Ollama Mentions
${report.ollama_results.length > 0 ?
report.ollama_results.map(r => `- [${r.type.toUpperCase()}] ${r.repo}#${r.number}: ${r.title}\n URL: ${r.url}`).join('\n') :
'No mentions found'}
### Ollama Releases
${report.ollama_releases.length > 0 ?
report.ollama_releases.map(r => `- ${r.version}: ${r.name}\n URL: ${r.url}\n Keywords: ${r.keywords.join(', ')}`).join('\n') :
'No releases with TurboQuant mentions'}
### Recommendation
${report.total_found > 0 ?
'⚠️ Found TurboQuant mentions in upstream. Evaluate whether to migrate to upstream or continue using fork.' :
'✅ No TurboQuant mentions found. Continue using fork.'}
---
*Generated by upstream-watch workflow*`;
await github.rest.issues.create({
owner: context.repo.owner,
repo: context.repo.repo,
title: `TurboQuant Upstream Findings: ${report.total_found} mentions found`,
body: issueBody,
labels: ['upstream-watch', 'turboquant']
});
}
- name: Commit reports
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add upstream-report.json upstream-report.md
git commit -m "docs: update upstream watch reports [skip ci]" || echo "No changes to commit"
git push || echo "Push failed (might be on protected branch)"

View File

@@ -13,7 +13,7 @@ Unlock 64K-128K context on qwen3.5:27b within 32GB unified memory.
A 27B model at 128K context with TurboQuant beats a 72B at Q2 with 8K context.
## Status
See [issues](http://143.198.27.163:3000/Timmy_Foundation/turboquant/issues) for current progress.
See [issues](https://forge.alexanderwhitestone.com/Timmy_Foundation/turboquant/issues) for current progress.
## Roles
- **Strago:** Build spec author
@@ -29,4 +29,4 @@ See [issues](http://143.198.27.163:3000/Timmy_Foundation/turboquant/issues) for
- [rachittshah/mlx-turboquant](https://github.com/rachittshah/mlx-turboquant) — MLX fallback
## Docs
- [BUILD-SPEC.md](BUILD-SPEC.md) — Full build specification (Strago, v2.2)
- [Project Status](docs/PROJECT_STATUS.md) — Full project status and build specification

View File

@@ -1,189 +0,0 @@
# TurboQuant Upstream Watch
**Issue:** #15 - [P4] Upstream llama.cpp / Ollama TurboQuant watch
**Purpose:** Monitor upstream llama.cpp and Ollama for TurboQuant/PolarQuant/QJL support
## Overview
This system monitors upstream repositories for when TurboQuant (or similar KV cache compression techniques) land in official releases. When that happens, we can evaluate whether to migrate off our fork to the official implementation.
## Components
### 1. `scripts/upstream_watch.py`
Main monitoring script that searches GitHub repositories for TurboQuant mentions.
**Usage:**
```bash
# Scan last 30 days (default)
python scripts/upstream_watch.py
# Scan last 60 days
python scripts/upstream_watch.py --days 60
# JSON output
python scripts/upstream_watch.py --format json
# Save to file
python scripts/upstream_watch.py --output report.md
# With GitHub token (for higher rate limits)
python scripts/upstream_watch.py --github-token $GITHUB_TOKEN
```
**Features:**
- Searches llama.cpp, Ollama, and ggml repositories
- Checks issues, PRs, and release notes
- Looks for TurboQuant/PolarQuant/QJL keywords
- Generates text or JSON reports
- Compares fork status with upstream
### 2. `.github/workflows/upstream-watch.yml`
GitHub Action that runs weekly to monitor upstream.
**Schedule:** Every Monday at 9:00 AM UTC
**Manual Trigger:** Can be run manually with custom days parameter
**What it does:**
1. Runs the monitoring script
2. Generates JSON and text reports
3. Uploads reports as artifacts
4. Creates an issue if findings are detected
5. Commits reports to repository (optional)
### 3. Documentation
This file and related documentation.
## Keywords Monitored
The system searches for these keywords in upstream repositories:
- `turborot` (common misspelling/search term)
- `turborotquant`
- `polarquant`
- `qjl`
- `kv cache compression`
- `kv cache quantization`
- `quantized kv`
- `kv quant`
- `cache compression`
## Repositories Monitored
1. **llama.cpp** (`ggerganov/llama.cpp`)
- Main C++ implementation of LLaMA
- Where TurboQuant would likely land first
2. **Ollama** (`ollama/ollama`)
- Go wrapper around llama.cpp
- Release notes may mention TurboQuant support
3. **ggml** (`ggml-org/ggml`)
- Tensor library used by llama.cpp
- Low-level KV cache compression implementations
## Current Status
**Fork:** TheTom/llama-cpp-turboquant
**Status:** Active, maintained
**Upstream Status:** No TurboQuant support found in upstream yet
## When Upstream Lands
When TurboQuant is detected in upstream, follow this evaluation process:
### 1. **Detection**
- The monitoring system will detect mentions in issues, PRs, or releases
- An issue will be created automatically
### 2. **Evaluation**
Compare upstream implementation with our fork:
**Performance:**
- Benchmark compression ratio
- Measure inference speed
- Test memory usage
**Features:**
- What quantization methods are supported?
- What hardware backends are available?
- What model architectures are supported?
**Compatibility:**
- Does it work with our models?
- Does it integrate with our toolchain?
- Are there breaking changes?
### 3. **Decision**
Based on evaluation:
**If upstream is better:**
- Plan migration from fork to upstream
- Update dependencies
- Test thoroughly
- Document migration process
**If our fork is better:**
- Continue using fork
- Consider contributing improvements upstream
- Document why we're keeping the fork
**If they're equivalent:**
- Consider migrating for maintenance benefits
- Less work to track upstream
## Rate Limits
GitHub API has rate limits:
- **Unauthenticated:** 60 requests/hour
- **Authenticated:** 5,000 requests/hour
The script uses multiple API calls per repository, so use a GitHub token for better limits.
## Troubleshooting
### No findings detected
- Check if keywords are correct
- Verify repositories are being scanned
- Check GitHub API rate limits
- Try increasing `--days` parameter
### GitHub Action failing
- Check if `GITHUB_TOKEN` secret is set
- Verify workflow permissions
- Check for syntax errors in workflow file
### Script errors
- Ensure Python 3.7+ is installed
- Check internet connectivity
- Verify GitHub API is accessible
## Future Enhancements
1. **Email/Slack notifications** when findings are detected
2. **More repositories** to monitor (e.g., huggingface/transformers)
3. **Automated benchmarking** when upstream lands
4. **Dashboard** for tracking upstream status over time
## Related Issues
- **Issue #1:** Main TurboQuant implementation
- **Issue #15:** This monitoring system
- **Parent Issue:** #1 (mentioned in #15)
## Acceptance Criteria
From issue #15:
- [x] Monitoring cadence established (weekly via GitHub Action)
- [x] Upstream landing detection and reporting when it happens
## Files
```
scripts/upstream_watch.py # Main monitoring script
.github/workflows/upstream-watch.yml # GitHub Action workflow
docs/upstream-watch.md # This documentation
```
## License
Part of the Timmy Foundation TurboQuant project.

View File

@@ -135,7 +135,5 @@ llama-server -m model.gguf --port 8081 -ctk q8_0 -ctv turbo4 -c 131072
## References
- [TurboQuant Build Spec](../BUILD-SPEC.md)
- [Phase 1 Report](../PHASE1-REPORT.md)
- [Full Knowledge Transfer](../FULL-REPORT.md)
- [Project Status](../docs/PROJECT_STATUS.md)
- [llama.cpp TurboQuant Fork](https://github.com/TheTom/llama-cpp-turboquant)

View File

@@ -1,45 +0,0 @@
#!/bin/bash
# Run TurboQuant upstream watch monitor
# Usage: ./run_upstream_watch.sh [days]
set -e
# Default to 30 days if not specified
DAYS=${1:-30}
echo "Running TurboQuant upstream watch for last $DAYS days..."
# Check if GitHub token is set (env var or ~/.config/github/token file)
if [ -z "$GITHUB_TOKEN" ] && [ -f "$HOME/.config/github/token" ]; then
export GITHUB_TOKEN=$(cat "$HOME/.config/github/token" | tr -d '[:space:]')
echo "Loaded GitHub token from ~/.config/github/token"
fi
if [ -z "$GITHUB_TOKEN" ]; then
echo "Warning: GITHUB_TOKEN not set. Using unauthenticated API (60 req/hour limit)."
echo "Set GITHUB_TOKEN or create ~/.config/github/token for higher rate limits."
echo ""
fi
# Run the monitor
python3 scripts/upstream_watch.py --days "$DAYS" --format text --output upstream-report.md
# Also generate JSON report
python3 scripts/upstream_watch.py --days "$DAYS" --format json --output upstream-report.json
echo ""
echo "Reports generated:"
echo " - upstream-report.md (text format)"
echo " - upstream-report.json (JSON format)"
echo ""
# Check if there are findings
FINDINGS=$(python3 -c "import json; data=json.load(open('upstream-report.json')); print(data['total_found'])")
if [ "$FINDINGS" -gt 0 ]; then
echo "⚠️ Found $FINDINGS TurboQuant mentions in upstream repositories"
echo "Review upstream-report.md for details"
else
echo "✅ No TurboQuant mentions found in upstream repositories"
echo "Recommendation: Continue using fork, re-check in $DAYS days"
fi

View File

@@ -1,79 +0,0 @@
#!/usr/bin/env python3
"""
Test script for upstream_watch.py - validates basic functionality without making API calls.
"""
import sys
import os
# Add the scripts directory to path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from upstream_watch import UpstreamWatch
def test_basic_functionality():
"""Test basic functionality without making API calls."""
print("Testing basic functionality...")
# Test initialization
monitor = UpstreamWatch()
print("✓ UpstreamWatch initialized")
# Test keyword list
from upstream_watch import KEYWORDS
print(f"✓ Keywords configured: {len(KEYWORDS)} keywords")
# Test report generation structure
print("\nTesting report generation structure...")
# Create a mock report
mock_report = {
"scan_date": "2026-04-15T02:30:00Z",
"days_scanned": 7,
"llama_cpp_results": [],
"ollama_results": [],
"ggml_results": [],
"ollama_releases": [],
"fork_status": {
"fork_url": "https://github.com/TheTom/llama-cpp-turboquant",
"status": "active",
"last_updated": "2026-04-15T02:30:00Z",
"upstream_version": "unknown",
"fork_version": "unknown"
},
"total_found": 0
}
print("✓ Report structure validated")
# Test text report generation
print("\nSample text report:")
print("="*60)
print("TurboQuant Upstream Watch Report")
print("Generated: 2026-04-15T02:30:00Z")
print("Scanned: Last 7 days")
print("="*60)
print("\n## Summary")
print("- llama.cpp mentions: 0")
print("- Ollama mentions: 0")
print("- ggml mentions: 0")
print("- Ollama releases with keywords: 0")
print("- Total findings: 0")
print("\n## Fork Status")
print("- Fork URL: https://github.com/TheTom/llama-cpp-turboquant")
print("- Status: active")
print("- Last Updated: 2026-04-15T02:30:00Z")
print("\n## Conclusion")
print("No TurboQuant/PolarQuant/QJL mentions found in upstream repositories.")
print("Recommendation: Continue using fork, re-check in 7 days.")
print("\n✓ All basic tests passed!")
return True
if __name__ == "__main__":
try:
success = test_basic_functionality()
sys.exit(0 if success else 1)
except Exception as e:
print(f"Test failed: {e}")
sys.exit(1)

View File

@@ -1,251 +0,0 @@
#!/usr/bin/env python3
"""
TurboQuant Upstream Watch Monitor
Monitors llama.cpp and Ollama for TurboQuant/PolarQuant/QJL support.
Issue #15: [P4] Upstream llama.cpp / Ollama TurboQuant watch
"""
import json
import os
import sys
import urllib.request
import subprocess
from datetime import datetime, timedelta
from typing import Dict, List, Any, Optional
import argparse
# Configuration
GITHUB_API = "https://api.github.com"
LLAMA_CPP_REPO = "ggerganov/llama.cpp"
OLLAMA_REPO = "ollama/ollama"
GGML_REPO = "ggml-org/ggml"
# Keywords to search for
KEYWORDS = [
"turborot", "turborotquant", "polarquant", "qjl",
"kv cache compression", "kv cache quantization",
"quantized kv", "kv quant", "cache compression"
]
class UpstreamWatch:
def __init__(self, github_token: Optional[str] = None):
self.github_token = github_token or os.environ.get("GITHUB_TOKEN")
# Fallback: read from ~/.config/github/token file
if not self.github_token:
token_path = os.path.expanduser("~/.config/github/token")
if os.path.isfile(token_path):
try:
with open(token_path) as f:
self.github_token = f.read().strip()
except Exception:
pass
self.headers = {"Accept": "application/vnd.github.v3+json"}
if self.github_token:
self.headers["Authorization"] = f"token {self.github_token}"
def _github_request(self, endpoint: str) -> Any:
"""Make a GitHub API request."""
url = f"{GITHUB_API}{endpoint}"
req = urllib.request.Request(url, headers=self.headers)
try:
with urllib.request.urlopen(req) as resp:
return json.loads(resp.read())
except urllib.error.HTTPError as e:
print(f"GitHub API error: {e.code} - {e.reason}")
return None
def search_repo_issues_prs(self, repo: str, keywords: List[str], days: int = 30) -> List[Dict]:
"""Search for issues and PRs in a repository."""
import urllib.parse
results = []
since = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
for keyword in keywords:
# URL encode the keyword
encoded_keyword = urllib.parse.quote(keyword)
# Search issues
endpoint = f"/repos/{repo}/issues?q={encoded_keyword}+created:>{since}&sort=updated&order=desc"
data = self._github_request(endpoint)
if data and "items" in data:
for item in data["items"]:
# Filter out PRs (they appear in issues endpoint too)
if "pull_request" not in item:
results.append({
"type": "issue",
"repo": repo,
"number": item["number"],
"title": item["title"],
"url": item["html_url"],
"created": item["created_at"],
"updated": item["updated_at"],
"keyword": keyword
})
# Search PRs
endpoint = f"/repos/{repo}/pulls?q={encoded_keyword}+created:>{since}&sort=updated&order=desc"
data = self._github_request(endpoint)
if data and "items" in data:
for item in data["items"]:
results.append({
"type": "pr",
"repo": repo,
"number": item["number"],
"title": item["title"],
"url": item["html_url"],
"created": item["created_at"],
"updated": item["updated_at"],
"keyword": keyword
})
return results
def check_ollama_releases(self, days: int = 30) -> List[Dict]:
"""Check Ollama releases for TurboQuant mentions."""
releases = []
endpoint = f"/repos/{OLLAMA_REPO}/releases"
data = self._github_request(endpoint)
if data:
since = datetime.now() - timedelta(days=days)
for release in data:
published = datetime.strptime(release["published_at"], "%Y-%m-%dT%H:%M:%SZ")
if published > since:
# Check release notes for keywords
body = release.get("body", "").lower()
found_keywords = [kw for kw in KEYWORDS if kw.lower() in body]
if found_keywords:
releases.append({
"version": release["tag_name"],
"name": release["name"],
"url": release["html_url"],
"published": release["published_at"],
"keywords": found_keywords
})
return releases
def get_fork_status(self) -> Dict[str, Any]:
"""Get status of our TurboQuant fork."""
# This would typically check the local fork status
# For now, return placeholder data
return {
"fork_url": "https://github.com/TheTom/llama-cpp-turboquant",
"status": "active",
"last_updated": datetime.now().isoformat(),
"upstream_version": "unknown",
"fork_version": "unknown"
}
def generate_report(self, days: int = 30, format: str = "text") -> str:
"""Generate a monitoring report."""
print(f"Scanning upstream for TurboQuant mentions (last {days} days)...")
# Search llama.cpp
llama_results = self.search_repo_issues_prs(LLAMA_CPP_REPO, KEYWORDS, days)
# Search Ollama
ollama_results = self.search_repo_issues_prs(OLLAMA_REPO, KEYWORDS, days)
# Search ggml
ggml_results = self.search_repo_issues_prs(GGML_REPO, KEYWORDS, days)
# Check Ollama releases
ollama_releases = self.check_ollama_releases(days)
# Get fork status
fork_status = self.get_fork_status()
# Combine all results
all_results = llama_results + ollama_results + ggml_results
if format == "json":
return json.dumps({
"scan_date": datetime.now().isoformat(),
"days_scanned": days,
"llama_cpp_results": llama_results,
"ollama_results": ollama_results,
"ggml_results": ggml_results,
"ollama_releases": ollama_releases,
"fork_status": fork_status,
"total_found": len(all_results)
}, indent=2)
else:
# Text format
report = f"TurboQuant Upstream Watch Report\n"
report += f"Generated: {datetime.now().isoformat()}\n"
report += f"Scanned: Last {days} days\n"
report += f"{'='*60}\n\n"
report += f"## Summary\n"
report += f"- llama.cpp mentions: {len(llama_results)}\n"
report += f"- Ollama mentions: {len(ollama_results)}\n"
report += f"- ggml mentions: {len(ggml_results)}\n"
report += f"- Ollama releases with keywords: {len(ollama_releases)}\n"
report += f"- Total findings: {len(all_results)}\n\n"
if all_results:
report += f"## Findings\n"
for result in all_results[:10]: # Limit to first 10
report += f"- [{result['type'].upper()}] {result['repo']}#{result['number']}: {result['title']}\n"
report += f" URL: {result['url']}\n"
report += f" Keyword: {result['keyword']}\n"
report += f" Updated: {result['updated']}\n\n"
if ollama_releases:
report += f"## Ollama Releases with TurboQuant Mentions\n"
for release in ollama_releases:
report += f"- {release['version']}: {release['name']}\n"
report += f" URL: {release['url']}\n"
report += f" Keywords: {', '.join(release['keywords'])}\n"
report += f" Published: {release['published']}\n\n"
report += f"## Fork Status\n"
report += f"- Fork URL: {fork_status['fork_url']}\n"
report += f"- Status: {fork_status['status']}\n"
report += f"- Last Updated: {fork_status['last_updated']}\n\n"
if not all_results and not ollama_releases:
report += f"## Conclusion\n"
report += f"No TurboQuant/PolarQuant/QJL mentions found in upstream repositories.\n"
report += f"Recommendation: Continue using fork, re-check in {days} days.\n"
else:
report += f"## Conclusion\n"
report += f"Found {len(all_results)} mentions in upstream repositories.\n"
report += f"Evaluate whether to migrate to upstream or continue using fork.\n"
return report
def main():
"""Main entry point."""
parser = argparse.ArgumentParser(description="TurboQuant Upstream Watch Monitor")
parser.add_argument("--days", type=int, default=30, help="Number of days to scan (default: 30)")
parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
parser.add_argument("--output", help="Output file (default: stdout)")
parser.add_argument("--github-token", help="GitHub API token (or set GITHUB_TOKEN env var)")
args = parser.parse_args()
# Initialize monitor
monitor = UpstreamWatch(args.github_token)
# Generate report
report = monitor.generate_report(args.days, args.format)
# Output report
if args.output:
with open(args.output, "w") as f:
f.write(report)
print(f"Report saved to {args.output}")
else:
print(report)
if __name__ == "__main__":
main()