@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/ai-ml/rag-patterns/META.yaml

@@ -0,0 +1,57 @@
+# =============================================================================
+# META.yaml — RAG Patterns
+# =============================================================================
+
+name: rag-patterns
+version: "1.0.0"
+category: ai-ml
+priority: 3
+
+description: |
+  Retrieval-Augmented Generation patterns: chunking strategies,
+  embedding models, vector databases, retrieval optimization, evaluation.
+
+triggers:
+  keywords:
+    - rag
+    - retrieval augmented
+    - embedding
+    - vector database
+    - chunking
+    - semantic search
+    - pinecone
+    - weaviate
+    - qdrant
+    - chroma
+    - pgvector
+    - langchain
+    - llamaindex
+    - reranking
+
+  intents:
+    - "implement RAG pipeline"
+    - "setup vector database"
+    - "chunking strategy"
+    - "embedding model selection"
+    - "semantic search"
+    - "evaluate RAG quality"
+
+  detect_patterns:
+    content: ["VectorStore", "embedding", "chunk", "retriever", "RAG"]
+
+caps:
+  - chunking_strategies
+  - embedding_selection
+  - vector_db_setup
+  - retrieval_optimization
+  - rag_evaluation
+  - hybrid_search
+
+data_files:
+  - chunking-strategies.yaml
+  - embedding-models.yaml
+  - vector-databases.yaml
+  - retrieval-patterns.yaml
+  - evaluation.yaml
+
+# _DOMYH Awesome Code • RAG Patterns Skill_

package/.agent/skills/ai-ml/rag-patterns/SKILL.md

@@ -0,0 +1,92 @@
+# 🧠 RAG Patterns
+
+> Retrieval-Augmented Generation architecture patterns
+> 📚 Chunking • Embeddings • Vector DBs • Retrieval • Evaluation
+
+---
+
+## Quick Reference
+
+| Component      | Options                            | Recommendation           |
+| -------------- | ---------------------------------- | ------------------------ |
+| **Chunking**   | Fixed, Semantic, Recursive         | Recursive for docs       |
+| **Embeddings** | OpenAI, Cohere, Jina, local        | text-embedding-3-small   |
+| **Vector DB**  | Pinecone, Qdrant, Chroma, pgvector | pgvector for existing PG |
+| **Retrieval**  | Similarity, Hybrid, Reranking      | Hybrid + Reranking       |
+| **Evaluation** | RAGAS, faithfulness, relevancy     | RAGAS framework          |
+
+---
+
+## RAG Pipeline
+
+```
+Documents → Chunking → Embedding → Vector Store
+                                        ↓
+Query → Embedding → Similarity Search → Retrieved Chunks
+                                        ↓
+                              LLM + Context → Answer
+```
+
+---
+
+## Naive vs Advanced RAG
+
+| Aspect        | Naive RAG               | Advanced RAG          |
+| ------------- | ----------------------- | --------------------- |
+| Chunking      | Fixed 512 tokens        | Semantic boundaries   |
+| Retrieval     | Top-K similarity        | Hybrid + reranking    |
+| Context       | All chunks concatenated | Filtered + compressed |
+| Hallucination | Common                  | Reduced (citations)   |
+| Latency       | Fast                    | Moderate              |
+
+---
+
+## Chunking Strategies
+
+| Strategy           | Best For             | Overlap            |
+| ------------------ | -------------------- | ------------------ |
+| **Fixed-size**     | Simple docs, logs    | 10-20%             |
+| **Recursive**      | Markdown, code, HTML | Respects structure |
+| **Semantic**       | Mixed content        | By meaning change  |
+| **Document-aware** | PDFs, tables         | Preserves layout   |
+
+---
+
+## Embedding Models (2026)
+
+| Model                  | Dimensions | Context | Speed   | Quality |
+| ---------------------- | ---------- | ------- | ------- | ------- |
+| text-embedding-3-small | 1536       | 8K      | ⚡ Fast | Good    |
+| text-embedding-3-large | 3072       | 8K      | Medium  | Great   |
+| Cohere embed-v4        | 1024       | 512     | Fast    | Great   |
+| Jina v3                | 1024       | 8K      | Fast    | Good    |
+| BGE-M3 (local)         | 1024       | 8K      | Varies  | Good    |
+
+---
+
+## Vector Databases
+
+| Database     | Type        | Best For                 |
+| ------------ | ----------- | ------------------------ |
+| **pgvector** | Extension   | Already using PostgreSQL |
+| **Pinecone** | Managed     | Production, serverless   |
+| **Qdrant**   | Self-hosted | Full control, filtering  |
+| **Chroma**   | Embedded    | Prototyping, small scale |
+| **Weaviate** | Self-hosted | Multi-modal, hybrid      |
+| **Milvus**   | Self-hosted | Large scale, GPU         |
+
+---
+
+## HSA Integration
+
+| Query                               | Data File                  |
+| ----------------------------------- | -------------------------- |
+| `chunking fixed semantic recursive` | `chunking-strategies.yaml` |
+| `embedding model openai cohere`     | `embedding-models.yaml`    |
+| `pinecone qdrant chroma pgvector`   | `vector-databases.yaml`    |
+| `hybrid search reranking hyde`      | `retrieval-patterns.yaml`  |
+| `ragas faithfulness evaluation`     | `evaluation.yaml`          |
+
+---
+
+_DOMYH Awesome Code • RAG Patterns_

package/.agent/skills/ai-ml/rag-patterns/data/chunking-strategies.yaml

@@ -0,0 +1,71 @@
+# =============================================================================
+# chunking-strategies.yaml — Document Chunking Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+fixed_size:
+  description: "Split by character/token count"
+  config:
+    chunk_size: 512
+    chunk_overlap: 50
+    split_on: "tokens"
+  best_for: "Simple text, logs, uniform content"
+  example_python: |
+    from langchain.text_splitter import CharacterTextSplitter
+    splitter = CharacterTextSplitter(
+        chunk_size=512,
+        chunk_overlap=50,
+        separator="\n"
+    )
+    chunks = splitter.split_text(document)
+
+recursive:
+  description: "Split by hierarchy of separators"
+  separators: ["\n\n", "\n", ". ", " ", ""]
+  best_for: "Markdown, code, HTML, structured docs"
+  example_python: |
+    from langchain.text_splitter import RecursiveCharacterTextSplitter
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=1000,
+        chunk_overlap=200,
+        separators=["\n\n", "\n", ". ", " "]
+    )
+    chunks = splitter.split_documents(docs)
+
+semantic:
+  description: "Split by meaning changes using embeddings"
+  method: |
+    1. Split into sentences
+    2. Create embeddings for each sentence
+    3. Compute cosine similarity between adjacent sentences
+    4. Split where similarity drops below threshold
+  best_for: "Mixed content, preserving meaning"
+  example_python: |
+    from langchain_experimental.text_splitter import SemanticChunker
+    from langchain_openai import OpenAIEmbeddings
+    chunker = SemanticChunker(
+        OpenAIEmbeddings(),
+        breakpoint_threshold_type="percentile"
+    )
+    chunks = chunker.split_text(text)
+
+code_splitting:
+  description: "Language-aware code splitting"
+  languages: ["python", "javascript", "go", "rust", "java"]
+  example_python: |
+    from langchain.text_splitter import Language, RecursiveCharacterTextSplitter
+    splitter = RecursiveCharacterTextSplitter.from_language(
+        language=Language.PYTHON,
+        chunk_size=2000,
+        chunk_overlap=200
+    )
+
+best_practices:
+  - "Include metadata (source, page, section) with each chunk"
+  - "Overlap 10-20% to maintain context at boundaries"
+  - "Keep chunks between 100-1000 tokens"
+  - "For tables: keep entire table as one chunk"
+  - "For code: split at function/class boundaries"
+
+# _DOMYH Awesome Code • Chunking Strategies_

package/.agent/skills/ai-ml/rag-patterns/data/embedding-models.yaml

@@ -0,0 +1,76 @@
+# =============================================================================
+# embedding-models.yaml — Embedding Model Selection
+# =============================================================================
+
+version: "1.0.0"
+
+models:
+  openai:
+    - name: "text-embedding-3-small"
+      dimensions: 1536
+      max_tokens: 8191
+      price_per_1M: "$0.02"
+      best_for: "Cost-effective, general purpose"
+
+    - name: "text-embedding-3-large"
+      dimensions: 3072
+      max_tokens: 8191
+      price_per_1M: "$0.13"
+      best_for: "Highest quality, retrieval-critical"
+
+  cohere:
+    - name: "embed-v4"
+      dimensions: 1024
+      max_tokens: 512
+      features: ["search_document", "search_query", "classification"]
+      best_for: "Multilingual, separate query/doc models"
+
+  jina:
+    - name: "jina-embeddings-v3"
+      dimensions: 1024
+      max_tokens: 8192
+      best_for: "Long documents, code"
+
+  local:
+    - name: "BAAI/bge-m3"
+      dimensions: 1024
+      max_tokens: 8192
+      best_for: "Self-hosted, multilingual, free"
+
+    - name: "sentence-transformers/all-MiniLM-L6-v2"
+      dimensions: 384
+      max_tokens: 256
+      best_for: "Lightweight, fast, prototyping"
+
+selection_guide:
+  decision_tree:
+    - question: "Budget matters?"
+      yes: "text-embedding-3-small or local BGE-M3"
+      no: "text-embedding-3-large"
+
+    - question: "Need multilingual?"
+      yes: "Cohere embed-v4 or BGE-M3"
+      no: "OpenAI models"
+
+    - question: "Self-hosted required?"
+      yes: "BGE-M3 or sentence-transformers"
+      no: "OpenAI or Cohere (managed)"
+
+    - question: "Long documents (>2K tokens)?"
+      yes: "Jina v3 or BGE-M3 (8K context)"
+      no: "Any model works"
+
+  dimensionality:
+    description: |
+      Higher dimensions = better quality but more storage/compute.
+      OpenAI 3-large supports Matryoshka (reduce dims without retraining).
+    example: |
+      # Reduce OpenAI 3-large from 3072 to 256 dimensions
+      from openai import OpenAI
+      response = client.embeddings.create(
+          model="text-embedding-3-large",
+          input="text",
+          dimensions=256  # Matryoshka reduction
+      )
+
+# _DOMYH Awesome Code • Embedding Models_

package/.agent/skills/ai-ml/rag-patterns/data/evaluation.yaml

@@ -0,0 +1,92 @@
+# =============================================================================
+# evaluation.yaml — RAG Evaluation Framework
+# =============================================================================
+
+version: "1.0.0"
+
+ragas:
+  description: "Reference-free RAG evaluation framework"
+  metrics:
+    - name: faithfulness
+      description: "Are claims supported by retrieved context?"
+      range: "0.0 - 1.0"
+      formula: "supported_claims / total_claims"
+
+    - name: answer_relevancy
+      description: "Is the answer relevant to the question?"
+      range: "0.0 - 1.0"
+      method: "Generate N questions from answer, compare to original"
+
+    - name: context_precision
+      description: "Are relevant chunks ranked higher?"
+      range: "0.0 - 1.0"
+
+    - name: context_recall
+      description: "Are all relevant facts retrieved?"
+      range: "0.0 - 1.0"
+
+  example_python: |
+    from ragas import evaluate
+    from ragas.metrics import faithfulness, answer_relevancy, context_precision
+
+    result = evaluate(
+        dataset,
+        metrics=[faithfulness, answer_relevancy, context_precision],
+    )
+    print(result)
+    # {'faithfulness': 0.85, 'answer_relevancy': 0.92, 'context_precision': 0.78}
+
+custom_metrics:
+  - name: "Answer Correctness"
+    description: "Does the answer match the ground truth?"
+    method: "LLM-as-judge or exact match"
+
+  - name: "Hallucination Rate"
+    description: "% of claims not supported by context"
+    formula: "unsupported_claims / total_claims"
+    target: "< 5%"
+
+  - name: "Retrieval Hit Rate"
+    description: "% of queries where correct doc is in top-K"
+    formula: "queries_with_hit / total_queries"
+    target: "> 90%"
+
+  - name: "Latency"
+    description: "End-to-end response time"
+    components:
+      - "Embedding: ~50ms"
+      - "Vector search: ~20ms"
+      - "Reranking: ~200ms"
+      - "LLM generation: ~1-3s"
+    target: "< 3s total"
+
+evaluation_dataset:
+  creation: |
+    1. Collect 50-100 representative queries
+    2. For each query, identify correct source documents
+    3. Write expected answers (ground truth)
+    4. Include edge cases and ambiguous queries
+
+  format: |
+    {
+      "question": "What is the return policy?",
+      "ground_truth": "30-day return policy for unused items",
+      "contexts": ["Retrieved chunk 1", "Retrieved chunk 2"],
+      "answer": "RAG-generated answer"
+    }
+
+testing_pipeline:
+  stages:
+    - name: "Retrieval Quality"
+      metrics: ["context_precision", "context_recall", "hit_rate"]
+      test: "Does the retriever find relevant chunks?"
+
+    - name: "Generation Quality"
+      metrics: ["faithfulness", "answer_relevancy", "correctness"]
+      test: "Does the LLM use context correctly?"
+
+    - name: "End-to-End"
+      metrics: ["latency", "user_satisfaction"]
+      test: "Is the full pipeline acceptable?"
+
+# _DOMYH Awesome Code • RAG Evaluation_

package/.agent/skills/ai-ml/rag-patterns/data/retrieval-patterns.yaml

@@ -0,0 +1,101 @@
+# =============================================================================
+# retrieval-patterns.yaml — Advanced Retrieval Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+hybrid_search:
+  description: "Combine dense (vector) + sparse (keyword) search"
+  method: |
+    Score = α × dense_score + (1-α) × sparse_score
+    α = 0.7 (typical, tune per use case)
+  implementations:
+    - name: "Qdrant"
+      method: "Sparse + dense vectors natively"
+    - name: "Weaviate"
+      method: "BM25 + vector built-in"
+    - name: "pgvector + pg_trgm"
+      method: "Vector similarity + trigram text search"
+  example: |
+    # Qdrant hybrid search
+    from qdrant_client.models import SparseVector
+    results = client.query_points(
+        collection_name="docs",
+        prefetch=[
+            Prefetch(query=dense_vector, using="dense", limit=20),
+            Prefetch(query=sparse_vector, using="sparse", limit=20),
+        ],
+        query=FusionQuery(fusion=Fusion.RRF),  # Reciprocal Rank Fusion
+        limit=5,
+    )
+
+reranking:
+  description: "Re-score top-K results with a cross-encoder"
+  models:
+    - "Cohere Rerank v3"
+    - "BAAI/bge-reranker-v2-m3"
+    - "cross-encoder/ms-marco-MiniLM-L-6-v2"
+  pipeline: |
+    1. Retrieve top-20 from vector search
+    2. Re-rank with cross-encoder model
+    3. Return top-5 after reranking
+  example_python: |
+    from cohere import Client
+    co = Client("API_KEY")
+
+    results = co.rerank(
+        model="rerank-v3.5",
+        query="What is RAG?",
+        documents=retrieved_chunks,
+        top_n=5
+    )
+
+hyde:
+  name: "Hypothetical Document Embeddings"
+  description: |
+    Generate a hypothetical answer to the query, embed it, then
+    search for similar real documents. Improves retrieval for
+    questions that don't lexically match the source.
+  pipeline: |
+    Query → LLM generates hypothetical answer → Embed answer → Search
+  example_python: |
+    # 1. Generate hypothetical answer
+    hypothetical = llm.generate(f"Answer this question: {query}")
+
+    # 2. Embed the hypothetical answer
+    embedding = embed_model.encode(hypothetical)
+
+    # 3. Search with hypothetical embedding
+    results = vector_store.similarity_search(embedding, k=5)
+
+self_query:
+  description: "LLM extracts structured filters from natural language query"
+  example: |
+    Query: "What papers about transformers were published after 2023?"
+    → filter: {"year": {">": 2023}, "topic": "transformers"}
+    → vector search with metadata filter
+
+multi_query:
+  description: "Generate multiple query variants for broader retrieval"
+  pipeline: |
+    Original query → LLM generates 3-5 variants → Search each → Deduplicate → Rank
+  example: |
+    Query: "How to handle errors in Go?"
+    Variants:
+      - "Go error handling patterns"
+      - "golang error wrapping best practices"
+      - "Go error types and sentinel errors"
+
+contextual_compression:
+  description: "Extract only relevant parts from retrieved chunks"
+  pipeline: |
+    Retrieved chunk (500 tokens) → LLM extracts relevant sentences → Compressed (100 tokens)
+  benefit: "Fits more relevant context in LLM prompt"
+
+parent_document:
+  description: "Store small chunks for retrieval, return parent doc for context"
+  pipeline: |
+    Document → Split into small chunks (200 tokens) → Index
+    Query → Match small chunk → Return parent section (2000 tokens)
+
+# _DOMYH Awesome Code • Retrieval Patterns_

package/.agent/skills/ai-ml/rag-patterns/data/vector-databases.yaml

@@ -0,0 +1,103 @@
+# =============================================================================
+# vector-databases.yaml — Vector Database Comparison
+# =============================================================================
+
+version: "1.0.0"
+
+databases:
+  pgvector:
+    type: "PostgreSQL extension"
+    hosting: "Self-hosted or managed (Supabase, Neon)"
+    best_for: "Already using PostgreSQL, small-medium scale"
+    setup: |
+      CREATE EXTENSION vector;
+      CREATE TABLE documents (
+          id SERIAL PRIMARY KEY,
+          content TEXT,
+          metadata JSONB,
+          embedding vector(1536)
+      );
+      CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+    query: |
+      SELECT content, 1 - (embedding <=> $1) AS similarity
+      FROM documents
+      ORDER BY embedding <=> $1
+      LIMIT 5;
+
+  pinecone:
+    type: "Managed SaaS"
+    hosting: "Cloud (AWS, GCP, Azure)"
+    best_for: "Production, serverless, managed"
+    example_python: |
+      from pinecone import Pinecone
+      pc = Pinecone(api_key="YOUR_KEY")
+      index = pc.Index("my-index")
+
+      # Upsert
+      index.upsert(vectors=[
+          {"id": "doc1", "values": embedding, "metadata": {"source": "doc.pdf"}}
+      ])
+
+      # Query
+      results = index.query(vector=query_embedding, top_k=5, include_metadata=True)
+
+  qdrant:
+    type: "Self-hosted / Cloud"
+    hosting: "Docker, Kubernetes, Qdrant Cloud"
+    best_for: "Full control, advanced filtering"
+    features: ["Payload filtering", "Sparse vectors", "Hybrid search"]
+    example_python: |
+      from qdrant_client import QdrantClient
+      client = QdrantClient("localhost", port=6333)
+
+      client.upsert(collection_name="docs", points=[
+          {"id": 1, "vector": embedding, "payload": {"source": "doc.pdf"}}
+      ])
+
+      results = client.search(
+          collection_name="docs",
+          query_vector=query_embedding,
+          query_filter={"must": [{"key": "source", "match": {"value": "doc.pdf"}}]},
+          limit=5
+      )
+
+  chroma:
+    type: "Embedded / Server"
+    hosting: "In-process or Docker"
+    best_for: "Prototyping, development, small datasets"
+    example_python: |
+      import chromadb
+      client = chromadb.Client()
+      collection = client.create_collection("docs")
+
+      collection.add(
+          documents=["text1", "text2"],
+          metadatas=[{"source": "a"}, {"source": "b"}],
+          ids=["1", "2"]
+      )
+
+      results = collection.query(query_texts=["search query"], n_results=5)
+
+  weaviate:
+    type: "Self-hosted / Cloud"
+    best_for: "Multi-modal (text + images), hybrid search built-in"
+
+  milvus:
+    type: "Self-hosted"
+    best_for: "Large scale (billion vectors), GPU acceleration"
+
+selection_guide:
+  - scenario: "Already using PostgreSQL"
+    choice: "pgvector"
+  - scenario: "Need managed, production-ready"
+    choice: "Pinecone"
+  - scenario: "Need advanced filtering, self-hosted"
+    choice: "Qdrant"
+  - scenario: "Quick prototype, local dev"
+    choice: "Chroma"
+  - scenario: "Multi-modal (text + images)"
+    choice: "Weaviate"
+  - scenario: "Billion+ vectors, GPU"
+    choice: "Milvus"
+
+# _DOMYH Awesome Code • Vector Databases_

package/.agent/skills/ai-ml/vector-search/META.yaml

@@ -0,0 +1,63 @@
+name: vector-search
+version: "1.0.0"
+display: Vector Search & Embeddings
+category: ai-ml
+tier: 1
+priority: 2
+
+desc: "Vector databases & semantic search. Embeddings, similarity search, hybrid search (vector + BM25), indexing strategies, and production patterns."
+
+  ### Data Files (3 domains, ~21 patterns)
+  - vector-dbs.yaml: comparison table, features, pricing (7)
+  - embedding-models.yaml: model comparison, dimensions, perf (7)
+  - search-patterns.yaml: hybrid search, filtering, reranking (7)
+
+triggers:
+  file_patterns:
+    - "**/embeddings/**"
+    - "**/vector/**"
+    - "chromadb/**"
+  keywords:
+    - vector database
+    - vector search
+    - vector store
+    - embeddings
+    - semantic search
+    - similarity search
+    - cosine similarity
+    - HNSW
+    - ANN
+    - approximate nearest neighbor
+    - pinecone
+    - weaviate
+    - qdrant
+    - chromadb
+    - chroma
+    - milvus
+    - pgvector
+    - text embedding
+    - embedding model
+    - hybrid search
+    - dense retrieval
+
+caps:
+  - Embedding generation (OpenAI, Cohere, Voyage, local models)
+  - Vector DB selection (Pinecone, Weaviate, Qdrant, ChromaDB, Milvus)
+  - pgvector (PostgreSQL native vector search)
+  - Indexing strategies (HNSW, IVF, PQ, SCANN)
+  - Hybrid Search (vector + keyword BM25)
+  - Metadata filtering & namespace isolation
+  - Batch upsert & real-time indexing
+  - Distance metrics (cosine, L2 euclidean, dot product)
+  - Reranking (Cohere Rerank, cross-encoder)
+  - Chunking strategies for documents
+
+related_skills:
+  - ai-agents
+  - rag-patterns
+  - database
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/ai-ml/vector-search/data"
+  preload_data: true