refactored: to utilise the google adk and production grade agent

2026-09-02 21:42:10 +01:00
parent b9a924cf4a
commit a24a44e28c
279 changed files with 12003 additions and 390 deletions
--- a/README.md
+++ b/README.md
@@ -1,22 +1,176 @@
-# gcp_solution_architecture_agent
+# GCP Solution Architecture Agent (`gcp_solution_architecture_agent`)

-A four-phase Google Cloud solution-architecture workflow packaged as one reviewable repository.
+A production-ready Google Cloud Solution Architecture Agent built using **Google ADK (Agent Development Kit)**, **LangChain**, and **LangGraph**, featuring a multi-agent orchestration graph with iterative review loops, dynamic local skill loading, PostgreSQL database persistence, a Starlette REST API server, and an offline evaluation harness.

-## Workflow
-1. **Discover** requirements without choosing products (`docs/requirements.md`).
-2. **Design** the Google Cloud architecture and Terraform (`docs/architecture.md`, `architecture.mmd`, `terraform/`).
-3. **Validate** artifacts without provisioning (`scripts/validate.sh`, `tests/`).
-4. **Package** the approved result (`solution-architecture-guide.md`).
+---

-The repository is derived from the `workflow_agent` template and is intentionally safe to run without a cloud deployment. The Terraform plan requires credentials and a project only when a user chooses to run it.
+## 🌟 Architecture & Features

-## Commands
+### 1. Multi-Agent Orchestration & `google.adk.agents.LoopAgent`
+The agent uses an end-to-end multi-agent graph managed by an `OrchestratorLoopAgent` (`google.adk.agents.LoopAgent`):
+- **`SourceDiscoveryAgent`** (Phase 0a): Pre-emptively audits and documents the existing pre-migration source environment (As-Is Architecture) and pain points.
+- **`DiscoveryAgent`** (Phase 0): Discovers functional & non-functional requirements while explicitly deferring product selection.
+- **`ArchitectureDesignAgent`** (Phase 1): Resolves product selections (Cloud Run, Pub/Sub, Cloud Storage, Firestore, IAM, KMS), grounds guidance with **Google Developer Knowledge MCP**, generates Mermaid diagrams (`architecture.mmd`), and builds Terraform IaC (`terraform/main.tf`).
+- **`ValidationReviewAgent`** (Phase 2): Evaluates Mermaid syntax, Terraform structural integrity, and artifact completeness using `google.adk.tools.FunctionTool`.
+- **`PackagingAgent`** (Phase 3): Compiles the final comprehensive `solution-architecture-guide.md` with **Before (Source) vs After (Target)** architecture comparison.
+- **`OrchestratorLoopAgent`**: Repeatedly loops through the multi-agent pipeline, reviewing and validating content in a feedback loop until production quality criteria pass or `max_iterations` is reached.
+
+### 2. Google ADK Integration (`google.adk`)
+Built directly on Google ADK framework primitives (with offline compatibility stubs):
+- **`google.adk.agents`**: `LlmAgent`, `SequentialAgent`, `ParallelAgent`, `LoopAgent`.
+- **`google.adk.tools`**: `FunctionTool` wrappers for static artifact and diagram validators, plus Google Developer Knowledge MCP tools (`developerknowledge:*`).
+- **`google.adk.artifacts`**: `ArtifactRepository` synchronized with disk and PostgreSQL.
+- **`google.adk.sessions`**: `PostgresSessionService` for durable session memory.
+- **`google.adk.runners`**: `Runner` for managing execution workflows.
+- **`google.adk.workflows`**: `Workflow` composition primitives.
+- **`google.adk.evaluation`**: `Evaluator` for scoring benchmark suites.
+
+### 3. PostgreSQL Database Persistence (`app/database.py`)
+State, sessions, workflow executions, review iteration logs, and evaluation metrics are written to an external PostgreSQL database (with an automatic SQLite fallback for offline development):
+- `adk_sessions`: Durable session memory and state data.
+- `workflow_executions`: Workflow execution status, phase, and iteration metrics.
+- `adk_artifacts`: Generated solution architecture artifacts (including `docs/source-architecture.md` and `source-architecture.mmd`).
+- `orchestrator_review_logs`: Detailed iteration review logs from the `OrchestratorLoopAgent`.
+- `adk_evaluations`: Benchmark evaluation scores and pass rates.
+
+### 4. Dynamic Local Skill Loading (`app/skills/`)
+Domain knowledge is stored as self-contained markdown instruction templates under `app/skills/`:
+- `source_discovery/SKILL.md` (Phase 0a - Pre-emptive Source Environment Discovery)
+- `requirements_discovery/SKILL.md` (Phase 0 - Requirements Discovery & Deferral)
+- `architecture_design/SKILL.md` (Phase 1 - Product Selection & Terraform IaC)
+- `validation_rules/SKILL.md` (Phase 2 - Pre-deployment Validation Rules)
+- `packaging_guide/SKILL.md` (Phase 3 - Solution Guide Packaging)
+
+The `SkillLoader` (`app/skills/loader.py`) dynamically parses frontmatter and injects instructions into phase system prompts.
+
+### 5. Starlette REST API Server (`app/agent.py`)
+Production HTTP REST endpoints exposed via Starlette and Uvicorn:
+- `GET /health`: Operational health signal & database connection status.
+- `GET /card`: Agent capability card metadata.
+- `POST /generate`: Trigger the ADK multi-agent workflow execution.
+- `POST /validate`: Execute pre-deployment artifact validation.
+- `GET /sessions/{session_id}`: Query session state from the PostgreSQL database.
+
+---
+
+## 🚀 Quick Start & Commands
+
+### Install Dependencies
 ```bash
-terraform -chdir=terraform fmt -check -recursive
-terraform -chdir=terraform init -backend=false
-terraform -chdir=terraform validate
-python3 -m unittest discover -s tests -v
-bash scripts/validate.sh
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+### Run Tests & Validation
+```bash
+# Run pytest test suite (100% pass rate)
+pytest -v
+
+# Run offline benchmark evaluation harness
+python3 -m eval.eval_harness
+
+# Run static artifact validation
+python3 scripts/validate_artifacts.py
+```
+
+### Start Starlette REST Server
+```bash
+python3 app/agent.py --host 0.0.0.0 --port 8080
+```
+
+### 🐳 Run with Podman
+
+#### 1. Build the Podman Container Image
+```bash
+podman build -t gcp-solution-architecture-agent:latest .
+```
+
+#### 2. Run Container with Host Deliverables Volume Mount
+To ensure execution deliverables (`deliverables/executions/{execution_id}/*`) are written directly to your host machine's workspace:
+
+```bash
+podman run -d --name gcp-agent \
+  -p 8080:8080 \
+  -v $(pwd)/deliverables:/app/deliverables:Z \
+  -v ~/.config/gcloud/application_default_credentials.json:/app/credentials/adc.json:ro \
+  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json \
+  -e GCP_PROJECT_ID=your-project-id \
+  localhost/gcp-solution-architecture-agent:latest
+```
+
+#### 3. Run Connected to External PostgreSQL Container
+```bash
+podman run -d --name gcp-agent \
+  -p 8080:8080 \
+  -e POSTGRES_HOST=postgres-container-name \
+  -e POSTGRES_PORT=5432 \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=gcp_agent_db \
+  localhost/gcp-solution-architecture-agent:latest
+```
+
+#### 4. Test API Endpoints
+```bash
+# Health Signal
+curl http://localhost:8080/health
+
+# Agent Capability Card
+curl http://localhost:8080/card
+
+# Run Multi-Agent ADK Workflow
+curl -X POST http://localhost:8080/generate \
+  -H "Content-Type: application/json" \
+  -d '{"request": "Event-driven regional HTTP application in Podman"}'
+```
+
+---
+
+## 📁 Repository Structure
+```
+gcp_solution_architecture_agent/
+├── app/
+│   ├── adk/                     # Google ADK framework primitives & fallbacks
+│   │   ├── agents.py            # Multi-agents & OrchestratorLoopAgent
+│   │   ├── artifacts.py         # PostgresArtifactRepository
+│   │   ├── compat.py            # ADK compatibility layer
+│   │   ├── evaluation.py        # ADKEvaluator
+│   │   ├── runners.py           # ADKAgentRunner
+│   │   ├── sessions.py          # PostgresSessionService
+│   │   ├── tools.py             # ADK FunctionTools
+│   │   └── workflows.py         # ADK Workflow composition
+│   ├── agent.py                 # Starlette REST server entrypoint
+│   ├── card.py                  # AgentCard & capability metadata
+│   ├── config.py                # Typed settings (Pydantic BaseSettings)
+│   ├── database.py              # PostgreSQL database persistence manager
+│   ├── nodes/                   # Phase execution node handlers
+│   ├── skills/                  # Local SKILL.md instruction templates & SkillLoader
+│   ├── states/                  # GCPArchitectureState schema definition
+│   ├── tools/                   # LangChain & ADK validation tools
+│   └── workflows/               # LangGraph StateGraph & Starlette REST routes
+├── eval/                        # ADK Evaluation & Optimization Harness
+│   ├── datasets/                # Benchmark test cases (JSON)
+│   ├── eval_harness.py          # Benchmark runner CLI
+│   ├── metrics.py               # Scoring rubrics & evaluation logic
+│   ├── optimizer.py             # Prompt tuning optimizer
+│   └── test_eval_harness.py     # Evaluation unit tests
+├── deliverables/                 # Scalable deliverable repository (categorized & versioned)
+│   ├── as-is/                   # Pre-emptive Source Environment Deliverables (Before State)
+│   │   ├── source-architecture.md
+│   │   └── source-architecture.mmd
+│   ├── target/                  # Target Architecture Deliverables (After State)
+│   │   ├── requirements.md
+│   │   ├── architecture.md
+│   │   └── architecture.mmd
+│   ├── validation/              # Pre-deployment Validation Reports
+│   │   └── validation-results.md
+│   ├── guides/                  # Consolidate Solution Architecture Guides
+│   │   └── solution-architecture-guide.md
+│   └── executions/              # Per-Execution Versioned Snapshots ({execution_id}/*)
+├── docs/                        # Specifications, audit notes & verification records
+├── terraform/                   # Deployable GCP Terraform IaC blueprint
+├── scripts/
+│   └── validate_artifacts.py    # Static artifact validation script
+└── tests/                       # Unit & integration test suite
 ```

-`terraform plan` is optional and must be run with an explicitly supplied project and credentials; CI only performs static validation.