"""The design advisor's fan-out to one advisor per architecture-framework pillar. Pillar advice is working material for the design recommendations Deliverable, not a Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's working memory, so a Revision re-consults only the pillars its feedback touches. """ from __future__ import annotations import asyncio import dataclasses from collections.abc import Mapping, MutableMapping, Sequence from contextlib import AsyncExitStack from typing import Any from app.adk.runtime import ( AgentRuntime, AgentTask, RoleSpec, RunLimiter, Submitted, ToolResult, ToolSpec, ) CONSULT_TOOL = "consult_pillar_advisors" NO_GUIDANCE = "No guidance" ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given def pillar_consultation_tool( runtime: AgentRuntime, advisor: RoleSpec, pillar_skills: Mapping[str, str], extra_tools: Sequence[ToolSpec] = (), memory: MutableMapping[str, Any] | None = None, limiter: RunLimiter | None = None, ) -> ToolSpec: """A tool that runs one pillar advisor per pillar, in parallel, each with its Skill. With `memory`, advice is remembered: naming `pillars` re-consults only those and returns the remembered advice for the rest. """ async def advise(pillar: str, brief: str) -> str: async with AsyncExitStack() as stack: if limiter: await stack.enter_async_context(limiter.slot()) return await _advise( runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools ) async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult: chosen = list(pillars) if pillars else list(pillar_skills) unknown = [pillar for pillar in chosen if pillar not in pillar_skills] if unknown: return ToolResult( f"Refused: unknown pillars {', '.join(unknown)}; " f"choose from {', '.join(pillar_skills)}" ) async with AsyncExitStack() as stack: if limiter: # The calling Specialist only waits here, so its slot goes to advisors. await stack.enter_async_context(limiter.lend()) fresh = dict( zip( chosen, await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)), ) ) remembered: dict[str, str] = ( dict(memory.get(ADVICE_KEY, {})) if memory is not None else {} ) sections = [] for pillar in pillar_skills: if pillar in fresh: advice = fresh[pillar] if not advice.startswith(NO_GUIDANCE): remembered[pillar] = advice sections.append(f"## {pillar}\n\n{advice}") elif pillar in remembered: sections.append( f"## {pillar} (from your earlier consultation)\n\n" f"{remembered[pillar]}" ) if memory is not None: memory[ADVICE_KEY] = remembered return ToolResult("\n\n".join(sections)) return ToolSpec( CONSULT_TOOL, "Get guidance from one advisor per architecture-framework pillar, in parallel. " "Give a brief with the workload, its requirements and the selected products. " "Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult " "only those; advice already given for the others is returned unchanged.", { "type": "object", "properties": { "brief": {"type": "string"}, "pillars": { "type": "array", "items": {"type": "string", "enum": list(pillar_skills)}, }, }, "required": ["brief"], }, consult, ) async def _advise( runtime: AgentRuntime, advisor: RoleSpec, pillar: str, skill: str, brief: str, extra_tools: Sequence[ToolSpec], ) -> str: role = dataclasses.replace(advisor, skills=(skill,)) task = AgentTask( role=advisor.name, prompt=f"Advise on the {pillar} pillar for this workload.", context={"pillar": pillar, "brief": brief}, ) try: outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools]) except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others return f"{NO_GUIDANCE}: the advisor failed ({exc})." if isinstance(outcome, Submitted): return outcome.content.strip() return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}." def _submit_advice_tool() -> ToolSpec: async def submit_advice(content: str) -> ToolResult: if not content.strip(): return ToolResult("Not submitted: the advice is empty.") return ToolResult("Advice submitted.", Submitted(content)) return ToolSpec( "submit_advice", "Submit your pillar recommendations as markdown. Ends your turn.", { "type": "object", "properties": {"content": {"type": "string"}}, "required": ["content"], }, submit_advice, tier="execution", )