feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005). A new target-architect Specialist produces one graph of Elements, Relationships and Checks; the diagram is rendered from it, deployment guidance must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations carry ids in data files, and a submission with a gap in the Requirements chain is refused. Also in this commit: - Customer cases group Executions, with an intent history per case - lesson candidates are captured when an Execution ends - evaluation gains chain, verdict, judged and interactive checks, and per-case thresholds - Terraform providers are cached between checks - the requirements analyst proposes defaults instead of asking - the legacy-baseline case and the checks that only read it are removed - ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed - plans for iterations 4 to 7 under .agents/plans/ Unproven with a real model: no evaluation run has completed on this design. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -56,6 +56,7 @@ class SolutionArchitectExecutor(AgentExecutor):
|
||||
interaction = await self._engine.start(
|
||||
context.get_user_input(),
|
||||
session_id=context.context_id,
|
||||
customer_case=options.get("customer_case"),
|
||||
execution_id=task_id,
|
||||
pre_approved=bool(options.get("pre_approved", False)),
|
||||
allow_cloud_read=options.get("allow_cloud_read"),
|
||||
|
||||
@@ -31,6 +31,7 @@ from google.adk.tools.tool_context import ToolContext
|
||||
from google.genai import types
|
||||
|
||||
from app.adk.runtime import (
|
||||
REJECTION_PREFIXES,
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
@@ -52,13 +53,6 @@ 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)
|
||||
|
||||
@@ -7,6 +7,7 @@ enforce is exercised exactly as a model would meet it.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections import deque
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
@@ -20,6 +21,7 @@ from app.adk.runtime import (
|
||||
Stopped,
|
||||
ToolSpec,
|
||||
)
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -31,6 +33,97 @@ class Call:
|
||||
Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]]
|
||||
|
||||
|
||||
# One small, coherent Requirements chain, so sample submissions pass every link.
|
||||
SAMPLE_DATA: dict[str, str] = {
|
||||
"requirements.json": json.dumps(
|
||||
[
|
||||
{"id": "FR-1", "kind": "functional", "text": "Accept events."},
|
||||
{"id": "NFR-1", "kind": "non_functional", "text": "99.9% availability."},
|
||||
]
|
||||
),
|
||||
"components.json": json.dumps(
|
||||
[{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}]
|
||||
),
|
||||
"products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]),
|
||||
"recommendations.json": json.dumps(
|
||||
[
|
||||
{
|
||||
"id": "DR-1",
|
||||
"pillar": "security",
|
||||
"text": "Use a dedicated identity.",
|
||||
"components": ["C-1"],
|
||||
}
|
||||
]
|
||||
),
|
||||
"target-architecture.json": json.dumps(
|
||||
{
|
||||
"elements": [
|
||||
{
|
||||
"id": "E-1",
|
||||
"name": "Ingress service",
|
||||
"component": "C-1",
|
||||
"product": "Example Run",
|
||||
"resource_type": "example_run_service",
|
||||
},
|
||||
{
|
||||
"id": "E-2",
|
||||
"name": "Ingress identity",
|
||||
"product": "Example IAM",
|
||||
"resource_type": "example_service_account",
|
||||
},
|
||||
],
|
||||
"relationships": [
|
||||
{"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"}
|
||||
],
|
||||
"checks": [
|
||||
{
|
||||
"id": "K-1",
|
||||
"applies_to": "E-1",
|
||||
"statement": "The service runs at least two instances.",
|
||||
"source": "NFR-1",
|
||||
},
|
||||
{
|
||||
"id": "K-2",
|
||||
"applies_to": "E-2",
|
||||
"statement": "The identity is used by this service only.",
|
||||
"source": "DR-1",
|
||||
},
|
||||
],
|
||||
}
|
||||
),
|
||||
"implementation.json": json.dumps(
|
||||
[
|
||||
{"check": "K-1", "file": "terraform/main.tf", "address": "example.run"},
|
||||
{"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"},
|
||||
]
|
||||
),
|
||||
"verdicts.json": json.dumps(
|
||||
{
|
||||
"dry_run": {"verdict": "pass", "evidence": "terraform validate passed."},
|
||||
"checks": [
|
||||
{"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."},
|
||||
{"check": "K-2", "verdict": "pass", "evidence": "One binding."},
|
||||
],
|
||||
"proposed_additions": [],
|
||||
}
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def sample_submission(kind: DeliverableKind, note: str = "") -> Call:
|
||||
"""A `submit_deliverable` call that meets the Deliverable's contract."""
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
parts = [f"# {kind}", note or "Summary."]
|
||||
parts += [f"## {section}\n{note or 'Details.'}" for section in spec.sections]
|
||||
attachments = {
|
||||
name: SAMPLE_DATA.get(name, f"# {name}\n") for name in spec.attachments
|
||||
}
|
||||
return Call(
|
||||
"submit_deliverable",
|
||||
{"content": "\n".join(parts) + "\n", "attachments": attachments},
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RunRecord:
|
||||
role: str
|
||||
|
||||
@@ -6,7 +6,17 @@ a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
import asyncio
|
||||
import contextvars
|
||||
from collections.abc import (
|
||||
AsyncIterator,
|
||||
Awaitable,
|
||||
Callable,
|
||||
Mapping,
|
||||
MutableMapping,
|
||||
Sequence,
|
||||
)
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Protocol
|
||||
|
||||
@@ -47,10 +57,15 @@ class Submitted:
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NeedsInput:
|
||||
"""The agent can't continue without the user. `permission` names a tool tier to grant."""
|
||||
"""The agent can't continue without the user. `permission` names a tool tier to grant.
|
||||
|
||||
`draft` is work the agent wants back when it is started again with the answers.
|
||||
"""
|
||||
|
||||
questions: tuple[str, ...]
|
||||
permission: str | None = None
|
||||
draft: str | None = None
|
||||
draft_attachments: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -127,8 +142,62 @@ 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]]
|
||||
# The tools a role gets beyond the Execution tools, given the Deliverable it is producing
|
||||
# and that Deliverable's working memory: JSON-compatible data a tool may read and write,
|
||||
# kept with the Execution across attempts.
|
||||
ToolFactory = Callable[
|
||||
[RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec]
|
||||
]
|
||||
|
||||
|
||||
class RunLimiter:
|
||||
"""Caps how many agent runs are in flight at once.
|
||||
|
||||
A run that fans out to further runs lends its slot while it waits, so the cap
|
||||
holds across the whole hierarchy and a cap of 1 cannot deadlock.
|
||||
"""
|
||||
|
||||
def __init__(self, limit: int) -> None:
|
||||
if limit < 1:
|
||||
raise ValueError("limit must be at least 1")
|
||||
self.limit = limit
|
||||
self._semaphore = asyncio.Semaphore(limit)
|
||||
self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar(
|
||||
"run_limiter_holding", default=False
|
||||
)
|
||||
|
||||
@asynccontextmanager
|
||||
async def slot(self) -> AsyncIterator[None]:
|
||||
async with self._semaphore:
|
||||
token = self._holding.set(True)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
|
||||
@asynccontextmanager
|
||||
async def lend(self) -> AsyncIterator[None]:
|
||||
"""Give up the caller's slot, if it holds one, while its own fan-out runs."""
|
||||
if not self._holding.get():
|
||||
yield
|
||||
return
|
||||
self._semaphore.release()
|
||||
token = self._holding.set(False)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
self._holding.reset(token)
|
||||
await self._semaphore.acquire()
|
||||
|
||||
|
||||
# Tool replies that mean the call did nothing. Runtimes log them, and the Execution
|
||||
# keeps them as lesson candidates.
|
||||
REJECTION_PREFIXES = (
|
||||
"Not submitted",
|
||||
"Refused",
|
||||
"Discovery gap",
|
||||
"terraform validate failed",
|
||||
)
|
||||
|
||||
|
||||
class AgentRuntime(Protocol):
|
||||
|
||||
36
app/agent.py
36
app/agent.py
@@ -22,11 +22,14 @@ from langgraph.checkpoint.base import BaseCheckpointSaver
|
||||
from langgraph.types import Command
|
||||
|
||||
from app.adk.roles import load_roles
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
|
||||
from app.checkpointing import open_checkpointer
|
||||
from app.config import Settings
|
||||
from app.customer_case import record_intent
|
||||
from app.providers import ProviderBundle, load_provider
|
||||
from app.recorder import DatabaseRecorder, ExecutionRecorder
|
||||
from app.skills.agent_skills import skill_version
|
||||
from app.states.execution_state import check_customer_case
|
||||
from app.states.ledger import Ledger
|
||||
from app.tools.execution import ORCHESTRATOR
|
||||
from app.tools.local import TerraformRunner, local_tools
|
||||
@@ -62,6 +65,8 @@ class ExecutionEngine:
|
||||
max_revisions: int = 3,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
@@ -71,6 +76,7 @@ class ExecutionEngine:
|
||||
if missing:
|
||||
raise ValueError(f"Missing roles: {', '.join(missing)}")
|
||||
self._max_revisions = max_revisions
|
||||
self._output_root = output_root
|
||||
self._graph = build_execution_graph(
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
@@ -78,6 +84,8 @@ class ExecutionEngine:
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
@@ -85,6 +93,7 @@ class ExecutionEngine:
|
||||
workflow_request: str,
|
||||
*,
|
||||
session_id: str | None = None,
|
||||
customer_case: str | None = None,
|
||||
pre_approved: bool = False,
|
||||
allow_cloud_read: bool | None = None,
|
||||
execution_id: str | None = None,
|
||||
@@ -92,14 +101,25 @@ class ExecutionEngine:
|
||||
) -> Interaction:
|
||||
"""Start an Execution. `scripted_answers` are (regex, answer) pairs a
|
||||
pre-approved Execution uses to answer questions, for evaluation runs."""
|
||||
customer_case = check_customer_case(customer_case)
|
||||
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
|
||||
session_id = session_id or str(uuid.uuid4())
|
||||
intent_version = record_intent(
|
||||
self._output_root,
|
||||
customer_case,
|
||||
execution_id=execution_id,
|
||||
session_id=session_id,
|
||||
workflow_request=workflow_request,
|
||||
)
|
||||
initial: dict[str, Any] = {
|
||||
"execution_id": execution_id,
|
||||
"session_id": session_id or str(uuid.uuid4()),
|
||||
"session_id": session_id,
|
||||
"customer_case": customer_case,
|
||||
"intent_version": intent_version,
|
||||
"workflow_request": workflow_request,
|
||||
"pre_approved": pre_approved,
|
||||
"allow_cloud_read": allow_cloud_read,
|
||||
@@ -112,9 +132,12 @@ class ExecutionEngine:
|
||||
"pending_questions": [],
|
||||
"awaiting_questions": [],
|
||||
"answers": {},
|
||||
"drafts": {},
|
||||
"working": {},
|
||||
"pending_permission": None,
|
||||
"prompt": None,
|
||||
"outcomes": [],
|
||||
"refusals": [],
|
||||
"outcomes_applied": 0,
|
||||
"events_recorded": 0,
|
||||
"turns": 0,
|
||||
@@ -218,15 +241,18 @@ async def open_assembly(
|
||||
runner = TerraformRunner(
|
||||
binary=settings.TERRAFORM_BINARY,
|
||||
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
|
||||
plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR,
|
||||
plugin_cache_dir=settings.terraform_plugin_cache(),
|
||||
)
|
||||
offered = [name for names in bundle.tools.values() for name in names]
|
||||
# One cap for Specialists and the pillar advisors they fan out to.
|
||||
limiter = RunLimiter(settings.MAX_PARALLEL_SPECIALISTS)
|
||||
tool_factory = make_tool_factory(
|
||||
runtime,
|
||||
roles,
|
||||
bundle.pillar_skills,
|
||||
local_tools=local_tools(offered, runner),
|
||||
catalog=catalog,
|
||||
limiter=limiter,
|
||||
)
|
||||
|
||||
async with open_checkpointer(settings) as checkpointer:
|
||||
@@ -239,5 +265,9 @@ async def open_assembly(
|
||||
max_revisions=settings.MAX_REVISIONS,
|
||||
max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS,
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions={
|
||||
name: skill_version(meta.path) for name, meta in bundle.skills.items()
|
||||
},
|
||||
)
|
||||
yield Assembly(engine, bundle, roles, dict(catalog.gaps))
|
||||
|
||||
@@ -38,7 +38,9 @@ class Settings(BaseSettings):
|
||||
# Local Terraform tools (fmt, validate, plan; never apply)
|
||||
TERRAFORM_BINARY: str = "terraform"
|
||||
TERRAFORM_TIMEOUT_SECONDS: float = 300
|
||||
TF_PLUGIN_CACHE_DIR: str | None = None
|
||||
# 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
|
||||
@@ -51,12 +53,21 @@ class Settings(BaseSettings):
|
||||
SPECIALIST_BUDGET: int = 15
|
||||
MAX_REVISIONS: int = 3
|
||||
MAX_ORCHESTRATOR_TURNS: int = 100
|
||||
# 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"
|
||||
|
||||
# Paths
|
||||
BASE_DIR: Path = Path(__file__).resolve().parent.parent
|
||||
|
||||
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:
|
||||
|
||||
105
app/customer_case.py
Normal file
105
app/customer_case.py
Normal file
@@ -0,0 +1,105 @@
|
||||
"""A Customer case on disk: its intent and the history of that intent.
|
||||
|
||||
deliverables/cases/<customer_case>/
|
||||
intent/
|
||||
001.md, 002.md, ... each statement of what the customer wants, as given
|
||||
history.json every statement in order, the Execution it started
|
||||
and how that Execution ended
|
||||
executions/<execution_id>/ what was generated for one statement
|
||||
|
||||
The intent is recorded when an Execution starts, so a request is on record even if
|
||||
nothing was delivered for it. history.json is the index of the case.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from app.states.execution_state import case_dir
|
||||
|
||||
INTENT_DIR = "intent"
|
||||
HISTORY_FILENAME = "history.json"
|
||||
IN_PROGRESS = "in_progress"
|
||||
|
||||
|
||||
def intent_dir(output_root: Path, customer_case: str) -> Path:
|
||||
return case_dir(output_root, customer_case) / INTENT_DIR
|
||||
|
||||
|
||||
def read_history(output_root: Path, customer_case: str) -> dict[str, Any]:
|
||||
"""The case's intent history; empty when the case has none yet."""
|
||||
path = intent_dir(output_root, customer_case) / HISTORY_FILENAME
|
||||
if path.is_file():
|
||||
try:
|
||||
history = json.loads(path.read_text(encoding="utf-8"))
|
||||
if isinstance(history, dict) and isinstance(history.get("intents"), list):
|
||||
return history
|
||||
except ValueError:
|
||||
pass
|
||||
return {"customer_case": customer_case, "intents": []}
|
||||
|
||||
|
||||
def record_intent(
|
||||
output_root: Path,
|
||||
customer_case: str,
|
||||
*,
|
||||
execution_id: str,
|
||||
session_id: str,
|
||||
workflow_request: str,
|
||||
) -> int:
|
||||
"""Record a new statement of the customer's intent and return its version."""
|
||||
folder = intent_dir(output_root, customer_case)
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
history = read_history(output_root, customer_case)
|
||||
version = max((item["version"] for item in history["intents"]), default=0) + 1
|
||||
recorded_at = datetime.now(UTC).isoformat(timespec="seconds")
|
||||
statement = f"{version:03d}.md"
|
||||
(folder / statement).write_text(
|
||||
f"# Intent {version}: {customer_case}\n\n"
|
||||
f"- Recorded: {recorded_at}\n"
|
||||
f"- Execution: `{execution_id}`\n\n"
|
||||
f"## What the customer wants\n\n{workflow_request.strip()}\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
history["intents"].append(
|
||||
{
|
||||
"version": version,
|
||||
"recorded_at": recorded_at,
|
||||
"statement": f"{INTENT_DIR}/{statement}",
|
||||
"workflow_request": workflow_request,
|
||||
"execution_id": execution_id,
|
||||
"session_id": session_id,
|
||||
"status": IN_PROGRESS,
|
||||
"execution": None,
|
||||
}
|
||||
)
|
||||
_write_history(folder, history)
|
||||
return version
|
||||
|
||||
|
||||
def close_intent(
|
||||
output_root: Path,
|
||||
customer_case: str,
|
||||
*,
|
||||
execution_id: str,
|
||||
status: str,
|
||||
has_files: bool,
|
||||
) -> None:
|
||||
"""Record how the Execution started by an intent ended, and where its files are."""
|
||||
history = read_history(output_root, customer_case)
|
||||
for item in history["intents"]:
|
||||
if item.get("execution_id") == execution_id:
|
||||
item["status"] = status
|
||||
item["execution"] = f"executions/{execution_id}" if has_files else None
|
||||
_write_history(intent_dir(output_root, customer_case), history)
|
||||
return
|
||||
|
||||
|
||||
def _write_history(folder: Path, history: dict[str, Any]) -> None:
|
||||
folder.mkdir(parents=True, exist_ok=True)
|
||||
(folder / HISTORY_FILENAME).write_text(
|
||||
json.dumps(history, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
|
||||
)
|
||||
@@ -68,9 +68,12 @@ def create_app(
|
||||
interaction = await assembly.engine.start(
|
||||
workflow_request,
|
||||
session_id=body.get("session_id"),
|
||||
customer_case=body.get("customer_case"),
|
||||
pre_approved=True,
|
||||
allow_cloud_read=bool(body.get("allow_cloud_read", False)),
|
||||
)
|
||||
except ValueError as exc:
|
||||
return JSONResponse({"error": str(exc)}, status_code=400)
|
||||
except Exception as exc:
|
||||
logger.exception("/generate failed")
|
||||
return JSONResponse(
|
||||
|
||||
@@ -6,10 +6,12 @@ append outcomes that the next Orchestrator turn applies in order.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
@@ -17,22 +19,32 @@ from typing import Any
|
||||
from langgraph.types import Command, Send, interrupt
|
||||
|
||||
from app.adk.runtime import (
|
||||
REJECTION_PREFIXES,
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
BudgetExhausted,
|
||||
NeedsInput,
|
||||
Outcome,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
Stopped,
|
||||
Submitted,
|
||||
ToolFactory,
|
||||
ToolSpec,
|
||||
TurnEnded,
|
||||
)
|
||||
from app.customer_case import close_intent
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
from app.states.execution_state import (
|
||||
UNASSIGNED_CASE,
|
||||
ExecutionState,
|
||||
execution_dir,
|
||||
lessons_file,
|
||||
)
|
||||
from app.states.ledger import Ledger, LedgerRefusal
|
||||
from app.states.lessons import collect_lesson_candidates, refusal
|
||||
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
||||
from app.workflows.chain import VERDICTS_FILE, validation_outcome
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
@@ -47,9 +59,12 @@ NO_USER_REPLY = (
|
||||
"'Assumptions', and proceed."
|
||||
)
|
||||
GUIDE_FILENAME = "solution-architecture-guide.md"
|
||||
MANIFEST_FILENAME = "execution.json" # request, status and files of one Execution
|
||||
|
||||
|
||||
def _no_tools(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
def _no_tools(
|
||||
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
|
||||
) -> Sequence[ToolSpec]:
|
||||
return ()
|
||||
|
||||
|
||||
@@ -73,9 +88,42 @@ def make_execution_nodes(
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
) -> ExecutionNodes:
|
||||
tool_factory = tool_factory or _no_tools
|
||||
|
||||
def close(state: ExecutionState, status: str, *, has_files: bool) -> None:
|
||||
close_intent(
|
||||
output_root,
|
||||
_case(state),
|
||||
execution_id=state["execution_id"],
|
||||
status=status,
|
||||
has_files=has_files,
|
||||
)
|
||||
|
||||
async def record_lessons(
|
||||
state: ExecutionState, ledger: Ledger, status: str
|
||||
) -> None:
|
||||
record = collect_lesson_candidates(
|
||||
execution_id=state["execution_id"],
|
||||
customer_case=_case(state),
|
||||
status=status,
|
||||
ledger=ledger,
|
||||
outcomes=state.get("outcomes", []),
|
||||
orchestrator_refusals=state.get("refusals", []),
|
||||
role_skills={name: role.skills for name, role in roles.items()},
|
||||
skill_versions=skill_versions or {},
|
||||
)
|
||||
# Kept apart from deliverables/: an Execution that ends with warnings writes
|
||||
# no Deliverable files, but what went wrong in it is still worth keeping.
|
||||
path = lessons_file(output_root, state["execution_id"], _case(state))
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(
|
||||
json.dumps(record, indent=2, ensure_ascii=False), encoding="utf-8"
|
||||
)
|
||||
await recorder.record_lesson_candidates(state["execution_id"], record)
|
||||
|
||||
async def record_progress(
|
||||
state: ExecutionState, ledger: Ledger, status: str | None = None
|
||||
) -> int:
|
||||
@@ -102,6 +150,7 @@ def make_execution_nodes(
|
||||
ledger.revisions(kind) for kind in DEPENDENCY_GRAPH
|
||||
),
|
||||
"warnings": state.get("warnings", []),
|
||||
"customer_case": _case(state),
|
||||
},
|
||||
)
|
||||
return len(ledger.events)
|
||||
@@ -113,6 +162,7 @@ def make_execution_nodes(
|
||||
notes = list(state.get("notes", []))
|
||||
pending_permission = state.get("pending_permission")
|
||||
warnings = list(state.get("warnings", []))
|
||||
drafts = dict(state.get("drafts", {}))
|
||||
|
||||
outcomes = state.get("outcomes", [])
|
||||
for record in outcomes[state.get("outcomes_applied", 0) :]:
|
||||
@@ -124,6 +174,7 @@ def make_execution_nodes(
|
||||
"content": record["content"],
|
||||
"attachments": record["attachments"],
|
||||
}
|
||||
drafts.pop(kind.value, None)
|
||||
await recorder.record_submission(
|
||||
state["execution_id"],
|
||||
kind.value,
|
||||
@@ -143,6 +194,11 @@ def make_execution_nodes(
|
||||
"requested_by": [*requested, kind.value],
|
||||
}
|
||||
continue
|
||||
if record.get("draft"):
|
||||
drafts[kind.value] = {
|
||||
"content": record["draft"],
|
||||
"attachments": record.get("draft_attachments", {}),
|
||||
}
|
||||
questions = record.get("questions") or [
|
||||
(
|
||||
f"The {record['role']} stopped: {record['summary']} "
|
||||
@@ -154,6 +210,7 @@ def make_execution_nodes(
|
||||
turns = state.get("turns", 0) + 1
|
||||
update: dict[str, Any] = {
|
||||
"deliverables": deliverables,
|
||||
"drafts": drafts,
|
||||
"pending_questions": pending_questions,
|
||||
"pending_permission": pending_permission,
|
||||
"outcomes_applied": len(outcomes),
|
||||
@@ -180,13 +237,21 @@ def make_execution_nodes(
|
||||
return finish_with("end_with_warnings", warnings=warnings)
|
||||
|
||||
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
|
||||
refusals = list(state.get("refusals", []))
|
||||
update["refusals"] = refusals
|
||||
task = AgentTask(
|
||||
role=ORCHESTRATOR,
|
||||
prompt="Decide the next step for this Execution using your tools.",
|
||||
context=_orchestrator_context(state, ledger, pending_questions, notes),
|
||||
context=_orchestrator_context(
|
||||
state, ledger, deliverables, pending_questions, notes
|
||||
),
|
||||
)
|
||||
started = time.monotonic()
|
||||
outcome = await runtime.run(roles[ORCHESTRATOR], task, toolbox.tools())
|
||||
outcome = await runtime.run(
|
||||
roles[ORCHESTRATOR],
|
||||
task,
|
||||
_noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None),
|
||||
)
|
||||
logger.info(
|
||||
"[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s",
|
||||
state["execution_id"],
|
||||
@@ -209,7 +274,9 @@ def make_execution_nodes(
|
||||
sends = [
|
||||
Send(
|
||||
"specialist_task",
|
||||
_specialist_input(state, ledger, deliverables, kind, attempt),
|
||||
_specialist_input(
|
||||
state, ledger, deliverables, drafts, kind, attempt
|
||||
),
|
||||
)
|
||||
for kind, attempt in toolbox.started.items()
|
||||
]
|
||||
@@ -257,10 +324,18 @@ def make_execution_nodes(
|
||||
async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]:
|
||||
role = roles[task_input["role"]]
|
||||
kind = DeliverableKind(task_input["kind"])
|
||||
tools = specialist_tools(
|
||||
kind,
|
||||
extra=tool_factory(role, kind.value),
|
||||
allow_cloud_read=task_input["allow_cloud_read"],
|
||||
working: dict[str, Any] = dict(task_input.get("working") or {})
|
||||
refusals: list[dict[str, Any]] = []
|
||||
tools = _noting_refusals(
|
||||
specialist_tools(
|
||||
kind,
|
||||
extra=tool_factory(role, kind.value, working),
|
||||
allow_cloud_read=task_input["allow_cloud_read"],
|
||||
upstream=task_input["context"].get("dependencies"),
|
||||
),
|
||||
refusals,
|
||||
role.name,
|
||||
kind.value,
|
||||
)
|
||||
task = AgentTask(
|
||||
role=role.name,
|
||||
@@ -277,7 +352,11 @@ def make_execution_nodes(
|
||||
)
|
||||
started = time.monotonic()
|
||||
try:
|
||||
outcome: Outcome = await runtime.run(role, task, tools)
|
||||
if limiter:
|
||||
async with limiter.slot():
|
||||
outcome: Outcome = await runtime.run(role, task, tools)
|
||||
else:
|
||||
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}")
|
||||
@@ -291,14 +370,18 @@ def make_execution_nodes(
|
||||
)
|
||||
return {
|
||||
"outcomes": [
|
||||
_outcome_record(role.name, kind, task_input["attempt"], outcome)
|
||||
]
|
||||
{
|
||||
**_outcome_record(role.name, kind, task_input["attempt"], outcome),
|
||||
"refusals": refusals,
|
||||
}
|
||||
],
|
||||
"working": {kind.value: working},
|
||||
}
|
||||
|
||||
async def await_user(state: ExecutionState) -> Command:
|
||||
prompt = state["prompt"] or {}
|
||||
if state.get("pre_approved"):
|
||||
reply = _automatic_reply(prompt, state.get("scripted_answers", []))
|
||||
reply = automatic_reply(prompt, state.get("scripted_answers", []))
|
||||
else:
|
||||
reply = interrupt(prompt)
|
||||
|
||||
@@ -359,16 +442,17 @@ def make_execution_nodes(
|
||||
|
||||
async def finalize(state: ExecutionState) -> dict[str, Any]:
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
_write_outputs(
|
||||
output_root / "deliverables" / "executions" / state["execution_id"],
|
||||
state.get("deliverables", {}),
|
||||
)
|
||||
_write_outputs(output_root, state)
|
||||
close(state, "completed", has_files=True)
|
||||
await record_progress(state, ledger, "completed")
|
||||
await record_lessons(state, ledger, "completed")
|
||||
return {"status": "completed"}
|
||||
|
||||
async def end_with_warnings(state: ExecutionState) -> dict[str, Any]:
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
close(state, "completed_with_warnings", has_files=False)
|
||||
await record_progress(state, ledger, "completed_with_warnings")
|
||||
await record_lessons(state, ledger, "completed_with_warnings")
|
||||
return {"status": "completed_with_warnings"}
|
||||
|
||||
return ExecutionNodes(
|
||||
@@ -383,6 +467,28 @@ def make_execution_nodes(
|
||||
# --- helpers ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _noting_refusals(
|
||||
tools: Sequence[ToolSpec],
|
||||
sink: list[dict[str, Any]],
|
||||
role: str,
|
||||
deliverable: str | None,
|
||||
) -> list[ToolSpec]:
|
||||
"""The same tools, noting each reply that means the call did nothing."""
|
||||
|
||||
def noting(tool: ToolSpec) -> ToolSpec:
|
||||
async def handler(**kwargs: Any) -> Any:
|
||||
result = await tool.handler(**kwargs)
|
||||
if result.outcome is None and result.message.startswith(REJECTION_PREFIXES):
|
||||
sink.append(
|
||||
refusal(role, deliverable, tool.name, tool.tier, result.message)
|
||||
)
|
||||
return result
|
||||
|
||||
return dataclasses.replace(tool, handler=handler)
|
||||
|
||||
return [noting(tool) for tool in tools]
|
||||
|
||||
|
||||
def _summarise_outcome(outcome: Outcome) -> str:
|
||||
if isinstance(outcome, TurnEnded):
|
||||
return f"called {outcome.tool}"
|
||||
@@ -405,10 +511,19 @@ def _current_phase(ledger: Ledger) -> str:
|
||||
def _orchestrator_context(
|
||||
state: ExecutionState,
|
||||
ledger: Ledger,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
pending_questions: Sequence[Mapping[str, Any]],
|
||||
notes: Sequence[str],
|
||||
) -> dict[str, Any]:
|
||||
validation = deliverables.get(DeliverableKind.VALIDATION_RESULTS.value)
|
||||
return {
|
||||
# The verdict on each Check, once validation is submitted: failed Checks are
|
||||
# faults in the code; the rest are gaps in the Target architecture.
|
||||
"validation": validation_outcome(
|
||||
validation.get("attachments", {}).get(VERDICTS_FILE, "")
|
||||
)
|
||||
if validation
|
||||
else None,
|
||||
"workflow_request": state["workflow_request"],
|
||||
"pre_approved": bool(state.get("pre_approved")),
|
||||
"allow_cloud_read": state.get("allow_cloud_read"),
|
||||
@@ -438,6 +553,7 @@ def _specialist_input(
|
||||
state: ExecutionState,
|
||||
ledger: Ledger,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
drafts: Mapping[str, Mapping[str, Any]],
|
||||
kind: DeliverableKind,
|
||||
attempt: int,
|
||||
) -> dict[str, Any]:
|
||||
@@ -448,15 +564,18 @@ def _specialist_input(
|
||||
"kind": kind.value,
|
||||
"attempt": attempt,
|
||||
"allow_cloud_read": state.get("allow_cloud_read"),
|
||||
"working": dict(state.get("working", {}).get(kind.value, {})),
|
||||
"context": {
|
||||
"workflow_request": state["workflow_request"],
|
||||
"pre_approved": bool(state.get("pre_approved")),
|
||||
"contract": spec.contract(),
|
||||
"dependencies": {
|
||||
dependency.value: dict(deliverables[dependency.value])
|
||||
for dependency in inputs_of(kind)
|
||||
},
|
||||
"feedback": list(ledger.feedback(kind)),
|
||||
"answers": list(state.get("answers", {}).get(kind.value, [])),
|
||||
"draft": dict(drafts[kind.value]) if kind.value in drafts else None,
|
||||
"attempt": attempt,
|
||||
},
|
||||
}
|
||||
@@ -479,6 +598,8 @@ def _outcome_record(
|
||||
"type": "needs_input",
|
||||
"questions": list(outcome.questions),
|
||||
"permission": outcome.permission,
|
||||
"draft": outcome.draft,
|
||||
"draft_attachments": dict(outcome.draft_attachments),
|
||||
}
|
||||
if isinstance(outcome, BudgetExhausted):
|
||||
return {**base, "type": "budget_exhausted", "summary": outcome.summary}
|
||||
@@ -495,7 +616,7 @@ def _describe_unfinished(outcome: Outcome) -> str:
|
||||
return f"Ended with an unexpected outcome: {type(outcome).__name__}."
|
||||
|
||||
|
||||
def _automatic_reply(
|
||||
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
|
||||
@@ -543,18 +664,44 @@ def _render_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
return "\n".join(item["question"] for item in prompt.get("questions", []))
|
||||
|
||||
|
||||
def _write_outputs(
|
||||
out_dir: Path, deliverables: Mapping[str, Mapping[str, Any]]
|
||||
) -> None:
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
def _case(state: ExecutionState) -> str:
|
||||
return state.get("customer_case") or UNASSIGNED_CASE
|
||||
|
||||
|
||||
def _write_outputs(output_root: Path, state: ExecutionState) -> None:
|
||||
"""Write a finished Execution's files under its Customer case, with a manifest
|
||||
that ties the request to what was generated for it."""
|
||||
customer_case = _case(state)
|
||||
execution_id = state["execution_id"]
|
||||
out_dir = execution_dir(output_root, execution_id, customer_case)
|
||||
deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {})
|
||||
files: dict[str, str] = {}
|
||||
by_kind: dict[str, dict[str, Any]] = {}
|
||||
guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value)
|
||||
if guide:
|
||||
(out_dir / GUIDE_FILENAME).write_text(guide["content"], encoding="utf-8")
|
||||
files[GUIDE_FILENAME] = guide["content"]
|
||||
for kind, deliverable in deliverables.items():
|
||||
path = out_dir / "deliverables" / f"{kind}.md"
|
||||
document = f"deliverables/{kind}.md"
|
||||
files[document] = deliverable["content"]
|
||||
attachments = dict(deliverable.get("attachments", {}))
|
||||
files.update(attachments)
|
||||
by_kind[kind] = {"document": document, "attachments": sorted(attachments)}
|
||||
for name, content in files.items():
|
||||
path = out_dir / name
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(deliverable["content"], encoding="utf-8")
|
||||
for name, content in deliverable.get("attachments", {}).items():
|
||||
attachment = out_dir / name
|
||||
attachment.parent.mkdir(parents=True, exist_ok=True)
|
||||
attachment.write_text(content, encoding="utf-8")
|
||||
path.write_text(content, encoding="utf-8")
|
||||
|
||||
manifest = {
|
||||
"customer_case": customer_case,
|
||||
"execution_id": execution_id,
|
||||
"session_id": state.get("session_id"),
|
||||
"intent_version": state.get("intent_version"),
|
||||
"workflow_request": state["workflow_request"],
|
||||
"status": "completed",
|
||||
"solution_guide": GUIDE_FILENAME if guide else None,
|
||||
"deliverables": by_kind,
|
||||
}
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
(out_dir / MANIFEST_FILENAME).write_text(
|
||||
json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8"
|
||||
)
|
||||
|
||||
@@ -27,6 +27,7 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
return (
|
||||
f"Please review the {approval['phase']} Phase: {approval['summary']}\n\n"
|
||||
f"Deliverables: {', '.join(approval['deliverables'])}.\n\n"
|
||||
f"{_describe_target_architecture(approval.get('target_architecture'))}"
|
||||
f"To approve, reply with the data {json.dumps(reply)}. "
|
||||
f"To request changes, reply with {json.dumps(changes)}. "
|
||||
"A text reply is recorded as conversation and never approves."
|
||||
@@ -46,6 +47,24 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
return "\n".join(lines) + "\n\nReply in text; answer every question you can."
|
||||
|
||||
|
||||
def _describe_target_architecture(summary: Mapping[str, Any] | None) -> str:
|
||||
"""What the design Approval commits to: no code is written until it is granted."""
|
||||
if not summary:
|
||||
return ""
|
||||
text = (
|
||||
f"The Target architecture has {summary['elements']} Elements, "
|
||||
f"{summary['relationships']} Relationships and {summary['checks']} Checks. "
|
||||
"No infrastructure code is written until you approve it; the code is then "
|
||||
"validated against those Checks.\n\n"
|
||||
)
|
||||
for item in summary.get("not_applicable", []):
|
||||
text += (
|
||||
f"Recommendation {item['recommendation']} is treated as not applicable: "
|
||||
f"{item['reason']}\n"
|
||||
)
|
||||
return text + ("\n" if summary.get("not_applicable") else "")
|
||||
|
||||
|
||||
def to_generate_response(
|
||||
interaction: Interaction, roles: Mapping[str, RoleSpec]
|
||||
) -> dict[str, Any]:
|
||||
@@ -86,7 +105,7 @@ def to_generate_response(
|
||||
"requirements_doc": requirements,
|
||||
"architecture_doc": content(DeliverableKind.ARCHITECTURE_DESCRIPTION),
|
||||
"mermaid_diagram": attachment(
|
||||
DeliverableKind.ARCHITECTURE_DIAGRAM, "architecture.mmd"
|
||||
DeliverableKind.TARGET_ARCHITECTURE, "architecture.mmd"
|
||||
),
|
||||
"terraform_code": attachment(
|
||||
DeliverableKind.DEPLOYMENT_GUIDANCE, "terraform/main.tf"
|
||||
|
||||
@@ -8,6 +8,7 @@ Execution store (review candidate 03) replaces them.
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import uuid
|
||||
from collections import defaultdict
|
||||
from collections.abc import Mapping, Sequence
|
||||
@@ -42,12 +43,22 @@ class ExecutionRecorder(Protocol):
|
||||
details: Mapping[str, Any],
|
||||
) -> None: ...
|
||||
|
||||
async def record_lesson_candidates(
|
||||
self, execution_id: str, record: Mapping[str, Any]
|
||||
) -> None: ...
|
||||
|
||||
|
||||
class InMemoryRecorder:
|
||||
def __init__(self) -> None:
|
||||
self.events: dict[str, list[LedgerEvent]] = defaultdict(list)
|
||||
self.submissions: dict[str, list[dict[str, Any]]] = defaultdict(list)
|
||||
self.statuses: dict[str, list[dict[str, Any]]] = defaultdict(list)
|
||||
self.lessons: dict[str, dict[str, Any]] = {}
|
||||
|
||||
async def record_lesson_candidates(
|
||||
self, execution_id: str, record: Mapping[str, Any]
|
||||
) -> None:
|
||||
self.lessons[execution_id] = dict(record)
|
||||
|
||||
async def record_events(
|
||||
self, execution_id: str, events: Sequence[LedgerEvent]
|
||||
@@ -154,3 +165,15 @@ class DatabaseRecorder:
|
||||
agent_name=SESSION_AGENT_NAME,
|
||||
state_data={"latest_execution_id": execution_id, "status": status},
|
||||
)
|
||||
|
||||
async def record_lesson_candidates(
|
||||
self, execution_id: str, record: Mapping[str, Any]
|
||||
) -> None:
|
||||
await asyncio.to_thread(
|
||||
self._db.save_artifact,
|
||||
artifact_id=str(uuid.uuid4()),
|
||||
execution_id=execution_id,
|
||||
artifact_type="lesson_candidates",
|
||||
file_path="lesson-candidates.json",
|
||||
content=json.dumps(dict(record), ensure_ascii=False),
|
||||
)
|
||||
|
||||
@@ -6,6 +6,7 @@ Agent Skills specification (https://agentskills.io/specification).
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import re
|
||||
from collections.abc import Iterable
|
||||
from dataclasses import dataclass
|
||||
@@ -123,6 +124,15 @@ def read_skill(skill_dir: Path) -> SkillMeta:
|
||||
return SkillMeta(name=name, description=description, path=skill_dir)
|
||||
|
||||
|
||||
def skill_version(skill_dir: Path) -> str:
|
||||
"""A short content hash of every file in the Skill, to say which Skill was loaded."""
|
||||
digest = hashlib.sha256()
|
||||
for path in sorted(p for p in skill_dir.rglob("*") if p.is_file()):
|
||||
digest.update(path.relative_to(skill_dir).as_posix().encode())
|
||||
digest.update(path.read_bytes())
|
||||
return digest.hexdigest()[:12]
|
||||
|
||||
|
||||
def discover_skills(directories: Iterable[Path]) -> dict[str, SkillMeta]:
|
||||
"""Index every Skill that is an immediate child of one of `directories`.
|
||||
|
||||
|
||||
@@ -3,12 +3,58 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import operator
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import Annotated, Any, TypedDict
|
||||
|
||||
# A Customer case id becomes a directory name, so it is a short lowercase slug.
|
||||
CUSTOMER_CASE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$")
|
||||
# Executions started without a Customer case are grouped here, so every Execution's
|
||||
# files sit under a case.
|
||||
UNASSIGNED_CASE = "unassigned"
|
||||
|
||||
|
||||
def check_customer_case(customer_case: object) -> str:
|
||||
"""The Customer case id, defaulting to UNASSIGNED_CASE; a ValueError when it is
|
||||
not a safe slug."""
|
||||
if customer_case is None:
|
||||
return UNASSIGNED_CASE
|
||||
if not isinstance(customer_case, str) or not CUSTOMER_CASE.match(customer_case):
|
||||
raise ValueError(
|
||||
"customer_case must be 1 to 64 lowercase letters, digits or hyphens, "
|
||||
f"starting and ending with a letter or digit; got {customer_case!r}"
|
||||
)
|
||||
return customer_case
|
||||
|
||||
|
||||
def case_dir(output_root: Path, customer_case: str) -> Path:
|
||||
"""Everything generated for one Customer case."""
|
||||
return output_root / "deliverables" / "cases" / customer_case
|
||||
|
||||
|
||||
def execution_dir(output_root: Path, execution_id: str, customer_case: str) -> Path:
|
||||
"""Where one Execution's files go, under its Customer case."""
|
||||
return case_dir(output_root, customer_case) / "executions" / execution_id
|
||||
|
||||
|
||||
def lessons_file(output_root: Path, execution_id: str, customer_case: str) -> Path:
|
||||
return (
|
||||
output_root / "lessons" / "candidates" / customer_case / f"{execution_id}.json"
|
||||
)
|
||||
|
||||
|
||||
def merge_by_key(
|
||||
current: dict[str, dict[str, Any]] | None, update: dict[str, dict[str, Any]] | None
|
||||
) -> dict[str, dict[str, Any]]:
|
||||
"""Parallel Specialist tasks each write their own Deliverable's entry."""
|
||||
return {**(current or {}), **(update or {})}
|
||||
|
||||
|
||||
class ExecutionState(TypedDict, total=False):
|
||||
execution_id: str
|
||||
session_id: str
|
||||
customer_case: str # the Customer case this Execution belongs to
|
||||
intent_version: int # which statement of the case's intent started this Execution
|
||||
workflow_request: str
|
||||
pre_approved: bool
|
||||
allow_cloud_read: bool | None
|
||||
@@ -21,6 +67,11 @@ class ExecutionState(TypedDict, total=False):
|
||||
pending_questions: list[dict[str, Any]] # {kind, questions} not yet asked
|
||||
awaiting_questions: list[dict[str, Any]] # {kind, questions} asked, not answered
|
||||
answers: dict[str, list[dict[str, Any]]] # kind -> [{questions, reply}]
|
||||
drafts: dict[
|
||||
str, dict[str, Any]
|
||||
] # kind -> {content, attachments} awaiting the user
|
||||
# kind -> working memory its tools keep across attempts (e.g. pillar advice)
|
||||
working: Annotated[dict[str, dict[str, Any]], merge_by_key]
|
||||
pending_permission: dict[str, Any] | None # {tier, requested_by}
|
||||
prompt: dict[str, Any] | None # what the user is being asked
|
||||
|
||||
@@ -28,6 +79,7 @@ class ExecutionState(TypedDict, total=False):
|
||||
# applied to the Ledger by the next Orchestrator turn.
|
||||
outcomes: Annotated[list[dict[str, Any]], operator.add]
|
||||
outcomes_applied: int
|
||||
refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls
|
||||
events_recorded: int
|
||||
|
||||
turns: int
|
||||
|
||||
125
app/states/lessons.py
Normal file
125
app/states/lessons.py
Normal file
@@ -0,0 +1,125 @@
|
||||
"""Lesson candidates: what went wrong in an Execution and what was asked to fix it.
|
||||
|
||||
Collected once, when the Execution ends, from what the Execution already holds: the
|
||||
Ledger's events, the Specialists' outcome records and the tool refusals. They are raw
|
||||
material for a reviewed change to a Skill, never memory carried into another Execution.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.states.ledger import Ledger
|
||||
from app.workflows.chain import VERDICTS_FILE, validation_outcome
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
DeliverableKind,
|
||||
PhaseId,
|
||||
)
|
||||
|
||||
MESSAGE_LIMIT = 500
|
||||
_UNFINISHED = {"budget_exhausted", "stopped"}
|
||||
|
||||
|
||||
def refusal(
|
||||
role: str, deliverable: str | None, tool: str, tier: str, message: str
|
||||
) -> dict[str, Any]:
|
||||
"""One tool refusal, as stored in Execution state.
|
||||
|
||||
A cloud-read tool's message may describe the user's environment, so only its
|
||||
leading words are kept.
|
||||
"""
|
||||
if tier == "cloud_read":
|
||||
message = message.split(":", 1)[0]
|
||||
return {
|
||||
"role": role,
|
||||
"deliverable": deliverable,
|
||||
"tool": tool,
|
||||
"message": message[:MESSAGE_LIMIT],
|
||||
}
|
||||
|
||||
|
||||
def collect_lesson_candidates(
|
||||
*,
|
||||
execution_id: str,
|
||||
customer_case: str,
|
||||
status: str,
|
||||
ledger: Ledger,
|
||||
outcomes: Sequence[Mapping[str, Any]],
|
||||
orchestrator_refusals: Sequence[Mapping[str, Any]],
|
||||
role_skills: Mapping[str, Sequence[str]],
|
||||
skill_versions: Mapping[str, str],
|
||||
) -> dict[str, Any]:
|
||||
candidates: list[dict[str, Any]] = []
|
||||
|
||||
for event in ledger.events:
|
||||
if event.type == "reopened":
|
||||
candidates.append(
|
||||
{
|
||||
"type": "revision",
|
||||
"deliverable": event.subject,
|
||||
"reason": event.detail,
|
||||
"requested_by": event.actor,
|
||||
}
|
||||
)
|
||||
elif event.type == "escalated":
|
||||
candidates.append(
|
||||
{
|
||||
"type": "revision_limit",
|
||||
"deliverable": event.subject,
|
||||
"reason": event.detail,
|
||||
}
|
||||
)
|
||||
elif event.type == "changes_requested":
|
||||
candidates.append(
|
||||
{
|
||||
"type": "change_request",
|
||||
"phase": event.subject,
|
||||
"deliverables": [
|
||||
kind.value
|
||||
for kind, spec in DEPENDENCY_GRAPH.items()
|
||||
if spec.phase is PhaseId(event.subject)
|
||||
],
|
||||
"feedback": event.detail,
|
||||
}
|
||||
)
|
||||
elif event.type == "released" and event.detail in _UNFINISHED:
|
||||
candidates.append(
|
||||
{
|
||||
"type": "unfinished",
|
||||
"deliverable": event.subject,
|
||||
"role": event.actor,
|
||||
"reason": event.detail,
|
||||
}
|
||||
)
|
||||
|
||||
for record in outcomes:
|
||||
for item in record.get("refusals", ()):
|
||||
candidates.append({"type": "refusal", **item})
|
||||
if (
|
||||
record.get("type") == "submitted"
|
||||
and record.get("kind") == DeliverableKind.VALIDATION_RESULTS.value
|
||||
):
|
||||
outcome = validation_outcome(
|
||||
record.get("attachments", {}).get(VERDICTS_FILE, "")
|
||||
)
|
||||
attempt = record.get("attempt")
|
||||
for kind, items in (
|
||||
("failed_check", outcome["failed"]),
|
||||
("unverifiable_check", outcome["not_verifiable"]),
|
||||
("proposed_addition", outcome["proposed_additions"]),
|
||||
):
|
||||
for item in items:
|
||||
candidates.append({"type": kind, "attempt": attempt, **item})
|
||||
for item in orchestrator_refusals:
|
||||
candidates.append({"type": "refusal", **item})
|
||||
|
||||
return {
|
||||
"execution_id": execution_id,
|
||||
"customer_case": customer_case,
|
||||
"status": status,
|
||||
"role_skills": {role: list(skills) for role, skills in role_skills.items()},
|
||||
"skill_versions": dict(skill_versions),
|
||||
"candidates": candidates,
|
||||
}
|
||||
@@ -28,8 +28,17 @@ from app.workflows.deliverables import (
|
||||
check_submission,
|
||||
deliverables_in,
|
||||
)
|
||||
from app.workflows.target_architecture import (
|
||||
DIAGRAM_ATTACHMENT,
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
TargetArchitecture,
|
||||
parse_graph,
|
||||
render_mermaid,
|
||||
)
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
_TARGET = DeliverableKind.TARGET_ARCHITECTURE
|
||||
CLOUD_READ = "cloud_read"
|
||||
|
||||
_NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}}
|
||||
@@ -186,10 +195,23 @@ class OrchestratorToolbox:
|
||||
"summary": summary,
|
||||
"deliverables": [kind.value for kind in deliverables_in(phase_id)],
|
||||
}
|
||||
graph = self._target_architecture()
|
||||
if graph and phase_id is DEPENDENCY_GRAPH[_TARGET].phase:
|
||||
# What the user is approving before any code is written.
|
||||
self.approval["target_architecture"] = graph.summary()
|
||||
return ToolResult(
|
||||
f"Asked the user to approve {phase_id}.", TurnEnded("request_approval")
|
||||
)
|
||||
|
||||
def _target_architecture(self) -> TargetArchitecture | None:
|
||||
deliverable = self._deliverables.get(_TARGET.value)
|
||||
if not deliverable:
|
||||
return None
|
||||
try:
|
||||
return parse_graph(deliverable.get("attachments", {})[GRAPH_ATTACHMENT])
|
||||
except (KeyError, GraphError):
|
||||
return None
|
||||
|
||||
async def reopen(self, kind: str, reason: str) -> ToolResult:
|
||||
try:
|
||||
result = self.ledger.reopen(
|
||||
@@ -231,8 +253,13 @@ def specialist_tools(
|
||||
kind: DeliverableKind,
|
||||
extra: Sequence[ToolSpec],
|
||||
allow_cloud_read: bool | None,
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None = None,
|
||||
) -> list[ToolSpec]:
|
||||
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate."""
|
||||
"""A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate.
|
||||
|
||||
`upstream` is the Deliverables this one builds on; with it, a submission's links
|
||||
along the Requirements chain are checked.
|
||||
"""
|
||||
|
||||
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
|
||||
try:
|
||||
@@ -245,18 +272,34 @@ def specialist_tools(
|
||||
"attachment names must be relative paths without '..': "
|
||||
+ ", ".join(unsafe)
|
||||
)
|
||||
missing = check_submission(kind, content, attachments)
|
||||
missing = check_submission(kind, content, attachments, upstream)
|
||||
if missing:
|
||||
return ToolResult(
|
||||
"Not submitted. The Deliverable is missing: " + "; ".join(missing)
|
||||
)
|
||||
if kind is DeliverableKind.TARGET_ARCHITECTURE:
|
||||
# The diagram is a view of the graph, so the engine draws it.
|
||||
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(
|
||||
parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
)
|
||||
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
|
||||
|
||||
async def needs_input(questions: Sequence[str]) -> ToolResult:
|
||||
async def needs_input(
|
||||
questions: Sequence[str], draft: str | None = None, attachments: Any = None
|
||||
) -> ToolResult:
|
||||
questions = tuple(q for q in questions if q)
|
||||
if not questions:
|
||||
return _refused("ask at least one question")
|
||||
return ToolResult("Questions sent to the user.", NeedsInput(questions))
|
||||
try:
|
||||
draft_attachments = files_from_argument(attachments)
|
||||
except TypeError as exc:
|
||||
return _refused(f"attachments: {exc}")
|
||||
return ToolResult(
|
||||
"Questions sent to the user.",
|
||||
NeedsInput(
|
||||
questions, draft=draft or None, draft_attachments=draft_attachments
|
||||
),
|
||||
)
|
||||
|
||||
return [
|
||||
ToolSpec(
|
||||
@@ -274,9 +317,15 @@ def specialist_tools(
|
||||
),
|
||||
ToolSpec(
|
||||
"needs_input",
|
||||
"Ask the user questions you can't proceed without. Ends your turn.",
|
||||
"Ask the user questions you can't proceed without. Ends your turn. When "
|
||||
"you are asking them to confirm a draft, pass it as `draft` (with its "
|
||||
"`attachments`): it is returned to you with their answers.",
|
||||
_schema(
|
||||
{"questions": {"type": "array", "items": {"type": "string"}}},
|
||||
{
|
||||
"questions": {"type": "array", "items": {"type": "string"}},
|
||||
"draft": {"type": "string"},
|
||||
"attachments": FILES_SCHEMA,
|
||||
},
|
||||
["questions"],
|
||||
),
|
||||
needs_input,
|
||||
|
||||
@@ -11,7 +11,7 @@ import os
|
||||
import re
|
||||
import tempfile
|
||||
from collections.abc import Awaitable, Callable, Iterable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
@@ -76,7 +76,11 @@ async def mermaid_check(diagram: str) -> ToolResult:
|
||||
class TerraformRunner:
|
||||
binary: str = "terraform"
|
||||
timeout_seconds: float = 300
|
||||
# Providers are downloaded here once and reused by every later check. Without it,
|
||||
# each validate or plan downloads its providers again into a scratch directory.
|
||||
plugin_cache_dir: str | None = None
|
||||
# Terraform's plugin cache is not safe for concurrent installs.
|
||||
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
|
||||
|
||||
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
|
||||
refusal = _check_files(files)
|
||||
@@ -147,9 +151,12 @@ class TerraformRunner:
|
||||
)
|
||||
|
||||
async def _init(self, root: Path) -> ToolResult | None:
|
||||
code, output = await self._run(
|
||||
[self.binary, "init", "-backend=false", "-input=false", "-no-color"], root
|
||||
)
|
||||
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
|
||||
if self.plugin_cache_dir:
|
||||
async with self._init_lock:
|
||||
code, output = await self._run(command, root)
|
||||
else:
|
||||
code, output = await self._run(command, root)
|
||||
if code != 0:
|
||||
return ToolResult(_clip(f"terraform init failed:\n{output}"))
|
||||
return None
|
||||
@@ -159,7 +166,12 @@ class TerraformRunner:
|
||||
) -> tuple[int, str]:
|
||||
environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})}
|
||||
if self.plugin_cache_dir:
|
||||
environment["TF_PLUGIN_CACHE_DIR"] = self.plugin_cache_dir
|
||||
cache = Path(self.plugin_cache_dir).expanduser().resolve()
|
||||
cache.mkdir(parents=True, exist_ok=True)
|
||||
environment["TF_PLUGIN_CACHE_DIR"] = str(cache)
|
||||
# Each check runs in a scratch directory with no dependency lock file.
|
||||
# Without this, Terraform downloads a cached provider again to verify it.
|
||||
environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true"
|
||||
try:
|
||||
process = await asyncio.create_subprocess_exec(
|
||||
*args,
|
||||
|
||||
@@ -1,25 +1,31 @@
|
||||
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
|
||||
|
||||
Pillar advice is working material for the design recommendations Deliverable, not a
|
||||
Deliverable itself, so it never touches the Ledger.
|
||||
Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's
|
||||
working memory, so a Revision re-consults only the pillars its feedback touches.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import dataclasses
|
||||
from collections.abc import Mapping, Sequence
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from contextlib import AsyncExitStack
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
CONSULT_TOOL = "consult_pillar_advisors"
|
||||
NO_GUIDANCE = "No guidance"
|
||||
ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given
|
||||
|
||||
|
||||
def pillar_consultation_tool(
|
||||
@@ -27,8 +33,22 @@ def pillar_consultation_tool(
|
||||
advisor: RoleSpec,
|
||||
pillar_skills: Mapping[str, str],
|
||||
extra_tools: Sequence[ToolSpec] = (),
|
||||
memory: MutableMapping[str, Any] | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
) -> ToolSpec:
|
||||
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill."""
|
||||
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill.
|
||||
|
||||
With `memory`, advice is remembered: naming `pillars` re-consults only those and
|
||||
returns the remembered advice for the rest.
|
||||
"""
|
||||
|
||||
async def advise(pillar: str, brief: str) -> str:
|
||||
async with AsyncExitStack() as stack:
|
||||
if limiter:
|
||||
await stack.enter_async_context(limiter.slot())
|
||||
return await _advise(
|
||||
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
||||
)
|
||||
|
||||
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
|
||||
chosen = list(pillars) if pillars else list(pillar_skills)
|
||||
@@ -38,20 +58,41 @@ def pillar_consultation_tool(
|
||||
f"Refused: unknown pillars {', '.join(unknown)}; "
|
||||
f"choose from {', '.join(pillar_skills)}"
|
||||
)
|
||||
results = await asyncio.gather(
|
||||
*(
|
||||
_advise(
|
||||
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
||||
async with AsyncExitStack() as stack:
|
||||
if limiter:
|
||||
# The calling Specialist only waits here, so its slot goes to advisors.
|
||||
await stack.enter_async_context(limiter.lend())
|
||||
fresh = dict(
|
||||
zip(
|
||||
chosen,
|
||||
await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)),
|
||||
)
|
||||
for pillar in chosen
|
||||
)
|
||||
remembered: dict[str, str] = (
|
||||
dict(memory.get(ADVICE_KEY, {})) if memory is not None else {}
|
||||
)
|
||||
return ToolResult("\n\n".join(results))
|
||||
sections = []
|
||||
for pillar in pillar_skills:
|
||||
if pillar in fresh:
|
||||
advice = fresh[pillar]
|
||||
if not advice.startswith(NO_GUIDANCE):
|
||||
remembered[pillar] = advice
|
||||
sections.append(f"## {pillar}\n\n{advice}")
|
||||
elif pillar in remembered:
|
||||
sections.append(
|
||||
f"## {pillar} (from your earlier consultation)\n\n"
|
||||
f"{remembered[pillar]}"
|
||||
)
|
||||
if memory is not None:
|
||||
memory[ADVICE_KEY] = remembered
|
||||
return ToolResult("\n\n".join(sections))
|
||||
|
||||
return ToolSpec(
|
||||
CONSULT_TOOL,
|
||||
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
|
||||
"Give a brief with the workload, its requirements and the selected products.",
|
||||
"Give a brief with the workload, its requirements and the selected products. "
|
||||
"Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult "
|
||||
"only those; advice already given for the others is returned unchanged.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -84,12 +125,10 @@ async def _advise(
|
||||
try:
|
||||
outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools])
|
||||
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
|
||||
return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})."
|
||||
return f"{NO_GUIDANCE}: the advisor failed ({exc})."
|
||||
if isinstance(outcome, Submitted):
|
||||
return f"## {pillar}\n\n{outcome.content.strip()}"
|
||||
return (
|
||||
f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}."
|
||||
)
|
||||
return outcome.content.strip()
|
||||
return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}."
|
||||
|
||||
|
||||
def _submit_advice_tool() -> ToolSpec:
|
||||
|
||||
@@ -7,10 +7,11 @@ Cloud-read gating is applied later, per Execution, by `specialist_tools`.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.adk.roles import PILLAR_ADVISOR
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory, ToolSpec
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory, ToolSpec
|
||||
from app.tools.mcp import McpCatalog
|
||||
from app.tools.pillars import pillar_consultation_tool
|
||||
from app.workflows.deliverables import DeliverableKind
|
||||
@@ -23,26 +24,41 @@ def make_tool_factory(
|
||||
*,
|
||||
local_tools: Sequence[ToolSpec] = (),
|
||||
catalog: McpCatalog | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
) -> ToolFactory:
|
||||
local_by_name = {tool.name: tool for tool in local_tools}
|
||||
|
||||
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
|
||||
return catalog.tools_for(role.mcp_servers) if catalog else []
|
||||
|
||||
consult = None
|
||||
advisor = roles.get(PILLAR_ADVISOR)
|
||||
if pillar_skills and advisor:
|
||||
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
||||
advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"]
|
||||
consult = pillar_consultation_tool(
|
||||
runtime, advisor, pillar_skills, extra_tools=advisor_tools
|
||||
)
|
||||
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
||||
advisor_tools = (
|
||||
[tool for tool in mcp_tools(advisor) if tool.tier == "general"]
|
||||
if advisor
|
||||
else []
|
||||
)
|
||||
|
||||
def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
|
||||
def tools_for(
|
||||
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
|
||||
) -> Sequence[ToolSpec]:
|
||||
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
|
||||
tools += mcp_tools(role)
|
||||
if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value:
|
||||
tools.append(consult)
|
||||
if (
|
||||
pillar_skills
|
||||
and advisor
|
||||
and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value
|
||||
):
|
||||
tools.append(
|
||||
pillar_consultation_tool(
|
||||
runtime,
|
||||
advisor,
|
||||
pillar_skills,
|
||||
extra_tools=advisor_tools,
|
||||
memory=working,
|
||||
limiter=limiter,
|
||||
)
|
||||
)
|
||||
return tools
|
||||
|
||||
return tools_for
|
||||
|
||||
336
app/workflows/chain.py
Normal file
336
app/workflows/chain.py
Normal file
@@ -0,0 +1,336 @@
|
||||
"""The data files along the Requirements chain, and what each must hold (ADR-0005).
|
||||
|
||||
requirements.json requirements with ids
|
||||
components.json components, and the requirements each serves
|
||||
products.json the product selected for each component
|
||||
recommendations.json design recommendations with ids
|
||||
target-architecture.json the graph (see target_architecture.py)
|
||||
implementation.json which code satisfies each Check
|
||||
verdicts.json the validation verdict on each Check
|
||||
|
||||
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
|
||||
and submit again. `upstream` is the Deliverables a submission builds on, by kind; a
|
||||
link to one of them is checked only when it is there.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.workflows.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
TargetArchitecture,
|
||||
chain_gaps,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
REQUIREMENTS_FILE = "requirements.json"
|
||||
COMPONENTS_FILE = "components.json"
|
||||
PRODUCTS_FILE = "products.json"
|
||||
RECOMMENDATIONS_FILE = "recommendations.json"
|
||||
IMPLEMENTATION_FILE = "implementation.json"
|
||||
VERDICTS_FILE = "verdicts.json"
|
||||
|
||||
REQUIREMENT_KINDS = ("functional", "non_functional")
|
||||
VERDICTS = ("pass", "fail", "not_verifiable")
|
||||
DRY_RUN_VERDICTS = ("pass", "fail", "not_run")
|
||||
|
||||
Upstream = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
||||
"""An upstream data file as a list of objects; empty when absent or unreadable."""
|
||||
text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "")
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return []
|
||||
return (
|
||||
[item for item in data if isinstance(item, dict)]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def read_graph(upstream: Upstream | None) -> TargetArchitecture | None:
|
||||
text = (
|
||||
((upstream or {}).get("target_architecture") or {})
|
||||
.get("attachments", {})
|
||||
.get(GRAPH_ATTACHMENT, "")
|
||||
)
|
||||
try:
|
||||
return parse_graph(text)
|
||||
except GraphError:
|
||||
return None
|
||||
|
||||
|
||||
def _objects(
|
||||
text: str, name: str, strings: Sequence[str], lists: Sequence[str] = ()
|
||||
) -> tuple[list[dict[str, Any]], list[str]]:
|
||||
"""The file's objects that have every required field, and what is wrong with it."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return [], [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, list):
|
||||
return [], [f"{name}: must be a JSON list"]
|
||||
accepted, problems = [], []
|
||||
for index, item in enumerate(data):
|
||||
where = f"{name}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where}: must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in strings
|
||||
if not isinstance(item.get(field), str) or not item[field].strip()
|
||||
]
|
||||
missing += [
|
||||
field
|
||||
for field in lists
|
||||
if not isinstance(item.get(field), list)
|
||||
or not all(isinstance(value, str) for value in item[field])
|
||||
]
|
||||
if missing:
|
||||
problems.append(f"{where}: needs {', '.join(missing)}")
|
||||
continue
|
||||
accepted.append(item)
|
||||
return accepted, problems
|
||||
|
||||
|
||||
def _repeated(
|
||||
items: Sequence[Mapping[str, Any]], name: str, key: str = "id"
|
||||
) -> list[str]:
|
||||
seen: set[str] = set()
|
||||
problems = []
|
||||
for item in items:
|
||||
if item[key] in seen:
|
||||
problems.append(f"{name}: {key} {item[key]} is used more than once")
|
||||
seen.add(item[key])
|
||||
return problems
|
||||
|
||||
|
||||
def check_requirements(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = REQUIREMENTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("id", "kind", "text"))
|
||||
problems += _repeated(items, name)
|
||||
problems += [
|
||||
f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}"
|
||||
for item in items
|
||||
if item["kind"] not in REQUIREMENT_KINDS
|
||||
]
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no requirements")
|
||||
return problems
|
||||
|
||||
|
||||
def check_components(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = COMPONENTS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "name"), ("requirements",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no components")
|
||||
requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE)
|
||||
if requirements:
|
||||
known = {item["id"] for item in requirements}
|
||||
served: set[str] = set()
|
||||
for item in items:
|
||||
served.update(item["requirements"])
|
||||
problems += [
|
||||
f"{name}: {item['id']} serves {reference}, which is not a requirement"
|
||||
for reference in item["requirements"]
|
||||
if reference not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: functional requirement {item['id']} is served by no component"
|
||||
for item in requirements
|
||||
if item.get("kind") == "functional" and item["id"] not in served
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_products(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = PRODUCTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("component", "product"))
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
chosen = {item["component"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {item['component']} is not a component"
|
||||
for item in items
|
||||
if item["component"] not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: component {identifier} has no product selected"
|
||||
for identifier in sorted(known - chosen)
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_recommendations(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = RECOMMENDATIONS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "pillar", "text"), ("components",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no recommendations")
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
problems += [
|
||||
f"{name}: {item['id']} names {reference}, which is not a component"
|
||||
for item in items
|
||||
for reference in item["components"]
|
||||
if reference not in known
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_target_architecture(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
try:
|
||||
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
except GraphError as exc:
|
||||
return list(exc.problems)
|
||||
if upstream is None:
|
||||
return []
|
||||
return list(
|
||||
chain_gaps(
|
||||
graph,
|
||||
requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE),
|
||||
components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE),
|
||||
products=read_list(upstream, "product_selection", PRODUCTS_FILE),
|
||||
recommendations=read_list(
|
||||
upstream, "design_recommendations", RECOMMENDATIONS_FILE
|
||||
),
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def _covers_every_check(
|
||||
items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None
|
||||
) -> list[str]:
|
||||
problems = _repeated(items, name, "check")
|
||||
if graph is None:
|
||||
return problems
|
||||
given = {item["check"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {identifier} is not a Check in the Target architecture"
|
||||
for identifier in sorted(given - set(graph.check_ids))
|
||||
]
|
||||
problems += [
|
||||
f"{name}: Check {identifier} is not accounted for"
|
||||
for identifier in graph.check_ids
|
||||
if identifier not in given
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_implementation(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = IMPLEMENTATION_FILE
|
||||
items, problems = _objects(attachments[name], name, ("check", "file", "address"))
|
||||
problems += _covers_every_check(items, name, read_graph(upstream))
|
||||
problems += [
|
||||
f"{name}: {item['check']} names {item['file']}, which is not attached"
|
||||
for item in items
|
||||
if item["file"] not in attachments
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = VERDICTS_FILE
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict):
|
||||
return [
|
||||
f"{name}: must be an object with dry_run, checks and proposed_additions"
|
||||
]
|
||||
problems: list[str] = []
|
||||
dry_run = data.get("dry_run")
|
||||
if (
|
||||
not isinstance(dry_run, dict)
|
||||
or dry_run.get("verdict") not in DRY_RUN_VERDICTS
|
||||
or not isinstance(dry_run.get("evidence"), str)
|
||||
or not dry_run["evidence"].strip()
|
||||
):
|
||||
problems.append(
|
||||
f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence"
|
||||
)
|
||||
items, faults = _objects(
|
||||
json.dumps(data.get("checks", [])),
|
||||
f"{name}.checks",
|
||||
("check", "verdict", "evidence"),
|
||||
)
|
||||
problems += faults
|
||||
problems += [
|
||||
f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}"
|
||||
for item in items
|
||||
if item["verdict"] not in VERDICTS
|
||||
]
|
||||
problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream))
|
||||
_, faults = _objects(
|
||||
json.dumps(data.get("proposed_additions", [])),
|
||||
f"{name}.proposed_additions",
|
||||
("statement", "applies_to", "reason"),
|
||||
)
|
||||
return problems + faults
|
||||
|
||||
|
||||
def validation_outcome(verdicts_text: str) -> dict[str, Any]:
|
||||
"""What a validation decided, for routing a Revision and for scoring.
|
||||
|
||||
Failed Checks are faults in the code. A Check that could not be verified and a
|
||||
proposed addition are gaps in the Target architecture.
|
||||
"""
|
||||
try:
|
||||
data = json.loads(verdicts_text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
checks = [item for item in data.get("checks", []) if isinstance(item, dict)]
|
||||
|
||||
def with_verdict(verdict: str) -> list[dict[str, Any]]:
|
||||
return [
|
||||
{"check": item.get("check"), "evidence": item.get("evidence")}
|
||||
for item in checks
|
||||
if item.get("verdict") == verdict
|
||||
]
|
||||
|
||||
dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {}
|
||||
return {
|
||||
"dry_run": dry_run,
|
||||
"passed": [
|
||||
item.get("check") for item in checks if item.get("verdict") == "pass"
|
||||
],
|
||||
"failed": with_verdict("fail"),
|
||||
"not_verifiable": with_verdict("not_verifiable"),
|
||||
"proposed_additions": [
|
||||
item
|
||||
for item in data.get("proposed_additions", [])
|
||||
if isinstance(item, dict)
|
||||
],
|
||||
}
|
||||
@@ -9,14 +9,34 @@ solution-guide template by suffix (e.g. "Products and features mapping" matches
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Mapping
|
||||
from collections.abc import Callable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from enum import StrEnum
|
||||
|
||||
from app.workflows.chain import (
|
||||
COMPONENTS_FILE,
|
||||
IMPLEMENTATION_FILE,
|
||||
PRODUCTS_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
VERDICTS_FILE,
|
||||
Upstream,
|
||||
check_components,
|
||||
check_implementation,
|
||||
check_products,
|
||||
check_recommendations,
|
||||
check_requirements,
|
||||
check_target_architecture,
|
||||
check_verdicts,
|
||||
)
|
||||
from app.workflows.target_architecture import GRAPH_ATTACHMENT
|
||||
|
||||
|
||||
class PhaseId(StrEnum):
|
||||
REQUIREMENTS_DISCOVERY = "requirements_discovery"
|
||||
# Design: ends with the Target architecture, approved before any code is written.
|
||||
SOLUTION_ARCHITECTURE = "solution_architecture"
|
||||
SOLUTION_IMPLEMENTATION = "solution_implementation"
|
||||
SOLUTION_VALIDATION = "solution_validation"
|
||||
PACKAGING = "packaging"
|
||||
|
||||
@@ -28,9 +48,9 @@ class DeliverableKind(StrEnum):
|
||||
REQUIREMENTS = "requirements"
|
||||
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
||||
PRODUCT_SELECTION = "product_selection"
|
||||
ARCHITECTURE_DIAGRAM = "architecture_diagram"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
||||
TARGET_ARCHITECTURE = "target_architecture"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DEPLOYMENT_GUIDANCE = "deployment_guidance"
|
||||
VALIDATION_RESULTS = "validation_results"
|
||||
SOLUTION_GUIDE = "solution_guide"
|
||||
@@ -45,6 +65,13 @@ class DeliverableSpec:
|
||||
sections: tuple[str, ...] = ()
|
||||
attachments: tuple[str, ...] = ()
|
||||
|
||||
def contract(self) -> dict[str, list[str]]:
|
||||
"""What a submission must contain, as plain data for the Specialist's context."""
|
||||
return {
|
||||
"sections": list(self.sections),
|
||||
"attachments": list(self.attachments),
|
||||
}
|
||||
|
||||
|
||||
_K = DeliverableKind
|
||||
|
||||
@@ -61,12 +88,15 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"Current state",
|
||||
"Dependencies",
|
||||
),
|
||||
attachments=(REQUIREMENTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.TECHNICAL_DECOMPOSITION,
|
||||
PhaseId.REQUIREMENTS_DISCOVERY,
|
||||
"decomposer",
|
||||
depends_on=(_K.REQUIREMENTS,),
|
||||
sections=("Components",),
|
||||
attachments=(COMPONENTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.PRODUCT_SELECTION,
|
||||
@@ -74,19 +104,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"product-selector",
|
||||
depends_on=(_K.TECHNICAL_DECOMPOSITION,),
|
||||
sections=("Products and features mapping",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DIAGRAM,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"diagrammer",
|
||||
depends_on=(_K.PRODUCT_SELECTION,),
|
||||
attachments=("architecture.mmd",),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DESCRIPTION,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"describer",
|
||||
depends_on=(_K.ARCHITECTURE_DIAGRAM, _K.PRODUCT_SELECTION),
|
||||
attachments=(PRODUCTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DESIGN_RECOMMENDATIONS,
|
||||
@@ -101,17 +119,38 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"Performance efficiency",
|
||||
"Sustainability",
|
||||
),
|
||||
attachments=(RECOMMENDATIONS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.TARGET_ARCHITECTURE,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
"target-architect",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
|
||||
sections=("Elements", "Relationships", "Checks"),
|
||||
# The engine adds architecture.mmd, rendered from the graph, on submission.
|
||||
attachments=(GRAPH_ATTACHMENT,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.ARCHITECTURE_DESCRIPTION,
|
||||
PhaseId.SOLUTION_IMPLEMENTATION,
|
||||
"describer",
|
||||
depends_on=(_K.TARGET_ARCHITECTURE,),
|
||||
sections=("Components", "Flow"),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.DEPLOYMENT_GUIDANCE,
|
||||
PhaseId.SOLUTION_ARCHITECTURE,
|
||||
PhaseId.SOLUTION_IMPLEMENTATION,
|
||||
"iac-author",
|
||||
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
|
||||
depends_on=(_K.TARGET_ARCHITECTURE,),
|
||||
sections=(
|
||||
"Deployment prerequisites",
|
||||
"Step-by-step deployment instructions",
|
||||
),
|
||||
attachments=("terraform/main.tf", "terraform/variables.tf"),
|
||||
attachments=(
|
||||
"terraform/main.tf",
|
||||
"terraform/variables.tf",
|
||||
IMPLEMENTATION_FILE,
|
||||
),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.VALIDATION_RESULTS,
|
||||
@@ -119,6 +158,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"validator",
|
||||
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
|
||||
sections=("Deployment dry-run", "Architecture and policy analysis"),
|
||||
attachments=(VERDICTS_FILE,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.SOLUTION_GUIDE,
|
||||
@@ -139,6 +179,20 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
)
|
||||
}
|
||||
|
||||
# What each data file along the Requirements chain must hold, checked at submission.
|
||||
DATA_CHECKS: Mapping[
|
||||
DeliverableKind,
|
||||
tuple[str, Callable[[Mapping[str, str], Upstream | None], list[str]]],
|
||||
] = {
|
||||
_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements),
|
||||
_K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components),
|
||||
_K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products),
|
||||
_K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations),
|
||||
_K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture),
|
||||
_K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation),
|
||||
_K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts),
|
||||
}
|
||||
|
||||
|
||||
def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
|
||||
"""The Deliverables a Specialist works from, in graph order.
|
||||
@@ -179,9 +233,16 @@ def _normalise(text: str) -> str:
|
||||
|
||||
|
||||
def check_submission(
|
||||
kind: DeliverableKind, content: str, attachments: Mapping[str, str]
|
||||
kind: DeliverableKind,
|
||||
content: str,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None = None,
|
||||
) -> tuple[str, ...]:
|
||||
"""Return what a submission lacks against its contract; empty means it's complete."""
|
||||
"""Return what a submission lacks against its contract; empty means it's complete.
|
||||
|
||||
`upstream` is the Deliverables this one builds on, by kind. With it, the links
|
||||
along the Requirements chain are checked too.
|
||||
"""
|
||||
if not content.strip():
|
||||
return ("content: must not be empty",)
|
||||
|
||||
@@ -195,4 +256,10 @@ def check_submission(
|
||||
for name in spec.attachments:
|
||||
if name not in attachments:
|
||||
missing.append(f"attachment: {name}")
|
||||
elif not attachments[name].strip():
|
||||
missing.append(f"attachment: {name} must not be empty")
|
||||
if kind in DATA_CHECKS:
|
||||
name, check = DATA_CHECKS[kind]
|
||||
if attachments.get(name, "").strip():
|
||||
missing.extend(check(attachments, upstream))
|
||||
return tuple(missing)
|
||||
|
||||
@@ -18,7 +18,7 @@ from typing import Any, cast
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
|
||||
from app.nodes.execution_nodes import make_execution_nodes
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
@@ -32,6 +32,8 @@ def build_execution_graph(
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
runtime=runtime,
|
||||
@@ -40,6 +42,8 @@ def build_execution_graph(
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
|
||||
283
app/workflows/target_architecture.py
Normal file
283
app/workflows/target_architecture.py
Normal file
@@ -0,0 +1,283 @@
|
||||
"""The Target architecture: one explicit graph, established before code (ADR-0005).
|
||||
|
||||
Elements every component and the resource that realises it
|
||||
Relationships how Elements connect
|
||||
Checks the numbered, verifiable conditions each must meet, each traced
|
||||
to the requirement or design recommendation it comes from
|
||||
|
||||
This module is pure: it parses the graph, states what is wrong with it, renders it as
|
||||
a diagram, and says whether the Requirements chain through it is complete.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from collections.abc import Iterable, Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
GRAPH_ATTACHMENT = "target-architecture.json"
|
||||
DIAGRAM_ATTACHMENT = "architecture.mmd"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Element:
|
||||
id: str
|
||||
name: str
|
||||
product: str
|
||||
resource_type: str
|
||||
component: str | None = None # None for a supporting Element, e.g. an identity
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Relationship:
|
||||
id: str
|
||||
source: str # "from" in the data
|
||||
target: str # "to" in the data
|
||||
kind: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Check:
|
||||
id: str
|
||||
applies_to: str # an Element or Relationship id
|
||||
statement: str
|
||||
source: str # a requirement or design recommendation id
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class NotApplicable:
|
||||
recommendation: str
|
||||
reason: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TargetArchitecture:
|
||||
elements: tuple[Element, ...]
|
||||
relationships: tuple[Relationship, ...]
|
||||
checks: tuple[Check, ...]
|
||||
not_applicable: tuple[NotApplicable, ...] = ()
|
||||
|
||||
@property
|
||||
def check_ids(self) -> tuple[str, ...]:
|
||||
return tuple(check.id for check in self.checks)
|
||||
|
||||
def summary(self) -> dict[str, Any]:
|
||||
"""What a user approving the design is told about the graph."""
|
||||
return {
|
||||
"elements": len(self.elements),
|
||||
"relationships": len(self.relationships),
|
||||
"checks": len(self.checks),
|
||||
"not_applicable": [
|
||||
{"recommendation": item.recommendation, "reason": item.reason}
|
||||
for item in self.not_applicable
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
class GraphError(ValueError):
|
||||
"""The graph is not well-formed; `problems` says how, one entry per fault."""
|
||||
|
||||
def __init__(self, problems: Sequence[str]) -> None:
|
||||
super().__init__("; ".join(problems))
|
||||
self.problems = tuple(problems)
|
||||
|
||||
|
||||
def parse_graph(text: str) -> TargetArchitecture:
|
||||
"""Parse target-architecture.json, or raise GraphError naming every fault."""
|
||||
name = GRAPH_ATTACHMENT
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc
|
||||
if not isinstance(data, dict):
|
||||
raise GraphError(
|
||||
[f"{name}: must be an object with elements, relationships and checks"]
|
||||
)
|
||||
|
||||
problems: list[str] = []
|
||||
|
||||
def items(key: str, required: Sequence[str]) -> list[dict[str, str]]:
|
||||
raw = data.get(key, [])
|
||||
if not isinstance(raw, list):
|
||||
problems.append(f"{name}.{key}: must be a list")
|
||||
return []
|
||||
accepted = []
|
||||
for index, item in enumerate(raw):
|
||||
where = f"{name}.{key}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where}: must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in required
|
||||
if not isinstance(item.get(field), str) or not item[field].strip()
|
||||
]
|
||||
if missing:
|
||||
problems.append(f"{where}: needs a non-empty {', '.join(missing)}")
|
||||
continue
|
||||
accepted.append(item)
|
||||
return accepted
|
||||
|
||||
elements = tuple(
|
||||
Element(
|
||||
id=item["id"],
|
||||
name=item["name"],
|
||||
product=item["product"],
|
||||
resource_type=item["resource_type"],
|
||||
component=item.get("component") or None,
|
||||
)
|
||||
for item in items("elements", ("id", "name", "product", "resource_type"))
|
||||
)
|
||||
relationships = tuple(
|
||||
Relationship(item["id"], item["from"], item["to"], item["kind"])
|
||||
for item in items("relationships", ("id", "from", "to", "kind"))
|
||||
)
|
||||
checks = tuple(
|
||||
Check(item["id"], item["applies_to"], item["statement"], item["source"])
|
||||
for item in items("checks", ("id", "applies_to", "statement", "source"))
|
||||
)
|
||||
not_applicable = tuple(
|
||||
NotApplicable(item["recommendation"], item["reason"])
|
||||
for item in items("not_applicable", ("recommendation", "reason"))
|
||||
)
|
||||
|
||||
if not elements and not problems:
|
||||
problems.append(f"{name}.elements: the graph has no Elements")
|
||||
|
||||
seen: set[str] = set()
|
||||
ids = [thing.id for group in (elements, relationships, checks) for thing in group]
|
||||
for identifier in ids:
|
||||
if identifier in seen:
|
||||
problems.append(f"{name}: id {identifier} is used more than once")
|
||||
seen.add(identifier)
|
||||
|
||||
element_ids = {element.id for element in elements}
|
||||
for relationship in relationships:
|
||||
for end, value in (("from", relationship.source), ("to", relationship.target)):
|
||||
if value not in element_ids:
|
||||
problems.append(
|
||||
f"{name}: Relationship {relationship.id} {end} {value}, "
|
||||
"which is not an Element"
|
||||
)
|
||||
targets = element_ids | {relationship.id for relationship in relationships}
|
||||
for check in checks:
|
||||
if check.applies_to not in targets:
|
||||
problems.append(
|
||||
f"{name}: Check {check.id} applies to {check.applies_to}, "
|
||||
"which is not an Element or Relationship"
|
||||
)
|
||||
checked = {check.applies_to for check in checks}
|
||||
for element in elements:
|
||||
if element.id not in checked:
|
||||
problems.append(f"{name}: Element {element.id} has no Check")
|
||||
|
||||
if problems:
|
||||
raise GraphError(problems)
|
||||
return TargetArchitecture(elements, relationships, checks, not_applicable)
|
||||
|
||||
|
||||
# --- the Requirements chain through the graph ----------------------------------------
|
||||
|
||||
|
||||
def chain_gaps(
|
||||
graph: TargetArchitecture,
|
||||
*,
|
||||
requirements: Sequence[Mapping[str, Any]],
|
||||
components: Sequence[Mapping[str, Any]],
|
||||
products: Sequence[Mapping[str, Any]],
|
||||
recommendations: Sequence[Mapping[str, Any]],
|
||||
) -> tuple[str, ...]:
|
||||
"""Every place the Requirements chain stops before reaching a Check.
|
||||
|
||||
A functional requirement is carried by a component that has an Element, or by a
|
||||
Check of its own. A non-functional requirement and a design recommendation are
|
||||
each a constraint, so each must be the source of a Check (a recommendation may
|
||||
instead be marked not applicable, with a reason).
|
||||
"""
|
||||
gaps: list[str] = []
|
||||
requirement_ids = {item["id"] for item in requirements}
|
||||
recommendation_ids = {item["id"] for item in recommendations}
|
||||
sources = {check.source for check in graph.checks}
|
||||
realised = {element.component for element in graph.elements if element.component}
|
||||
|
||||
for check in graph.checks:
|
||||
if check.source not in requirement_ids | recommendation_ids:
|
||||
gaps.append(
|
||||
f"Check {check.id} has source {check.source}, which is not a "
|
||||
"requirement or design recommendation"
|
||||
)
|
||||
for element in graph.elements:
|
||||
if element.component and element.component not in {c["id"] for c in components}:
|
||||
gaps.append(
|
||||
f"Element {element.id} realises {element.component}, "
|
||||
"which is not a component"
|
||||
)
|
||||
|
||||
for component in components:
|
||||
if component["id"] not in realised:
|
||||
gaps.append(f"Component {component['id']} has no Element")
|
||||
for requirement in requirements:
|
||||
if requirement["id"] in sources:
|
||||
continue
|
||||
served = any(
|
||||
requirement["id"] in component.get("requirements", ())
|
||||
and component["id"] in realised
|
||||
for component in components
|
||||
)
|
||||
if requirement.get("kind") == "functional" and served:
|
||||
continue
|
||||
gaps.append(f"Requirement {requirement['id']} has no Check")
|
||||
for selection in products:
|
||||
used = any(
|
||||
element.component == selection["component"]
|
||||
and element.product == selection["product"]
|
||||
for element in graph.elements
|
||||
)
|
||||
if not used:
|
||||
gaps.append(
|
||||
f"Product {selection['product']} selected for "
|
||||
f"{selection['component']} appears on no Element"
|
||||
)
|
||||
excused = {item.recommendation for item in graph.not_applicable}
|
||||
for item in graph.not_applicable:
|
||||
if item.recommendation not in recommendation_ids:
|
||||
gaps.append(
|
||||
f"not_applicable names {item.recommendation}, "
|
||||
"which is not a design recommendation"
|
||||
)
|
||||
for recommendation in recommendations:
|
||||
if recommendation["id"] not in sources | excused:
|
||||
gaps.append(f"Recommendation {recommendation['id']} has no Check")
|
||||
return tuple(gaps)
|
||||
|
||||
|
||||
# --- the diagram is a view of the graph ----------------------------------------------
|
||||
|
||||
_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]')
|
||||
|
||||
|
||||
def _label(*parts: str) -> str:
|
||||
return "<br/>".join(_UNSAFE.sub(" ", part).strip() for part in parts if part)
|
||||
|
||||
|
||||
def _node_ids(ids: Iterable[str]) -> dict[str, str]:
|
||||
"""Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects."""
|
||||
return {identifier: f"n{index}" for index, identifier in enumerate(ids)}
|
||||
|
||||
|
||||
def render_mermaid(graph: TargetArchitecture) -> str:
|
||||
"""The architecture diagram: every Element and Relationship, exactly once."""
|
||||
nodes = _node_ids(element.id for element in graph.elements)
|
||||
lines = ["flowchart LR"]
|
||||
for element in graph.elements:
|
||||
lines.append(
|
||||
f' {nodes[element.id]}["{_label(element.name, element.product)}"]'
|
||||
)
|
||||
for relationship in graph.relationships:
|
||||
lines.append(
|
||||
f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| "
|
||||
f"{nodes[relationship.target]}"
|
||||
)
|
||||
return "\n".join(lines) + "\n"
|
||||
Reference in New Issue
Block a user