agentops-cockpit 0.5.0__py3-none-any.whl → 0.9.5__py3-none-any.whl

agent_ops_cockpit/ops/arch_review.py

@@ -1,14 +1,15 @@
 import typer
 import os
+import re
 from rich.console import Console
 from rich.table import Table
 from rich.panel import Panel
 
+from agent_ops_cockpit.ops.frameworks import detect_framework, FRAMEWORKS
+
 app = typer.Typer(help="Agent Architecture Reviewer: Audit your design against Google Well-Architected Framework.")
 console = Console()
 
-from agent_ops_cockpit.ops.frameworks import detect_framework, FRAMEWORKS
-
 @app.command()
 def audit(path: str = "."):
     """
@@ -18,15 +19,11 @@ def audit(path: str = "."):
     framework_data = FRAMEWORKS[framework_key]
     checklist = framework_data["checklist"]
     framework_name = framework_data["name"]
-
-    console.print(Panel.fit(f"🏛️ [bold blue]{framework_name.upper()}: ARCHITECTURE REVIEW[/bold blue]", border_style="blue"))
-    console.print(f"Detected Framework: [bold green]{framework_name}[/bold green]")
-    console.print(f"Comparing local agent implementation against [bold]{framework_name} Best Practices[/bold]...\n")
-
     # Read all relevant code files for inspection
     code_content = ""
     for root, dirs, files in os.walk(path):
-        if any(d in root for d in [".venv", "node_modules", ".git"]): continue
+        if any(d in root for d in [".venv", "node_modules", ".git"]):
+            continue
         for file in files:
             if file.endswith((".py", ".ts", ".tsx", ".js")):
                 try:
@@ -35,8 +32,34 @@ def audit(path: str = "."):
                 except Exception:
                     pass
 
-    total_checks = sum(len(section["checks"]) for section in checklist)
-    passed_checks = 0
+    if framework_key == "generic":
+        console.print(Panel.fit("🔍 [bold yellow]SHADOW INTELLIGENCE: ZERO-SHOT AUDIT INITIALIZED[/bold yellow]", border_style="yellow"))
+        console.print("⚠️ [dim]Detected Unknown Technology Stack. Switching to Structural Pattern Matching...[/dim]")
+        
+        # Self-Learning Heuristic: Look for patterns even if tech is unknown
+        structural_indicators = {
+            "decorators": r"@[\w\.]+",
+            "async_loops": r"async\s+def.*await",
+            "class_hierarchy": r"class\s+\w+\(\w*\):",
+            "environment_vars": r"os\.environ|process\.env",
+            "structured_output": r"Pydantic|BaseModel|zod|interface",
+        }
+        
+        found_patterns = []
+        for p_name, pattern in structural_indicators.items():
+            if re.search(pattern, code_content):
+                found_patterns.append(p_name)
+        
+        if found_patterns:
+            console.print(f"📡 [bold green]Heuristically identified patterns:[/bold green] {', '.join(found_patterns)}")
+            console.print("Adjusting audit benchmarks for custom agentic architecture...\n")
+
+    console.print(Panel.fit(f"🏛️ [bold blue]{framework_name.upper()}: ARCHITECTURE REVIEW[/bold blue]", border_style="blue"))
+    console.print(f"Detected Framework: [bold green]{framework_name}[/bold green]")
+    console.print(f"Comparing local agent implementation against [bold]{framework_name} Best Practices[/bold]...\n")
+
+    total_checks = 0.0
+    passed_checks = 0.0
     current_check_num = 0
 
     with console.status("[bold blue]Scanning architecture...") as status:
@@ -49,7 +72,7 @@ def audit(path: str = "."):
             for check_text, rationale in section["checks"]:
                 current_check_num += 1
                 check_key = check_text.split(":")[0].strip()
-                status.update(f"[bold blue][{current_check_num}/{total_checks}] Checking {check_key}...")
+                status.update(f"[bold blue]Step {current_check_num}: Checking {check_key}...")
                 
                 # Simple heuristic audit: check if certain keywords exist in the code
                 keywords = {
@@ -59,7 +82,7 @@ def audit(path: str = "."):
                     "Identity": ["iam", "auth", "token", "oauth", "workloadidentity"],
                     "Moderation": ["moderate", "safety", "filter"],
                     "Routing": ["router", "switch", "map", "agentengine"],
-                    "Outputs": ["schema", "json", "structured"],
+                    "Outputs": ["schema", "json", "structured", "basemodel", "interface"],
                     "HITL": ["approve", "confirm", "human"],
                     "Confirmation": ["confirm", "ask", "approve"],
                     "Logging": ["log", "trace", "audit", "reasoningengine"],
@@ -69,9 +92,39 @@ def audit(path: str = "."):
                     "A2UI": ["a2ui", "renderer", "registry", "component"],
                     "Responsive": ["@media", "max-width", "flex", "grid", "vw", "vh"],
                     "Accessibility": ["aria-", "role=", "alt=", "tabindex"],
-                    "Triggers": ["trigger", "callback", "handle", "onclick"]
+                    "Policies": ["policies.json", "policy_engine", "forbidden_topics", "hitl"],
+                    "Triggers": ["trigger", "callback", "handle", "onclick"],
+                    "Resiliency": ["retry", "tenacity", "backoff", "exponential"],
+                    "Prompts": [".md", ".yaml", ".prompt", "load_prompt", "jinja2"],
+                    "Sessions": ["session", "state", "conversation_id", "thread_id"],
+                    "Retrieval": ["rag", "vector", "embedding", "context_cache", "retrieval", "pinecone", "alloydb", "cloudsql", "bigquery", "firestore", "spanner", "redshift", "snowflake", "databricks", "s3", "blob"],
+                    "Reasoning": ["while", "for", "loop", "invoke", "call", "run", "execute", "chain", "agent"],
+                    "State": ["memory", "state", "db", "redis", "history", "session", "storage"],
+                    "Tools": ["tool", "registry", "dispatcher", "handler", "mcp", "api", "sdk", "client", "connect"],
+                    "Safety": ["filter", "clean", "sanitize", "scrub", "guard"],
+                    "Shadow Mode": ["shadow", "router", "dual_rollout", "traffic_split", "version_v2"],
+                    "Orchestration": ["swarm", "coordinator", "manager_agent", "supervisor", "orchestrator", "worker_agent"],
+                    "VPC": ["vpc_sc", "service_control", "isolated_network", "private_endpoint"],
+                    "Observability": ["otel", "trace", "span", "telemetry", "opentelemetry", "cloud_trace"],
+                    "Governance": ["policies.json", "hitl", "approval", "policy_engine"],
+                    "Legal": ["copyright", "license", "disclaimer", "data_residency", "privacy", "tos", "terms_of_service"],
+                    "Marketing": ["brand", "tone", "vibrant", "consistent", "seo", "og:image", "description", "cta"]
+                }
+                
+                # Weighting: Security and Core Architecture are more important
+                weights = {
+                    "🏗️": 1.5,
+                    "🛡️": 2.0,
+                    "🎭": 1.0,
+                    "🧗": 1.2,
+                    "📉": 1.3,
+                    "⚖️": 1.8,  # Legal/Compliance
+                    "📢": 0.9   # Marketing/Brand
                 }
                 
+                category_prefix = section["category"][:2]
+                weight = weights.get(category_prefix, 1.0)
+
                 # If any keyword for this check type is found, mark as PASSED
                 matched = False
                 for k, words in keywords.items():
@@ -82,12 +135,18 @@ def audit(path: str = "."):
                 
                 if matched:
                     check_status = "[bold green]PASSED[/bold green]"
-                    passed_checks += 1
+                    passed_checks += weight
+                    # Output source for evidence bridge
+                    if "Google" in framework_name:
+                        console.print(f"SOURCE: {check_key} | https://cloud.google.com/architecture/framework | Google Cloud Architecture Framework: {section['category']}")
                 else:
                     check_status = "[bold red]FAIL[/bold red]"
+                    # Output action for report
+                    console.print(f"ACTION: codebase | Architecture Gap: {check_key} | {rationale}")
+                    if "Google" in framework_name:
+                         console.print(f"SOURCE: {check_key} | https://cloud.google.com/architecture/framework | Recommended Pattern: {check_text}")
                 
-                import time
-                time.sleep(0.1) # Simulate deep heuristic scan
+                total_checks += weight
                 
                 table.add_row(check_text, check_status, rationale)
             
@@ -97,8 +156,10 @@ def audit(path: str = "."):
     score = (passed_checks / total_checks) * 100 if total_checks > 0 else 0
     console.print(f"📊 [bold]Review Score: {score:.0f}/100[/bold]")
     if score >= 80:
-        console.print(f"✅ [bold green]Architecture Review Complete.[/bold green] Your agent is well-aligned with {framework_name} patterns.")
+        console.print("✅ [bold green]Architecture Review Complete.[/bold green] Your agent is well-aligned with optimized patterns.")
     else:
+        if framework_key == "generic":
+            console.print("💡 [bold yellow]Self-Learning Note:[/bold yellow] Found unknown tech. I have mapped your code structure to universal agentic pillars (Reasoning/Tools/Safety).")
         console.print("⚠️ [bold yellow]Review Complete with warnings.[/bold yellow] Your agent has gaps in best practices. See results above.")
 
 if __name__ == "__main__":

agent_ops_cockpit/ops/cost_optimizer.py

@@ -1,4 +1,3 @@
-from typing import Dict
 import time
 
 class CostOptimizer:

agent_ops_cockpit/ops/evidence_bridge.py

@@ -0,0 +1,132 @@
+import json
+import os
+import urllib.request
+import xml.etree.ElementTree as ET
+import re
+from typing import Dict, Any, Optional, List
+import importlib.metadata
+from packaging import version
+from rich.console import Console
+
+console = Console()
+
+WATCHLIST_PATH = os.path.join(os.path.dirname(__file__), "watchlist.json")
+
+def clean_version(v_str: str) -> str:
+    match = re.search(r'(\d+\.\d+(?:\.\d+)?(?:[a-zA-Z]+\d+)?)', v_str)
+    if match:
+        return match.group(1)
+    return v_str.strip().lstrip('v')
+
+def fetch_latest_from_atom(url: str) -> Optional[Dict[str, str]]:
+    try:
+        req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
+        with urllib.request.urlopen(req, timeout=10) as response:
+            tree = ET.parse(response)
+            root = tree.getroot()
+            ns = {'ns': 'http://www.w3.org/2005/Atom'}
+            
+            latest_entry = root.find('ns:entry', ns)
+            if latest_entry is not None:
+                title = latest_entry.find('ns:title', ns).text
+                updated = latest_entry.find('ns:updated', ns).text
+                content_node = latest_entry.find('ns:content', ns)
+                summary = ""
+                if content_node is not None:
+                    summary = re.sub('<[^<]+?>', '', content_node.text or "")[:500] + "..."
+                
+                raw_v = title.strip().split()[-1]
+                return {
+                    "version": clean_version(raw_v) if "==" not in raw_v else clean_version(raw_v.split("==")[-1]),
+                    "date": updated,
+                    "title": title,
+                    "summary": summary
+                }
+    except Exception:
+        return None
+    return None
+
+def get_installed_version(package_name: str) -> str:
+    try:
+        return importlib.metadata.version(package_name)
+    except importlib.metadata.PackageNotFoundError:
+        return "Not Installed"
+
+def get_package_evidence(package_name: str) -> Dict[str, Any]:
+    if not os.path.exists(WATCHLIST_PATH):
+        return {"error": "Watchlist not found"}
+
+    with open(WATCHLIST_PATH, 'r') as f:
+        watchlist = json.load(f)
+
+    # Flatten categories to find the package
+    for cat_name, cat in watchlist.items():
+        if cat_name == "compatibility_rules":
+            continue
+        for name, info in cat.items():
+            if info.get("package") == package_name or name == package_name:
+                latest = fetch_latest_from_atom(info["feed"])
+                installed = get_installed_version(package_name)
+                min_v = info.get("min_version_for_optimizations", "0.0.0")
+                
+                upgrade_required = False
+                if installed != "Not Installed":
+                    try:
+                        if version.parse(installed) < version.parse(min_v):
+                            upgrade_required = True
+                    except Exception:
+                        pass
+
+                return {
+                    "package": package_name,
+                    "installed_version": installed,
+                    "latest_version": latest["version"] if latest else "Unknown",
+                    "min_optimized_version": min_v,
+                    "upgrade_required": upgrade_required,
+                    "release_date": latest["date"] if latest else "Unknown",
+                    "source_url": info["feed"].replace(".atom", ""),
+                    "best_practice_context": latest["summary"] if latest else "Check release notes for performance/security enhancements."
+                }
+    return {"error": f"Package {package_name} not found in watchlist"}
+
+def get_compatibility_report(installed_packages: List[str]) -> List[Dict[str, Any]]:
+    if not os.path.exists(WATCHLIST_PATH):
+        return []
+
+    with open(WATCHLIST_PATH, 'r') as f:
+        watchlist = json.load(f)
+    
+    rules = watchlist.get("compatibility_rules", [])
+    reports = []
+    
+    # Normalize imports to find root package names
+    roots = set()
+    for pkg in installed_packages:
+        roots.add(pkg.split('.')[0].replace('-', '_'))
+
+    for rule in rules:
+        comp_root = rule["component"].replace('-', '_')
+        if comp_root in roots:
+            # Check for incompatibilities
+            for forbidden in rule.get("incompatible_with", []):
+                forbidden_root = forbidden.replace('-', '_')
+                if forbidden_root in roots:
+                    reports.append({
+                        "type": "INCOMPATIBLE",
+                        "component": rule["component"],
+                        "conflict_with": forbidden,
+                        "reason": rule["reason"]
+                    })
+            
+            # Check for synergies
+            for synergy in rule.get("works_well_with", []):
+                synergy_root = synergy.replace('-', '_')
+                if synergy_root in roots:
+                    reports.append({
+                        "type": "SYNERGY",
+                        "component": rule["component"],
+                        "partner": synergy,
+                        "reason": f"Optimally paired with ecosystem partner {synergy}."
+                    })
+
+    return reports

agent_ops_cockpit/ops/frameworks.py

@@ -1,6 +1,5 @@
 import os
 import re
-from typing import Dict, List, Any
 
 # --- CHECKLISTS ---
 
@@ -11,7 +10,8 @@ GOOGLE_CHECKLIST = [
             ("Runtime: Is the agent running on Cloud Run or GKE?", "Critical for scalability and cost."),
             ("Framework: Is ADK used for tool orchestration?", "Google-standard for agent-tool communication."),
             ("Sandbox: Is Code Execution running in Vertex AI Sandbox?", "Prevents malicious code execution."),
-            ("Backend: Is FastAPI used for the Engine layer?", "Industry-standard for high-concurrency agent apps.")
+            ("Backend: Is FastAPI used for the Engine layer?", "Industry-standard for high-concurrency agent apps."),
+            ("Outputs: Are Pydantic or Response Schemas used for structured output?", "Ensures data integrity and reliable tool execution.")
         ]
     },
     {
@@ -19,7 +19,8 @@ GOOGLE_CHECKLIST = [
         "checks": [
             ("PII: Is a scrubber active before sending data to LLM?", "Compliance requirement (GDPR/SOC2)."),
             ("Identity: Is IAM used for tool access?", "Ensures least-privilege security."),
-            ("Safety: Are Vertex AI Safety Filters configured?", "Protects against toxic generation.")
+            ("Safety: Are Vertex AI Safety Filters configured?", "Protects against toxic generation."),
+            ("Policies: Is 'policies.json' used for declarative guardrails?", "Enforces RFC-307 standards for forbidden topics and tool HITL.")
         ]
     },
     {
@@ -47,6 +48,33 @@ GOOGLE_CHECKLIST = [
             ("Accessibility: Do interactive elements have aria-labels?", "Critical for inclusive design and automated testing."),
             ("Triggers: Are you using interactive triggers for state changes?", "Improves 'Agentic Feel' through reactive UI.")
         ]
+    },
+    {
+        "category": "🧗 Resiliency & Best Practices",
+        "checks": [
+            ("Resiliency: Are retries with exponential backoff used for API/DB calls?", "Prevents cascading failures during downtime (e.g., using tenacity)."),
+            ("Prompts: Are prompts stored in external '.md' or '.yaml' files?", "Best practice for separation of concerns and versioning."),
+            ("Sessions: Is there a session/conversation management layer?", "Ensures context continuity and user state tracking."),
+            ("Retrieval: Are you using RAG or Efficient Context Caching for large datasets?", "Optimizes performance vs. cost for retrieval-heavy agents.")
+        ]
+    },
+    {
+        "category": "⚖️ Legal & Compliance",
+        "checks": [
+            ("Copyright: Does every source file have a legal copyright header?", "IP protection and enterprise policy."),
+            ("License: Is there a LICENSE file in the root?", "Mandatory for legal distribution."),
+            ("Disclaimer: Does the agent provide a clear LLM-usage disclaimer?", "Liability mitigation for AI hallucinations."),
+            ("Data Residency: Is the agent region-restricted to us-central1 or equivalent?", "Ensures data stays within geofenced boundaries.")
+        ]
+    },
+    {
+        "category": "📢 Marketing & Brand",
+        "checks": [
+            ("Tone: Is the system prompt aligned with brand voice (Helpful/Professional)?", "Consistency in agent personality."),
+            ("SEO: Are OpenGraph and meta-tags present in the Face layer?", "Critical for discoverability and social sharing."),
+            ("Vibrancy: Does the UI use the standard corporate color palette?", "Prevents ad-hoc branding in autonomous UIs."),
+            ("CTA: Is there a clear Call-to-Action for every agent proposing a tool?", "Drives conversion and user engagement.")
+        ]
     }
 ]
 
@@ -214,18 +242,49 @@ LANGCHAIN_CHECKLIST = [
 
 GENERIC_CHECKLIST = [
     {
-        "category": "🏗️ General Agent Architecture",
+        "category": "🏗️ Zero-Shot Discovery (Unknown Tech)",
+        "checks": [
+            ("Reasoning: Does the code exhibit a core reasoning/execution loop?", "Detected Structural Pattern: Universal Agentic Loop."),
+            ("State: Is there an identifiable state management or memory pattern?", "Ensures session continuity even in custom stacks."),
+            ("Tools: Are external functions being called via a registry or dispatcher?", "Standard for tool-enabled agents."),
+            ("Safety: Are there any input/output sanitization blocks?", "Basic security hygiene for any AI application.")
+        ]
+    }
+]
+
+ORACLE_CHECKLIST = [
+    {
+        "category": "🏗️ Oracle Cloud Architecture",
         "checks": [
-            ("Tooling: Does the agent use structured tool calling?", "Essential for reliable interactions."),
-            ("Orchestration: Is there a clear reason-act loop?", "Ensures agentic behavior."),
-            ("Observability: Are traces/logs being captured?", "Critical for debugging production agents.")
+            ("Platform: Using OCI Generative AI or AI Agents?", "OCI-native managed agent orchestration."),
+            ("Data: Is Oracle Database 23ai (Vector Search) used?", "Enterprise-grade vector grounding for RAG."),
+            ("Compute: Is the agent running on OCI Container Instances or OCI Functions?", "Scale-to-zero and high-performance OCI compute options.")
         ]
     },
     {
-        "category": "🛡️ Security",
+        "category": "🛡️ Security & Governance (Oracle)",
         "checks": [
-            ("Sandbox: Are tools running in an isolated environment?", "Protects the host system."),
-            ("Input Validation: Are tool arguments validated?", "Prevents local execution attacks.")
+            ("Identity: Is OCI IAM with dynamic groups enabled?", "Ensures secure, credential-less access to OCI resources."),
+            ("Secrets: Using OCI Vault for API/DB secrets?", "Production standard for key management on OCI."),
+            ("Network: Is the agent isolated in an OCI VCN with Private Endpoints?", "Prevents internet exposure of internal agent tools.")
+        ]
+    }
+]
+
+CREWAI_CHECKLIST = [
+    {
+        "category": "🏗️ CrewAI Multi-Agent Architecture",
+        "checks": [
+            ("Orchestration: Is the 'Process' defined (Sequential/Hierarchical)?", "CrewAI best practice for complex team coordination."),
+            ("Memory: Is Short-term or Long-term memory enabled?", "Critical for maintaining context across multi-agent tasks."),
+            ("Tools: Are tools shared across the Crew or specific to Agents?", "Promotes agent specialization and efficiency.")
+        ]
+    },
+    {
+        "category": "🛡️ Security & Reliability",
+        "checks": [
+            ("Manager: Is a 'Manager Agent' used for hierarchical crews?", "Provides a central governance layer for agent handoffs."),
+            ("Delegation: Is 'allow_delegation' configured per agent?", "Controls the communication flow between autonomous agents.")
         ]
     }
 ]
@@ -370,6 +429,16 @@ FRAMEWORKS = {
         "checklist": FIREBASE_CHECKLIST,
         "indicators": [r"firebase\.json", r"\.firebaserc", r"firestore"]
     },
+    "oracle": {
+        "name": "Oracle Cloud Infrastructure (OCI)",
+        "checklist": ORACLE_CHECKLIST,
+        "indicators": [r"oci", r"oracle", r"23ai"]
+    },
+    "crewai": {
+        "name": "CrewAI",
+        "checklist": CREWAI_CHECKLIST,
+        "indicators": [r"crewai", r"Agent\(", r"Task\(", r"Crew\("]
+    },
     "generic": {
 
         "name": "Generic Agentic Stack",

agent_ops_cockpit/ops/mcp_hub.py

@@ -1,6 +1,5 @@
-from typing import List, Dict, Any, Optional
+from typing import List, Dict, Any
 import asyncio
-import json
 import os
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client