everything-gemini 2.1.0 → 2.5.0

package/skills/spanner-graph-rag/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: spanner-graph-rag
+description: Implements Google Cloud Spanner Graph schemas, ISO GQL queries, knowledge graph traversal, and hybrid graph-vector RAG pipelines for Gemini agents.
+---
+
+# Spanner Graph & Knowledge Graph RAG
+
+Designs, provisions, and queries distributed enterprise knowledge graphs using Google Cloud Spanner Graph. Implements ISO GQL (Graph Query Language) multi-hop traversals, cyclic graph pattern matching, and hybrid Graph-Vector RAG to eliminate hallucinations across complex organizational entity networks.
+
+---
+
+## 1. Architecture: Graph-Grounded Agentic Reasoning
+
+```
+                                Google Cloud Spanner
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       SPANNER DISTRIBUTED GRAPH ENGINE                      │
+│                                                                             │
+│   ┌─────────────────────┐                   ┌───────────────────────────┐   │
+│   │ Node Table: Account │                   │ Node Table: Microservice  │   │
+│   │ (Enterprise Org)    │                   │ (Infrastructure Artifact) │   │
+│   └──────────┬──────────┘                   └─────────────┬─────────────┘   │
+│              │                                            │                 │
+│              │       Edge: OWNS             Edge: CALLS   │                 │
+│              └────────────────► [TEAM] ───────────────────┘                 │
+│                                   │                                         │
+│                                   ▼                                         │
+│                    ┌─────────────────────────────┐                          │
+│                    │ Edge: MUTATES_RESOURCE      │                          │
+│                    │ Destination: Cloud Database │                          │
+│                    └──────────────┬──────────────┘                          │
+│                                   │                                         │
+│                                   ▼                                         │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ ISO GQL Multi-Hop Graph Traversal             │                │
+│            │ MATCH (t:Team)-[:CALLS*1..3]->(m:Service)     │                │
+│            └──────────────────────┬────────────────────────┘                │
+│                                   │ Grounded Entity Context                 │
+│                                   ▼                                         │
+│            ┌───────────────────────────────────────────────┐                │
+│            │ Gemini 2.0 / 3.8 Reasoning & Action Engine    │                │
+│            │ Zero hallucination on architectural blast radius│               │
+│            └───────────────────────────────────────────────┘                │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Spanner Graph DDL (`CREATE PROPERTY GRAPH`)
+
+Define nodes, edges, and relationship labels on top of strongly consistent Spanner tables:
+
+```sql
+-- 1. Base Relational Tables
+CREATE TABLE Services (
+  service_id STRING(64) NOT NULL,
+  name STRING(128) NOT NULL,
+  tier STRING(32) NOT NULL,
+  owner_team STRING(64) NOT NULL,
+  created_at TIMESTAMP OPTIONS (allow_commit_timestamp = true)
+) PRIMARY KEY (service_id);
+
+CREATE TABLE Dependencies (
+  caller_id STRING(64) NOT NULL,
+  target_id STRING(64) NOT NULL,
+  protocol STRING(32) NOT NULL,
+  criticality STRING(16) NOT NULL,
+  CONSTRAINT FK_Caller FOREIGN KEY (caller_id) REFERENCES Services (service_id),
+  CONSTRAINT FK_Target FOREIGN KEY (target_id) REFERENCES Services (service_id)
+) PRIMARY KEY (caller_id, target_id);
+
+-- 2. Property Graph Definition (ISO GQL Standard)
+CREATE PROPERTY GRAPH ServiceArchitectureGraph
+  VERTEX TABLES (
+    Services
+      LABEL Service
+      PROPERTIES (service_id, name, tier, owner_team)
+  )
+  EDGE TABLES (
+    Dependencies
+      SOURCE KEY (caller_id) REFERENCES Services (service_id)
+      DESTINATION KEY (target_id) REFERENCES Services (service_id)
+      LABEL CALLS
+      PROPERTIES (protocol, criticality)
+  );
+```
+
+---
+
+## 3. ISO GQL Graph Traversal Queries
+
+Execute declarative graph pattern matching directly in Spanner SQL:
+
+```sql
+-- Multi-hop blast-radius query: Find all downstream services impacted by an outage
+GRAPH ServiceArchitectureGraph
+MATCH (root:Service {service_id: 'payment-gateway'})
+      -[:CALLS*1..3]-> (downstream:Service)
+WHERE downstream.tier = 'TIER_1'
+RETURN DISTINCT
+  root.name AS failing_service,
+  downstream.name AS impacted_dependency,
+  downstream.owner_team AS oncall_team;
+```
+
+---
+
+## 4. Python SDK Graph-Vector RAG Pipeline
+
+Combines topological graph queries with Gemini reasoning to assess infrastructure change risk:
+
+```python
+from google.cloud import spanner
+from google import genai
+
+spanner_client = spanner.Client()
+instance = spanner_client.instance("production-instance")
+database = instance.database("architecture-db")
+gemini_client = genai.Client()
+
+def analyze_architectural_blast_radius(failing_service_id: str) -> str:
+    """Executes ISO GQL query in Spanner Graph and reasons over downstream risks with Gemini."""
+    gql_query = """
+    GRAPH ServiceArchitectureGraph
+    MATCH (s:Service {service_id: @serviceId})-[e:CALLS*1..4]->(dep:Service)
+    RETURN DISTINCT s.name AS root_service, dep.name AS dependency, dep.tier AS tier, dep.owner_team AS team
+    """
+    
+    with database.snapshot() as snapshot:
+        results = list(snapshot.execute_sql(
+            gql_query,
+            params={"serviceId": failing_service_id},
+            param_types={"serviceId": spanner.param_types.STRING}
+        ))
+    
+    # Format graph path topology into structured context
+    graph_context = "\n".join([
+        f"- Dependency: {row[1]} (Tier: {row[2]}, Team: {row[3]})"
+        for row in results
+    ])
+    
+    # Reason with Gemini using strictly grounded graph topology
+    prompt = f"""
+    The following microservice is experiencing an outage: {failing_service_id}
+    Here is the verified dependency graph topology from Spanner Graph:
+    {graph_context}
+    
+    Provide an actionable incident response triage plan, identifying on-call escalations.
+    """
+    
+    response = gemini_client.models.generate_content(
+        model="gemini-2.0-flash",
+        contents=prompt
+    )
+    return response.text
+```
+
+---
+
+## 5. Enterprise Best Practices & Anti-Patterns
+
+| Category | Recommended Pattern | Anti-Pattern |
+| :--- | :--- | :--- |
+| **Topology Modeling** | Use Directed Property Graphs with foreign keys enforcing referential integrity | Storing graph edges in unindexed JSON arrays |
+| **Path Search Depth** | Bound variable-length path traversals (e.g. `[:CALLS*1..4]`) | Unbounded path queries (`[:CALLS*]`) causing exponential scans |
+| **Hybrid RAG** | Retrieve exact entity graph topology from Spanner before prompt construction | Letting LLMs guess multi-hop dependencies from vector embeddings alone |
+| **Transactions** | Execute read-only graph traversals inside Spanner read-only snapshots | Mixing long-running graph analyses into interactive read-write transactions |

package/skills/vertex-ai-feature-store/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: vertex-ai-feature-store
+description: Provisions and queries Google Cloud Vertex AI Feature Store, point-in-time correct historical joins, low-latency online serving, and Gemini embedding feature tables.
+---
+
+# Vertex AI Feature Store & Embeddings Serving
+
+Architects, provisions, and serves machine learning features and vector representations using Google Cloud Vertex AI Feature Store. Covers BigQuery-backed offline storage, point-in-time joins, low-latency online feature serving, and real-time agent memory retrieval.
+
+---
+
+## 1. Architecture: Vertex AI Feature Store
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         VERTEX AI FEATURE STORE                             │
+│                                                                             │
+│   ┌─────────────────────┐                   ┌───────────────────────────┐   │
+│   │ BigQuery Lakehouse  │                   │ Streaming Ingestion       │   │
+│   │ (Offline Gold Data) │                   │ (Pub/Sub + Dataflow)      │   │
+│   └──────────┬──────────┘                   └─────────────┬─────────────┘   │
+│              │                                            │                 │
+│              ▼                                            ▼                 │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │ Feature Registry & View Definitions (BigQuery-backed Feature Store) │   │
+│   │ • Entity: user_id, repo_id, session_id                              │   │
+│   │ • Embeddings: text_embedding_004 (768-dim)                          │   │
+│   └──────────────────┬────────────────────────────┬─────────────────────┘   │
+│                      │                            │                         │
+│                      ▼ Offline                    ▼ Online (<10ms)          │
+│   ┌─────────────────────────────┐      ┌─────────────────────────────┐      │
+│   │ Point-in-Time Correct       │      │ Optimized Online Serving    │      │
+│   │ Historical Training Joins   │      │ (Bigtable / Cache Engine)   │      │
+│   └─────────────────────────────┘      └─────────────────────────────┘      │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Infrastructure Provisioning (`gcloud`)
+
+Set up a Feature Online Store optimized for sub-10ms feature retrieval:
+
+```bash
+# 1. Create Feature Online Store with optimized serving
+gcloud vertex-ai feature-online-stores create agent-memory-store \
+  --location=us-central1 \
+  --dedicated-serving-nodes-min=1 \
+  --dedicated-serving-nodes-max=5
+
+# 2. Create Feature View backed by BigQuery table
+gcloud vertex-ai feature-views create user-profile-features \
+  --feature-online-store=agent-memory-store \
+  --location=us-central1 \
+  --bigquery-table=projects/my_project/datasets/features/tables/user_profiles \
+  --entity-id-columns=user_id \
+  --cron-schedule="0 */4 * * *"
+```
+
+---
+
+## 3. Real-Time Online Feature Retrieval (Python SDK)
+
+Query real-time feature vectors inside an agent execution turn:
+
+```python
+from google.cloud import aiplatform_v1beta1 as vertex_ai
+
+client = vertex_ai.FeatureOnlineStoreServiceClient()
+
+def fetch_agent_session_features(user_id: str) -> dict:
+    """Fetches real-time developer context and historical preference vectors."""
+    feature_view_path = client.feature_view_path(
+        project="my_project",
+        location="us-central1",
+        feature_online_store="agent-memory-store",
+        feature_view="user-profile-features"
+    )
+    
+    response = client.fetch_feature_values(
+        request=vertex_ai.FetchFeatureValuesRequest(
+            feature_view=feature_view_path,
+            data_key=vertex_ai.FeatureViewDataKey(key=user_id)
+        )
+    )
+    
+    return {
+        field.name: field.value
+        for field in response.key_values.features
+    }
+```
+
+---
+
+## 4. Point-in-Time Correct Offline Joins
+
+Avoid data leakage in offline agent evaluation benchmarks:
+
+```sql
+SELECT
+  observations.task_id,
+  observations.timestamp,
+  features.seniority_level,
+  features.preferred_framework,
+  features.embedding_vector
+FROM `my_project.evals.agent_runs` AS observations
+POINT_IN_TIME JOIN `my_project.features.user_profiles` AS features
+  ON observations.user_id = features.user_id
+  AND observations.timestamp >= features.feature_timestamp;
+```

package/skills/webrtc-agent-gateway/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: webrtc-agent-gateway
+description: Architect and deploy ultra-low latency WebRTC audio duplex gateways, Opus audio transcoding, STUN/TURN ICE candidate negotiation, and real-time voice streaming for Gemini Live pair programming.
+---
+
+# WebRTC Agent Gateway (Ultra-Low Latency Duplex Voice Streaming)
+
+Architects, secures, and deploys production-grade WebRTC media gateways that bridge browser/IDE client media streams directly into the Google Gemini Live API. Implements bidirectional Opus/PCM audio transcoding, interactive data channels, STUN/TURN NAT traversal, and jitter-buffer optimization for sub-200ms voice pair-programming.
+
+---
+
+## 1. WebRTC Duplex Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       WEBRTC MEDIA GATEWAY TOPOLOGY                         │
+│                                                                             │
+│   ┌─────────────────────┐      WebRTC PeerConnection     ┌────────────────┐ │
+│   │ Developer Browser   │◄──────────────────────────────►│ WebRTC Gateway │ │
+│   │ / Antigravity IDE   │   SRTP / Opus Audio Tracks     │ (aiortc / Go)  │ │
+│   └─────────────────────┘   SCTP DataChannel (Events)    └───────┬────────┘ │
+│              │                                                   │          │
+│              │ SDP Offer / Answer (HTTPS / WSS)                  │          │
+│              ▼                                                   ▼          │
+│   ┌─────────────────────┐                            ┌────────────────────┐ │
+│   │ Coturn STUN / TURN  │                            │ Google Gemini Live │ │
+│   │ NAT Traversal Relay │                            │ WebSocket Endpoint │ │
+│   └─────────────────────┘                            └────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Python aiortc WebRTC Gateway Implementation
+
+Below is a production-grade WebRTC audio bridge receiving developer microphone tracks, transcoding Opus to PCM 16kHz for Gemini Live, and streaming back synthesized agent speech:
+
+```python
+import asyncio
+import json
+import fractions
+import time
+from aiortc import RTCPeerConnection, RTCSessionDescription, MediaStreamTrack
+from aiortc.contrib.media import MediaBlackhole
+from av import AudioResampler, AudioFrame
+from google import genai
+from google.genai import types
+
+class GeminiLiveAudioTrack(MediaStreamTrack):
+    """Generates outgoing WebRTC audio frames from Gemini Live synthesized speech."""
+    kind = "audio"
+
+    def __init__(self):
+        super().__init__()
+        self.queue = asyncio.Queue()
+        self._sample_rate = 48000
+        self._samples_per_frame = 960  # 20ms at 48kHz
+        self._pts = 0
+
+    def push_pcm_bytes(self, pcm_data: bytes):
+        """Pushes raw 24kHz/16kHz PCM audio bytes from Gemini into the WebRTC audio queue."""
+        self.queue.put_nowait(pcm_data)
+
+    async def recv(self):
+        pcm_chunk = await self.queue.get()
+        frame = AudioFrame(format="s16", layout="mono", samples=self._samples_per_frame)
+        frame.planes[0].update(pcm_chunk[:frame.linesizes[0]])
+        frame.sample_rate = self._sample_rate
+        frame.time_base = fractions.Fraction(1, self._sample_rate)
+        frame.pts = self._pts
+        self._pts += self._samples_per_frame
+        return frame
+
+class WebRTCAgentGateway:
+    def __init__(self, gemini_api_key: str):
+        self.client = genai.Client(api_key=gemini_api_key)
+        self.pcs = set()
+
+    async def handle_offer(self, sdp_offer: str, sdp_type: str = "offer") -> dict:
+        pc = RTCPeerConnection()
+        self.pcs.add(pc)
+
+        outgoing_audio = GeminiLiveAudioTrack()
+        pc.addTrack(outgoing_audio)
+
+        @pc.on("track")
+        def on_track(track):
+            if track.kind == "audio":
+                asyncio.create_task(self._relay_to_gemini(track, outgoing_audio))
+
+        @pc.on("connectionstatechange")
+        async def on_connectionstatechange():
+            if pc.connectionState in ["failed", "closed"]:
+                await pc.close()
+                self.pcs.discard(pc)
+
+        offer = RTCSessionDescription(sdp=sdp_offer, type=sdp_type)
+        await pc.setRemoteDescription(offer)
+        answer = await pc.createAnswer()
+        await pc.setLocalDescription(answer)
+
+        return {"sdp": pc.localDescription.sdp, "type": pc.localDescription.type}
+
+    async def _relay_to_gemini(self, track: MediaStreamTrack, outgoing_audio: GeminiLiveAudioTrack):
+        resampler = AudioResampler(format="s16", layout="mono", rate=16000)
+        async with self.client.aio.live.connect(
+            model="gemini-2.0-flash-exp",
+            config=types.LiveConnectConfig(
+                response_modalities=[types.LiveModality.AUDIO],
+                speech_config=types.SpeechConfig(
+                    voice_config=types.VoiceConfig(
+                        prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Aoede")
+                    )
+                )
+            )
+        ) as session:
+            # Task to read synthesized audio from Gemini and queue to WebRTC
+            async def receive_from_gemini():
+                async for response in session.receive():
+                    server_content = response.server_content
+                    if server_content and server_content.model_turn:
+                        for part in server_content.model_turn.parts:
+                            if part.inline_data:
+                                outgoing_audio.push_pcm_bytes(part.inline_data.data)
+
+            receiver_task = asyncio.create_task(receive_from_gemini())
+
+            try:
+                while True:
+                    frame = await track.recv()
+                    resampled = resampler.resample(frame)
+                    for r_frame in resampled:
+                        pcm_bytes = r_frame.planes[0].to_bytes()
+                        await session.send(input={"data": pcm_bytes, "mime_type": "audio/pcm;rate=16000"})
+            except asyncio.CancelledError:
+                receiver_task.cancel()
+```
+
+---
+
+## 3. Client WebRTC SDP Exchange & ICE Configuration
+
+```typescript
+export async function initializeVoiceSession(gatewayUrl: string): Promise<RTCPeerConnection> {
+  const pc = new RTCPeerConnection({
+    iceServers: [
+      { urls: 'stun:stun.l.google.com:19302' },
+      {
+        urls: 'turn:turn.enterprise-antigravity.internal:3478',
+        username: 'agent-dev',
+        credential: 'ephemeral-turn-token'
+      }
+    ]
+  });
+
+  // Capture developer microphone stream
+  const micStream = await navigator.mediaDevices.getUserMedia({
+    audio: {
+      channelCount: 1,
+      sampleRate: 48000,
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true
+    }
+  });
+
+  micStream.getAudioTracks().forEach(track => pc.addTrack(track, micStream));
+
+  // Audio track speaker output
+  pc.ontrack = (event) => {
+    if (event.track.kind === 'audio') {
+      const audioEl = new Audio();
+      audioEl.srcObject = event.streams[0];
+      audioEl.play().catch(console.error);
+    }
+  };
+
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+
+  const response = await fetch(`${gatewayUrl}/api/webrtc/offer`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sdp: offer.sdp, type: offer.type })
+  });
+
+  const answer = await response.json();
+  await pc.setRemoteDescription(new RTCSessionDescription(answer));
+  return pc;
+}
+```
+
+---
+
+## 4. Operational Best Practices & SLA Targets
+
+1. **Jitter-Buffer Tuning**: Target 40ms to 80ms playout delay. Avoid buffer bloating which degrades conversational turn-taking.
+2. **STUN/TURN High Availability**: Deploy Coturn behind Network Load Balancers (NLB) across at least 2 GCP availability zones.
+3. **Graceful Teardown**: Intercept `connectionstatechange` to immediately close Gemini WebSocket sessions on client hangup.