@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/laravel-patterns.md

@@ -0,0 +1,261 @@
+---
+name: laravel-patterns
+description: Laravel patterns for Eloquent, middleware, jobs, events, policies, Blade, and Livewire.
+---
+
+# Laravel Patterns
+
+## When to Use
+
+Apply these patterns when building Laravel 10+ applications. Use this skill for
+structuring Eloquent models and relationships, writing middleware, dispatching
+background jobs, handling events, authorizing with policies, building Blade
+templates, and adding interactivity with Livewire.
+
+## How It Works
+
+### Eloquent Models
+
+Use scopes for reusable query constraints. Define relationships explicitly.
+Use casts for attribute transformation. Always set `$fillable` or `$guarded`.
+
+```php
+class Article extends Model
+{
+    protected $fillable = ['title', 'body', 'status', 'published_at'];
+
+    protected $casts = [
+        'published_at' => 'datetime',
+        'metadata' => 'array',
+        'status' => ArticleStatus::class, // backed enum
+    ];
+
+    // Relationships
+    public function author(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'author_id');
+    }
+
+    public function tags(): BelongsToMany
+    {
+        return $this->belongsToMany(Tag::class)->withTimestamps();
+    }
+
+    // Scopes
+    public function scopePublished(Builder $query): Builder
+    {
+        return $query->where('status', ArticleStatus::Published)
+                     ->where('published_at', '<=', now());
+    }
+
+    public function scopeByAuthor(Builder $query, User $user): Builder
+    {
+        return $query->where('author_id', $user->id);
+    }
+}
+
+// Usage: Article::published()->byAuthor($user)->paginate(20)
+```
+
+### Middleware
+
+Register middleware in `bootstrap/app.php` (Laravel 11+). Keep middleware focused
+on a single concern. Use constructor injection for dependencies.
+
+```php
+class EnsureApiVersion
+{
+    public function handle(Request $request, Closure $next, string $version = 'v1'): Response
+    {
+        if ($request->header('X-API-Version', 'v1') !== $version) {
+            return response()->json(['error' => 'Unsupported API version'], 400);
+        }
+
+        $response = $next($request);
+        $response->headers->set('X-API-Version', $version);
+
+        return $response;
+    }
+}
+
+// bootstrap/app.php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->api(append: [EnsureApiVersion::class]);
+})
+```
+
+### Jobs and Queues
+
+Use jobs for heavy processing: email sending, PDF generation, API calls. Implement
+`ShouldQueue` for async. Set `$tries`, `$backoff`, and `$timeout`.
+
+```php
+class ProcessUpload implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public array $backoff = [10, 60, 300];
+    public int $timeout = 120;
+
+    public function __construct(
+        private Upload $upload,
+    ) {}
+
+    public function handle(StorageService $storage): void
+    {
+        $storage->processFile($this->upload->path);
+        $this->upload->update(['status' => 'processed']);
+    }
+
+    public function failed(Throwable $exception): void
+    {
+        $this->upload->update(['status' => 'failed']);
+        Log::error('Upload processing failed', [
+            'upload_id' => $this->upload->id,
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}
+
+// Dispatch
+ProcessUpload::dispatch($upload)->onQueue('uploads');
+```
+
+### Events and Listeners
+
+Use events for decoupled side effects. One event can have multiple listeners.
+Queue listeners for non-blocking processing.
+
+```php
+// Events
+class OrderPlaced
+{
+    public function __construct(public readonly Order $order) {}
+}
+
+// Listeners
+class SendOrderConfirmation implements ShouldQueue
+{
+    public function handle(OrderPlaced $event): void
+    {
+        Mail::to($event->order->customer_email)
+            ->send(new OrderConfirmationMail($event->order));
+    }
+}
+
+class UpdateInventory
+{
+    public function handle(OrderPlaced $event): void
+    {
+        foreach ($event->order->items as $item) {
+            $item->product->decrement('stock', $item->quantity);
+        }
+    }
+}
+
+// Dispatch
+event(new OrderPlaced($order));
+```
+
+### Policies for Authorization
+
+One policy per model. Methods map to controller actions. Use `Gate::authorize`
+or `$this->authorize` in controllers.
+
+```php
+class ArticlePolicy
+{
+    public function update(User $user, Article $article): bool
+    {
+        return $user->id === $article->author_id
+            || $user->hasRole('editor');
+    }
+
+    public function delete(User $user, Article $article): bool
+    {
+        return $user->id === $article->author_id
+            || $user->hasRole('admin');
+    }
+}
+
+// Controller
+public function update(Request $request, Article $article)
+{
+    $this->authorize('update', $article);
+    // ... proceed with update
+}
+```
+
+### Blade Components
+
+Use class-based components for logic, anonymous components for simple markup.
+Pass data via attributes. Use `{{ }}` for escaped output, `@` directives for
+control flow.
+
+```php
+<!-- resources/views/components/alert.blade.php -->
+@props(['type' => 'info', 'dismissible' => false])
+
+<div {{ $attributes->merge(['class' => "alert alert-{$type}"]) }}>
+    {{ $slot }}
+    @if($dismissible)
+        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+    @endif
+</div>
+
+<!-- Usage -->
+<x-alert type="success" dismissible>Order placed successfully.</x-alert>
+```
+
+### Livewire for Interactivity
+
+Use Livewire 3 for server-rendered interactivity without writing JavaScript.
+Keep components focused. Use `wire:model.live` for real-time binding.
+
+```php
+class SearchArticles extends Component
+{
+    public string $query = '';
+    public int $perPage = 10;
+
+    public function updatedQuery(): void
+    {
+        $this->resetPage();
+    }
+
+    public function render(): View
+    {
+        return view('livewire.search-articles', [
+            'articles' => Article::published()
+                ->where('title', 'like', "%{$this->query}%")
+                ->paginate($this->perPage),
+        ]);
+    }
+}
+```
+
+## Examples
+
+| Scenario | Pattern | Key Class/Method |
+|----------|---------|-----------------|
+| Reusable query filters | Eloquent scopes | `scopePublished()`, `scopeByAuthor()` |
+| Background email sending | Queued job | `ProcessUpload implements ShouldQueue` |
+| Decoupled side effects | Event + Listener | `event(new OrderPlaced($order))` |
+| Model-level authorization | Policy | `$this->authorize('update', $article)` |
+| Reusable UI components | Blade component | `<x-alert type="success">` |
+| Real-time search/filter | Livewire | `wire:model.live` binding |
+| Retry failed background work | Job backoff | `$backoff = [10, 60, 300]` |
+
+## Checklist
+
+- [ ] Eloquent models use scopes, casts, and explicit `$fillable`
+- [ ] `with()` / `load()` for eager loading (no N+1 queries)
+- [ ] Middleware does one thing; registered in `bootstrap/app.php`
+- [ ] Jobs implement `ShouldQueue` with `$tries`, `$backoff`, `$timeout`
+- [ ] `failed()` method on every job for error handling
+- [ ] Events for decoupled side effects; listeners queued for heavy work
+- [ ] Policies for model-level authorization, checked in controllers
+- [ ] Blade components for reusable UI; `$attributes->merge()` for defaults
+- [ ] Livewire components are small; `wire:model.live` for reactive search/filter
+- [ ] Enum casts for status fields (`ArticleStatus::class`)

package/assets/skills/llm-fine-tuning.md

@@ -0,0 +1,335 @@
+---
+name: llm-fine-tuning
+description: LLM fine-tuning patterns for dataset preparation, LoRA/QLoRA training, evaluation metrics, deployment, and cost optimization.
+---
+
+# LLM Fine-Tuning Patterns
+
+## When to Use
+Fine-tune an LLM when prompt engineering alone cannot achieve the required output quality, consistency, or format adherence. Common scenarios: domain-specific terminology, consistent structured output, style matching, classification tasks, and reducing prompt length. Start with prompt engineering, then few-shot examples, then fine-tuning only when those approaches fall short. Fine-tuning is most cost-effective for high-volume, narrow tasks.
+
+## How It Works
+
+### Dataset Preparation
+
+```typescript
+// scripts/prepare-dataset.ts
+import fs from 'fs/promises';
+
+interface TrainingExample {
+  messages: Array<{
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+  }>;
+}
+
+interface RawDataItem {
+  input: string;
+  output: string;
+  category?: string;
+}
+
+const SYSTEM_PROMPT = `You are a customer support assistant for Acme Corp. Respond in a helpful, concise manner. Always include the relevant ticket ID when available.`;
+
+async function prepareDataset(rawPath: string, outputPath: string) {
+  const raw: RawDataItem[] = JSON.parse(await fs.readFile(rawPath, 'utf-8'));
+
+  // Validate and filter
+  const valid = raw.filter((item) => {
+    if (!item.input?.trim() || !item.output?.trim()) return false;
+    if (item.input.length < 10 || item.output.length < 10) return false;
+    if (item.input.length > 4000 || item.output.length > 4000) return false;
+    return true;
+  });
+
+  console.log(`Valid examples: ${valid.length}/${raw.length}`);
+
+  // Convert to chat format
+  const training: TrainingExample[] = valid.map((item) => ({
+    messages: [
+      { role: 'system', content: SYSTEM_PROMPT },
+      { role: 'user', content: item.input },
+      { role: 'assistant', content: item.output },
+    ],
+  }));
+
+  // Shuffle
+  for (let i = training.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [training[i], training[j]] = [training[j], training[i]];
+  }
+
+  // Split: 90% train, 10% validation
+  const splitIdx = Math.floor(training.length * 0.9);
+  const train = training.slice(0, splitIdx);
+  const val = training.slice(splitIdx);
+
+  // Write JSONL format
+  await fs.writeFile(
+    outputPath.replace('.jsonl', '_train.jsonl'),
+    train.map((e) => JSON.stringify(e)).join('\n')
+  );
+  await fs.writeFile(
+    outputPath.replace('.jsonl', '_val.jsonl'),
+    val.map((e) => JSON.stringify(e)).join('\n')
+  );
+
+  console.log(`Train: ${train.length}, Validation: ${val.length}`);
+}
+```
+
+### Dataset Quality Checks
+
+```typescript
+// scripts/validate-dataset.ts
+interface DatasetStats {
+  totalExamples: number;
+  avgInputTokens: number;
+  avgOutputTokens: number;
+  maxInputTokens: number;
+  maxOutputTokens: number;
+  duplicateInputs: number;
+  categoryDistribution: Record<string, number>;
+}
+
+async function validateDataset(path: string): Promise<DatasetStats> {
+  const lines = (await fs.readFile(path, 'utf-8')).trim().split('\n');
+  const examples = lines.map((l) => JSON.parse(l) as TrainingExample);
+
+  const inputSet = new Set<string>();
+  let duplicates = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let maxInput = 0;
+  let maxOutput = 0;
+
+  for (const ex of examples) {
+    const userMsg = ex.messages.find((m) => m.role === 'user')?.content ?? '';
+    const assistantMsg = ex.messages.find((m) => m.role === 'assistant')?.content ?? '';
+
+    const inputTokens = Math.ceil(userMsg.length / 4); // rough estimate
+    const outputTokens = Math.ceil(assistantMsg.length / 4);
+
+    totalInputTokens += inputTokens;
+    totalOutputTokens += outputTokens;
+    maxInput = Math.max(maxInput, inputTokens);
+    maxOutput = Math.max(maxOutput, outputTokens);
+
+    if (inputSet.has(userMsg)) duplicates++;
+    inputSet.add(userMsg);
+  }
+
+  return {
+    totalExamples: examples.length,
+    avgInputTokens: Math.round(totalInputTokens / examples.length),
+    avgOutputTokens: Math.round(totalOutputTokens / examples.length),
+    maxInputTokens: maxInput,
+    maxOutputTokens: maxOutput,
+    duplicateInputs: duplicates,
+    categoryDistribution: {},
+  };
+}
+```
+
+### OpenAI Fine-Tuning API
+
+```typescript
+// scripts/finetune.ts
+import OpenAI from 'openai';
+
+const openai = new OpenAI();
+
+async function startFineTuning(trainFile: string, valFile: string) {
+  // Upload training file
+  const trainUpload = await openai.files.create({
+    file: fs.createReadStream(trainFile),
+    purpose: 'fine-tune',
+  });
+  console.log(`Training file uploaded: ${trainUpload.id}`);
+
+  // Upload validation file
+  const valUpload = await openai.files.create({
+    file: fs.createReadStream(valFile),
+    purpose: 'fine-tune',
+  });
+  console.log(`Validation file uploaded: ${valUpload.id}`);
+
+  // Create fine-tuning job
+  const job = await openai.fineTuning.jobs.create({
+    training_file: trainUpload.id,
+    validation_file: valUpload.id,
+    model: 'gpt-4o-mini-2024-07-18',
+    hyperparameters: {
+      n_epochs: 3,
+      batch_size: 'auto',
+      learning_rate_multiplier: 'auto',
+    },
+    suffix: 'customer-support-v1',
+  });
+
+  console.log(`Fine-tuning job created: ${job.id}`);
+  return job.id;
+}
+
+async function monitorJob(jobId: string) {
+  while (true) {
+    const job = await openai.fineTuning.jobs.retrieve(jobId);
+    console.log(`Status: ${job.status}`);
+
+    if (job.status === 'succeeded') {
+      console.log(`Model ready: ${job.fine_tuned_model}`);
+      return job.fine_tuned_model;
+    }
+
+    if (job.status === 'failed') {
+      console.error(`Failed: ${job.error?.message}`);
+      throw new Error(job.error?.message);
+    }
+
+    // List recent events
+    const events = await openai.fineTuning.jobs.listEvents(jobId, { limit: 5 });
+    for (const event of events.data) {
+      console.log(`  [${event.level}] ${event.message}`);
+    }
+
+    await new Promise((r) => setTimeout(r, 60_000)); // check every minute
+  }
+}
+```
+
+### LoRA Configuration (Hugging Face / PEFT)
+
+```python
+# train_lora.py
+from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
+from peft import LoraConfig, get_peft_model, TaskType
+from trl import SFTTrainer
+from datasets import load_dataset
+
+# Load base model
+model_name = "meta-llama/Llama-3.1-8B-Instruct"
+model = AutoModelForCausalLM.from_pretrained(
+    model_name,
+    torch_dtype="auto",
+    device_map="auto",
+    load_in_4bit=True,  # QLoRA: 4-bit quantization
+)
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+tokenizer.pad_token = tokenizer.eos_token
+
+# LoRA configuration
+lora_config = LoraConfig(
+    task_type=TaskType.CAUSAL_LM,
+    r=16,                      # rank — higher = more capacity, more VRAM
+    lora_alpha=32,             # scaling factor
+    lora_dropout=0.05,
+    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],  # attention layers
+    bias="none",
+)
+
+model = get_peft_model(model, lora_config)
+model.print_trainable_parameters()
+# trainable params: 6.5M || all params: 8B || trainable%: 0.08%
+
+# Training
+dataset = load_dataset("json", data_files={"train": "train.jsonl", "validation": "val.jsonl"})
+
+training_args = TrainingArguments(
+    output_dir="./output",
+    num_train_epochs=3,
+    per_device_train_batch_size=4,
+    gradient_accumulation_steps=4,
+    learning_rate=2e-4,
+    warmup_ratio=0.1,
+    logging_steps=10,
+    evaluation_strategy="steps",
+    eval_steps=100,
+    save_strategy="steps",
+    save_steps=100,
+    bf16=True,
+    report_to="wandb",
+)
+
+trainer = SFTTrainer(
+    model=model,
+    args=training_args,
+    train_dataset=dataset["train"],
+    eval_dataset=dataset["validation"],
+    tokenizer=tokenizer,
+    max_seq_length=2048,
+)
+
+trainer.train()
+model.save_pretrained("./lora-adapter")
+```
+
+### Evaluation
+
+```typescript
+// scripts/evaluate.ts
+interface EvalResult {
+  example: TrainingExample;
+  predicted: string;
+  reference: string;
+  metrics: { exact_match: boolean; bleu: number; rouge_l: number };
+}
+
+async function evaluateModel(modelId: string, testFile: string): Promise<void> {
+  const examples = (await fs.readFile(testFile, 'utf-8')).trim().split('\n')
+    .map((l) => JSON.parse(l) as TrainingExample);
+
+  const results: EvalResult[] = [];
+
+  for (const ex of examples) {
+    const messages = ex.messages.filter((m) => m.role !== 'assistant');
+    const reference = ex.messages.find((m) => m.role === 'assistant')!.content;
+
+    const response = await openai.chat.completions.create({
+      model: modelId,
+      messages,
+      max_tokens: 500,
+      temperature: 0,
+    });
+
+    const predicted = response.choices[0].message.content ?? '';
+    results.push({
+      example: ex,
+      predicted,
+      reference,
+      metrics: {
+        exact_match: predicted.trim() === reference.trim(),
+        bleu: computeBleu(predicted, reference),
+        rouge_l: computeRougeL(predicted, reference),
+      },
+    });
+  }
+
+  const avgBleu = results.reduce((s, r) => s + r.metrics.bleu, 0) / results.length;
+  const avgRouge = results.reduce((s, r) => s + r.metrics.rouge_l, 0) / results.length;
+  const exactMatch = results.filter((r) => r.metrics.exact_match).length / results.length;
+
+  console.log(`Results (${results.length} examples):`);
+  console.log(`  Exact Match: ${(exactMatch * 100).toFixed(1)}%`);
+  console.log(`  Avg BLEU:    ${(avgBleu * 100).toFixed(1)}`);
+  console.log(`  Avg ROUGE-L: ${(avgRouge * 100).toFixed(1)}`);
+}
+```
+
+## Examples
+
+| Approach | Dataset Size | Cost | Latency Impact | Best For |
+|----------|-------------|------|----------------|----------|
+| Prompt engineering | 0 | Free | None | Initial prototyping |
+| Few-shot examples | 5-20 | Token cost | Higher latency | Format adherence |
+| OpenAI fine-tune | 50-10K | $3-25/M tokens | Lower latency | Consistent behavior |
+| LoRA (self-hosted) | 1K-100K | GPU hours | You control | Full customization |
+
+## Checklist
+- [ ] Dataset has at least 50 examples (200+ recommended for quality)
+- [ ] Training data cleaned: no duplicates, validated formats, balanced categories
+- [ ] Held-out validation set (10%) for monitoring overfitting
+- [ ] System prompt consistent across all training examples
+- [ ] Evaluation metrics defined before training (BLEU, ROUGE, exact match)
+- [ ] Fine-tuned model compared against base model on evaluation set
+- [ ] Training costs estimated before starting (tokens x price per token)
+- [ ] Model versioned with suffix and deployment tested before production use