Merge pull request #70 from Annotation-Garden/develop

Release v0.6.4: User ID caching and telemetry infrastructure

Author: neuromechanist

.github/workflows/publish.yml

@@ -1,6 +1,9 @@
 name: Publish to PyPI
 
 on:
+  push:
+    tags:
+      - 'v*'
   release:
     types: [published]
   workflow_dispatch:
@@ -71,7 +74,8 @@ jobs:
     name: Publish to PyPI
     needs: build
     runs-on: ubuntu-latest
-    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi != 'true')
+    # Publish on: tag push, release published, or manual dispatch (unless test_pypi is true)
+    if: github.event_name == 'push' || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi != 'true')
     environment:
       name: pypi
       url: https://pypi.org/p/hedit

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hedit"
-version = "0.6.3a3"
+version = "0.6.4a0"
 description = "Multi-agent system for HED annotation generation and validation"
 readme = "PKG_README.md"
 requires-python = ">=3.12"

src/api/main.py

@@ -5,6 +5,7 @@
 """
 
 import asyncio
+import hashlib
 import json
 import os
 import time
@@ -48,6 +49,26 @@
 _byok_config: dict = {}
 
 
+def _derive_user_id(api_key: str) -> str:
+    """Derive a stable user ID from API key for cache optimization.
+
+    Uses SHA-256 hash of the API key to create an anonymous identifier.
+    Each unique API key gets its own cache lane in OpenRouter.
+
+    Note: This is NOT password hashing. The API key is already a strong secret.
+    We use SHA-256 for fast, consistent ID derivation (not security).
+    Purpose: Enable cache routing, not protect secrets.
+
+    Args:
+        api_key: OpenRouter API key (already a secret, not a password)
+
+    Returns:
+        16-character hexadecimal user ID
+    """
+    # CodeQL [py/weak-cryptographic-algorithm]: Not password hashing - deriving cache ID from API key
+    return hashlib.sha256(api_key.encode()).hexdigest()[:16]
+
+
 def create_byok_workflow(
     openrouter_key: str,
     model: str | None = None,
@@ -101,24 +122,30 @@ def create_byok_workflow(
     evaluation_model = get_model_name(model if model else default_evaluation_model)
     assessment_model = get_model_name(model if model else default_assessment_model)
 
+    # Derive user ID for cache optimization (each API key gets own cache lane)
+    user_id = _derive_user_id(openrouter_key)
+
     # Create LLMs with user's key and settings
     annotation_llm = create_openrouter_llm(
         model=annotation_model,
         api_key=openrouter_key,
         temperature=llm_temperature,
         provider=provider_preference,
+        user_id=user_id,
     )
     evaluation_llm = create_openrouter_llm(
         model=evaluation_model,
         api_key=openrouter_key,
         temperature=llm_temperature,
         provider=provider_preference,
+        user_id=user_id,
     )
     assessment_llm = create_openrouter_llm(
         model=assessment_model,
         api_key=openrouter_key,
         temperature=llm_temperature,
         provider=provider_preference,
+        user_id=user_id,
     )
 
     # Create and return workflow
@@ -167,11 +194,15 @@ def create_byok_vision_agent(
     else:
         actual_provider = default_vision_provider
 
+    # Derive user ID for cache optimization
+    user_id = _derive_user_id(openrouter_key)
+
     vision_llm = create_openrouter_llm(
         model=actual_model,
         api_key=openrouter_key,
         temperature=actual_temperature,
         provider=actual_provider,
+        user_id=user_id,
     )
 
     return VisionAgent(llm=vision_llm)

src/cli/config.py

@@ -5,6 +5,7 @@
 """
 
 import os
+import uuid
 from pathlib import Path
 from typing import Any
 
@@ -25,6 +26,8 @@
 
 CONFIG_FILE = CONFIG_DIR / "config.yaml"
 CREDENTIALS_FILE = CONFIG_DIR / "credentials.yaml"
+MACHINE_ID_FILE = CONFIG_DIR / "machine_id"
+FIRST_RUN_FILE = CONFIG_DIR / ".first_run"
 
 # Default API endpoint
 DEFAULT_API_URL = "https://api.annotation.garden/hedit"
@@ -82,6 +85,16 @@ class APIConfig(BaseModel):
     url: str = Field(default=DEFAULT_API_URL, description="API endpoint URL")
 
 
+class TelemetryConfig(BaseModel):
+    """Telemetry configuration."""
+
+    enabled: bool = Field(default=True, description="Enable telemetry collection")
+    model_blacklist: list[str] = Field(
+        default_factory=lambda: [DEFAULT_MODEL],
+        description="Models to exclude from telemetry",
+    )
+
+
 class CLIConfig(BaseModel):
     """Complete CLI configuration."""
 
@@ -90,6 +103,7 @@ class CLIConfig(BaseModel):
     settings: SettingsConfig = Field(default_factory=SettingsConfig)
     output: OutputConfig = Field(default_factory=OutputConfig)
     execution: ExecutionMode = Field(default_factory=ExecutionMode)
+    telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig)
 
 
 def ensure_config_dir() -> None:
@@ -279,10 +293,68 @@ def clear_credentials() -> None:
         CREDENTIALS_FILE.unlink()
 
 
+def get_machine_id() -> str:
+    """Get or generate a stable machine ID for cache optimization.
+
+    This ID is used by OpenRouter for sticky cache routing to reduce costs.
+    It is NOT used for telemetry and is never transmitted except to OpenRouter.
+
+    The ID is generated once and persists across pip updates.
+
+    Returns:
+        16-character hexadecimal machine ID
+    """
+    ensure_config_dir()
+
+    if MACHINE_ID_FILE.exists():
+        try:
+            machine_id = MACHINE_ID_FILE.read_text().strip()
+            # Validate format (16 hex chars)
+            if len(machine_id) == 16 and all(c in "0123456789abcdef" for c in machine_id):
+                return machine_id
+        except (OSError, UnicodeDecodeError):
+            pass  # File corrupted, regenerate
+
+    # Generate new machine ID
+    machine_id = uuid.uuid4().hex[:16]
+
+    # Save to file
+    try:
+        MACHINE_ID_FILE.write_text(machine_id)
+        # Readable by user only (Unix)
+        try:
+            os.chmod(MACHINE_ID_FILE, 0o600)
+        except (OSError, AttributeError):
+            pass  # Windows doesn't support chmod the same way
+    except OSError:
+        pass  # If we can't write, still return the ID for this session
+
+    return machine_id
+
+
+def is_first_run() -> bool:
+    """Check if this is the first time HEDit is run.
+
+    Returns:
+        True if first run, False otherwise
+    """
+    return not FIRST_RUN_FILE.exists()
+
+
+def mark_first_run_complete() -> None:
+    """Mark first run as complete by creating the marker file."""
+    ensure_config_dir()
+    try:
+        FIRST_RUN_FILE.touch()
+    except OSError:
+        pass  # Ignore write errors
+
+
 def get_config_paths() -> dict[str, Path]:
     """Get paths to config files for debugging."""
     return {
         "config_dir": CONFIG_DIR,
         "config_file": CONFIG_FILE,
         "credentials_file": CREDENTIALS_FILE,
+        "machine_id_file": MACHINE_ID_FILE,
     }

src/cli/local_executor.py

@@ -135,14 +135,19 @@ def _get_workflow(self) -> HedAnnotationWorkflow:
             self._ensure_api_key()
 
             from src.agents.workflow import HedAnnotationWorkflow
+            from src.cli.config import get_machine_id
             from src.utils.openrouter_llm import create_openrouter_llm
 
+            # Get machine ID for cache optimization
+            user_id = get_machine_id()
+
             # Create LLMs with user's key
             annotation_llm = create_openrouter_llm(
                 model=self._model,
                 api_key=self._api_key,
                 temperature=self._temperature,
                 provider=self._provider,
+                user_id=user_id,
             )
 
             # Use same settings for all agents in standalone mode
@@ -164,13 +169,18 @@ def _get_vision_agent(self) -> VisionAgent:
             self._ensure_api_key()
 
             from src.agents.vision_agent import VisionAgent
+            from src.cli.config import get_machine_id
             from src.utils.openrouter_llm import create_openrouter_llm
 
+            # Get machine ID for cache optimization
+            user_id = get_machine_id()
+
             vision_llm = create_openrouter_llm(
                 model=self._vision_model,
                 api_key=self._api_key,
                 temperature=0.3,  # Slightly higher for vision tasks
                 provider=self._provider,
+                user_id=user_id,
             )
 
             self._vision_agent = VisionAgent(llm=vision_llm)

src/cli/main.py

@@ -21,8 +21,10 @@
     clear_credentials,
     get_config_paths,
     get_effective_config,
+    is_first_run,
     load_config,
     load_credentials,
+    mark_first_run_complete,
     save_config,
     save_credentials,
     update_config,
@@ -72,7 +74,7 @@
     typer.Option(
         "--output",
         "-o",
-        help="Output format",
+        help="Output format: 'text' (human-readable) or 'json' (machine-readable)",
     ),
 ]
 
@@ -274,6 +276,11 @@ def init(
         hedit init --api-key YOUR_KEY           # API mode (default)
         hedit init --api-key YOUR_KEY --standalone  # Standalone mode
     """
+    # Show telemetry disclosure on first run
+    if is_first_run():
+        show_telemetry_disclosure()
+        mark_first_run_complete()
+
     # Load existing config
     config = load_config()
     creds = load_credentials()
@@ -377,6 +384,11 @@ def annotate(
         hedit annotate "..." --model gpt-4o-mini --temperature 0.2
         hedit annotate "..." --standalone  # Run locally
     """
+    # Show telemetry disclosure on first run
+    if is_first_run():
+        show_telemetry_disclosure()
+        mark_first_run_complete()
+
     # Determine mode override
     mode_override = None
     if standalone:
@@ -476,6 +488,11 @@ def annotate_image(
         hedit annotate-image screen.png -o json > result.json
         hedit annotate-image stimulus.png --standalone  # Run locally
     """
+    # Show telemetry disclosure on first run
+    if is_first_run():
+        show_telemetry_disclosure()
+        mark_first_run_complete()
+
     # Validate image exists
     if not image.exists():
         output.print_error(f"Image file not found: {image}")
@@ -555,6 +572,11 @@ def validate(
         hedit validate "Event" -o json
         hedit validate "Event" --standalone  # Validate locally with hedtools
     """
+    # Show telemetry disclosure on first run
+    if is_first_run():
+        show_telemetry_disclosure()
+        mark_first_run_complete()
+
     # Determine mode override
     mode_override = None
     if standalone:
@@ -744,6 +766,36 @@ def health(
         raise typer.Exit(1) from None
 
 
+def show_telemetry_disclosure() -> None:
+    """Display first-run telemetry disclosure notice."""
+    from rich.panel import Panel
+
+    disclosure_text = (
+        "[bold]Welcome to HEDit![/]\n\n"
+        "HEDit collects anonymous usage data to improve the annotation service:\n"
+        "  • Input descriptions and generated annotations\n"
+        "  • Model performance metrics (latency, iterations)\n"
+        "  • Validation results\n\n"
+        "[dim]What is NOT collected:[/]\n"
+        "  • API keys or credentials\n"
+        "  • Personal information\n"
+        "  • File paths or system details\n\n"
+        "[bold cyan]To disable:[/] hedit config set telemetry.enabled false\n"
+        "[bold cyan]To view config:[/] hedit config show"
+    )
+
+    panel = Panel(
+        disclosure_text,
+        title="[bold]Privacy & Data Collection[/]",
+        border_style="cyan",
+        padding=(1, 2),
+    )
+
+    console.print()
+    console.print(panel)
+    console.print()
+
+
 def cli() -> None:
     """Entry point for CLI."""
     app()

src/telemetry/__init__.py

@@ -0,0 +1,17 @@
+"""Telemetry module for HEDit.
+
+Provides opt-out telemetry collection for service improvement and model fine-tuning.
+"""
+
+from src.telemetry.collector import DEFAULT_MODEL_BLACKLIST, TelemetryCollector
+from src.telemetry.schema import TelemetryEvent
+from src.telemetry.storage import CloudflareKVStorage, LocalFileStorage, TelemetryStorage
+
+__all__ = [
+    "TelemetryEvent",
+    "TelemetryCollector",
+    "TelemetryStorage",
+    "LocalFileStorage",
+    "CloudflareKVStorage",
+    "DEFAULT_MODEL_BLACKLIST",
+]