Iteration 4: - Overlay Skills (step 12): an Execution names an organisation's standards Skill from the folders the deployment configures; recorded with its version. An example standards Skill and an evaluation case that uses it. - Lessons (step 10): a prove command that compares a run with lessons against one without, and triage of evidence an existing lesson already covers. Iteration 5: - Step 8: the references of a Specialist's Skills its task needs are named in its context as read_first. - Step 14: a remote MCP server's reply that instructs the agent is withheld; the user's own text is flagged as a risk and nothing more. - Step 15: in a Change request, items only reworded are listed apart from real changes. - Step 19: each Execution's design recommendations are judged when it ends and the scores kept in its record. The evaluation takes its rubric from the same place. Each question was calibrated against live Jev; none has run in a case. Steps 6, 7, 9, 13 and 18 stay planned, with the reasons in the plan map. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
195 lines
8.4 KiB
Python
195 lines
8.4 KiB
Python
"""Typed settings for GCP Solution Architecture Agent."""
|
|
|
|
import os
|
|
from collections.abc import MutableMapping
|
|
from pathlib import Path
|
|
|
|
from dotenv import dotenv_values
|
|
from pydantic_settings import BaseSettings, SettingsConfigDict
|
|
|
|
|
|
class Settings(BaseSettings):
|
|
"""Application Settings."""
|
|
|
|
model_config = SettingsConfigDict(
|
|
env_file=".env",
|
|
env_file_encoding="utf-8",
|
|
extra="ignore",
|
|
)
|
|
|
|
# Agent Identity
|
|
AGENT_NAME: str = "gcp_solution_architecture_agent"
|
|
AGENT_VERSION: str = "1.0.0"
|
|
LOG_LEVEL: str = "INFO"
|
|
|
|
# Database & Storage Settings (External PostgreSQL, SQLite fallback)
|
|
POSTGRES_HOST: str = "localhost"
|
|
POSTGRES_PORT: int = 5432
|
|
POSTGRES_DB: str = "gcp_agent_db"
|
|
POSTGRES_USER: str = "postgres"
|
|
POSTGRES_PASSWORD: str = "postgres"
|
|
DATABASE_URL: str | None = None
|
|
SQLITE_FALLBACK_DB: str = "gcp_agent_local.db"
|
|
|
|
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
|
|
CLOUD_PROVIDER: str = "gcp"
|
|
MCP_ENABLED: bool = True
|
|
MCP_ENABLE_PREVIEW: bool = True
|
|
MCP_QUOTA_PROJECT: str | None = None # defaults to the ADC project
|
|
MCP_TIMEOUT_SECONDS: float = 30
|
|
|
|
# Local Terraform tools (fmt, validate, plan; never apply)
|
|
TERRAFORM_BINARY: str = "terraform"
|
|
TERRAFORM_TIMEOUT_SECONDS: float = 300
|
|
# Where Terraform providers are kept between checks, so they download once.
|
|
# Relative paths are under the repository root. Set it empty to disable the cache.
|
|
TF_PLUGIN_CACHE_DIR: str = ".cache/terraform-plugins"
|
|
|
|
# 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
|
|
A2A_PUBLIC_URL: str | None = None # advertised in the agent card
|
|
ORCHESTRATOR_BUDGET: int = 40
|
|
SPECIALIST_BUDGET: int = 15
|
|
# Where overlay Skills live: an organisation's standards or one engagement's
|
|
# constraints, each an Agent Skill (ADR-0004). Comma-separated folders, relative
|
|
# to the repository root. A caller names an overlay; it can never supply one.
|
|
OVERLAY_SKILLS_DIRS: str = "skills/overlays"
|
|
# Overlay Skills every Execution loads, comma-separated.
|
|
DEFAULT_OVERLAY_SKILLS: str = ""
|
|
|
|
# Give Specialists the lessons Skill. Off runs without anything learned, which
|
|
# is how the evaluation shows whether a lesson helps.
|
|
LESSONS_ENABLED: bool = True
|
|
# With a user present, a Specialist's first submission of a Deliverable is refused
|
|
# until it has put its draft to them. Off: Specialists are only told to.
|
|
CONFIRM_DRAFTS: bool = True
|
|
MAX_REVISIONS: int = 3
|
|
MAX_ORCHESTRATOR_TURNS: int = 100
|
|
# How an Orchestrator turn is decided (ADR-0007): "router" reads the Execution
|
|
# and follows its playbook, with Jev for the judgements; "model" has a language
|
|
# model choose the tool calls, as before, and is kept for comparison.
|
|
ORCHESTRATOR: str = "router"
|
|
# Agent runs in flight at once, pillar advisors included (model rate limits)
|
|
MAX_PARALLEL_SPECIALISTS: int = 4
|
|
CHECKPOINTER: str = "sqlite" # memory | sqlite | postgres
|
|
CHECKPOINT_DB_PATH: str = "checkpoints.db"
|
|
|
|
# Jev decision service (ADR-0007), reached through TypeSafe AI's Python SDK.
|
|
# With no key, every decision takes its fallback and the agent behaves as it does
|
|
# without Jev. The key comes from the environment or a secret store, never from
|
|
# the provider bundle or the repository.
|
|
TYPESAFE_API_KEY: str | None = None
|
|
TYPESAFE_BASE_URL: str | None = None # None: the SDK's default endpoint
|
|
TYPESAFE_DEFAULT_MODEL: str | None = None # None: the SDK's default model
|
|
JEV_TIMEOUT_SECONDS: float = 5.0 # one request
|
|
JEV_REQUESTS_PER_SECOND: float = 5.0
|
|
JEV_MAX_IN_FLIGHT: int = 8
|
|
JEV_BUDGET_CALLS: int = 500 # per Execution
|
|
JEV_BUDGET_TOKENS: int = 1_000_000 # per Execution
|
|
# A probability at or above ACT is acted on; at or below CLOSE is dropped; in
|
|
# between, the user is asked. A choice below CONFIDENCE is not relied on.
|
|
JEV_ACT_THRESHOLD: float = 0.75
|
|
JEV_CLOSE_THRESHOLD: float = 0.15
|
|
JEV_CONFIDENCE_THRESHOLD: float = 0.6
|
|
# Review a design's coverage at submission: for each condition a requirement
|
|
# lists, which Check verifies it. Off until a full case has run with it.
|
|
JEV_COVERAGE_REVIEW: bool = False
|
|
# How likely "no Check verifies this" must be before the condition is raised.
|
|
JEV_COVERAGE_THRESHOLD: float = 0.6
|
|
# Review the requirements at submission: does any name a cloud product? Off
|
|
# until a full case has run with it.
|
|
JEV_REQUIREMENTS_REVIEW: bool = False
|
|
JEV_REQUIREMENTS_THRESHOLD: float = 0.3
|
|
# How directly a change must affect a pillar for its advisor to be consulted
|
|
# again: 0 not at all, 1 only indirectly, 2 directly.
|
|
JEV_PILLAR_THRESHOLD: float = 1.5
|
|
# In a Change request: at or below this probability of a real change, an item
|
|
# whose text differs from the Baseline's is listed as reworded, not changed.
|
|
JEV_REWORDED_THRESHOLD: float = 0.25
|
|
# Name, in a Specialist's context, the references of its Skills its task needs.
|
|
# A reference is named at this score or above: 0 not needed, 1 might help,
|
|
# 2 needed.
|
|
JEV_SKILL_ROUTING: bool = True
|
|
JEV_SKILL_THRESHOLD: float = 1.25
|
|
# Judge each Execution's design recommendations when it ends and keep the
|
|
# scores in its record. It reports only.
|
|
JEV_ASSESS_EXECUTIONS: bool = True
|
|
# Check what remote MCP servers return, and what the user writes, for text that
|
|
# tries to instruct the agent. A server's reply at or above the threshold is
|
|
# withheld from the Specialist; the user's own words are only flagged.
|
|
JEV_GUARDRAIL: bool = True
|
|
JEV_GUARDRAIL_THRESHOLD: float = 0.75
|
|
|
|
# Paths
|
|
BASE_DIR: Path = Path(__file__).resolve().parent.parent
|
|
|
|
def overlay_dirs(self) -> list[Path]:
|
|
return [
|
|
path if path.is_absolute() else self.BASE_DIR / path
|
|
for path in (
|
|
Path(entry.strip())
|
|
for entry in self.OVERLAY_SKILLS_DIRS.split(",")
|
|
if entry.strip()
|
|
)
|
|
]
|
|
|
|
def default_overlays(self) -> list[str]:
|
|
return [n.strip() for n in self.DEFAULT_OVERLAY_SKILLS.split(",") if n.strip()]
|
|
|
|
def terraform_plugin_cache(self) -> str | None:
|
|
"""The provider cache directory as an absolute path; None when disabled."""
|
|
if not self.TF_PLUGIN_CACHE_DIR.strip():
|
|
return None
|
|
path = Path(self.TF_PLUGIN_CACHE_DIR).expanduser()
|
|
return str(path if path.is_absolute() else self.BASE_DIR / path)
|
|
|
|
def get_database_url(self) -> str:
|
|
"""Construct database connection URL (PostgreSQL or SQLite fallback)."""
|
|
if self.DATABASE_URL:
|
|
return self.DATABASE_URL
|
|
return f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
|
|
|
|
|
|
_settings: Settings | None = None
|
|
|
|
|
|
def export_env_file(
|
|
path: str | Path = ".env", environ: MutableMapping[str, str] | None = None
|
|
) -> list[str]:
|
|
"""Put the env file's other variables into the process environment.
|
|
|
|
Settings reads its own fields from the env file. Everything else in it is for a
|
|
library that reads the environment itself, such as a Cloud provider's client
|
|
looking for its project and credentials, and would otherwise be ignored. A
|
|
variable already set in the environment is left alone, and Settings' own fields
|
|
are never exported, so the secrets among them do not reach child processes.
|
|
Returns the names it set.
|
|
"""
|
|
environ = os.environ if environ is None else environ
|
|
path = Path(path)
|
|
if not path.is_file():
|
|
return []
|
|
own = {name.upper() for name in Settings.model_fields}
|
|
exported = []
|
|
for name, value in dotenv_values(path).items():
|
|
if value is None or name.upper() in own or name in environ:
|
|
continue
|
|
environ[name] = value
|
|
exported.append(name)
|
|
return exported
|
|
|
|
|
|
def get_settings() -> Settings:
|
|
"""Get singleton Settings instance, loading the env file at first use."""
|
|
global _settings
|
|
if _settings is None:
|
|
# Tests switch this off so they never depend on a developer's env file.
|
|
if os.environ.get("ENV_FILE_EXPORT", "true").lower() != "false":
|
|
export_env_file()
|
|
_settings = Settings()
|
|
return _settings
|