@jaguilar87/gaia-ops 1.0.0

package/tools/context_provider.py

@@ -0,0 +1,181 @@
+import json
+import argparse
+import sys
+from pathlib import Path
+from typing import Dict, List, Any
+
+# This script is expected to be run from the root of the repository.
+# The project context file is located at `.claude/project-context.json`.
+# We construct the path relative to the script's assumed execution location.
+DEFAULT_CONTEXT_PATH = Path(".claude/project-context.json")
+
+# Defines the mandatory keys that form the "Context Contract" for each agent.
+AGENT_CONTRACTS: Dict[str, List[str]] = {
+    "terraform-architect": [
+        "project_details",
+        "terraform_infrastructure",
+        "operational_guidelines",
+    ],
+    "gitops-operator": [
+        "project_details",
+        "gitops_configuration",
+        "infrastructure_topology",
+        "cluster_details",
+        "operational_guidelines",
+    ],
+    "gcp-troubleshooter": [
+        "project_details",
+        "infrastructure_topology",
+        "terraform_infrastructure",
+        "gitops_configuration",
+        "application_services",
+        "monitoring_observability",
+    ],
+    "aws-troubleshooter": [
+        "project_details",
+        "infrastructure_topology",
+        "terraform_infrastructure",
+        "gitops_configuration",
+        "application_services",
+        "monitoring_observability",
+    ],
+    # devops-developer has a more generic contract, often needing the full view.
+    "devops-developer": [
+        "project_details",
+        "application_architecture",
+        "application_services",
+        "development_standards",
+        "operational_guidelines"
+    ]
+}
+
+def load_project_context(context_path: Path) -> Dict[str, Any]:
+    """Loads the project context from the specified JSON file."""
+    if not context_path.is_file():
+        print(f"Error: Context file not found at {context_path}", file=sys.stderr)
+        sys.exit(1)
+    with open(context_path, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+def get_contract_context(project_context: Dict[str, Any], agent_name: str) -> Dict[str, Any]:
+    """Extracts the contract-defined context for a given agent."""
+    contract_keys = AGENT_CONTRACTS.get(agent_name)
+    if not contract_keys:
+        print(
+            f"Warning: No contract found for agent '{agent_name}'. Returning empty contract.",
+            file=sys.stderr,
+        )
+        return {}
+
+    sections = project_context.get("sections", {})
+    if not sections:
+        raise KeyError("project-context.json must contain a 'sections' object.")
+    return {key: sections[key] for key in contract_keys if key in sections}
+
+
+def get_semantic_enrichment(
+    project_context: Dict[str, Any], contract_keys: List[str], user_task: str
+) -> Dict[str, Any]:
+    """
+    Performs semantic analysis to find additional relevant context.
+
+    NOTE: This is a placeholder implementation. A real implementation would use
+    vector embeddings (e.g., SentenceTransformers, OpenAI embeddings) to find
+    sections of the project_context semantically similar to the user_task.
+
+    For now, it performs a simple keyword match, excluding keys already in the contract.
+    """
+    sections = project_context.get("sections", {})
+    if not sections:
+        raise KeyError("project-context.json must contain a 'sections' object.")
+    enrichment: Dict[str, Any] = {}
+    contract_key_set = set(contract_keys)
+    potential_keys = set(sections.keys()) - contract_key_set
+    task_words = {word.strip(".,:;!?") for word in user_task.lower().split()}
+
+    for key in potential_keys:
+        normalized_key = key.lower()
+        if normalized_key in task_words:
+            enrichment[key] = sections[key]
+
+    # Light metadata hints when the user asks about freshness/versioning.
+    metadata = project_context.get("metadata")
+    if metadata and any(word in {"metadata", "version", "updated"} for word in task_words):
+        enrichment.setdefault("metadata", metadata)
+
+    # Heuristic: include matching services based on task wording.
+    def normalize_services(raw: Any) -> List[Dict[str, Any]]:
+        normalized: List[Dict[str, Any]] = []
+        if isinstance(raw, list):
+            for svc in raw:
+                if isinstance(svc, dict) and svc.get("name"):
+                    normalized.append(svc)
+        elif isinstance(raw, dict):
+            for name, payload in raw.items():
+                entry = {"name": name}
+                if isinstance(payload, dict):
+                    entry.update(payload)
+                normalized.append(entry)
+        return normalized
+
+    candidate_services: List[Dict[str, Any]] = []
+    candidate_services.extend(normalize_services(sections.get("application_services")))
+
+    service_catalog = sections.get("service_catalog")
+    if isinstance(service_catalog, dict):
+        candidate_services.extend(
+            normalize_services(service_catalog.get("applications"))
+        )
+
+    app_arch = sections.get("application_architecture")
+    if isinstance(app_arch, dict):
+        candidate_services.extend(normalize_services(app_arch.get("services")))
+
+    if candidate_services and "application_services" not in contract_key_set:
+        matched = [
+            svc for svc in candidate_services
+            if svc.get("name", "").lower() in user_task.lower()
+        ]
+        if matched:
+            enrichment["application_services"] = matched
+
+    return enrichment
+
+def main():
+    """Main function to generate and print the context payload."""
+    parser = argparse.ArgumentParser(
+        description="""
+        Generates a structured context payload for a Claude agent based on its contract
+        and a semantic analysis of the user's task.
+        """
+    )
+    parser.add_argument("agent_name", choices=AGENT_CONTRACTS.keys(), help="The name of the agent being invoked.")
+    parser.add_argument("user_task", help="The user's task or query for the agent.")
+    parser.add_argument(
+        "--context-file",
+        type=Path,
+        default=DEFAULT_CONTEXT_PATH,
+        help=f"Path to the project-context.json file. Defaults to '{DEFAULT_CONTEXT_PATH}'"
+    )
+
+    args = parser.parse_args()
+
+    project_context = load_project_context(args.context_file)
+    
+    contract_context = get_contract_context(project_context, args.agent_name)
+    
+    enrichment_context = get_semantic_enrichment(
+        project_context,
+        list(contract_context.keys()),
+        args.user_task
+    )
+
+    final_payload = {
+        "contract": contract_context,
+        "enrichment": enrichment_context
+    }
+
+    print(json.dumps(final_payload, indent=2))
+
+if __name__ == "__main__":
+    main()

package/tools/context_section_reader.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""
+Context Section Reader for Claude Agent System
+
+Reads specific sections from project-context.json for selective loading by agents.
+Called by Claude orchestrator BEFORE invoking agents to reduce token usage.
+
+Architecture:
+- Claude orchestrator executes this script (NOT agents)
+- Agents receive pre-filtered context in their prompts
+- Reduces token usage by ~70% per agent invocation
+
+Usage:
+    from .claude.tools.context_section_reader import ContextSectionReader
+
+    reader = ContextSectionReader()
+    context = reader.get_for_agent('gitops-operator')
+
+    # Pass context to agent in Task tool prompt
+"""
+
+from pathlib import Path
+from typing import List, Dict, Optional, Any
+import json
+
+
+def find_claude_dir() -> Path:
+    """Find the .claude directory by searching upward from current location"""
+    current = Path.cwd()
+
+    # If we're already in a .claude directory, return it
+    if current.name == ".claude":
+        return current
+
+    # Look for .claude in current directory
+    claude_dir = current / ".claude"
+    if claude_dir.exists():
+        return claude_dir
+
+    # Search upward through parent directories
+    for parent in current.parents:
+        claude_dir = parent / ".claude"
+        if claude_dir.exists():
+            return claude_dir
+
+    # Fallback - raise error if not found
+    raise FileNotFoundError(
+        "No .claude directory found. Please run from a project directory "
+        "or specify context_file explicitly."
+    )
+
+
+class ContextSectionReader:
+    """
+    Read and filter sections from project-context.json for agent-specific loading.
+
+    Token Optimization:
+    - Without filtering: ~328 lines (1,312 tokens)
+    - With filtering: ~80-100 lines (320-400 tokens)
+    - Savings: ~70% per agent invocation
+    """
+
+    # Define which sections each agent needs (JSON keys in snake_case)
+    AGENT_SECTIONS = {
+        'gitops-operator': [
+            'infrastructure_topology',
+            'gitops_configuration',
+            'operational_guidelines',
+        ],
+        'gcp-troubleshooter': [
+            'infrastructure_topology',
+            'operational_guidelines',
+            'monitoring_observability',
+        ],
+        'terraform-architect': [
+            'infrastructure_topology',
+            'terraform_infrastructure',
+            'operational_guidelines',
+        ],
+        'devops-developer': [
+            'application_architecture',
+            'development_standards',
+            'operational_guidelines',
+        ],
+        'aws-troubleshooter': [
+            'infrastructure_topology',
+            'operational_guidelines',
+        ]
+    }
+
+    def __init__(self, context_file: Optional[str] = None):
+        """
+        Initialize reader with project context file.
+
+        Args:
+            context_file: Path to project-context.json (default: searches for .claude/project-context.json)
+        """
+        if context_file is None:
+            # Find the .claude directory by searching upward
+            claude_dir = find_claude_dir()
+            context_file = claude_dir / "project-context.json"
+
+        self.path = Path(context_file)
+
+        if not self.path.exists():
+            raise FileNotFoundError(f"Context file not found: {self.path}")
+
+        with open(self.path, 'r', encoding='utf-8') as f:
+            self.data = json.load(f)
+
+        self._parse_sections()
+
+    def _parse_sections(self) -> None:
+        """Extract sections from JSON data."""
+        self.sections: Dict[str, Any] = {}
+
+        # Extract sections from JSON
+        if 'sections' in self.data:
+            self.sections = self.data['sections']
+        else:
+            raise ValueError("Invalid JSON structure: 'sections' key not found")
+
+    def get_sections(self, section_names: List[str]) -> str:
+        """
+        Get specific sections as formatted JSON string.
+
+        Args:
+            section_names: List of section names to retrieve
+
+        Returns:
+            Formatted JSON string with requested sections
+        """
+        result = {}
+        missing = []
+
+        for name in section_names:
+            if name in self.sections:
+                result[name] = self.sections[name]
+            else:
+                missing.append(name)
+
+        if missing:
+            print(f"Warning: Sections not found: {missing}")
+
+        if not result:
+            return json.dumps({
+                "error": "No sections found",
+                "message": "Requested sections were not available."
+            }, indent=2)
+
+        # Format as JSON for agent consumption
+        return json.dumps(result, indent=2, ensure_ascii=False)
+
+    def get_for_agent(self, agent_name: str) -> str:
+        """
+        Get sections needed by specific agent.
+
+        Args:
+            agent_name: Name of the agent (e.g., 'gitops-operator')
+
+        Returns:
+            Markdown string with agent-specific context
+
+        Raises:
+            ValueError: If agent_name is not recognized
+        """
+        if agent_name not in self.AGENT_SECTIONS:
+            available = ', '.join(self.AGENT_SECTIONS.keys())
+            raise ValueError(
+                f"Unknown agent: {agent_name}. "
+                f"Available agents: {available}"
+            )
+
+        sections = self.AGENT_SECTIONS[agent_name]
+        return self.get_sections(sections)
+
+    def list_sections(self) -> List[str]:
+        """Get list of all available sections."""
+        return list(self.sections.keys())
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get statistics about the context file.
+
+        Returns:
+            Dictionary with size and token estimates
+        """
+        # Calculate total JSON size
+        total_json = json.dumps(self.data, ensure_ascii=False)
+        total_chars = len(total_json)
+        total_tokens = total_chars // 4  # Rough estimate: 4 chars per token
+
+        return {
+            'total_chars': total_chars,
+            'total_tokens_estimated': total_tokens,
+            'total_sections': len(self.sections),
+            'sections': {
+                name: {
+                    'chars': len(json.dumps(content, ensure_ascii=False)),
+                    'tokens_estimated': len(json.dumps(content, ensure_ascii=False)) // 4
+                }
+                for name, content in self.sections.items()
+            }
+        }
+
+    def get_agent_stats(self, agent_name: str) -> Dict[str, Any]:
+        """
+        Get statistics for a specific agent's context.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Dictionary with character and token counts for agent
+        """
+        context = self.get_for_agent(agent_name)
+        chars = len(context)
+        tokens = chars // 4
+
+        full_stats = self.get_stats()
+        savings = {
+            'chars': full_stats['total_chars'] - chars,
+            'tokens': full_stats['total_tokens_estimated'] - tokens,
+            'percentage': round((1 - chars / full_stats['total_chars']) * 100, 1)
+        }
+
+        return {
+            'agent': agent_name,
+            'chars_loaded': chars,
+            'tokens_estimated': tokens,
+            'savings': savings
+        }
+
+
+def main():
+    """CLI interface for testing and debugging."""
+    import sys
+    import json
+
+    reader = ContextSectionReader()
+
+    if len(sys.argv) < 2:
+        print("Context Section Reader")
+        print("\nUsage:")
+        print("  python context_section_reader.py <command> [args]")
+        print("\nCommands:")
+        print("  list                    - List all available sections")
+        print("  stats                   - Show statistics for context file")
+        print("  agent <name>            - Get context for specific agent")
+        print("  agent-stats <name>      - Show stats for agent's context")
+        print("  sections <name1> <name2> - Get specific sections")
+        print("\nAvailable agents:")
+        for agent in reader.AGENT_SECTIONS.keys():
+            print(f"  - {agent}")
+        sys.exit(0)
+
+    command = sys.argv[1]
+
+    if command == 'list':
+        print("Available sections:")
+        for section in reader.list_sections():
+            print(f"  - {section}")
+
+    elif command == 'stats':
+        stats = reader.get_stats()
+        print(json.dumps(stats, indent=2))
+
+    elif command == 'agent':
+        if len(sys.argv) < 3:
+            print("Error: Agent name required")
+            sys.exit(1)
+
+        agent_name = sys.argv[2]
+        context = reader.get_for_agent(agent_name)
+        print(context)
+
+    elif command == 'agent-stats':
+        if len(sys.argv) < 3:
+            print("Error: Agent name required")
+            sys.exit(1)
+
+        agent_name = sys.argv[2]
+        stats = reader.get_agent_stats(agent_name)
+        print(json.dumps(stats, indent=2))
+
+    elif command == 'sections':
+        if len(sys.argv) < 3:
+            print("Error: Section names required")
+            sys.exit(1)
+
+        section_names = sys.argv[2:]
+        context = reader.get_sections(section_names)
+        print(context)
+
+    else:
+        print(f"Unknown command: {command}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/tools/demo_clarify.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Demo script for the Clarification Engine
+
+Shows how the clarification system works with different types of prompts.
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(__file__))
+
+from clarify_engine import request_clarification
+
+
+def demo_prompt(prompt: str, description: str = ""):
+    """Test a single prompt and display results."""
+    print("=" * 70)
+    if description:
+        print(f"📝 {description}")
+    print(f"Prompt: \"{prompt}\"")
+    print("=" * 70)
+
+    result = request_clarification(prompt)
+
+    if not result["needs_clarification"]:
+        print("✅ No clarification needed - prompt is specific enough\n")
+        return
+
+    print(f"⚠️  Clarification needed (score: {result['clarification_context']['ambiguity_analysis']['ambiguity_score']}/100)\n")
+
+    # Show summary
+    print(result["summary"])
+    print()
+
+    # Show questions
+    for i, question in enumerate(result["question_config"]["questions"]):
+        print(f"\n{'─' * 70}")
+        print(f"{question['header']}")
+        print(f"{'─' * 70}")
+        print(f"❓ {question['question']}\n")
+
+        for j, option in enumerate(question["options"], 1):
+            print(f"  {j}. {option['label']}")
+            print(f"     → {option['description']}\n")
+
+    print()
+
+
+def main():
+    """Run demo with various prompt types."""
+
+    print("\n" + "🎯" * 35)
+    print("   CLARIFICATION ENGINE - DEMO")
+    print("🎯" * 35 + "\n")
+
+    # Test 1: Ambiguous service
+    demo_prompt(
+        "Check the API",
+        "Test 1: Ambiguous service reference"
+    )
+
+    # Test 2: Specific service (no clarification)
+    demo_prompt(
+        "Check tcm-api service status",
+        "Test 2: Specific service (should NOT need clarification)"
+    )
+
+    # Test 3: Environment mismatch
+    demo_prompt(
+        "Deploy to production",
+        "Test 3: Environment mismatch warning"
+    )
+
+    # Test 4: Namespace ambiguity
+    demo_prompt(
+        "Deploy to the cluster",
+        "Test 4: Namespace ambiguity"
+    )
+
+    # Test 5: Multiple ambiguities
+    demo_prompt(
+        "Deploy the API to the cluster",
+        "Test 5: Multiple ambiguities (service + namespace)"
+    )
+
+    # Test 6: Spanish prompt
+    demo_prompt(
+        "Chequea el servicio",
+        "Test 6: Spanish keywords"
+    )
+
+    # Test 7: Redis resource
+    demo_prompt(
+        "Check the Redis instance",
+        "Test 7: Resource ambiguity (Redis)"
+    )
+
+    print("\n" + "✅" * 35)
+    print("   DEMO COMPLETE")
+    print("✅" * 35 + "\n")
+
+
+if __name__ == "__main__":
+    main()