This commit is contained in:
@@ -1,27 +1 @@
|
||||
"""Tools package."""
|
||||
|
||||
from .gcp_scanner import GCPEnvironmentScanner
|
||||
from .mcp_developer_knowledge import (
|
||||
DeveloperKnowledgeMCPClient,
|
||||
developerknowledge_answer_query,
|
||||
developerknowledge_get_documents,
|
||||
developerknowledge_search_documents,
|
||||
get_mcp_client,
|
||||
)
|
||||
from .validation_tools import (
|
||||
validate_mermaid_diagram,
|
||||
validate_repository_artifacts,
|
||||
validate_terraform_syntax,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"validate_mermaid_diagram",
|
||||
"validate_repository_artifacts",
|
||||
"validate_terraform_syntax",
|
||||
"developerknowledge_search_documents",
|
||||
"developerknowledge_get_documents",
|
||||
"developerknowledge_answer_query",
|
||||
"DeveloperKnowledgeMCPClient",
|
||||
"get_mcp_client",
|
||||
"GCPEnvironmentScanner",
|
||||
]
|
||||
|
||||
318
app/tools/execution.py
Normal file
318
app/tools/execution.py
Normal file
@@ -0,0 +1,318 @@
|
||||
"""Execution tools: how agents act on an Execution.
|
||||
|
||||
Tools enforce the Ledger's rules at the moment an agent acts, and return refusals as
|
||||
messages so a ReAct agent can recover. A tool ends the agent's turn by returning an
|
||||
outcome.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from pathlib import PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import (
|
||||
FILES_SCHEMA,
|
||||
NeedsInput,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
files_from_argument,
|
||||
)
|
||||
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
DeliverableKind,
|
||||
PhaseId,
|
||||
check_submission,
|
||||
deliverables_in,
|
||||
)
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
CLOUD_READ = "cloud_read"
|
||||
|
||||
_NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}}
|
||||
|
||||
|
||||
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": dict(properties),
|
||||
"required": list(required),
|
||||
}
|
||||
|
||||
|
||||
def _refused(reason: object) -> ToolResult:
|
||||
return ToolResult(f"Refused: {reason}")
|
||||
|
||||
|
||||
class OrchestratorToolbox:
|
||||
"""The Orchestrator's tools, bound to a working copy of the Ledger for one turn."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
ledger: Ledger,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
pending_questions: Sequence[Mapping[str, Any]],
|
||||
) -> None:
|
||||
self.ledger = ledger
|
||||
self._deliverables = deliverables
|
||||
self._pending_questions = pending_questions
|
||||
self.started: dict[DeliverableKind, int] = {}
|
||||
self.questions: list[dict[str, str]] = []
|
||||
self.approval: dict[str, Any] | None = None
|
||||
self.escalation: str | None = None
|
||||
|
||||
def tools(self) -> list[ToolSpec]:
|
||||
return [
|
||||
ToolSpec(
|
||||
"ready_work",
|
||||
"List Deliverables ready to delegate and Phases ready for Approval.",
|
||||
_NO_ARGS,
|
||||
self.ready_work,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"delegate",
|
||||
"Start Specialists on ready Deliverables, in parallel. Ends your turn.",
|
||||
_schema(
|
||||
{"kinds": {"type": "array", "items": {"type": "string"}}},
|
||||
["kinds"],
|
||||
),
|
||||
self.delegate,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"ask_user",
|
||||
"Ask the user your questions together with any waiting Specialist "
|
||||
"questions. Ends your turn.",
|
||||
_schema(
|
||||
{"questions": {"type": "array", "items": {"type": "string"}}}, []
|
||||
),
|
||||
self.ask_user,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"request_approval",
|
||||
"Ask the user to approve a Phase whose Deliverables are all "
|
||||
"submitted. Ends your turn unless the Execution is pre-approved.",
|
||||
_schema(
|
||||
{"phase": {"type": "string"}, "summary": {"type": "string"}},
|
||||
["phase", "summary"],
|
||||
),
|
||||
self.request_approval,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"reopen",
|
||||
"Revise a submitted Deliverable; everything depending on it returns "
|
||||
"to draft.",
|
||||
_schema(
|
||||
{"kind": {"type": "string"}, "reason": {"type": "string"}},
|
||||
["kind", "reason"],
|
||||
),
|
||||
self.reopen,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"read_deliverable",
|
||||
"Read a submitted Deliverable's content.",
|
||||
_schema({"kind": {"type": "string"}}, ["kind"]),
|
||||
self.read_deliverable,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"finish",
|
||||
"Complete the Execution once packaging is approved. Ends your turn.",
|
||||
_NO_ARGS,
|
||||
self.finish,
|
||||
tier="execution",
|
||||
),
|
||||
]
|
||||
|
||||
async def ready_work(self) -> ToolResult:
|
||||
ready = ", ".join(self.ledger.ready_work()) or "none"
|
||||
phases = ", ".join(self.ledger.phases_ready_for_approval()) or "none"
|
||||
return ToolResult(
|
||||
f"Ready to delegate: {ready}. Phases ready for approval: {phases}."
|
||||
)
|
||||
|
||||
async def delegate(self, kinds: Sequence[str]) -> ToolResult:
|
||||
try:
|
||||
parsed = [DeliverableKind(kind) for kind in kinds]
|
||||
if not parsed:
|
||||
raise LedgerRefusal("name at least one Deliverable")
|
||||
started = self.ledger.start(parsed, actor=ORCHESTRATOR)
|
||||
except (ValueError, LedgerRefusal) as exc:
|
||||
return _refused(exc)
|
||||
self.started.update(started)
|
||||
return ToolResult(f"Started: {', '.join(started)}.", TurnEnded("delegate"))
|
||||
|
||||
async def ask_user(self, questions: Sequence[str] = ()) -> ToolResult:
|
||||
waiting = sorted(
|
||||
self._pending_questions,
|
||||
key=lambda item: list(DEPENDENCY_GRAPH).index(
|
||||
DeliverableKind(item["kind"])
|
||||
),
|
||||
)
|
||||
combined = [
|
||||
{"from": item["kind"], "question": question}
|
||||
for item in waiting
|
||||
for question in item["questions"]
|
||||
]
|
||||
combined += [{"from": ORCHESTRATOR, "question": q} for q in questions if q]
|
||||
if not combined:
|
||||
return _refused("there is nothing to ask the user")
|
||||
self.questions = combined
|
||||
return ToolResult("Asked the user.", TurnEnded("ask_user"))
|
||||
|
||||
async def request_approval(self, phase: str, summary: str) -> ToolResult:
|
||||
try:
|
||||
phase_id = PhaseId(phase)
|
||||
except ValueError as exc:
|
||||
return _refused(exc)
|
||||
if self.ledger.phase_status(phase_id) is not PhaseStatus.AWAITING_APPROVAL:
|
||||
try:
|
||||
self.ledger.request_approval(phase_id, actor=ORCHESTRATOR)
|
||||
except LedgerRefusal as exc:
|
||||
return _refused(exc)
|
||||
if self.ledger.phase_status(phase_id) is PhaseStatus.APPROVED:
|
||||
return ToolResult(
|
||||
f"Phase {phase_id} approved (pre-approved Execution)."
|
||||
)
|
||||
self.approval = {
|
||||
"phase": phase_id.value,
|
||||
"summary": summary,
|
||||
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
|
||||
}
|
||||
return ToolResult(
|
||||
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
|
||||
)
|
||||
|
||||
async def reopen(self, kind: str, reason: str) -> ToolResult:
|
||||
try:
|
||||
result = self.ledger.reopen(
|
||||
DeliverableKind(kind), reason, actor=ORCHESTRATOR
|
||||
)
|
||||
except (ValueError, LedgerRefusal) as exc:
|
||||
return _refused(exc)
|
||||
if result.escalation:
|
||||
if self.ledger.pre_approved:
|
||||
self.escalation = result.escalation
|
||||
return ToolResult(result.escalation, TurnEnded("escalate"))
|
||||
return ToolResult(
|
||||
f"{result.escalation} Use ask_user to put this to the user."
|
||||
)
|
||||
withdrawn = ", ".join(result.withdrawn_approvals) or "none"
|
||||
return ToolResult(
|
||||
f"Reopened {kind}. Returned to draft: {', '.join(result.reset)}. "
|
||||
f"Approvals withdrawn: {withdrawn}."
|
||||
)
|
||||
|
||||
async def read_deliverable(self, kind: str) -> ToolResult:
|
||||
deliverable = self._deliverables.get(kind)
|
||||
if deliverable is None:
|
||||
return ToolResult(f"{kind} has not been submitted.")
|
||||
return ToolResult(deliverable["content"])
|
||||
|
||||
async def finish(self) -> ToolResult:
|
||||
if not self.ledger.can_finish():
|
||||
return _refused("packaging has not been approved")
|
||||
return ToolResult("Finishing the Execution.", TurnEnded("finish"))
|
||||
|
||||
|
||||
def _safe_relative(name: str) -> bool:
|
||||
path = PurePosixPath(name)
|
||||
return bool(name) and not path.is_absolute() and ".." not in path.parts
|
||||
|
||||
|
||||
def specialist_tools(
|
||||
kind: DeliverableKind,
|
||||
extra: Sequence[ToolSpec],
|
||||
allow_cloud_read: bool | None,
|
||||
) -> list[ToolSpec]:
|
||||
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate."""
|
||||
|
||||
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
|
||||
try:
|
||||
attachments = files_from_argument(attachments)
|
||||
except TypeError as exc:
|
||||
return _refused(f"attachments: {exc}")
|
||||
unsafe = [name for name in attachments if not _safe_relative(name)]
|
||||
if unsafe:
|
||||
return _refused(
|
||||
"attachment names must be relative paths without '..': "
|
||||
+ ", ".join(unsafe)
|
||||
)
|
||||
missing = check_submission(kind, content, attachments)
|
||||
if missing:
|
||||
return ToolResult(
|
||||
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
|
||||
)
|
||||
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
|
||||
|
||||
async def needs_input(questions: Sequence[str]) -> ToolResult:
|
||||
questions = tuple(q for q in questions if q)
|
||||
if not questions:
|
||||
return _refused("ask at least one question")
|
||||
return ToolResult("Questions sent to the user.", NeedsInput(questions))
|
||||
|
||||
return [
|
||||
ToolSpec(
|
||||
"submit_deliverable",
|
||||
f"Submit the {kind} Deliverable once it meets its contract. Ends your turn.",
|
||||
_schema(
|
||||
{
|
||||
"content": {"type": "string"},
|
||||
"attachments": FILES_SCHEMA,
|
||||
},
|
||||
["content"],
|
||||
),
|
||||
submit_deliverable,
|
||||
tier="execution",
|
||||
),
|
||||
ToolSpec(
|
||||
"needs_input",
|
||||
"Ask the user questions you can't proceed without. Ends your turn.",
|
||||
_schema(
|
||||
{"questions": {"type": "array", "items": {"type": "string"}}},
|
||||
["questions"],
|
||||
),
|
||||
needs_input,
|
||||
tier="execution",
|
||||
),
|
||||
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
|
||||
]
|
||||
|
||||
|
||||
def gate_cloud_read(tool: ToolSpec, allow_cloud_read: bool | None) -> ToolSpec:
|
||||
"""Apply the Execution's cloud-read permission to a tool in that tier."""
|
||||
if tool.tier != CLOUD_READ or allow_cloud_read is True:
|
||||
return tool
|
||||
|
||||
if allow_cloud_read is False:
|
||||
|
||||
async def refuse(**_: Any) -> ToolResult:
|
||||
return _refused(
|
||||
"reading live cloud resources is not permitted for this Execution. "
|
||||
"Work from what the user has told you and record the gap."
|
||||
)
|
||||
|
||||
handler = refuse
|
||||
else:
|
||||
|
||||
async def ask_permission(**_: Any) -> ToolResult:
|
||||
return ToolResult(
|
||||
"Permission to read live cloud resources is needed first.",
|
||||
NeedsInput(
|
||||
(
|
||||
f"May I read live resources in your cloud environment? ({tool.name})",
|
||||
),
|
||||
permission=CLOUD_READ,
|
||||
),
|
||||
)
|
||||
|
||||
handler = ask_permission
|
||||
|
||||
return ToolSpec(tool.name, tool.description, tool.parameters, handler, tool.tier)
|
||||
@@ -1,346 +0,0 @@
|
||||
"""Live Google Cloud Environment & Resource Scanner.
|
||||
|
||||
Discovers and audits existing resources in a target Google Cloud project (GCS buckets,
|
||||
Compute Engine instances, Cloud SQL, Pub/Sub, Cloud Run) using Google Cloud REST APIs.
|
||||
Authenticated via Application Default Credentials (ADC), Service Account keys, or gcloud CLI tokens.
|
||||
"""
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import subprocess
|
||||
from typing import Any, Dict, List, Optional
|
||||
import httpx
|
||||
|
||||
try:
|
||||
import google.auth
|
||||
import google.auth.transport.requests
|
||||
HAS_GOOGLE_AUTH = True
|
||||
except ImportError:
|
||||
HAS_GOOGLE_AUTH = False
|
||||
|
||||
from app.config import get_settings
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class GCPEnvironmentScanner:
|
||||
"""Scans and audits live resources in a target Google Cloud project."""
|
||||
|
||||
def __init__(self, project_id: Optional[str] = None) -> None:
|
||||
settings = get_settings()
|
||||
self.project_id = project_id or settings.GCP_PROJECT_ID or os.getenv("GCP_PROJECT_ID")
|
||||
self.timeout = httpx.Timeout(10.0)
|
||||
if not self.project_id:
|
||||
self._auto_detect_project()
|
||||
|
||||
def _auto_detect_project(self) -> None:
|
||||
"""Attempt auto-detecting project ID via gcloud CLI."""
|
||||
try:
|
||||
cmd = ["gcloud", "config", "get-value", "project", "--quiet"]
|
||||
proj = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL).strip()
|
||||
if proj and proj != "(unset)":
|
||||
self.project_id = proj
|
||||
logger.info("Auto-detected GCP project_id: '%s'", proj)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
def _get_access_token(self) -> Optional[str]:
|
||||
"""Obtain a valid OAuth2 bearer token from GCP_ACCESS_TOKEN env, service account key, google.auth, or gcloud CLI."""
|
||||
# Method 0: Direct access token passed via environment
|
||||
env_token = os.getenv("GCP_ACCESS_TOKEN")
|
||||
if env_token and env_token.strip():
|
||||
logger.info("Obtained GCP OAuth2 bearer token from GCP_ACCESS_TOKEN environment variable.")
|
||||
return env_token.strip()
|
||||
|
||||
settings = get_settings()
|
||||
key_path = settings.GOOGLE_APPLICATION_CREDENTIALS or os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
|
||||
|
||||
# Method 1: Try Service Account Key file directly if specified
|
||||
if key_path and os.path.isfile(key_path) and HAS_GOOGLE_AUTH:
|
||||
try:
|
||||
from google.oauth2 import service_account
|
||||
scopes = ["https://www.googleapis.com/auth/cloud-platform"]
|
||||
creds = service_account.Credentials.from_service_account_file(key_path, scopes=scopes)
|
||||
auth_req = google.auth.transport.requests.Request()
|
||||
creds.refresh(auth_req)
|
||||
if creds.project_id and not self.project_id:
|
||||
self.project_id = creds.project_id
|
||||
if creds.token:
|
||||
logger.info("Obtained GCP token via Service Account Key file: %s", key_path)
|
||||
return creds.token
|
||||
except Exception as exc:
|
||||
logger.debug("Service account key auth failed for %s: %s", key_path, exc)
|
||||
|
||||
# Method 2: Try google.auth.default()
|
||||
if HAS_GOOGLE_AUTH:
|
||||
try:
|
||||
creds, proj = google.auth.default(
|
||||
scopes=["https://www.googleapis.com/auth/cloud-platform"]
|
||||
)
|
||||
auth_req = google.auth.transport.requests.Request()
|
||||
creds.refresh(auth_req)
|
||||
if not self.project_id and proj:
|
||||
self.project_id = proj
|
||||
if creds.token:
|
||||
logger.info("Obtained GCP token via Application Default Credentials.")
|
||||
return creds.token
|
||||
except Exception as exc:
|
||||
logger.debug("google.auth.default token acquisition failed: %s", exc)
|
||||
|
||||
# Method 3: Fallback to gcloud CLI token (with --quiet)
|
||||
try:
|
||||
cmd = ["gcloud", "auth", "print-access-token", "--quiet"]
|
||||
token = subprocess.check_output(cmd, text=True, stderr=subprocess.DEVNULL).strip()
|
||||
if token:
|
||||
logger.info("Obtained GCP token via gcloud auth print-access-token --quiet.")
|
||||
return token
|
||||
except Exception as exc:
|
||||
logger.debug("gcloud auth print-access-token fallback failed: %s", exc)
|
||||
|
||||
return None
|
||||
|
||||
def scan_environment(self) -> Dict[str, Any]:
|
||||
"""Execute a full live environment scan against the target GCP project."""
|
||||
token = self._get_access_token()
|
||||
if not token or not self.project_id:
|
||||
logger.warning(
|
||||
"GCP Scanner unable to authenticate or project_id missing (project_id=%s, token_present=%s). "
|
||||
"Using fallback baseline template.",
|
||||
self.project_id,
|
||||
bool(token),
|
||||
)
|
||||
return {"authenticated": False, "project_id": self.project_id, "resources": {}}
|
||||
|
||||
headers = {"Authorization": f"Bearer {token}"}
|
||||
resources: Dict[str, Any] = {
|
||||
"project_id": self.project_id,
|
||||
"gcs_buckets": [],
|
||||
"compute_instances": [],
|
||||
"cloud_sql_instances": [],
|
||||
"pubsub_topics": [],
|
||||
"cloud_run_services": [],
|
||||
"disabled_apis": [],
|
||||
}
|
||||
|
||||
with httpx.Client(timeout=self.timeout) as client:
|
||||
# 1. Scan GCS Buckets
|
||||
try:
|
||||
r = client.get(
|
||||
f"https://storage.googleapis.com/storage/v1/b?project={self.project_id}",
|
||||
headers=headers,
|
||||
)
|
||||
if r.status_code == 200:
|
||||
items = r.json().get("items", [])
|
||||
resources["gcs_buckets"] = [
|
||||
{"name": item.get("name"), "location": item.get("location"), "storage_class": item.get("storageClass")}
|
||||
for item in items
|
||||
]
|
||||
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
|
||||
resources["disabled_apis"].append("storage.googleapis.com")
|
||||
except Exception as exc:
|
||||
logger.debug("GCS scan error: %s", exc)
|
||||
|
||||
# 2. Scan Compute Engine Instances
|
||||
try:
|
||||
r = client.get(
|
||||
f"https://compute.googleapis.com/compute/v1/projects/{self.project_id}/aggregated/instances",
|
||||
headers=headers,
|
||||
)
|
||||
if r.status_code == 200:
|
||||
items_dict = r.json().get("items", {})
|
||||
instances = []
|
||||
for zone, zone_data in items_dict.items():
|
||||
for inst in zone_data.get("instances", []):
|
||||
instances.append({
|
||||
"name": inst.get("name"),
|
||||
"zone": zone.replace("zones/", ""),
|
||||
"status": inst.get("status"),
|
||||
"machine_type": inst.get("machineType", "").split("/")[-1],
|
||||
})
|
||||
resources["compute_instances"] = instances
|
||||
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
|
||||
resources["disabled_apis"].append("compute.googleapis.com")
|
||||
except Exception as exc:
|
||||
logger.debug("Compute Engine scan error: %s", exc)
|
||||
|
||||
# 3. Scan Cloud SQL Instances
|
||||
try:
|
||||
r = client.get(
|
||||
f"https://sqladmin.googleapis.com/v1/projects/{self.project_id}/instances",
|
||||
headers=headers,
|
||||
)
|
||||
if r.status_code == 200:
|
||||
items = r.json().get("items", [])
|
||||
resources["cloud_sql_instances"] = [
|
||||
{
|
||||
"name": item.get("name"),
|
||||
"database_version": item.get("databaseVersion"),
|
||||
"region": item.get("region"),
|
||||
"state": item.get("state"),
|
||||
}
|
||||
for item in items
|
||||
]
|
||||
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
|
||||
resources["disabled_apis"].append("sqladmin.googleapis.com")
|
||||
except Exception as exc:
|
||||
logger.debug("Cloud SQL scan error: %s", exc)
|
||||
|
||||
# 4. Scan Pub/Sub Topics
|
||||
try:
|
||||
r = client.get(
|
||||
f"https://pubsub.googleapis.com/v1/projects/{self.project_id}/topics",
|
||||
headers=headers,
|
||||
)
|
||||
if r.status_code == 200:
|
||||
topics = r.json().get("topics", [])
|
||||
resources["pubsub_topics"] = [
|
||||
{"name": t.get("name", "").split("/")[-1]} for t in topics
|
||||
]
|
||||
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
|
||||
resources["disabled_apis"].append("pubsub.googleapis.com")
|
||||
except Exception as exc:
|
||||
logger.debug("Pub/Sub scan error: %s", exc)
|
||||
|
||||
# 5. Scan Cloud Run Services
|
||||
try:
|
||||
r = client.get(
|
||||
f"https://run.googleapis.com/v2/projects/{self.project_id}/locations/-/services",
|
||||
headers=headers,
|
||||
)
|
||||
if r.status_code == 200:
|
||||
services = r.json().get("services", [])
|
||||
resources["cloud_run_services"] = [
|
||||
{"name": s.get("name", "").split("/")[-1], "uri": s.get("uri")}
|
||||
for s in services
|
||||
]
|
||||
elif r.status_code == 403 and "SERVICE_DISABLED" in r.text:
|
||||
resources["disabled_apis"].append("run.googleapis.com")
|
||||
except Exception as exc:
|
||||
logger.debug("Cloud Run scan error: %s", exc)
|
||||
|
||||
return {"authenticated": True, "project_id": self.project_id, "resources": resources}
|
||||
|
||||
def format_scan_report(self, scan_result: Dict[str, Any]) -> Dict[str, str]:
|
||||
"""Format live environment scan findings into markdown report and Mermaid diagram."""
|
||||
if not scan_result.get("authenticated") or not scan_result.get("resources"):
|
||||
# Fallback
|
||||
doc = """# Pre-emptive Source Environment Discovery (As-Is Architecture)
|
||||
|
||||
## Existing Workload Audit
|
||||
- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment)
|
||||
- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure
|
||||
- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS
|
||||
- **Application Runtime**: Monolithic Application Instance (Single Point of Failure)
|
||||
- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk)
|
||||
- **Queue / Messaging**: Local RabbitMQ Queue Instance
|
||||
|
||||
## Current Operational Pain Points & Bottlenecks
|
||||
- Single-instance compute leading to downtime during maintenance windows.
|
||||
- Manual scaling capabilities unable to handle unexpected traffic spikes.
|
||||
- Unencrypted local storage and unmanaged backups creating data loss risks.
|
||||
- Elevated operational overhead and hardware lifecycle costs.
|
||||
|
||||
## Source Component Topology
|
||||
- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ`
|
||||
"""
|
||||
mmd = """flowchart TD
|
||||
Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy]
|
||||
NginxProxy --> MonolithApp[Monolithic Application VM]
|
||||
MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)]
|
||||
MonolithApp --> LocalQueue[Local RabbitMQ Queue]
|
||||
"""
|
||||
return {"doc": doc, "mermaid": mmd}
|
||||
|
||||
res = scan_result["resources"]
|
||||
proj_id = res.get("project_id", "Unknown")
|
||||
buckets = res.get("gcs_buckets", [])
|
||||
instances = res.get("compute_instances", [])
|
||||
sql_instances = res.get("cloud_sql_instances", [])
|
||||
topics = res.get("pubsub_topics", [])
|
||||
run_services = res.get("cloud_run_services", [])
|
||||
disabled_apis = res.get("disabled_apis", [])
|
||||
|
||||
# Build Markdown Document
|
||||
doc_lines = [
|
||||
f"# Pre-emptive Live GCP Environment Discovery (Project: `{proj_id}`)",
|
||||
"",
|
||||
"## Live Resource Audit",
|
||||
f"- **Target Google Cloud Project**: `{proj_id}`",
|
||||
f"- **Discovered Storage Buckets**: {len(buckets)} GCS Bucket(s)" if buckets else "- **Discovered Storage Buckets**: None / Default Bucket",
|
||||
f"- **Discovered Compute Instances**: {len(instances)} Compute VM(s)" if instances else "- **Discovered Compute Instances**: None active",
|
||||
f"- **Discovered Database Instances**: {len(sql_instances)} Cloud SQL DB(s)" if sql_instances else "- **Discovered Database Instances**: None active",
|
||||
f"- **Discovered Pub/Sub Topics**: {len(topics)} Topic(s)" if topics else "- **Discovered Pub/Sub Topics**: None active",
|
||||
f"- **Discovered Cloud Run Services**: {len(run_services)} Service(s)" if run_services else "- **Discovered Cloud Run Services**: None active",
|
||||
"",
|
||||
"## Resource Inventory Breakdown",
|
||||
]
|
||||
|
||||
if buckets:
|
||||
doc_lines.append("### Cloud Storage Buckets")
|
||||
for b in buckets:
|
||||
doc_lines.append(f"- `b/{b['name']}` (Location: `{b['location']}`, Storage Class: `{b['storage_class']}`)")
|
||||
doc_lines.append("")
|
||||
|
||||
if instances:
|
||||
doc_lines.append("### Compute Engine Instances")
|
||||
for inst in instances:
|
||||
doc_lines.append(f"- VM `instance/{inst['name']}` (Zone: `{inst['zone']}`, Type: `{inst['machine_type']}`, Status: `{inst['status']}`)")
|
||||
doc_lines.append("")
|
||||
|
||||
if sql_instances:
|
||||
doc_lines.append("### Cloud SQL Databases")
|
||||
for sql in sql_instances:
|
||||
doc_lines.append(f"- DB `sql/{sql['name']}` (Engine: `{sql['database_version']}`, Region: `{sql['region']}`, State: `{sql['state']}`)")
|
||||
doc_lines.append("")
|
||||
|
||||
if topics:
|
||||
doc_lines.append("### Cloud Pub/Sub Topics")
|
||||
for t in topics:
|
||||
doc_lines.append(f"- Topic `pubsub/{t['name']}`")
|
||||
doc_lines.append("")
|
||||
|
||||
if run_services:
|
||||
doc_lines.append("### Cloud Run Services")
|
||||
for s in run_services:
|
||||
doc_lines.append(f"- Service `run/{s['name']}` (URI: `{s['uri']}`)")
|
||||
doc_lines.append("")
|
||||
|
||||
if disabled_apis:
|
||||
doc_lines.append("### API Status Diagnostics")
|
||||
for api in disabled_apis:
|
||||
doc_lines.append(f"- `SERVICE_DISABLED`: `{api}` is not enabled on project `{proj_id}`.")
|
||||
doc_lines.append("")
|
||||
|
||||
doc_lines.extend([
|
||||
"## Current Operational Bottlenecks & Migration Drivers",
|
||||
"- As-is infrastructure requires serverless auto-scaling and managed high availability.",
|
||||
"- Need for declarative IaC management via Terraform.",
|
||||
"- Transition to least-privilege IAM service identities and automated CI validation.",
|
||||
])
|
||||
|
||||
# Build Mermaid Diagram
|
||||
mmd_lines = ["flowchart TD", f" subgraph GCPProject[\"Google Cloud Project: {proj_id}\"]"]
|
||||
if buckets:
|
||||
for i, b in enumerate(buckets[:3]):
|
||||
mmd_lines.append(f" GCS{i}[(\"GCS: {b['name']}\")]")
|
||||
if instances:
|
||||
for i, inst in enumerate(instances[:3]):
|
||||
mmd_lines.append(f" VM{i}[\"GCE: {inst['name']}\"]")
|
||||
if sql_instances:
|
||||
for i, sql in enumerate(sql_instances[:3]):
|
||||
mmd_lines.append(f" SQL{i}[(\"Cloud SQL: {sql['name']}\")]")
|
||||
if topics:
|
||||
for i, t in enumerate(topics[:3]):
|
||||
mmd_lines.append(f" PubSub{i}[\"PubSub: {t['name']}\"]")
|
||||
if run_services:
|
||||
for i, s in enumerate(run_services[:3]):
|
||||
mmd_lines.append(f" Run{i}[\"Cloud Run: {s['name']}\"]")
|
||||
|
||||
if not (buckets or instances or sql_instances or topics or run_services):
|
||||
mmd_lines.append(f" EmptyProject[\"Project {proj_id} (No Active Resources Detected)\"]")
|
||||
|
||||
mmd_lines.append(" end")
|
||||
mmd_lines.append(" Client[External Traffic] --> GCPProject")
|
||||
|
||||
return {"doc": "\n".join(doc_lines), "mermaid": "\n".join(mmd_lines)}
|
||||
@@ -10,12 +10,12 @@ import asyncio
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
from collections.abc import Iterable, Mapping
|
||||
from collections.abc import Awaitable, Callable, Iterable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from app.agents.runtime import ToolResult, ToolSpec
|
||||
from app.adk.runtime import FILES_SCHEMA, ToolResult, ToolSpec, files_from_argument
|
||||
|
||||
_MAX_OUTPUT = 8_000
|
||||
_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json")
|
||||
@@ -108,7 +108,7 @@ class TerraformRunner:
|
||||
if refusal:
|
||||
return refusal
|
||||
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
root = _write(Path(tmp), files) / _module_dir(files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
@@ -127,7 +127,7 @@ class TerraformRunner:
|
||||
if bad:
|
||||
return ToolResult(f"Refused: invalid variable names {', '.join(bad)}")
|
||||
with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
root = _write(Path(tmp), files) / _module_dir(files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
@@ -198,9 +198,20 @@ def _check_files(files: Mapping[str, str]) -> ToolResult | None:
|
||||
"Refused: file names must be relative .tf, .tf.json or .tfvars paths "
|
||||
f"without '..': {', '.join(bad)}"
|
||||
)
|
||||
directories = {str(PurePosixPath(name).parent) for name in files}
|
||||
if len(directories) > 1:
|
||||
return ToolResult(
|
||||
"Refused: put all files in one directory (one root module), for example "
|
||||
f"terraform/main.tf and terraform/variables.tf; got {', '.join(sorted(directories))}"
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _module_dir(files: Mapping[str, str]) -> str:
|
||||
"""The one directory holding the files; Terraform runs there."""
|
||||
return str(PurePosixPath(next(iter(files))).parent)
|
||||
|
||||
|
||||
def _write(root: Path, files: Mapping[str, str]) -> Path:
|
||||
for name, content in files.items():
|
||||
target = root / name
|
||||
@@ -214,11 +225,26 @@ def _clip(text: str) -> str:
|
||||
|
||||
|
||||
_FILES_SCHEMA: dict[str, Any] = {
|
||||
"type": "object",
|
||||
"description": "Terraform files by relative path, e.g. {'main.tf': '...'}",
|
||||
"additionalProperties": {"type": "string"},
|
||||
**FILES_SCHEMA,
|
||||
"description": "Terraform files in one directory, e.g. terraform/main.tf",
|
||||
}
|
||||
|
||||
|
||||
def _with_files(
|
||||
method: Callable[..., Awaitable[ToolResult]],
|
||||
) -> Callable[..., Awaitable[ToolResult]]:
|
||||
"""Adapt a runner method to take the FILES_SCHEMA argument."""
|
||||
|
||||
async def handler(files: Any, **kwargs: Any) -> ToolResult:
|
||||
try:
|
||||
converted = files_from_argument(files)
|
||||
except TypeError as exc:
|
||||
return ToolResult(f"Refused: files: {exc}")
|
||||
return await method(converted, **kwargs)
|
||||
|
||||
return handler
|
||||
|
||||
|
||||
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
||||
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
|
||||
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
|
||||
@@ -254,7 +280,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.fmt,
|
||||
_with_files(runner.fmt),
|
||||
tier="general",
|
||||
),
|
||||
"terraform_validate": lambda: ToolSpec(
|
||||
@@ -265,7 +291,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.validate,
|
||||
_with_files(runner.validate),
|
||||
tier="general",
|
||||
),
|
||||
"terraform_plan": lambda: ToolSpec(
|
||||
@@ -282,7 +308,7 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
|
||||
},
|
||||
"required": ["files"],
|
||||
},
|
||||
runner.plan,
|
||||
_with_files(runner.plan),
|
||||
tier="cloud_read",
|
||||
),
|
||||
}
|
||||
|
||||
@@ -22,7 +22,7 @@ from mcp import ClientSession
|
||||
from mcp.client.streamable_http import streamable_http_client
|
||||
from mcp.shared._httpx_utils import create_mcp_http_client
|
||||
|
||||
from app.agents.runtime import ToolResult, ToolSpec
|
||||
from app.adk.runtime import ToolResult, ToolSpec
|
||||
from app.providers import McpServerSpec
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -1,258 +0,0 @@
|
||||
"""Google Developer Knowledge MCP (Model Context Protocol) Client & Tools.
|
||||
|
||||
Provides integration with the Google Developer Knowledge MCP server (https://developerknowledge.googleapis.com/mcp).
|
||||
Implements official MCP tools:
|
||||
- developerknowledge:search_documents
|
||||
- developerknowledge:get_documents
|
||||
- developerknowledge:answer_query
|
||||
|
||||
Supports live HTTP/JSON-RPC MCP requests with built-in offline GCP knowledge fallback
|
||||
for offline testing and high availability.
|
||||
"""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict, List, Optional
|
||||
import httpx
|
||||
from langchain_core.tools import tool
|
||||
|
||||
from app.config import get_settings
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Fallback Offline GCP Developer Knowledge Base
|
||||
OFFLINE_GCP_KNOWLEDGE_BASE: Dict[str, Dict[str, Any]] = {
|
||||
"cloud_run": {
|
||||
"title": "Google Cloud Run Architecture Guide",
|
||||
"uri": "https://cloud.google.com/run/docs/overview/what-is-cloud-run",
|
||||
"release_status": "GA (General Availability)",
|
||||
"category": "compute",
|
||||
"summary": "Stateless container execution platform with automatic scaling from zero to thousands of instances, built on Knative.",
|
||||
"citations": ["https://cloud.google.com/run/docs/securing/service-identity"],
|
||||
},
|
||||
"pubsub": {
|
||||
"title": "Google Cloud Pub/Sub Messaging Best Practices",
|
||||
"uri": "https://cloud.google.com/pubsub/docs/overview",
|
||||
"release_status": "GA (General Availability)",
|
||||
"category": "messaging",
|
||||
"summary": "Globally distributed, asynchronous message bus providing at-least-once delivery with dead-letter topics and exponential backoff.",
|
||||
"citations": ["https://cloud.google.com/pubsub/docs/dead-letter-topics"],
|
||||
},
|
||||
"storage": {
|
||||
"title": "Google Cloud Storage Object Lifecycle & Security",
|
||||
"uri": "https://cloud.google.com/storage/docs/overview",
|
||||
"release_status": "GA (General Availability)",
|
||||
"category": "storage",
|
||||
"summary": "Unified object storage with uniform bucket-level access, retention lifecycle rules, customer-managed encryption (CMEK), and audit logging.",
|
||||
"citations": ["https://cloud.google.com/storage/docs/uniform-bucket-level-access"],
|
||||
},
|
||||
"firestore": {
|
||||
"title": "Google Cloud Firestore Document Database",
|
||||
"uri": "https://cloud.google.com/firestore/docs/overview",
|
||||
"release_status": "GA (General Availability)",
|
||||
"category": "database",
|
||||
"summary": "Serverless, flexible NoSQL document database built for automatic scaling, rich queries, and ACID multi-document transactions.",
|
||||
"citations": ["https://cloud.google.com/firestore/docs/best-practices"],
|
||||
},
|
||||
"iam": {
|
||||
"title": "Google Cloud IAM Least-Privilege Identity Guide",
|
||||
"uri": "https://cloud.google.com/iam/docs/overview",
|
||||
"release_status": "GA (General Availability)",
|
||||
"category": "security",
|
||||
"summary": "Fine-grained access control and least-privilege service identity management for Google Cloud resources.",
|
||||
"citations": ["https://cloud.google.com/iam/docs/using-iam-securely"],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
class DeveloperKnowledgeMCPClient:
|
||||
"""Client for Google Developer Knowledge MCP server."""
|
||||
|
||||
def __init__(self, mcp_url: Optional[str] = None) -> None:
|
||||
settings = get_settings()
|
||||
self.mcp_url = mcp_url or settings.DEVELOPER_KNOWLEDGE_MCP_URL
|
||||
self.enabled = settings.DEVELOPER_KNOWLEDGE_MCP_ENABLED
|
||||
self.timeout = httpx.Timeout(5.0)
|
||||
|
||||
def search_documents(self, query: str, category: str = "all") -> Dict[str, Any]:
|
||||
"""Search Google Cloud reference architecture, decision-making, and best-practice documents."""
|
||||
if self.enabled and self.mcp_url:
|
||||
try:
|
||||
payload = {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "developerknowledge:search_documents",
|
||||
"arguments": {"query": query, "category": category},
|
||||
},
|
||||
"id": 1,
|
||||
}
|
||||
with httpx.Client(timeout=self.timeout) as client:
|
||||
resp = client.post(self.mcp_url, json=payload)
|
||||
if resp.status_code == 200:
|
||||
data = resp.json()
|
||||
if "result" in data:
|
||||
return {"source": "live_mcp", "data": data["result"]}
|
||||
except Exception as exc:
|
||||
logger.debug("Live MCP search_documents query failed (%s); using offline knowledge base.", exc)
|
||||
|
||||
# Offline fallback search
|
||||
results = []
|
||||
q_lower = query.lower()
|
||||
for key, doc in OFFLINE_GCP_KNOWLEDGE_BASE.items():
|
||||
if (
|
||||
q_lower in doc["title"].lower()
|
||||
or q_lower in doc["summary"].lower()
|
||||
or q_lower in doc["category"].lower()
|
||||
or category == "all"
|
||||
or category == doc["category"]
|
||||
):
|
||||
results.append(doc)
|
||||
|
||||
return {
|
||||
"source": "offline_fallback",
|
||||
"query": query,
|
||||
"category": category,
|
||||
"total_matches": len(results),
|
||||
"documents": results,
|
||||
}
|
||||
|
||||
def get_documents(self, document_uri: str) -> Dict[str, Any]:
|
||||
"""Fetch official Google Cloud document content and citations by URI."""
|
||||
if self.enabled and self.mcp_url:
|
||||
try:
|
||||
payload = {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "developerknowledge:get_documents",
|
||||
"arguments": {"document_uri": document_uri},
|
||||
},
|
||||
"id": 2,
|
||||
}
|
||||
with httpx.Client(timeout=self.timeout) as client:
|
||||
resp = client.post(self.mcp_url, json=payload)
|
||||
if resp.status_code == 200:
|
||||
data = resp.json()
|
||||
if "result" in data:
|
||||
return {"source": "live_mcp", "data": data["result"]}
|
||||
except Exception as exc:
|
||||
logger.debug("Live MCP get_documents query failed (%s); using offline knowledge base.", exc)
|
||||
|
||||
# Search matching offline doc
|
||||
for doc in OFFLINE_GCP_KNOWLEDGE_BASE.values():
|
||||
if document_uri in doc["uri"] or doc["uri"] in document_uri:
|
||||
return {"source": "offline_fallback", "document": doc}
|
||||
|
||||
return {
|
||||
"source": "offline_fallback",
|
||||
"document_uri": document_uri,
|
||||
"document": {
|
||||
"title": f"Google Cloud Documentation ({document_uri})",
|
||||
"uri": document_uri,
|
||||
"release_status": "GA",
|
||||
"summary": "Official Google Cloud architecture reference documentation.",
|
||||
"citations": [document_uri],
|
||||
},
|
||||
}
|
||||
|
||||
def answer_query(self, query: str) -> Dict[str, Any]:
|
||||
"""Answer architectural questions and check GCP product release statuses and best practices."""
|
||||
if self.enabled and self.mcp_url:
|
||||
try:
|
||||
payload = {
|
||||
"jsonrpc": "2.0",
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "developerknowledge:answer_query",
|
||||
"arguments": {"query": query},
|
||||
},
|
||||
"id": 3,
|
||||
}
|
||||
with httpx.Client(timeout=self.timeout) as client:
|
||||
resp = client.post(self.mcp_url, json=payload)
|
||||
if resp.status_code == 200:
|
||||
data = resp.json()
|
||||
if "result" in data:
|
||||
return {"source": "live_mcp", "answer": data["result"]}
|
||||
except Exception as exc:
|
||||
logger.debug("Live MCP answer_query failed (%s); using offline knowledge base.", exc)
|
||||
|
||||
# Offline grounding logic
|
||||
q_lower = query.lower()
|
||||
if "release status" in q_lower or "deprecated" in q_lower:
|
||||
return {
|
||||
"source": "offline_fallback",
|
||||
"query": query,
|
||||
"status_check": "All recommended products (Cloud Run, Pub/Sub, Cloud Storage, Firestore, Cloud IAM) are Active GA (General Availability). None are deprecated.",
|
||||
"supported": True,
|
||||
}
|
||||
|
||||
return {
|
||||
"source": "offline_fallback",
|
||||
"query": query,
|
||||
"answer": (
|
||||
"Google Cloud Architecture Best Practice: Design regional event-driven workloads "
|
||||
"using Cloud Run for stateless container execution, Pub/Sub for asynchronous message buffering, "
|
||||
"and Cloud Storage / Firestore for durable state retention under least-privilege IAM."
|
||||
),
|
||||
"citations": ["https://cloud.google.com/architecture/framework"],
|
||||
}
|
||||
|
||||
|
||||
# Singleton client instance
|
||||
_mcp_client: Optional[DeveloperKnowledgeMCPClient] = None
|
||||
|
||||
|
||||
def get_mcp_client() -> DeveloperKnowledgeMCPClient:
|
||||
"""Get singleton DeveloperKnowledgeMCPClient."""
|
||||
global _mcp_client
|
||||
if _mcp_client is None:
|
||||
_mcp_client = DeveloperKnowledgeMCPClient()
|
||||
return _mcp_client
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# LangChain @tool wrappers matching official Google spec
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@tool
|
||||
def developerknowledge_search_documents(query: str, category: str = "all") -> Dict[str, Any]:
|
||||
"""Searches Google Cloud reference architecture, decision-making, and best-practice documents.
|
||||
|
||||
Args:
|
||||
query: Search query string (e.g. 'Cloud Run PubSub event architecture').
|
||||
category: Optional category filter ('compute', 'messaging', 'storage', 'security', or 'all').
|
||||
|
||||
Returns:
|
||||
Dict containing matching Google Cloud documents and citations.
|
||||
"""
|
||||
client = get_mcp_client()
|
||||
return client.search_documents(query=query, category=category)
|
||||
|
||||
|
||||
@tool
|
||||
def developerknowledge_get_documents(document_uri: str) -> Dict[str, Any]:
|
||||
"""Retrieves official Google Cloud document content and citations by URI.
|
||||
|
||||
Args:
|
||||
document_uri: Official Google Cloud documentation URL or document identifier.
|
||||
|
||||
Returns:
|
||||
Dict containing document metadata, summary, and citations.
|
||||
"""
|
||||
client = get_mcp_client()
|
||||
return client.get_documents(document_uri=document_uri)
|
||||
|
||||
|
||||
@tool
|
||||
def developerknowledge_answer_query(query: str) -> Dict[str, Any]:
|
||||
"""Answers architectural questions and checks GCP product release statuses and best practices.
|
||||
|
||||
Args:
|
||||
query: Architectural question or product status query string.
|
||||
|
||||
Returns:
|
||||
Dict containing grounded answer, release status, and documentation citations.
|
||||
"""
|
||||
client = get_mcp_client()
|
||||
return client.answer_query(query=query)
|
||||
111
app/tools/pillars.py
Normal file
111
app/tools/pillars.py
Normal file
@@ -0,0 +1,111 @@
|
||||
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
|
||||
|
||||
Pillar advice is working material for the design recommendations Deliverable, not a
|
||||
Deliverable itself, so it never touches the Ledger.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import dataclasses
|
||||
from collections.abc import Mapping, Sequence
|
||||
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
RoleSpec,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
CONSULT_TOOL = "consult_pillar_advisors"
|
||||
|
||||
|
||||
def pillar_consultation_tool(
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar_skills: Mapping[str, str],
|
||||
extra_tools: Sequence[ToolSpec] = (),
|
||||
) -> ToolSpec:
|
||||
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
|
||||
|
||||
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
|
||||
chosen = list(pillars) if pillars else list(pillar_skills)
|
||||
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
|
||||
if unknown:
|
||||
return ToolResult(
|
||||
f"Refused: unknown pillars {', '.join(unknown)}; "
|
||||
f"choose from {', '.join(pillar_skills)}"
|
||||
)
|
||||
results = await asyncio.gather(
|
||||
*(
|
||||
_advise(
|
||||
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
||||
)
|
||||
for pillar in chosen
|
||||
)
|
||||
)
|
||||
return ToolResult("\n\n".join(results))
|
||||
|
||||
return ToolSpec(
|
||||
CONSULT_TOOL,
|
||||
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
|
||||
"Give a brief with the workload, its requirements and the selected products.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"brief": {"type": "string"},
|
||||
"pillars": {
|
||||
"type": "array",
|
||||
"items": {"type": "string", "enum": list(pillar_skills)},
|
||||
},
|
||||
},
|
||||
"required": ["brief"],
|
||||
},
|
||||
consult,
|
||||
)
|
||||
|
||||
|
||||
async def _advise(
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar: str,
|
||||
skill: str,
|
||||
brief: str,
|
||||
extra_tools: Sequence[ToolSpec],
|
||||
) -> str:
|
||||
role = dataclasses.replace(advisor, skills=(skill,))
|
||||
task = AgentTask(
|
||||
role=advisor.name,
|
||||
prompt=f"Advise on the {pillar} pillar for this workload.",
|
||||
context={"pillar": pillar, "brief": brief},
|
||||
)
|
||||
try:
|
||||
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
|
||||
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
|
||||
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
|
||||
if isinstance(outcome, Submitted):
|
||||
return f"## {pillar}\n\n{outcome.content.strip()}"
|
||||
return (
|
||||
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
|
||||
)
|
||||
|
||||
|
||||
def _submit_advice_tool() -> ToolSpec:
|
||||
async def submit_advice(content: str) -> ToolResult:
|
||||
if not content.strip():
|
||||
return ToolResult("Not submitted: the advice is empty.")
|
||||
return ToolResult("Advice submitted.", Submitted(content))
|
||||
|
||||
return ToolSpec(
|
||||
"submit_advice",
|
||||
"Submit your pillar recommendations as markdown. Ends your turn.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"content": {"type": "string"}},
|
||||
"required": ["content"],
|
||||
},
|
||||
submit_advice,
|
||||
tier="execution",
|
||||
)
|
||||
48
app/tools/toolkit.py
Normal file
48
app/tools/toolkit.py
Normal file
@@ -0,0 +1,48 @@
|
||||
"""Which tools each role gets beyond the Execution tools.
|
||||
|
||||
A role gets the local tools its role file names, the tools of the remote MCP servers
|
||||
the provider bundle assigns it, and, for the design advisor, the pillar consultation.
|
||||
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
|
||||
from app.adk.roles import PILLAR_ADVISOR
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory, ToolSpec
|
||||
from app.tools.mcp import McpCatalog
|
||||
from app.tools.pillars import pillar_consultation_tool
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
|
||||
|
||||
def make_tool_factory(
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
pillar_skills: Mapping[str, str],
|
||||
*,
|
||||
local_tools: Sequence[ToolSpec] = (),
|
||||
catalog: McpCatalog | None = None,
|
||||
) -> ToolFactory:
|
||||
local_by_name = {tool.name: tool for tool in local_tools}
|
||||
|
||||
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
|
||||
return catalog.tools_for(role.mcp_servers) if catalog else []
|
||||
|
||||
consult = None
|
||||
advisor = roles.get(PILLAR_ADVISOR)
|
||||
if pillar_skills and advisor:
|
||||
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
||||
advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"]
|
||||
consult = pillar_consultation_tool(
|
||||
runtime, advisor, pillar_skills, extra_tools=advisor_tools
|
||||
)
|
||||
|
||||
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
|
||||
tools += mcp_tools(role)
|
||||
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
|
||||
tools.append(consult)
|
||||
return tools
|
||||
|
||||
return tools_for
|
||||
@@ -1,124 +0,0 @@
|
||||
"""LangChain decorated tools for artifact and schema validation."""
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
import re
|
||||
from typing import Dict, Any
|
||||
from langchain_core.tools import tool
|
||||
|
||||
|
||||
@tool
|
||||
def validate_mermaid_diagram(diagram_content: str) -> Dict[str, Any]:
|
||||
"""Validates the syntax and graph structure of a Mermaid diagram.
|
||||
|
||||
Args:
|
||||
diagram_content: Raw text content of the Mermaid diagram file.
|
||||
|
||||
Returns:
|
||||
Dict with status, valid boolean, and error details if any.
|
||||
"""
|
||||
if not diagram_content or not diagram_content.strip():
|
||||
return {"valid": False, "error": "Mermaid diagram is empty."}
|
||||
|
||||
if not re.search(r"\b(flowchart|graph)\b", diagram_content):
|
||||
return {
|
||||
"valid": False,
|
||||
"error": "Mermaid diagram must start with 'flowchart' or 'graph'.",
|
||||
}
|
||||
|
||||
# Basic bracket matching check
|
||||
open_brackets = diagram_content.count("[") + diagram_content.count("(") + diagram_content.count("{")
|
||||
close_brackets = diagram_content.count("]") + diagram_content.count(")") + diagram_content.count("}")
|
||||
if open_brackets != close_brackets:
|
||||
return {
|
||||
"valid": False,
|
||||
"error": "Mismatched brackets in Mermaid diagram syntax.",
|
||||
}
|
||||
|
||||
return {"valid": True, "message": "Mermaid diagram syntax is valid."}
|
||||
|
||||
|
||||
@tool
|
||||
def validate_terraform_syntax(terraform_content: str) -> Dict[str, Any]:
|
||||
"""Validates Terraform HCL basic structure and required Google Cloud blocks.
|
||||
|
||||
Args:
|
||||
terraform_content: Raw HCL text content of main.tf.
|
||||
|
||||
Returns:
|
||||
Dict with valid boolean and diagnostic information.
|
||||
"""
|
||||
if not terraform_content or not terraform_content.strip():
|
||||
return {"valid": False, "error": "Terraform configuration is empty."}
|
||||
|
||||
if "resource" not in terraform_content and "module" not in terraform_content:
|
||||
return {
|
||||
"valid": False,
|
||||
"error": "Terraform configuration must contain at least one resource or module block.",
|
||||
}
|
||||
|
||||
return {"valid": True, "message": "Terraform HCL structural check passed."}
|
||||
|
||||
|
||||
@tool
|
||||
def validate_repository_artifacts(target_dir: str) -> Dict[str, Any]:
|
||||
"""Executes full offline validation against solution architecture artifacts in a directory.
|
||||
|
||||
Args:
|
||||
target_dir: Directory path containing the solution architecture repository.
|
||||
|
||||
Returns:
|
||||
Dict containing validation pass status and missing items list.
|
||||
"""
|
||||
root = Path(target_dir)
|
||||
|
||||
def find_artifact(filename):
|
||||
search_dirs = [
|
||||
root / "deliverables" / "as-is",
|
||||
root / "deliverables" / "target",
|
||||
root / "deliverables" / "validation",
|
||||
root / "deliverables" / "guides",
|
||||
root / "deliverables",
|
||||
root / "docs",
|
||||
root,
|
||||
]
|
||||
for d in search_dirs:
|
||||
candidate = d / filename
|
||||
if candidate.is_file():
|
||||
return candidate
|
||||
return None
|
||||
|
||||
required_names = ["requirements.md", "architecture.md", "architecture.mmd", "solution-architecture-guide.md"]
|
||||
missing = []
|
||||
|
||||
for fname in required_names:
|
||||
if not find_artifact(fname):
|
||||
missing.append(fname)
|
||||
|
||||
if not (root / "terraform/main.tf").is_file():
|
||||
missing.append("terraform/main.tf")
|
||||
if not (root / "terraform/variables.tf").is_file():
|
||||
missing.append("terraform/variables.tf")
|
||||
|
||||
guide_path = find_artifact("solution-architecture-guide.md")
|
||||
if guide_path:
|
||||
guide_text = guide_path.read_text(encoding="utf-8")
|
||||
required_sections = ["Functional requirements", "Selected products", "Validation results", "Terraform", "Mermaid"]
|
||||
for section in required_sections:
|
||||
if section not in guide_text:
|
||||
missing.append(f"Guide section missing: {section}")
|
||||
else:
|
||||
missing.append("solution-architecture-guide.md missing")
|
||||
|
||||
mmd_path = find_artifact("architecture.mmd")
|
||||
if mmd_path:
|
||||
mmd_text = mmd_path.read_text(encoding="utf-8")
|
||||
if not re.search(r"flowchart|graph", mmd_text):
|
||||
missing.append("Invalid Mermaid graph directive in architecture.mmd")
|
||||
|
||||
passed = len(missing) == 0
|
||||
return {
|
||||
"valid": passed,
|
||||
"missing_items": missing,
|
||||
"message": "All required architecture artifacts valid." if passed else f"Validation failed for: {', '.join(missing)}",
|
||||
}
|
||||
Reference in New Issue
Block a user