latest refactoring
Some checks failed
validation / verify (push) Failing after 10s

This commit is contained in:
2026-10-06 20:22:37 +01:00
parent e94b2493e7
commit 7ee49ab352
414 changed files with 15768 additions and 3896 deletions

View File

@@ -1 +0,0 @@
"""A2A interface for interactive Executions (A2A 1.0, with v0.3 compatibility)."""

View File

@@ -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"],
)
],
)

View File

@@ -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__)

View File

@@ -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."""

View File

@@ -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```"

View File

@@ -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)

View File

@@ -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

View File

@@ -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,
}

View File

@@ -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

View File

@@ -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,

View File

@@ -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"

View File

@@ -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", []),
}

View File

@@ -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]

View File

@@ -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

View File

@@ -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,
]

View File

@@ -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],
)

View File

@@ -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))

View File

@@ -1 +0,0 @@
"""Agent runtimes: the framework-neutral interface agents run behind, and its implementations."""

View File

@@ -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))

View File

@@ -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"],
)
],
},
}
)

View File

@@ -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

View File

@@ -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:

View File

@@ -1 +0,0 @@
"""Execution of the solution-architecture workflow: Deliverables, the Ledger and the graph."""

View File

@@ -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,
}

View File

@@ -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__)

View File

@@ -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."""

View File

@@ -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,
}

View File

@@ -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,
}

View File

@@ -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:

View File

@@ -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,
}

View File

@@ -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,
}

View File

@@ -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,
}

View File

@@ -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:

View File

@@ -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

View File

@@ -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"

View File

@@ -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."""

View File

@@ -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.

View File

@@ -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,
)

View File

@@ -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.

View File

@@ -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.

View File

@@ -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`).

View File

@@ -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.

View File

@@ -1,5 +1 @@
"""States package."""
from .state import GCPArchitectureState
__all__ = ["GCPArchitectureState"]
"""Checkpointed Execution state and the Ledger that guards it."""

View File

@@ -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

View File

@@ -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,

View File

@@ -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]

View File

@@ -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",
]

View File

@@ -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"],
),

View File

@@ -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)}

View File

@@ -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",
),
}

View File

@@ -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__)

View File

@@ -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)

View File

@@ -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,

View File

@@ -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(

View File

@@ -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)}",
}

View File

@@ -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."""

View 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

View File

@@ -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)

View File

@@ -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)