@groupby/ai-dev 0.5.7 → 0.5.8

package/teams/fhr-ai-team/resources/opencode-setup.md

@@ -0,0 +1,43 @@
+# OpenCode Setup
+
+## Installation
+
+```bash
+git clone https://github.com/Attraqt/ai.agent-skills.git
+```
+
+Open the cloned directory in OpenCode. No additional setup is required.
+
+## How It Works
+
+- `AGENTS.md` at the repo root is loaded automatically and provides agent instructions
+- Skills in the `skills/` directory are discovered via directory convention
+- The agent automatically selects the appropriate skill based on your natural language request
+- No slash commands are needed; the agent detects intent and routes to the right workflow
+
+## Skill Routing
+
+| Your request | Skill invoked |
+|-------------|---------------|
+| "Let's brainstorm how to..." | `skills/brainstorming/SKILL.md` |
+| "Plan the implementation for..." | `skills/planning/SKILL.md` |
+| "Test the pipeline for..." | `skills/algo-test-planning/SKILL.md` |
+| "Run the tests for..." | `skills/e2e-testing/SKILL.md` |
+| "Check my Kubeflow run" | `skills/ml-tooling-dev/SKILL.md` |
+| "Review the naming in..." | `skills/naming-conventions-reviewer/SKILL.md` |
+
+## Using in Other Projects
+
+To use ai.pierre skills when working in a different project repo:
+
+1. Ensure `AGENTS.md` is copied or symlinked to your project root
+2. Copy the `skills/` directory (or specific skills you need) into your project
+3. The agent will auto-discover and apply them
+
+Alternatively, reference the skills directory in your OpenCode configuration to load them globally.
+
+## Notes
+
+- The skill routing depends on the model consistently following rules in `AGENTS.md`
+- For best results, keep your requests natural and descriptive
+- The agent will use the `question` tool (OpenCode equivalent of AskUserQuestion) to gather requirements interactively

package/teams/fhr-ai-team/skills/algo-test-planning/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: algo-test-planning
+description: >
+  Use when the user wants to plan or configure a test for an algo pipeline. Guides through
+  pipeline selection, config gathering, and Kubeflow config JSON generation via a 3-stage
+  interactive flow using AskUserQuestion. Covers full multi-step pipelines and base
+  single-step pipelines.
+---
+
+# Algo Pipeline Test Planning
+
+## Overview
+
+This skill guides you through planning and configuring a test run for an ML pipeline.
+It produces a complete Kubeflow config JSON and a test plan with launch and verification steps.
+
+All pipeline operations target the **DEV environment only**.
+
+## Stage 1: Pipeline Type Selection
+
+Use AskUserQuestion to ask:
+
+**Question:** "What type of pipeline do you want to test?"
+
+| Option | Description |
+|--------|-------------|
+| Full pipeline | Multi-step end-to-end pipeline (e.g., learning + evaluation + encoding) |
+| Base/single-step pipeline | Single step using a base pipeline template |
+
+---
+
+## Stage 2a: Full Pipeline Selection
+
+If the user chose "Full pipeline", use AskUserQuestion to ask which pipeline.
+
+Consult `references/pipeline-registry.md` for the complete list grouped by domain.
+Present the most relevant options based on context, or let the user search.
+
+Common full pipelines by domain:
+
+**Semantic Search:**
+- `semantic_search_learning_with_generated_analytics_pipeline`
+- `semantic_search_item_encoding_pipeline`
+
+**Visual Search / CLIP:**
+- `clip_learning_pipeline`
+- `clip_item_encoding_pipeline`
+
+**Tagging:**
+- `tagging_learning_pipeline`
+- `transformer_tagging_learning_pipeline`
+
+**Image:**
+- `image_encoder_learning_pipeline`
+- `image_classifier_pipeline`
+
+**Shop the Look:**
+- `shop_the_look_learning_pipeline`
+
+**FM / Recommendations:**
+- `fm_learning_pipeline`
+
+**Text Encoder:**
+- `text_encoder_learning_pipeline`
+
+Then gather pipeline-specific config fields based on the selected pipeline's requirements
+(see `references/pipeline-registry.md` for required fields per pipeline).
+
+---
+
+## Stage 2b: Base Pipeline Selection
+
+If the user chose "Base/single-step pipeline", use AskUserQuestion to ask:
+
+**Question:** "Which base pipeline type?"
+
+| Option | Description |
+|--------|-------------|
+| `python_batch_pipeline` | Standard Python batch jobs |
+| `large_python_batch_pipeline` | GPU/high-memory Python batch jobs |
+| `scala_batch_pipeline` | Scala-based batch jobs |
+| `spark_scala_batch_pipeline` | Spark Scala batch jobs |
+
+Then ask:
+- **Strategy ID** (what job to run, e.g., `semantic-search-learning`, `item-images-single-encoding`)
+- **Docker image name** (e.g., `semantic-search`, `algo-fm-batch`)
+- **Arguments** specific to the strategy (varies by step type)
+
+Key rules for base pipelines:
+- `python_batch_pipeline` and `large_python_batch_pipeline` use `batch_config.arguments` for custom params
+- `scala_batch_pipeline` and `spark_scala_batch_pipeline` use `batch_config.custom_params` (NOT `arguments`)
+- GPU jobs must include `gpu_vendor: "nvidia.com/gpu"` and `gpu_accelerator_name: "nvidia-l4"` for L4 nodes
+
+---
+
+## Stage 3: Config Gathering and JSON Generation
+
+Use AskUserQuestion sequentially for each required input:
+
+### 3.1 Predictor ID
+Ask for the MongoDB ObjectId (e.g., `64f0a12b5856b11b7aa4e71e`).
+This identifies the tenant/predictor whose config will be used.
+
+### 3.2 Experiment Name
+Discover available experiments:
+```bash
+python3 scripts/kf_query.py --experiments
+```
+Or let the user provide one directly.
+
+### 3.3 Strategy ID
+Based on the pipeline or step selected. Reference `skills/ml-tooling-dev/references/pipeline-configs.md`
+for the canonical strategy ID list.
+
+### 3.4 Image Version
+Verify the version exists in Kubeflow:
+```bash
+python3 scripts/kf_query.py --pipeline-versions <pipeline_name>
+```
+Use the most recent `version_name` from the output (e.g., `"0.1.271"`).
+
+### 3.5 Dataset Paths (if applicable)
+GCS paths from previous pipeline runs. Discover via:
+```bash
+python3 scripts/kf_query.py <previous_run_id>
+```
+Check Kubeflow UI -> run -> succeeded steps -> Output artifacts tab.
+
+### 3.6 MLflow Run ID (if applicable)
+For evaluation or encoding steps that need a trained model:
+```bash
+python3 scripts/mlflow_query.py model-for-predictor <predictor_id>
+```
+
+### 3.7 MongoDB Config Check
+Read current training hyperparameters:
+```bash
+mongosh "mongodb://10.11.96.21:27017/earlybirds" --quiet --eval '
+const doc = db.predictors.findOne({"_id": ObjectId("<PREDICTOR_ID>")});
+print(JSON.stringify(doc.config.batch, null, 2));
+'
+```
+Present the current config to the user. Ask if any changes are needed before the test run.
+If changes are needed, generate the `updateOne` command (see `skills/ml-tooling-dev/references/mongodb-config.md`).
+
+### 3.8 Resource Overrides
+Use defaults from `skills/ml-tooling-dev/references/pipeline-configs.md` unless the user specifies:
+- CPU/memory requests and limits
+- GPU type and count
+- Disk size
+
+---
+
+## Output
+
+Generate the following:
+
+### 1. Complete Kubeflow Config JSON
+A ready-to-submit JSON file. Save to `/tmp/<pipeline>-<predictor_id>-test.json`.
+
+### 2. Pre-Launch Checklist
+- [ ] `version_name` verified via `kf_query.py --pipeline-versions`
+- [ ] MongoDB config confirmed (show current values)
+- [ ] Dataset paths validated (exist in GCS)
+- [ ] Experiment exists in Kubeflow
+
+### 3. Launch Command
+```bash
+cd attraqt-kubeflow-configs/scripts
+python -m run -c <absolute_path_to_config>
+```
+
+### 4. Verification Steps
+- Monitor run: `python3 scripts/kf_query.py <run_id>`
+- Check failed steps: `python3 scripts/kf_query.py <run_id> --failed`
+- Expected step outcomes for each pipeline step
+- Pod log patterns to watch for
+
+### 5. Failure Recovery
+- Debug failed steps: see `skills/ml-tooling-dev/references/kubectl-debug.md`
+- Common failure patterns and fixes
+- How to re-run individual failed steps
+
+---
+
+## Skill Dependencies
+
+This skill invokes `ai.pierre:ml-tooling-dev` for:
+- Config templates and validation
+- Kubeflow/MLflow query commands
+- MongoDB read/update operations
+- kubectl debugging commands

package/teams/fhr-ai-team/skills/algo-test-planning/references/pipeline-registry.md

@@ -0,0 +1,280 @@
+# Pipeline Registry
+
+Complete registry of all AI pipelines from `attraqt-kubeflow-pipelines`.
+Source: `kubeflow_pipelines/pipelines/ai/__init__.py`
+
+---
+
+## Base Pipelines (Single-Step Templates)
+
+These are generic pipeline wrappers for running a single batch job step.
+
+| Pipeline | Type | Use case |
+|----------|------|----------|
+| `python_batch_pipeline` | Python | Standard Python batch jobs |
+| `large_python_batch_pipeline` | Python | GPU/high-memory Python batch jobs |
+| `scala_batch_pipeline` | Scala | Scala-based batch jobs |
+| `spark_scala_batch_pipeline` | Spark Scala | Spark Scala batch jobs |
+
+**Config differences:**
+- Python pipelines use `batch_config.arguments` for custom params
+- Scala pipelines use `batch_config.custom_params` (NOT `arguments`)
+- `large_python_batch_pipeline` supports GPU: set `gpu_vendor: "nvidia.com/gpu"` and `gpu_accelerator_name: "nvidia-l4"`
+
+---
+
+## Semantic Search
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `semantic_search_learning_pipeline` | Full | Learning only |
+| `semantic_search_learning_with_generated_analytics_pipeline` | Full | Learning + analytics generation (most common) |
+| `semantic_search_item_encoding_pipeline` | Full | Item encoding after training |
+| `export_huggingface_sentence_transformer_model_pipeline` | Script | Export HuggingFace sentence transformer model |
+
+---
+
+## Search (Text-only, no images)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `search_rnn_learning_pipeline_without_images` | Full | RNN-based search learning |
+| `search_llm_learning_pipeline_without_images` | Full | LLM-based search learning |
+| `search_item_encoding_pipeline_without_images` | Full | Item encoding (text only) |
+
+---
+
+## Search + CLIP (Text + Images)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `clip_search_rnn_learning_pipeline` | Full | CLIP + RNN search learning |
+| `clip_search_llm_learning_pipeline` | Full | CLIP + LLM search learning |
+| `clip_search_llm_learning_pipeline_with_data_augmentation` | Full | CLIP + LLM with data augmentation |
+| `clip_search_vertical_rnn_learning_pipeline` | Full | Vertical (per-tenant) CLIP + RNN learning |
+| `clip_search_vertical_llm_learning_pipeline` | Full | Vertical (per-tenant) CLIP + LLM learning |
+| `clip_large_search_vertical_rnn_learning_pipeline` | Full | Large vertical CLIP + RNN (GPU) |
+| `clip_large_search_vertical_llm_learning_pipeline` | Full | Large vertical CLIP + LLM (GPU) |
+| `clip_search_item_encoding_pipeline` | Full | CLIP search item encoding |
+
+---
+
+## Search + Image Encoder
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `image_encoder_search_item_encoding_pipeline_with_images` | Full | Image encoder search encoding (with images) |
+| `image_encoder_search_item_encoding_pipeline_without_images` | Full | Image encoder search encoding (without images) |
+
+---
+
+## Search Evaluation
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `search_evaluation_pipeline` | Full | Standard search evaluation |
+| `search_llm_evaluation_pipeline` | Full | LLM-based search evaluation |
+
+---
+
+## Computer Vision - CLIP
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `clip_learning_pipeline` | Full | CLIP model learning |
+| `clip_vertical_learning_pipeline` | Full | Per-tenant CLIP learning |
+| `large_clip_learning_pipeline` | Full | Large CLIP learning (GPU) |
+| `clip_item_images_single_encoding_pipeline` | Full | CLIP single image encoding |
+| `export_huggingface_clip_model_pipeline` | Script | Export HuggingFace CLIP model |
+
+---
+
+## Computer Vision - Image Encoder
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `computer_vision_learning_pipeline` | Full | Image encoder learning |
+| `computer_vision_vertical_learning_pipeline` | Full | Per-tenant image encoder learning |
+| `large_computer_vision_vertical_learning_pipeline` | Full | Large vertical learning (GPU) |
+| `computer_vision_item_images_single_encoding_pipeline` | Full | Image encoding |
+
+---
+
+## Computer Vision - SAM
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `export_huggingface_sam_model_pipeline` | Script | Export HuggingFace SAM model |
+
+---
+
+## FM (Factorization Machines / Recommendations)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `fm_global_initialization_pipeline` | Full | FM global model initialization |
+| `fm_global_incremental_pipeline` | Full | FM global incremental update |
+| `fm_complementarity_initialization_pipeline` | Full | FM complementarity initialization |
+| `fm_complementarity_incremental_pipeline` | Full | FM complementarity incremental update |
+
+---
+
+## GPT (Generative)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `gpt_initialization_pipeline_with_images` | Full | GPT init (with images) |
+| `gpt_initialization_pipeline_without_images` | Full | GPT init (text only) |
+| `gpt_incremental_pipeline_with_images` | Full | GPT incremental (with images) |
+| `gpt_incremental_pipeline_without_images` | Full | GPT incremental (text only) |
+| `gpt_item_encoding_pipeline_with_images` | Full | GPT item encoding (with images) |
+| `gpt_item_encoding_pipeline_without_images` | Full | GPT item encoding (text only) |
+
+---
+
+## Tagging
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `tagging_learning_pipeline` | Full | Tagging model learning |
+| `tagging_item_tagging_pipeline` | Full | Apply tagging to items |
+| `tagging_item_macro_tagging_pipeline` | Full | Apply macro tagging to items |
+
+---
+
+## Shop the Look
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `shop_the_look_recommendation_pipeline` | Full | STL recommendations |
+| `shop_the_look_recommendation_with_segmentation_pipeline` | Full | STL with image segmentation |
+| `shop_the_look_recommendation_without_segmentation_pipeline` | Full | STL without segmentation |
+| `shop_the_look_recommendation_with_outfit_detection_pipeline` | Full | STL with outfit detection |
+| `outfit_image_classification_learning_pipeline` | Full | Outfit classifier learning |
+| `outfit_image_classification_vertical_learning_pipeline` | Full | Per-tenant outfit classifier |
+
+---
+
+## YOLO (Object Detection)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `yolo_model_fine_tuning_pipeline` | Full | YOLO model fine-tuning |
+| `yolo_model_fine_tuning_vertical_pipeline` | Full | Per-tenant YOLO fine-tuning |
+| `export_ultralytics_yolo_model_pipeline` | Script | Export Ultralytics YOLO model |
+
+---
+
+## Item and Analytic Data
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `xo_item_data_pipeline` | Full | XO item data ingestion |
+| `fhr_item_data_pipeline` | Full | FHR item data ingestion |
+| `fhr_item_data_pipeline_legacy` | Full | FHR item data (legacy) |
+| `cidp_item_data_pipeline` | Full | CIDP item data ingestion |
+| `fhr_analytic_incremental_data_pipeline` | Full | FHR analytics incremental |
+| `fhr_analytic_incremental_data_pipeline_legacy` | Full | FHR analytics incremental (legacy) |
+| `fhr_analytic_data_pipeline_legacy` | Full | FHR analytics (legacy) |
+
+---
+
+## NLP
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `nlp_word_tokenizer_pipeline` | Full | Word tokenizer training |
+| `nlp_character_tokenizer_pipeline` | Full | Character tokenizer training |
+
+---
+
+## Content-Based
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `content_based_word2vec_pipeline` | Full | Word2Vec content-based recommendations |
+
+---
+
+## ALS (Alternating Least Squares)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `als_pipeline` | Full | ALS collaborative filtering |
+
+---
+
+## FP-Growth
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `fp_growth_items_pipeline` | Full | FP-Growth item associations |
+| `fp_growth_categories_pipeline` | Full | FP-Growth category associations |
+
+---
+
+## Pass-Through (Graph)
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `pass_through_scored_graph_pipeline` | Full | Scored graph pass-through |
+| `pass_through_unscored_graph_1_pipeline` | Full | Unscored graph variant 1 |
+| `pass_through_unscored_graph_2_pipeline` | Full | Unscored graph variant 2 |
+| `pass_through_source_to_items_unscored_graph_pipeline` | Full | Source-to-items unscored graph |
+
+---
+
+## Autocomplete
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `autocomplete_pipeline` | Full | Autocomplete model training |
+
+---
+
+## Miscellaneous
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `basic_pipeline` | Full | Basic/generic pipeline template |
+| `sessions_pipeline` | Full | Session data processing |
+| `bigquery_cleanup_pipeline` | Full | BigQuery data cleanup |
+| `gibberish_pipeline` | Full | Gibberish detection |
+| `dummy_ai_scores_pipeline` | Full | Dummy AI scores (testing) |
+| `item_tagging_pipeline` | Full | Items enrichment tagging |
+| `merch_agent_data_pipeline` | Full | Merch agent data preparation |
+| `lakefs_garbage_collection_pipeline` | Full | LakeFS garbage collection |
+
+---
+
+## Label Studio
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `outfit_tasks_import_pipeline` | Script | Import outfit tasks to Label Studio |
+| `outfit_annotations_export_pipeline` | Script | Export outfit annotations from Label Studio |
+| `yolo_tasks_import_pipeline` | Script | Import YOLO tasks to Label Studio |
+| `yolo_annotations_export_pipeline` | Script | Export YOLO annotations from Label Studio |
+
+---
+
+## Monitoring and Maintenance
+
+| Pipeline | Type | Description |
+|----------|------|-------------|
+| `activity_monitoring` | Monitoring | Activity monitoring |
+| `experiments_with_consecutive_failed_runs_monitoring_pipeline` | Monitoring | Failed experiments monitoring |
+| `runs_with_abnormal_duration_cleaning_pipeline` | Monitoring | Abnormal duration cleanup |
+| `gcs_cleaning_pipeline` | Script | GCS storage cleanup |
+| `gcs_activities_copy_pipeline` | Script | GCS activities data copy |
+| `image_download_pipeline` | Script | Image download utility |
+| `inference_data_cleaning_pipeline` | Script | Inference data cleanup |
+
+---
+
+## Total: ~93 pipelines
+
+- 4 base pipelines
+- ~70 full (multi-step) pipelines
+- ~12 script/utility pipelines
+- ~7 monitoring/maintenance pipelines

package/teams/fhr-ai-team/skills/brainstorming/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: brainstorming
+description: >
+  Use when the user wants to brainstorm, design, or explore a new feature, improvement,
+  or architecture decision. Discovers AI team repos via gh, searches existing code before
+  proposing solutions, and gathers requirements interactively via AskUserQuestion.
+---
+
+# Codebase-Aware Brainstorming
+
+## Hard Gate
+
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any
+implementation action until you have presented a design and the user has approved it.
+
+## Process
+
+### Step 1: Discover AI Team Repos
+
+Run the following to get the current repo landscape:
+
+```bash
+gh repo list Attraqt --json name,description --limit 200 --no-archived
+```
+
+Filter results for repos matching `ai.*`, `algo.*`, `ebap-*`, `attraqt-kubeflow-*`, and `*-toolbox` patterns.
+Present the user with a summary of the relevant repos grouped by category:
+
+| Category | Pattern | Purpose |
+|----------|---------|---------|
+| ML algorithms | `algo.*` | Model training, inference, evaluation |
+| ML training | `algo.*-ml` | Kubeflow-based model training/fine-tuning |
+| AI services | `ai.*` | FastAPI/Streamlit microservices |
+| Toolboxes | `*-toolbox` | Shared Python libraries |
+| Kubeflow infra | `attraqt-kubeflow-*` | Pipeline configs and definitions |
+| Platform infra | `ebap-*` | Early Birds AI Platform |
+
+### Step 2: Explore Project Context
+
+For repos relevant to the brainstorm topic:
+- Read their `CLAUDE.md` or `README.md` for architecture context
+- Check recent git history (`git log --oneline -20`) for active development areas
+- Scan directory structure to understand component layout
+
+### Step 3: Search Before Proposing
+
+**MANDATORY:** Before proposing any solution, search the codebase for existing utilities,
+patterns, and implementations related to the topic.
+
+- Use Grep/Glob across relevant repos
+- Check shared libraries: `earlybirds_commons`, `torch_toolbox`, `item-toolbox`, `nlp-toolbox`, `eb_tensorflow`
+- Report findings to the user: "I found X in repo Y that does something similar"
+
+If existing code covers part of the need, build on it rather than proposing greenfield work.
+
+### Step 4: Gather Requirements
+
+Use the AskUserQuestion tool to gather requirements interactively.
+
+Rules:
+- **One question per message.** Do not batch multiple questions.
+- **Prefer multiple-choice** over open-ended questions. Provide 2-4 concrete options based on what you found in the codebase.
+- Cover these dimensions (not all at once; ask only what is relevant):
+  - Scope: what is in/out
+  - Target repos: which repos are affected
+  - Constraints: performance, compatibility, timeline
+  - Dependencies: what must exist first
+  - Users: who benefits from this
+
+### Step 5: Propose 2-3 Approaches
+
+For each approach, include:
+- **Summary:** one-sentence description
+- **Trade-offs:** pros, cons, effort
+- **Repos affected:** which repos need changes
+- **Reuse opportunities:** what existing code can be leveraged
+- **Concrete code references:** point to specific files/functions in real repos
+
+### Step 6: Present Design in Sections
+
+Break the design into focused sections, each covering one concern.
+Wait for user feedback between sections. Sections might include:
+- Data model / schema changes
+- API contracts
+- Pipeline configuration
+- Integration points with existing code
+- Testing strategy
+
+### Step 7: Write Design Document
+
+After user approval, save the design to `docs/specs/YYYY-MM-DD-<topic>-design.md`
+in the relevant project repo. Include:
+- Problem statement
+- Chosen approach (with rationale)
+- Detailed design per section
+- Open questions (if any remain)
+- References to existing code being reused
+
+### Step 8: Self-Review
+
+Before presenting the final spec, review it for:
+- Placeholders or vague language ("TBD", "as appropriate", "handle errors")
+- Contradictions between sections
+- Scope creep beyond what was agreed
+- Missing error paths or edge cases
+- Naming convention violations (invoke `ai.pierre:naming-conventions-reviewer` if code is shown)
+
+### Step 9: User Review and Transition
+
+Present the spec for final user review. After approval, offer to invoke `/plan` to create
+implementation tasks from the approved design.