appydave-tools 0.15.0 → 0.16.0

data/docs/tools/name-manager.md

@@ -0,0 +1,322 @@
+# Name Manager
+
+Parse and generate project names following AppyDave naming conventions and channel codes.
+
+## What It Does
+
+**Name Manager** handles project naming and parsing:
+
+- Parses project names following AppyDave conventions
+- Generates standardized project names
+- Extracts sequence numbers, channel codes, and project descriptors
+- Validates names against configured channels
+- Enforces naming consistency across projects
+
+## Naming Convention
+
+AppyDave project names follow this pattern:
+
+```
+{sequence}-{channel-code}-{project-name}
+```
+
+**Examples**:
+- `b60-appydave-intro-to-system-design`
+  - Sequence: `b60`
+  - Channel: `appydave`
+  - Project: `intro-to-system-design`
+
+- `b61-aitldr-ai-graphics-basics`
+  - Sequence: `b61`
+  - Channel: `aitldr`
+  - Project: `ai-graphics-basics`
+
+- `50-quick-tip`
+  - Sequence: `50`
+  - Channel: (none - uses default)
+  - Project: `quick-tip`
+
+## How to Use
+
+### Parse Project Name
+
+```ruby
+require 'appydave/tools'
+
+# Parse a project filename
+project = Appydave::Tools::NameManager::ProjectName.new('b60-appydave-intro-to-coding.md')
+
+project.sequence              # => "b60"
+project.channel_code          # => "appydave"
+project.project_name          # => "intro-to-coding"
+project.generate_name         # => "b60-appydave-intro-to-coding"
+```
+
+### Generate Project Name
+
+```ruby
+require 'appydave/tools'
+
+project = Appydave::Tools::NameManager::ProjectName.new('b60-appydave-intro-to-coding.md')
+
+# Set new values
+project.sequence = 'b75'
+project.project_name = 'advanced-system-design'
+
+# Generate updated name
+new_name = project.generate_name
+# => "b75-appydave-advanced-system-design"
+```
+
+### Set Channel Code
+
+```ruby
+require 'appydave/tools'
+
+project = Appydave::Tools::NameManager::ProjectName.new('b60-intro-to-coding.md')
+
+# Set channel code (validates against configured channels)
+project.channel_code = 'appydave'
+
+project.generate_name
+# => "b60-appydave-intro-to-coding"
+```
+
+## Use Cases for AI Agents
+
+### 1. Project Inventory Generation
+```ruby
+# AI parses all project files
+projects = Dir.glob('**/*.md').map do |file|
+  Appydave::Tools::NameManager::ProjectName.new(file)
+end
+
+# Generates inventory with sequence, channel, project name
+projects.each do |p|
+  puts "#{p.sequence} (#{p.channel_code}): #{p.project_name}"
+end
+```
+**AI discovers**: Project structure, naming patterns, distribution across channels. Can generate comprehensive inventory.
+
+### 2. Channel Migration
+```ruby
+# AI renames projects when moving between channels
+# From appydave to aitldr
+project = Appydave::Tools::NameManager::ProjectName.new('b60-appydave-old-project.md')
+project.channel_code = 'aitldr'
+new_name = project.generate_name
+# => "b60-aitldr-old-project"
+```
+**AI discovers**: Channel organization. Can systematically rename projects during migrations.
+
+### 3. Sequence Number Management
+```ruby
+# AI analyzes sequence numbers
+# Identifies gaps, next available number
+projects = Dir.glob('b*.md').map { |f| ProjectName.new(f) }
+sequences = projects.map(&:sequence).sort
+
+# Find next sequence number
+last_sequence = sequences.last  # "b75"
+next_sequence = "b#{last_sequence.sub(/^b/, '').to_i + 1}"
+# => "b76"
+```
+**AI discovers**: Sequence patterns, gaps. Can manage project numbering scheme.
+
+### 4. Naming Validation
+```ruby
+# AI validates all projects follow naming convention
+Dir.glob('**/*').each do |file|
+  project = ProjectName.new(file)
+  if project.sequence.nil? || project.project_name.nil?
+    puts "Invalid name: #{file}"
+  end
+end
+```
+**AI discovers**: Naming compliance. Can identify and fix naming violations.
+
+### 5. Multi-Channel Reporting
+```ruby
+# AI generates reports by channel
+channels = {}
+Dir.glob('**/*.md').each do |file|
+  project = ProjectName.new(file)
+  channels[project.channel_code] ||= []
+  channels[project.channel_code] << project
+end
+
+channels.each do |channel, projects|
+  puts "#{channel}: #{projects.length} projects"
+end
+```
+**AI discovers**: Projects per channel. Can generate channel-specific reports.
+
+### 6. Bulk Renaming
+```ruby
+# AI orchestrates renaming operation
+# When naming convention changes
+Dir.glob('**/*.md').each do |old_file|
+  project = ProjectName.new(old_file)
+  # Apply new naming rules
+  new_name = "#{project.sequence}-#{project.channel_code}-#{project.project_name.upcase}.md"
+  File.rename(old_file, new_name) if old_file != new_name
+end
+```
+**AI discovers**: Current naming scheme. Can apply new conventions systematically.
+
+### 7. Project Organization
+```ruby
+# AI organizes projects by channel
+Dir.glob('**/*.md').each do |file|
+  project = ProjectName.new(file)
+  channel_dir = "projects/#{project.channel_code}"
+  FileUtils.mkdir_p(channel_dir)
+  FileUtils.mv(file, "#{channel_dir}/#{project.generate_name}.md")
+end
+```
+**AI discovers**: Naming patterns. Can reorganize by channel using names.
+
+### 8. Name Conflict Detection
+```ruby
+# AI identifies duplicate project names
+names = Dir.glob('**/*').map { |f| ProjectName.new(f).generate_name }
+duplicates = names.group_by { |n| n }.select { |_, v| v.length > 1 }
+
+duplicates.each do |name, count|
+  puts "Duplicate: #{name} (#{count} files)"
+end
+```
+**AI discovers**: Naming collisions. Can identify and help resolve duplicates.
+
+### 9. Sequence Gap Analysis
+```ruby
+# AI analyzes sequence number coverage
+projects = Dir.glob('b*.md').map { |f| ProjectName.new(f) }
+sequences = projects.map { |p| p.sequence.sub(/^b/, '').to_i }.sort
+
+gaps = []
+(sequences.first..sequences.last).each do |n|
+  gaps << n unless sequences.include?(n)
+end
+
+puts "Gaps in sequence: #{gaps.inspect}"
+```
+**AI discovers**: Sequence coverage. Can identify missing numbers for reuse or filling.
+
+### 10. Naming Standardization
+```ruby
+# AI ensures all names follow convention
+# lowercase, hyphenated, valid channels
+Dir.glob('**/*').each do |file|
+  project = ProjectName.new(file)
+  standardized_name = project.generate_name.downcase.gsub(/\s+/, '-')
+  new_path = "#{File.dirname(file)}/#{standardized_name}#{File.extname(file)}"
+  File.rename(file, new_path) if file != new_path
+end
+```
+**AI discovers**: Naming inconsistencies. Can standardize all names.
+
+## Class Reference
+
+### ProjectName
+
+```ruby
+class ProjectName
+  # Parse project filename
+  def initialize(file_name)
+  end
+
+  # Get/set attributes
+  attr_accessor :sequence
+  attr_accessor :project_name
+  attr_reader :channel_code
+
+  # Generate standardized name
+  def generate_name
+  end
+
+  # Set and validate channel code
+  def channel_code=(code)
+  end
+end
+```
+
+**Attributes**:
+- `sequence` - Project sequence (e.g., "b60", "50")
+- `channel_code` - Channel code (e.g., "appydave", "aitldr")
+- `project_name` - Project descriptor (e.g., "intro-to-coding")
+
+**Methods**:
+- `generate_name()` - Returns "{sequence}-{channel}-{project_name}" (lowercase, hyphenated)
+- `channel_code=(code)` - Validates and sets channel code against configured channels
+
+## Configuration
+
+Names are validated against configured channels in:
+```
+~/.config/appydave/channels.json
+```
+
+Valid channels must be defined in configuration. Invalid channels are rejected.
+
+## Naming Rules
+
+1. **Sequence**: Alphanumeric identifier (e.g., `b60`, `50`)
+2. **Channel** (optional): Valid configured channel code (e.g., `appydave`, `aitldr`)
+3. **Project Name**: Hyphenated, lowercase (e.g., `intro-to-coding`)
+
+**Generated Format**:
+- With channel: `{seq}-{channel}-{project}` (all lowercase)
+- Without channel: `{seq}-{project}` (all lowercase)
+
+## Examples
+
+### Parse & Regenerate
+```ruby
+project = ProjectName.new('B60-APPYDAVE-Intro-To-Coding')
+project.generate_name
+# => "b60-appydave-intro-to-coding" (normalized)
+```
+
+### Create New Project Name
+```ruby
+project = ProjectName.new('b60-test')
+project.channel_code = 'appydave'
+project.project_name = 'full-course-series'
+project.generate_name
+# => "b60-appydave-full-course-series"
+```
+
+### Extract Parts
+```ruby
+project = ProjectName.new('b60-appydave-advanced-python.md')
+puts "Sequence: #{project.sequence}"           # "b60"
+puts "Channel: #{project.channel_code}"        # "appydave"
+puts "Project: #{project.project_name}"        # "advanced-python"
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Invalid channel code" | Channel must be configured in ~/.config/appydave/channels.json |
+| "Parse error" | Ensure filename follows {seq}-{channel?}-{project} format |
+| "Missing sequence" | Sequence (first part) is required |
+| "Invalid characters" | Project names should use hyphens, no spaces or underscores |
+
+## Tips & Tricks
+
+1. **Use sequence prefix**: `b` for big videos, `s` for shorts, helps with sorting
+2. **Valid channel first**: Set correct channel before generating names
+3. **Lowercase output**: `generate_name()` always returns lowercase
+4. **Batch processing**: Use in loops to rename/validate entire projects
+5. **Configuration required**: Set up channels.json before using
+
+---
+
+**Related Tools**:
+- `configuration` - Manage channel definitions
+- `youtube_manager` - Uses project names for organization
+- Video production tools - Reference projects by names
+
+**Pattern**: Part of AppyDave project organization system

data/docs/tools/prompt-tools.md

@@ -0,0 +1,209 @@
+# Prompt Tools
+
+⚠️ **DEPRECATED**: Uses legacy OpenAI Completion API (discontinued). See "Use Cases" for alternatives.
+
+Generate text completions using OpenAI's API for prompts and content generation.
+
+## What It Does (Deprecated)
+
+**Prompt Tools** provides command-line access to OpenAI text generation:
+
+- Send prompts to OpenAI API
+- Get text completions
+- Configure model and parameters
+- Handle streaming responses
+- Process batch prompts
+
+⚠️ **Status**: Uses deprecated OpenAI Completion API (`davinci-003`). OpenAI discontinued this in January 2024.
+
+## How to Use
+
+### Basic Completion
+
+```bash
+prompt_tools completion -p "Write a haiku about programming"
+
+prompt_tools completion -p "Explain recursion" -m "text-davinci-003"
+```
+
+### Configuration
+
+Set OpenAI API key in config:
+
+```bash
+# Interactive setup
+prompt_tools config
+
+# Or set environment variable
+export OPENAI_API_KEY="sk-..."
+```
+
+### Options
+
+```bash
+-p, --prompt TEXT        Text prompt to complete
+-m, --model MODEL        Model name (default: text-davinci-003)
+-t, --temperature NUM    Randomness 0-2 (default: 1.0)
+-l, --max-tokens NUM     Maximum response length
+-h, --help              Show help
+```
+
+## Why It's Deprecated
+
+OpenAI discontinued the Completion API in January 2024. The tool still works with archived models but should not be used for new work.
+
+### Migration Path
+
+**Instead of Completion API:**
+
+Use the **Chat Completion API** which is the current standard:
+
+```bash
+# Using gpt_context with aider (better approach)
+gpt_context -i 'lib/**/*.rb' -p "Explain this code" -o clipboard
+
+# Then paste into Claude, ChatGPT, or Copilot directly
+# Or use aider CLI tool with gpt_context output
+```
+
+## Use Cases for AI Agents
+
+### 1. Legacy Workflow Compatibility
+```bash
+# If you have existing scripts using this tool
+# They will continue to work with archived models
+# But consider migrating to Chat API
+```
+**AI discovers**: Legacy integration points. Can identify and update deprecated API usage.
+
+### 2. Batch Prompt Processing (Outdated)
+```bash
+# Old approach: Use prompt_tools in loop
+# Better approach: Use aider with gpt_context
+# Or call Claude/ChatGPT API directly
+```
+**AI discovers**: Where deprecated tools are used. Can plan migration strategy.
+
+### 3. Content Generation (Better Alternatives)
+```bash
+# Old: prompt_tools completion -p "Write blog post..."
+# New: Use Claude API (claude-3-sonnet-20240229)
+# Or: gpt_context + aider for code-aware generation
+```
+**AI discovers**: Content generation workflows. Can recommend better solutions.
+
+### 4. Completion for Coding (Much Better Alternatives)
+```bash
+# Old: prompt_tools to suggest code completions
+# Better: Use Copilot, Cursor, or Claude Code
+# These understand context and code style
+```
+**AI discovers**: Code generation needs. Can recommend modern tools.
+
+### 5. Migrating Legacy Prompts
+```bash
+# Convert old completion-style prompts to Chat format
+# Old: "Write a story about..."
+# New: ChatMessage with role="user", content="Write a story about..."
+```
+**AI discovers**: Legacy prompt format. Can adapt to modern APIs.
+
+### 6. Archive Historical Data
+```bash
+# If you have saved outputs from this tool
+# Convert to structured format for analysis
+# Keep for historical reference if needed
+```
+**AI discovers**: What was generated with this tool. Can preserve and archive.
+
+### 7. Identify Integration Points
+```bash
+# Find all scripts using prompt_tools
+# Document current usage
+# Plan migration to modern APIs
+grep -r "prompt_tools" . --include="*.rb" --include="*.sh"
+```
+**AI discovers**: Tool dependencies, integration surface area. Can plan systematic migration.
+
+### 8. API Cost Optimization
+```bash
+# Old models (davinci-003) are expensive
+# New models (gpt-3.5-turbo, gpt-4) are cheaper and better
+# Migrate to save on API costs
+```
+**AI discovers**: Cost structure. Can calculate migration savings.
+
+### 9. Functionality Assessment
+```bash
+# Determine what this tool was used for
+# Evaluate modern alternatives:
+#   - Code: GitHub Copilot, Claude Code, Cursor
+#   - Writing: ChatGPT, Claude, Gemini
+#   - Data: Claude API, GPT-4 API, specialized models
+```
+**AI discovers**: Use cases. Can recommend best modern solution for each.
+
+### 10. Retirement Planning
+```bash
+# Schedule deprecation of prompt_tools
+# Replace with modern API calls
+# Remove from codebase once all usages migrated
+```
+**AI discovers**: Deprecation timeline. Can plan orderly sunset of legacy tool.
+
+## Modern Alternatives
+
+| Use Case | Modern Solution | Notes |
+|----------|-----------------|-------|
+| Interactive coding | Claude Code, Copilot, Cursor | IDE integration recommended |
+| Batch code analysis | gpt_context + Claude API | Better context awareness |
+| Writing generation | ChatGPT API, Claude API | Chat format is more flexible |
+| Content creation | Dedicated content tools | Like Copy.ai, WriterAccess |
+| Completion in code | Model-specific APIs | Call modern APIs directly |
+
+## Troubleshooting (Legacy)
+
+| Issue | Solution |
+|-------|----------|
+| "Model not found" | Archived models are no longer available; migrate to Chat API |
+| "API key error" | Check `~/.config/appydave` for OPENAI_API_KEY |
+| "Rate limited" | Reduce batch size or wait; consider modern API quotas |
+
+## Migration Guide
+
+### Step 1: Identify Usage
+```bash
+# Find all prompt_tools invocations
+grep -r "prompt_tools" . --include="*.rb"
+```
+
+### Step 2: Understand Intent
+For each usage:
+- What is it trying to do?
+- What would be the best modern tool?
+
+### Step 3: Implement Alternative
+- For code: Use Claude Code, Copilot
+- For writing: Use ChatGPT API or Claude API
+- For batch: Use modern API with proper batching
+
+### Step 4: Test & Validate
+- Verify new solution works
+- Compare output quality
+- Measure cost difference
+
+### Step 5: Remove Legacy
+- Delete `prompt_tools` invocations
+- Update documentation
+- Remove from dependencies if no longer needed
+
+---
+
+**Status**: ⚠️ Deprecated - Migrate to modern APIs
+**Recommendation**: Replace with Claude API, OpenAI Chat API, or IDE-integrated tools
+**Timeline**: Plan migration within 6 months
+**Related Tools**:
+- `gpt_context` - For context gathering (works with modern APIs)
+- `youtube_automation` - Uses newer API patterns
+
+**OpenAI Migration**: [Completion → Chat Completions](https://platform.openai.com/docs/guides/gpt/completions-api)