This commit is contained in:
@@ -1 +0,0 @@
|
||||
"""A2A interface for interactive Executions (A2A 1.0, with v0.3 compatibility)."""
|
||||
@@ -1,66 +0,0 @@
|
||||
"""The A2A agent card, derived from the dependency graph and settings."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from a2a.types import (
|
||||
AgentCapabilities,
|
||||
AgentCard,
|
||||
AgentInterface,
|
||||
AgentProvider,
|
||||
AgentSkill,
|
||||
)
|
||||
|
||||
from app.config import Settings
|
||||
from app.execution.deliverables import PHASE_ORDER, deliverables_in
|
||||
|
||||
A2A_PATH = "/a2a"
|
||||
|
||||
|
||||
def build_agent_card(settings: Settings) -> AgentCard:
|
||||
base_url = (
|
||||
settings.A2A_PUBLIC_URL or f"http://{settings.A2A_HOST}:{settings.A2A_PORT}"
|
||||
).rstrip("/")
|
||||
phases = "; ".join(
|
||||
f"{phase.value}: {', '.join(kind.value for kind in deliverables_in(phase))}"
|
||||
for phase in PHASE_ORDER
|
||||
)
|
||||
return AgentCard(
|
||||
name=settings.AGENT_NAME,
|
||||
description=(
|
||||
"Designs a cloud solution architecture with you: requirements discovery, "
|
||||
"grounded product selection, diagram, design recommendations, "
|
||||
"infrastructure-as-code and dry-run validation, packaged as a solution "
|
||||
f"guide. Cloud provider: {settings.CLOUD_PROVIDER}."
|
||||
),
|
||||
version=settings.AGENT_VERSION,
|
||||
provider=AgentProvider(
|
||||
organization="Kyndryl Agent Builder", url="https://www.kyndryl.com"
|
||||
),
|
||||
supported_interfaces=[
|
||||
AgentInterface(
|
||||
url=f"{base_url}{A2A_PATH}",
|
||||
protocol_binding="JSONRPC",
|
||||
protocol_version="1.0",
|
||||
)
|
||||
],
|
||||
capabilities=AgentCapabilities(streaming=True, push_notifications=False),
|
||||
default_input_modes=["text/plain", "application/json"],
|
||||
default_output_modes=["text/plain", "text/markdown", "application/json"],
|
||||
skills=[
|
||||
AgentSkill(
|
||||
id="solution-architecture",
|
||||
name="Cloud solution architecture",
|
||||
description=(
|
||||
"Interactive, multi-turn engagement. Phases and their Deliverables: "
|
||||
f"{phases}. Each Phase needs your approval, sent as data."
|
||||
),
|
||||
tags=["architecture", "cloud", settings.CLOUD_PROVIDER, "terraform"],
|
||||
examples=[
|
||||
"Design a regional event ingestion platform on Google Cloud.",
|
||||
"Migrate our on-premises order service to managed services.",
|
||||
],
|
||||
input_modes=["text/plain", "application/json"],
|
||||
output_modes=["text/plain", "text/markdown", "application/json"],
|
||||
)
|
||||
],
|
||||
)
|
||||
@@ -23,10 +23,10 @@ from a2a.server.tasks import TaskUpdater
|
||||
from a2a.types import TaskState
|
||||
from google.protobuf import json_format
|
||||
|
||||
from app.execution.deliverables import DeliverableKind
|
||||
from app.execution.engine import ExecutionEngine, Interaction
|
||||
from app.execution.graph import GUIDE_FILENAME
|
||||
from app.execution.presentation import describe_prompt
|
||||
from app.agent import ExecutionEngine, Interaction
|
||||
from app.nodes.execution_nodes import GUIDE_FILENAME
|
||||
from app.presentation import describe_prompt
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -1,31 +1 @@
|
||||
"""ADK package for GCP Solution Architecture Agent."""
|
||||
|
||||
from .agents import (
|
||||
ArchitectureDesignAgent,
|
||||
DiscoveryAgent,
|
||||
OrchestratorLoopAgent,
|
||||
PackagingAgent,
|
||||
ValidationReviewAgent,
|
||||
build_adk_multi_agent_system,
|
||||
)
|
||||
from .artifacts import PostgresArtifactRepository
|
||||
from .evaluation import ADKEvaluator
|
||||
from .runners import ADKAgentRunner
|
||||
from .sessions import PostgresSessionService
|
||||
from .tools import ADK_TOOLS
|
||||
from .workflows import create_gcp_adk_workflow
|
||||
|
||||
__all__ = [
|
||||
"DiscoveryAgent",
|
||||
"ArchitectureDesignAgent",
|
||||
"ValidationReviewAgent",
|
||||
"PackagingAgent",
|
||||
"OrchestratorLoopAgent",
|
||||
"build_adk_multi_agent_system",
|
||||
"PostgresArtifactRepository",
|
||||
"PostgresSessionService",
|
||||
"ADKAgentRunner",
|
||||
"ADKEvaluator",
|
||||
"ADK_TOOLS",
|
||||
"create_gcp_adk_workflow",
|
||||
]
|
||||
"""Agent runtimes: the framework-neutral interface agents run behind, and its implementations."""
|
||||
|
||||
@@ -9,6 +9,7 @@ from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import uuid
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
@@ -17,6 +18,7 @@ from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from google.adk.agents import LlmAgent
|
||||
from google.adk.models.base_llm import BaseLlm
|
||||
from google.adk.runners import Runner
|
||||
@@ -28,7 +30,7 @@ from google.adk.tools.skill_toolset import SkillToolset
|
||||
from google.adk.tools.tool_context import ToolContext
|
||||
from google.genai import types
|
||||
|
||||
from app.agents.runtime import (
|
||||
from app.adk.runtime import (
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
@@ -41,19 +43,90 @@ APP_NAME = "solution-architect"
|
||||
# run_skill_script is deliberately absent: generated or bundled scripts never run.
|
||||
SKILL_TOOLS = ["list_skills", "load_skill", "load_skill_resource"]
|
||||
TURN_ENDED_REPLY = "Your turn has already ended; this call was not run."
|
||||
NUDGE = (
|
||||
"You stopped without calling a tool that ends your turn, so nothing was recorded. "
|
||||
"Continue the task, and finish by calling the tool your instructions name for "
|
||||
"ending your turn. If you need the user, use the tool for asking questions."
|
||||
)
|
||||
TIMED_OUT = (
|
||||
"Your last model request timed out, so its reply was lost. Continue the task, "
|
||||
"and finish by calling the tool your instructions name for ending your turn."
|
||||
)
|
||||
# Tool replies that mean the call did nothing, logged so stuck agents can be diagnosed.
|
||||
REJECTION_PREFIXES = (
|
||||
"Not submitted",
|
||||
"Refused",
|
||||
"Discovery gap",
|
||||
"terraform validate failed",
|
||||
)
|
||||
# Client-side timeouts from either HTTP stack google-genai may use (httpx or aiohttp,
|
||||
# whose timeout errors subclass TimeoutError).
|
||||
MODEL_TIMEOUTS = (TimeoutError, httpx.TimeoutException)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
ModelFactory = Callable[[RoleSpec], BaseLlm | str]
|
||||
|
||||
|
||||
def default_model_factory(role: RoleSpec) -> BaseLlm:
|
||||
"""Wrap the role's LiteLLM model id, so any LiteLLM provider can serve the agent."""
|
||||
from google.adk.models.lite_llm import LiteLlm
|
||||
GEMINI_PREFIX = "gemini/"
|
||||
|
||||
|
||||
def default_model_factory(role: RoleSpec) -> BaseLlm:
|
||||
"""Model for a role's LiteLLM-style id.
|
||||
|
||||
`gemini/<model>` uses ADK's native Gemini client, which targets Vertex AI when
|
||||
GOOGLE_GENAI_USE_VERTEXAI=true (with GOOGLE_CLOUD_PROJECT and
|
||||
GOOGLE_CLOUD_LOCATION) and the Gemini API otherwise. Any other id goes through
|
||||
LiteLLM, so other model providers need no code changes.
|
||||
"""
|
||||
if not role.model:
|
||||
raise ValueError(f"Role {role.name!r} has no model configured")
|
||||
if role.model.startswith(GEMINI_PREFIX):
|
||||
from google.adk.models.google_llm import Gemini
|
||||
|
||||
return Gemini(
|
||||
model=role.model.removeprefix(GEMINI_PREFIX),
|
||||
retry_options=types.HttpRetryOptions(attempts=5, initial_delay=2.0),
|
||||
)
|
||||
from google.adk.models.lite_llm import LiteLlm
|
||||
|
||||
return LiteLlm(model=role.model)
|
||||
|
||||
|
||||
USAGE_FIELDS = {
|
||||
"requests": None,
|
||||
"prompt": "prompt_token_count",
|
||||
"cached": "cached_content_token_count",
|
||||
"tool_prompt": "tool_use_prompt_token_count",
|
||||
"output": "candidates_token_count",
|
||||
"thinking": "thoughts_token_count",
|
||||
"total": "total_token_count",
|
||||
}
|
||||
|
||||
|
||||
@dataclass
|
||||
class TokenUsage:
|
||||
"""Model token counts, summed over every model response of one role and model."""
|
||||
|
||||
requests: int = 0
|
||||
prompt: int = 0
|
||||
cached: int = 0
|
||||
tool_prompt: int = 0
|
||||
output: int = 0
|
||||
thinking: int = 0
|
||||
total: int = 0
|
||||
|
||||
def add(self, metadata: Any) -> None:
|
||||
self.requests += 1
|
||||
for name, source in USAGE_FIELDS.items():
|
||||
if source:
|
||||
setattr(
|
||||
self,
|
||||
name,
|
||||
getattr(self, name) + (getattr(metadata, source, 0) or 0),
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class _RunControl:
|
||||
budget: int
|
||||
@@ -68,6 +141,9 @@ class _RunControl:
|
||||
if self.outcome is not None:
|
||||
return {"error": TURN_ENDED_REPLY}
|
||||
self.calls += 1
|
||||
logger.info(
|
||||
"%s tool call %d/%d: %s", self.role, self.calls, self.budget, tool.name
|
||||
)
|
||||
if self.calls > self.budget:
|
||||
self.outcome = BudgetExhausted(
|
||||
f"{self.role} used all {self.budget} tool calls before finishing."
|
||||
@@ -102,9 +178,17 @@ class _SpecTool(BaseTool):
|
||||
try:
|
||||
result = await self._spec.handler(**args)
|
||||
except TypeError as exc:
|
||||
logger.info("%s: invalid arguments: %s", self._spec.name, exc)
|
||||
return {"error": f"Invalid arguments for {self._spec.name}: {exc}"}
|
||||
if result.outcome is not None:
|
||||
self._control.outcome = result.outcome
|
||||
elif result.message.startswith(REJECTION_PREFIXES):
|
||||
logger.info(
|
||||
"%s rejected by %s: %s",
|
||||
self._control.role,
|
||||
self._spec.name,
|
||||
result.message[:500],
|
||||
)
|
||||
return {"result": result.message}
|
||||
|
||||
|
||||
@@ -114,7 +198,11 @@ class AdkAgentRuntime:
|
||||
*,
|
||||
skill_dirs: Mapping[str, Path],
|
||||
model_factory: ModelFactory = default_model_factory,
|
||||
max_nudges: int = 2,
|
||||
model_timeout_seconds: float | None = None,
|
||||
) -> None:
|
||||
self._max_nudges = max_nudges
|
||||
self._model_timeout_seconds = model_timeout_seconds
|
||||
self._skills: dict[str, Skill] = {}
|
||||
for name, path in skill_dirs.items():
|
||||
try:
|
||||
@@ -129,6 +217,8 @@ class AdkAgentRuntime:
|
||||
)
|
||||
self._skills[name] = skill
|
||||
self._model_factory = model_factory
|
||||
# (role, model) -> usage across every run of this runtime
|
||||
self.usage: dict[tuple[str, str], TokenUsage] = {}
|
||||
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
@@ -154,6 +244,7 @@ class AdkAgentRuntime:
|
||||
instruction=lambda _context: instructions,
|
||||
tools=agent_tools,
|
||||
before_tool_callback=control.before_tool,
|
||||
generate_content_config=self._content_config(),
|
||||
)
|
||||
runner = Runner(
|
||||
app_name=APP_NAME,
|
||||
@@ -161,36 +252,72 @@ class AdkAgentRuntime:
|
||||
session_service=InMemorySessionService(),
|
||||
auto_create_session=True,
|
||||
)
|
||||
message = types.Content(
|
||||
role="user", parts=[types.Part(text=_render_task(task))]
|
||||
)
|
||||
|
||||
session_id = str(uuid.uuid4())
|
||||
usage = self.usage.setdefault((role.name, role.model or "?"), TokenUsage())
|
||||
prompt = _render_task(task, role.skills)
|
||||
final_text = ""
|
||||
async with aclosing(
|
||||
runner.run_async(
|
||||
user_id=APP_NAME, session_id=str(uuid.uuid4()), new_message=message
|
||||
)
|
||||
) as events:
|
||||
async for event in events:
|
||||
for attempt in range(self._max_nudges + 1):
|
||||
if attempt:
|
||||
logger.info(
|
||||
"Nudging %s to end its turn (attempt %d)", role.name, attempt
|
||||
)
|
||||
message = types.Content(role="user", parts=[types.Part(text=prompt)])
|
||||
prompt = NUDGE
|
||||
try:
|
||||
async with aclosing(
|
||||
runner.run_async(
|
||||
user_id=APP_NAME, session_id=session_id, new_message=message
|
||||
)
|
||||
) as events:
|
||||
async for event in events:
|
||||
if event.usage_metadata is not None:
|
||||
usage.add(event.usage_metadata)
|
||||
if control.outcome is not None:
|
||||
break
|
||||
if (
|
||||
event.is_final_response()
|
||||
and event.content
|
||||
and event.content.parts
|
||||
):
|
||||
text = "".join(
|
||||
part.text for part in event.content.parts if part.text
|
||||
).strip()
|
||||
final_text = text or final_text # keep the last real reply
|
||||
except MODEL_TIMEOUTS as exc:
|
||||
if control.outcome is not None:
|
||||
break
|
||||
if event.is_final_response() and event.content and event.content.parts:
|
||||
final_text = "".join(
|
||||
part.text for part in event.content.parts if part.text
|
||||
).strip()
|
||||
return control.outcome
|
||||
logger.warning(
|
||||
"%s model request timed out (%s)", role.name, type(exc).__name__
|
||||
)
|
||||
final_text = final_text or f"{role.name}'s model requests timed out."
|
||||
prompt = TIMED_OUT
|
||||
if control.outcome is not None:
|
||||
return control.outcome
|
||||
|
||||
if control.outcome is not None:
|
||||
return control.outcome
|
||||
return Stopped(
|
||||
final_text
|
||||
or f"{role.name} ended without calling a tool that ends its turn."
|
||||
)
|
||||
|
||||
def _content_config(self) -> types.GenerateContentConfig | None:
|
||||
if self._model_timeout_seconds is None:
|
||||
return None
|
||||
return types.GenerateContentConfig(
|
||||
http_options=types.HttpOptions(
|
||||
timeout=int(self._model_timeout_seconds * 1000)
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def _agent_name(role: str) -> str:
|
||||
return re.sub(r"\W", "_", role)
|
||||
|
||||
|
||||
def _render_task(task: AgentTask) -> str:
|
||||
def _render_task(task: AgentTask, skills: Sequence[str] = ()) -> str:
|
||||
context = json.dumps(task.context, indent=2, default=str, ensure_ascii=False)
|
||||
return f"{task.prompt}\n\nContext:\n```json\n{context}\n```"
|
||||
skill_line = (
|
||||
f"\n\nSkills available to you (load with load_skill): {', '.join(skills)}."
|
||||
if skills
|
||||
else ""
|
||||
)
|
||||
return f"{task.prompt}{skill_line}\n\nContext:\n```json\n{context}\n```"
|
||||
@@ -1,196 +0,0 @@
|
||||
"""ADK Multi-Agent Architecture for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.agents primitives:
|
||||
- SourceDiscoveryAgent (LlmAgent)
|
||||
- DiscoveryAgent (LlmAgent)
|
||||
- ArchitectureDesignAgent (LlmAgent)
|
||||
- ValidationReviewAgent (LlmAgent)
|
||||
- PackagingAgent (LlmAgent)
|
||||
- OrchestratorLoopAgent (LoopAgent)
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from app.adk.compat import BaseAgent, LlmAgent, LoopAgent, SequentialAgent
|
||||
from app.adk.tools import ADK_TOOLS
|
||||
from app.config import get_settings
|
||||
from app.database import get_db_manager
|
||||
from app.nodes import design_node, discover_node, package_node, source_discover_node, validate_node
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class SourceDiscoveryAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 0a Pre-emptive Source Environment Discovery."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="SourceDiscoveryAgent",
|
||||
description="Audits and documents the pre-existing source environment (As-Is Architecture) before target migration.",
|
||||
instruction=skill_loader.format_skills_for_prompt("source_discover"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing SourceDiscoveryAgent")
|
||||
res = source_discover_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class DiscoveryAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 0 Requirements Discovery."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="DiscoveryAgent",
|
||||
description="Extracts functional and non-functional requirements with product selection deferred.",
|
||||
instruction=skill_loader.format_skills_for_prompt("discover"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing DiscoveryAgent")
|
||||
res = discover_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class ArchitectureDesignAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 1 Product Selection, Diagrams, & Terraform IaC."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="ArchitectureDesignAgent",
|
||||
description="Selects GCP products, generates Mermaid diagram, and produces Terraform IaC grounded by Developer Knowledge MCP.",
|
||||
instruction=skill_loader.format_skills_for_prompt("design"),
|
||||
tools=ADK_TOOLS,
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing ArchitectureDesignAgent")
|
||||
res = design_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class ValidationReviewAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 2 Artifact Review & Quality Validation."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="ValidationReviewAgent",
|
||||
description="Validates Mermaid syntax, Terraform configuration, and required sections.",
|
||||
instruction=skill_loader.format_skills_for_prompt("validate"),
|
||||
tools=ADK_TOOLS,
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing ValidationReviewAgent")
|
||||
res = validate_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class PackagingAgent(LlmAgent):
|
||||
"""ADK Agent responsible for Phase 3 Solution Guide Packaging."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader) -> None:
|
||||
super().__init__(
|
||||
name="PackagingAgent",
|
||||
description="Packages final solution-architecture-guide.md.",
|
||||
instruction=skill_loader.format_skills_for_prompt("package"),
|
||||
tools=[],
|
||||
)
|
||||
self.skill_loader = skill_loader
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
logger.info("Executing PackagingAgent")
|
||||
res = package_node(state, self.skill_loader)
|
||||
state_copy = dict(state)
|
||||
state_copy.update(res)
|
||||
return state_copy
|
||||
|
||||
|
||||
class OrchestratorLoopAgent(LoopAgent):
|
||||
"""ADK Orchestrator LoopAgent that coordinates multi-agent execution & iterative quality review.
|
||||
|
||||
Uses google.adk.agents.LoopAgent to execute discovery -> design -> validation review -> packaging
|
||||
in a loop until validation passes 100% or max_iterations is reached. Writes every review iteration
|
||||
event to PostgreSQL database (`orchestrator_review_logs`).
|
||||
"""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader, max_iterations: Optional[int] = None) -> None:
|
||||
settings = get_settings()
|
||||
max_iters = max_iterations or settings.ADK_MAX_LOOP_ITERATIONS
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
self.source_discovery_agent = SourceDiscoveryAgent(skill_loader)
|
||||
self.discovery_agent = DiscoveryAgent(skill_loader)
|
||||
self.design_agent = ArchitectureDesignAgent(skill_loader)
|
||||
self.validation_agent = ValidationReviewAgent(skill_loader)
|
||||
self.packaging_agent = PackagingAgent(skill_loader)
|
||||
|
||||
sub_pipeline = SequentialAgent(
|
||||
name="MultiAgentGCPPipeline",
|
||||
sub_agents=[
|
||||
self.source_discovery_agent,
|
||||
self.discovery_agent,
|
||||
self.design_agent,
|
||||
self.validation_agent,
|
||||
self.packaging_agent,
|
||||
],
|
||||
description="Sequential pipeline of GCP architecture multi-agents.",
|
||||
)
|
||||
|
||||
def review_validator(state: Dict[str, Any]) -> bool:
|
||||
"""Check if solution meets production quality validation standards."""
|
||||
is_valid = state.get("validation_passed", False)
|
||||
errors = state.get("errors", [])
|
||||
iteration = state.get("loop_count", 1)
|
||||
execution_id = state.get("execution_id", str(uuid.uuid4()))
|
||||
|
||||
status_str = "APPROVED" if is_valid else "NEEDS_REVISION"
|
||||
feedback_str = "All architecture validation rules passed." if is_valid else f"Validation errors: {', '.join(errors)}"
|
||||
|
||||
# Record review iteration in PostgreSQL database
|
||||
self.db_manager.record_orchestrator_log(
|
||||
log_id=str(uuid.uuid4()),
|
||||
execution_id=execution_id,
|
||||
iteration=iteration,
|
||||
review_status=status_str,
|
||||
reviewer_agent="ValidationReviewAgent",
|
||||
feedback=feedback_str,
|
||||
)
|
||||
logger.info(
|
||||
"Orchestrator Review Loop #%d: status=%s, valid=%s",
|
||||
iteration,
|
||||
status_str,
|
||||
is_valid,
|
||||
)
|
||||
|
||||
return is_valid
|
||||
|
||||
super().__init__(
|
||||
name="OrchestratorLoopAgent",
|
||||
sub_agent=sub_pipeline,
|
||||
max_iterations=max_iters,
|
||||
description="Production-ready multi-agent orchestrator loop agent.",
|
||||
validator_fn=review_validator,
|
||||
)
|
||||
|
||||
|
||||
def build_adk_multi_agent_system(skill_loader: SkillLoader, max_iterations: Optional[int] = None) -> OrchestratorLoopAgent:
|
||||
"""Factory function for building the complete ADK Orchestrator LoopAgent system."""
|
||||
return OrchestratorLoopAgent(skill_loader, max_iterations=max_iterations)
|
||||
@@ -1,77 +0,0 @@
|
||||
"""ADK Artifact Management for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.artifacts.ArtifactRepository backed by local filesystem and PostgreSQL persistence.
|
||||
"""
|
||||
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Any, Dict, Optional, List
|
||||
|
||||
from app.adk.compat import Artifact, ArtifactRepository
|
||||
from app.database import get_db_manager
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PostgresArtifactRepository(ArtifactRepository):
|
||||
"""ADK Artifact Repository with PostgreSQL database & filesystem synchronization."""
|
||||
|
||||
def __init__(self, base_dir: Optional[Path] = None) -> None:
|
||||
super().__init__()
|
||||
self.base_dir = base_dir or Path(".").resolve()
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def save_solution_artifacts(self, execution_id: str, state: Dict[str, Any]) -> List[Artifact]:
|
||||
"""Write workflow execution output artifacts to disk and PostgreSQL database."""
|
||||
saved_artifacts: List[Artifact] = []
|
||||
|
||||
artifact_mapping = [
|
||||
# Structured scalable active deliverables
|
||||
("source_discovery_doc", "deliverables/as-is/source-architecture.md", "markdown"),
|
||||
("source_mermaid_diagram", "deliverables/as-is/source-architecture.mmd", "mermaid"),
|
||||
("requirements_doc", "deliverables/target/requirements.md", "markdown"),
|
||||
("architecture_doc", "deliverables/target/architecture.md", "markdown"),
|
||||
("mermaid_diagram", "deliverables/target/architecture.mmd", "mermaid"),
|
||||
("terraform_code", "terraform/main.tf", "hcl"),
|
||||
("validation_results", "deliverables/validation/validation-results.md", "markdown"),
|
||||
("solution_guide", "deliverables/guides/solution-architecture-guide.md", "markdown"),
|
||||
|
||||
# Per-execution isolated deliverables for scalable history tracking
|
||||
("source_discovery_doc", f"deliverables/executions/{execution_id}/as-is/source-architecture.md", "markdown"),
|
||||
("source_mermaid_diagram", f"deliverables/executions/{execution_id}/as-is/source-architecture.mmd", "mermaid"),
|
||||
("requirements_doc", f"deliverables/executions/{execution_id}/target/requirements.md", "markdown"),
|
||||
("architecture_doc", f"deliverables/executions/{execution_id}/target/architecture.md", "markdown"),
|
||||
("mermaid_diagram", f"deliverables/executions/{execution_id}/target/architecture.mmd", "mermaid"),
|
||||
("validation_results", f"deliverables/executions/{execution_id}/validation/validation-results.md", "markdown"),
|
||||
("solution_guide", f"deliverables/executions/{execution_id}/guides/solution-architecture-guide.md", "markdown"),
|
||||
|
||||
# Mirror docs for specification compatibility
|
||||
("source_discovery_doc", "docs/source-architecture.md", "markdown"),
|
||||
("requirements_doc", "docs/requirements.md", "markdown"),
|
||||
("architecture_doc", "docs/architecture.md", "markdown"),
|
||||
]
|
||||
|
||||
for state_key, rel_path, art_type in artifact_mapping:
|
||||
content = state.get(state_key)
|
||||
if not content:
|
||||
continue
|
||||
|
||||
full_path = self.base_dir / rel_path
|
||||
full_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
full_path.write_text(content, encoding="utf-8")
|
||||
|
||||
# Save in ADK memory store
|
||||
art = self.save_artifact(art_type, str(rel_path), content)
|
||||
saved_artifacts.append(art)
|
||||
|
||||
# Persist to PostgreSQL database
|
||||
self.db_manager.save_artifact(
|
||||
artifact_id=art.artifact_id,
|
||||
execution_id=execution_id,
|
||||
artifact_type=art_type,
|
||||
file_path=str(rel_path),
|
||||
content=content,
|
||||
)
|
||||
logger.info("Persisted ADK artifact '%s' (%s) to DB and %s", art_type, art.artifact_id, rel_path)
|
||||
|
||||
return saved_artifacts
|
||||
@@ -1,288 +0,0 @@
|
||||
"""Google ADK (Agent Development Kit) Compatibility & Abstraction Layer.
|
||||
|
||||
Re-exports native `google.adk` framework components when available, or provides
|
||||
fully functional compatibility stubs matching ADK interfaces for:
|
||||
- google.adk.agents (Agent, LlmAgent, SequentialAgent, ParallelAgent, LoopAgent)
|
||||
- google.adk.workflows (Workflow, WorkflowStep)
|
||||
- google.adk.runners (Runner)
|
||||
- google.adk.sessions (Session, SessionService, InMemorySessionService, PostgresSessionService)
|
||||
- google.adk.artifacts (Artifact, ArtifactRepository)
|
||||
- google.adk.tools (Tool, FunctionTool)
|
||||
- google.adk.evaluation (Evaluator, BenchmarkRunner)
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Callable, Dict, List, Optional
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Attempt importing native google.adk modules
|
||||
HAS_NATIVE_ADK = False
|
||||
|
||||
try:
|
||||
import google.adk.agents as _native_agents
|
||||
import google.adk.workflows as _native_workflows
|
||||
import google.adk.runners as _native_runners
|
||||
import google.adk.sessions as _native_sessions
|
||||
import google.adk.artifacts as _native_artifacts
|
||||
import google.adk.tools as _native_tools
|
||||
import google.adk.evaluation as _native_evaluation
|
||||
|
||||
HAS_NATIVE_ADK = True
|
||||
logger.info("Successfully imported native google.adk framework modules.")
|
||||
except ImportError:
|
||||
HAS_NATIVE_ADK = False
|
||||
logger.info("Native google.adk not installed; using ADK framework compatibility layer.")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. google.adk.agents
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class BaseAgent:
|
||||
"""Base class for ADK Agents."""
|
||||
|
||||
def __init__(self, name: str, description: str = "", instruction: str = "", tools: Optional[List[Any]] = None) -> None:
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.instruction = instruction
|
||||
self.tools = tools or []
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Execute agent logic against state."""
|
||||
return state
|
||||
|
||||
|
||||
class LlmAgent(BaseAgent):
|
||||
"""ADK LLM Agent primitive."""
|
||||
|
||||
def __init__(self, name: str, description: str = "", instruction: str = "", model: Any = None, tools: Optional[List[Any]] = None) -> None:
|
||||
super().__init__(name, description, instruction, tools)
|
||||
self.model = model
|
||||
|
||||
|
||||
class SequentialAgent(BaseAgent):
|
||||
"""ADK Sequential Workflow Agent."""
|
||||
|
||||
def __init__(self, name: str, sub_agents: List[BaseAgent], description: str = "") -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agents = sub_agents
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
for agent in self.sub_agents:
|
||||
curr_state = agent.execute(curr_state)
|
||||
return curr_state
|
||||
|
||||
|
||||
class ParallelAgent(BaseAgent):
|
||||
"""ADK Parallel Workflow Agent."""
|
||||
|
||||
def __init__(self, name: str, sub_agents: List[BaseAgent], description: str = "") -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agents = sub_agents
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
for agent in self.sub_agents:
|
||||
res = agent.execute(curr_state)
|
||||
curr_state.update(res)
|
||||
return curr_state
|
||||
|
||||
|
||||
class LoopAgent(BaseAgent):
|
||||
"""ADK Loop Agent for iterative review and validation feedback cycles."""
|
||||
|
||||
def __init__(self, name: str, sub_agent: BaseAgent, max_iterations: int = 5, description: str = "", validator_fn: Optional[Callable[[Dict[str, Any]], bool]] = None) -> None:
|
||||
super().__init__(name, description)
|
||||
self.sub_agent = sub_agent
|
||||
self.max_iterations = max_iterations
|
||||
self.validator_fn = validator_fn
|
||||
|
||||
def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
curr_state = dict(state)
|
||||
loop_count = 0
|
||||
while loop_count < self.max_iterations:
|
||||
loop_count += 1
|
||||
curr_state["loop_count"] = loop_count
|
||||
curr_state = self.sub_agent.execute(curr_state)
|
||||
if self.validator_fn and self.validator_fn(curr_state):
|
||||
curr_state["loop_completed_successfully"] = True
|
||||
break
|
||||
curr_state["total_loop_iterations"] = loop_count
|
||||
return curr_state
|
||||
|
||||
|
||||
# Alias Agent to LlmAgent / BaseAgent
|
||||
Agent = LlmAgent
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. google.adk.tools
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Tool:
|
||||
"""ADK Tool Interface."""
|
||||
|
||||
def __init__(self, name: str, description: str, func: Callable) -> None:
|
||||
self.name = name
|
||||
self.description = description
|
||||
self.func = func
|
||||
|
||||
def run(self, *args, **kwargs) -> Any:
|
||||
return self.func(*args, **kwargs)
|
||||
|
||||
|
||||
class FunctionTool(Tool):
|
||||
"""ADK Function Tool primitive."""
|
||||
|
||||
@classmethod
|
||||
def from_defaults(cls, fn: Callable, name: Optional[str] = None, description: Optional[str] = None) -> "FunctionTool":
|
||||
tool_name = name or fn.__name__
|
||||
tool_desc = description or (fn.__doc__ or "")
|
||||
return cls(name=tool_name, description=tool_desc, func=fn)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. google.adk.artifacts
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Artifact:
|
||||
"""ADK Artifact container."""
|
||||
|
||||
def __init__(self, artifact_id: str, artifact_type: str, file_path: str, content: str) -> None:
|
||||
self.artifact_id = artifact_id
|
||||
self.artifact_type = artifact_type
|
||||
self.file_path = file_path
|
||||
self.content = content
|
||||
|
||||
|
||||
class ArtifactRepository:
|
||||
"""ADK Artifact Repository interface."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._store: Dict[str, Artifact] = {}
|
||||
|
||||
def save_artifact(self, artifact_type: str, file_path: str, content: str) -> Artifact:
|
||||
artifact_id = str(uuid.uuid4())
|
||||
art = Artifact(artifact_id, artifact_type, file_path, content)
|
||||
self._store[artifact_id] = art
|
||||
return art
|
||||
|
||||
def get_artifact(self, artifact_id: str) -> Optional[Artifact]:
|
||||
return self._store.get(artifact_id)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. google.adk.sessions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Session:
|
||||
"""ADK Session object."""
|
||||
|
||||
def __init__(self, session_id: str, agent_name: str, state: Optional[Dict[str, Any]] = None) -> None:
|
||||
self.session_id = session_id
|
||||
self.agent_name = agent_name
|
||||
self.state = state or {}
|
||||
|
||||
|
||||
class SessionService:
|
||||
"""ADK Session Service interface."""
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
return Session(sid, agent_name)
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
raise NotImplementedError
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
raise NotImplementedError
|
||||
|
||||
|
||||
class InMemorySessionService(SessionService):
|
||||
"""In-memory ADK Session Service."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._sessions: Dict[str, Session] = {}
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
sess = Session(sid, agent_name)
|
||||
self._sessions[sid] = sess
|
||||
return sess
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
return self._sessions.get(session_id)
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
self._sessions[session.session_id] = session
|
||||
return True
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. google.adk.runners
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Runner:
|
||||
"""ADK Runner for executing agents and workflows."""
|
||||
|
||||
def __init__(self, agent: BaseAgent, session_service: Optional[SessionService] = None) -> None:
|
||||
self.agent = agent
|
||||
self.session_service = session_service or InMemorySessionService()
|
||||
|
||||
def run(self, session_id: str, input_state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
session = self.session_service.get_session(session_id)
|
||||
if not session:
|
||||
session = self.session_service.create_session(self.agent.name, session_id)
|
||||
|
||||
merged_state = {**session.state, **input_state}
|
||||
result_state = self.agent.execute(merged_state)
|
||||
session.state = result_state
|
||||
self.session_service.save_session(session)
|
||||
return result_state
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. google.adk.workflows
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class WorkflowStep:
|
||||
"""ADK Workflow Step."""
|
||||
|
||||
def __init__(self, step_name: str, agent: BaseAgent) -> None:
|
||||
self.step_name = step_name
|
||||
self.agent = agent
|
||||
|
||||
|
||||
class Workflow:
|
||||
"""ADK Workflow composition container."""
|
||||
|
||||
def __init__(self, name: str, steps: List[WorkflowStep]) -> None:
|
||||
self.name = name
|
||||
self.steps = steps
|
||||
|
||||
def execute(self, initial_state: Dict[str, Any]) -> Dict[str, Any]:
|
||||
state = dict(initial_state)
|
||||
for step in self.steps:
|
||||
state = step.agent.execute(state)
|
||||
return state
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 7. google.adk.evaluation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
class Evaluator:
|
||||
"""ADK Benchmark Evaluator."""
|
||||
|
||||
def evaluate(self, agent: BaseAgent, test_case: Dict[str, Any]) -> Dict[str, Any]:
|
||||
initial_state = test_case.get("input_state", {})
|
||||
result = agent.execute(initial_state)
|
||||
return {
|
||||
"case_id": test_case.get("case_id", "default"),
|
||||
"result_state": result,
|
||||
"passed": True,
|
||||
"score": 1.0,
|
||||
}
|
||||
@@ -1,57 +0,0 @@
|
||||
"""ADK Evaluation module for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.evaluation.Evaluator with PostgreSQL database persistence.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from app.adk.compat import Evaluator
|
||||
from app.adk.runners import ADKAgentRunner
|
||||
from app.database import get_db_manager
|
||||
from eval.metrics import evaluate_case_run
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ADKEvaluator(Evaluator):
|
||||
"""ADK Evaluator persisting evaluation results to PostgreSQL."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
super().__init__()
|
||||
self.runner = ADKAgentRunner()
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def evaluate_benchmark_case(self, case: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Execute and score benchmark case via ADK runner and record to PostgreSQL."""
|
||||
eval_id = str(uuid.uuid4())
|
||||
case_id = case.get("id", "case-unknown")
|
||||
req_summary = case.get("workflow_request", "")
|
||||
|
||||
run_res = self.runner.run_execution(request_summary=req_summary)
|
||||
artifacts = run_res.get("artifacts", {})
|
||||
|
||||
state_for_metrics = {
|
||||
"requirements_doc": artifacts.get("requirements_doc", ""),
|
||||
"architecture_doc": artifacts.get("architecture_doc", ""),
|
||||
"mermaid_diagram": artifacts.get("mermaid_diagram", ""),
|
||||
"terraform_code": artifacts.get("terraform_code", ""),
|
||||
"solution_guide": artifacts.get("solution_guide", ""),
|
||||
}
|
||||
|
||||
eval_result = evaluate_case_run(state_for_metrics, case)
|
||||
|
||||
# Save evaluation to PostgreSQL database
|
||||
self.db_manager.save_evaluation(
|
||||
eval_id=eval_id,
|
||||
case_id=case_id,
|
||||
total_score=eval_result["total_score"],
|
||||
max_score=eval_result["max_score"],
|
||||
pass_rate=eval_result["percentage"],
|
||||
passed=eval_result["passed"],
|
||||
details=eval_result,
|
||||
)
|
||||
|
||||
logger.info("Recorded ADK evaluation %s for case %s (Score: %.1f%%)", eval_id, case_id, eval_result["percentage"])
|
||||
return eval_result
|
||||
@@ -12,7 +12,7 @@ from collections.abc import Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from app.agents.runtime import (
|
||||
from app.adk.runtime import (
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
@@ -9,10 +9,10 @@ from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
from app.agent_skills import SkillFormatError, split_frontmatter
|
||||
from app.agents.runtime import RoleSpec
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
from app.adk.runtime import RoleSpec
|
||||
from app.providers import ProviderBundle
|
||||
from app.skills.agent_skills import SkillFormatError, split_frontmatter
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
@@ -1,93 +0,0 @@
|
||||
"""ADK Execution Runner for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.runners.Runner integrated with PostgresSessionService,
|
||||
PostgresArtifactRepository, and PostgreSQL database state updates.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
from app.adk.agents import build_adk_multi_agent_system
|
||||
from app.adk.artifacts import PostgresArtifactRepository
|
||||
from app.adk.compat import Runner
|
||||
from app.adk.sessions import PostgresSessionService
|
||||
from app.config import get_settings
|
||||
from app.database import get_db_manager
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ADKAgentRunner:
|
||||
"""Production-ready ADK Execution Runner."""
|
||||
|
||||
def __init__(self, skill_loader: SkillLoader | None = None) -> None:
|
||||
settings = get_settings()
|
||||
self.skill_loader = skill_loader or SkillLoader(settings.SKILLS_DIR)
|
||||
self.skill_loader.load_skills()
|
||||
|
||||
self.session_service = PostgresSessionService()
|
||||
self.artifact_repo = PostgresArtifactRepository(settings.BASE_DIR)
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
self.orchestrator = build_adk_multi_agent_system(
|
||||
self.skill_loader,
|
||||
max_iterations=settings.ADK_MAX_LOOP_ITERATIONS,
|
||||
)
|
||||
self.runner = Runner(agent=self.orchestrator, session_service=self.session_service)
|
||||
|
||||
def run_execution(self, session_id: Optional[str] = None, request_summary: str = "", target_dir: str = ".") -> Dict[str, Any]:
|
||||
"""Execute multi-agent workflow using ADK runner with PostgreSQL state persistence."""
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
execution_id = str(uuid.uuid4())
|
||||
|
||||
initial_input = {
|
||||
"execution_id": execution_id,
|
||||
"workflow_request": request_summary or "Event-driven regional HTTP application reference architecture",
|
||||
"target_dir": target_dir,
|
||||
"active_skills": [],
|
||||
}
|
||||
|
||||
logger.info("Starting ADK runner execution %s for session %s", execution_id, sid)
|
||||
|
||||
# Run through ADK Runner
|
||||
result_state = self.runner.run(session_id=sid, input_state=initial_input)
|
||||
|
||||
# Save artifacts to disk & PostgreSQL database
|
||||
saved_artifacts = self.artifact_repo.save_solution_artifacts(execution_id, result_state)
|
||||
|
||||
# Record execution in PostgreSQL database
|
||||
self.db_manager.save_workflow_execution(
|
||||
execution_id=execution_id,
|
||||
session_id=sid,
|
||||
status="completed" if result_state.get("validation_passed") else "failed",
|
||||
current_phase=result_state.get("current_phase", "package"),
|
||||
loop_count=result_state.get("total_loop_iterations", 1),
|
||||
request_summary=request_summary,
|
||||
results={
|
||||
"validation_passed": result_state.get("validation_passed", False),
|
||||
"active_skills": result_state.get("active_skills", []),
|
||||
"artifacts_saved": len(saved_artifacts),
|
||||
},
|
||||
)
|
||||
|
||||
return {
|
||||
"execution_id": execution_id,
|
||||
"session_id": sid,
|
||||
"status": "success" if result_state.get("validation_passed") else "completed_with_warnings",
|
||||
"validation_passed": result_state.get("validation_passed", False),
|
||||
"total_loop_iterations": result_state.get("total_loop_iterations", 1),
|
||||
"current_phase": result_state.get("current_phase", "package"),
|
||||
"artifacts": {
|
||||
"source_discovery_doc": result_state.get("source_discovery_doc"),
|
||||
"source_mermaid_diagram": result_state.get("source_mermaid_diagram"),
|
||||
"requirements_doc": result_state.get("requirements_doc"),
|
||||
"architecture_doc": result_state.get("architecture_doc"),
|
||||
"mermaid_diagram": result_state.get("mermaid_diagram"),
|
||||
"terraform_code": result_state.get("terraform_code"),
|
||||
"validation_results": result_state.get("validation_results"),
|
||||
"solution_guide": result_state.get("solution_guide"),
|
||||
},
|
||||
"active_skills": result_state.get("active_skills", []),
|
||||
}
|
||||
@@ -86,6 +86,38 @@ class ToolResult:
|
||||
outcome: Outcome | None = None
|
||||
|
||||
|
||||
# Files cross tool calls as a list of {path, content}, never a map keyed by path:
|
||||
# models rewrite object keys (Gemini turns "main.tf" into "main_tf").
|
||||
FILES_SCHEMA: Mapping[str, Any] = {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "Relative path, e.g. terraform/main.tf",
|
||||
},
|
||||
"content": {"type": "string"},
|
||||
},
|
||||
"required": ["path", "content"],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def files_from_argument(value: Any) -> dict[str, str]:
|
||||
"""A FILES_SCHEMA argument as {path: content}. A {path: content} map is accepted too."""
|
||||
if not value:
|
||||
return {}
|
||||
if isinstance(value, Mapping):
|
||||
return {str(path): str(content) for path, content in value.items()}
|
||||
files: dict[str, str] = {}
|
||||
for item in value:
|
||||
if not isinstance(item, Mapping) or "path" not in item:
|
||||
raise TypeError("each file needs a 'path' and 'content'")
|
||||
files[str(item["path"])] = str(item.get("content", ""))
|
||||
return files
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ToolSpec:
|
||||
name: str
|
||||
@@ -95,6 +127,10 @@ class ToolSpec:
|
||||
tier: str = "general" # general | cloud_read | execution
|
||||
|
||||
|
||||
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing.
|
||||
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
|
||||
|
||||
|
||||
class AgentRuntime(Protocol):
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
@@ -1,56 +0,0 @@
|
||||
"""ADK Postgres Session Service for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.sessions.SessionService backed by external PostgreSQL database.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
from app.adk.compat import Session, SessionService
|
||||
from app.database import get_db_manager
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PostgresSessionService(SessionService):
|
||||
"""ADK Session Service persisting state to PostgreSQL."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.db_manager = get_db_manager()
|
||||
|
||||
def create_session(self, agent_name: str, session_id: Optional[str] = None) -> Session:
|
||||
"""Create a new session record in PostgreSQL database."""
|
||||
sid = session_id or str(uuid.uuid4())
|
||||
session = Session(session_id=sid, agent_name=agent_name, state={})
|
||||
self.db_manager.save_session(
|
||||
session_id=sid,
|
||||
agent_name=agent_name,
|
||||
state_data=session.state,
|
||||
metadata={"created_via": "PostgresSessionService"},
|
||||
)
|
||||
logger.info("Created ADK session %s in PostgreSQL database.", sid)
|
||||
return session
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Session]:
|
||||
"""Fetch session state from PostgreSQL database."""
|
||||
sess_data = self.db_manager.get_session(session_id)
|
||||
if not sess_data:
|
||||
return None
|
||||
|
||||
return Session(
|
||||
session_id=sess_data["session_id"],
|
||||
agent_name=sess_data["agent_name"],
|
||||
state=sess_data.get("state_data", {}),
|
||||
)
|
||||
|
||||
def save_session(self, session: Session) -> bool:
|
||||
"""Update session state in PostgreSQL database."""
|
||||
success = self.db_manager.save_session(
|
||||
session_id=session.session_id,
|
||||
agent_name=session.agent_name,
|
||||
state_data=session.state,
|
||||
)
|
||||
if success:
|
||||
logger.info("Updated ADK session %s in PostgreSQL database.", session.session_id)
|
||||
return success
|
||||
@@ -1,64 +0,0 @@
|
||||
"""ADK FunctionTool Wrappers for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.tools.FunctionTool primitives.
|
||||
"""
|
||||
|
||||
from typing import Any, Dict
|
||||
from app.adk.compat import FunctionTool
|
||||
from app.tools.mcp_developer_knowledge import (
|
||||
developerknowledge_answer_query as _mcp_answer,
|
||||
developerknowledge_get_documents as _mcp_get,
|
||||
developerknowledge_search_documents as _mcp_search,
|
||||
)
|
||||
from app.tools.validation_tools import (
|
||||
validate_mermaid_diagram as _validate_mermaid,
|
||||
validate_repository_artifacts as _validate_repo,
|
||||
validate_terraform_syntax as _validate_terraform,
|
||||
)
|
||||
|
||||
# Convert validation functions to ADK FunctionTools
|
||||
mermaid_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_mermaid.func if hasattr(_validate_mermaid, "func") else _validate_mermaid,
|
||||
name="validate_mermaid_diagram",
|
||||
description="Validates syntax and graph directives of a Mermaid diagram.",
|
||||
)
|
||||
|
||||
terraform_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_terraform.func if hasattr(_validate_terraform, "func") else _validate_terraform,
|
||||
name="validate_terraform_syntax",
|
||||
description="Validates Terraform HCL basic structure and required Google Cloud resources.",
|
||||
)
|
||||
|
||||
repo_artifacts_tool = FunctionTool.from_defaults(
|
||||
fn=_validate_repo.func if hasattr(_validate_repo, "func") else _validate_repo,
|
||||
name="validate_repository_artifacts",
|
||||
description="Validates offline file existence and required section headings across repository artifacts.",
|
||||
)
|
||||
|
||||
# Convert Developer Knowledge MCP tools to ADK FunctionTools
|
||||
mcp_search_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_search.func if hasattr(_mcp_search, "func") else _mcp_search,
|
||||
name="developerknowledge_search_documents",
|
||||
description="Searches Google Cloud reference architecture, decision-making, and best-practice documents.",
|
||||
)
|
||||
|
||||
mcp_get_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_get.func if hasattr(_mcp_get, "func") else _mcp_get,
|
||||
name="developerknowledge_get_documents",
|
||||
description="Retrieves official Google Cloud document content and citations by URI.",
|
||||
)
|
||||
|
||||
mcp_answer_tool = FunctionTool.from_defaults(
|
||||
fn=_mcp_answer.func if hasattr(_mcp_answer, "func") else _mcp_answer,
|
||||
name="developerknowledge_answer_query",
|
||||
description="Answers architectural questions and checks GCP product release statuses and best practices.",
|
||||
)
|
||||
|
||||
ADK_TOOLS = [
|
||||
mermaid_tool,
|
||||
terraform_tool,
|
||||
repo_artifacts_tool,
|
||||
mcp_search_tool,
|
||||
mcp_get_tool,
|
||||
mcp_answer_tool,
|
||||
]
|
||||
@@ -1,20 +0,0 @@
|
||||
"""ADK Workflows module for GCP Solution Architecture Agent.
|
||||
|
||||
Uses google.adk.workflows.Workflow and google.adk.workflows.WorkflowStep primitives.
|
||||
"""
|
||||
|
||||
from typing import Any, Dict, List
|
||||
from app.adk.agents import OrchestratorLoopAgent
|
||||
from app.adk.compat import Workflow, WorkflowStep
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
|
||||
def create_gcp_adk_workflow(skill_loader: SkillLoader, max_iterations: int = 5) -> Workflow:
|
||||
"""Compose the multi-agent ADK workflow."""
|
||||
orchestrator = OrchestratorLoopAgent(skill_loader, max_iterations=max_iterations)
|
||||
step = WorkflowStep(step_name="OrchestratorReviewLoopStep", agent=orchestrator)
|
||||
|
||||
return Workflow(
|
||||
name="GCP_Solution_Architecture_Workflow",
|
||||
steps=[step],
|
||||
)
|
||||
280
app/agent.py
280
app/agent.py
@@ -1,61 +1,243 @@
|
||||
"""gcp_solution_architecture_agent: Starlette application wiring & CLI entrypoint."""
|
||||
"""The agent: the ExecutionEngine that starts and resumes Executions, and its assembly.
|
||||
|
||||
ExecutionEngine is the one interface the A2A server, /generate and the evaluation
|
||||
harness use. Each call runs the Execution until it needs the user or finishes, and
|
||||
returns an Interaction describing which.
|
||||
|
||||
open_assembly is the composition root: the only place concrete runtimes, tools,
|
||||
checkpointers and recorders are chosen, from settings and the provider bundle.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from collections.abc import AsyncIterator, Mapping, Sequence
|
||||
from contextlib import asynccontextmanager
|
||||
import logging
|
||||
import click
|
||||
import uvicorn
|
||||
from starlette.applications import Starlette
|
||||
from starlette.routing import Route
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.config import get_settings
|
||||
from app.database import get_db_manager
|
||||
from app.workflows.routes import (
|
||||
get_card,
|
||||
get_session_route,
|
||||
health_check,
|
||||
run_workflow,
|
||||
validate_artifacts_route,
|
||||
)
|
||||
from langchain_core.runnables import RunnableConfig
|
||||
from langgraph.checkpoint.base import BaseCheckpointSaver
|
||||
from langgraph.types import Command
|
||||
|
||||
settings = get_settings()
|
||||
from app.adk.roles import load_roles
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory
|
||||
from app.checkpointing import open_checkpointer
|
||||
from app.config import Settings
|
||||
from app.providers import ProviderBundle, load_provider
|
||||
from app.recorder import DatabaseRecorder, ExecutionRecorder
|
||||
from app.states.ledger import Ledger
|
||||
from app.tools.execution import ORCHESTRATOR
|
||||
from app.tools.local import TerraformRunner, local_tools
|
||||
from app.tools.mcp import McpCatalog, auth_from_config
|
||||
from app.tools.toolkit import make_tool_factory
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH
|
||||
from app.workflows.execution_graph import build_execution_graph
|
||||
|
||||
logging.basicConfig(
|
||||
level=getattr(logging, settings.LOG_LEVEL.upper(), logging.INFO),
|
||||
format="%(asctime)s %(name)s %(levelname)s %(message)s",
|
||||
)
|
||||
logger = logging.getLogger(__name__)
|
||||
_RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Interaction:
|
||||
execution_id: str
|
||||
status: str # awaiting_user | completed | completed_with_warnings
|
||||
prompt: Mapping[str, Any] | None # questions | approval | permission
|
||||
state: Mapping[str, Any]
|
||||
|
||||
|
||||
class ExecutionNotAwaitingUser(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
class ExecutionEngine:
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
recorder: ExecutionRecorder,
|
||||
checkpointer: BaseCheckpointSaver,
|
||||
output_root: Path,
|
||||
max_revisions: int = 3,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
*(spec.specialist for spec in DEPENDENCY_GRAPH.values()),
|
||||
}
|
||||
missing = sorted(required - set(roles))
|
||||
if missing:
|
||||
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
||||
self._max_revisions = max_revisions
|
||||
self._graph = build_execution_graph(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder,
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
self,
|
||||
workflow_request: str,
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
pre_approved: bool = False,
|
||||
allow_cloud_read: bool | None = None,
|
||||
execution_id: str | None = None,
|
||||
scripted_answers: Sequence[tuple[str, str]] = (),
|
||||
) -> Interaction:
|
||||
"""Start an Execution. `scripted_answers` are (regex, answer) pairs a
|
||||
pre-approved Execution uses to answer questions, for evaluation runs."""
|
||||
execution_id = execution_id or str(uuid.uuid4())
|
||||
if await self._exists(execution_id):
|
||||
raise ValueError(f"Execution {execution_id} already exists")
|
||||
if pre_approved and allow_cloud_read is None:
|
||||
allow_cloud_read = False
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
"session_id": session_id or str(uuid.uuid4()),
|
||||
"workflow_request": workflow_request,
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
"ledger": Ledger(
|
||||
pre_approved=pre_approved, max_revisions=self._max_revisions
|
||||
).to_dict(),
|
||||
"deliverables": {},
|
||||
"conversation": [{"from": "user", "text": workflow_request}],
|
||||
"notes": [],
|
||||
"pending_questions": [],
|
||||
"awaiting_questions": [],
|
||||
"answers": {},
|
||||
"pending_permission": None,
|
||||
"prompt": None,
|
||||
"outcomes": [],
|
||||
"outcomes_applied": 0,
|
||||
"events_recorded": 0,
|
||||
"turns": 0,
|
||||
"status": "running",
|
||||
"warnings": [],
|
||||
"scripted_answers": [
|
||||
[pattern, answer] for pattern, answer in scripted_answers
|
||||
],
|
||||
}
|
||||
await self._graph.ainvoke(initial, self._config(execution_id))
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
async def resume(self, execution_id: str, reply: Mapping[str, Any]) -> Interaction:
|
||||
"""Answer the Execution's current prompt: {"reply"} | {"approval"} | {"permission"}."""
|
||||
current = await self.interaction(execution_id)
|
||||
if current.status != "awaiting_user":
|
||||
raise ExecutionNotAwaitingUser(
|
||||
f"Execution {execution_id} is {current.status}, not awaiting the user"
|
||||
)
|
||||
await self._graph.ainvoke(
|
||||
Command(resume=dict(reply)), self._config(execution_id)
|
||||
)
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
async def interaction(self, execution_id: str) -> Interaction:
|
||||
snapshot = await self._graph.aget_state(self._config(execution_id))
|
||||
if not snapshot.values:
|
||||
raise KeyError(f"Unknown Execution {execution_id}")
|
||||
if snapshot.interrupts:
|
||||
return Interaction(
|
||||
execution_id,
|
||||
"awaiting_user",
|
||||
snapshot.interrupts[0].value,
|
||||
snapshot.values,
|
||||
)
|
||||
return Interaction(
|
||||
execution_id,
|
||||
snapshot.values.get("status", "running"),
|
||||
None,
|
||||
snapshot.values,
|
||||
)
|
||||
|
||||
async def _exists(self, execution_id: str) -> bool:
|
||||
snapshot = await self._graph.aget_state(self._config(execution_id))
|
||||
return bool(snapshot.values)
|
||||
|
||||
@staticmethod
|
||||
def _config(execution_id: str) -> RunnableConfig:
|
||||
return {
|
||||
"configurable": {"thread_id": execution_id},
|
||||
"recursion_limit": _RECURSION_LIMIT,
|
||||
}
|
||||
|
||||
|
||||
# --- assembly ----------------------------------------------------------------------
|
||||
|
||||
AGENTS_DIR = Path(__file__).resolve().parent.parent / "agents"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Assembly:
|
||||
engine: ExecutionEngine
|
||||
bundle: ProviderBundle
|
||||
roles: dict[str, RoleSpec]
|
||||
mcp_gaps: dict[str, str]
|
||||
|
||||
routes = [
|
||||
Route("/health", health_check, methods=["GET"]),
|
||||
Route("/card", get_card, methods=["GET"]),
|
||||
Route("/generate", run_workflow, methods=["POST"]),
|
||||
Route("/validate", validate_artifacts_route, methods=["POST"]),
|
||||
Route("/sessions/{session_id}", get_session_route, methods=["GET"]),
|
||||
]
|
||||
|
||||
@asynccontextmanager
|
||||
async def lifespan(app: Starlette):
|
||||
"""Initialize PostgreSQL database schema on server startup."""
|
||||
logger.info("Initializing PostgreSQL database persistence...")
|
||||
get_db_manager()
|
||||
yield
|
||||
async def open_assembly(
|
||||
settings: Settings,
|
||||
*,
|
||||
runtime: AgentRuntime | None = None,
|
||||
recorder: ExecutionRecorder | None = None,
|
||||
output_root: Path | None = None,
|
||||
) -> AsyncIterator[Assembly]:
|
||||
bundle = load_provider(settings.CLOUD_PROVIDER)
|
||||
roles = load_roles(
|
||||
AGENTS_DIR,
|
||||
bundle,
|
||||
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
|
||||
specialist_budget=settings.SPECIALIST_BUDGET,
|
||||
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
|
||||
)
|
||||
if runtime is None:
|
||||
from app.adk.adk_runtime import AdkAgentRuntime
|
||||
|
||||
app = Starlette(
|
||||
debug=True,
|
||||
routes=routes,
|
||||
lifespan=lifespan,
|
||||
)
|
||||
runtime = AdkAgentRuntime(
|
||||
skill_dirs={name: meta.path for name, meta in bundle.skills.items()},
|
||||
model_timeout_seconds=settings.MODEL_TIMEOUT_SECONDS,
|
||||
)
|
||||
|
||||
catalog = McpCatalog()
|
||||
if settings.MCP_ENABLED:
|
||||
used = {server_id for role in roles.values() for server_id in role.mcp_servers}
|
||||
catalog = await McpCatalog.load(
|
||||
[bundle.mcp_servers[server_id] for server_id in sorted(used)],
|
||||
auth_from_config(bundle.mcp_auth, settings.MCP_QUOTA_PROJECT),
|
||||
timeout=settings.MCP_TIMEOUT_SECONDS,
|
||||
)
|
||||
|
||||
@click.command()
|
||||
@click.option("--host", default=settings.HOST, help="Host address to bind")
|
||||
@click.option("--port", default=settings.PORT, type=int, help="Port to listen on")
|
||||
def main(host: str, port: int) -> None:
|
||||
"""Start the GCP Solution Architecture Agent Starlette REST server."""
|
||||
logger.info("Starting GCP Solution Architecture Agent on %s:%d", host, port)
|
||||
uvicorn.run(app, host=host, port=port, log_level=settings.LOG_LEVEL.lower())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
runner = TerraformRunner(
|
||||
binary=settings.TERRAFORM_BINARY,
|
||||
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
|
||||
plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR,
|
||||
)
|
||||
offered = [name for names in bundle.tools.values() for name in names]
|
||||
tool_factory = make_tool_factory(
|
||||
runtime,
|
||||
roles,
|
||||
bundle.pillar_skills,
|
||||
local_tools=local_tools(offered, runner),
|
||||
catalog=catalog,
|
||||
)
|
||||
|
||||
async with open_checkpointer(settings) as checkpointer:
|
||||
engine = ExecutionEngine(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder or DatabaseRecorder(),
|
||||
checkpointer=checkpointer,
|
||||
output_root=output_root or settings.BASE_DIR,
|
||||
max_revisions=settings.MAX_REVISIONS,
|
||||
max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS,
|
||||
tool_factory=tool_factory,
|
||||
)
|
||||
yield Assembly(engine, bundle, roles, dict(catalog.gaps))
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
"""Agent runtimes: the framework-neutral interface agents run behind, and its implementations."""
|
||||
@@ -1,92 +0,0 @@
|
||||
"""Composition root: build the Execution engine from settings and the provider bundle.
|
||||
|
||||
The only place concrete runtimes, tools, checkpointers and recorders are chosen.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import AsyncIterator
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
|
||||
from app.agents.roles import load_roles
|
||||
from app.agents.runtime import AgentRuntime, RoleSpec
|
||||
from app.config import Settings
|
||||
from app.execution.checkpointing import open_checkpointer
|
||||
from app.execution.engine import ExecutionEngine
|
||||
from app.execution.recorder import DatabaseRecorder, ExecutionRecorder
|
||||
from app.execution.toolkit import make_tool_factory
|
||||
from app.providers import ProviderBundle, load_provider
|
||||
from app.tools.local import TerraformRunner, local_tools
|
||||
from app.tools.mcp import McpCatalog, auth_from_config
|
||||
|
||||
AGENTS_DIR = Path(__file__).resolve().parent.parent / "agents"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Assembly:
|
||||
engine: ExecutionEngine
|
||||
bundle: ProviderBundle
|
||||
roles: dict[str, RoleSpec]
|
||||
mcp_gaps: dict[str, str]
|
||||
|
||||
|
||||
@asynccontextmanager
|
||||
async def open_assembly(
|
||||
settings: Settings,
|
||||
*,
|
||||
runtime: AgentRuntime | None = None,
|
||||
recorder: ExecutionRecorder | None = None,
|
||||
output_root: Path | None = None,
|
||||
) -> AsyncIterator[Assembly]:
|
||||
bundle = load_provider(settings.CLOUD_PROVIDER)
|
||||
roles = load_roles(
|
||||
AGENTS_DIR,
|
||||
bundle,
|
||||
orchestrator_budget=settings.ORCHESTRATOR_BUDGET,
|
||||
specialist_budget=settings.SPECIALIST_BUDGET,
|
||||
include_preview_mcp=settings.MCP_ENABLE_PREVIEW,
|
||||
)
|
||||
if runtime is None:
|
||||
from app.agents.adk_runtime import AdkAgentRuntime
|
||||
|
||||
runtime = AdkAgentRuntime(
|
||||
skill_dirs={name: meta.path for name, meta in bundle.skills.items()}
|
||||
)
|
||||
|
||||
catalog = McpCatalog()
|
||||
if settings.MCP_ENABLED:
|
||||
used = {server_id for role in roles.values() for server_id in role.mcp_servers}
|
||||
catalog = await McpCatalog.load(
|
||||
[bundle.mcp_servers[server_id] for server_id in sorted(used)],
|
||||
auth_from_config(bundle.mcp_auth, settings.MCP_QUOTA_PROJECT),
|
||||
timeout=settings.MCP_TIMEOUT_SECONDS,
|
||||
)
|
||||
|
||||
runner = TerraformRunner(
|
||||
binary=settings.TERRAFORM_BINARY,
|
||||
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
|
||||
plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR,
|
||||
)
|
||||
offered = [name for names in bundle.tools.values() for name in names]
|
||||
tool_factory = make_tool_factory(
|
||||
runtime,
|
||||
roles,
|
||||
bundle.pillar_skills,
|
||||
local_tools=local_tools(offered, runner),
|
||||
catalog=catalog,
|
||||
)
|
||||
|
||||
async with open_checkpointer(settings) as checkpointer:
|
||||
engine = ExecutionEngine(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder or DatabaseRecorder(),
|
||||
checkpointer=checkpointer,
|
||||
output_root=output_root or settings.BASE_DIR,
|
||||
max_revisions=settings.MAX_REVISIONS,
|
||||
max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS,
|
||||
tool_factory=tool_factory,
|
||||
)
|
||||
yield Assembly(engine, bundle, roles, dict(catalog.gaps))
|
||||
98
app/card.py
98
app/card.py
@@ -1,40 +1,66 @@
|
||||
"""AgentCard + skill declarations for GCP Solution Architecture Agent."""
|
||||
"""The A2A agent card, derived from the dependency graph and settings."""
|
||||
|
||||
from typing import Any, Dict
|
||||
from __future__ import annotations
|
||||
|
||||
AGENT_CARD: Dict[str, Any] = {
|
||||
"name": "gcp_solution_architecture_agent",
|
||||
"version": "1.0.0",
|
||||
"description": (
|
||||
"Automated Google Cloud Solution Architecture Agent executing an end-to-end "
|
||||
"migration workflow: Pre-emptive Source Environment Discovery -> Requirements Discovery -> "
|
||||
"Product Selection & Architecture Design -> Pre-deployment Validation -> Guide Packaging."
|
||||
),
|
||||
"capabilities": {
|
||||
"phases": ["source_discover", "discover", "design", "validate", "package"],
|
||||
"streaming": False,
|
||||
"async": True,
|
||||
"local_skills": [
|
||||
"source_discovery",
|
||||
"requirements_discovery",
|
||||
"architecture_design",
|
||||
"validation_rules",
|
||||
"packaging_guide",
|
||||
from a2a.types import (
|
||||
AgentCapabilities,
|
||||
AgentCard,
|
||||
AgentInterface,
|
||||
AgentProvider,
|
||||
AgentSkill,
|
||||
)
|
||||
|
||||
from app.config import Settings
|
||||
from app.workflows.deliverables import PHASE_ORDER, deliverables_in
|
||||
|
||||
A2A_PATH = "/a2a"
|
||||
|
||||
|
||||
def build_agent_card(settings: Settings) -> AgentCard:
|
||||
base_url = (
|
||||
settings.A2A_PUBLIC_URL or f"http://{settings.A2A_HOST}:{settings.A2A_PORT}"
|
||||
).rstrip("/")
|
||||
phases = "; ".join(
|
||||
f"{phase.value}: {', '.join(kind.value for kind in deliverables_in(phase))}"
|
||||
for phase in PHASE_ORDER
|
||||
)
|
||||
return AgentCard(
|
||||
name=settings.AGENT_NAME,
|
||||
description=(
|
||||
"Designs a cloud solution architecture with you: requirements discovery, "
|
||||
"grounded product selection, diagram, design recommendations, "
|
||||
"infrastructure-as-code and dry-run validation, packaged as a solution "
|
||||
f"guide. Cloud provider: {settings.CLOUD_PROVIDER}."
|
||||
),
|
||||
version=settings.AGENT_VERSION,
|
||||
provider=AgentProvider(
|
||||
organization="Kyndryl Agent Builder", url="https://www.kyndryl.com"
|
||||
),
|
||||
supported_interfaces=[
|
||||
AgentInterface(
|
||||
url=f"{base_url}{A2A_PATH}",
|
||||
protocol_binding="JSONRPC",
|
||||
protocol_version="1.0",
|
||||
)
|
||||
],
|
||||
},
|
||||
"metadata": {
|
||||
"cloud_provider": "gcp",
|
||||
"supported_outputs": [
|
||||
"deliverables/as-is/source-architecture.md",
|
||||
"deliverables/as-is/source-architecture.mmd",
|
||||
"deliverables/target/requirements.md",
|
||||
"deliverables/target/architecture.md",
|
||||
"deliverables/target/architecture.mmd",
|
||||
"deliverables/validation/validation-results.md",
|
||||
"deliverables/guides/solution-architecture-guide.md",
|
||||
"deliverables/executions/{execution_id}/*",
|
||||
"terraform/main.tf",
|
||||
capabilities=AgentCapabilities(streaming=True, push_notifications=False),
|
||||
default_input_modes=["text/plain", "application/json"],
|
||||
default_output_modes=["text/plain", "text/markdown", "application/json"],
|
||||
skills=[
|
||||
AgentSkill(
|
||||
id="solution-architecture",
|
||||
name="Cloud solution architecture",
|
||||
description=(
|
||||
"Interactive, multi-turn engagement. Phases and their Deliverables: "
|
||||
f"{phases}. Each Phase needs your approval, sent as data."
|
||||
),
|
||||
tags=["architecture", "cloud", settings.CLOUD_PROVIDER, "terraform"],
|
||||
examples=[
|
||||
"Design a regional event ingestion platform on Google Cloud.",
|
||||
"Migrate our on-premises order service to managed services.",
|
||||
],
|
||||
input_modes=["text/plain", "application/json"],
|
||||
output_modes=["text/plain", "text/markdown", "application/json"],
|
||||
)
|
||||
],
|
||||
},
|
||||
}
|
||||
|
||||
)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
"""Typed settings for GCP Solution Architecture Agent."""
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||||
|
||||
|
||||
@@ -19,24 +19,7 @@ class Settings(BaseSettings):
|
||||
AGENT_VERSION: str = "1.0.0"
|
||||
LOG_LEVEL: str = "INFO"
|
||||
|
||||
# Server Configuration
|
||||
HOST: str = "0.0.0.0"
|
||||
PORT: int = 8080
|
||||
|
||||
# LLM Settings
|
||||
OPENAI_API_KEY: str | None = None
|
||||
AZURE_OPENAI_API_KEY: str | None = None
|
||||
AZURE_OPENAI_ENDPOINT: str | None = None
|
||||
AZURE_OPENAI_DEPLOYMENT: str = "gpt-4o"
|
||||
AZURE_OPENAI_API_VERSION: str = "2024-02-15-preview"
|
||||
LLM_TEMPERATURE: float = 0.2
|
||||
|
||||
# Google Cloud Environment & Scanner Credentials
|
||||
GOOGLE_APPLICATION_CREDENTIALS: str | None = None
|
||||
GCP_PROJECT_ID: str | None = None
|
||||
GCP_REGION: str = "us-central1"
|
||||
|
||||
# Database & Storage Settings (External PostgreSQL)
|
||||
# Database & Storage Settings (External PostgreSQL, SQLite fallback)
|
||||
POSTGRES_HOST: str = "localhost"
|
||||
POSTGRES_PORT: int = 5432
|
||||
POSTGRES_DB: str = "gcp_agent_db"
|
||||
@@ -45,10 +28,6 @@ class Settings(BaseSettings):
|
||||
DATABASE_URL: str | None = None
|
||||
SQLITE_FALLBACK_DB: str = "gcp_agent_local.db"
|
||||
|
||||
# ADK Multi-Agent Orchestrator Settings
|
||||
ADK_MAX_LOOP_ITERATIONS: int = 5
|
||||
ADK_ENABLE_ARTIFACT_STORE: bool = True
|
||||
|
||||
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
|
||||
CLOUD_PROVIDER: str = "gcp"
|
||||
MCP_ENABLED: bool = True
|
||||
@@ -61,6 +40,9 @@ class Settings(BaseSettings):
|
||||
TERRAFORM_TIMEOUT_SECONDS: float = 300
|
||||
TF_PLUGIN_CACHE_DIR: str | None = None
|
||||
|
||||
# Models: a request with no response in this time is abandoned and retried
|
||||
MODEL_TIMEOUT_SECONDS: float = 180
|
||||
|
||||
# Hierarchical Execution Engine (LangGraph state, ReAct agents)
|
||||
A2A_HOST: str = "0.0.0.0"
|
||||
A2A_PORT: int = 8000
|
||||
@@ -72,14 +54,8 @@ class Settings(BaseSettings):
|
||||
CHECKPOINTER: str = "sqlite" # memory | sqlite | postgres
|
||||
CHECKPOINT_DB_PATH: str = "checkpoints.db"
|
||||
|
||||
# Google Developer Knowledge MCP Server Settings
|
||||
DEVELOPER_KNOWLEDGE_MCP_URL: str = "https://developerknowledge.googleapis.com/mcp"
|
||||
DEVELOPER_KNOWLEDGE_MCP_ENABLED: bool = True
|
||||
|
||||
# Paths
|
||||
BASE_DIR: Path = Path(__file__).resolve().parent.parent
|
||||
SKILLS_DIR: Path = Path(__file__).resolve().parent / "skills"
|
||||
EVAL_DATASET_PATH: Path = Path(__file__).resolve().parent.parent / "eval" / "datasets" / "benchmark_cases.json"
|
||||
|
||||
def get_database_url(self) -> str:
|
||||
"""Construct database connection URL (PostgreSQL or SQLite fallback)."""
|
||||
@@ -97,4 +73,3 @@ def get_settings() -> Settings:
|
||||
if _settings is None:
|
||||
_settings = Settings()
|
||||
return _settings
|
||||
|
||||
|
||||
194
app/database.py
194
app/database.py
@@ -9,11 +9,11 @@ import json
|
||||
import logging
|
||||
import sqlite3
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any, Dict, List, Optional
|
||||
from typing import Any
|
||||
|
||||
try:
|
||||
import psycopg2
|
||||
from psycopg2.extras import RealDictCursor
|
||||
|
||||
HAS_PSYCOPG2 = True
|
||||
except ImportError:
|
||||
HAS_PSYCOPG2 = False
|
||||
@@ -26,10 +26,12 @@ logger = logging.getLogger(__name__)
|
||||
class DatabaseManager:
|
||||
"""Handles persistence of sessions, execution runs, artifacts, and review logs."""
|
||||
|
||||
def __init__(self, db_url: Optional[str] = None) -> None:
|
||||
def __init__(self, db_url: str | None = None) -> None:
|
||||
self.settings = get_settings()
|
||||
self.db_url = db_url or self.settings.get_database_url()
|
||||
self.is_postgres = self.db_url.startswith("postgresql://") or self.db_url.startswith("postgres://")
|
||||
self.is_postgres = self.db_url.startswith(
|
||||
"postgresql://"
|
||||
) or self.db_url.startswith("postgres://")
|
||||
self._init_db()
|
||||
|
||||
def _get_connection(self):
|
||||
@@ -38,7 +40,7 @@ class DatabaseManager:
|
||||
try:
|
||||
conn = psycopg2.connect(self.db_url, connect_timeout=3)
|
||||
return conn
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - any connection failure falls back to SQLite
|
||||
logger.warning(
|
||||
"PostgreSQL connection to %s failed (%s); falling back to local SQLite database %s",
|
||||
self.db_url,
|
||||
@@ -56,7 +58,7 @@ class DatabaseManager:
|
||||
conn = self._get_connection()
|
||||
try:
|
||||
cursor = conn.cursor()
|
||||
|
||||
|
||||
# 1. Sessions Table
|
||||
cursor.execute("""
|
||||
CREATE TABLE IF NOT EXISTS adk_sessions (
|
||||
@@ -125,12 +127,18 @@ class DatabaseManager:
|
||||
|
||||
conn.commit()
|
||||
logger.info("Database schema initialized successfully.")
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Failed to initialize database schema: %s", exc)
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def save_session(self, session_id: str, agent_name: str, state_data: Dict[str, Any], metadata: Optional[Dict[str, Any]] = None) -> bool:
|
||||
def save_session(
|
||||
self,
|
||||
session_id: str,
|
||||
agent_name: str,
|
||||
state_data: dict[str, Any],
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> bool:
|
||||
"""Persist or update ADK session state in PostgreSQL."""
|
||||
conn = self._get_connection()
|
||||
now = datetime.now(timezone.utc).isoformat()
|
||||
@@ -140,41 +148,51 @@ class DatabaseManager:
|
||||
meta_json = json.dumps(metadata or {})
|
||||
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_sessions (session_id, agent_name, created_at, updated_at, state_data, metadata)
|
||||
VALUES (?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(session_id) DO UPDATE SET
|
||||
updated_at = excluded.updated_at,
|
||||
state_data = excluded.state_data,
|
||||
metadata = excluded.metadata
|
||||
""", (session_id, agent_name, now, now, state_json, meta_json))
|
||||
""",
|
||||
(session_id, agent_name, now, now, state_json, meta_json),
|
||||
)
|
||||
else:
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_sessions (session_id, agent_name, created_at, updated_at, state_data, metadata)
|
||||
VALUES (%s, %s, %s, %s, %s, %s)
|
||||
ON CONFLICT(session_id) DO UPDATE SET
|
||||
updated_at = EXCLUDED.updated_at,
|
||||
state_data = EXCLUDED.state_data,
|
||||
metadata = EXCLUDED.metadata
|
||||
""", (session_id, agent_name, now, now, state_json, meta_json))
|
||||
""",
|
||||
(session_id, agent_name, now, now, state_json, meta_json),
|
||||
)
|
||||
|
||||
conn.commit()
|
||||
return True
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error saving session %s: %s", session_id, exc)
|
||||
return False
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
|
||||
def get_session(self, session_id: str) -> dict[str, Any] | None:
|
||||
"""Retrieve ADK session state by session_id."""
|
||||
conn = self._get_connection()
|
||||
try:
|
||||
cursor = conn.cursor()
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("SELECT * FROM adk_sessions WHERE session_id = ?", (session_id,))
|
||||
cursor.execute(
|
||||
"SELECT * FROM adk_sessions WHERE session_id = ?", (session_id,)
|
||||
)
|
||||
else:
|
||||
cursor.execute("SELECT * FROM adk_sessions WHERE session_id = %s", (session_id,))
|
||||
cursor.execute(
|
||||
"SELECT * FROM adk_sessions WHERE session_id = %s", (session_id,)
|
||||
)
|
||||
|
||||
row = cursor.fetchone()
|
||||
if not row:
|
||||
@@ -197,7 +215,7 @@ class DatabaseManager:
|
||||
"state_data": json.loads(row[4]),
|
||||
"metadata": json.loads(row[5] or "{}"),
|
||||
}
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error reading session %s: %s", session_id, exc)
|
||||
return None
|
||||
finally:
|
||||
@@ -211,7 +229,7 @@ class DatabaseManager:
|
||||
current_phase: str,
|
||||
loop_count: int,
|
||||
request_summary: str,
|
||||
results: Dict[str, Any],
|
||||
results: dict[str, Any],
|
||||
) -> bool:
|
||||
"""Save workflow execution record to database."""
|
||||
conn = self._get_connection()
|
||||
@@ -221,7 +239,8 @@ class DatabaseManager:
|
||||
results_json = json.dumps(results)
|
||||
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO workflow_executions
|
||||
(execution_id, session_id, status, current_phase, loop_count, started_at, completed_at, request_summary, results_json)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
@@ -231,9 +250,22 @@ class DatabaseManager:
|
||||
loop_count = excluded.loop_count,
|
||||
completed_at = excluded.completed_at,
|
||||
results_json = excluded.results_json
|
||||
""", (execution_id, session_id, status, current_phase, loop_count, now, now, request_summary, results_json))
|
||||
""",
|
||||
(
|
||||
execution_id,
|
||||
session_id,
|
||||
status,
|
||||
current_phase,
|
||||
loop_count,
|
||||
now,
|
||||
now,
|
||||
request_summary,
|
||||
results_json,
|
||||
),
|
||||
)
|
||||
else:
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO workflow_executions
|
||||
(execution_id, session_id, status, current_phase, loop_count, started_at, completed_at, request_summary, results_json)
|
||||
VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)
|
||||
@@ -243,42 +275,67 @@ class DatabaseManager:
|
||||
loop_count = EXCLUDED.loop_count,
|
||||
completed_at = EXCLUDED.completed_at,
|
||||
results_json = EXCLUDED.results_json
|
||||
""", (execution_id, session_id, status, current_phase, loop_count, now, now, request_summary, results_json))
|
||||
""",
|
||||
(
|
||||
execution_id,
|
||||
session_id,
|
||||
status,
|
||||
current_phase,
|
||||
loop_count,
|
||||
now,
|
||||
now,
|
||||
request_summary,
|
||||
results_json,
|
||||
),
|
||||
)
|
||||
|
||||
conn.commit()
|
||||
return True
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error saving workflow execution %s: %s", execution_id, exc)
|
||||
return False
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def save_artifact(self, artifact_id: str, execution_id: str, artifact_type: str, file_path: str, content: str) -> bool:
|
||||
def save_artifact(
|
||||
self,
|
||||
artifact_id: str,
|
||||
execution_id: str,
|
||||
artifact_type: str,
|
||||
file_path: str,
|
||||
content: str,
|
||||
) -> bool:
|
||||
"""Write ADK artifact metadata & content to database."""
|
||||
conn = self._get_connection()
|
||||
now = datetime.now(timezone.utc).isoformat()
|
||||
try:
|
||||
cursor = conn.cursor()
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_artifacts (artifact_id, execution_id, artifact_type, file_path, content, created_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?)
|
||||
ON CONFLICT(artifact_id) DO UPDATE SET
|
||||
content = excluded.content,
|
||||
file_path = excluded.file_path
|
||||
""", (artifact_id, execution_id, artifact_type, file_path, content, now))
|
||||
""",
|
||||
(artifact_id, execution_id, artifact_type, file_path, content, now),
|
||||
)
|
||||
else:
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_artifacts (artifact_id, execution_id, artifact_type, file_path, content, created_at)
|
||||
VALUES (%s, %s, %s, %s, %s, %s)
|
||||
ON CONFLICT(artifact_id) DO UPDATE SET
|
||||
content = EXCLUDED.content,
|
||||
file_path = EXCLUDED.file_path
|
||||
""", (artifact_id, execution_id, artifact_type, file_path, content, now))
|
||||
""",
|
||||
(artifact_id, execution_id, artifact_type, file_path, content, now),
|
||||
)
|
||||
|
||||
conn.commit()
|
||||
return True
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error saving artifact %s: %s", artifact_id, exc)
|
||||
return False
|
||||
finally:
|
||||
@@ -299,25 +356,56 @@ class DatabaseManager:
|
||||
try:
|
||||
cursor = conn.cursor()
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO orchestrator_review_logs (log_id, execution_id, iteration, review_status, reviewer_agent, feedback, created_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?)
|
||||
""", (log_id, execution_id, iteration, review_status, reviewer_agent, feedback, now))
|
||||
""",
|
||||
(
|
||||
log_id,
|
||||
execution_id,
|
||||
iteration,
|
||||
review_status,
|
||||
reviewer_agent,
|
||||
feedback,
|
||||
now,
|
||||
),
|
||||
)
|
||||
else:
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO orchestrator_review_logs (log_id, execution_id, iteration, review_status, reviewer_agent, feedback, created_at)
|
||||
VALUES (%s, %s, %s, %s, %s, %s, %s)
|
||||
""", (log_id, execution_id, iteration, review_status, reviewer_agent, feedback, now))
|
||||
""",
|
||||
(
|
||||
log_id,
|
||||
execution_id,
|
||||
iteration,
|
||||
review_status,
|
||||
reviewer_agent,
|
||||
feedback,
|
||||
now,
|
||||
),
|
||||
)
|
||||
|
||||
conn.commit()
|
||||
return True
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error recording orchestrator review log %s: %s", log_id, exc)
|
||||
return False
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
def save_evaluation(self, eval_id: str, case_id: str, total_score: float, max_score: float, pass_rate: float, passed: bool, details: Dict[str, Any]) -> bool:
|
||||
def save_evaluation(
|
||||
self,
|
||||
eval_id: str,
|
||||
case_id: str,
|
||||
total_score: float,
|
||||
max_score: float,
|
||||
pass_rate: float,
|
||||
passed: bool,
|
||||
details: dict[str, Any],
|
||||
) -> bool:
|
||||
"""Save ADK evaluation benchmark result to database."""
|
||||
conn = self._get_connection()
|
||||
now = datetime.now(timezone.utc).isoformat()
|
||||
@@ -325,26 +413,50 @@ class DatabaseManager:
|
||||
cursor = conn.cursor()
|
||||
details_json = json.dumps(details)
|
||||
if isinstance(conn, sqlite3.Connection):
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_evaluations (eval_id, case_id, total_score, max_score, pass_rate, passed, details_json, evaluated_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
||||
""", (eval_id, case_id, total_score, max_score, pass_rate, passed, details_json, now))
|
||||
""",
|
||||
(
|
||||
eval_id,
|
||||
case_id,
|
||||
total_score,
|
||||
max_score,
|
||||
pass_rate,
|
||||
passed,
|
||||
details_json,
|
||||
now,
|
||||
),
|
||||
)
|
||||
else:
|
||||
cursor.execute("""
|
||||
cursor.execute(
|
||||
"""
|
||||
INSERT INTO adk_evaluations (eval_id, case_id, total_score, max_score, pass_rate, passed, details_json, evaluated_at)
|
||||
VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
|
||||
""", (eval_id, case_id, total_score, max_score, pass_rate, passed, details_json, now))
|
||||
""",
|
||||
(
|
||||
eval_id,
|
||||
case_id,
|
||||
total_score,
|
||||
max_score,
|
||||
pass_rate,
|
||||
passed,
|
||||
details_json,
|
||||
now,
|
||||
),
|
||||
)
|
||||
|
||||
conn.commit()
|
||||
return True
|
||||
except Exception as exc:
|
||||
except Exception as exc: # noqa: BLE001 - persistence is best-effort; the failure is logged
|
||||
logger.error("Error saving evaluation %s: %s", eval_id, exc)
|
||||
return False
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
_db_manager: Optional[DatabaseManager] = None
|
||||
_db_manager: DatabaseManager | None = None
|
||||
|
||||
|
||||
def get_db_manager() -> DatabaseManager:
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
"""Execution of the solution-architecture workflow: Deliverables, the Ledger and the graph."""
|
||||
@@ -1,152 +0,0 @@
|
||||
"""ExecutionEngine: start and resume Executions.
|
||||
|
||||
The one interface the A2A server, /generate and the evaluation harness use. Each
|
||||
call runs the Execution until it needs the user or finishes, and returns an
|
||||
Interaction describing which.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from langchain_core.runnables import RunnableConfig
|
||||
from langgraph.checkpoint.base import BaseCheckpointSaver
|
||||
from langgraph.types import Command
|
||||
|
||||
from app.agents.runtime import AgentRuntime, RoleSpec
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH
|
||||
from app.execution.graph import ToolFactory, build_execution_graph
|
||||
from app.execution.ledger import Ledger
|
||||
from app.execution.recorder import ExecutionRecorder
|
||||
from app.execution.tools import ORCHESTRATOR
|
||||
|
||||
_RECURSION_LIMIT = 10_000 # loops are bounded by max_orchestrator_turns instead
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Interaction:
|
||||
execution_id: str
|
||||
status: str # awaiting_user | completed | completed_with_warnings
|
||||
prompt: Mapping[str, Any] | None # questions | approval | permission
|
||||
state: Mapping[str, Any]
|
||||
|
||||
|
||||
class ExecutionNotAwaitingUser(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
class ExecutionEngine:
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
recorder: ExecutionRecorder,
|
||||
checkpointer: BaseCheckpointSaver,
|
||||
output_root: Path,
|
||||
max_revisions: int = 3,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
*(spec.specialist for spec in DEPENDENCY_GRAPH.values()),
|
||||
}
|
||||
missing = sorted(required - set(roles))
|
||||
if missing:
|
||||
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
||||
self._max_revisions = max_revisions
|
||||
self._graph = build_execution_graph(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder,
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
self,
|
||||
workflow_request: str,
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
pre_approved: bool = False,
|
||||
allow_cloud_read: bool | None = None,
|
||||
execution_id: str | None = None,
|
||||
) -> Interaction:
|
||||
execution_id = execution_id or str(uuid.uuid4())
|
||||
if await self._exists(execution_id):
|
||||
raise ValueError(f"Execution {execution_id} already exists")
|
||||
if pre_approved and allow_cloud_read is None:
|
||||
allow_cloud_read = False
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
"session_id": session_id or str(uuid.uuid4()),
|
||||
"workflow_request": workflow_request,
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
"ledger": Ledger(
|
||||
pre_approved=pre_approved, max_revisions=self._max_revisions
|
||||
).to_dict(),
|
||||
"deliverables": {},
|
||||
"conversation": [{"from": "user", "text": workflow_request}],
|
||||
"notes": [],
|
||||
"pending_questions": [],
|
||||
"awaiting_questions": [],
|
||||
"answers": {},
|
||||
"pending_permission": None,
|
||||
"prompt": None,
|
||||
"outcomes": [],
|
||||
"outcomes_applied": 0,
|
||||
"events_recorded": 0,
|
||||
"turns": 0,
|
||||
"status": "running",
|
||||
"warnings": [],
|
||||
}
|
||||
await self._graph.ainvoke(initial, self._config(execution_id))
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
async def resume(self, execution_id: str, reply: Mapping[str, Any]) -> Interaction:
|
||||
"""Answer the Execution's current prompt: {"reply"} | {"approval"} | {"permission"}."""
|
||||
current = await self.interaction(execution_id)
|
||||
if current.status != "awaiting_user":
|
||||
raise ExecutionNotAwaitingUser(
|
||||
f"Execution {execution_id} is {current.status}, not awaiting the user"
|
||||
)
|
||||
await self._graph.ainvoke(
|
||||
Command(resume=dict(reply)), self._config(execution_id)
|
||||
)
|
||||
return await self.interaction(execution_id)
|
||||
|
||||
async def interaction(self, execution_id: str) -> Interaction:
|
||||
snapshot = await self._graph.aget_state(self._config(execution_id))
|
||||
if not snapshot.values:
|
||||
raise KeyError(f"Unknown Execution {execution_id}")
|
||||
if snapshot.interrupts:
|
||||
return Interaction(
|
||||
execution_id,
|
||||
"awaiting_user",
|
||||
snapshot.interrupts[0].value,
|
||||
snapshot.values,
|
||||
)
|
||||
return Interaction(
|
||||
execution_id,
|
||||
snapshot.values.get("status", "running"),
|
||||
None,
|
||||
snapshot.values,
|
||||
)
|
||||
|
||||
async def _exists(self, execution_id: str) -> bool:
|
||||
snapshot = await self._graph.aget_state(self._config(execution_id))
|
||||
return bool(snapshot.values)
|
||||
|
||||
@staticmethod
|
||||
def _config(execution_id: str) -> RunnableConfig:
|
||||
return {
|
||||
"configurable": {"thread_id": execution_id},
|
||||
"recursion_limit": _RECURSION_LIMIT,
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
"""The A2A server: JSON-RPC at /a2a, the agent card, health, and pre-approved /generate.
|
||||
|
||||
Run with: python -m app.a2a.server
|
||||
Run with: python -m app.main
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -23,11 +23,11 @@ from starlette.requests import Request
|
||||
from starlette.responses import JSONResponse
|
||||
from starlette.routing import Route
|
||||
|
||||
from app.a2a.card import A2A_PATH, build_agent_card
|
||||
from app.a2a.executor import SolutionArchitectExecutor
|
||||
from app.assembly import Assembly, open_assembly
|
||||
from app.a2a_server import SolutionArchitectExecutor
|
||||
from app.agent import Assembly, open_assembly
|
||||
from app.card import A2A_PATH, build_agent_card
|
||||
from app.config import Settings, get_settings
|
||||
from app.execution.presentation import to_generate_response
|
||||
from app.presentation import to_generate_response
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -1,9 +1 @@
|
||||
"""Nodes package."""
|
||||
|
||||
from .design_node import design_node
|
||||
from .discover_node import discover_node
|
||||
from .package_node import package_node
|
||||
from .source_discover_node import source_discover_node
|
||||
from .validate_node import validate_node
|
||||
|
||||
__all__ = ["source_discover_node", "discover_node", "design_node", "validate_node", "package_node"]
|
||||
"""The nodes of the Execution graph."""
|
||||
|
||||
@@ -1,139 +0,0 @@
|
||||
"""Phase 1: Architecture Design Node."""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict
|
||||
from app.states.state import GCPArchitectureState
|
||||
from app.skills.loader import SkillLoader
|
||||
from app.tools.mcp_developer_knowledge import get_mcp_client
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def design_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
|
||||
"""Processes Phase 1 Design: select GCP managed products, generate Mermaid graph, and Terraform IaC."""
|
||||
logger.info("Executing design_node")
|
||||
skill_prompt = skill_loader.format_skills_for_prompt("design")
|
||||
|
||||
# Developer Knowledge MCP Grounding Search
|
||||
mcp_client = get_mcp_client()
|
||||
mcp_knowledge = mcp_client.search_documents(query="Cloud Run PubSub event-driven architecture", category="compute")
|
||||
docs = mcp_knowledge.get("documents", [])
|
||||
citations_str = "\n".join([f"- [{doc['title']}]({doc['uri']})" for doc in docs[:3]]) if docs else "- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework)"
|
||||
|
||||
architecture_doc = f"""# Phase 1 — Architecture & Product Selection
|
||||
|
||||
## Selected Products
|
||||
- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution)
|
||||
- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling)
|
||||
- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay)
|
||||
- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys)
|
||||
- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting)
|
||||
|
||||
## Component Responsibilities
|
||||
1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted.
|
||||
2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers.
|
||||
3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting.
|
||||
|
||||
## Security & Compliance
|
||||
- HTTPS ingress with TLS 1.3 encryption in transit.
|
||||
- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub.
|
||||
- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`.
|
||||
|
||||
## Grounded Documentation Citations (Google Developer Knowledge MCP)
|
||||
{citations_str}
|
||||
"""
|
||||
|
||||
mermaid_diagram = """flowchart TD
|
||||
Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service]
|
||||
CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic]
|
||||
CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket]
|
||||
PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service]
|
||||
EventConsumer -->|Acknowledge| PubSubTopic
|
||||
"""
|
||||
|
||||
terraform_code = """# Google Cloud Solution Architecture Baseline
|
||||
terraform {
|
||||
required_version = ">= 1.5.0"
|
||||
required_providers {
|
||||
google = {
|
||||
source = "hashicorp/google"
|
||||
version = "~> 5.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "google" {
|
||||
project = var.project_id
|
||||
region = var.region
|
||||
}
|
||||
|
||||
# Cloud Run v2 Service
|
||||
resource "google_cloud_run_v2_service" "app_service" {
|
||||
name = "${var.environment}-app-service"
|
||||
location = var.region
|
||||
|
||||
template {
|
||||
containers {
|
||||
image = var.container_image
|
||||
ports {
|
||||
container_port = 8080
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Pub/Sub Topic for Event Ingestion
|
||||
resource "google_pubsub_topic" "event_ingestion" {
|
||||
name = "${var.environment}-event-ingestion-topic"
|
||||
labels = {
|
||||
environment = var.environment
|
||||
managed_by = "terraform"
|
||||
}
|
||||
}
|
||||
|
||||
# Cloud Storage Bucket for Event Replay Audit
|
||||
resource "google_storage_bucket" "audit_bucket" {
|
||||
name = "${var.project_id}-${var.environment}-audit-bucket"
|
||||
location = var.region
|
||||
force_destroy = false
|
||||
uniform_bucket_level_access = true
|
||||
|
||||
versioning {
|
||||
enabled = true
|
||||
}
|
||||
|
||||
lifecycle_rule {
|
||||
condition {
|
||||
age = 30
|
||||
}
|
||||
action {
|
||||
type = "Delete"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Least-Privilege IAM Service Account
|
||||
resource "google_service_account" "ingress_sa" {
|
||||
account_id = "${var.environment}-ingress-sa"
|
||||
display_name = "Cloud Run Ingress Identity"
|
||||
}
|
||||
|
||||
resource "google_pubsub_topic_iam_member" "publisher_binding" {
|
||||
topic = google_pubsub_topic.event_ingestion.name
|
||||
role = "roles/pubsub.publisher"
|
||||
member = "serviceAccount:${google_service_account.ingress_sa.email}"
|
||||
}
|
||||
"""
|
||||
|
||||
active_skills = state.get("active_skills", [])
|
||||
if "architecture_design" not in active_skills:
|
||||
active_skills.append("architecture_design")
|
||||
|
||||
return {
|
||||
"architecture_doc": architecture_doc,
|
||||
"mermaid_diagram": mermaid_diagram,
|
||||
"terraform_code": terraform_code,
|
||||
"product_selection_deferred": False,
|
||||
"current_phase": "design",
|
||||
"active_skills": active_skills,
|
||||
}
|
||||
@@ -1,74 +0,0 @@
|
||||
"""Phase 0: Requirements Discovery Node."""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict
|
||||
from app.states.state import GCPArchitectureState
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def discover_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
|
||||
"""Processes Phase 0 Discovery: document functional/non-functional requirements with product selection deferred."""
|
||||
logger.info("Executing discover_node")
|
||||
skill_prompt = skill_loader.format_skills_for_prompt("discover")
|
||||
|
||||
# Generate or format requirements document baseline
|
||||
request_summary = state.get("workflow_request", "Event-driven HTTP application reference architecture")
|
||||
|
||||
requirements_doc = f"""# Step 0 — Requirements discovery
|
||||
|
||||
## Workflow request
|
||||
{request_summary}
|
||||
|
||||
## Functional requirements
|
||||
- Accept authenticated HTTPS requests from external clients.
|
||||
- Execute stateless application logic behind a versioned service endpoint.
|
||||
- Publish asynchronous domain events from the application.
|
||||
- Process events independently and tolerate retry/redelivery.
|
||||
- Persist durable objects and application state separately.
|
||||
- Expose operational logs, metrics, and audit-relevant events.
|
||||
- Support repeatable infrastructure changes through declarative IaC.
|
||||
|
||||
## Non-functional requirements
|
||||
- High availability within a selected Google Cloud region.
|
||||
- Horizontal scale for bursty HTTP traffic and asynchronous work.
|
||||
- At-least-once event delivery with idempotent consumers.
|
||||
- Encryption in transit and at rest using managed defaults initially.
|
||||
- Least-privilege runtime identities and private network egress where practical.
|
||||
- Observable deployments with structured logs and actionable health signals.
|
||||
- Reproducible, reviewable, non-deployment validation in CI.
|
||||
|
||||
## Constraints
|
||||
- Google Cloud is the target cloud; exact products are not selected in discovery.
|
||||
- Terraform must be deployable without embedding secrets or credentials.
|
||||
- The baseline must not provision resources during validation.
|
||||
- A container image must be supplied by the application delivery pipeline.
|
||||
- State backends, DNS ownership, identity federation, and organization policies are external concerns.
|
||||
|
||||
## Assumptions
|
||||
- A single region is acceptable for the initial deployment.
|
||||
- The application can be packaged as an OCI container listening on port 8080.
|
||||
- Events can use at-least-once semantics and consumers can deduplicate.
|
||||
- A dedicated Google Cloud project is available.
|
||||
- Managed encryption keys and public ingress are acceptable defaults pending review.
|
||||
|
||||
## Open questions
|
||||
- What are the actual API, event, data-retention, and compliance requirements?
|
||||
- Which clients and identity provider must authenticate requests?
|
||||
- What are traffic, payload-size, latency, RTO, and RPO targets?
|
||||
- Which data is relational, document, object, or analytical?
|
||||
|
||||
**Product selection deferred:** `true` for this phase.
|
||||
"""
|
||||
|
||||
active_skills = state.get("active_skills", [])
|
||||
if "requirements_discovery" not in active_skills:
|
||||
active_skills.append("requirements_discovery")
|
||||
|
||||
return {
|
||||
"requirements_doc": requirements_doc,
|
||||
"product_selection_deferred": True,
|
||||
"current_phase": "discover",
|
||||
"active_skills": active_skills,
|
||||
}
|
||||
@@ -1,10 +1,4 @@
|
||||
"""The LangGraph that holds an Execution (ADR-0003).
|
||||
|
||||
START -> orchestrator_turn
|
||||
orchestrator_turn -> specialist_task x N (Send, parallel) -> orchestrator_turn
|
||||
orchestrator_turn -> await_user (interrupt) -> orchestrator_turn
|
||||
orchestrator_turn -> finalize -> END
|
||||
orchestrator_turn -> end_with_warnings -> END
|
||||
"""The nodes of the Execution graph (ADR-0003); app/workflows/execution_graph.py wires them.
|
||||
|
||||
Only orchestrator_turn and await_user change the Ledger; parallel Specialist tasks
|
||||
append outcomes that the next Orchestrator turn applies in order.
|
||||
@@ -13,14 +7,16 @@ append outcomes that the next Orchestrator turn applies in order.
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
import re
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
from typing import Any
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
from langgraph.types import Command, Send, interrupt
|
||||
|
||||
from app.agents.runtime import (
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
@@ -29,24 +25,23 @@ from app.agents.runtime import (
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
Submitted,
|
||||
ToolFactory,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
)
|
||||
from app.execution.deliverables import (
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
from app.states.ledger import Ledger, LedgerRefusal
|
||||
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
DeliverableKind,
|
||||
inputs_of,
|
||||
)
|
||||
from app.execution.ledger import Ledger, LedgerRefusal
|
||||
from app.execution.recorder import ExecutionRecorder
|
||||
from app.execution.state import ExecutionState
|
||||
from app.execution.tools import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]]
|
||||
|
||||
NO_USER_REPLY = (
|
||||
"No user is available. State your assumption, record it in the Deliverable under "
|
||||
"'Assumptions', and proceed."
|
||||
@@ -58,7 +53,19 @@ def _no_tools(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
return ()
|
||||
|
||||
|
||||
def build_execution_graph(
|
||||
@dataclass(frozen=True)
|
||||
class ExecutionNodes:
|
||||
"""The node functions of one Execution graph, bound to its runtime and recorder."""
|
||||
|
||||
orchestrator_turn: Callable[[ExecutionState], Awaitable[Command]]
|
||||
# Receives its Send payload, not the Execution state.
|
||||
specialist_task: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
|
||||
await_user: Callable[[ExecutionState], Awaitable[Command]]
|
||||
finalize: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
|
||||
end_with_warnings: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
|
||||
|
||||
|
||||
def make_execution_nodes(
|
||||
*,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
@@ -66,13 +73,22 @@ def build_execution_graph(
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
) -> StateGraph:
|
||||
) -> ExecutionNodes:
|
||||
tool_factory = tool_factory or _no_tools
|
||||
|
||||
async def record_progress(
|
||||
state: ExecutionState, ledger: Ledger, status: str | None = None
|
||||
) -> int:
|
||||
recorded = state.get("events_recorded", 0)
|
||||
for event in ledger.events[recorded:]:
|
||||
logger.info(
|
||||
"[%s] ledger %s %s by %s%s",
|
||||
state["execution_id"],
|
||||
event.type,
|
||||
event.subject,
|
||||
event.actor,
|
||||
f" ({event.detail})" if event.detail else "",
|
||||
)
|
||||
await recorder.record_events(state["execution_id"], ledger.events[recorded:])
|
||||
if status:
|
||||
await recorder.record_status(
|
||||
@@ -169,7 +185,16 @@ def build_execution_graph(
|
||||
prompt="Decide the next step for this Execution using your tools.",
|
||||
context=_orchestrator_context(state, ledger, pending_questions, notes),
|
||||
)
|
||||
started = time.monotonic()
|
||||
outcome = await runtime.run(roles[ORCHESTRATOR], task, toolbox.tools())
|
||||
logger.info(
|
||||
"[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s",
|
||||
state["execution_id"],
|
||||
turns,
|
||||
_current_phase(ledger),
|
||||
time.monotonic() - started,
|
||||
_summarise_outcome(outcome),
|
||||
)
|
||||
notes = []
|
||||
pre_approved = bool(state.get("pre_approved"))
|
||||
conversation = list(state.get("conversation", []))
|
||||
@@ -243,11 +268,27 @@ def build_execution_graph(
|
||||
context=task_input["context"],
|
||||
deliverable=kind.value,
|
||||
)
|
||||
logger.info(
|
||||
"[%s] %s started %s (attempt %d)",
|
||||
task_input["execution_id"],
|
||||
role.name,
|
||||
kind,
|
||||
task_input["attempt"],
|
||||
)
|
||||
started = time.monotonic()
|
||||
try:
|
||||
outcome: Outcome = await runtime.run(role, task, tools)
|
||||
except Exception as exc:
|
||||
logger.exception("Specialist %s failed on %s", role.name, kind)
|
||||
outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}")
|
||||
logger.info(
|
||||
"[%s] %s finished %s in %.0fs: %s",
|
||||
task_input["execution_id"],
|
||||
role.name,
|
||||
kind,
|
||||
time.monotonic() - started,
|
||||
_summarise_outcome(outcome),
|
||||
)
|
||||
return {
|
||||
"outcomes": [
|
||||
_outcome_record(role.name, kind, task_input["attempt"], outcome)
|
||||
@@ -257,7 +298,7 @@ def build_execution_graph(
|
||||
async def await_user(state: ExecutionState) -> Command:
|
||||
prompt = state["prompt"] or {}
|
||||
if state.get("pre_approved"):
|
||||
reply = _automatic_reply(prompt)
|
||||
reply = _automatic_reply(prompt, state.get("scripted_answers", []))
|
||||
else:
|
||||
reply = interrupt(prompt)
|
||||
|
||||
@@ -330,23 +371,30 @@ def build_execution_graph(
|
||||
await record_progress(state, ledger, "completed_with_warnings")
|
||||
return {"status": "completed_with_warnings"}
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
graph.add_node("orchestrator_turn", orchestrator_turn)
|
||||
# Specialist tasks receive their Send payload, not the Execution state.
|
||||
graph.add_node("specialist_task", cast(Any, specialist_task))
|
||||
graph.add_node("await_user", await_user)
|
||||
graph.add_node("finalize", finalize)
|
||||
graph.add_node("end_with_warnings", end_with_warnings)
|
||||
graph.add_edge(START, "orchestrator_turn")
|
||||
graph.add_edge("specialist_task", "orchestrator_turn")
|
||||
graph.add_edge("finalize", END)
|
||||
graph.add_edge("end_with_warnings", END)
|
||||
return graph
|
||||
return ExecutionNodes(
|
||||
orchestrator_turn=orchestrator_turn,
|
||||
specialist_task=specialist_task,
|
||||
await_user=await_user,
|
||||
finalize=finalize,
|
||||
end_with_warnings=end_with_warnings,
|
||||
)
|
||||
|
||||
|
||||
# --- helpers ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _summarise_outcome(outcome: Outcome) -> str:
|
||||
if isinstance(outcome, TurnEnded):
|
||||
return f"called {outcome.tool}"
|
||||
if isinstance(outcome, Submitted):
|
||||
return f"submitted ({len(outcome.content)} chars)"
|
||||
if isinstance(outcome, NeedsInput):
|
||||
return f"needs input ({len(outcome.questions)} questions)"
|
||||
if isinstance(outcome, BudgetExhausted):
|
||||
return f"budget exhausted: {outcome.summary[:200]}"
|
||||
return f"stopped: {outcome.message[:200]}"
|
||||
|
||||
|
||||
def _current_phase(ledger: Ledger) -> str:
|
||||
for phase in PHASE_ORDER:
|
||||
if ledger.phase_status(phase).value != "approved":
|
||||
@@ -395,6 +443,7 @@ def _specialist_input(
|
||||
) -> dict[str, Any]:
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
return {
|
||||
"execution_id": state["execution_id"],
|
||||
"role": spec.specialist,
|
||||
"kind": kind.value,
|
||||
"attempt": attempt,
|
||||
@@ -446,14 +495,35 @@ def _describe_unfinished(outcome: Outcome) -> str:
|
||||
return f"Ended with an unexpected outcome: {type(outcome).__name__}."
|
||||
|
||||
|
||||
def _automatic_reply(prompt: Mapping[str, Any]) -> dict[str, Any]:
|
||||
def _automatic_reply(
|
||||
prompt: Mapping[str, Any], scripted_answers: Sequence[Sequence[str]] = ()
|
||||
) -> dict[str, Any]:
|
||||
"""The reply in a pre-approved Execution: approve, deny cloud reads, and answer
|
||||
questions from scripted (pattern, answer) pairs where one matches."""
|
||||
if "approval" in prompt:
|
||||
return {
|
||||
"approval": {"phase": prompt["approval"]["phase"], "decision": "approve"}
|
||||
}
|
||||
if "permission" in prompt:
|
||||
return {"permission": {prompt["permission"]["tier"]: False}}
|
||||
return {"reply": NO_USER_REPLY}
|
||||
lines = []
|
||||
unanswered = False
|
||||
for item in prompt.get("questions", []):
|
||||
answer = next(
|
||||
(
|
||||
scripted
|
||||
for pattern, scripted in scripted_answers
|
||||
if re.search(pattern, item["question"], re.IGNORECASE)
|
||||
),
|
||||
None,
|
||||
)
|
||||
if answer is None:
|
||||
unanswered = True
|
||||
else:
|
||||
lines.append(f"Q: {item['question']}\nA: {answer}")
|
||||
if unanswered or not lines:
|
||||
lines.append(NO_USER_REPLY)
|
||||
return {"reply": "\n\n".join(lines)}
|
||||
|
||||
|
||||
def _reply_text(reply: object) -> str:
|
||||
@@ -1,151 +0,0 @@
|
||||
"""Phase 3: Solution Guide Packaging Node."""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict
|
||||
from app.states.state import GCPArchitectureState
|
||||
from app.skills.loader import SkillLoader
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def package_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
|
||||
"""Processes Phase 3 Packaging: assemble final solution-architecture-guide.md document."""
|
||||
logger.info("Executing package_node")
|
||||
skill_prompt = skill_loader.format_skills_for_prompt("package")
|
||||
|
||||
src_doc = state.get("source_discovery_doc", "")
|
||||
src_mmd = state.get("source_mermaid_diagram", "")
|
||||
req_doc = state.get("requirements_doc", "")
|
||||
arch_doc = state.get("architecture_doc", "")
|
||||
mmd_doc = state.get("mermaid_diagram", "")
|
||||
tf_doc = state.get("terraform_code", "")
|
||||
val_doc = state.get("validation_results", "")
|
||||
|
||||
solution_guide = f"""# Google Cloud solution architecture: Event-Driven Regional Workload
|
||||
|
||||
## 1. Executive summary and workload overview
|
||||
This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture.
|
||||
|
||||
## 2. Requirements and current state
|
||||
|
||||
### 2.1. Functional requirements
|
||||
See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions.
|
||||
- Accept authenticated HTTPS requests from external clients.
|
||||
- Execute stateless application logic behind a versioned service endpoint.
|
||||
- Asynchronously publish domain events to Pub/Sub.
|
||||
- Retain raw payload records in Cloud Storage for audit and replay.
|
||||
|
||||
### 2.2. Non-functional requirements
|
||||
- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts.
|
||||
- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics.
|
||||
- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense.
|
||||
- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring.
|
||||
- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load.
|
||||
- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes.
|
||||
|
||||
### 2.3. Current state (As-Is Architecture)
|
||||
{src_doc.strip()}
|
||||
|
||||
```mermaid
|
||||
{(src_mmd or "flowchart TD\n Client --> LegacyApp").strip()}
|
||||
```
|
||||
|
||||
### 2.4. Dependencies
|
||||
- **Internal dependencies**: Service identity bindings and event consumer subscribers.
|
||||
- **External dependencies**: Client HTTP submitters and OCI container image registry.
|
||||
|
||||
## 3. Technical decomposition of the workload
|
||||
- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls.
|
||||
- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages.
|
||||
- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state.
|
||||
|
||||
## 4. Proposed solution architecture
|
||||
|
||||
### 4.1. Google Cloud products and features mapping (Selected products)
|
||||
| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control <br> **Cons**: Higher operational overhead & idle costs |
|
||||
| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls <br> **Cons**: Complex cluster management |
|
||||
| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support <br> **Cons**: Less flexible scaling for unstructured event logs |
|
||||
|
||||
### 4.2. Architecture diagram (Mermaid)
|
||||
```mermaid
|
||||
{mmd_doc.strip()}
|
||||
```
|
||||
|
||||
### 4.3. Architecture description
|
||||
- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event.
|
||||
- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger.
|
||||
|
||||
## 5. Design and configuration recommendations
|
||||
|
||||
### 5.1. Security, privacy, and compliance
|
||||
- **Access control**: Least-privilege IAM service accounts bound to publisher roles.
|
||||
- **Data protection**: Managed encryption at rest for Pub/Sub and Storage.
|
||||
- **Network Security**: Serverless VPC Access connector for isolated network egress.
|
||||
|
||||
### 5.2. Reliability
|
||||
- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication.
|
||||
- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic.
|
||||
|
||||
### 5.3. Operational excellence
|
||||
- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts.
|
||||
- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints.
|
||||
|
||||
### 5.4. Cost optimization
|
||||
- **Sizing and scaling**: Automatic scale-to-zero compute instances.
|
||||
|
||||
### 5.5. Performance efficiency
|
||||
- **Caching and CDN**: Edge CDN caching for static endpoints.
|
||||
|
||||
### 5.6. Sustainability
|
||||
- Serverless compute adoption minimizing idle carbon footprint.
|
||||
|
||||
## 6. Deployment guidance
|
||||
|
||||
### 6.1. Deployment prerequisites
|
||||
- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`).
|
||||
- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`).
|
||||
|
||||
### 6.2. Step-by-step deployment instructions (Terraform)
|
||||
```hcl
|
||||
{tf_doc.strip()}
|
||||
```
|
||||
|
||||
Apply blueprint instructions:
|
||||
```bash
|
||||
terraform -chdir=terraform init
|
||||
terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI'
|
||||
terraform -chdir=terraform apply
|
||||
```
|
||||
|
||||
## 7. Validation plan (Validation results)
|
||||
{val_doc.strip()}
|
||||
|
||||
### Verification Checklist
|
||||
- Step 4 guide persistence: non-empty solution-architecture-guide.md.
|
||||
- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram.
|
||||
- Step 6 & 7 publication & remote verification: complete.
|
||||
|
||||
## 8. References
|
||||
- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework)
|
||||
- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run)
|
||||
- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview)
|
||||
"""
|
||||
|
||||
active_skills = state.get("active_skills", [])
|
||||
if "packaging_guide" not in active_skills:
|
||||
active_skills.append("packaging_guide")
|
||||
|
||||
status_summary = {
|
||||
"phases_completed": ["discover", "design", "validate", "package"],
|
||||
"validation_passed": state.get("validation_passed", True),
|
||||
"total_active_skills": len(active_skills),
|
||||
}
|
||||
|
||||
return {
|
||||
"solution_guide": solution_guide,
|
||||
"current_phase": "package",
|
||||
"active_skills": active_skills,
|
||||
"status_summary": status_summary,
|
||||
}
|
||||
@@ -1,43 +0,0 @@
|
||||
"""Phase 0a: Existing Source Environment Discovery Node."""
|
||||
|
||||
import logging
|
||||
import re
|
||||
from typing import Any, Dict
|
||||
from app.states.state import GCPArchitectureState
|
||||
from app.skills.loader import SkillLoader
|
||||
from app.tools.gcp_scanner import GCPEnvironmentScanner
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def source_discover_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
|
||||
"""Processes Phase 0a Source Environment Discovery: documents existing as-is architecture before target migration."""
|
||||
logger.info("Executing source_discover_node")
|
||||
skill_prompt = skill_loader.format_skills_for_prompt("source_discover")
|
||||
|
||||
# Extract target GCP project ID from request if specified
|
||||
request_summary = state.get("workflow_request", "")
|
||||
project_id = state.get("project_id")
|
||||
if not project_id and request_summary:
|
||||
match = re.search(r"project\s+([a-z0-9-]+)", request_summary, re.IGNORECASE)
|
||||
if match:
|
||||
project_id = match.group(1)
|
||||
|
||||
# Run live GCP environment scanner
|
||||
scanner = GCPEnvironmentScanner(project_id=project_id)
|
||||
scan_result = scanner.scan_environment()
|
||||
report = scanner.format_scan_report(scan_result)
|
||||
|
||||
source_discovery_doc = report["doc"]
|
||||
source_mermaid_diagram = report["mermaid"]
|
||||
|
||||
active_skills = state.get("active_skills", [])
|
||||
if "source_discovery" not in active_skills:
|
||||
active_skills.append("source_discovery")
|
||||
|
||||
return {
|
||||
"source_discovery_doc": source_discovery_doc,
|
||||
"source_mermaid_diagram": source_mermaid_diagram,
|
||||
"current_phase": "source_discover",
|
||||
"active_skills": active_skills,
|
||||
}
|
||||
@@ -1,60 +0,0 @@
|
||||
"""Phase 2: Pre-deployment Validation Node."""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict
|
||||
from app.states.state import GCPArchitectureState
|
||||
from app.skills.loader import SkillLoader
|
||||
from app.tools.validation_tools import (
|
||||
validate_mermaid_diagram,
|
||||
validate_terraform_syntax,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def validate_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
|
||||
"""Processes Phase 2 Validation: verify diagram, Terraform IaC, and artifact integrity."""
|
||||
logger.info("Executing validate_node")
|
||||
skill_prompt = skill_loader.format_skills_for_prompt("validate")
|
||||
|
||||
mermaid_content = state.get("mermaid_diagram", "")
|
||||
terraform_content = state.get("terraform_code", "")
|
||||
|
||||
mermaid_check = validate_mermaid_diagram.invoke({"diagram_content": mermaid_content})
|
||||
terraform_check = validate_terraform_syntax.invoke({"terraform_content": terraform_content})
|
||||
|
||||
errors = []
|
||||
if not mermaid_check.get("valid"):
|
||||
errors.append(f"Mermaid Check Failed: {mermaid_check.get('error')}")
|
||||
if not terraform_check.get("valid"):
|
||||
errors.append(f"Terraform Check Failed: {terraform_check.get('error')}")
|
||||
|
||||
validation_passed = len(errors) == 0
|
||||
|
||||
validation_results = f"""# Validation Results
|
||||
|
||||
## Summary
|
||||
- **Overall Validation Status**: {"PASS" if validation_passed else "FAIL"}
|
||||
- **Mermaid Diagram Syntax**: {"PASS" if mermaid_check.get("valid") else "FAIL"}
|
||||
- **Terraform Structural Check**: {"PASS" if terraform_check.get("valid") else "FAIL"}
|
||||
- **Resource Provisioning Triggered**: False (Static non-deployment check enforced)
|
||||
|
||||
## Verification Rules Checklist
|
||||
- [x] Functional & Non-functional requirements specified
|
||||
- [x] Product selection deferred during discovery and resolved in design phase
|
||||
- [x] Regional High Availability and Security IAM boundaries configured
|
||||
- [x] Mermaid diagram follows valid graph syntax
|
||||
- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings
|
||||
"""
|
||||
|
||||
active_skills = state.get("active_skills", [])
|
||||
if "validation_rules" not in active_skills:
|
||||
active_skills.append("validation_rules")
|
||||
|
||||
return {
|
||||
"validation_results": validation_results,
|
||||
"validation_passed": validation_passed,
|
||||
"errors": errors,
|
||||
"current_phase": "validate",
|
||||
"active_skills": active_skills,
|
||||
}
|
||||
@@ -7,9 +7,9 @@ import re
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.agents.runtime import RoleSpec
|
||||
from app.execution.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
from app.execution.engine import Interaction
|
||||
from app.adk.runtime import RoleSpec
|
||||
from app.agent import Interaction
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
|
||||
def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
@@ -14,7 +14,7 @@ from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.agent_skills import SkillFormatError, SkillMeta, discover_skills
|
||||
from app.skills.agent_skills import SkillFormatError, SkillMeta, discover_skills
|
||||
|
||||
TIERS = ("general", "cloud_read")
|
||||
_REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
|
||||
@@ -13,7 +13,7 @@ from collections import defaultdict
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any, Protocol
|
||||
|
||||
from app.execution.ledger import LedgerEvent
|
||||
from app.states.ledger import LedgerEvent
|
||||
|
||||
SESSION_AGENT_NAME = "solution-architect"
|
||||
|
||||
@@ -1,5 +1 @@
|
||||
"""Skills package."""
|
||||
|
||||
from .loader import LocalSkill, SkillLoader
|
||||
|
||||
__all__ = ["LocalSkill", "SkillLoader"]
|
||||
"""Agent Skills discovery and validation. The Skills themselves live in skills/ at the repository root."""
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
name: architecture_design
|
||||
phase: design
|
||||
description: Guidance for GCP product selection, architecture design markdown, Mermaid diagrams, and Terraform IaC generation.
|
||||
---
|
||||
|
||||
# Phase 1: Architecture Design & Product Selection Skill
|
||||
|
||||
When designing a Google Cloud Solution Architecture based on `docs/requirements.md`:
|
||||
|
||||
1. **Resolve Deferred Product Choices**: Select Google Cloud managed services suited for regional high availability and scale:
|
||||
- Compute: Cloud Run / Cloud Functions / GKE.
|
||||
- Messaging & Ingestion: Pub/Sub, Eventarc, or Cloud Tasks.
|
||||
- State & Storage: Cloud Storage, Firestore, Cloud SQL, or Spanner.
|
||||
- Identity & Security: Cloud IAM, Secret Manager, KMS, Artifact Registry.
|
||||
2. **Architecture Documentation (`docs/architecture.md`)**:
|
||||
- Provide executive summary, component responsibilities, data flow, security model, and cost model.
|
||||
3. **Mermaid Diagram (`architecture.mmd`)**:
|
||||
- Render clean, valid Mermaid syntax (`graph TD` or `flowchart TD`) mapping client ingress, compute, messaging, and storage components.
|
||||
4. **Terraform Infrastructure as Code (`terraform/`)**:
|
||||
- Produce valid Terraform HCL files (`main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`).
|
||||
- Ensure planability without credentials or resource provisioning during validation.
|
||||
@@ -1,105 +0,0 @@
|
||||
"""Dynamic Local Skill Loader."""
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional
|
||||
import yaml
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@dataclass
|
||||
class LocalSkill:
|
||||
"""Represents a local skill loaded from SKILL.md."""
|
||||
|
||||
name: str
|
||||
phase: str
|
||||
description: str
|
||||
content: str
|
||||
filepath: Path
|
||||
|
||||
|
||||
class SkillLoader:
|
||||
"""Discovers and parses local skills from SKILL.md files."""
|
||||
|
||||
def __init__(self, skills_dir: Path) -> None:
|
||||
self.skills_dir = skills_dir
|
||||
self._skills: Dict[str, LocalSkill] = {}
|
||||
|
||||
def load_skills(self) -> Dict[str, LocalSkill]:
|
||||
"""Scan skills_dir and load all valid SKILL.md files."""
|
||||
self._skills.clear()
|
||||
if not self.skills_dir.exists():
|
||||
logger.warning("Skills directory does not exist: %s", self.skills_dir)
|
||||
return self._skills
|
||||
|
||||
for skill_file in self.skills_dir.glob("**/SKILL.md"):
|
||||
try:
|
||||
skill = self._parse_skill_file(skill_file)
|
||||
if skill:
|
||||
self._skills[skill.name] = skill
|
||||
logger.info("Loaded skill '%s' (phase: %s)", skill.name, skill.phase)
|
||||
except Exception as exc:
|
||||
logger.error("Failed to parse skill file %s: %s", skill_file, exc)
|
||||
|
||||
return self._skills
|
||||
|
||||
def get_skill(self, name: str) -> Optional[LocalSkill]:
|
||||
"""Get skill by name."""
|
||||
if not self._skills:
|
||||
self.load_skills()
|
||||
return self._skills.get(name)
|
||||
|
||||
def get_skills_by_phase(self, phase: str) -> List[LocalSkill]:
|
||||
"""Get all skills matching a specific workflow phase."""
|
||||
if not self._skills:
|
||||
self.load_skills()
|
||||
return [skill for skill in self._skills.values() if skill.phase == phase]
|
||||
|
||||
def format_skills_for_prompt(self, phase: Optional[str] = None) -> str:
|
||||
"""Format skill instruction content into a single string for system prompt injection."""
|
||||
skills = self.get_skills_by_phase(phase) if phase else list(self._skills.values())
|
||||
if not skills:
|
||||
return ""
|
||||
|
||||
prompt_parts = ["## Injected Skill Instructions\n"]
|
||||
for skill in skills:
|
||||
prompt_parts.append(f"### Skill: {skill.name} (Phase: {skill.phase})\n{skill.content}\n")
|
||||
return "\n".join(prompt_parts)
|
||||
|
||||
def _parse_skill_file(self, filepath: Path) -> Optional[LocalSkill]:
|
||||
"""Parse frontmatter and markdown content from SKILL.md."""
|
||||
raw_text = filepath.read_text(encoding="utf-8")
|
||||
if not raw_text.startswith("---"):
|
||||
return LocalSkill(
|
||||
name=filepath.parent.name,
|
||||
phase="general",
|
||||
description="",
|
||||
content=raw_text,
|
||||
filepath=filepath,
|
||||
)
|
||||
|
||||
parts = raw_text.split("---", 2)
|
||||
if len(parts) < 3:
|
||||
return None
|
||||
|
||||
frontmatter_raw = parts[1]
|
||||
content = parts[2].strip()
|
||||
|
||||
try:
|
||||
metadata = yaml.safe_load(frontmatter_raw) or {}
|
||||
except Exception:
|
||||
metadata = {}
|
||||
|
||||
name = metadata.get("name", filepath.parent.name)
|
||||
phase = metadata.get("phase", "general")
|
||||
description = metadata.get("description", "")
|
||||
|
||||
return LocalSkill(
|
||||
name=name,
|
||||
phase=phase,
|
||||
description=description,
|
||||
content=content,
|
||||
filepath=filepath,
|
||||
)
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
name: packaging_guide
|
||||
phase: package
|
||||
description: Guidance for assembling the comprehensive solution-architecture-guide.md following Google's official 8-section output template.
|
||||
---
|
||||
|
||||
# Phase 3: Solution Packaging Skill
|
||||
|
||||
When producing `solution-architecture-guide.md`, follow Google's official 8-section solution architecture output template:
|
||||
|
||||
1. **Executive summary and workload overview**
|
||||
- High-level business goals, workload description, and proposed solution architecture summary.
|
||||
2. **Requirements and current state**
|
||||
- **2.1. Functional requirements**: Business processes, key activities, and use cases.
|
||||
- **2.2. Non-functional requirements**: Security, reliability, cost, operations, performance, and sustainability requirements.
|
||||
- **2.3. Current state**: Existing As-Is architecture, pain points, and migration drivers.
|
||||
- **2.4. Dependencies**: Internal and external system dependencies.
|
||||
3. **Technical decomposition of the workload**
|
||||
- Layered breakdown of application tiers and logical components.
|
||||
4. **Proposed solution architecture**
|
||||
- **4.1. Google Cloud products and features mapping**: Selected products mapping table with justifications, doc citations, and alternatives considered.
|
||||
- **4.2. Architecture diagram**: Embedded Mermaid diagrams for As-Is (Before) and Target Google Cloud (After) architecture.
|
||||
- **4.3. Architecture description**: Data flow and task/control flow between components.
|
||||
5. **Design and configuration recommendations** (Architecture Framework Pillars)
|
||||
- 5.1 Security, privacy, and compliance (IAM, encryption, network security)
|
||||
- 5.2 Reliability (Redundancy, disaster recovery, RTO/RPO)
|
||||
- 5.3 Operational excellence (Monitoring, logging, IaC)
|
||||
- 5.4 Cost optimization (Sizing, autoscaling, pricing models)
|
||||
- 5.5 Performance efficiency (Caching, database & query optimization)
|
||||
- 5.6 Sustainability (Resource efficiency, serverless adoption)
|
||||
6. **Deployment guidance**
|
||||
- **6.1. Deployment prerequisites**: Required GCP APIs, SDK tools, and permissions.
|
||||
- **6.2. Step-by-step deployment instructions**: Complete Terraform IaC blueprint (`terraform/main.tf`) and CLI execution runbook.
|
||||
7. **Validation plan**
|
||||
- Pre-deployment validation results, dry-run checks, and Verification Checklist.
|
||||
8. **References**
|
||||
- Citations and documentation links grounded by Google Developer Knowledge MCP.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: requirements_discovery
|
||||
phase: discover
|
||||
description: Guidance for discovering, analyzing, and documenting GCP solution requirements.
|
||||
---
|
||||
|
||||
# Phase 0: Requirements Discovery Skill
|
||||
|
||||
When performing requirements discovery for a Google Cloud Solution Architecture:
|
||||
|
||||
1. **Analyze Workflow Request**: Extract functional and non-functional requirements from the user request or baseline specification.
|
||||
2. **Defer Product Selection**: During discovery, product selection must explicitly be marked as `deferred: true`. Do not commit to specific GCP products (e.g. Cloud Run vs GKE) until the design phase.
|
||||
3. **Capture Core Requirements**:
|
||||
- Authenticated HTTPS ingress, stateless processing, asynchronous domain events.
|
||||
- High availability within a selected GCP region.
|
||||
- At-least-once delivery with idempotent processing.
|
||||
- Least-privilege IAM service accounts and private networking where practical.
|
||||
4. **Document Assumptions and Open Questions**: Highlight unknowns regarding scale, traffic spikes, compliance, and specific region requirements.
|
||||
5. **Output Standard**: Produce a valid `docs/requirements.md` file matching the phase spec.
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
name: source_discovery
|
||||
phase: source_discover
|
||||
description: Guidance for discovering, auditing, and documenting the existing pre-emptive source environment before target migration.
|
||||
---
|
||||
|
||||
# Phase 0a: Existing Source Environment Discovery Skill
|
||||
|
||||
When auditing and discovering an existing pre-emptive source environment:
|
||||
|
||||
1. **Assess As-Is Architecture**: Analyze existing workloads, on-premises applications, legacy infrastructure, or existing cloud provider setups.
|
||||
2. **Identify Existing Components**:
|
||||
- Monolithic / legacy application services & ingress endpoints.
|
||||
- Self-hosted database engines (e.g. MySQL, PostgreSQL, Oracle) or legacy file shares.
|
||||
- Traditional messaging queues (e.g. RabbitMQ, ActiveMQ).
|
||||
- Network topology, firewall rules, and authentication mechanisms.
|
||||
3. **Capture Source Metrics & Pain Points**:
|
||||
- Current scale, capacity constraints, downtime risks, and operational bottlenecks.
|
||||
- Security vulnerabilities, compliance gaps, and maintenance costs.
|
||||
4. **Document Source Architecture**:
|
||||
- Produce a clear `docs/source-architecture.md` baseline documenting the "Before" state.
|
||||
- Render a Mermaid diagram representing the existing source topology (`source-architecture.mmd`).
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: validation_rules
|
||||
phase: validate
|
||||
description: Guidance for verifying Terraform syntax, Mermaid diagrams, and repository artifact completeness.
|
||||
---
|
||||
|
||||
# Phase 2: Pre-Deployment Validation Skill
|
||||
|
||||
When validating solution architecture artifacts:
|
||||
|
||||
1. **Static File Validation**:
|
||||
- Verify existence and non-emptiness of `workflow.yaml`, `requirements.yaml`, `docs/requirements.md`, `docs/architecture.md`, `architecture.mmd`, `terraform/main.tf`, `solution-architecture-guide.md`.
|
||||
2. **Mermaid Syntax Validation**:
|
||||
- Check diagram for matching subgraphs, valid node definitions, arrow syntaxes, and clean structure.
|
||||
3. **Terraform Integrity**:
|
||||
- Ensure Terraform modules, variables, and resource blocks adhere to Google Cloud provider standards.
|
||||
- Ensure static non-provisioning check passes (`deploy_resources: false`).
|
||||
4. **Output Report**:
|
||||
- Generate `validation-results.md` summarizing pass/fail status across all verification rules.
|
||||
@@ -1,5 +1 @@
|
||||
"""States package."""
|
||||
|
||||
from .state import GCPArchitectureState
|
||||
|
||||
__all__ = ["GCPArchitectureState"]
|
||||
"""Checkpointed Execution state and the Ledger that guards it."""
|
||||
|
||||
@@ -33,3 +33,4 @@ class ExecutionState(TypedDict, total=False):
|
||||
turns: int
|
||||
status: str # running | completed | completed_with_warnings
|
||||
warnings: list[str]
|
||||
scripted_answers: list[list[str]] # [regex, answer], pre-approved runs only
|
||||
@@ -12,7 +12,7 @@ from dataclasses import asdict, dataclass, field
|
||||
from enum import StrEnum
|
||||
from typing import Any
|
||||
|
||||
from app.execution.deliverables import (
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
DeliverableKind,
|
||||
@@ -1,31 +0,0 @@
|
||||
"""State definition for GCP Solution Architecture Agent workflow."""
|
||||
|
||||
from typing import Any, Dict, List, Optional, TypedDict
|
||||
|
||||
|
||||
class GCPArchitectureState(TypedDict, total=False):
|
||||
"""LangGraph State tracking state across all workflow phases."""
|
||||
|
||||
# Workflow Request / Input Intent
|
||||
workflow_request: str
|
||||
target_dir: str
|
||||
|
||||
# Pre-emptive Source Environment Discovery Outputs (Before State)
|
||||
source_discovery_doc: Optional[str]
|
||||
source_mermaid_diagram: Optional[str]
|
||||
|
||||
# Target Phase Outputs (After State)
|
||||
requirements_doc: Optional[str]
|
||||
architecture_doc: Optional[str]
|
||||
mermaid_diagram: Optional[str]
|
||||
terraform_code: Optional[str]
|
||||
validation_results: Optional[str]
|
||||
solution_guide: Optional[str]
|
||||
|
||||
# Workflow Metadata & Dynamic Skill Context
|
||||
product_selection_deferred: bool
|
||||
current_phase: str
|
||||
active_skills: List[str]
|
||||
errors: List[str]
|
||||
validation_passed: bool
|
||||
status_summary: Dict[str, Any]
|
||||
@@ -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",
|
||||
]
|
||||
|
||||
@@ -11,21 +11,23 @@ from collections.abc import Mapping, Sequence
|
||||
from pathlib import PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from app.agents.runtime import (
|
||||
from app.adk.runtime import (
|
||||
FILES_SCHEMA,
|
||||
NeedsInput,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
files_from_argument,
|
||||
)
|
||||
from app.execution.deliverables import (
|
||||
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
DeliverableKind,
|
||||
PhaseId,
|
||||
check_submission,
|
||||
deliverables_in,
|
||||
)
|
||||
from app.execution.ledger import Ledger, LedgerRefusal, PhaseStatus
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
CLOUD_READ = "cloud_read"
|
||||
@@ -232,10 +234,11 @@ def specialist_tools(
|
||||
) -> 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: Mapping[str, str] | None = None
|
||||
) -> ToolResult:
|
||||
attachments = dict(attachments or {})
|
||||
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(
|
||||
@@ -262,10 +265,7 @@ def specialist_tools(
|
||||
_schema(
|
||||
{
|
||||
"content": {"type": "string"},
|
||||
"attachments": {
|
||||
"type": "object",
|
||||
"additionalProperties": {"type": "string"},
|
||||
},
|
||||
"attachments": FILES_SCHEMA,
|
||||
},
|
||||
["content"],
|
||||
),
|
||||
@@ -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)
|
||||
@@ -10,7 +10,7 @@ import asyncio
|
||||
import dataclasses
|
||||
from collections.abc import Mapping, Sequence
|
||||
|
||||
from app.agents.runtime import (
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
RoleSpec,
|
||||
@@ -9,12 +9,11 @@ from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
|
||||
from app.agents.roles import PILLAR_ADVISOR
|
||||
from app.agents.runtime import AgentRuntime, RoleSpec, ToolSpec
|
||||
from app.execution.deliverables import DeliverableKind
|
||||
from app.execution.graph import ToolFactory
|
||||
from app.execution.pillars import pillar_consultation_tool
|
||||
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(
|
||||
@@ -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)}",
|
||||
}
|
||||
@@ -1,5 +1 @@
|
||||
"""Workflows package."""
|
||||
|
||||
from .gcp_architecture_graph import create_agent, create_gcp_architecture_graph
|
||||
|
||||
__all__ = ["create_agent", "create_gcp_architecture_graph"]
|
||||
"""The Execution graph and the dependency graph of Deliverables it runs."""
|
||||
|
||||
56
app/workflows/execution_graph.py
Normal file
56
app/workflows/execution_graph.py
Normal file
@@ -0,0 +1,56 @@
|
||||
"""The LangGraph that holds an Execution (ADR-0003).
|
||||
|
||||
START -> orchestrator_turn
|
||||
orchestrator_turn -> specialist_task x N (Send, parallel) -> orchestrator_turn
|
||||
orchestrator_turn -> await_user (interrupt) -> orchestrator_turn
|
||||
orchestrator_turn -> finalize -> END
|
||||
orchestrator_turn -> end_with_warnings -> END
|
||||
|
||||
The nodes live in app/nodes/execution_nodes.py; they route with Command and Send, so
|
||||
only the fixed edges are declared here.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory
|
||||
from app.nodes.execution_nodes import make_execution_nodes
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
|
||||
|
||||
def build_execution_graph(
|
||||
*,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
recorder: ExecutionRecorder,
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder,
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
graph.add_node("orchestrator_turn", cast(Any, nodes.orchestrator_turn))
|
||||
# Specialist tasks receive their Send payload, not the Execution state.
|
||||
graph.add_node("specialist_task", cast(Any, nodes.specialist_task))
|
||||
graph.add_node("await_user", cast(Any, nodes.await_user))
|
||||
graph.add_node("finalize", cast(Any, nodes.finalize))
|
||||
graph.add_node("end_with_warnings", cast(Any, nodes.end_with_warnings))
|
||||
graph.add_edge(START, "orchestrator_turn")
|
||||
graph.add_edge("specialist_task", "orchestrator_turn")
|
||||
graph.add_edge("finalize", END)
|
||||
graph.add_edge("end_with_warnings", END)
|
||||
return graph
|
||||
@@ -1,61 +0,0 @@
|
||||
"""Dynamic LangGraph StateGraph Factory with Skill Injection."""
|
||||
|
||||
import logging
|
||||
from typing import Any, Callable
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
from langgraph.graph.state import CompiledStateGraph
|
||||
|
||||
from app.config import get_settings
|
||||
from app.nodes import design_node, discover_node, package_node, source_discover_node, validate_node
|
||||
from app.skills.loader import SkillLoader
|
||||
from app.states.state import GCPArchitectureState
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def create_gcp_architecture_graph(skill_loader: SkillLoader | None = None) -> CompiledStateGraph:
|
||||
"""Creates and compiles the LangGraph StateGraph with dynamic local skill injection."""
|
||||
if skill_loader is None:
|
||||
settings = get_settings()
|
||||
skill_loader = SkillLoader(settings.SKILLS_DIR)
|
||||
skill_loader.load_skills()
|
||||
|
||||
builder = StateGraph(GCPArchitectureState)
|
||||
|
||||
# Wrap nodes with skill loader injection
|
||||
def run_source_discover(state: GCPArchitectureState) -> dict[str, Any]:
|
||||
return source_discover_node(state, skill_loader)
|
||||
|
||||
def run_discover(state: GCPArchitectureState) -> dict[str, Any]:
|
||||
return discover_node(state, skill_loader)
|
||||
|
||||
def run_design(state: GCPArchitectureState) -> dict[str, Any]:
|
||||
return design_node(state, skill_loader)
|
||||
|
||||
def run_validate(state: GCPArchitectureState) -> dict[str, Any]:
|
||||
return validate_node(state, skill_loader)
|
||||
|
||||
def run_package(state: GCPArchitectureState) -> dict[str, Any]:
|
||||
return package_node(state, skill_loader)
|
||||
|
||||
# Add graph nodes
|
||||
builder.add_node("source_discover", run_source_discover)
|
||||
builder.add_node("discover", run_discover)
|
||||
builder.add_node("design", run_design)
|
||||
builder.add_node("validate", run_validate)
|
||||
builder.add_node("package", run_package)
|
||||
|
||||
# Add sequential workflow edges
|
||||
builder.add_edge(START, "source_discover")
|
||||
builder.add_edge("source_discover", "discover")
|
||||
builder.add_edge("discover", "design")
|
||||
builder.add_edge("design", "validate")
|
||||
builder.add_edge("validate", "package")
|
||||
builder.add_edge("package", END)
|
||||
|
||||
return builder.compile()
|
||||
|
||||
|
||||
def create_agent(skill_loader: SkillLoader | None = None) -> CompiledStateGraph:
|
||||
"""Alias for create_gcp_architecture_graph to support standardized agent creation."""
|
||||
return create_gcp_architecture_graph(skill_loader)
|
||||
@@ -1,89 +0,0 @@
|
||||
"""Starlette REST Route Handlers for GCP Solution Architecture Agent.
|
||||
|
||||
Powered by Google ADK runner, PostgreSQL database persistence, and multi-agent orchestration.
|
||||
"""
|
||||
|
||||
import logging
|
||||
from typing import Any, Dict
|
||||
from starlette.requests import Request
|
||||
from starlette.responses import JSONResponse
|
||||
|
||||
from app.adk.evaluation import ADKEvaluator
|
||||
from app.adk.runners import ADKAgentRunner
|
||||
from app.adk.sessions import PostgresSessionService
|
||||
from app.card import AGENT_CARD
|
||||
from app.config import get_settings
|
||||
from app.tools.validation_tools import validate_repository_artifacts
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
async def health_check(request: Request) -> JSONResponse:
|
||||
"""GET /health - Operational health endpoint."""
|
||||
settings = get_settings()
|
||||
return JSONResponse({
|
||||
"status": "healthy",
|
||||
"agent": settings.AGENT_NAME,
|
||||
"version": settings.AGENT_VERSION,
|
||||
"adk_framework": "enabled",
|
||||
"database": "postgresql",
|
||||
})
|
||||
|
||||
|
||||
async def get_card(request: Request) -> JSONResponse:
|
||||
"""GET /card - Agent metadata and capability card."""
|
||||
return JSONResponse(AGENT_CARD)
|
||||
|
||||
|
||||
async def run_workflow(request: Request) -> JSONResponse:
|
||||
"""POST /generate - Execute multi-agent ADK workflow with PostgreSQL persistence."""
|
||||
try:
|
||||
body = await request.json() if request.headers.get("content-type") == "application/json" else {}
|
||||
except Exception:
|
||||
body = {}
|
||||
|
||||
workflow_request = body.get("request", "Default event-driven HTTP architecture")
|
||||
target_dir = body.get("target_dir", ".")
|
||||
session_id = body.get("session_id")
|
||||
|
||||
runner = ADKAgentRunner()
|
||||
result = runner.run_execution(
|
||||
session_id=session_id,
|
||||
request_summary=workflow_request,
|
||||
target_dir=target_dir,
|
||||
)
|
||||
|
||||
return JSONResponse(result)
|
||||
|
||||
|
||||
async def get_session_route(request: Request) -> JSONResponse:
|
||||
"""GET /sessions/{session_id} - Query session state from PostgreSQL database."""
|
||||
session_id = request.path_params.get("session_id")
|
||||
session_service = PostgresSessionService()
|
||||
session = session_service.get_session(session_id)
|
||||
|
||||
if not session:
|
||||
return JSONResponse({"error": f"Session {session_id} not found"}, status_code=404)
|
||||
|
||||
return JSONResponse({
|
||||
"session_id": session.session_id,
|
||||
"agent_name": session.agent_name,
|
||||
"state": session.state,
|
||||
})
|
||||
|
||||
|
||||
async def validate_artifacts_route(request: Request) -> JSONResponse:
|
||||
"""POST /validate - Run pre-deployment validation checks against target directory."""
|
||||
try:
|
||||
body = await request.json() if request.headers.get("content-type") == "application/json" else {}
|
||||
except Exception:
|
||||
body = {}
|
||||
|
||||
target_dir = body.get("target_dir", ".")
|
||||
result = validate_repository_artifacts.invoke({"target_dir": target_dir})
|
||||
|
||||
status_code = 200 if result.get("valid") else 400
|
||||
return JSONResponse(result, status_code=status_code)
|
||||
|
||||
status_code = 200 if result.get("valid") else 400
|
||||
return JSONResponse(result, status_code=status_code)
|
||||
Reference in New Issue
Block a user