anvil-dev-framework 0.1.7 → 0.1.9

package/project/hooks/subagent_stop.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+
+import argparse
+import json
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+
+def get_tts_script_path():
+    """
+    Determine which TTS script to use based on availability and API keys.
+    Priority order: MLX Audio (local) > ElevenLabs > OpenAI > pyttsx3
+    """
+    # Get current script directory and construct utils/tts path
+    script_dir = Path(__file__).parent
+    tts_dir = script_dir / "utils" / "tts"
+
+    # Check for MLX Audio (highest priority - fast, free, local)
+    mlx_script = tts_dir / "mlx_audio_tts.py"
+    if mlx_script.exists():
+        return str(mlx_script)
+
+    # Check for ElevenLabs API key
+    if os.getenv('ELEVENLABS_API_KEY'):
+        elevenlabs_script = tts_dir / "elevenlabs_tts.py"
+        if elevenlabs_script.exists():
+            return str(elevenlabs_script)
+
+    # Check for OpenAI API key
+    if os.getenv('OPENAI_API_KEY'):
+        openai_script = tts_dir / "openai_tts.py"
+        if openai_script.exists():
+            return str(openai_script)
+
+    # Fall back to pyttsx3 (no API key required)
+    pyttsx3_script = tts_dir / "pyttsx3_tts.py"
+    if pyttsx3_script.exists():
+        return str(pyttsx3_script)
+
+    return None
+
+
+def is_legitimate_completion(input_data):
+    """
+    Check if this is a legitimate subagent completion vs startup cleanup.
+    Returns True if we should announce, False otherwise.
+    
+    The problem: When Claude starts, it cleans up orphaned subagents from
+    previous sessions, firing SubagentStop for each. We don't want TTS for these.
+    
+    Solution: Track session start time in a temp file. Only announce if the
+    subagent completed AFTER the current session started (with buffer).
+    """
+    import time
+    import tempfile
+    
+    # Must have an agent_id to be a real subagent
+    agent_id = input_data.get('agent_id', '')
+    if not agent_id:
+        return False
+    
+    session_id = input_data.get('session_id', '')
+    if not session_id:
+        return False
+    
+    # Track session start time using a temp file
+    session_marker = Path(tempfile.gettempdir()) / f".claude_session_{session_id}"
+    
+    if not session_marker.exists():
+        # First SubagentStop for this session - create marker with current time
+        # This is likely startup cleanup, so don't announce
+        session_marker.write_text(str(time.time()))
+        return False
+    
+    try:
+        # Session marker exists - check how long since session started
+        session_start = float(session_marker.read_text().strip())
+        session_age = time.time() - session_start
+        
+        # If session just started (within 10 seconds), this is likely cleanup
+        if session_age < 10:
+            return False
+        
+        # Session has been running for a while - this is a real completion
+        # Verify the agent transcript exists and has content
+        transcript_path = input_data.get('agent_transcript_path', '')
+        if transcript_path and os.path.exists(transcript_path):
+            file_size = os.path.getsize(transcript_path)
+            if file_size > 500:
+                return True
+                
+    except (ValueError, OSError):
+        pass
+    
+    return False
+
+
+def announce_subagent_completion():
+    """Announce subagent completion using the best available TTS service."""
+    try:
+        tts_script = get_tts_script_path()
+        if not tts_script:
+            return  # No TTS scripts available
+
+        # Use fixed message for subagent completion
+        completion_message = "Subagent Complete"
+
+        # Call the TTS script with the completion message
+        subprocess.run([
+            "uv", "run", tts_script, completion_message
+        ],
+        capture_output=True,  # Suppress output
+        timeout=10  # 10-second timeout
+        )
+
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, FileNotFoundError):
+        # Fail silently if TTS encounters issues
+        pass
+    except Exception:
+        # Fail silently for any other errors
+        pass
+
+
+def main():
+    try:
+        # Parse command line arguments
+        parser = argparse.ArgumentParser()
+        parser.add_argument('--chat', action='store_true', help='Copy transcript to chat.json')
+        parser.add_argument('--announce', action='store_true', help='Announce completion via TTS')
+        args = parser.parse_args()
+
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+
+        # Extract required fields
+        input_data.get("session_id", "")
+        input_data.get("stop_hook_active", False)
+
+        # Ensure log directory exists
+        log_dir = os.path.join(os.getcwd(), "logs")
+        os.makedirs(log_dir, exist_ok=True)
+        log_path = os.path.join(log_dir, "subagent_stop.json")
+
+        # Read existing log data or initialize empty list
+        if os.path.exists(log_path):
+            with open(log_path, 'r') as f:
+                try:
+                    log_data = json.load(f)
+                except (json.JSONDecodeError, ValueError):
+                    log_data = []
+        else:
+            log_data = []
+
+        # Append new data
+        log_data.append(input_data)
+
+        # Write back to file with formatting
+        with open(log_path, 'w') as f:
+            json.dump(log_data, f, indent=2)
+
+        # Handle --chat switch (same as stop.py)
+        if args.chat and 'transcript_path' in input_data:
+            transcript_path = input_data['transcript_path']
+            if os.path.exists(transcript_path):
+                # Read .jsonl file and convert to JSON array
+                chat_data = []
+                try:
+                    with open(transcript_path, 'r') as f:
+                        for line in f:
+                            line = line.strip()
+                            if line:
+                                try:
+                                    chat_data.append(json.loads(line))
+                                except json.JSONDecodeError:
+                                    pass  # Skip invalid lines
+
+                    # Write to logs/chat.json
+                    chat_file = os.path.join(log_dir, 'chat.json')
+                    with open(chat_file, 'w') as f:
+                        json.dump(chat_data, f, indent=2)
+                except Exception:
+                    pass  # Fail silently
+
+        # Announce subagent completion via TTS
+        # Only announce if --announce flag is explicitly set
+        # Note: post_tool_use.py already handles Task tool completion announcements
+        if args.announce:
+            announce_subagent_completion()
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/project/hooks/user_prompt_submit.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+
+def log_user_prompt(session_id, input_data):
+    """Log user prompt to logs directory."""
+    # Ensure logs directory exists
+    log_dir = Path("logs")
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / 'user_prompt_submit.json'
+
+    # Read existing log data or initialize empty list
+    if log_file.exists():
+        with open(log_file, 'r') as f:
+            try:
+                log_data = json.load(f)
+            except (json.JSONDecodeError, ValueError):
+                log_data = []
+    else:
+        log_data = []
+
+    # Append the entire input data
+    log_data.append(input_data)
+
+    # Write back to file with formatting
+    with open(log_file, 'w') as f:
+        json.dump(log_data, f, indent=2)
+
+
+def validate_prompt(prompt):
+    """
+    Validate the user prompt for security or policy violations.
+    Returns tuple (is_valid, reason).
+    """
+    # Example validation rules (customize as needed)
+    blocked_patterns = [
+        # Add any patterns you want to block
+        # Example: ('rm -rf /', 'Dangerous command detected'),
+    ]
+
+    prompt_lower = prompt.lower()
+
+    for pattern, reason in blocked_patterns:
+        if pattern.lower() in prompt_lower:
+            return False, reason
+
+    return True, None
+
+
+def main():
+    try:
+        # Parse command line arguments
+        parser = argparse.ArgumentParser()
+        parser.add_argument('--validate', action='store_true',
+                          help='Enable prompt validation')
+        parser.add_argument('--log-only', action='store_true',
+                          help='Only log prompts, no validation or blocking')
+        args = parser.parse_args()
+
+        # Read JSON input from stdin
+        input_data = json.loads(sys.stdin.read())
+
+        # Extract session_id and prompt
+        session_id = input_data.get('session_id', 'unknown')
+        prompt = input_data.get('prompt', '')
+
+        # Log the user prompt
+        log_user_prompt(session_id, input_data)
+
+        # Validate prompt if requested and not in log-only mode
+        if args.validate and not args.log_only:
+            is_valid, reason = validate_prompt(prompt)
+            if not is_valid:
+                # Exit code 2 blocks the prompt with error message
+                print(f"Prompt blocked: {reason}", file=sys.stderr)
+                sys.exit(2)
+
+        # Add context information (optional)
+        # You can print additional context that will be added to the prompt
+        # Example: print(f"Current time: {datetime.now()}")
+
+        # Success - prompt will be processed
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/project/hooks/utils/llm/anth.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "anthropic",
+#     "python-dotenv",
+# ]
+# ///
+
+import os
+import sys
+from dotenv import load_dotenv
+
+
+def prompt_llm(prompt_text):
+    """
+    Base Anthropic LLM prompting method using fastest model.
+
+    Args:
+        prompt_text (str): The prompt to send to the model
+
+    Returns:
+        str: The model's response text, or None if error
+    """
+    load_dotenv()
+
+    api_key = os.getenv("ANTHROPIC_API_KEY")
+    if not api_key:
+        return None
+
+    try:
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=api_key)
+
+        message = client.messages.create(
+            model="claude-3-5-haiku-20241022",  # Fastest Anthropic model
+            max_tokens=100,
+            temperature=0.7,
+            messages=[{"role": "user", "content": prompt_text}],
+        )
+
+        return message.content[0].text.strip()
+
+    except Exception:
+        return None
+
+
+def generate_completion_message():
+    """
+    Generate a completion message using Anthropic LLM.
+
+    Returns:
+        str: A natural language completion message, or None if error
+    """
+    engineer_name = os.getenv("ENGINEER_NAME", "").strip()
+
+    if engineer_name:
+        name_instruction = f"Sometimes (about 30% of the time) include the engineer's name '{engineer_name}' in a natural way."
+        examples = f"""Examples of the style:
+- Standard: "Work complete!", "All done!", "Task finished!", "Ready for your next move!"
+- Personalized: "{engineer_name}, all set!", "Ready for you, {engineer_name}!", "Complete, {engineer_name}!", "{engineer_name}, we're done!" """
+    else:
+        name_instruction = ""
+        examples = """Examples of the style: "Work complete!", "All done!", "Task finished!", "Ready for your next move!" """
+
+    prompt = f"""Generate a short, friendly completion message for when an AI coding assistant finishes a task.
+
+Requirements:
+- Keep it under 10 words
+- Make it positive and future focused
+- Use natural, conversational language
+- Focus on completion/readiness
+- Do NOT include quotes, formatting, or explanations
+- Return ONLY the completion message text
+{name_instruction}
+
+{examples}
+
+Generate ONE completion message:"""
+
+    response = prompt_llm(prompt)
+
+    # Clean up response - remove quotes and extra formatting
+    if response:
+        response = response.strip().strip('"').strip("'").strip()
+        # Take first line if multiple lines
+        response = response.split("\n")[0].strip()
+
+    return response
+
+
+def main():
+    """Command line interface for testing."""
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--completion":
+            message = generate_completion_message()
+            if message:
+                print(message)
+            else:
+                print("Error generating completion message")
+        else:
+            prompt_text = " ".join(sys.argv[1:])
+            response = prompt_llm(prompt_text)
+            if response:
+                print(response)
+            else:
+                print("Error calling Anthropic API")
+    else:
+        print("Usage: ./anth.py 'your prompt here' or ./anth.py --completion")
+
+
+if __name__ == "__main__":
+    main()

package/project/hooks/utils/llm/oai.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "openai",
+#     "python-dotenv",
+# ]
+# ///
+
+import os
+import sys
+from dotenv import load_dotenv
+
+
+def prompt_llm(prompt_text):
+    """
+    Base OpenAI LLM prompting method using fastest model.
+
+    Args:
+        prompt_text (str): The prompt to send to the model
+
+    Returns:
+        str: The model's response text, or None if error
+    """
+    load_dotenv()
+
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        return None
+
+    try:
+        from openai import OpenAI
+
+        client = OpenAI(api_key=api_key)
+
+        response = client.chat.completions.create(
+            model="gpt-4.1-nano",  # Fastest OpenAI model
+            messages=[{"role": "user", "content": prompt_text}],
+            max_tokens=100,
+            temperature=0.7,
+        )
+
+        return response.choices[0].message.content.strip()
+
+    except Exception:
+        return None
+
+
+def generate_completion_message():
+    """
+    Generate a completion message using OpenAI LLM.
+
+    Returns:
+        str: A natural language completion message, or None if error
+    """
+    engineer_name = os.getenv("ENGINEER_NAME", "").strip()
+
+    if engineer_name:
+        name_instruction = f"Sometimes (about 30% of the time) include the engineer's name '{engineer_name}' in a natural way."
+        examples = f"""Examples of the style:
+- Standard: "Work complete!", "All done!", "Task finished!", "Ready for your next move!"
+- Personalized: "{engineer_name}, all set!", "Ready for you, {engineer_name}!", "Complete, {engineer_name}!", "{engineer_name}, we're done!" """
+    else:
+        name_instruction = ""
+        examples = """Examples of the style: "Work complete!", "All done!", "Task finished!", "Ready for your next move!" """
+
+    prompt = f"""Generate a short, friendly completion message for when an AI coding assistant finishes a task.
+
+Requirements:
+- Keep it under 10 words
+- Make it positive and future focused
+- Use natural, conversational language
+- Focus on completion/readiness
+- Do NOT include quotes, formatting, or explanations
+- Return ONLY the completion message text
+{name_instruction}
+
+{examples}
+
+Generate ONE completion message:"""
+
+    response = prompt_llm(prompt)
+
+    # Clean up response - remove quotes and extra formatting
+    if response:
+        response = response.strip().strip('"').strip("'").strip()
+        # Take first line if multiple lines
+        response = response.split("\n")[0].strip()
+
+    return response
+
+
+def main():
+    """Command line interface for testing."""
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--completion":
+            message = generate_completion_message()
+            if message:
+                print(message)
+            else:
+                print("Error generating completion message")
+        else:
+            prompt_text = " ".join(sys.argv[1:])
+            response = prompt_llm(prompt_text)
+            if response:
+                print(response)
+            else:
+                print("Error calling OpenAI API")
+    else:
+        print("Usage: ./oai.py 'your prompt here' or ./oai.py --completion")
+
+
+if __name__ == "__main__":
+    main()

package/project/hooks/utils/tts/elevenlabs_tts.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env -S uv run --script --python 3.12
+# /// script
+# requires-python = ">=3.8,<3.14"
+# dependencies = [
+#     "elevenlabs",
+#     "python-dotenv",
+# ]
+# ///
+
+"""
+ElevenLabs TTS Script - Fast, high-quality text-to-speech.
+
+Usage:
+    uv run elevenlabs_tts.py "Your text here"
+"""
+
+import os
+import sys
+import tempfile
+import subprocess
+from dotenv import load_dotenv
+
+
+def main():
+    # Load from current dir and home dir
+    load_dotenv()
+    load_dotenv(os.path.expanduser("~/.env"))
+
+    api_key = os.getenv('ELEVENLABS_API_KEY')
+    if not api_key:
+        sys.exit(1)
+
+    try:
+        from elevenlabs.client import ElevenLabs
+
+        client = ElevenLabs(api_key=api_key)
+
+        # Get text from command line or use default
+        text = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else "Task complete"
+
+        # Generate audio
+        audio = client.text_to_speech.convert(
+            text=text,
+            voice_id="CwhRBWXzGAHq8TQ4Fs17",  # Roger - Laid-Back, Casual
+            model_id="eleven_turbo_v2_5",
+            output_format="mp3_44100_128",
+        )
+
+        # Save to temp file and play with afplay (macOS)
+        with tempfile.NamedTemporaryFile(suffix='.mp3', delete=False) as f:
+            for chunk in audio:
+                f.write(chunk)
+            temp_path = f.name
+
+        subprocess.run(['afplay', temp_path], check=True, capture_output=True)
+        os.unlink(temp_path)
+
+    except Exception:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/project/hooks/utils/tts/mlx_audio_tts.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env -S uv run --script --python 3.12
+# /// script
+# requires-python = ">=3.11,<3.14"
+# dependencies = [
+#     "mlx-audio",
+#     "soundfile",
+#     "scipy",
+#     "numpy",
+#     "sounddevice",
+#     "loguru",
+#     "misaki[en]",
+#     "spacy",
+#     "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
+# ]
+# ///
+
+"""
+MLX Audio TTS - Fast local text-to-speech for Apple Silicon.
+
+Uses Kokoro-82M model via MLX framework for native Metal acceleration.
+First run downloads ~330MB model to ~/.cache/huggingface/
+
+Usage:
+    uv run mlx_audio_tts.py "Task complete"
+    uv run mlx_audio_tts.py --voice af_heart "Hello world"
+    uv run mlx_audio_tts.py --speed 1.2 "Subagent complete"
+"""
+
+import sys
+import os
+import subprocess
+import tempfile
+import argparse
+import glob
+
+
+def speak(text: str, voice: str = "af_heart", speed: float = 1.1):
+    """Generate and play speech using MLX Audio with Kokoro."""
+    try:
+        from mlx_audio.tts.generate import generate_audio
+
+        # Create unique prefix for audio output
+        with tempfile.NamedTemporaryFile(suffix='.wav', delete=True) as f:
+            output_prefix = f.name.replace('.wav', '')
+
+        # Generate audio (library adds _000.wav, _001.wav, etc.)
+        generate_audio(
+            text=text,
+            model_path="prince-canuma/Kokoro-82M",
+            voice=voice,
+            speed=speed,
+            audio_format="wav",
+            file_prefix=output_prefix
+        )
+
+        # Find generated audio file (library adds segment suffix like _000)
+        audio_files = glob.glob(f"{output_prefix}*.wav")
+
+        if audio_files:
+            audio_file = audio_files[0]  # Use first segment
+            if os.path.getsize(audio_file) > 0:
+                subprocess.run(['afplay', audio_file], capture_output=True, timeout=10)
+            # Clean up all generated segments
+            for f in audio_files:
+                os.unlink(f)
+        else:
+            sys.exit(1)
+
+    except ImportError:
+        sys.exit(1)
+    except Exception:
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="MLX Audio TTS for Apple Silicon")
+    parser.add_argument("text", nargs="?", default="Task complete", help="Text to speak")
+    parser.add_argument("--voice", default="af_heart", help="Voice to use (default: af_heart)")
+    parser.add_argument("--speed", type=float, default=1.1, help="Speech speed (default: 1.1)")
+
+    args = parser.parse_args()
+    speak(args.text, args.voice, args.speed)
+
+
+if __name__ == "__main__":
+    main()