Architecture Decisions Basics

python -m venv .venv && source .venv/bin/activate
# stdlib only for the examples below

from dataclasses import dataclass
from datetime import date
from enum import Enum
 
 
class AdrStatus(str, Enum):
    PROPOSED = "proposed"
    ACCEPTED = "accepted"
    DEPRECATED = "deprecated"
    SUPERSEDED = "superseded"
 
 
@dataclass
class AdrHeader:
    id: str
    title: str
    status: AdrStatus
    date: date
    owner: str
 
 
header = AdrHeader(
    id="ADR-001",
    title="Use a thin custom loop for the support triage agent",
    status=AdrStatus.PROPOSED,
    date=date(2026, 7, 1),
    owner="platform-agents",
)
print(header)

from dataclasses import dataclass
 
 
@dataclass
class AdrContext:
    problem: str
    forces: list[str]
    non_goals: list[str]
 
 
ctx = AdrContext(
    problem="Ship a single-tool support triage agent in two weeks.",
    forces=[
        "Team knows FastAPI and stdlib; limited graph experience",
        "One read-only knowledge tool; no multi-day HITL yet",
        "Must keep tools portable if we adopt LangGraph later",
    ],
    non_goals=[
        "Multi-agent research pipelines",
        "Durable multi-day resume",
    ],
)
for f in ctx.forces:
    print("-", f)

from dataclasses import dataclass
 
 
@dataclass
class Option:
    name: str
    pros: list[str]
    cons: list[str]
 
 
options = [
    Option(
        name="Thin custom loop",
        pros=["Fast to ship", "Few dependencies", "Easy to reason about"],
        cons=["We own resume/HITL later", "Less community graph tooling"],
    ),
    Option(
        name="LangGraph",
        pros=["Checkpoints and graphs ready", "Ecosystem tracing"],
        cons=["Learning curve this sprint", "Heavier than one tool needs"],
    ),
    Option(
        name="CrewAI multi-agent",
        pros=["Role metaphors for demos"],
        cons=["Overkill for one triage tool", "Coordination cost now"],
    ),
]
 
decision = "Thin custom loop"
print("DECISION:", decision)
for o in options:
    mark = "← chosen" if o.name == decision else ""
    print(f"* {o.name} {mark}")

from dataclasses import dataclass
 
 
@dataclass
class Consequences:
    positive: list[str]
    negative: list[str]
    follow_ups: list[str]
 
 
cons = Consequences(
    positive=[
        "Triage agent ships without framework upgrade risk",
        "Tool function stays a pure Python callable",
    ],
    negative=[
        "No built-in durable resume if we add long HITL later",
        "Team must enforce max turns and timeouts ourselves",
    ],
    follow_ups=[
        "Add max_turns=8 and wall_clock_s=60 in host policy",
        "Write ADR-00N if we need graph resume",
    ],
)
print("Watch:", cons.negative[0])

# agent_config.py - pins referenced by ADR-001
AGENT_RUNTIME = "custom_thin_loop"
FRAMEWORK = None  # explicit: no agent framework yet
MAX_TURNS = 8
WALL_CLOCK_S = 60
MODEL_ROLE = "mid_default"  # see model ADR; do not hardcode vendor id here
TOOLS_ALLOWLIST = ["knowledge_search"]
 
 
def describe() -> str:
    return (
        f"runtime={AGENT_RUNTIME} framework={FRAMEWORK} "
        f"max_turns={MAX_TURNS} tools={TOOLS_ALLOWLIST}"
    )
 
 
print(describe())

from textwrap import dedent
 
 
def render_adr() -> str:
    return dedent(
        f"""
        # ADR-001: Thin custom loop for support triage
 
        - Status: {AdrStatus.ACCEPTED.value}
        - Date: 2026-07-01
        - Owner: platform-agents
 
        ## Context
        {ctx.problem}
 
        ## Decision
        Use a thin custom agent loop (no LangGraph/CrewAI) for the support triage agent.
 
        ## Options considered
        - Thin custom loop (chosen)
        - LangGraph
        - CrewAI multi-agent
 
        ## Consequences
        Positive: fast ship, portable tools.
        Negative: we own bounds and future resume.
 
        ## Revisit when
        - We need durable mid-flight resume or multi-agent privilege split
        - Or 2026-10-01 review, whichever comes first
        """
    ).strip()
 
 
print(render_adr()[:200], "...")

from dataclasses import dataclass
 
 
@dataclass
class AdrLink:
    id: str
    status: AdrStatus
    supersedes: str | None = None
    superseded_by: str | None = None
 
 
adr001 = AdrLink(
    id="ADR-001",
    status=AdrStatus.SUPERSEDED,
    superseded_by="ADR-014",
)
adr014 = AdrLink(
    id="ADR-014",
    status=AdrStatus.ACCEPTED,
    supersedes="ADR-001",
)
 
assert adr001.superseded_by == adr014.id
assert adr014.supersedes == adr001.id
print(adr001.status, "->", adr014.id)

from dataclasses import dataclass
 
 
@dataclass
class RevisitSignal:
    name: str
    fired: bool
 
 
signals = [
    RevisitSignal("Need durable HITL resume", False),
    RevisitSignal("More than one specialist privilege tier", False),
    RevisitSignal("Custom loop code > 1.5k lines of orchestration", True),
    RevisitSignal("Quarterly review date reached", False),
]
 
if any(s.fired for s in signals):
    print("Schedule ADR review / spike")
    for s in signals:
        if s.fired:
            print("  fired:", s.name)
else:
    print("No revisit required")