codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/pipecat-friday-agent/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pipecat-friday-agent
+description: "Build a low-latency, Iron Man-inspired tactical voice assistant (F.R.I.D.A.Y.) using Pipecat, Gemini, and OpenAI."
+category: voice-agents
+risk: safe
+source: community
+date_added: "2026-03-10"
+tags: [pipecat, voice, gemini, openai, python]
+tools: [pipecat]
+---
+
+# Pipecat Friday Agent
+
+## Overview
+
+This skill provides a blueprint for building **F.R.I.D.A.Y.** (Replacement Integrated Digital Assistant Youth), a local voice assistant inspired by the tactical AI from the Iron Man films. It uses the **Pipecat** framework to orchestrate a low-latency pipeline:
+- **STT**: OpenAI Whisper (`whisper-1`) or `gpt-4o-transcribe`
+- **LLM**: Google Gemini 2.5 Flash (via a compatibility shim)
+- **TTS**: OpenAI TTS (`nova` voice)
+- **Transport**: Local Audio (Hardware Mic/Speakers)
+
+## When to Use This Skill
+
+- Use when you want to build a real-time, conversational voice agent.
+- Use when working with the Pipecat framework for pipeline-based AI.
+- Use when you need to integrate multiple providers (Google and OpenAI) into a single voice loop.
+- Use when building Iron Man-themed or tactical-themed voice applications.
+
+## How It Works
+
+### Step 1: Install Dependencies
+
+You will need the Pipecat framework and its service providers installed:
+```bash
+pip install pipecat-ai[openai,google,silero] python-dotenv
+```
+
+### Step 2: Configure Environment
+
+Create a `.env` file with your API keys:
+```env
+OPENAI_API_KEY=your_openai_key
+GOOGLE_API_KEY=your_google_key
+```
+
+### Step 3: Run the Agent
+
+Execute the provided Python script to start the interface:
+```bash
+python scripts/friday_agent.py
+```
+
+## Core Concepts
+
+### Pipeline Architecture
+The agent follows a linear pipeline: `Mic -> VAD -> STT -> LLM -> TTS -> Speaker`. This allows for granular control over each stage, unlike end-to-end speech-to-speech models.
+
+### Google Compatibility Shim
+Since Google's Gemini API has a different message format than OpenAI's standard (which Pipecat aggregators expect), the script includes a `GoogleSafeContext` and `GoogleSafeMessage` class to bridge the gap.
+
+## Best Practices
+
+- ✅ **Use Silero VAD**: It is robust for local hardware and prevents background noise from triggering the LLM.
+- ✅ **Concise Prompts**: Tactical agents should give short, data-dense responses to minimize latency.
+- ✅ **Sample Rate Match**: OpenAI TTS outputs at 24kHz; ensure your `audio_out_sample_rate` matches to avoid high-pitched or slowed audio.
+- ❌ **No Polite Fillers**: Avoid "Hello, how can I help you today?" Instead, use "Systems nominal. Ready for commands."
+
+## Troubleshooting
+
+- **Problem:** Audio is choppy or delayed.
+  - **Solution:** Check your `OUTPUT_DEVICE` index. Run a script like `test_audio_output.py` to find the correct hardware index for your OS.
+- **Problem:** "Validation error" for message format.
+  - **Solution:** Ensure the `GoogleSafeContext` shim is correctly translating OpenAI-style dicts to Gemini-style schema.
+
+## Related Skills
+
+- `@voice-agents` - General principles of voice AI.
+- `@agent-tool-builder` - Add tools (Search, Lights, etc.) to your Friday agent.
+- `@llm-architect` - Optimizing the LLM layer.

package/templates/.agent/skills/pipecat-friday-agent/scripts/friday_agent.py

@@ -0,0 +1,146 @@
+import asyncio
+import os
+import sys
+from dotenv import load_dotenv
+
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.runner import PipelineRunner
+from pipecat.pipeline.task import PipelineTask, PipelineParams
+from pipecat.services.openai.stt import OpenAISTTService
+from pipecat.services.openai.tts import OpenAITTSService
+from pipecat.services.google.llm import GoogleLLMService
+from pipecat.processors.aggregators.llm_response import LLMUserContextAggregator, LLMAssistantContextAggregator
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.transports.local.audio import LocalAudioTransport, LocalAudioTransportParams
+
+# ── Config ────────────────────────────────────────────────────────────────────
+# run test_audio_output.py to find your device index
+# [4]  Speaker (Realtek)              Windows default speakers
+# [6]  Headphones (soundcore Space One)  Bluetooth headphones
+OUTPUT_DEVICE  = 6
+
+# "whisper-1" (classic) or "gpt-4o-transcribe" (GPT-4o powered, higher accuracy)
+WHISPER_MODEL  = "whisper-1"
+
+# OpenAI TTS voice — alloy, ash, coral, echo, fable, nova, onyx, sage, shimmer
+# "nova" is calm and professional; "shimmer" is warm; "onyx" is deep
+TTS_VOICE      = "nova"
+
+# ── Google compatibility shim ─────────────────────────────────────────────────
+# Pipecat's context aggregators use OpenAI-style {role, content} messages,
+# but GoogleLLMService expects {role, parts: [{text}]}.
+# These wrapper classes handle that translation.
+class GoogleSafeMessage(dict):
+    def __init__(self, role, content):
+        super().__init__(role=role, content=content)
+        self.role = role
+        self.content = content
+    def to_json_dict(self):
+        return {"role": self.role, "parts": [{"text": self.content}]}
+
+class GoogleSafeContext:
+    def __init__(self, messages=None):
+        self.messages = [GoogleSafeMessage(m['role'], m['content']) for m in messages] if messages else []
+        self.tools = []
+        self.tool_choice = None
+    def add_message(self, message):
+        if isinstance(message, dict):
+            self.messages.append(GoogleSafeMessage(message.get("role", "user"), message.get("content", "")))
+        elif hasattr(message, "text"):
+            self.messages.append(GoogleSafeMessage("user", message.text))
+    def get_messages(self, *args, **kwargs): return self.messages
+    def get_messages_for_token_count(self): return self.messages
+    def clear(self): self.messages = []
+
+# ─────────────────────────────────────────────────────────────────────────────
+load_dotenv()
+
+async def main():
+    print("\n" + "="*60)
+    print("🛡️  F.R.I.D.A.Y. — FULL OPENAI EDITION")
+    print(f"   STT: OpenAI {WHISPER_MODEL}")
+    print("   LLM: Gemini 2.5 Flash")
+    print(f"   TTS: OpenAI TTS ({TTS_VOICE})")
+    print("="*60)
+
+    # ── API key check ─────────────────────────────────────────────────────────
+    openai_key  = os.getenv("OPENAI_API_KEY")
+    google_key  = os.getenv("GOOGLE_API_KEY")
+
+    if not openai_key:  print("❌ OPENAI_API_KEY missing in .env");  sys.exit(1)
+    if not google_key:  print("❌ GOOGLE_API_KEY missing in .env");   sys.exit(1)
+    print("✅ All API keys loaded\n")
+
+    # ── 1. Transport ──────────────────────────────────────────────────────────
+    transport = LocalAudioTransport(
+        params=LocalAudioTransportParams(
+            audio_in_enabled=True,
+            audio_out_enabled=True,
+            audio_in_sample_rate=16000,
+            audio_out_sample_rate=24000,   # OpenAI TTS only outputs 24kHz
+            output_device_index=OUTPUT_DEVICE,
+            vad_enabled=True,
+            vad_analyzer=SileroVADAnalyzer(),
+            vad_audio_passthrough=True,
+        )
+    )
+
+    # ── 2. STT — OpenAI Whisper ───────────────────────────────────────────────
+    # Whisper receives the full audio segment (after VAD detects silence)
+    # and returns a transcript. No streaming — waits for the full utterance.
+    stt = OpenAISTTService(
+        api_key=openai_key,
+        model=WHISPER_MODEL,
+    )
+
+    # ── 3. LLM — Gemini 2.5 Flash ────────────────────────────────────────────
+    llm = GoogleLLMService(
+        api_key=google_key,
+        model="gemini-2.5-flash",
+    )
+
+    # ── 4. TTS — OpenAI TTS ──────────────────────────────────────────────────
+    # OpenAI TTS streams audio at 24kHz PCM. Change TTS_VOICE at the top of the file.
+    tts = OpenAITTSService(
+        api_key=openai_key,
+        voice=TTS_VOICE,
+        model="gpt-4o-mini-tts",
+        sample_rate=24000,
+    )
+
+    # ── 5. Personality ────────────────────────────────────────────────────────
+    system_prompt = (
+        "You are F.R.I.D.A.Y., a tactical support AI replacing JARVIS. "
+        "Address me as 'Boss'. "
+        "Be concise, soft-spoken, and focus on situational awareness. "
+        "Prioritize clear data over polite formalities. "
+        "If asked about status, report 'Systems nominal'."
+    )
+    context      = GoogleSafeContext([{"role": "system", "content": system_prompt}])
+    user_agg     = LLMUserContextAggregator(context)
+    assistant_agg = LLMAssistantContextAggregator(context)
+
+    # ── 6. Pipeline ───────────────────────────────────────────────────────────
+    # Mic → VAD → Whisper STT → LLM → ElevenLabs TTS → Speaker
+    pipeline = Pipeline([
+        transport.input(),   # mic audio
+        stt,                 # Whisper: audio → transcript
+        user_agg,            # add transcript to context
+        llm,                 # Gemini: context → response
+        tts,                 # ElevenLabs: text → speech
+        transport.output(),  # speaker
+        assistant_agg,       # store response in context
+    ])
+
+    task   = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=True))
+    runner = PipelineRunner()
+
+    print("🎤 Ready. Speak after silence — Whisper transcribes on each pause.")
+    print("   Press Ctrl+C to stop.\n")
+    await runner.run(task)
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\n👋 Systems offline.")

package/templates/.agent/skills/postgresql-optimization/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: postgresql-optimization
+description: "PostgreSQL database optimization workflow for query tuning, indexing strategies, performance analysis, and production database management."
+category: granular-workflow-bundle
+risk: safe
+source: personal
+date_added: "2026-02-27"
+---
+
+# PostgreSQL Optimization Workflow
+
+## Overview
+
+Specialized workflow for PostgreSQL database optimization including query tuning, indexing strategies, performance analysis, vacuum management, and production database administration.
+
+## When to Use This Workflow
+
+Use this workflow when:
+- Optimizing slow PostgreSQL queries
+- Designing indexing strategies
+- Analyzing database performance
+- Tuning PostgreSQL configuration
+- Managing production databases
+
+## Workflow Phases
+
+### Phase 1: Performance Assessment
+
+#### Skills to Invoke
+- `database-optimizer` - Database optimization
+- `postgres-best-practices` - PostgreSQL best practices
+
+#### Actions
+1. Check database version
+2. Review configuration
+3. Analyze slow queries
+4. Check resource usage
+5. Identify bottlenecks
+
+#### Copy-Paste Prompts
+```
+Use @database-optimizer to assess PostgreSQL performance
+```
+
+### Phase 2: Query Analysis
+
+#### Skills to Invoke
+- `sql-optimization-patterns` - SQL optimization
+- `postgres-best-practices` - PostgreSQL patterns
+
+#### Actions
+1. Run EXPLAIN ANALYZE
+2. Identify scan types
+3. Check join strategies
+4. Analyze execution time
+5. Find optimization opportunities
+
+#### Copy-Paste Prompts
+```
+Use @sql-optimization-patterns to analyze and optimize queries
+```
+
+### Phase 3: Indexing Strategy
+
+#### Skills to Invoke
+- `database-design` - Index design
+- `postgresql` - PostgreSQL indexing
+
+#### Actions
+1. Identify missing indexes
+2. Create B-tree indexes
+3. Add composite indexes
+4. Consider partial indexes
+5. Review index usage
+
+#### Copy-Paste Prompts
+```
+Use @database-design to design PostgreSQL indexing strategy
+```
+
+### Phase 4: Query Optimization
+
+#### Skills to Invoke
+- `sql-optimization-patterns` - Query tuning
+- `sql-pro` - SQL expertise
+
+#### Actions
+1. Rewrite inefficient queries
+2. Optimize joins
+3. Add CTEs where helpful
+4. Implement pagination
+5. Test improvements
+
+#### Copy-Paste Prompts
+```
+Use @sql-optimization-patterns to optimize SQL queries
+```
+
+### Phase 5: Configuration Tuning
+
+#### Skills to Invoke
+- `postgres-best-practices` - Configuration
+- `database-admin` - Database administration
+
+#### Actions
+1. Tune shared_buffers
+2. Configure work_mem
+3. Set effective_cache_size
+4. Adjust checkpoint settings
+5. Configure autovacuum
+
+#### Copy-Paste Prompts
+```
+Use @postgres-best-practices to tune PostgreSQL configuration
+```
+
+### Phase 6: Maintenance
+
+#### Skills to Invoke
+- `database-admin` - Database maintenance
+- `postgresql` - PostgreSQL maintenance
+
+#### Actions
+1. Schedule VACUUM
+2. Run ANALYZE
+3. Check table bloat
+4. Monitor autovacuum
+5. Review statistics
+
+#### Copy-Paste Prompts
+```
+Use @database-admin to schedule PostgreSQL maintenance
+```
+
+### Phase 7: Monitoring
+
+#### Skills to Invoke
+- `grafana-dashboards` - Monitoring dashboards
+- `prometheus-configuration` - Metrics collection
+
+#### Actions
+1. Set up monitoring
+2. Create dashboards
+3. Configure alerts
+4. Track key metrics
+5. Review trends
+
+#### Copy-Paste Prompts
+```
+Use @grafana-dashboards to create PostgreSQL monitoring
+```
+
+## Optimization Checklist
+
+- [ ] Slow queries identified
+- [ ] Indexes optimized
+- [ ] Configuration tuned
+- [ ] Maintenance scheduled
+- [ ] Monitoring active
+- [ ] Performance improved
+
+## Quality Gates
+
+- [ ] Query performance improved
+- [ ] Indexes effective
+- [ ] Configuration optimized
+- [ ] Maintenance automated
+- [ ] Monitoring in place
+
+## Related Workflow Bundles
+
+- `database` - Database operations
+- `cloud-devops` - Infrastructure
+- `performance-optimization` - Performance