@jaguilar87/gaia-ops 1.0.0

package/tools/generate_embeddings.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Generate intent embeddings offline using sentence-transformers
+
+This script is run ONCE to generate pre-computed embeddings.
+At runtime, we only need numpy for similarity calculations.
+
+Usage:
+    python3 generate_embeddings.py
+
+Output:
+    - .claude/configs/intent_embeddings.npy (binary, ~5MB)
+    - .claude/configs/intent_embeddings.json (readable metadata)
+"""
+
+import json
+from pathlib import Path
+import sys
+
+# Define intent examples (from agent_router.py IntentClassifier)
+INTENT_EXAMPLES = {
+    "infrastructure_creation": [
+        "create gke cluster with autopilot",
+        "provision new vpc and subnets",
+        "deploy terraform infrastructure",
+        "setup kubernetes cluster",
+        "build cloud resources",
+        "create new database instance",
+        "provision redis cache",
+        "deploy load balancer"
+    ],
+    "infrastructure_diagnosis": [
+        "diagnose cluster connectivity",
+        "troubleshoot gke pod crashes",
+        "debug network latency problems",
+        "check kubernetes node status",
+        "analyze infrastructure errors",
+        "troubleshoot cloud sql connectivity",
+        "debug workload identity issues",
+        "diagnose firewall rule problems"
+    ],
+    "kubernetes_operations": [
+        "check pod status in namespace",
+        "view deployment logs",
+        "verify flux reconciliation",
+        "monitor helm release status",
+        "inspect kubernetes resources",
+        "check service endpoints",
+        "scale deployment replicas",
+        "update configmap values"
+    ],
+    "application_development": [
+        "build docker image for api",
+        "run unit tests for application",
+        "validate application configuration",
+        "compile typescript code",
+        "execute npm build command",
+        "lint code with eslint",
+        "run integration tests",
+        "package application for deployment"
+    ],
+    "infrastructure_validation": [
+        "validate terraform configuration",
+        "check hcl syntax errors",
+        "run terraform plan",
+        "scan infrastructure security",
+        "verify module dependencies",
+        "check terraform state integrity",
+        "scan for policy violations",
+        "validate cloudformation template"
+    ]
+}
+
+
+def generate_embeddings():
+    """Generate and save embeddings using sentence-transformers"""
+    try:
+        from sentence_transformers import SentenceTransformer
+        import numpy as np
+    except ImportError:
+        print("❌ Error: sentence-transformers not installed")
+        print("   Run: pip install sentence-transformers torch")
+        return False
+
+    print("\n" + "="*70)
+    print("🔧 Generating Intent Embeddings (Offline)")
+    print("="*70 + "\n")
+
+    # Load model
+    print("📥 Loading sentence-transformers model: all-MiniLM-L6-v2")
+    model = SentenceTransformer('all-MiniLM-L6-v2')
+    print(f"   ✅ Model loaded (embedding dimension: 384)")
+
+    embeddings_data = {}
+    total_examples = 0
+
+    print("\n📊 Generating embeddings for intents:\n")
+
+    for intent_name, examples in INTENT_EXAMPLES.items():
+        print(f"   🎯 {intent_name}")
+
+        # Generate embeddings for all examples
+        embeddings = model.encode(examples, convert_to_numpy=True)
+        mean_embedding = embeddings.mean(axis=0)
+
+        # Store metadata and mean embedding
+        embeddings_data[intent_name] = {
+            "embedding": mean_embedding.tolist(),  # Convert to list for JSON
+            "examples": examples,
+            "dimension": len(mean_embedding),
+            "count": len(examples)
+        }
+
+        print(f"      ✅ {len(examples):2d} examples → 384-dim embedding")
+        total_examples += len(examples)
+
+    print(f"\n   Total examples processed: {total_examples}")
+
+    # Save as JSON (readable metadata)
+    output_dir = Path(__file__).parent.parent / "configs"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    json_path = output_dir / "intent_embeddings.json"
+    with open(json_path, 'w', encoding='utf-8') as f:
+        json.dump(embeddings_data, f, indent=2)
+
+    print(f"\n✅ Saved metadata: {json_path}")
+    print(f"   Size: {json_path.stat().st_size / 1024:.1f} KB")
+
+    # Save as numpy array (binary, optimized)
+    npy_path = output_dir / "intent_embeddings.npy"
+    import numpy as np
+    np.save(npy_path, embeddings_data)
+
+    print(f"✅ Saved embeddings: {npy_path}")
+    print(f"   Size: {npy_path.stat().st_size / (1024*1024):.1f} MB")
+
+    # Create runtime loader info
+    info_path = output_dir / "embeddings_info.json"
+    info = {
+        "model": "all-MiniLM-L6-v2",
+        "dimension": 384,
+        "intents": list(embeddings_data.keys()),
+        "total_examples": total_examples,
+        "timestamp": str(Path(__file__).stat().st_mtime),
+        "note": "Pre-computed offline. At runtime, load with numpy (no torch needed)."
+    }
+
+    with open(info_path, 'w') as f:
+        json.dump(info, f, indent=2)
+
+    print(f"✅ Saved info: {info_path}")
+
+    print("\n" + "="*70)
+    print("🎉 Embeddings Generated Successfully!")
+    print("="*70)
+    print("\nUsage:")
+    print("   from semantic_matcher import SemanticMatcher")
+    print("   matcher = SemanticMatcher()  # Loads embeddings automatically")
+    print("   intent, conf = matcher.find_similar_intent(request, keyword_scores)")
+    print()
+
+    return True
+
+
+if __name__ == "__main__":
+    success = generate_embeddings()
+    sys.exit(0 if success else 1)

package/tools/quicktriage_aws_troubleshooter.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# QuickTriage script for aws-troubleshooter
+# Provides a minimal health snapshot for AWS EKS clusters and supporting services.
+
+set -euo pipefail
+
+REGION="${AWS_REGION:-${1:-us-east-1}}"
+CLUSTER="${EKS_CLUSTER:-${2:-}}"
+VPC_ID="${VPC_ID:-${3:-}}"
+
+info() {
+  printf '[quicktriage] %s\n' "$*"
+}
+
+run_cmd() {
+  local description="$1"
+  shift
+
+  if ! command -v "$1" >/dev/null 2>&1; then
+    info "Skipping ${description} (command $1 not available)"
+    return
+  fi
+
+  info "$description"
+  "$@" || info "Command failed: $*"
+}
+
+info "Starting AWS quick triage (region=${REGION}, cluster=${CLUSTER:-unset})"
+
+AWS_ARGS=(--region "$REGION")
+
+if [[ -n "$CLUSTER" ]]; then
+  run_cmd "aws eks describe-cluster ${CLUSTER}" aws eks describe-cluster "${AWS_ARGS[@]}" --name "$CLUSTER" --query "cluster.{name:name,status:status,endpoint:endpoint,version:version}" --output table
+  run_cmd "kubectl get nodes (short)" kubectl get nodes -o wide
+fi
+
+run_cmd "aws elbv2 describe-target-health (summary)" aws elbv2 describe-target-health "${AWS_ARGS[@]}" --target-group-arn "${TARGET_GROUP_ARN:-}" || info "Set TARGET_GROUP_ARN to include ALB status in triage."
+
+run_cmd "aws cloudwatch describe-alarms (ALARM state)" aws cloudwatch describe-alarms "${AWS_ARGS[@]}" --state-value ALARM --max-items 10 --query "MetricAlarms[*].{Name:AlarmName,State:StateValue}" --output table
+
+if [[ -n "$VPC_ID" ]]; then
+  run_cmd "aws ec2 describe-vpc-endpoints ${VPC_ID}" aws ec2 describe-vpc-endpoints "${AWS_ARGS[@]}" --filters "Name=vpc-id,Values=${VPC_ID}" --query "VpcEndpoints[*].{ServiceName:ServiceName,State:State}" --output table
+fi
+
+info "Quick triage completed. Investigate failing components by describing pods/services or reviewing IAM/VPC configuration as next steps."

package/tools/quicktriage_devops_developer.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# QuickTriage script for devops-developer
+# Checks repository hygiene, linting, and test discoverability quickly.
+
+set -euo pipefail
+
+WORKDIR="${1:-.}"
+LINT_CMD="${LINT_CMD:-npm run lint -- --max-warnings=0}"
+TEST_DISCOVERY_CMD="${TEST_DISCOVERY_CMD:-npm run test -- --watchAll=false --listTests}"
+
+info() {
+  printf '[quicktriage] %s\n' "$*"
+}
+
+run_in_repo() {
+  local description="$1"
+  shift
+
+  info "$description"
+  (cd "$WORKDIR" && eval "$*") || info "Command failed: $*"
+}
+
+info "Starting devops quick triage (workdir=${WORKDIR})"
+
+run_in_repo "git status --short" "git status --short"
+
+if command -v npm >/dev/null 2>&1 || command -v pnpm >/dev/null 2>&1; then
+  run_in_repo "Lint check" "$LINT_CMD"
+  run_in_repo "Test discovery" "$TEST_DISCOVERY_CMD"
+else
+  info "Skipping lint/test (npm/pnpm not available)"
+fi
+
+if [ -f "${WORKDIR}/package.json" ]; then
+  run_in_repo "npm audit --production (summary)" "npm audit --production --json | jq '.metadata.vulnerabilities' || npm audit --production"
+fi
+
+info "Quick triage completed. Use full test runs or profiling if deeper analysis is required."

package/tools/quicktriage_gcp_troubleshooter.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# QuickTriage script for gcp-troubleshooter
+# Provides a lightweight health snapshot for GKE clusters and key managed services.
+
+set -euo pipefail
+
+PROJECT="${GCP_PROJECT:-${1:-}}"
+CLUSTER="${GKE_CLUSTER:-${2:-}}"
+REGION="${GKE_REGION:-${3:-us-central1}}"
+SQL_INSTANCE="${CLOUD_SQL_INSTANCE:-${4:-}}"
+
+info() {
+  printf '[quicktriage] %s\n' "$*"
+}
+
+run_cmd() {
+  local description="$1"
+  shift
+
+  if ! command -v "$1" >/dev/null 2>&1; then
+    info "Skipping ${description} (command $1 not available)"
+    return
+  fi
+
+  info "$description"
+  "$@" || info "Command failed: $*"
+}
+
+info "Starting GCP quick triage (project=${PROJECT:-unset}, cluster=${CLUSTER:-unset})"
+
+if [[ -n "$PROJECT" ]]; then
+  gcloud config set project "$PROJECT" >/dev/null 2>&1 || true
+fi
+
+if [[ -n "$CLUSTER" ]]; then
+  run_cmd "gcloud container clusters describe ${CLUSTER}" \
+    gcloud container clusters describe "$CLUSTER" --region "$REGION" --format="table(name,status,endpoint,releaseChannel.releaseChannel)"
+fi
+
+run_cmd "gcloud container clusters list (summary)" \
+  gcloud container clusters list --format="table(name,location,status,nodePools[0].status)"
+
+if [[ -n "$SQL_INSTANCE" ]]; then
+  run_cmd "gcloud sql instances describe ${SQL_INSTANCE}" \
+    gcloud sql instances describe "$SQL_INSTANCE" --format="table(name,state,backendType,availabilityType,ipAddresses.ipAddress)"
+fi
+
+run_cmd "gcloud logging read (recent errors)" \
+  gcloud logging read 'severity>=ERROR' --limit=5 --format="table(timestamp, resource.labels.cluster_name, textPayload)"
+
+info "Quick triage completed. Consider VPC connectivity, IAM bindings, or workload identity if issues persist."

package/tools/quicktriage_gitops_operator.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# QuickTriage script for gitops-operator
+# Provides a fast snapshot of workload health inside a Kubernetes cluster.
+
+set -euo pipefail
+
+NAMESPACE="${1:-tcm-non-prod}"
+LABEL_SELECTOR="${2:-}"
+
+info() {
+  printf '[quicktriage] %s\n' "$*"
+}
+
+run_cmd() {
+  local description="$1"
+  shift
+
+  if ! command -v "$1" >/dev/null 2>&1; then
+    info "Skipping ${description} (command $1 not available)"
+    return
+  fi
+
+  info "$description"
+  "$@" || info "Command failed: $*"
+}
+
+info "Starting gitops quick triage (namespace=${NAMESPACE:-all}, selector='${LABEL_SELECTOR}')"
+
+KUBECTL_ARGS=(-o wide)
+if [[ -n "$NAMESPACE" ]]; then
+  KUBECTL_ARGS=(-n "$NAMESPACE" "${KUBECTL_ARGS[@]}")
+fi
+if [[ -n "$LABEL_SELECTOR" ]]; then
+  KUBECTL_ARGS+=(-l "$LABEL_SELECTOR")
+fi
+
+run_cmd "kubectl get pods" kubectl get pods "${KUBECTL_ARGS[@]}"
+
+if [[ -n "$NAMESPACE" ]]; then
+  run_cmd "kubectl get deploy" kubectl get deploy -n "$NAMESPACE"
+  run_cmd "kubectl get helmrelease" kubectl get helmrelease -n "$NAMESPACE"
+fi
+
+run_cmd "flux get kustomizations" flux get kustomizations
+run_cmd "flux get helmreleases" flux get helmreleases -A
+
+info "Quick triage completed. Recommended next steps: describe failing pods or inspect logs if issues were detected."

package/tools/quicktriage_terraform_architect.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# QuickTriage script for terraform-architect
+# Performs fast validation checks on Terraform/Terragrunt directories.
+
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+USE_TERRAGRUNT="${USE_TERRAGRUNT:-false}"
+
+info() {
+  printf '[quicktriage] %s\n' "$*"
+}
+
+run_cmd() {
+  local description="$1"
+  shift
+
+  if ! command -v "$1" >/dev/null 2>&1; then
+    info "Skipping ${description} (command $1 not available)"
+    return
+  fi
+
+  info "$description"
+  (cd "$TARGET_DIR" && "$@") || info "Command failed: $*"
+}
+
+info "Starting Terraform quick triage (dir=${TARGET_DIR}, terragrunt=${USE_TERRAGRUNT})"
+
+if [[ "${USE_TERRAGRUNT}" == "true" ]]; then
+  run_cmd "terragrunt fmt -check" terragrunt fmt -check
+  run_cmd "terragrunt validate" terragrunt validate
+  run_cmd "terragrunt plan (detailed exit code)" terragrunt plan -lock=false -detailed-exitcode || true
+else
+  run_cmd "terraform fmt -check" terraform fmt -check
+  run_cmd "terraform init -backend=false" terraform init -backend=false
+  run_cmd "terraform validate" terraform validate
+  run_cmd "terraform plan (detailed exit code)" terraform plan -lock=false -refresh=false -detailed-exitcode || true
+fi
+
+info "Quick triage completed. Exit code 1 on plan indicates drift; review the plan output if printed."

package/tools/semantic_matcher.py

@@ -0,0 +1,222 @@
+"""
+Semantic matching using pre-computed embeddings
+
+CRITICAL: This module does NOT require torch at runtime!
+- Embeddings are pre-computed offline
+- At runtime, we only load numpy + json
+- Similarity is calculated with scipy/sklearn
+
+Week 2 Addition
+"""
+
+import json
+from pathlib import Path
+from typing import Tuple, List, Optional, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticMatcher:
+    """
+    Match requests to intents using pre-computed embeddings
+
+    - Loads pre-computed embeddings from .npy/.json
+    - Calculates similarity using numpy only
+    - No torch/transformers needed at runtime
+    - Provides fallback to keyword scores
+    """
+
+    def __init__(self, embeddings_dir: Optional[Path] = None):
+        """
+        Initialize semantic matcher
+
+        Args:
+            embeddings_dir: Directory containing embeddings (defaults to .claude/configs/)
+        """
+        if embeddings_dir is None:
+            embeddings_dir = Path(__file__).parent.parent / "configs"
+
+        self.embeddings_dir = embeddings_dir
+        self.embeddings: Dict[str, Any] = {}
+        self.metadata: Dict[str, Any] = {}
+        self.available = False
+
+        self._load_embeddings()
+
+    def _load_embeddings(self):
+        """Load pre-computed embeddings from JSON"""
+        json_path = self.embeddings_dir / "intent_embeddings.json"
+
+        if not json_path.exists():
+            logger.warning(
+                f"⚠️  Embeddings not found at {json_path}. "
+                "Run: python3 .claude/tools/generate_embeddings.py"
+            )
+            self.available = False
+            return
+
+        try:
+            with open(json_path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+
+            # Convert lists back to numpy arrays
+            import numpy as np
+
+            for intent, info in data.items():
+                self.embeddings[intent] = {
+                    "embedding": np.array(info["embedding"]),
+                    "examples": info["examples"],
+                    "dimension": info.get("dimension", 384)
+                }
+
+            self.available = True
+            logger.info(f"✅ Loaded {len(self.embeddings)} intent embeddings")
+
+        except Exception as e:
+            logger.error(f"Error loading embeddings: {e}")
+            self.available = False
+
+    def find_similar_intent(
+        self,
+        text: str,
+        keyword_scores: Dict[str, float]
+    ) -> Tuple[Optional[str], float]:
+        """
+        Find most similar intent combining keywords + embeddings
+
+        Args:
+            text: User request
+            keyword_scores: Scores from keyword matching {intent: score}
+
+        Returns:
+            (best_intent, confidence)
+
+        Strategy:
+        1. If embeddings available, calculate text embedding (via TF-IDF approximation)
+        2. Find similarity to each intent embedding
+        3. Combine with keyword scores
+        4. Return best match
+        """
+        if not keyword_scores:
+            return None, 0.0
+
+        # If embeddings not available, use keyword scores as primary
+        if not self.available:
+            logger.debug("Embeddings not available, using keyword scores only")
+            best_intent = max(keyword_scores, key=keyword_scores.get)
+            confidence = keyword_scores[best_intent]
+            return best_intent, confidence
+
+        # If embeddings available, enhance keyword scores with embedding similarity
+        try:
+            import numpy as np
+            from sklearn.feature_extraction.text import TfidfVectorizer
+
+            # Create TF-IDF approximation of text embedding
+            # (lightweight alternative to transformer embeddings)
+            all_examples = []
+            intent_map = []
+
+            for intent, info in self.embeddings.items():
+                all_examples.extend(info["examples"])
+                intent_map.extend([intent] * len(info["examples"]))
+
+            all_examples.append(text)  # Add query at end
+
+            # Vectorize
+            vectorizer = TfidfVectorizer(
+                analyzer='char',
+                ngram_range=(2, 3),
+                max_features=100
+            )
+            tfidf_matrix = vectorizer.fit_transform(all_examples)
+
+            # Get query vector (last row)
+            query_vector = tfidf_matrix[-1].toarray().flatten()
+
+            # Calculate similarities to each intent
+            embedding_scores = {}
+
+            for intent in self.embeddings.keys():
+                # Get example vectors for this intent
+                example_indices = [i for i, x in enumerate(intent_map) if x == intent]
+                example_vectors = tfidf_matrix[example_indices].toarray()
+
+                # Calculate mean similarity to examples
+                similarities = []
+                for example_vec in example_vectors:
+                    # Cosine similarity
+                    dot = np.dot(query_vector, example_vec)
+                    norm1 = np.linalg.norm(query_vector)
+                    norm2 = np.linalg.norm(example_vec)
+                    if norm1 > 0 and norm2 > 0:
+                        similarity = dot / (norm1 * norm2)
+                        similarities.append(similarity)
+
+                # Mean similarity for this intent
+                if similarities:
+                    embedding_scores[intent] = np.mean(similarities)
+                else:
+                    embedding_scores[intent] = 0.0
+
+            # Combine keyword scores (70%) + embedding scores (30%)
+            combined_scores = {}
+            for intent in keyword_scores.keys():
+                kw_score = keyword_scores[intent]
+                emb_score = embedding_scores.get(intent, 0.0)
+
+                # Normalize both to 0-1
+                kw_norm = min(kw_score / 5.0, 1.0)  # keyword scores are ~0-5
+                emb_norm = max(0.0, min(emb_score, 1.0))  # embedding scores already 0-1
+
+                # Weighted combination
+                combined = (kw_norm * 0.7) + (emb_norm * 0.3)
+                combined_scores[intent] = combined
+
+            # Select best
+            best_intent = max(combined_scores, key=combined_scores.get)
+            confidence = combined_scores[best_intent]
+
+            logger.debug(
+                f"Combined scores: {best_intent} = {confidence:.3f} "
+                f"(kw={keyword_scores.get(best_intent, 0):.2f}, "
+                f"emb={embedding_scores.get(best_intent, 0):.3f})"
+            )
+
+            return best_intent, confidence
+
+        except Exception as e:
+            logger.warning(f"Error in embedding similarity: {e}")
+            # Fallback to keyword scores
+            best_intent = max(keyword_scores, key=keyword_scores.get)
+            confidence = keyword_scores[best_intent]
+            return best_intent, confidence
+
+    def get_intent_examples(self, intent: str) -> List[str]:
+        """Get example requests for an intent"""
+        if intent in self.embeddings:
+            return self.embeddings[intent]["examples"]
+        return []
+
+    def list_intents(self) -> List[str]:
+        """List all available intents"""
+        return list(self.embeddings.keys())
+
+    def is_available(self) -> bool:
+        """Check if embeddings are loaded"""
+        return self.available
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get statistics about loaded embeddings"""
+        return {
+            "available": self.available,
+            "intents": len(self.embeddings),
+            "total_examples": sum(
+                len(info["examples"]) for info in self.embeddings.values()
+            ),
+            "embedding_dimension": next(
+                (info["dimension"] for info in self.embeddings.values()),
+                None
+            )
+        }