@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/ai-ml/ai-agents/data/orchestration-patterns.yaml

@@ -0,0 +1,101 @@
+# AI Agent Orchestration Patterns - HSA AI Agents Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: ai-agents
+  domain: orchestration
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: orch001
+    name: supervisor
+    category: orchestration
+    description: Single supervisor routes tasks to specialized agents
+    text: supervisor orchestrator router delegate specialized agent
+    example: |
+      // LangGraph supervisor
+      const graph = new StateGraph({ channels: { messages, next } })
+        .addNode("supervisor", supervisorAgent)
+        .addNode("researcher", researchAgent)
+        .addNode("coder", codingAgent)
+        .addEdge("supervisor", routeToAgent)
+        .compile();
+    best_for: "Complex tasks with clear sub-task boundaries"
+
+  - id: orch002
+    name: swarm
+    category: orchestration
+    description: Peer-to-peer agents collaborate without central control
+    text: swarm peer collaborative decentralized agents handoff
+    example: |
+      // OpenAI Swarm pattern
+      const triage = new Agent({ name: "Triage", handoffs: [sales, support] });
+      const sales = new Agent({ name: "Sales", tools: [createQuote] });
+    best_for: "Customer service, collaborative workflows"
+
+  - id: orch003
+    name: sequential
+    category: orchestration
+    description: Linear pipeline of agents, output feeds next input
+    text: sequential pipeline chain linear flow step by step
+    example: |
+      const pipeline = research.pipe(draft).pipe(review).pipe(publish);
+      const result = await pipeline.invoke({ topic: "MCP best practices" });
+    best_for: "Content creation, ETL, simple workflows"
+
+  - id: orch004
+    name: hierarchical
+    category: orchestration
+    description: Manager agents delegate to worker agents recursively
+    text: hierarchical manager worker delegation tree recursive
+    best_for: "Enterprise workflows, complex project management"
+
+  - id: orch005
+    name: langgraph_setup
+    category: framework
+    description: LangGraph state machine for agent workflows
+    text: langgraph state graph node edge checkpoint persistence
+    example: |
+      const graph = new StateGraph(AgentState)
+        .addNode("agent", callModel)
+        .addNode("tools", toolNode)
+        .addEdge(START, "agent")
+        .addConditionalEdges("agent", shouldContinue, { continue: "tools", end: END })
+        .addEdge("tools", "agent")
+        .compile({ checkpointer: new MemorySaver() });
+
+  - id: orch006
+    name: crewai_setup
+    category: framework
+    description: CrewAI role-based multi-agent collaboration
+    text: crewai crew agent task role goal backstory
+    example: |
+      researcher = Agent(role="Researcher", goal="Find information", tools=[search])
+      writer = Agent(role="Writer", goal="Write content")
+      crew = Crew(agents=[researcher, writer], tasks=[research_task, write_task])
+
+  - id: orch007
+    name: hitl
+    category: production
+    description: Human-in-the-loop approval for critical actions
+    text: human in the loop approval review critical destructive confirm
+    example: |
+      // LangGraph interrupt pattern
+      .addNode("approval", async (state) => {
+        return { needsApproval: true, action: state.proposedAction };
+        // Graph pauses here until human approves
+      })
+
+  - id: orch008
+    name: error_recovery
+    category: production
+    description: Agent error recovery and retry strategies
+    text: error recovery retry fallback checkpoint resume
+    example: |
+      const config = {
+        maxRetries: 3,
+        fallbackModel: "gpt-4o-mini",
+        checkpointOnSuccess: true
+      };

package/.agent/skills/ai-ml/gemini-live/META.yaml

@@ -0,0 +1,55 @@
+name: gemini-live
+version: "1.0.0"
+display: Gemini Live & Advanced APIs
+category: ai-ml
+tier: 1
+priority: 4
+
+desc: "Advanced Gemini APIs: Live API (real-time voice/video streaming via WebSocket), Context Caching (implicit + explicit TTL), Code Execution (Python sandbox, 30+ libs), Grounding with Google Search (citations). 28+ patterns."
+
+triggers:
+  file_patterns: []
+  keywords:
+    - live api
+    - real-time ai
+    - gemini live
+    - context caching
+    - code execution
+    - gemini sandbox
+    - grounding
+    - google search grounding
+    - implicit caching
+    - explicit caching
+    - voice activity detection
+    - session management
+    - ephemeral token
+    - websocket ai
+    - streaming ai
+  intents:
+    - build real-time AI app
+    - cache context for LLM
+    - execute code with gemini
+    - ground responses with search
+    - stream audio/video to AI
+
+caps:
+  - Live API (WebSocket, audio/video streaming)
+  - Voice Activity Detection (VAD)
+  - Context Caching (implicit + explicit TTL, cost savings)
+  - Code Execution (Python sandbox, 30+ libs including TensorFlow)
+  - Grounding with Google Search (real-time citations)
+  - Multi-tool combinations (Search + Code + Functions)
+  - Session management for long conversations
+  - Ephemeral tokens (client-side auth)
+  - Partner integrations (Pipecat, LiveKit, ADK)
+
+related_skills:
+  - ai-agents
+  - prompt-engineering
+  - gemini-media-gen
+
+data_files:
+  - data/live-api.yaml
+  - data/context-caching.yaml
+  - data/code-execution.yaml
+  - data/grounding.yaml

package/.agent/skills/ai-ml/gemini-live/SKILL.md

@@ -0,0 +1,155 @@
+# Gemini Live & Advanced APIs
+
+> 🔴 **Real-time streaming + Advanced Gemini capabilities**
+> **APIs**: Live API + Context Caching + Code Execution + Grounding | **Patterns**: 28+
+
+---
+
+## Quick Reference
+
+| What You Need                  | Data File              | Patterns |
+| ------------------------------ | ---------------------- | -------- |
+| Live API (WebSocket streaming) | `live-api.yaml`        | 8        |
+| Context Caching                | `context-caching.yaml` | 6        |
+| Code Execution (sandbox)       | `code-execution.yaml`  | 8        |
+| Grounding with Google Search   | `grounding.yaml`       | 6        |
+
+---
+
+## Live API Overview
+
+```
+┌──────────────────────────────────────────┐
+│  Client (Audio/Video/Text)               │
+│    ↓ WebSocket                           │
+│  Gemini Live API                         │
+│    ↓ Real-time processing                │
+│  Response (Audio/Text)                   │
+│    + Voice Activity Detection            │
+│    + Tool calling                        │
+│    + Session management                  │
+└──────────────────────────────────────────┘
+```
+
+### Implementation Approaches
+
+| Approach             | Description                  | Use Case                      |
+| -------------------- | ---------------------------- | ----------------------------- |
+| **Server-to-server** | Backend connects to Live API | Secure, full control          |
+| **Client-to-server** | Frontend connects directly   | Low latency, ephemeral tokens |
+
+### Partner Integrations
+
+| Partner                        | Description                       |
+| ------------------------------ | --------------------------------- |
+| **Pipecat** (Daily)            | Real-time AI chatbot framework    |
+| **LiveKit**                    | Agents with Gemini Live           |
+| **Fishjam** (Software Mansion) | Live video/audio streaming        |
+| **ADK** (Google)               | Agent Development Kit             |
+| **Vision Agents** (Stream)     | Real-time voice/video AI          |
+| **Voximplant**                 | Inbound/outbound call integration |
+
+---
+
+## Context Caching
+
+| Type         | Description                   | Cost                |
+| ------------ | ----------------------------- | ------------------- |
+| **Implicit** | Auto-enabled, no code changes | Free (auto savings) |
+| **Explicit** | Manual cache with TTL control | Reduced input cost  |
+
+### When to Use Explicit Caching
+
+- Chatbots with extensive system instructions
+- Repetitive analysis of lengthy video files
+- Recurring queries against large document sets
+- Frequent code repository analysis
+
+### Implicit Caching Tips
+
+- Put large, common content at beginning of prompt
+- Send similar-prefix requests close together in time
+- Check `usage_metadata.cached_content_token_count`
+
+---
+
+## Code Execution
+
+**Python sandbox with 30+ libraries** — model writes, runs, and iterates on code.
+
+### Key Libraries Available
+
+| Category          | Libraries                                   |
+| ----------------- | ------------------------------------------- |
+| **Data Science**  | numpy, pandas, scipy, scikit-learn          |
+| **Visualization** | matplotlib, seaborn                         |
+| **Image**         | pillow, opencv-python, imageio              |
+| **Documents**     | PyPDF2, python-docx, python-pptx, reportlab |
+| **ML**            | tensorflow                                  |
+| **Math**          | sympy, mpmath                               |
+
+### Gemini 3 — Code Execution with Images
+
+New in Gemini 3: model can manipulate and inspect images via code:
+
+- **Zoom and inspect**: Auto-crops to examine small details
+- **Visual math**: Multi-step calculations from image data
+- **Image annotation**: Draws arrows and labels on images
+
+### Billing
+
+- No extra charge for code execution
+- Billed at standard input/output token rates
+- Generated code + results count as output tokens
+
+---
+
+## Grounding with Google Search
+
+```
+User Prompt → Model → Google Search → Synthesized Response + Citations
+```
+
+### Response Structure
+
+```json
+{
+  "groundingMetadata": {
+    "webSearchQueries": ["search terms used"],
+    "groundingChunks": [{ "web": { "uri": "...", "title": "..." } }],
+    "groundingSupports": [
+      { "segment": { "text": "claim..." }, "groundingChunkIndices": [0, 1] }
+    ]
+  }
+}
+```
+
+### Building Citations
+
+- `groundingChunks` → source URLs and titles
+- `groundingSupports` → maps text segments to sources
+- `searchEntryPoint` → HTML/CSS for search widget (required by ToS)
+
+---
+
+## Multi-Tool Combinations
+
+| Combo              | Use Case                        |
+| ------------------ | ------------------------------- |
+| Search + Functions | Real-time data + custom actions |
+| Code + Functions   | Compute + external data         |
+| Search + Code      | Research + data analysis        |
+| All + MCP          | Complex agentic workflows       |
+
+Live API supports ALL tool combinations simultaneously.
+
+---
+
+## HSA Integration
+
+| Domain | Query Examples                               |
+| ------ | -------------------------------------------- |
+| Live   | "WebSocket streaming real-time audio VAD"    |
+| Cache  | "context caching TTL cost savings implicit"  |
+| Code   | "sandbox Python execution tensorflow pandas" |
+| Ground | "Google Search grounding citations metadata" |

package/.agent/skills/ai-ml/gemini-live/data/code-execution.yaml

@@ -0,0 +1,131 @@
+# =============================================================================
+# code-execution.yaml — Gemini Code Execution Patterns
+# =============================================================================
+# 8 patterns for Python sandbox execution
+# Source: https://ai.google.dev/gemini-api/docs/code-execution
+# =============================================================================
+
+version: "1.0.0"
+total_patterns: 8
+
+overview:
+  description: "Model generates and runs Python code, iterates on results"
+  language: "Python only (can generate other languages, but only runs Python)"
+  cost: "No additional charge (standard token billing)"
+  sandbox: true
+  custom_libraries: false
+
+supported_libraries:
+  data_science:
+    - numpy
+    - pandas
+    - scipy
+    - scikit-learn
+  visualization:
+    - matplotlib
+    - seaborn
+  image:
+    - pillow
+    - opencv-python
+    - imageio
+  documents:
+    - PyPDF2
+    - python-docx
+    - python-pptx
+    - reportlab
+    - fpdf
+    - openpyxl
+    - xlrd
+  math:
+    - sympy
+    - mpmath
+  ml:
+    - tensorflow
+  parsing:
+    - lxml
+    - jsonschema
+    - pyparsing
+    - striprtf
+  other:
+    - chess
+    - geopandas
+    - jinja2
+    - joblib
+    - tabulate
+    - contourpy
+    - protobuf
+    - packaging
+
+api_usage:
+  enable:
+    python: |
+      from google import genai
+      from google.genai import types
+
+      client = genai.Client(api_key="API_KEY")
+      response = client.models.generate_content(
+          model="gemini-2.5-flash",
+          contents="Calculate the first 15 Fibonacci numbers and plot them",
+          config=types.GenerateContentConfig(
+              tools=[types.Tool(code_execution=types.ToolCodeExecution())]
+          )
+      )
+    javascript: |
+      const response = await ai.models.generateContent({
+          model: "gemini-2.5-flash",
+          contents: "Calculate Fibonacci and plot",
+          config: { tools: [{ codeExecution: {} }] }
+      });
+
+gemini3_image_execution:
+  description: "Gemini 3 Flash: write code to manipulate and inspect images"
+  use_cases:
+    zoom_and_inspect:
+      desc: "Model detects small details, crops and re-examines at higher resolution"
+      example: "Reading a distant gauge in a photo"
+    visual_math:
+      desc: "Multi-step calculations using code on image data"
+      example: "Summing line items on a receipt"
+    image_annotation:
+      desc: "Draw arrows, labels, highlights on images"
+      example: "Annotating a diagram to show relationships"
+  enable:
+    python: |
+      response = client.models.generate_content(
+          model="gemini-3-flash",
+          contents=[image, "What is the reading on the gauge?"],
+          config=types.GenerateContentConfig(
+              tools=[types.Tool(code_execution=types.ToolCodeExecution())]
+          )
+      )
+
+chat_mode:
+  description: "Use code execution in multi-turn chat"
+  benefit: "Model can build on previous code results"
+  pattern:
+    - "Turn 1: 'Load and analyze this data'"
+    - "Turn 2: 'Now visualize the top 10 results'"
+    - "Turn 3: 'Apply a trend line and predict next quarter'"
+
+billing:
+  description: "Code execution billing model"
+  rules:
+    - "Input tokens: billed once (your prompt)"
+    - "Intermediate tokens: generated code + execution results (billed as input)"
+    - "Output tokens: final summary + code + results"
+    - "Check usage_metadata for intermediate_token_count"
+
+limitations:
+  - "Can only generate and execute code (no media artifacts)"
+  - "Enabling may cause regressions in creative tasks"
+  - "Cannot install custom libraries"
+  - "Model variation in code execution quality"
+
+tool_combinations:
+  - "Code Execution + Google Search = Research + Analysis"
+  - "Code Execution + Function Calling = Compute + External Data"
+  - "All three combined via Live API"
+
+# =============================================================================
+# _DOMYH Awesome Code • Code Execution v1.0_
+# =============================================================================

package/.agent/skills/ai-ml/gemini-live/data/context-caching.yaml

@@ -0,0 +1,96 @@
+# =============================================================================
+# context-caching.yaml — Gemini Context Caching Patterns
+# =============================================================================
+# 6 patterns for implicit and explicit caching strategies
+# Source: https://ai.google.dev/gemini-api/docs/caching
+# =============================================================================
+
+version: "1.0.0"
+total_patterns: 6
+
+implicit_caching:
+  description: "Automatic cost savings — no code changes needed"
+  enabled: "Default (all Gemini models)"
+  effective_since: "May 8, 2025"
+  how_it_works:
+    - "Gemini auto-caches repeated input prefixes"
+    - "Cost savings passed on automatically"
+    - "No configuration needed"
+  optimization_tips:
+    - "Put large, common content at BEGINNING of prompt"
+    - "Send similar-prefix requests close together in time"
+    - "Check usage_metadata.cached_content_token_count for hits"
+  minimum_token_count:
+    gemini_2_5_flash: 1024
+    gemini_2_5_pro: 2048
+    gemini_3_flash: 1024
+
+explicit_caching:
+  description: "Manual cache creation with TTL control"
+  how_it_works:
+    - "Upload content to cache once"
+    - "Reference cached content in subsequent requests"
+    - "Set TTL (default: 1 hour)"
+    - "Pay reduced rate for cached tokens"
+
+  operations:
+    create:
+      python: |
+        from google import genai
+        client = genai.Client(api_key="API_KEY")
+        cache = client.caches.create(
+            model="gemini-2.5-flash",
+            config=genai.types.CreateCachedContentConfig(
+                display_name="my-cache",
+                contents=[large_document],
+                ttl="3600s"  # 1 hour
+            )
+        )
+
+    use:
+      python: |
+        response = client.models.generate_content(
+            model="gemini-2.5-flash",
+            contents="Summarize the key findings",
+            config=genai.types.GenerateContentConfig(
+                cached_content=cache.name
+            )
+        )
+
+    list:
+      python: |
+        for cache in client.caches.list():
+            print(f"{cache.display_name}: {cache.expire_time}")
+
+    update_ttl:
+      python: |
+        client.caches.update(
+            name=cache.name,
+            config=genai.types.UpdateCachedContentConfig(ttl="7200s")
+        )
+
+    delete:
+      python: |
+        client.caches.delete(name=cache.name)
+
+use_cases:
+  - scenario: "Chatbot with large system instructions"
+    benefit: "Cache system prompt, pay once"
+  - scenario: "Repetitive video analysis"
+    benefit: "Cache video, query multiple times"
+  - scenario: "Document Q&A"
+    benefit: "Cache document set, ask many questions"
+  - scenario: "Code repository analysis"
+    benefit: "Cache codebase, run multiple audits"
+
+cost_analysis:
+  description: "Cost savings from explicit caching"
+  factors:
+    - "Cached token rate < regular input rate"
+    - "Savings increase with more requests to same cache"
+    - "TTL cost: longer cache = higher storage cost"
+    - "Break-even: typically 3-5 requests to same content"
+
+# =============================================================================
+# _DOMYH Awesome Code • Context Caching v1.0_
+# =============================================================================

package/.agent/skills/ai-ml/gemini-live/data/grounding.yaml

@@ -0,0 +1,97 @@
+# =============================================================================
+# grounding.yaml — Grounding with Google Search Patterns
+# =============================================================================
+# 6 patterns for real-time web grounding and citation building
+# Source: https://ai.google.dev/gemini-api/docs/grounding
+# =============================================================================
+
+version: "1.0.0"
+total_patterns: 6
+
+overview:
+  description: "Connect Gemini to real-time web content via Google Search"
+  benefits:
+    - "Increase factual accuracy (reduce hallucinations)"
+    - "Access real-time information"
+    - "Provide verifiable citations"
+  supported_languages: "All available languages"
+
+how_it_works:
+  flow:
+    - step: "User Prompt"
+      desc: "Your app sends prompt with google_search tool enabled"
+    - step: "Prompt Analysis"
+      desc: "Model determines if search can improve answer"
+    - step: "Google Search"
+      desc: "Model auto-generates and executes search queries"
+    - step: "Results Processing"
+      desc: "Model synthesizes search results into response"
+    - step: "Grounded Response"
+      desc: "Response includes text + groundingMetadata with citations"
+
+api_usage:
+  enable:
+    python: |
+      from google import genai
+      from google.genai import types
+
+      client = genai.Client(api_key="API_KEY")
+      response = client.models.generate_content(
+          model="gemini-2.5-flash",
+          contents="Who won Euro 2024?",
+          config=types.GenerateContentConfig(
+              tools=[types.Tool(google_search=types.GoogleSearch())]
+          )
+      )
+    javascript: |
+      const response = await ai.models.generateContent({
+          model: "gemini-2.5-flash",
+          contents: "Who won Euro 2024?",
+          config: { tools: [{ googleSearch: {} }] }
+      });
+
+response_structure:
+  groundingMetadata:
+    webSearchQueries:
+      desc: "Array of search queries used"
+      use: "Debugging, understanding model reasoning"
+    searchEntryPoint:
+      desc: "HTML/CSS for search suggestion widget"
+      use: "Required by Terms of Service for web display"
+    groundingChunks:
+      desc: "Array of web sources (uri + title)"
+      use: "Build source list, link verification"
+    groundingSupports:
+      desc: "Maps text segments to source citations"
+      fields:
+        - "segment.startIndex / endIndex — text range"
+        - "segment.text — the grounded text"
+        - "groundingChunkIndices — which sources support this claim"
+      use: "Build inline citations, highlight sourced claims"
+
+building_citations:
+  description: "How to create inline citations from grounding response"
+  steps:
+    - "Parse groundingChunks for source URLs"
+    - "Parse groundingSupports for text-to-source mapping"
+    - "For each support, link text range to source(s)"
+    - "Render as [text](source_url) or footnotes"
+  example: |
+    # Text: "Spain won Euro 2024, defeating England 2-1"
+    # groundingSupports[0].groundingChunkIndices = [0]
+    # groundingChunks[0].web.uri = "https://..."
+    # → "Spain won Euro 2024 [1], defeating England 2-1"
+
+url_context_tool:
+  description: "Combine grounding with specific URL analysis"
+  how: "Use URL context tool alongside Google Search"
+  benefit: "Ground in both public web AND specific URLs you provide"
+
+pricing:
+  description: "Grounding incurs search API costs"
+  tip: "Use grounding selectively — not all queries need real-time data"
+  free_tier: "Available with API key"
+
+# =============================================================================
+# _DOMYH Awesome Code • Grounding v1.0_
+# =============================================================================