This commit is contained in:
@@ -238,7 +238,7 @@ class AdkAgentRuntime:
|
||||
instruction=lambda _context: instructions,
|
||||
tools=agent_tools,
|
||||
before_tool_callback=control.before_tool,
|
||||
generate_content_config=self._content_config(),
|
||||
generate_content_config=self._content_config(role),
|
||||
)
|
||||
runner = Runner(
|
||||
app_name=APP_NAME,
|
||||
@@ -293,13 +293,13 @@ class AdkAgentRuntime:
|
||||
or f"{role.name} ended without calling a tool that ends its turn."
|
||||
)
|
||||
|
||||
def _content_config(self) -> types.GenerateContentConfig | None:
|
||||
if self._model_timeout_seconds is None:
|
||||
def _content_config(self, role: RoleSpec) -> types.GenerateContentConfig | None:
|
||||
# A role whose replies are long is given longer than the default.
|
||||
seconds = role.model_timeout_seconds or self._model_timeout_seconds
|
||||
if seconds is None:
|
||||
return None
|
||||
return types.GenerateContentConfig(
|
||||
http_options=types.HttpOptions(
|
||||
timeout=int(self._model_timeout_seconds * 1000)
|
||||
)
|
||||
http_options=types.HttpOptions(timeout=int(seconds * 1000))
|
||||
)
|
||||
|
||||
|
||||
|
||||
@@ -15,8 +15,10 @@ from typing import Any
|
||||
|
||||
from app.adk.runtime import (
|
||||
AgentTask,
|
||||
Answer,
|
||||
BudgetExhausted,
|
||||
Outcome,
|
||||
Question,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
ToolSpec,
|
||||
@@ -180,3 +182,27 @@ class FakeAgentRuntime:
|
||||
RunRecord(role.name, task, tuple(by_name), tuple(results), outcome)
|
||||
)
|
||||
return outcome
|
||||
|
||||
|
||||
class FakeDecider:
|
||||
"""A scripted Decider: answers by question id, or declines so callers fall back.
|
||||
|
||||
`answers` maps a question id to an Answer, or to a function of (state, question)
|
||||
returning one. An id with no entry makes the whole decision unavailable.
|
||||
"""
|
||||
|
||||
def __init__(self, answers: Mapping[str, Any] | None = None) -> None:
|
||||
self.answers = dict(answers or {})
|
||||
self.asked: list[tuple[str, dict[str, Question], str]] = []
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
self.asked.append((state, dict(questions), scope))
|
||||
decided = {}
|
||||
for name, question in questions.items():
|
||||
if name not in self.answers:
|
||||
return None
|
||||
answer = self.answers[name]
|
||||
decided[name] = answer(state, question) if callable(answer) else answer
|
||||
return decided
|
||||
|
||||
@@ -16,6 +16,7 @@ from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
REPLY_WRITER = "reply-writer"
|
||||
PARTIALS_DIR = "partials"
|
||||
|
||||
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
|
||||
@@ -34,7 +35,7 @@ def load_roles(
|
||||
include_preview_mcp: bool = True,
|
||||
) -> dict[str, RoleSpec]:
|
||||
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
|
||||
required = {ORCHESTRATOR, PILLAR_ADVISOR, *specialists}
|
||||
required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists}
|
||||
|
||||
roles = {}
|
||||
for path in sorted(agents_dir.glob("*.md")):
|
||||
@@ -129,4 +130,5 @@ def _load_role(
|
||||
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
|
||||
),
|
||||
model=bundle.models.for_role(name),
|
||||
model_timeout_seconds=bundle.models.timeout_for(name),
|
||||
)
|
||||
|
||||
@@ -32,6 +32,8 @@ class RoleSpec:
|
||||
tools: tuple[str, ...] = () # local tool names, e.g. terraform_validate
|
||||
mcp_servers: tuple[str, ...] = ()
|
||||
model: str | None = None
|
||||
# Seconds one model request may take; None takes the runtime's default.
|
||||
model_timeout_seconds: float | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -200,6 +202,59 @@ REJECTION_PREFIXES = (
|
||||
)
|
||||
|
||||
|
||||
# --- decisions -----------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Question:
|
||||
"""A closed question about a state. Its answer is typed, never prose.
|
||||
|
||||
choice pick one of `options`
|
||||
score rate against `options`, ordered from lowest to highest
|
||||
noul yes or no; the answer is the probability that it is yes
|
||||
"""
|
||||
|
||||
kind: str # choice | score | noul
|
||||
instructions: str
|
||||
options: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Answer:
|
||||
"""`value` is the chosen option (choice), the level reached (score, as a number
|
||||
from 0 for the lowest option) or the probability of yes (noul)."""
|
||||
|
||||
value: str | float
|
||||
confidence: float
|
||||
probabilities: Mapping[str, float] = field(default_factory=dict)
|
||||
|
||||
def is_yes(self, threshold: float = 0.5) -> bool:
|
||||
return isinstance(self.value, (int, float)) and self.value >= threshold
|
||||
|
||||
|
||||
class Decider(Protocol):
|
||||
"""Answers closed questions about a state (ADR-0007).
|
||||
|
||||
Returns None when no decision could be made: the service is not configured,
|
||||
unreachable, over its budget, or the request is too large. The caller then takes
|
||||
its fallback; a decider never blocks an Execution. `scope` names what a budget is
|
||||
counted against, usually the Execution.
|
||||
"""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None: ...
|
||||
|
||||
|
||||
class NoDecider:
|
||||
"""The decider when none is configured: every caller takes its fallback."""
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
return None
|
||||
|
||||
|
||||
class AgentRuntime(Protocol):
|
||||
async def run(
|
||||
self, role: RoleSpec, task: AgentTask, tools: Sequence[ToolSpec]
|
||||
|
||||
77
app/agent.py
77
app/agent.py
@@ -10,10 +10,11 @@ checkpointers and recorders are chosen, from settings and the provider bundle.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import uuid
|
||||
from collections.abc import AsyncIterator, Mapping, Sequence
|
||||
from contextlib import asynccontextmanager
|
||||
from dataclasses import dataclass
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
@@ -22,16 +23,31 @@ 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, RunLimiter, ToolFactory
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
Decider,
|
||||
NoDecider,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
ToolFactory,
|
||||
)
|
||||
from app.checkpointing import open_checkpointer
|
||||
from app.config import Settings
|
||||
from app.customer_case import record_intent
|
||||
from app.nodes.router import (
|
||||
REPLY_WRITER,
|
||||
OrchestratorPolicy,
|
||||
Router,
|
||||
RuntimeReplyWriter,
|
||||
Thresholds,
|
||||
)
|
||||
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.jev import JevDecider, JevLimits
|
||||
from app.tools.local import TerraformRunner, local_tools
|
||||
from app.tools.mcp import McpCatalog, auth_from_config
|
||||
from app.tools.toolkit import make_tool_factory
|
||||
@@ -67,6 +83,7 @@ class ExecutionEngine:
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
orchestrator: OrchestratorPolicy | None = None,
|
||||
) -> None:
|
||||
required = {
|
||||
ORCHESTRATOR,
|
||||
@@ -86,6 +103,7 @@ class ExecutionEngine:
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
orchestrator=orchestrator,
|
||||
).compile(checkpointer=checkpointer)
|
||||
|
||||
async def start(
|
||||
@@ -136,6 +154,11 @@ class ExecutionEngine:
|
||||
"working": {},
|
||||
"pending_permission": None,
|
||||
"prompt": None,
|
||||
"last_reply": None,
|
||||
"pending_change": None,
|
||||
"awaiting_gap_decision": False,
|
||||
"validation_settled": 0,
|
||||
"decisions": [],
|
||||
"outcomes": [],
|
||||
"refusals": [],
|
||||
"outcomes_applied": 0,
|
||||
@@ -203,6 +226,27 @@ class Assembly:
|
||||
bundle: ProviderBundle
|
||||
roles: dict[str, RoleSpec]
|
||||
mcp_gaps: dict[str, str]
|
||||
decider: Decider = field(default_factory=NoDecider)
|
||||
|
||||
|
||||
def open_decider(settings: Settings) -> Decider:
|
||||
"""The Jev client when a key is configured; otherwise a decider that always
|
||||
sends its caller to the fallback."""
|
||||
if not settings.TYPESAFE_API_KEY:
|
||||
return NoDecider()
|
||||
return JevDecider(
|
||||
api_key=settings.TYPESAFE_API_KEY,
|
||||
base_url=settings.TYPESAFE_BASE_URL,
|
||||
model=settings.TYPESAFE_DEFAULT_MODEL,
|
||||
limits=dataclasses.replace(
|
||||
JevLimits(),
|
||||
request_timeout=settings.JEV_TIMEOUT_SECONDS,
|
||||
requests_per_second=settings.JEV_REQUESTS_PER_SECOND,
|
||||
max_in_flight=settings.JEV_MAX_IN_FLIGHT,
|
||||
budget_calls=settings.JEV_BUDGET_CALLS,
|
||||
budget_tokens=settings.JEV_BUDGET_TOKENS,
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
@asynccontextmanager
|
||||
@@ -242,6 +286,7 @@ async def open_assembly(
|
||||
binary=settings.TERRAFORM_BINARY,
|
||||
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
|
||||
plugin_cache_dir=settings.terraform_plugin_cache(),
|
||||
providers=bundle.terraform_providers,
|
||||
)
|
||||
offered = [name for names in bundle.tools.values() for name in names]
|
||||
# One cap for Specialists and the pillar advisors they fan out to.
|
||||
@@ -250,11 +295,30 @@ async def open_assembly(
|
||||
runtime,
|
||||
roles,
|
||||
bundle.pillar_skills,
|
||||
local_tools=local_tools(offered, runner),
|
||||
local_tools=lambda working_copy: local_tools(offered, runner, working_copy),
|
||||
catalog=catalog,
|
||||
limiter=limiter,
|
||||
)
|
||||
|
||||
decider = open_decider(settings)
|
||||
orchestrator: OrchestratorPolicy | None = None
|
||||
if settings.ORCHESTRATOR == "router":
|
||||
# The Orchestrator routes: Jev reads, the playbook decides, and a model only
|
||||
# writes what the user reads. With no Jev key the playbook runs on its rules.
|
||||
orchestrator = Router(
|
||||
decider,
|
||||
RuntimeReplyWriter(runtime, roles[REPLY_WRITER]),
|
||||
Thresholds(
|
||||
act=settings.JEV_ACT_THRESHOLD,
|
||||
close=settings.JEV_CLOSE_THRESHOLD,
|
||||
confidence=settings.JEV_CONFIDENCE_THRESHOLD,
|
||||
),
|
||||
)
|
||||
elif settings.ORCHESTRATOR != "model":
|
||||
raise ValueError(
|
||||
f"ORCHESTRATOR must be router or model, not {settings.ORCHESTRATOR!r}"
|
||||
)
|
||||
|
||||
async with open_checkpointer(settings) as checkpointer:
|
||||
engine = ExecutionEngine(
|
||||
runtime=runtime,
|
||||
@@ -269,5 +333,10 @@ async def open_assembly(
|
||||
skill_versions={
|
||||
name: skill_version(meta.path) for name, meta in bundle.skills.items()
|
||||
},
|
||||
orchestrator=orchestrator,
|
||||
)
|
||||
yield Assembly(engine, bundle, roles, dict(catalog.gaps))
|
||||
try:
|
||||
yield Assembly(engine, bundle, roles, dict(catalog.gaps), decider)
|
||||
finally:
|
||||
if isinstance(decider, JevDecider):
|
||||
await decider.aclose()
|
||||
|
||||
@@ -53,11 +53,33 @@ class Settings(BaseSettings):
|
||||
SPECIALIST_BUDGET: int = 15
|
||||
MAX_REVISIONS: int = 3
|
||||
MAX_ORCHESTRATOR_TURNS: int = 100
|
||||
# How an Orchestrator turn is decided (ADR-0007): "router" reads the Execution
|
||||
# and follows its playbook, with Jev for the judgements; "model" has a language
|
||||
# model choose the tool calls, as before, and is kept for comparison.
|
||||
ORCHESTRATOR: str = "router"
|
||||
# Agent runs in flight at once, pillar advisors included (model rate limits)
|
||||
MAX_PARALLEL_SPECIALISTS: int = 4
|
||||
CHECKPOINTER: str = "sqlite" # memory | sqlite | postgres
|
||||
CHECKPOINT_DB_PATH: str = "checkpoints.db"
|
||||
|
||||
# Jev decision service (ADR-0007), reached through TypeSafe AI's Python SDK.
|
||||
# With no key, every decision takes its fallback and the agent behaves as it does
|
||||
# without Jev. The key comes from the environment or a secret store, never from
|
||||
# the provider bundle or the repository.
|
||||
TYPESAFE_API_KEY: str | None = None
|
||||
TYPESAFE_BASE_URL: str | None = None # None: the SDK's default endpoint
|
||||
TYPESAFE_DEFAULT_MODEL: str | None = None # None: the SDK's default model
|
||||
JEV_TIMEOUT_SECONDS: float = 5.0 # one request
|
||||
JEV_REQUESTS_PER_SECOND: float = 5.0
|
||||
JEV_MAX_IN_FLIGHT: int = 8
|
||||
JEV_BUDGET_CALLS: int = 500 # per Execution
|
||||
JEV_BUDGET_TOKENS: int = 1_000_000 # per Execution
|
||||
# A probability at or above ACT is acted on; at or below CLOSE is dropped; in
|
||||
# between, the user is asked. A choice below CONFIDENCE is not relied on.
|
||||
JEV_ACT_THRESHOLD: float = 0.75
|
||||
JEV_CLOSE_THRESHOLD: float = 0.15
|
||||
JEV_CONFIDENCE_THRESHOLD: float = 0.6
|
||||
|
||||
# Paths
|
||||
BASE_DIR: Path = Path(__file__).resolve().parent.parent
|
||||
|
||||
|
||||
@@ -34,6 +34,7 @@ from app.adk.runtime import (
|
||||
TurnEnded,
|
||||
)
|
||||
from app.customer_case import close_intent
|
||||
from app.nodes.router import ModelOrchestrator, OrchestratorPolicy, TurnView
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import (
|
||||
UNASSIGNED_CASE,
|
||||
@@ -43,13 +44,19 @@ from app.states.execution_state import (
|
||||
)
|
||||
from app.states.ledger import DeliverableStatus, Ledger, LedgerRefusal
|
||||
from app.states.lessons import collect_lesson_candidates, refusal
|
||||
from app.tools import workspace
|
||||
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
|
||||
from app.workflows.chain import VERDICTS_FILE, validation_outcome
|
||||
from app.workflows.chain import (
|
||||
IMPLEMENTATION_FILE,
|
||||
VERDICTS_FILE,
|
||||
unimplementable_checks,
|
||||
validation_outcome,
|
||||
)
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
PHASE_ORDER,
|
||||
DeliverableKind,
|
||||
inputs_of,
|
||||
dependencies_for,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
@@ -90,8 +97,12 @@ def make_execution_nodes(
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
orchestrator: OrchestratorPolicy | None = None,
|
||||
) -> ExecutionNodes:
|
||||
tool_factory = tool_factory or _no_tools
|
||||
# How an Orchestrator turn is decided. The default drives the tools from the
|
||||
# Orchestrator role on the runtime; the assembly supplies the router (ADR-0007).
|
||||
orchestrator = orchestrator or ModelOrchestrator(runtime, roles[ORCHESTRATOR])
|
||||
|
||||
def close(state: ExecutionState, status: str, *, has_files: bool) -> None:
|
||||
close_intent(
|
||||
@@ -239,19 +250,33 @@ def make_execution_nodes(
|
||||
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.",
|
||||
view = TurnView(
|
||||
execution_id=state["execution_id"],
|
||||
pre_approved=bool(state.get("pre_approved")),
|
||||
ledger=ledger,
|
||||
deliverables=deliverables,
|
||||
pending_questions=pending_questions,
|
||||
outcomes=outcomes,
|
||||
last_reply=state.get("last_reply"),
|
||||
pending_change=state.get("pending_change"),
|
||||
awaiting_gap_decision=bool(state.get("awaiting_gap_decision")),
|
||||
validation_settled=int(state.get("validation_settled", 0)),
|
||||
context=_orchestrator_context(
|
||||
state, ledger, deliverables, pending_questions, notes
|
||||
),
|
||||
)
|
||||
started = time.monotonic()
|
||||
outcome = await runtime.run(
|
||||
roles[ORCHESTRATOR],
|
||||
task,
|
||||
_noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None),
|
||||
decided = await orchestrator.turn(
|
||||
view, _noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None)
|
||||
)
|
||||
outcome = decided.outcome
|
||||
update.update(decided.updates)
|
||||
if decided.decisions:
|
||||
# Every decision is kept: what was read, which group applied, what was done.
|
||||
update["decisions"] = [
|
||||
*state.get("decisions", []),
|
||||
*({"turn": turns, **decision} for decision in decided.decisions),
|
||||
]
|
||||
logger.info(
|
||||
"[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s",
|
||||
state["execution_id"],
|
||||
@@ -325,13 +350,22 @@ def make_execution_nodes(
|
||||
role = roles[task_input["role"]]
|
||||
kind = DeliverableKind(task_input["kind"])
|
||||
working: dict[str, Any] = dict(task_input.get("working") or {})
|
||||
upstream = task_input["context"].get("dependencies") or {}
|
||||
source = DEPENDENCY_GRAPH[kind].working_copy
|
||||
if source and source is not kind:
|
||||
# The tools work on the files as they were last submitted.
|
||||
working[workspace.FILES] = dict(
|
||||
upstream.get(source.value, {}).get("attachments", {})
|
||||
)
|
||||
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"),
|
||||
upstream=upstream,
|
||||
working=working,
|
||||
library=task_input.get("library"),
|
||||
),
|
||||
refusals,
|
||||
role.name,
|
||||
@@ -388,6 +422,7 @@ def make_execution_nodes(
|
||||
ledger = Ledger.from_dict(state["ledger"])
|
||||
conversation = list(state.get("conversation", []))
|
||||
update: dict[str, Any] = {"prompt": None}
|
||||
said: dict[str, Any] | None = None # what the user said, for the next turn
|
||||
|
||||
if "approval" in prompt:
|
||||
phase = prompt["approval"]["phase"]
|
||||
@@ -405,9 +440,11 @@ def make_execution_nodes(
|
||||
feedback = str(decision.get("feedback", ""))
|
||||
ledger.request_changes(phase_id, feedback, actor="user")
|
||||
text = f"Requested changes to {phase}: {feedback}"
|
||||
said = {"kind": "changes", "phase": phase, "text": feedback}
|
||||
conversation.append({"from": "user", "text": text})
|
||||
else:
|
||||
conversation.append({"from": "user", "text": _reply_text(reply)})
|
||||
said = {"kind": "reply", "text": _reply_text(reply)}
|
||||
elif "permission" in prompt:
|
||||
tier = prompt["permission"]["tier"]
|
||||
permission = reply.get("permission") if isinstance(reply, Mapping) else None
|
||||
@@ -427,6 +464,7 @@ def make_execution_nodes(
|
||||
else:
|
||||
text = _reply_text(reply)
|
||||
conversation.append({"from": "user", "text": text})
|
||||
said = {"kind": "reply", "text": text}
|
||||
answers = {
|
||||
kind: list(items) for kind, items in state.get("answers", {}).items()
|
||||
}
|
||||
@@ -436,6 +474,8 @@ def make_execution_nodes(
|
||||
)
|
||||
update.update(answers=answers, awaiting_questions=[])
|
||||
|
||||
# Only a real user's words are routed; a pre-approved Execution has none.
|
||||
update["last_reply"] = None if state.get("pre_approved") else said
|
||||
update["events_recorded"] = await record_progress(state, ledger)
|
||||
update.update(ledger=ledger.to_dict(), conversation=conversation)
|
||||
return Command(update=update, goto="orchestrator_turn")
|
||||
@@ -523,7 +563,17 @@ def _orchestrator_context(
|
||||
is DeliverableStatus.SUBMITTED
|
||||
else None
|
||||
)
|
||||
code = DeliverableKind.DEPLOYMENT_GUIDANCE
|
||||
return {
|
||||
# Checks the code's author reported cannot be met as written: faults in the
|
||||
# Target architecture, known before any validation.
|
||||
"unimplementable_checks": unimplementable_checks(
|
||||
deliverables.get(code.value, {})
|
||||
.get("attachments", {})
|
||||
.get(IMPLEMENTATION_FILE, "")
|
||||
)
|
||||
if ledger.status(code) is DeliverableStatus.SUBMITTED
|
||||
else [],
|
||||
# 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(
|
||||
@@ -565,8 +615,15 @@ def _specialist_input(
|
||||
attempt: int,
|
||||
) -> dict[str, Any]:
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
given = dependencies_for(kind, deliverables)
|
||||
return {
|
||||
"execution_id": state["execution_id"],
|
||||
# The Deliverables given as data files alone, whole, for reading on demand.
|
||||
"library": {
|
||||
name: dict(deliverables[name])
|
||||
for name, deliverable in given.items()
|
||||
if "content" not in deliverable
|
||||
},
|
||||
"role": spec.specialist,
|
||||
"kind": kind.value,
|
||||
"attempt": attempt,
|
||||
@@ -576,13 +633,14 @@ def _specialist_input(
|
||||
"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)
|
||||
},
|
||||
"dependencies": given,
|
||||
"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,
|
||||
# What the Specialist's own tools already hold from earlier attempts.
|
||||
"working_copy": workspace.summary(
|
||||
state.get("working", {}).get(kind.value, {})
|
||||
),
|
||||
"attempt": attempt,
|
||||
},
|
||||
}
|
||||
|
||||
779
app/nodes/router.py
Normal file
779
app/nodes/router.py
Normal file
@@ -0,0 +1,779 @@
|
||||
"""The Orchestrator as a router (ADR-0007): readings, a disposition, then a playbook.
|
||||
|
||||
1. Readings facts about the turn. Most come from the Ledger; the ones that need
|
||||
judgement (what is the user asking for? does this gap matter?) are
|
||||
typed answers from the decision model.
|
||||
2. Disposition code turns a judged reading into act, queue or close, by threshold.
|
||||
3. Playbook ordered groups. The first group that applies is taken, and within
|
||||
it the strongest action whose conditions hold. When no group
|
||||
applies, escalate to the user.
|
||||
|
||||
The decision model reads and never acts: every action goes through the Orchestrator's
|
||||
tools, so the Ledger refuses anything that is not allowed, whatever was decided.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import re
|
||||
from collections.abc import Awaitable, Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Protocol
|
||||
|
||||
from app.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
Decider,
|
||||
Outcome,
|
||||
Question,
|
||||
RoleSpec,
|
||||
Stopped,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
from app.states.ledger import DeliverableStatus, Ledger, PhaseStatus
|
||||
from app.workflows.chain import (
|
||||
IMPLEMENTATION_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
VERDICTS_FILE,
|
||||
read_graph,
|
||||
read_list,
|
||||
unimplementable_checks,
|
||||
validation_outcome,
|
||||
)
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
REPLY_WRITER = "reply-writer"
|
||||
MAX_STEPS = 12 # actions in one turn; a turn that needs more is not making progress
|
||||
|
||||
ACT, QUEUE, CLOSE = "act", "queue", "close"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Thresholds:
|
||||
"""Where a probability becomes a disposition."""
|
||||
|
||||
act: float = 0.75 # at or above: do it
|
||||
close: float = 0.15 # at or below: there is nothing to do
|
||||
confidence: float = 0.6 # a choice below this is not relied on
|
||||
|
||||
def disposition(self, probability: float) -> str:
|
||||
if probability >= self.act:
|
||||
return ACT
|
||||
if probability <= self.close:
|
||||
return CLOSE
|
||||
return QUEUE
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TurnView:
|
||||
"""What one Orchestrator turn can see."""
|
||||
|
||||
execution_id: str
|
||||
pre_approved: bool
|
||||
ledger: Ledger
|
||||
deliverables: Mapping[str, Mapping[str, Any]]
|
||||
pending_questions: Sequence[Mapping[str, Any]]
|
||||
outcomes: Sequence[Mapping[str, Any]]
|
||||
last_reply: Mapping[str, Any] | None = None # the user's message, not yet routed
|
||||
pending_change: Mapping[str, Any] | None = None # a change we asked them to confirm
|
||||
awaiting_gap_decision: bool = False
|
||||
validation_settled: int = 0 # the validation attempt already decided on
|
||||
context: Mapping[str, Any] = field(default_factory=dict) # for a model Orchestrator
|
||||
|
||||
|
||||
@dataclass
|
||||
class TurnResult:
|
||||
outcome: Outcome
|
||||
decisions: list[dict[str, Any]] = field(default_factory=list)
|
||||
updates: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
class OrchestratorPolicy(Protocol):
|
||||
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult: ...
|
||||
|
||||
|
||||
class ReplyWriter(Protocol):
|
||||
async def approval_summary(
|
||||
self, phase: str, facts: Mapping[str, Any]
|
||||
) -> str | None: ...
|
||||
|
||||
|
||||
# --- readings ------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass
|
||||
class Readings:
|
||||
"""Everything the playbook decides from."""
|
||||
|
||||
# From the Ledger and the Execution's data.
|
||||
questions_waiting: bool = False
|
||||
phases_ready: tuple[PhaseId, ...] = ()
|
||||
phases_awaiting: tuple[PhaseId, ...] = () # asked for Approval, not yet decided
|
||||
ready_work: tuple[DeliverableKind, ...] = ()
|
||||
can_finish: bool = False
|
||||
validation_attempt: int = 0 # 0 when no validation stands undecided
|
||||
failed: list[dict[str, Any]] = field(default_factory=list)
|
||||
repeat_failed: list[dict[str, Any]] = field(default_factory=list)
|
||||
unverifiable: list[dict[str, Any]] = field(default_factory=list)
|
||||
additions: list[dict[str, Any]] = field(default_factory=list)
|
||||
dry_run_failed: bool = False
|
||||
# Checks the code's author reported cannot be met as the Target architecture
|
||||
# words them.
|
||||
unimplementable: list[dict[str, str]] = field(default_factory=list)
|
||||
# Judged: what the user's message asks for.
|
||||
change: str = CLOSE # act | queue | close
|
||||
change_target: DeliverableKind | None = None
|
||||
change_reason: str = ""
|
||||
# Judged: whether a gap in the Target architecture is worth a Revision.
|
||||
gap: str = CLOSE
|
||||
judged: dict[str, Any] = field(default_factory=dict) # what the decider answered
|
||||
|
||||
|
||||
def _attempt(ledger: Ledger, kind: DeliverableKind) -> int:
|
||||
return int(ledger.to_dict()["deliverables"][kind.value].get("attempt", 0))
|
||||
|
||||
|
||||
def _submitted(ledger: Ledger) -> list[DeliverableKind]:
|
||||
return [
|
||||
kind
|
||||
for kind in DEPENDENCY_GRAPH
|
||||
if ledger.status(kind) is DeliverableStatus.SUBMITTED
|
||||
]
|
||||
|
||||
|
||||
def _mentioned(
|
||||
text: str, candidates: Sequence[DeliverableKind]
|
||||
) -> list[DeliverableKind]:
|
||||
"""Deliverables named outright in a message, as `deployment_guidance` or in words."""
|
||||
lowered = re.sub(r"[\s_\-]+", " ", text.lower())
|
||||
return [kind for kind in candidates if kind.value.replace("_", " ") in lowered]
|
||||
|
||||
|
||||
def _failed_before(outcomes: Sequence[Mapping[str, Any]]) -> set[str]:
|
||||
"""Check ids that failed in the validation before the one that stands now."""
|
||||
validations = [
|
||||
record
|
||||
for record in outcomes
|
||||
if record.get("type") == "submitted"
|
||||
and record.get("kind") == DeliverableKind.VALIDATION_RESULTS.value
|
||||
]
|
||||
if len(validations) < 2:
|
||||
return set()
|
||||
previous = validation_outcome(
|
||||
validations[-2].get("attachments", {}).get(VERDICTS_FILE, "")
|
||||
)
|
||||
return {item["check"] for item in previous["failed"]}
|
||||
|
||||
|
||||
class Router:
|
||||
"""Decides an Orchestrator turn from readings and a playbook, with no language
|
||||
model choosing the action. A model, when one is given, only writes what the user
|
||||
reads."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
decider: Decider,
|
||||
writer: ReplyWriter | None = None,
|
||||
thresholds: Thresholds | None = None,
|
||||
) -> None:
|
||||
self._decider = decider
|
||||
self._writer = writer
|
||||
self._thresholds = thresholds or Thresholds()
|
||||
|
||||
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
|
||||
by_name = {tool.name: tool for tool in tools}
|
||||
result = TurnResult(Stopped("The router took no action."))
|
||||
# A user message is routed once; a confirmation we asked for is consumed.
|
||||
result.updates = {
|
||||
"last_reply": None,
|
||||
"pending_change": None,
|
||||
"awaiting_gap_decision": False,
|
||||
}
|
||||
readings = await self._read(view, result)
|
||||
blocked: set[str] = set()
|
||||
settled = view.validation_settled
|
||||
|
||||
async def call(tool: str, **arguments: Any) -> ToolResult:
|
||||
return await by_name[tool].handler(**arguments)
|
||||
|
||||
for _ in range(MAX_STEPS):
|
||||
group, action = self._choose(view, readings, blocked, settled)
|
||||
result.decisions.append(
|
||||
{"group": group, "action": action, "judged": dict(readings.judged)}
|
||||
)
|
||||
readings.judged = {}
|
||||
reply = await self._perform(action, view, readings, call, result)
|
||||
if action == "proceed":
|
||||
settled = readings.validation_attempt
|
||||
result.updates["validation_settled"] = settled
|
||||
self._read_ledger(view, readings, settled)
|
||||
continue
|
||||
if reply is None:
|
||||
return result
|
||||
if reply.outcome is not None:
|
||||
result.outcome = reply.outcome
|
||||
return result
|
||||
if "revision limit" in reply.message and not view.pre_approved:
|
||||
# Past the Revision limit the user decides.
|
||||
limit = await call(
|
||||
"ask_user", questions=[reply.message.split(" Use ")[0]]
|
||||
)
|
||||
if limit.outcome is not None:
|
||||
result.outcome = limit.outcome
|
||||
return result
|
||||
if reply.message.startswith("Refused") or "revision limit" in reply.message:
|
||||
# Permission is the Ledger's: take the next action that is allowed.
|
||||
blocked.add(action)
|
||||
# The action changed the Execution; read the Ledger's facts again.
|
||||
self._read_ledger(view, readings, settled)
|
||||
if action in {"revise_requested", "confirm_change"}:
|
||||
readings.change = CLOSE
|
||||
result.outcome = Stopped("The router made no progress in this turn.")
|
||||
return result
|
||||
|
||||
# --- readings ---------------------------------------------------------------------
|
||||
|
||||
async def _read(self, view: TurnView, result: TurnResult) -> Readings:
|
||||
readings = Readings()
|
||||
self._read_ledger(view, readings, view.validation_settled)
|
||||
await self._read_message(view, readings)
|
||||
await self._read_gap(view, readings)
|
||||
return readings
|
||||
|
||||
def _read_ledger(self, view: TurnView, readings: Readings, settled: int) -> None:
|
||||
ledger = view.ledger
|
||||
readings.questions_waiting = bool(view.pending_questions)
|
||||
readings.phases_ready = ledger.phases_ready_for_approval()
|
||||
readings.phases_awaiting = tuple(
|
||||
phase
|
||||
for phase in PhaseId
|
||||
if ledger.phase_status(phase) is PhaseStatus.AWAITING_APPROVAL
|
||||
)
|
||||
readings.ready_work = ledger.ready_work()
|
||||
readings.can_finish = ledger.can_finish()
|
||||
readings.validation_attempt = 0
|
||||
readings.failed, readings.repeat_failed = [], []
|
||||
readings.unverifiable, readings.additions = [], []
|
||||
readings.dry_run_failed = False
|
||||
code = DeliverableKind.DEPLOYMENT_GUIDANCE
|
||||
readings.unimplementable = (
|
||||
unimplementable_checks(
|
||||
view.deliverables.get(code.value, {})
|
||||
.get("attachments", {})
|
||||
.get(IMPLEMENTATION_FILE, "")
|
||||
)
|
||||
if ledger.status(code) is DeliverableStatus.SUBMITTED
|
||||
else []
|
||||
)
|
||||
|
||||
validation = DeliverableKind.VALIDATION_RESULTS
|
||||
phase = DEPENDENCY_GRAPH[validation].phase
|
||||
attempt = _attempt(ledger, validation)
|
||||
if (
|
||||
ledger.status(validation) is not DeliverableStatus.SUBMITTED
|
||||
or ledger.phase_status(phase) is PhaseStatus.APPROVED
|
||||
or attempt == settled
|
||||
):
|
||||
return
|
||||
outcome = validation_outcome(
|
||||
view.deliverables.get(validation.value, {})
|
||||
.get("attachments", {})
|
||||
.get(VERDICTS_FILE, "")
|
||||
)
|
||||
before = _failed_before(view.outcomes)
|
||||
readings.validation_attempt = attempt
|
||||
readings.failed = outcome["failed"]
|
||||
readings.repeat_failed = [f for f in outcome["failed"] if f["check"] in before]
|
||||
readings.unverifiable = outcome["not_verifiable"]
|
||||
readings.additions = outcome["proposed_additions"]
|
||||
readings.dry_run_failed = outcome["dry_run"].get("verdict") == "fail"
|
||||
|
||||
async def _read_message(self, view: TurnView, readings: Readings) -> None:
|
||||
"""Triage of the user's message: is it asking for a change, to what, and how
|
||||
clearly?"""
|
||||
reply = view.last_reply
|
||||
if not reply or view.awaiting_gap_decision:
|
||||
return
|
||||
text = str(reply.get("text", "")).strip()
|
||||
pending = view.pending_change
|
||||
if pending:
|
||||
text = f"{pending.get('text', '')}\nThe user then said: {text}"
|
||||
candidates = _submitted(view.ledger)
|
||||
if not text or not candidates:
|
||||
return
|
||||
readings.change_reason = text
|
||||
# A structured request for changes is known to be one, and so is the reply to
|
||||
# our own question about a change they already asked for.
|
||||
structured = reply.get("kind") == "changes" or bool(pending)
|
||||
|
||||
questions = {
|
||||
"change_target": Question(
|
||||
"choice",
|
||||
"Which submitted Deliverable would have to change first to do what "
|
||||
"the user asks?",
|
||||
tuple(kind.value for kind in candidates),
|
||||
),
|
||||
"change_clarity": Question(
|
||||
"score",
|
||||
"How specific is the user about what should change?",
|
||||
("vague", "partial", "specific"),
|
||||
),
|
||||
}
|
||||
if not structured:
|
||||
questions["asks_change"] = Question(
|
||||
"noul",
|
||||
"Is the user asking for a change to work that has already been "
|
||||
"submitted, as opposed to answering a question or adding information?",
|
||||
)
|
||||
state = (
|
||||
f"Submitted Deliverables: {', '.join(kind.value for kind in candidates)}.\n"
|
||||
f"Questions waiting for the user: {len(view.pending_questions)}.\n"
|
||||
f"The user's message: {text}"
|
||||
)
|
||||
answers = await self._decider.decide(state, questions, scope=view.execution_id)
|
||||
|
||||
named = _mentioned(text, candidates)
|
||||
if answers is None:
|
||||
# No judgement available: act only on what is certain.
|
||||
if structured:
|
||||
target = (
|
||||
candidates[0]
|
||||
if len(candidates) == 1
|
||||
else named[0]
|
||||
if len(named) == 1
|
||||
else None
|
||||
)
|
||||
readings.change = ACT if target else QUEUE
|
||||
readings.change_target = target
|
||||
return
|
||||
|
||||
readings.judged = {
|
||||
name: {"value": answer.value, "confidence": answer.confidence}
|
||||
for name, answer in answers.items()
|
||||
}
|
||||
probability = 1.0 if structured else float(answers["asks_change"].value)
|
||||
disposition = self._thresholds.disposition(probability)
|
||||
target_answer = answers["change_target"]
|
||||
target = DeliverableKind(str(target_answer.value))
|
||||
readings.change_target = target
|
||||
if disposition == ACT and (
|
||||
target_answer.confidence < self._thresholds.confidence
|
||||
or float(answers["change_clarity"].value) < 0.5
|
||||
):
|
||||
# They want a change, but which, or what, is not clear enough to act on.
|
||||
disposition = QUEUE
|
||||
if disposition == QUEUE and pending:
|
||||
# Asked once already: act if they named it, otherwise let it go.
|
||||
disposition = ACT if len(named) == 1 else CLOSE
|
||||
readings.change_target = named[0] if named else target
|
||||
readings.change = disposition
|
||||
|
||||
async def _read_gap(self, view: TurnView, readings: Readings) -> None:
|
||||
"""Whether a gap in the Target architecture is worth revising it for."""
|
||||
if (
|
||||
readings.failed
|
||||
or readings.dry_run_failed
|
||||
or not readings.validation_attempt
|
||||
):
|
||||
return
|
||||
if not (readings.additions or readings.unverifiable):
|
||||
return
|
||||
items = "\n".join(
|
||||
[
|
||||
f"- proposed addition on {item.get('applies_to')}: "
|
||||
f"{item.get('statement')} (serves {item.get('reason')})"
|
||||
for item in readings.additions
|
||||
]
|
||||
+ [
|
||||
f"- Check {item.get('check')} could not be verified: "
|
||||
f"{item.get('evidence')}"
|
||||
for item in readings.unverifiable
|
||||
]
|
||||
)
|
||||
reply = view.last_reply if view.awaiting_gap_decision else None
|
||||
if reply:
|
||||
question = Question(
|
||||
"noul",
|
||||
"Is the user asking for the Target architecture to be revised to "
|
||||
"close these gaps?",
|
||||
)
|
||||
state = f"Gaps found by validation:\n{items}\nThe user's reply: {reply.get('text', '')}"
|
||||
name = "wants_revision"
|
||||
else:
|
||||
question = Question(
|
||||
"noul",
|
||||
"Would leaving these gaps open mean a stated requirement or design "
|
||||
"recommendation is not met?",
|
||||
)
|
||||
state = f"Gaps found by validation:\n{items}"
|
||||
name = "gap_material"
|
||||
answers = await self._decider.decide(
|
||||
state, {name: question}, scope=view.execution_id
|
||||
)
|
||||
if answers is None:
|
||||
readings.gap = self._gap_by_rule(view, readings) if not reply else CLOSE
|
||||
return
|
||||
readings.judged[name] = {
|
||||
"value": answers[name].value,
|
||||
"confidence": answers[name].confidence,
|
||||
}
|
||||
disposition = self._thresholds.disposition(float(answers[name].value))
|
||||
if reply and disposition == QUEUE:
|
||||
disposition = CLOSE # asked once already; an unclear answer means go on
|
||||
readings.gap = disposition
|
||||
|
||||
@staticmethod
|
||||
def _gap_by_rule(view: TurnView, readings: Readings) -> str:
|
||||
"""Without a judgement: a Check that cannot be verified must be fixed, and an
|
||||
addition counts when it names a real requirement or recommendation."""
|
||||
if readings.unverifiable:
|
||||
return ACT
|
||||
known = {
|
||||
item["id"]
|
||||
for name, kind in (
|
||||
(REQUIREMENTS_FILE, "requirements"),
|
||||
(RECOMMENDATIONS_FILE, "design_recommendations"),
|
||||
)
|
||||
for item in read_list(view.deliverables, kind, name)
|
||||
if "id" in item
|
||||
}
|
||||
for item in readings.additions:
|
||||
words = set(re.findall(r"[A-Za-z]+-\d+", str(item.get("reason", ""))))
|
||||
if words & known:
|
||||
return ACT
|
||||
return CLOSE
|
||||
|
||||
# --- the playbook -----------------------------------------------------------------
|
||||
|
||||
def _choose(
|
||||
self, view: TurnView, r: Readings, blocked: set[str], settled: int
|
||||
) -> tuple[str, str]:
|
||||
"""The first group that applies, and within it the strongest action whose
|
||||
conditions hold. No group applies: escalate."""
|
||||
interactive = not view.pre_approved
|
||||
playbook: list[tuple[str, bool, list[tuple[str, bool]]]] = [
|
||||
(
|
||||
"the user asked for a change",
|
||||
r.change in {ACT, QUEUE},
|
||||
[
|
||||
(
|
||||
"revise_requested",
|
||||
r.change == ACT and r.change_target is not None,
|
||||
),
|
||||
("confirm_change", r.change == QUEUE and interactive),
|
||||
],
|
||||
),
|
||||
(
|
||||
"questions are waiting",
|
||||
r.questions_waiting,
|
||||
[("relay_questions", True)],
|
||||
),
|
||||
(
|
||||
# Known as soon as the code is submitted, so no validation is spent
|
||||
# on a Check that cannot pass.
|
||||
"the code cannot meet a Check",
|
||||
bool(r.unimplementable),
|
||||
[("revise_unimplementable", True)],
|
||||
),
|
||||
(
|
||||
"validation decided",
|
||||
bool(r.validation_attempt),
|
||||
[
|
||||
(
|
||||
"revise_target_architecture",
|
||||
bool(r.repeat_failed) or (not r.failed and r.gap == ACT),
|
||||
),
|
||||
("revise_code", bool(r.failed) or r.dry_run_failed),
|
||||
("ask_about_gaps", r.gap == QUEUE and interactive),
|
||||
("proceed", True),
|
||||
],
|
||||
),
|
||||
(
|
||||
"a Phase is complete",
|
||||
bool(r.phases_ready or r.phases_awaiting),
|
||||
# An Approval is granted only by a structured decision, so a Phase
|
||||
# still awaiting one is asked for again.
|
||||
[("request_approval", True)],
|
||||
),
|
||||
("work is ready", bool(r.ready_work), [("delegate", True)]),
|
||||
("packaging is approved", r.can_finish, [("finish", True)]),
|
||||
]
|
||||
for group, applies, actions in playbook:
|
||||
if not applies:
|
||||
continue
|
||||
for action, holds in actions:
|
||||
if holds and action not in blocked:
|
||||
return group, action
|
||||
return "no group applies", "escalate"
|
||||
|
||||
async def _perform(
|
||||
self,
|
||||
action: str,
|
||||
view: TurnView,
|
||||
r: Readings,
|
||||
call: Callable[..., Awaitable[ToolResult]],
|
||||
result: TurnResult,
|
||||
) -> ToolResult | None:
|
||||
if action == "proceed":
|
||||
return ToolResult("Proceeding.")
|
||||
if action == "revise_requested":
|
||||
assert r.change_target is not None
|
||||
return await call(
|
||||
"reopen", kind=r.change_target.value, reason=r.change_reason
|
||||
)
|
||||
if action == "confirm_change":
|
||||
guess = r.change_target.value if r.change_target else None
|
||||
result.updates["pending_change"] = {"text": r.change_reason, "guess": guess}
|
||||
options = ", ".join(kind.value for kind in _submitted(view.ledger))
|
||||
question = (
|
||||
f"Do you want {guess} changed? Reply naming the Deliverable to change "
|
||||
f"and what should be different. Submitted so far: {options}."
|
||||
if guess
|
||||
else "Which Deliverable should change, and what should be different? "
|
||||
f"Submitted so far: {options}."
|
||||
)
|
||||
return await call("ask_user", questions=[question])
|
||||
if action == "relay_questions":
|
||||
return await call("ask_user", questions=[])
|
||||
if action == "revise_code":
|
||||
items = r.failed or [
|
||||
{"check": "dry-run", "evidence": "the deployment dry-run failed"}
|
||||
]
|
||||
reason = "; ".join(f"{i['check']} failed: {i['evidence']}" for i in items)
|
||||
return await call(
|
||||
"reopen", kind=DeliverableKind.DEPLOYMENT_GUIDANCE.value, reason=reason
|
||||
)
|
||||
if action == "revise_unimplementable":
|
||||
reason = " ".join(
|
||||
f"Check {item['check']} cannot be implemented as written "
|
||||
f"({item['reason']}). Rewrite it so it can be met, or remove it with "
|
||||
"a reason."
|
||||
for item in r.unimplementable
|
||||
)
|
||||
return await call(
|
||||
"reopen", kind=DeliverableKind.TARGET_ARCHITECTURE.value, reason=reason
|
||||
)
|
||||
if action == "revise_target_architecture":
|
||||
return await call(
|
||||
"reopen",
|
||||
kind=DeliverableKind.TARGET_ARCHITECTURE.value,
|
||||
reason=_graph_reason(r),
|
||||
)
|
||||
if action == "ask_about_gaps":
|
||||
result.updates["awaiting_gap_decision"] = True
|
||||
listed = "; ".join(
|
||||
[str(i.get("statement")) for i in r.additions]
|
||||
+ [
|
||||
f"Check {i.get('check')} could not be verified"
|
||||
for i in r.unverifiable
|
||||
]
|
||||
)
|
||||
question = (
|
||||
"Validation passed every Check it could, and found gaps in the "
|
||||
f"Target architecture: {listed}. Should the Target architecture "
|
||||
"be revised to close them, or shall I proceed as it stands?"
|
||||
)
|
||||
return await call("ask_user", questions=[question])
|
||||
if action == "request_approval":
|
||||
phase = (r.phases_ready or r.phases_awaiting)[0]
|
||||
return await call(
|
||||
"request_approval",
|
||||
phase=phase.value,
|
||||
summary=await self._summary(phase, view, r),
|
||||
)
|
||||
if action == "delegate":
|
||||
return await call("delegate", kinds=[kind.value for kind in r.ready_work])
|
||||
if action == "finish":
|
||||
return await call("finish")
|
||||
# escalate: no group applies.
|
||||
if view.pre_approved:
|
||||
result.outcome = Stopped(
|
||||
"No next step applies and no user is available to decide."
|
||||
)
|
||||
return None
|
||||
return await call(
|
||||
"ask_user",
|
||||
questions=["I have no next step to take. What would you like me to do?"],
|
||||
)
|
||||
|
||||
async def _summary(self, phase: PhaseId, view: TurnView, r: Readings) -> str:
|
||||
facts = approval_facts(phase, view, r)
|
||||
if self._writer is not None:
|
||||
try:
|
||||
written = await self._writer.approval_summary(phase.value, facts)
|
||||
except Exception: # a summary must never stop an Approval
|
||||
logger.exception("The reply writer failed; using the assembled summary")
|
||||
written = None
|
||||
if written and written.strip():
|
||||
return written.strip()
|
||||
return assembled_summary(phase, facts)
|
||||
|
||||
|
||||
def _graph_reason(r: Readings) -> str:
|
||||
parts = [
|
||||
f"Check {item['check']} failed in two validations in a row and may not be "
|
||||
f"implementable as written ({item['evidence']}). Rewrite it so it can be met, "
|
||||
"or remove it with a reason."
|
||||
for item in r.repeat_failed
|
||||
]
|
||||
if not r.repeat_failed:
|
||||
parts += [
|
||||
f"Check {item.get('check')} could not be verified from the code "
|
||||
f"({item.get('evidence')}). Rewrite it so it can be."
|
||||
for item in r.unverifiable
|
||||
]
|
||||
parts += [
|
||||
f"Add a Check on {item.get('applies_to')}: {item.get('statement')} "
|
||||
f"(serves {item.get('reason')})."
|
||||
for item in r.additions
|
||||
]
|
||||
return " ".join(parts)
|
||||
|
||||
|
||||
def approval_facts(phase: PhaseId, view: TurnView, r: Readings) -> dict[str, Any]:
|
||||
"""What an Approval summary is written from: data, never Deliverable prose."""
|
||||
kinds = [kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase]
|
||||
facts: dict[str, Any] = {
|
||||
"phase": phase.value,
|
||||
"deliverables": [kind.value for kind in kinds],
|
||||
"revisions": {
|
||||
kind.value: view.ledger.revisions(kind)
|
||||
for kind in kinds
|
||||
if view.ledger.revisions(kind)
|
||||
},
|
||||
}
|
||||
counts = {
|
||||
"requirements": len(
|
||||
read_list(view.deliverables, "requirements", REQUIREMENTS_FILE)
|
||||
),
|
||||
"recommendations": len(
|
||||
read_list(view.deliverables, "design_recommendations", RECOMMENDATIONS_FILE)
|
||||
),
|
||||
}
|
||||
facts["counts"] = {name: count for name, count in counts.items() if count}
|
||||
graph = read_graph(view.deliverables)
|
||||
if graph is not None:
|
||||
facts["target_architecture"] = graph.summary()
|
||||
validation = view.deliverables.get(DeliverableKind.VALIDATION_RESULTS.value)
|
||||
if (
|
||||
validation
|
||||
and phase is DEPENDENCY_GRAPH[DeliverableKind.VALIDATION_RESULTS].phase
|
||||
):
|
||||
outcome = validation_outcome(
|
||||
validation.get("attachments", {}).get(VERDICTS_FILE, "")
|
||||
)
|
||||
facts["validation"] = {
|
||||
"passed": len(outcome["passed"]),
|
||||
"failed": [item["check"] for item in outcome["failed"]],
|
||||
"not_verifiable": [item["check"] for item in outcome["not_verifiable"]],
|
||||
"open_gaps": [
|
||||
item.get("statement") for item in outcome["proposed_additions"]
|
||||
],
|
||||
}
|
||||
return facts
|
||||
|
||||
|
||||
def assembled_summary(phase: PhaseId, facts: Mapping[str, Any]) -> str:
|
||||
"""An Approval summary from the facts alone, used when no writer is available."""
|
||||
lines = [
|
||||
(
|
||||
f"The {phase.value} Phase is ready: "
|
||||
f"{', '.join(facts['deliverables'])} submitted."
|
||||
)
|
||||
]
|
||||
counts = facts.get("counts") or {}
|
||||
if counts:
|
||||
lines.append(
|
||||
", ".join(f"{count} {name}" for name, count in counts.items()) + "."
|
||||
)
|
||||
graph = facts.get("target_architecture")
|
||||
if graph:
|
||||
lines.append(
|
||||
f"Target architecture: {graph['elements']} Elements, "
|
||||
f"{graph['relationships']} Relationships, {graph['checks']} Checks."
|
||||
)
|
||||
validation = facts.get("validation")
|
||||
if validation:
|
||||
lines.append(
|
||||
f"Validation: {validation['passed']} Checks passed, "
|
||||
f"{len(validation['failed'])} failed, "
|
||||
f"{len(validation['not_verifiable'])} not verifiable."
|
||||
)
|
||||
if validation["open_gaps"]:
|
||||
lines.append(
|
||||
"Open gaps: " + "; ".join(map(str, validation["open_gaps"])) + "."
|
||||
)
|
||||
if facts.get("revisions"):
|
||||
lines.append(
|
||||
"Revised: "
|
||||
+ ", ".join(
|
||||
f"{kind} × {count}" for kind, count in facts["revisions"].items()
|
||||
)
|
||||
+ "."
|
||||
)
|
||||
return " ".join(lines)
|
||||
|
||||
|
||||
# --- the two ways an Orchestrator turn can be driven ---------------------------------
|
||||
|
||||
|
||||
class ModelOrchestrator:
|
||||
"""The Orchestrator as a reasoning agent: a language model chooses the tool calls.
|
||||
|
||||
Kept so the Ledger's rules can be driven in any order by a scripted runtime in
|
||||
tests, and so an evaluation can compare it with the router.
|
||||
"""
|
||||
|
||||
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
|
||||
self._runtime = runtime
|
||||
self._role = role
|
||||
|
||||
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
|
||||
task = AgentTask(
|
||||
role=ORCHESTRATOR,
|
||||
prompt="Decide the next step for this Execution using your tools.",
|
||||
context=view.context,
|
||||
)
|
||||
return TurnResult(await self._runtime.run(self._role, task, tools))
|
||||
|
||||
|
||||
class RuntimeReplyWriter:
|
||||
"""Writes what the user reads, on a language model. It is given a decision that
|
||||
has already been made and the facts, and it decides nothing."""
|
||||
|
||||
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
|
||||
self._runtime = runtime
|
||||
self._role = role
|
||||
|
||||
async def approval_summary(
|
||||
self, phase: str, facts: Mapping[str, Any]
|
||||
) -> str | None:
|
||||
async def write_reply(text: str) -> ToolResult:
|
||||
if not text.strip():
|
||||
return ToolResult("Not submitted: the reply is empty.")
|
||||
return ToolResult("Written.", Submitted(text))
|
||||
|
||||
tool = ToolSpec(
|
||||
"write_reply",
|
||||
"Give the text the user will read. Ends your turn.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"text": {"type": "string"}},
|
||||
"required": ["text"],
|
||||
},
|
||||
write_reply,
|
||||
tier="execution",
|
||||
)
|
||||
task = AgentTask(
|
||||
role=REPLY_WRITER,
|
||||
prompt=f"Write the summary the user will approve the {phase} Phase from.",
|
||||
context={"phase": phase, "facts": dict(facts)},
|
||||
)
|
||||
outcome = await self._runtime.run(self._role, task, [tool])
|
||||
return outcome.content if isinstance(outcome, Submitted) else None
|
||||
@@ -42,10 +42,16 @@ class McpServerSpec:
|
||||
class ModelConfig:
|
||||
default: str
|
||||
roles: Mapping[str, str] = field(default_factory=dict)
|
||||
# Seconds one model request may take, for the roles whose replies are long. A
|
||||
# role not named here gets the runtime's default.
|
||||
timeouts: Mapping[str, float] = field(default_factory=dict)
|
||||
|
||||
def for_role(self, role: str) -> str:
|
||||
return self.roles.get(role, self.default)
|
||||
|
||||
def timeout_for(self, role: str) -> float | None:
|
||||
return self.timeouts.get(role)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ProviderBundle:
|
||||
@@ -60,6 +66,9 @@ class ProviderBundle:
|
||||
role_mcp_servers: Mapping[str, tuple[str, ...]]
|
||||
role_skills: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
|
||||
pillar_skills: Mapping[str, str] = field(default_factory=dict)
|
||||
# The Terraform providers generated code is written for, pinned so the schema
|
||||
# lookup, the patterns and validation agree: {name: {source, version}}.
|
||||
terraform_providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
|
||||
|
||||
def mcp_servers_for_role(
|
||||
self, role: str, include_preview: bool = True
|
||||
@@ -108,10 +117,34 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
models = config.get("models") or {}
|
||||
if not isinstance(models.get("default"), str) or not models["default"]:
|
||||
raise fail("'models.default' is required")
|
||||
timeouts = {}
|
||||
for role, seconds in (models.get("timeout_seconds") or {}).items():
|
||||
if isinstance(seconds, bool) or not isinstance(seconds, (int, float)):
|
||||
raise fail(f"'models.timeout_seconds' for {role!r} must be a number")
|
||||
if seconds <= 0:
|
||||
raise fail(f"'models.timeout_seconds' for {role!r} must be positive")
|
||||
timeouts[str(role)] = float(seconds)
|
||||
model_config = ModelConfig(
|
||||
default=models["default"], roles=dict(models.get("roles") or {})
|
||||
default=models["default"],
|
||||
roles=dict(models.get("roles") or {}),
|
||||
timeouts=timeouts,
|
||||
)
|
||||
|
||||
terraform_providers = {}
|
||||
pins = (config.get("terraform") or {}).get("required_providers") or {}
|
||||
for provider, pin in pins.items():
|
||||
if not isinstance(pin, dict) or not all(
|
||||
isinstance(pin.get(key), str) and pin[key] for key in ("source", "version")
|
||||
):
|
||||
raise fail(
|
||||
f"terraform provider {provider!r} needs a 'source' and an exact "
|
||||
"'version', both strings"
|
||||
)
|
||||
terraform_providers[str(provider)] = {
|
||||
"source": pin["source"],
|
||||
"version": pin["version"],
|
||||
}
|
||||
|
||||
tools = {}
|
||||
for tier, tool_names in (config.get("tools") or {}).items():
|
||||
if tier not in TIERS:
|
||||
@@ -173,4 +206,5 @@ def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
role_mcp_servers=role_mcp_servers,
|
||||
role_skills=role_skills,
|
||||
pillar_skills=pillar_skills,
|
||||
terraform_providers=terraform_providers,
|
||||
)
|
||||
|
||||
@@ -82,6 +82,13 @@ class ExecutionState(TypedDict, total=False):
|
||||
refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls
|
||||
events_recorded: int
|
||||
|
||||
# Routing (ADR-0007).
|
||||
last_reply: dict[str, Any] | None # the user's message, until a turn routes it
|
||||
pending_change: dict[str, Any] | None # a change the user was asked to confirm
|
||||
awaiting_gap_decision: bool # the user was asked whether to close gaps
|
||||
validation_settled: int # the validation attempt already decided on
|
||||
decisions: list[dict[str, Any]] # every routing decision, in order
|
||||
|
||||
turns: int
|
||||
status: str # running | completed | completed_with_warnings
|
||||
warnings: list[str]
|
||||
|
||||
@@ -7,8 +7,7 @@ outcome.
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from pathlib import PurePosixPath
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import (
|
||||
@@ -21,6 +20,14 @@ from app.adk.runtime import (
|
||||
files_from_argument,
|
||||
)
|
||||
from app.states.ledger import Ledger, LedgerRefusal, PhaseStatus
|
||||
from app.tools.workspace import (
|
||||
file_tools,
|
||||
graph_text,
|
||||
graph_tools,
|
||||
keep_graph,
|
||||
safe_relative,
|
||||
working_files,
|
||||
)
|
||||
from app.workflows.deliverables import (
|
||||
DEPENDENCY_GRAPH,
|
||||
DeliverableKind,
|
||||
@@ -35,6 +42,7 @@ from app.workflows.target_architecture import (
|
||||
TargetArchitecture,
|
||||
parse_graph,
|
||||
render_mermaid,
|
||||
render_tables,
|
||||
)
|
||||
|
||||
ORCHESTRATOR = "orchestrator"
|
||||
@@ -244,29 +252,37 @@ class OrchestratorToolbox:
|
||||
return ToolResult("Finishing the Execution.", TurnEnded("finish"))
|
||||
|
||||
|
||||
def _safe_relative(name: str) -> bool:
|
||||
path = PurePosixPath(name)
|
||||
return bool(name) and not path.is_absolute() and ".." not in path.parts
|
||||
|
||||
|
||||
def specialist_tools(
|
||||
kind: DeliverableKind,
|
||||
extra: Sequence[ToolSpec],
|
||||
allow_cloud_read: bool | None,
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None = None,
|
||||
working: MutableMapping[str, Any] | None = None,
|
||||
library: 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, its working copy, 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.
|
||||
along the Requirements chain are checked. `working` is the Deliverable's working
|
||||
memory, where its working copy is kept. `library` is the earlier Deliverables
|
||||
given to the Specialist as data files alone, to read whole when it needs one.
|
||||
"""
|
||||
working = {} if working is None else working
|
||||
is_graph = kind is DeliverableKind.TARGET_ARCHITECTURE
|
||||
own_files = DEPENDENCY_GRAPH[kind].working_copy is kind
|
||||
|
||||
async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult:
|
||||
try:
|
||||
attachments = files_from_argument(attachments)
|
||||
except TypeError as exc:
|
||||
return _refused(f"attachments: {exc}")
|
||||
unsafe = [name for name in attachments if not _safe_relative(name)]
|
||||
# The working copy is the submission; a file passed here replaces its copy.
|
||||
if own_files:
|
||||
attachments = {**working_files(working), **attachments}
|
||||
if is_graph and GRAPH_ATTACHMENT not in attachments and graph_text(working):
|
||||
attachments[GRAPH_ATTACHMENT] = graph_text(working)
|
||||
unsafe = [name for name in attachments if not safe_relative(name)]
|
||||
if unsafe:
|
||||
return _refused(
|
||||
"attachment names must be relative paths without '..': "
|
||||
@@ -277,13 +293,27 @@ def specialist_tools(
|
||||
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])
|
||||
)
|
||||
if own_files:
|
||||
working_files(working).update(attachments)
|
||||
if is_graph:
|
||||
# The tables and the diagram are views of the graph, so the engine
|
||||
# writes them: they cannot disagree with it.
|
||||
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
keep_graph(working, attachments[GRAPH_ATTACHMENT])
|
||||
content = content.rstrip() + "\n\n" + render_tables(graph)
|
||||
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph)
|
||||
return ToolResult(f"Submitted {kind}.", Submitted(content, attachments))
|
||||
|
||||
async def read_deliverable(kind: str) -> ToolResult:
|
||||
deliverable = (library or {}).get(kind)
|
||||
if deliverable is None:
|
||||
available = ", ".join(library or {}) or "none"
|
||||
return _refused(f"{kind} is not one you can read here: {available}")
|
||||
attached = ", ".join(deliverable.get("attachments", {})) or "none"
|
||||
return ToolResult(
|
||||
f"{deliverable.get('content', '')}\n\nAttachments: {attached}"
|
||||
)
|
||||
|
||||
async def needs_input(
|
||||
questions: Sequence[str], draft: str | None = None, attachments: Any = None
|
||||
) -> ToolResult:
|
||||
@@ -331,6 +361,23 @@ def specialist_tools(
|
||||
needs_input,
|
||||
tier="execution",
|
||||
),
|
||||
*(
|
||||
[
|
||||
ToolSpec(
|
||||
"read_deliverable",
|
||||
"Read the full text of an earlier Deliverable that `dependencies` "
|
||||
"gives you as its data file alone: "
|
||||
f"{', '.join(library)}. Use it only when the ids are not enough.",
|
||||
_schema({"kind": {"type": "string"}}, ["kind"]),
|
||||
read_deliverable,
|
||||
tier="execution",
|
||||
)
|
||||
]
|
||||
if library
|
||||
else ()
|
||||
),
|
||||
*(graph_tools(working) if is_graph else ()),
|
||||
*(file_tools(working) if own_files else ()),
|
||||
*(gate_cloud_read(tool, allow_cloud_read) for tool in extra),
|
||||
]
|
||||
|
||||
|
||||
327
app/tools/jev.py
Normal file
327
app/tools/jev.py
Normal file
@@ -0,0 +1,327 @@
|
||||
"""The Jev decision client: typed answers to closed questions, within strict limits.
|
||||
|
||||
Jev is TypeSafe AI's decision model. This module is the only one that speaks to it,
|
||||
through the vendor's Python SDK (`typesafe-sdk`), which owns the request shape, the
|
||||
timeout and the retries. Everything else here is ours: the service's limits are not
|
||||
published, so the client assumes they are strict and never lets Jev hold up an
|
||||
Execution. Any refusal, failure or timeout returns None and the caller takes its
|
||||
fallback.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import hashlib
|
||||
import json
|
||||
import logging
|
||||
import time
|
||||
from collections import OrderedDict, deque
|
||||
from collections.abc import Awaitable, Callable, Mapping
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from typesafe_sdk import (
|
||||
AsyncTypeSafeClient,
|
||||
Choice,
|
||||
ChoiceAnswer,
|
||||
Noul,
|
||||
NoulAnswer,
|
||||
RetryPolicy,
|
||||
Score,
|
||||
ScoreAnswer,
|
||||
TypeSafeError,
|
||||
TypeSafeRateLimitError,
|
||||
)
|
||||
|
||||
from app.adk.runtime import Answer, Question
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class JevLimits:
|
||||
"""Every limit the client keeps. Starting values, to tune from measurement."""
|
||||
|
||||
max_tokens: int = 48_000 # state plus questions; the service allows 64,000
|
||||
max_question_tokens: int = 24_000 # state plus the longest question; allows 32,000
|
||||
request_timeout: float = 5.0 # one HTTP attempt
|
||||
total_timeout: float = 15.0 # a decision, retries included
|
||||
retries: int = 2
|
||||
backoff_base: float = 0.5
|
||||
backoff_cap: float = 8.0
|
||||
requests_per_second: float = 5.0
|
||||
burst: int = 10
|
||||
max_in_flight: int = 8
|
||||
breaker_failures: int = 5
|
||||
breaker_window: float = 30.0
|
||||
breaker_cooldown: float = 60.0
|
||||
cache_size: int = 1024
|
||||
budget_calls: int = 500 # per scope, usually one Execution
|
||||
budget_tokens: int = 1_000_000 # per scope; about $0.42 at the published price
|
||||
|
||||
|
||||
@dataclass
|
||||
class DecisionRecord:
|
||||
"""One attempt to decide, kept for the evaluation report and for tuning."""
|
||||
|
||||
scope: str
|
||||
questions: tuple[str, ...]
|
||||
# answered | cached | too_large | over_budget | breaker_open | failed
|
||||
outcome: str = "failed"
|
||||
seconds: float = 0.0
|
||||
rate_limited: bool = False
|
||||
input_tokens: int = 0
|
||||
confidence: Mapping[str, float] = field(default_factory=dict)
|
||||
|
||||
|
||||
def estimate_tokens(text: str) -> int:
|
||||
"""A deliberately high estimate: refusing locally is cheaper than a rejected call."""
|
||||
return len(text) // 3 + 1
|
||||
|
||||
|
||||
def encode_question(question: Question) -> Noul | Choice | Score:
|
||||
if question.kind == "choice":
|
||||
return Choice(
|
||||
instructions=question.instructions,
|
||||
criteria=dict.fromkeys(question.options),
|
||||
)
|
||||
if question.kind == "score":
|
||||
return Score(
|
||||
instructions=question.instructions, criteria=list(question.options)
|
||||
)
|
||||
return Noul(instructions=question.instructions)
|
||||
|
||||
|
||||
def decode_answer(question: Question, raw: object) -> Answer | None:
|
||||
"""The SDK's answer as ours, or None when it does not answer the question asked."""
|
||||
if question.kind == "choice" and isinstance(raw, ChoiceAnswer):
|
||||
# A choice outside the options asked for is not an answer.
|
||||
if raw.choice not in question.options:
|
||||
return None
|
||||
return Answer(raw.choice, raw.confidence, dict(raw.probabilities))
|
||||
if question.kind == "score" and isinstance(raw, ScoreAnswer):
|
||||
probabilities = {str(level): p for level, p in raw.probabilities.items()}
|
||||
return Answer(raw.score, raw.confidence, probabilities)
|
||||
if question.kind == "noul" and isinstance(raw, NoulAnswer):
|
||||
# Jev gives a probability for a yes-or-no question and no separate
|
||||
# confidence, so confidence is how far the probability is from even.
|
||||
return Answer(raw.noul, abs(2 * raw.noul - 1))
|
||||
return None
|
||||
|
||||
|
||||
class JevDecider:
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
api_key: str,
|
||||
base_url: str | None = None,
|
||||
model: str | None = None,
|
||||
limits: JevLimits | None = None,
|
||||
transport: Any = None,
|
||||
clock: Callable[[], float] = time.monotonic,
|
||||
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
|
||||
) -> None:
|
||||
self.limits = limits or JevLimits()
|
||||
self._clock = clock
|
||||
self._sleep = sleep
|
||||
self._client = AsyncTypeSafeClient(
|
||||
api_key=api_key,
|
||||
base_url=base_url,
|
||||
model=model,
|
||||
timeout=self.limits.request_timeout,
|
||||
# The SDK retries 408, 429 and 5xx, and connection and timeout errors,
|
||||
# with jittered backoff, and honours Retry-After.
|
||||
retry=RetryPolicy(
|
||||
max_retries=self.limits.retries,
|
||||
backoff_initial=self.limits.backoff_base,
|
||||
backoff_max=self.limits.backoff_cap,
|
||||
timeout=self.limits.total_timeout,
|
||||
),
|
||||
transport=transport,
|
||||
)
|
||||
self._in_flight = asyncio.Semaphore(self.limits.max_in_flight)
|
||||
# Token bucket: starts full, refills at `rate`, which drops when the service
|
||||
# says we are going too fast.
|
||||
self._rate = self.limits.requests_per_second
|
||||
self._tokens = float(self.limits.burst)
|
||||
self._refilled = clock()
|
||||
self._bucket = asyncio.Lock()
|
||||
self._failures: deque[float] = deque()
|
||||
self._open_until = 0.0
|
||||
self._probing = False
|
||||
self._cache: OrderedDict[str, dict[str, Answer]] = OrderedDict()
|
||||
self._calls: dict[str, int] = {}
|
||||
self._tokens_used: dict[str, int] = {}
|
||||
self._over_budget: set[str] = set()
|
||||
self.records: list[DecisionRecord] = []
|
||||
|
||||
async def aclose(self) -> None:
|
||||
await self._client.aclose()
|
||||
|
||||
async def decide(
|
||||
self, state: str, questions: Mapping[str, Question], *, scope: str = ""
|
||||
) -> Mapping[str, Answer] | None:
|
||||
record = DecisionRecord(scope=scope, questions=tuple(questions))
|
||||
self.records.append(record)
|
||||
started = self._clock()
|
||||
try:
|
||||
return await self._decide(state, questions, scope, record)
|
||||
finally:
|
||||
record.seconds = self._clock() - started
|
||||
|
||||
async def _decide(
|
||||
self,
|
||||
state: str,
|
||||
questions: Mapping[str, Question],
|
||||
scope: str,
|
||||
record: DecisionRecord,
|
||||
) -> Mapping[str, Answer] | None:
|
||||
if not questions:
|
||||
record.outcome = "answered"
|
||||
return {}
|
||||
|
||||
asked = {
|
||||
name: {
|
||||
"kind": question.kind,
|
||||
"instructions": question.instructions,
|
||||
"options": list(question.options),
|
||||
}
|
||||
for name, question in questions.items()
|
||||
}
|
||||
sizes = [estimate_tokens(json.dumps(item)) for item in asked.values()]
|
||||
state_size = estimate_tokens(state)
|
||||
if (
|
||||
state_size + sum(sizes) > self.limits.max_tokens
|
||||
or state_size + max(sizes) > self.limits.max_question_tokens
|
||||
):
|
||||
# Never truncate: the caller must split by Deliverable or section.
|
||||
record.outcome = "too_large"
|
||||
return None
|
||||
|
||||
key = hashlib.sha256(
|
||||
json.dumps({"state": state, "questions": asked}, sort_keys=True).encode()
|
||||
).hexdigest()
|
||||
if key in self._cache:
|
||||
self._cache.move_to_end(key)
|
||||
record.outcome = "cached"
|
||||
return dict(self._cache[key])
|
||||
|
||||
if (
|
||||
self._calls.get(scope, 0) >= self.limits.budget_calls
|
||||
or self._tokens_used.get(scope, 0) >= self.limits.budget_tokens
|
||||
):
|
||||
if scope not in self._over_budget:
|
||||
self._over_budget.add(scope)
|
||||
logger.warning("Jev budget reached for %s; using fallbacks", scope)
|
||||
record.outcome = "over_budget"
|
||||
return None
|
||||
|
||||
if not self._breaker_allows():
|
||||
record.outcome = "breaker_open"
|
||||
return None
|
||||
|
||||
self._calls[scope] = self._calls.get(scope, 0) + 1
|
||||
await self._take_token()
|
||||
try:
|
||||
async with self._in_flight:
|
||||
response = await self._client.system_one(
|
||||
state=state,
|
||||
questions={
|
||||
name: encode_question(question)
|
||||
for name, question in questions.items()
|
||||
},
|
||||
)
|
||||
except TypeSafeRateLimitError:
|
||||
# Still rate limited after the SDK's retries: halve our own rate.
|
||||
record.rate_limited = True
|
||||
self._rate = max(self._rate / 2, 0.25)
|
||||
self._note_failure()
|
||||
return None
|
||||
except TypeSafeError as exc:
|
||||
logger.info("Jev request failed: %s", type(exc).__name__)
|
||||
self._note_failure()
|
||||
return None
|
||||
self._note_success()
|
||||
|
||||
used = response.usage.input_tokens or 0
|
||||
record.input_tokens = used
|
||||
self._tokens_used[scope] = self._tokens_used.get(scope, 0) + used
|
||||
|
||||
answers: dict[str, Answer] = {}
|
||||
for name, question in questions.items():
|
||||
answer = decode_answer(question, response.answers.get(name))
|
||||
if answer is None:
|
||||
# A reply that does not answer every question answers none.
|
||||
return None
|
||||
answers[name] = answer
|
||||
|
||||
record.outcome = "answered"
|
||||
record.confidence = {name: a.confidence for name, a in answers.items()}
|
||||
self._cache[key] = answers
|
||||
while len(self._cache) > self.limits.cache_size:
|
||||
self._cache.popitem(last=False)
|
||||
return dict(answers)
|
||||
|
||||
async def _take_token(self) -> None:
|
||||
async with self._bucket:
|
||||
while True:
|
||||
now = self._clock()
|
||||
self._tokens = min(
|
||||
float(self.limits.burst),
|
||||
self._tokens + (now - self._refilled) * self._rate,
|
||||
)
|
||||
self._refilled = now
|
||||
if self._tokens >= 1:
|
||||
self._tokens -= 1
|
||||
return
|
||||
await self._sleep((1 - self._tokens) / self._rate)
|
||||
|
||||
def _breaker_allows(self) -> bool:
|
||||
now = self._clock()
|
||||
if now < self._open_until:
|
||||
return False
|
||||
if self._open_until and not self._probing:
|
||||
# Cool-down over: let exactly one call through to test the service.
|
||||
self._probing = True
|
||||
return True
|
||||
|
||||
def _note_failure(self) -> None:
|
||||
now = self._clock()
|
||||
if self._probing:
|
||||
self._probing = False
|
||||
self._open_until = now + self.limits.breaker_cooldown
|
||||
return
|
||||
self._failures.append(now)
|
||||
while self._failures and now - self._failures[0] > self.limits.breaker_window:
|
||||
self._failures.popleft()
|
||||
if len(self._failures) >= self.limits.breaker_failures:
|
||||
self._failures.clear()
|
||||
self._open_until = now + self.limits.breaker_cooldown
|
||||
logger.warning(
|
||||
"Jev circuit open for %.0fs after repeated failures",
|
||||
self.limits.breaker_cooldown,
|
||||
)
|
||||
|
||||
def _note_success(self) -> None:
|
||||
self._failures.clear()
|
||||
self._open_until = 0.0
|
||||
self._probing = False
|
||||
|
||||
def summary(self) -> dict[str, Any]:
|
||||
"""Totals for the evaluation report."""
|
||||
outcomes: dict[str, int] = {}
|
||||
for record in self.records:
|
||||
outcomes[record.outcome] = outcomes.get(record.outcome, 0) + 1
|
||||
answered = [r for r in self.records if r.outcome == "answered"]
|
||||
return {
|
||||
"decisions": len(self.records),
|
||||
"outcomes": outcomes,
|
||||
"fallbacks": sum(
|
||||
count
|
||||
for name, count in outcomes.items()
|
||||
if name not in {"answered", "cached"}
|
||||
),
|
||||
"rate_limited": sum(1 for r in self.records if r.rate_limited),
|
||||
"seconds": round(sum(r.seconds for r in answered), 3),
|
||||
"input_tokens": sum(r.input_tokens for r in self.records),
|
||||
}
|
||||
@@ -1,16 +1,23 @@
|
||||
"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
|
||||
|
||||
Terraform runs only fmt, init -backend=false, validate and plan. No command that
|
||||
changes cloud resources is ever constructed.
|
||||
Terraform runs only fmt, init -backend=false, validate, plan and providers schema. No
|
||||
command that changes cloud resources is ever constructed.
|
||||
|
||||
A Specialist with a working copy (app/tools/workspace.py) runs the checks on it and
|
||||
passes no files; `terraform_fmt` formats the working copy in place. That is what
|
||||
keeps a fix cheap: the model changes a line and validates, without sending every file
|
||||
again on each call.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import difflib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
from collections.abc import Awaitable, Callable, Iterable, Mapping
|
||||
from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
@@ -79,10 +86,19 @@ class TerraformRunner:
|
||||
# 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
|
||||
# The providers the schema lookup answers for, as the provider bundle pins them:
|
||||
# {local name: {"source": ..., "version": ...}}.
|
||||
providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
|
||||
# Terraform's plugin cache is not safe for concurrent installs.
|
||||
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
|
||||
_schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
|
||||
# resource type -> (provider label, the resource's schema block)
|
||||
_schemas: dict[str, tuple[str, dict[str, Any]]] | None = field(
|
||||
default=None, repr=False
|
||||
)
|
||||
|
||||
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
|
||||
async def formatted(self, files: Mapping[str, str]) -> dict[str, str] | ToolResult:
|
||||
"""The files formatting changes, with their new content; or why it failed."""
|
||||
refusal = _check_files(files)
|
||||
if refusal:
|
||||
return refusal
|
||||
@@ -93,19 +109,24 @@ class TerraformRunner:
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(f"terraform fmt failed:\n{output}")
|
||||
changed = [
|
||||
name for name in files if (root / name).read_text() != files[name]
|
||||
]
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
formatted = "\n\n".join(
|
||||
f"--- {name}\n{(root / name).read_text()}" for name in changed
|
||||
)
|
||||
return ToolResult(
|
||||
_clip(
|
||||
f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}"
|
||||
)
|
||||
)
|
||||
return {
|
||||
name: (root / name).read_text()
|
||||
for name in files
|
||||
if (root / name).read_text() != files[name]
|
||||
}
|
||||
|
||||
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
|
||||
changed = await self.formatted(files)
|
||||
if isinstance(changed, ToolResult):
|
||||
return changed
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
formatted = "\n\n".join(
|
||||
f"--- {name}\n{content}" for name, content in changed.items()
|
||||
)
|
||||
return ToolResult(
|
||||
_clip(f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}")
|
||||
)
|
||||
|
||||
async def validate(self, files: Mapping[str, str]) -> ToolResult:
|
||||
refusal = _check_files(files)
|
||||
@@ -150,6 +171,87 @@ class TerraformRunner:
|
||||
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
|
||||
)
|
||||
|
||||
async def schema(
|
||||
self, resource_type: str, block: str = "", find: str = ""
|
||||
) -> ToolResult:
|
||||
"""What a resource type accepts, from the pinned provider's own schema."""
|
||||
loaded = await self._load_schemas()
|
||||
if isinstance(loaded, ToolResult):
|
||||
return loaded
|
||||
if resource_type not in loaded:
|
||||
close = difflib.get_close_matches(resource_type, loaded, n=5, cutoff=0.6)
|
||||
hint = f" Close matches: {', '.join(close)}." if close else ""
|
||||
return ToolResult(
|
||||
f"No resource type {resource_type} in {self._provider_labels()}.{hint}"
|
||||
)
|
||||
label, root = loaded[resource_type]
|
||||
title = f"{resource_type} ({label})"
|
||||
if find:
|
||||
return ToolResult(_clip(_find_in_schema(title, root, find)))
|
||||
node = root
|
||||
for step in [part for part in block.split(".") if part]:
|
||||
nested = node.get("block_types", {}).get(step)
|
||||
if nested is None:
|
||||
inside = ", ".join(sorted(node.get("block_types", {}))) or "none"
|
||||
return ToolResult(
|
||||
f"{title} has no block {block!r}: {step!r} is not a block there. "
|
||||
f"Blocks at that level: {inside}."
|
||||
)
|
||||
node = nested["block"]
|
||||
heading = f"{title}, block {block}" if block else title
|
||||
return ToolResult(_clip(_render_schema(heading, node)))
|
||||
|
||||
def _provider_labels(self) -> str:
|
||||
return (
|
||||
", ".join(
|
||||
f"{pin['source']} {pin['version']}" for pin in self.providers.values()
|
||||
)
|
||||
or "no pinned provider"
|
||||
)
|
||||
|
||||
async def _load_schemas(self) -> dict[str, tuple[str, dict[str, Any]]] | ToolResult:
|
||||
async with self._schema_lock:
|
||||
if self._schemas is not None:
|
||||
return self._schemas
|
||||
if not self.providers:
|
||||
return ToolResult(
|
||||
"Schema lookup is unavailable: the Cloud provider bundle pins no "
|
||||
"Terraform provider."
|
||||
)
|
||||
required = "\n".join(
|
||||
f' {name} = {{ source = "{pin["source"]}", '
|
||||
f'version = "{pin["version"]}" }}'
|
||||
for name, pin in self.providers.items()
|
||||
)
|
||||
with tempfile.TemporaryDirectory(prefix="tf-schema-") as tmp:
|
||||
root = Path(tmp)
|
||||
(root / "versions.tf").write_text(
|
||||
f"terraform {{\n required_providers {{\n{required}\n }}\n}}\n"
|
||||
)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
code, output = await self._run(
|
||||
[self.binary, "providers", "schema", "-json"], root
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(
|
||||
_clip(f"terraform providers schema failed:\n{output}")
|
||||
)
|
||||
try:
|
||||
data = json.loads(output)
|
||||
except ValueError:
|
||||
return ToolResult("terraform providers schema returned no JSON.")
|
||||
labels = {pin["source"]: pin["version"] for pin in self.providers.values()}
|
||||
schemas: dict[str, tuple[str, dict[str, Any]]] = {}
|
||||
for address, provider in (data.get("provider_schemas") or {}).items():
|
||||
source = address.split("/", 1)[-1] # drop the registry host
|
||||
label = f"{source} {labels.get(source, '')}".strip()
|
||||
for name, resource in (provider.get("resource_schemas") or {}).items():
|
||||
schemas[name] = (label, resource.get("block") or {})
|
||||
self._schemas = schemas
|
||||
return schemas
|
||||
|
||||
async def _init(self, root: Path) -> ToolResult | None:
|
||||
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
|
||||
if self.plugin_cache_dir:
|
||||
@@ -236,6 +338,100 @@ def _clip(text: str) -> str:
|
||||
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
|
||||
|
||||
|
||||
def _type(value: Any) -> str:
|
||||
if isinstance(value, str):
|
||||
return value
|
||||
if isinstance(value, list) and len(value) == 2 and value[0] != "object":
|
||||
return f"{value[0]} of {_type(value[1])}"
|
||||
return "object"
|
||||
|
||||
|
||||
def _use(attribute: Mapping[str, Any]) -> str:
|
||||
if attribute.get("required"):
|
||||
return "required"
|
||||
return "optional" if attribute.get("optional") else "read-only"
|
||||
|
||||
|
||||
def _arguments(node: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
|
||||
"""The arguments code may set: everything but the read-only ones."""
|
||||
return {
|
||||
name: attribute
|
||||
for name, attribute in sorted((node.get("attributes") or {}).items())
|
||||
if _use(attribute) != "read-only"
|
||||
}
|
||||
|
||||
|
||||
def _block_note(nested: Mapping[str, Any]) -> str:
|
||||
notes = [str(nested.get("nesting_mode", "block"))]
|
||||
if nested.get("min_items"):
|
||||
notes.append(f"at least {nested['min_items']}")
|
||||
if nested.get("max_items"):
|
||||
notes.append(f"at most {nested['max_items']}")
|
||||
return ", ".join(notes)
|
||||
|
||||
|
||||
def _render_schema(heading: str, node: Mapping[str, Any]) -> str:
|
||||
"""One level in full, and the blocks beneath it as an outline of names."""
|
||||
lines = [heading, "", "Arguments:"]
|
||||
arguments = _arguments(node)
|
||||
for name, attribute in arguments.items():
|
||||
described = " ".join(str(attribute.get("description") or "").split())[:160]
|
||||
deprecated = " DEPRECATED" if attribute.get("deprecated") else ""
|
||||
lines.append(
|
||||
f" {name} ({_type(attribute.get('type'))}, {_use(attribute)})"
|
||||
f"{deprecated}" + (f": {described}" if described else "")
|
||||
)
|
||||
if not arguments:
|
||||
lines.append(" none")
|
||||
|
||||
def outline(parent: Mapping[str, Any], depth: int) -> None:
|
||||
for name, nested in sorted((parent.get("block_types") or {}).items()):
|
||||
inner = nested.get("block") or {}
|
||||
names = ", ".join(
|
||||
f"{argument}*" if attribute.get("required") else argument
|
||||
for argument, attribute in _arguments(inner).items()
|
||||
)
|
||||
lines.append(
|
||||
f"{' ' * depth}{name} {{ }} ({_block_note(nested)}): {names or '-'}"
|
||||
)
|
||||
outline(inner, depth + 1)
|
||||
|
||||
lines += ["", "Blocks (* marks a required argument):"]
|
||||
before = len(lines)
|
||||
outline(node, 1)
|
||||
if len(lines) == before:
|
||||
lines.append(" none")
|
||||
lines += ["", "Pass `block`, such as a.b, for one block's arguments in full."]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _find_in_schema(title: str, root: Mapping[str, Any], wanted: str) -> str:
|
||||
"""Every argument or block whose name contains `wanted`, with where it sits."""
|
||||
needle = wanted.lower()
|
||||
found: list[str] = []
|
||||
|
||||
def search(node: Mapping[str, Any], path: str) -> None:
|
||||
for name, attribute in sorted((node.get("attributes") or {}).items()):
|
||||
if needle in name.lower():
|
||||
where = f"{path}.{name}" if path else name
|
||||
found.append(
|
||||
f" {where} ({_type(attribute.get('type'))}, {_use(attribute)})"
|
||||
)
|
||||
for name, nested in sorted((node.get("block_types") or {}).items()):
|
||||
where = f"{path}.{name}" if path else name
|
||||
if needle in name.lower():
|
||||
found.append(f" {where} {{ }} ({_block_note(nested)})")
|
||||
search(nested.get("block") or {}, where)
|
||||
|
||||
search(root, "")
|
||||
if not found:
|
||||
return (
|
||||
f"{title} has no argument or block named like {wanted!r}. It cannot be "
|
||||
"set on this resource type."
|
||||
)
|
||||
return f"{title}: {wanted!r} is found at\n" + "\n".join(found)
|
||||
|
||||
|
||||
_FILES_SCHEMA: dict[str, Any] = {
|
||||
**FILES_SCHEMA,
|
||||
"description": "Terraform files in one directory, e.g. terraform/main.tf",
|
||||
@@ -244,19 +440,53 @@ _FILES_SCHEMA: dict[str, Any] = {
|
||||
|
||||
def _with_files(
|
||||
method: Callable[..., Awaitable[ToolResult]],
|
||||
working_copy: MutableMapping[str, str] | None = None,
|
||||
) -> Callable[..., Awaitable[ToolResult]]:
|
||||
"""Adapt a runner method to take the FILES_SCHEMA argument."""
|
||||
"""Adapt a runner method to take the FILES_SCHEMA argument.
|
||||
|
||||
async def handler(files: Any, **kwargs: Any) -> ToolResult:
|
||||
With a working copy, the files are the Terraform files in it and the argument is
|
||||
optional: files passed anyway are written to the working copy first.
|
||||
"""
|
||||
|
||||
async def handler(files: Any = None, **kwargs: Any) -> ToolResult:
|
||||
try:
|
||||
converted = files_from_argument(files)
|
||||
except TypeError as exc:
|
||||
return ToolResult(f"Refused: files: {exc}")
|
||||
return await method(converted, **kwargs)
|
||||
if working_copy is None:
|
||||
return await method(converted, **kwargs)
|
||||
working_copy.update(converted)
|
||||
return await method(_terraform_files(working_copy), **kwargs)
|
||||
|
||||
return handler
|
||||
|
||||
|
||||
def _terraform_files(files: Mapping[str, str]) -> dict[str, str]:
|
||||
return {
|
||||
name: content
|
||||
for name, content in files.items()
|
||||
if name.endswith(_TERRAFORM_SUFFIXES)
|
||||
}
|
||||
|
||||
|
||||
def _fmt_in_place(
|
||||
runner: TerraformRunner, working_copy: MutableMapping[str, str]
|
||||
) -> Callable[..., Awaitable[ToolResult]]:
|
||||
async def format_working_copy(files: Mapping[str, str]) -> ToolResult:
|
||||
changed = await runner.formatted(files)
|
||||
if isinstance(changed, ToolResult):
|
||||
return changed
|
||||
working_copy.update(changed)
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
return ToolResult(
|
||||
f"terraform fmt reformatted {len(changed)} file(s) in your working "
|
||||
f"copy: {', '.join(sorted(changed))}."
|
||||
)
|
||||
|
||||
return _with_files(format_working_copy, working_copy)
|
||||
|
||||
|
||||
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
||||
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
|
||||
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
|
||||
@@ -268,10 +498,48 @@ LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
||||
"cloud_read",
|
||||
"Preview Terraform against the live cloud environment with a plan. Never applies.",
|
||||
),
|
||||
"terraform_schema": (
|
||||
"general",
|
||||
(
|
||||
"Look up what a Terraform resource type accepts, from the provider's own "
|
||||
"schema: its arguments and blocks, one block in full with `block`, or "
|
||||
"whether an argument exists anywhere in it with `find`."
|
||||
),
|
||||
),
|
||||
}
|
||||
|
||||
_ON_WORKING_COPY = " Runs on your working copy; pass no files."
|
||||
|
||||
|
||||
def local_tools(
|
||||
names: Iterable[str],
|
||||
runner: TerraformRunner,
|
||||
working_copy: MutableMapping[str, str] | None = None,
|
||||
) -> list[ToolSpec]:
|
||||
"""The named tools. With a `working_copy`, the Terraform checks run on it."""
|
||||
files_required = [] if working_copy is not None else ["files"]
|
||||
suffix = _ON_WORKING_COPY if working_copy is not None else ""
|
||||
|
||||
def checks(name: str, method: Callable[..., Awaitable[ToolResult]]) -> ToolSpec:
|
||||
properties: dict[str, Any] = {"files": _FILES_SCHEMA}
|
||||
if name == "terraform_plan":
|
||||
properties["variables"] = {
|
||||
"type": "object",
|
||||
"additionalProperties": {"type": "string"},
|
||||
}
|
||||
tier, description = LOCAL_TOOLS[name]
|
||||
return ToolSpec(
|
||||
name,
|
||||
description + suffix,
|
||||
{
|
||||
"type": "object",
|
||||
"properties": properties,
|
||||
"required": files_required,
|
||||
},
|
||||
method,
|
||||
tier=tier,
|
||||
)
|
||||
|
||||
def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]:
|
||||
builders = {
|
||||
"mermaid_check": lambda: ToolSpec(
|
||||
"mermaid_check",
|
||||
@@ -284,44 +552,41 @@ def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]
|
||||
mermaid_check,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_fmt": lambda: ToolSpec(
|
||||
"terraform_fmt": lambda: checks(
|
||||
"terraform_fmt",
|
||||
LOCAL_TOOLS["terraform_fmt"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
_with_files(runner.fmt),
|
||||
tier="general",
|
||||
_fmt_in_place(runner, working_copy)
|
||||
if working_copy is not None
|
||||
else _with_files(runner.fmt),
|
||||
),
|
||||
"terraform_validate": lambda: ToolSpec(
|
||||
"terraform_validate",
|
||||
LOCAL_TOOLS["terraform_validate"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"files": _FILES_SCHEMA},
|
||||
"required": ["files"],
|
||||
},
|
||||
_with_files(runner.validate),
|
||||
tier="general",
|
||||
"terraform_validate": lambda: checks(
|
||||
"terraform_validate", _with_files(runner.validate, working_copy)
|
||||
),
|
||||
"terraform_plan": lambda: ToolSpec(
|
||||
"terraform_plan",
|
||||
LOCAL_TOOLS["terraform_plan"][1],
|
||||
"terraform_plan": lambda: checks(
|
||||
"terraform_plan", _with_files(runner.plan, working_copy)
|
||||
),
|
||||
"terraform_schema": lambda: ToolSpec(
|
||||
"terraform_schema",
|
||||
LOCAL_TOOLS["terraform_schema"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"files": _FILES_SCHEMA,
|
||||
"variables": {
|
||||
"type": "object",
|
||||
"additionalProperties": {"type": "string"},
|
||||
"resource_type": {
|
||||
"type": "string",
|
||||
"description": "For example google_cloud_run_v2_service",
|
||||
},
|
||||
"block": {
|
||||
"type": "string",
|
||||
"description": "A nested block, such as template.containers",
|
||||
},
|
||||
"find": {
|
||||
"type": "string",
|
||||
"description": "An argument or block name to look for",
|
||||
},
|
||||
},
|
||||
"required": ["files"],
|
||||
"required": ["resource_type"],
|
||||
},
|
||||
_with_files(runner.plan),
|
||||
tier="cloud_read",
|
||||
runner.schema,
|
||||
tier="general",
|
||||
),
|
||||
}
|
||||
return [builders[name]() for name in names]
|
||||
|
||||
@@ -2,19 +2,24 @@
|
||||
|
||||
A role gets the local tools its role file names, the tools of the remote MCP servers
|
||||
the provider bundle assigns it, and, for the design advisor, the pillar consultation.
|
||||
When the Deliverable has a working copy, the local tools are built on it.
|
||||
Cloud-read gating is applied later, per Execution, by `specialist_tools`.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from collections.abc import Callable, Mapping, MutableMapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.adk.roles import PILLAR_ADVISOR
|
||||
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
|
||||
from app.tools.workspace import working_files
|
||||
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
|
||||
|
||||
# The local tools, built on a working copy of files when the Deliverable has one.
|
||||
LocalToolBuilder = Callable[[MutableMapping[str, str] | None], Sequence[ToolSpec]]
|
||||
|
||||
|
||||
def make_tool_factory(
|
||||
@@ -22,11 +27,14 @@ def make_tool_factory(
|
||||
roles: Mapping[str, RoleSpec],
|
||||
pillar_skills: Mapping[str, str],
|
||||
*,
|
||||
local_tools: Sequence[ToolSpec] = (),
|
||||
local_tools: Sequence[ToolSpec] | LocalToolBuilder = (),
|
||||
catalog: McpCatalog | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
) -> ToolFactory:
|
||||
local_by_name = {tool.name: tool for tool in local_tools}
|
||||
def build_local(
|
||||
working_copy: MutableMapping[str, str] | None,
|
||||
) -> Sequence[ToolSpec]:
|
||||
return local_tools(working_copy) if callable(local_tools) else local_tools
|
||||
|
||||
def mcp_tools(role: RoleSpec) -> list[ToolSpec]:
|
||||
return catalog.tools_for(role.mcp_servers) if catalog else []
|
||||
@@ -42,6 +50,16 @@ def make_tool_factory(
|
||||
def tools_for(
|
||||
role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any]
|
||||
) -> Sequence[ToolSpec]:
|
||||
has_working_copy = any(
|
||||
kind.value == deliverable and spec.working_copy is not None
|
||||
for kind, spec in DEPENDENCY_GRAPH.items()
|
||||
)
|
||||
local_by_name = {
|
||||
tool.name: tool
|
||||
for tool in build_local(
|
||||
working_files(working) if has_working_copy else None
|
||||
)
|
||||
}
|
||||
tools = [local_by_name[name] for name in role.tools if name in local_by_name]
|
||||
tools += mcp_tools(role)
|
||||
if (
|
||||
|
||||
289
app/tools/workspace.py
Normal file
289
app/tools/workspace.py
Normal file
@@ -0,0 +1,289 @@
|
||||
"""A Specialist's working copy: files and a graph built up over several tool calls.
|
||||
|
||||
A model that must return a whole Deliverable in one reply spends most of its output
|
||||
repeating itself, and a long reply is what times out. With a working copy it writes a
|
||||
file once, changes only the lines that need changing, and adds to a graph a few items
|
||||
at a time. The working copy is kept with the Execution, so a Revision starts from the
|
||||
last attempt instead of from nothing.
|
||||
|
||||
It lives in the Deliverable's working memory:
|
||||
|
||||
working["files"] {path: content}
|
||||
working["graph"] the Target architecture, as target-architecture.json holds it
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from pathlib import PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from app.adk.runtime import ToolResult, ToolSpec
|
||||
|
||||
FILES = "files"
|
||||
GRAPH = "graph"
|
||||
_GRAPH_LISTS = ("elements", "relationships", "checks", "not_applicable")
|
||||
_MAX_READ = 40_000
|
||||
|
||||
|
||||
def safe_relative(name: str) -> bool:
|
||||
path = PurePosixPath(name)
|
||||
return bool(name) and not path.is_absolute() and ".." not in path.parts
|
||||
|
||||
|
||||
def working_files(working: MutableMapping[str, Any]) -> MutableMapping[str, str]:
|
||||
files = working.get(FILES)
|
||||
if not isinstance(files, MutableMapping):
|
||||
files = working[FILES] = {}
|
||||
return files
|
||||
|
||||
|
||||
def _schema(properties: Mapping[str, Any], required: Sequence[str]) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "object",
|
||||
"properties": dict(properties),
|
||||
"required": list(required),
|
||||
}
|
||||
|
||||
|
||||
def _lines(content: str) -> int:
|
||||
return content.count("\n") + (1 if content and not content.endswith("\n") else 0)
|
||||
|
||||
|
||||
def file_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
|
||||
"""Tools that write, change and read the files of a working copy."""
|
||||
files = working_files(working)
|
||||
|
||||
async def write_file(path: str, content: str) -> ToolResult:
|
||||
if not safe_relative(path):
|
||||
return ToolResult(
|
||||
f"Refused: {path!r} must be a relative path without '..'."
|
||||
)
|
||||
files[path] = content
|
||||
return ToolResult(f"Wrote {path} ({_lines(content)} lines).")
|
||||
|
||||
async def edit_file(path: str, old: str, new: str) -> ToolResult:
|
||||
if path not in files:
|
||||
return ToolResult(f"Refused: {path} is not in your working copy.")
|
||||
found = files[path].count(old) if old else 0
|
||||
if found != 1:
|
||||
return ToolResult(
|
||||
f"Refused: `old` must match exactly one place in {path}; it matches "
|
||||
f"{found}. Include more of the surrounding lines."
|
||||
)
|
||||
files[path] = files[path].replace(old, new)
|
||||
return ToolResult(f"Edited {path}.")
|
||||
|
||||
async def read_file(path: str = "") -> ToolResult:
|
||||
if not path:
|
||||
if not files:
|
||||
return ToolResult("Your working copy is empty.")
|
||||
return ToolResult(
|
||||
"Your working copy:\n"
|
||||
+ "\n".join(
|
||||
f"- {name} ({_lines(files[name])} lines)" for name in sorted(files)
|
||||
)
|
||||
)
|
||||
if path not in files:
|
||||
return ToolResult(f"Refused: {path} is not in your working copy.")
|
||||
content = files[path]
|
||||
if len(content) > _MAX_READ:
|
||||
content = content[:_MAX_READ] + "\n[truncated]"
|
||||
return ToolResult(content)
|
||||
|
||||
async def delete_file(path: str) -> ToolResult:
|
||||
if files.pop(path, None) is None:
|
||||
return ToolResult(f"Refused: {path} is not in your working copy.")
|
||||
return ToolResult(f"Deleted {path}.")
|
||||
|
||||
text = {"type": "string"}
|
||||
return [
|
||||
ToolSpec(
|
||||
"write_file",
|
||||
"Write one file of your working copy, replacing it if it exists. Your "
|
||||
"working copy is attached for you when you submit.",
|
||||
_schema({"path": text, "content": text}, ["path", "content"]),
|
||||
write_file,
|
||||
),
|
||||
ToolSpec(
|
||||
"edit_file",
|
||||
"Change part of one file: replace the single place `old` matches with "
|
||||
"`new`. Use this for a fix instead of writing the file again.",
|
||||
_schema({"path": text, "old": text, "new": text}, ["path", "old", "new"]),
|
||||
edit_file,
|
||||
),
|
||||
ToolSpec(
|
||||
"read_file",
|
||||
"Read one file of your working copy, or list its files when `path` is "
|
||||
"left out.",
|
||||
_schema({"path": text}, []),
|
||||
read_file,
|
||||
),
|
||||
ToolSpec(
|
||||
"delete_file",
|
||||
"Remove one file from your working copy.",
|
||||
_schema({"path": text}, ["path"]),
|
||||
delete_file,
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
# --- the graph -----------------------------------------------------------------------
|
||||
|
||||
|
||||
def working_graph(working: MutableMapping[str, Any]) -> dict[str, list[dict[str, Any]]]:
|
||||
graph = working.get(GRAPH)
|
||||
if not isinstance(graph, dict):
|
||||
graph = working[GRAPH] = {}
|
||||
for name in _GRAPH_LISTS:
|
||||
if not isinstance(graph.get(name), list):
|
||||
graph[name] = []
|
||||
return graph
|
||||
|
||||
|
||||
def graph_text(working: MutableMapping[str, Any]) -> str:
|
||||
"""The working graph as target-architecture.json, or "" when nothing is in it."""
|
||||
graph = working.get(GRAPH)
|
||||
if not isinstance(graph, dict) or not any(graph.get(n) for n in _GRAPH_LISTS):
|
||||
return ""
|
||||
return json.dumps(
|
||||
{name: graph.get(name, []) for name in _GRAPH_LISTS},
|
||||
indent=2,
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
|
||||
def keep_graph(working: MutableMapping[str, Any], text: str) -> None:
|
||||
"""Make a submitted graph the working graph, so a Revision amends it."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return
|
||||
if isinstance(data, dict):
|
||||
working[GRAPH] = {
|
||||
name: [item for item in data.get(name, []) if isinstance(item, dict)]
|
||||
for name in _GRAPH_LISTS
|
||||
}
|
||||
|
||||
|
||||
def _key(name: str) -> str:
|
||||
return "recommendation" if name == "not_applicable" else "id"
|
||||
|
||||
|
||||
def graph_tools(working: MutableMapping[str, Any]) -> list[ToolSpec]:
|
||||
"""Tools that build the Target architecture a few items at a time."""
|
||||
|
||||
async def graph_put(
|
||||
elements: Sequence[Any] = (),
|
||||
relationships: Sequence[Any] = (),
|
||||
checks: Sequence[Any] = (),
|
||||
not_applicable: Sequence[Any] = (),
|
||||
) -> ToolResult:
|
||||
graph = working_graph(working)
|
||||
given = dict(
|
||||
zip(
|
||||
_GRAPH_LISTS,
|
||||
(elements, relationships, checks, not_applicable),
|
||||
strict=True,
|
||||
)
|
||||
)
|
||||
bad = [
|
||||
f"{name}[{index}]"
|
||||
for name, items in given.items()
|
||||
for index, item in enumerate(items or ())
|
||||
if not isinstance(item, Mapping)
|
||||
or not isinstance(item.get(_key(name)), str)
|
||||
or not item[_key(name)].strip()
|
||||
]
|
||||
if bad:
|
||||
return ToolResult(
|
||||
"Refused: each item must be an object with an `id` (a "
|
||||
f"`recommendation` under not_applicable): {', '.join(bad)}"
|
||||
)
|
||||
added = replaced = 0
|
||||
for name, items in given.items():
|
||||
key = _key(name)
|
||||
for item in items or ():
|
||||
for index, existing in enumerate(graph[name]):
|
||||
if existing.get(key) == item[key]:
|
||||
graph[name][index] = dict(item)
|
||||
replaced += 1
|
||||
break
|
||||
else:
|
||||
graph[name].append(dict(item))
|
||||
added += 1
|
||||
return ToolResult(f"Added {added}, replaced {replaced}. {_counts(graph)}")
|
||||
|
||||
async def graph_remove(ids: Sequence[str]) -> ToolResult:
|
||||
graph = working_graph(working)
|
||||
wanted = set(ids)
|
||||
removed = 0
|
||||
for name in _GRAPH_LISTS:
|
||||
kept = [item for item in graph[name] if item.get(_key(name)) not in wanted]
|
||||
removed += len(graph[name]) - len(kept)
|
||||
graph[name] = kept
|
||||
return ToolResult(f"Removed {removed}. {_counts(graph)}")
|
||||
|
||||
async def graph_read() -> ToolResult:
|
||||
return ToolResult(graph_text(working) or "Your working graph is empty.")
|
||||
|
||||
def items(*fields: str, optional: tuple[str, ...] = ()) -> dict[str, Any]:
|
||||
return {
|
||||
"type": "array",
|
||||
"items": _schema(
|
||||
{name: {"type": "string"} for name in (*fields, *optional)}, fields
|
||||
),
|
||||
}
|
||||
|
||||
lists = {
|
||||
"elements": items(
|
||||
"id", "name", "product", "resource_type", optional=("component",)
|
||||
),
|
||||
"relationships": items("id", "from", "to", "kind"),
|
||||
"checks": items("id", "applies_to", "statement", "source"),
|
||||
"not_applicable": items("recommendation", "reason"),
|
||||
}
|
||||
return [
|
||||
ToolSpec(
|
||||
"graph_put",
|
||||
"Add items to your working graph, or replace the ones with the same id. "
|
||||
"Call it several times with a few items each. Your working graph is "
|
||||
"attached as target-architecture.json when you submit.",
|
||||
_schema(lists, []),
|
||||
graph_put,
|
||||
),
|
||||
ToolSpec(
|
||||
"graph_remove",
|
||||
"Remove items from your working graph by id (a not-applicable entry by "
|
||||
"its recommendation id).",
|
||||
_schema({"ids": {"type": "array", "items": {"type": "string"}}}, ["ids"]),
|
||||
graph_remove,
|
||||
),
|
||||
ToolSpec(
|
||||
"graph_read",
|
||||
"Read your working graph.",
|
||||
{"type": "object", "properties": {}},
|
||||
graph_read,
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
def _counts(graph: Mapping[str, Sequence[Any]]) -> str:
|
||||
return (
|
||||
f"The graph has {len(graph['elements'])} Elements, "
|
||||
f"{len(graph['relationships'])} Relationships and "
|
||||
f"{len(graph['checks'])} Checks."
|
||||
)
|
||||
|
||||
|
||||
def summary(working: Mapping[str, Any]) -> dict[str, Any] | None:
|
||||
"""What a Specialist is told it already has, at the start of a run."""
|
||||
told: dict[str, Any] = {}
|
||||
files = working.get(FILES)
|
||||
if isinstance(files, Mapping) and files:
|
||||
told["files"] = sorted(files)
|
||||
graph = working.get(GRAPH)
|
||||
if isinstance(graph, Mapping) and any(graph.get(name) for name in _GRAPH_LISTS):
|
||||
told["graph"] = {name: len(graph.get(name) or ()) for name in _GRAPH_LISTS}
|
||||
return told or None
|
||||
@@ -242,20 +242,51 @@ def _covers_every_check(
|
||||
return problems
|
||||
|
||||
|
||||
def _split_implementation(text: str, name: str) -> tuple[str, str]:
|
||||
"""The entries that say where a Check is met, and those that say it cannot be."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return text, "[]"
|
||||
if not isinstance(data, list):
|
||||
return text, "[]"
|
||||
cannot = [
|
||||
item for item in data if isinstance(item, dict) and "unimplementable" in item
|
||||
]
|
||||
met = [item for item in data if item not in cannot]
|
||||
return json.dumps(met), json.dumps(cannot)
|
||||
|
||||
|
||||
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))
|
||||
met_text, cannot_text = _split_implementation(attachments[name], name)
|
||||
met, problems = _objects(met_text, name, ("check", "file", "address"))
|
||||
cannot, faults = _objects(cannot_text, name, ("check", "unimplementable"))
|
||||
problems += faults
|
||||
problems += _covers_every_check([*met, *cannot], name, read_graph(upstream))
|
||||
problems += [
|
||||
f"{name}: {item['check']} names {item['file']}, which is not attached"
|
||||
for item in items
|
||||
for item in met
|
||||
if item["file"] not in attachments
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]:
|
||||
"""The Checks the code's author found cannot be met as written, with the reason.
|
||||
|
||||
Each is a fault in the Target architecture, not in the code: the Check names
|
||||
something the resource does not have.
|
||||
"""
|
||||
_, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE)
|
||||
cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable"))
|
||||
return [
|
||||
{"check": item["check"], "reason": item["unimplementable"]} for item in cannot
|
||||
]
|
||||
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
|
||||
@@ -64,6 +64,14 @@ class DeliverableSpec:
|
||||
depends_on: tuple[DeliverableKind, ...] = ()
|
||||
sections: tuple[str, ...] = ()
|
||||
attachments: tuple[str, ...] = ()
|
||||
# Which earlier Deliverables the Specialist reads whole. None means the ones it
|
||||
# depends on. Every other input arrives as its data file alone: the ids the
|
||||
# Requirements chain runs through, without the prose written around them.
|
||||
reads_in_full: tuple[DeliverableKind, ...] | None = None
|
||||
# The Deliverable whose files this Specialist's tools work on. Its own kind: the
|
||||
# files are its working copy, kept across attempts and attached on submission.
|
||||
# Another kind: a fresh copy of that Deliverable's files on every attempt.
|
||||
working_copy: DeliverableKind | None = None
|
||||
|
||||
def contract(self) -> dict[str, list[str]]:
|
||||
"""What a submission must contain, as plain data for the Specialist's context."""
|
||||
@@ -126,8 +134,10 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
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.
|
||||
# The Specialist writes the reasoning and the graph. On submission the
|
||||
# engine adds the Elements, Relationships and Checks tables to the content
|
||||
# and architecture.mmd to the attachments, both rendered from the graph.
|
||||
sections=("Design rationale",),
|
||||
attachments=(GRAPH_ATTACHMENT,),
|
||||
),
|
||||
DeliverableSpec(
|
||||
@@ -151,6 +161,9 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"terraform/variables.tf",
|
||||
IMPLEMENTATION_FILE,
|
||||
),
|
||||
# The graph is all the code is written from.
|
||||
reads_in_full=(),
|
||||
working_copy=_K.DEPLOYMENT_GUIDANCE,
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.VALIDATION_RESULTS,
|
||||
@@ -159,6 +172,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
|
||||
sections=("Deployment dry-run", "Architecture and policy analysis"),
|
||||
attachments=(VERDICTS_FILE,),
|
||||
working_copy=_K.DEPLOYMENT_GUIDANCE,
|
||||
),
|
||||
DeliverableSpec(
|
||||
_K.SOLUTION_GUIDE,
|
||||
@@ -175,6 +189,8 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
|
||||
"Validation plan",
|
||||
"References",
|
||||
),
|
||||
# The guide is assembled from every Deliverable's prose.
|
||||
reads_in_full=tuple(_K)[:-1],
|
||||
),
|
||||
)
|
||||
}
|
||||
@@ -218,6 +234,31 @@ def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]:
|
||||
)
|
||||
|
||||
|
||||
def dependencies_for(
|
||||
kind: DeliverableKind, deliverables: Mapping[str, Mapping[str, object]]
|
||||
) -> dict[str, dict[str, object]]:
|
||||
"""What a Specialist is given of each Deliverable it works from.
|
||||
|
||||
A Deliverable read in full arrives as submitted. Any other arrives as its data
|
||||
file alone, which is all the Requirements chain needs of it.
|
||||
"""
|
||||
spec = DEPENDENCY_GRAPH[kind]
|
||||
in_full = spec.depends_on if spec.reads_in_full is None else spec.reads_in_full
|
||||
given: dict[str, dict[str, object]] = {}
|
||||
for dependency in inputs_of(kind):
|
||||
deliverable = deliverables[dependency.value]
|
||||
if dependency in in_full or dependency not in DATA_CHECKS:
|
||||
given[dependency.value] = dict(deliverable)
|
||||
continue
|
||||
name = DATA_CHECKS[dependency][0]
|
||||
attachments = deliverable.get("attachments")
|
||||
files = attachments if isinstance(attachments, Mapping) else {}
|
||||
given[dependency.value] = {
|
||||
"attachments": {name: files[name]} if name in files else {}
|
||||
}
|
||||
return given
|
||||
|
||||
|
||||
def deliverables_in(phase: PhaseId) -> tuple[DeliverableKind, ...]:
|
||||
return tuple(kind for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase is phase)
|
||||
|
||||
|
||||
@@ -20,6 +20,7 @@ from langgraph.graph import END, START, StateGraph
|
||||
|
||||
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
|
||||
from app.nodes.execution_nodes import make_execution_nodes
|
||||
from app.nodes.router import OrchestratorPolicy
|
||||
from app.recorder import ExecutionRecorder
|
||||
from app.states.execution_state import ExecutionState
|
||||
|
||||
@@ -34,6 +35,7 @@ def build_execution_graph(
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
orchestrator: OrchestratorPolicy | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
runtime=runtime,
|
||||
@@ -44,6 +46,7 @@ def build_execution_graph(
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
orchestrator=orchestrator,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
|
||||
@@ -6,7 +6,8 @@
|
||||
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.
|
||||
a diagram and as tables a person can review, and says whether the Requirements chain
|
||||
through it is complete.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -281,3 +282,64 @@ def render_mermaid(graph: TargetArchitecture) -> str:
|
||||
f"{nodes[relationship.target]}"
|
||||
)
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
# --- so are the tables a person reviews ----------------------------------------------
|
||||
|
||||
|
||||
def _cell(text: str | None) -> str:
|
||||
return " ".join((text or "").replace("|", "\\|").split())
|
||||
|
||||
|
||||
def _table(
|
||||
heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]]
|
||||
) -> str:
|
||||
lines = [
|
||||
f"## {heading}",
|
||||
"",
|
||||
"| " + " | ".join(columns) + " |",
|
||||
"|" + "|".join(" --- " for _ in columns) + "|",
|
||||
]
|
||||
lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def render_tables(graph: TargetArchitecture) -> str:
|
||||
"""The graph as markdown tables: what a person approving the design reads.
|
||||
|
||||
Written by code, so the tables cannot disagree with the graph and no model spends
|
||||
output repeating it.
|
||||
"""
|
||||
names = {element.id: element.name for element in graph.elements}
|
||||
parts = [
|
||||
_table(
|
||||
"Elements",
|
||||
("Id", "Name", "Product", "Resource type", "Component"),
|
||||
(
|
||||
(e.id, e.name, e.product, e.resource_type, e.component)
|
||||
for e in graph.elements
|
||||
),
|
||||
),
|
||||
_table(
|
||||
"Relationships",
|
||||
("Id", "From", "Kind", "To"),
|
||||
(
|
||||
(r.id, names[r.source], r.kind, names[r.target])
|
||||
for r in graph.relationships
|
||||
),
|
||||
),
|
||||
_table(
|
||||
"Checks",
|
||||
("Id", "Applies to", "Statement", "Source"),
|
||||
((c.id, c.applies_to, c.statement, c.source) for c in graph.checks),
|
||||
),
|
||||
]
|
||||
if graph.not_applicable:
|
||||
parts.append(
|
||||
_table(
|
||||
"Not applicable",
|
||||
("Recommendation", "Reason"),
|
||||
((n.recommendation, n.reason) for n in graph.not_applicable),
|
||||
)
|
||||
)
|
||||
return "\n\n".join(parts) + "\n"
|
||||
|
||||
Reference in New Issue
Block a user