From 1c83520d9e3de38944f997205c9bfc4ef974ef04 Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 16 Jan 2026 16:01:12 -0500 Subject: [PATCH 1/3] feat: Add decision record for flat namespaces --- team/DECISIONS.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/team/DECISIONS.md b/team/DECISIONS.md index bdc2d65f..cf26608e 100644 --- a/team/DECISIONS.md +++ b/team/DECISIONS.md @@ -40,4 +40,36 @@ class RetryStrategy(HookProvider): ... ``` -Higher-level abstractions require additional interface definitions, but this tradeoff provides an improved developer experience through explicit contracts. Developers with edge cases can still drop to raw `HookProvider` (and `agent.hooks`) when needed — optimizing for the common path while preserving that escape hatch. \ No newline at end of file +Higher-level abstractions require additional interface definitions, but this tradeoff provides an improved developer experience through explicit contracts. Developers with edge cases can still drop to raw `HookProvider` (and `agent.hooks`) when needed — optimizing for the common path while preserving that escape hatch. + + +## Prefer Flat Namespaces Over Nested Modules + +**Date**: Jan 16, 2026 + +### Decision + +Public APIs should expose commonly-used functionality through flat, top-level namespaces rather than requiring users to import from deeply nested module paths. + +### Rationale + +Fewer imports are simpler to use and more discoverable when using IDE autocompletion & documentation. It also aligns with the Python ethos "Flat is better than nested" (PEP 20 - The Zen of Python). + +We don't want users continually importing additional modules for common functionality. The goal is to optimize for the 80% case where users need standard features, while still allowing advanced users to import from specific submodules when needed. + + +For example, we prefer exporting all hook events from a single module: + +```python +from strands.hooks import MultiAgentInitializedEvent +``` + +instead of categorizing them based on their purpose + +```python +from strands.hooks.multiagent import MultiAgentInitializedEvent +``` + +this is even more important when the event names already indicate their grouping (**MultiAgent**InitializeEvent). + +Internal module organization can remain nested for code maintainability — the key is re-exporting public symbols at the package root. From 1d03927c3ccfbb9c79e7a6e892a08e2fb1701c35 Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 16 Jan 2026 16:03:25 -0500 Subject: [PATCH 2/3] Minor tweak --- team/DECISIONS.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/team/DECISIONS.md b/team/DECISIONS.md index cf26608e..ad67dceb 100644 --- a/team/DECISIONS.md +++ b/team/DECISIONS.md @@ -57,7 +57,6 @@ Fewer imports are simpler to use and more discoverable when using IDE autocomple We don't want users continually importing additional modules for common functionality. The goal is to optimize for the 80% case where users need standard features, while still allowing advanced users to import from specific submodules when needed. - For example, we prefer exporting all hook events from a single module: ```python @@ -72,4 +71,4 @@ from strands.hooks.multiagent import MultiAgentInitializedEvent this is even more important when the event names already indicate their grouping (**MultiAgent**InitializeEvent). -Internal module organization can remain nested for code maintainability — the key is re-exporting public symbols at the package root. +Internal module organization can remain nested for code maintainability — the key is re-exporting public symbols at common locations. From 49d350d294f578d38c2df8f92de0479b445b4fd6 Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Wed, 21 Jan 2026 09:30:38 -0500 Subject: [PATCH 3/3] Update language --- team/DECISIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/team/DECISIONS.md b/team/DECISIONS.md index ad67dceb..2e6bd79c 100644 --- a/team/DECISIONS.md +++ b/team/DECISIONS.md @@ -53,7 +53,7 @@ Public APIs should expose commonly-used functionality through flat, top-level na ### Rationale -Fewer imports are simpler to use and more discoverable when using IDE autocompletion & documentation. It also aligns with the Python ethos "Flat is better than nested" (PEP 20 - The Zen of Python). +Fewer imports are simpler to use and more discoverable when using IDE autocompletion & documentation. While inspired by Python's "Flat is better than nested" (PEP 20 - The Zen of Python), this principle applies across SDK languages. We don't want users continually importing additional modules for common functionality. The goal is to optimize for the 80% case where users need standard features, while still allowing advanced users to import from specific submodules when needed.