ai-qakit 1.0.0

package/templates/.claude/skills/ai-multimodal/.env.example

@@ -0,0 +1,185 @@
+# Google Gemini API Configuration
+
+# ============================================================================
+# OPTION 1: Google AI Studio (Default - Recommended for most users)
+# ============================================================================
+# Get your API key: https://aistudio.google.com/apikey
+GEMINI_API_KEY=your_api_key_here
+
+# ============================================================================
+# OPTION 2: Vertex AI (Google Cloud Platform)
+# ============================================================================
+# Uncomment these lines to use Vertex AI instead of Google AI Studio
+# GEMINI_USE_VERTEX=true
+# VERTEX_PROJECT_ID=your-gcp-project-id
+# VERTEX_LOCATION=us-central1
+
+# ============================================================================
+# Model Selection (Optional)
+# ============================================================================
+# Override default models for specific capabilities
+# If not set, intelligent defaults are used based on task type
+
+# --- Image Generation ---
+# Used by: --task generate (image)
+# Default: imagen-4.0-generate-001 (auto-fallback to cheaper model if billing fails)
+# NOTE: All image generation requires billing - no free tier available (limit: 0)
+# Options:
+#   imagen-4.0-generate-001           - Standard quality, balanced (~$0.02/image, requires billing)
+#   imagen-4.0-ultra-generate-001     - Maximum quality (~$0.04/image, requires billing)
+#   imagen-4.0-fast-generate-001      - Fastest generation (~$0.01/image, requires billing)
+#   gemini-3-pro-image-preview        - Pro quality with editing (requires billing)
+#   gemini-2.5-flash-image            - Cheaper fallback (~$0.039/image, requires billing)
+#   gemini-2.5-flash-image-preview    - Preview variant (requires billing)
+# Fallback chain: Imagen 4 -> gemini-2.5-flash-image (if Imagen fails)
+# IMAGE_GEN_MODEL=imagen-4.0-generate-001
+
+# --- Video Generation ---
+# Used by: --task generate-video (new capability)
+# Default: veo-3.1-generate-preview
+# NOTE: Video generation requires billing - no free tier fallback available
+# Options:
+#   veo-3.1-generate-preview       - Latest, native audio, frame control (requires billing)
+#   veo-3.1-fast-generate-preview  - Speed-optimized for business (requires billing)
+#   veo-3.0-generate-001           - Stable, native audio, 8s videos (requires billing)
+#   veo-3.0-fast-generate-001      - Stable fast variant (requires billing)
+# VIDEO_GEN_MODEL=veo-3.1-generate-preview
+
+# --- Multimodal Analysis ---
+# Used by: --task analyze, transcribe, extract
+# Default: gemini-2.5-flash
+# Options:
+#   gemini-3-pro-preview           - Latest, agentic workflows, 1M context
+#   gemini-2.5-flash               - Best price/performance (recommended)
+#   gemini-2.5-pro                 - Highest quality
+# MULTIMODAL_MODEL=gemini-2.5-flash
+
+# --- Legacy Compatibility ---
+# Generic model override (use specific variables above instead)
+# GEMINI_MODEL=gemini-2.5-flash
+# GEMINI_IMAGE_GEN_MODEL=gemini-2.5-flash-image
+
+# ============================================================================
+# Rate Limiting Configuration (Optional)
+# ============================================================================
+# Requests per minute limit (adjust based on your tier)
+# GEMINI_RPM_LIMIT=15
+
+# Tokens per minute limit
+# GEMINI_TPM_LIMIT=4000000
+
+# Requests per day limit
+# GEMINI_RPD_LIMIT=1500
+
+# ============================================================================
+# Video Generation Options (Optional)
+# ============================================================================
+# Video duration in seconds (8s only for now)
+# VEO_DURATION=8
+
+# Video resolution: 720p or 1080p
+# VEO_RESOLUTION=1080p
+
+# Aspect ratio: 16:9, 9:16, 1:1 (16:9 is default)
+# VEO_ASPECT_RATIO=16:9
+
+# Frame rate: 24fps (fixed for now)
+# VEO_FPS=24
+
+# Enable native audio generation
+# VEO_AUDIO=true
+
+# ============================================================================
+# Image Generation Options (Optional)
+# ============================================================================
+# Number of images to generate (1-4)
+# IMAGEN_NUM_IMAGES=1
+
+# Image size: 1K or 2K (Ultra/Standard only)
+# IMAGEN_SIZE=1K
+
+# Aspect ratio: 1:1, 16:9, 9:16, 4:3, 3:4
+# IMAGEN_ASPECT_RATIO=1:1
+
+# Enable person generation (restricted in EEA, CH, UK)
+# IMAGEN_PERSON_GENERATION=true
+
+# Add SynthID watermark (always enabled by default)
+# IMAGEN_WATERMARK=true
+
+# ============================================================================
+# Processing Options (Optional)
+# ============================================================================
+# Video resolution mode: default or low-res
+# low-res uses ~100 tokens/second vs ~300 for default
+# GEMINI_VIDEO_RESOLUTION=default
+
+# Audio quality: default (16 Kbps mono, auto-downsampled)
+# GEMINI_AUDIO_QUALITY=default
+
+# PDF processing mode: inline (<20MB) or file-api (>20MB, automatic)
+# GEMINI_PDF_MODE=auto
+
+# ============================================================================
+# Retry Configuration (Optional)
+# ============================================================================
+# Maximum retry attempts for failed requests
+# GEMINI_MAX_RETRIES=3
+
+# Initial retry delay in seconds (uses exponential backoff)
+# GEMINI_RETRY_DELAY=1
+
+# ============================================================================
+# Output Configuration (Optional)
+# ============================================================================
+# Default output directory for generated images
+# OUTPUT_DIR=./output
+
+# Image output format (png or jpeg)
+# IMAGE_FORMAT=png
+
+# Image quality for JPEG (1-100)
+# IMAGE_QUALITY=95
+
+# ============================================================================
+# Context Caching (Optional)
+# ============================================================================
+# Enable context caching for repeated queries on same file
+# GEMINI_ENABLE_CACHING=true
+
+# Cache TTL in seconds (default: 1800 = 30 minutes)
+# GEMINI_CACHE_TTL=1800
+
+# ============================================================================
+# Logging (Optional)
+# ============================================================================
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# LOG_LEVEL=INFO
+
+# Log file path
+# LOG_FILE=./logs/gemini.log
+
+# ============================================================================
+# Pricing Reference (as of 2025-11)
+# ============================================================================
+# Gemini 2.5 Flash: $1.00/1M input, $0.10/1M output
+# Gemini 2.5 Pro: $3.00/1M input, $12.00/1M output
+# Gemini 3 Pro: $2.00/1M input (<200k), $4.00 (>200k), $12/$18 output
+# Imagen 4: ~$0.01-$0.04 per image (varies by variant)
+# Veo 3: TBD (preview pricing)
+# Monitor: https://ai.google.dev/pricing
+
+# ============================================================================
+# Notes
+# ============================================================================
+# 1. Never commit API keys to version control
+# 2. Add .env to .gitignore
+# 3. API keys can be restricted in Google Cloud Console
+# 4. Monitor usage at: https://aistudio.google.com/apikey
+# 5. Free tier limits: 15 RPM, 1M-4M TPM, 1,500 RPD
+# 6. Vertex AI requires GCP authentication via gcloud CLI
+# 7. New model defaults (Nov 2025):
+#    - Image gen: Imagen 4 (was Flash Image)
+#    - Video gen: Veo 3.1 (new capability)
+#    - Analysis: Gemini 2.5 Flash (unchanged)
+# 8. Preview models (veo-3.1, gemini-3) may have API changes

package/templates/.claude/skills/ai-multimodal/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ai-multimodal
+description: Process and generate multimedia content using Google Gemini API for better vision capabilities. Capabilities include analyze audio files (transcription with timestamps, summarization, speech understanding, music/sound analysis up to 9.5 hours), understand images (better image analysis than Claude models, captioning, reasoning, object detection, design extraction, OCR, visual Q&A, segmentation, handle multiple images), process videos (scene detection, Q&A, temporal analysis, YouTube URLs, up to 6 hours), extract from documents (PDF tables, forms, charts, diagrams, multi-page), generate images (text-to-image with Imagen 4, editing, composition, refinement), generate videos (text-to-video with Veo 3, 8-second clips with native audio). Use when working with audio/video files, analyzing images or screenshots (instead of default vision capabilities of Claude, only fallback to Claude's vision capabilities if needed), processing PDF documents, extracting structured data from media, creating images/videos from text prompts, or implementing multimodal AI features. Supports Gemini 3/2.5, Imagen 4, and Veo 3 models with context windows up to 2M tokens.
+license: MIT
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# AI Multimodal
+
+Process audio, images, videos, documents, and generate images/videos using Google Gemini's multimodal API.
+
+## Setup
+
+```bash
+export GEMINI_API_KEY="your-key"  # Get from https://aistudio.google.com/apikey
+pip install google-genai python-dotenv pillow
+```
+
+## Quick Start
+
+**Verify setup**: `python scripts/check_setup.py`
+**Analyze media**: `python scripts/gemini_batch_process.py --files <file> --task <analyze|transcribe|extract>`
+  - TIP: When you're asked to analyze an image, check if `gemini` command is available, then use `"<prompt to analyze image>" | gemini -y -m gemini-2.5-flash` command. If `gemini` command is not available, use `python scripts/gemini_batch_process.py --files <file> --task analyze` command.
+**Generate content**: `python scripts/gemini_batch_process.py --task <generate|generate-video> --prompt "description"`
+
+> **Stdin support**: You can pipe files directly via stdin (auto-detects PNG/JPG/PDF/WAV/MP3).
+> - `cat image.png | python scripts/gemini_batch_process.py --task analyze --prompt "Describe this"`
+> - `python scripts/gemini_batch_process.py --files image.png --task analyze` (traditional)
+
+## Models
+
+- **Image generation**: `imagen-4.0-generate-001` (standard), `imagen-4.0-ultra-generate-001` (quality), `imagen-4.0-fast-generate-001` (speed)
+- **Video generation**: `veo-3.1-generate-preview` (8s clips with audio)
+- **Analysis**: `gemini-2.5-flash` (recommended), `gemini-2.5-pro` (advanced)
+
+## Scripts
+
+- **`gemini_batch_process.py`**: CLI orchestrator for `transcribe|analyze|extract|generate|generate-video` that auto-resolves API keys, picks sensible default models per task, streams files inline vs File API, and saves structured outputs (text/JSON/CSV/markdown plus generated assets) for Imagen 4 + Veo workflows.
+- **`media_optimizer.py`**: ffmpeg/Pillow-based preflight tool that compresses/resizes/converts audio, image, and video inputs, enforces target sizes/bitrates, splits long clips into hour chunks, and batch-processes directories so media stays within Gemini limits.
+- **`document_converter.py`**: Gemini-powered converter that uploads PDFs/images/Office docs, applies a markdown-preserving prompt, batches multiple files, auto-names outputs under `docs/assets`, and exposes CLI flags for model, prompt, auto-file naming, and verbose logging.
+- **`check_setup.py`**: Interactive readiness checker that verifies directory layout, centralized env resolver, required Python deps, and GEMINI_API_KEY availability/format, then performs a live Gemini API call and prints remediation instructions if anything fails.
+
+Use `--help` for options.
+
+## References
+
+Load for detailed guidance:
+
+| Topic | File | Description |
+|-------|------|-------------|
+| Audio | `references/audio-processing.md` | Audio formats and limits, transcription (timestamps, speakers, segments), non-speech analysis, File API vs inline input, TTS models, best practices, cost and token math, and concrete meeting/podcast/interview recipes. |
+| Images | `references/vision-understanding.md` | Vision capabilities overview, supported formats and models, captioning/classification/VQA, detection and segmentation, OCR and document reading, multi-image workflows, structured JSON output, token costs, best practices, and common product/screenshot/chart/scene use cases. |
+| Image Gen | `references/image-generation.md` | Imagen 4 and Gemini image model overview, generate_images vs generate_content APIs, aspect ratios and costs, text/image/both modalities, editing and composition, style and quality control, safety settings, best practices, troubleshooting, and common marketing/concept-art/UI scenarios. |
+| Video | `references/video-analysis.md` | Video analysis capabilities and supported formats, model/context choices, local/inline/YouTube inputs, clipping and FPS control, multi-video comparison, temporal Q&A and scene detection, transcription with visual context, token and cost guidance, and optimization/best-practice patterns. |
+| Video Gen | `references/video-generation.md` | Veo model matrix, text-to-video and image-to-video quick start, multi-reference and extension flows, camera and timing control, configuration (resolution, aspect, audio, safety), prompt design patterns, performance tips, limitations, troubleshooting, and cost estimates. |
+
+## Limits
+
+**Formats**: Audio (WAV/MP3/AAC, 9.5h), Images (PNG/JPEG/WEBP, 3.6k), Video (MP4/MOV, 6h), PDF (1k pages)
+**Size**: 20MB inline, 2GB File API
+
+## Resources
+
+- [API Docs](https://ai.google.dev/gemini-api/docs/)
+- [Pricing](https://ai.google.dev/pricing)

package/templates/.claude/skills/ai-multimodal/references/audio-processing.md

@@ -0,0 +1,386 @@
+# Audio Processing Reference
+
+Comprehensive guide for audio analysis and speech generation using Gemini API.
+
+## Audio Understanding
+
+### Supported Formats
+
+| Format | MIME Type | Best Use |
+|--------|-----------|----------|
+| WAV | `audio/wav` | Uncompressed, highest quality |
+| MP3 | `audio/mp3` | Compressed, widely compatible |
+| AAC | `audio/aac` | Compressed, good quality |
+| FLAC | `audio/flac` | Lossless compression |
+| OGG Vorbis | `audio/ogg` | Open format |
+| AIFF | `audio/aiff` | Apple format |
+
+### Specifications
+
+- **Maximum length**: 9.5 hours per request
+- **Multiple files**: Unlimited count, combined max 9.5 hours
+- **Token rate**: 32 tokens/second (1 minute = 1,920 tokens)
+- **Processing**: Auto-downsampled to 16 Kbps mono
+- **File size limits**:
+  - Inline: 20 MB max total request
+  - File API: 2 GB per file, 20 GB project quota
+  - Retention: 48 hours auto-delete
+
+## Transcription
+
+### Basic Transcription
+
+```python
+from google import genai
+import os
+
+client = genai.Client(api_key=os.getenv('GEMINI_API_KEY'))
+
+# Upload audio
+myfile = client.files.upload(file='meeting.mp3')
+
+# Transcribe
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Generate a transcript of the speech.', myfile]
+)
+print(response.text)
+```
+
+### With Timestamps
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Generate transcript with timestamps in MM:SS format.', myfile]
+)
+```
+
+### Multi-Speaker Identification
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Transcribe with speaker labels. Format: [Speaker 1], [Speaker 2], etc.', myfile]
+)
+```
+
+### Segment-Specific Transcription
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Transcribe only the segment from 02:30 to 05:15.', myfile]
+)
+```
+
+## Audio Analysis
+
+### Summarization
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Summarize key points in 5 bullets with timestamps.', myfile]
+)
+```
+
+### Non-Speech Audio Analysis
+
+```python
+# Music analysis
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Identify the musical instruments and genre.', myfile]
+)
+
+# Environmental sounds
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Identify all sounds: voices, music, ambient noise.', myfile]
+)
+
+# Birdsong identification
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Identify bird species based on their calls.', myfile]
+)
+```
+
+### Timestamp-Based Analysis
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['What is discussed from 10:30 to 15:45? Provide key points.', myfile]
+)
+```
+
+## Input Methods
+
+### File Upload (>20MB or Reuse)
+
+```python
+# Upload once, use multiple times
+myfile = client.files.upload(file='large-audio.mp3')
+
+# First query
+response1 = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Transcribe this', myfile]
+)
+
+# Second query (reuses same file)
+response2 = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Summarize this', myfile]
+)
+```
+
+### Inline Data (<20MB)
+
+```python
+from google.genai import types
+
+with open('small-audio.mp3', 'rb') as f:
+    audio_bytes = f.read()
+
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=[
+        'Describe this audio',
+        types.Part.from_bytes(data=audio_bytes, mime_type='audio/mp3')
+    ]
+)
+```
+
+## Speech Generation (TTS)
+
+### Available Models
+
+| Model | Quality | Speed | Cost/1M tokens |
+|-------|---------|-------|----------------|
+| `gemini-2.5-flash-native-audio-preview-09-2025` | High | Fast | $10 |
+| `gemini-2.5-pro` TTS mode | Premium | Slower | $20 |
+
+### Basic TTS
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    contents='Generate audio: Welcome to today\'s episode.'
+)
+
+# Save audio
+with open('output.wav', 'wb') as f:
+    f.write(response.audio_data)
+```
+
+### Controllable Voice Style
+
+```python
+# Professional tone
+response = client.models.generate_content(
+    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    contents='Generate audio in a professional, clear tone: Welcome to our quarterly earnings call.'
+)
+
+# Casual and friendly
+response = client.models.generate_content(
+    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    contents='Generate audio in a friendly, conversational tone: Hey there! Let\'s dive into today\'s topic.'
+)
+
+# Narrative style
+response = client.models.generate_content(
+    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    contents='Generate audio in a narrative, storytelling tone: Once upon a time, in a land far away...'
+)
+```
+
+### Voice Control Parameters
+
+- **Style**: Professional, casual, narrative, conversational
+- **Pace**: Slow, normal, fast
+- **Tone**: Friendly, serious, enthusiastic
+- **Accent**: Natural language control (e.g., "British accent", "Southern drawl")
+
+## Best Practices
+
+### File Management
+
+1. Use File API for files >20MB
+2. Use File API for repeated queries (saves tokens)
+3. Files auto-delete after 48 hours
+4. Clean up manually when done:
+   ```python
+   client.files.delete(name=myfile.name)
+   ```
+
+### Prompt Engineering
+
+**Effective prompts**:
+- "Transcribe from 02:30 to 03:29 in MM:SS format"
+- "Identify speakers and extract dialogue with timestamps"
+- "Summarize key points with relevant timestamps"
+- "Transcribe and analyze sentiment for each speaker"
+
+**Context improves accuracy**:
+- "This is a medical interview - use appropriate terminology"
+- "Transcribe this legal deposition with precise terminology"
+- "This is a technical podcast about machine learning"
+
+**Combined tasks**:
+- "Transcribe and summarize in bullet points"
+- "Extract key quotes with timestamps and speaker labels"
+- "Transcribe and identify action items with timestamps"
+
+### Cost Optimization
+
+**Token calculation**:
+- 1 minute audio = 1,920 tokens
+- 1 hour audio = 115,200 tokens
+- 9.5 hours = 1,094,400 tokens
+
+**Model selection**:
+- Use `gemini-2.5-flash` ($1/1M tokens) for most tasks
+- Upgrade to `gemini-2.5-pro` ($3/1M tokens) for complex analysis
+- For high-volume: `gemini-1.5-flash` ($0.70/1M tokens)
+
+**Reduce costs**:
+- Process only relevant segments using timestamps
+- Use lower-quality audio when possible
+- Batch multiple short files in one request
+- Cache context for repeated queries
+
+### Error Handling
+
+```python
+import time
+
+def transcribe_with_retry(file_path, max_retries=3):
+    """Transcribe audio with exponential backoff retry"""
+    for attempt in range(max_retries):
+        try:
+            myfile = client.files.upload(file=file_path)
+            response = client.models.generate_content(
+                model='gemini-2.5-flash',
+                contents=['Transcribe with timestamps', myfile]
+            )
+            return response.text
+        except Exception as e:
+            if attempt == max_retries - 1:
+                raise
+            wait_time = 2 ** attempt
+            print(f"Retry {attempt + 1} after {wait_time}s")
+            time.sleep(wait_time)
+```
+
+## Common Use Cases
+
+### 1. Meeting Transcription
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=[
+        '''Transcribe this meeting with:
+        1. Speaker labels
+        2. Timestamps for topic changes
+        3. Action items highlighted
+        ''',
+        myfile
+    ]
+)
+```
+
+### 2. Podcast Summary
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=[
+        '''Create podcast summary with:
+        1. Main topics with timestamps
+        2. Key quotes from each speaker
+        3. Recommended episode highlights
+        ''',
+        myfile
+    ]
+)
+```
+
+### 3. Interview Analysis
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=[
+        '''Analyze interview:
+        1. Questions asked with timestamps
+        2. Key responses from interviewee
+        3. Overall sentiment and tone
+        ''',
+        myfile
+    ]
+)
+```
+
+### 4. Content Verification
+
+```python
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=[
+        '''Verify audio content:
+        1. Check for specific keywords or phrases
+        2. Identify any compliance issues
+        3. Note any concerning statements with timestamps
+        ''',
+        myfile
+    ]
+)
+```
+
+### 5. Multilingual Transcription
+
+```python
+# Gemini auto-detects language
+response = client.models.generate_content(
+    model='gemini-2.5-flash',
+    contents=['Transcribe this audio and translate to English if needed.', myfile]
+)
+```
+
+## Token Costs
+
+**Audio Input** (32 tokens/second):
+- 1 minute = 1,920 tokens
+- 10 minutes = 19,200 tokens
+- 1 hour = 115,200 tokens
+- 9.5 hours = 1,094,400 tokens
+
+**Example costs** (Gemini 2.5 Flash at $1/1M):
+- 1 hour audio: 115,200 tokens = $0.12
+- Full day podcast (8 hours): 921,600 tokens = $0.92
+
+## Limitations
+
+- Maximum 9.5 hours per request
+- Auto-downsampled to 16 Kbps mono (quality loss)
+- Files expire after 48 hours
+- No real-time streaming support
+- Non-speech audio less accurate than speech
+
+---
+
+## Related References
+
+**Current**: Audio Processing
+
+**Related Capabilities**:
+- [Video Analysis](./video-analysis.md) - Extract audio from videos
+- [Video Generation](./video-generation.md) - Generate videos with native audio
+- [Image Understanding](./vision-understanding.md) - Analyze audio with visual context
+
+**Back to**: [AI Multimodal Skill](../SKILL.md)