Merge branch 'strands-agents:main' into main

Author: mehtarac

.codecov.yml

@@ -0,0 +1,11 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 90%    # overall coverage threshold
+    patch:
+      default:
+        target: 90%    # patch coverage threshold
+        base: auto
+        # Only post patch coverage on decreases
+        only_pulls: true

.github/workflows/pr-size-labeler.yml

@@ -0,0 +1,58 @@
+name: PR Size Labeler
+
+on:
+  pull_request_target:
+    branches: main
+
+jobs:
+  label-size:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Calculate PR size and apply label
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const totalChanges = pr.additions + pr.deletions;
+            
+            // Remove existing size labels
+            const labels = await github.rest.issues.listLabelsOnIssue({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number
+            });
+            
+            for (const label of labels.data) {
+              if (label.name.startsWith('size/')) {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.payload.pull_request.number,
+                  name: label.name
+                });
+              }
+            }
+            
+            // Determine and apply new size label
+            let sizeLabel;
+            if (totalChanges <= 20) sizeLabel = 'size/xs';
+            else if (totalChanges <= 100) sizeLabel = 'size/s';
+            else if (totalChanges <= 500) sizeLabel = 'size/m';
+            else if (totalChanges <= 1000) sizeLabel = 'size/l';
+            else {
+              sizeLabel = 'size/xl';
+            }
+            
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              labels: [sizeLabel]
+            });
+
+            if (sizeLabel === 'size/xl') {
+              core.setFailed(`PR is too large (${totalChanges} lines). Please split into smaller PRs.`);
+            }

.github/workflows/test-lint.yml

@@ -66,6 +66,11 @@ jobs:
         id: tests
         run: hatch test tests --cover
         continue-on-error: false
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
   lint:
     name: Lint
     runs-on: ubuntu-latest

.gitignore

@@ -11,4 +11,5 @@ __pycache__*
 .vscode
 dist
 repl_state
-.kiro
+.kiro
+uv.lock

CONTRIBUTING.md

@@ -36,6 +36,18 @@ Before starting work on any issue:
 3. Wait for maintainer confirmation before beginning significant work
 
 
+## Development Tenets
+Our team follows these core principles when designing and implementing features. These tenets help us make consistent decisions, resolve trade-offs, and maintain the quality and coherence of the SDK. When contributing, please consider how your changes align with these principles:
+
+1. **Simple at any scale:** We believe that simple things should be simple. The same clean abstractions that power a weekend prototype should scale effortlessly to production workloads. We reject the notion that enterprise-grade means enterprise-complicated - Strands remains approachable whether it's your first agent or your millionth.
+2. **Extensible by design:** We allow for as much configuration as possible, from hooks to model providers, session managers, tools, etc. We meet customers where they are with flexible extension points that are simple to integrate with.
+3. **Composability:** Primitives are building blocks with each other. Each feature of Strands is developed with all other features in mind, they are consistent and complement one another.
+4. **The obvious path is the happy path:** Through intuitive naming, helpful error messages, and thoughtful API design, we guide developers toward correct patterns and away from common pitfalls.
+5. **We are accessible to humans and agents:** Strands is designed for both humans and AI to understand equally well. We don’t take shortcuts on curated DX for humans and we go the extra mile to make sure coding assistants can help you use those interfaces the right way.
+6. **Embrace common standards:** We respect what came before, and do not want to reinvent something that is already widely adopted or done better.
+
+When proposing solutions or reviewing code, we reference these principles to guide our decisions. If two approaches seem equally valid, we choose the one that best aligns with our tenets.
+
 ## Development Environment
 
 This project uses [hatchling](https://hatch.pypa.io/latest/build/#hatchling) as the build backend and [hatch](https://hatch.pypa.io/latest/) for development workflow management.

pyproject.toml

@@ -30,6 +30,7 @@ dependencies = [
     "boto3>=1.26.0,<2.0.0",
     "botocore>=1.29.0,<2.0.0",
     "docstring_parser>=0.15,<1.0",
+    "jsonschema>=4.0.0,<5.0.0",
     "mcp>=1.11.0,<2.0.0",
     "pydantic>=2.4.0,<3.0.0",
     "typing-extensions>=4.13.2,<5.0.0",

src/strands/__init__.py

@@ -5,4 +5,12 @@
 from .tools.decorator import tool
 from .types.tools import ToolContext
 
-__all__ = ["Agent", "agent", "models", "tool", "types", "telemetry", "ToolContext"]
+__all__ = [
+    "Agent",
+    "agent",
+    "models",
+    "tool",
+    "ToolContext",
+    "types",
+    "telemetry",
+]

src/strands/_async.py

@@ -0,0 +1,31 @@
+"""Private async execution utilities."""
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from typing import Awaitable, Callable, TypeVar
+
+T = TypeVar("T")
+
+
+def run_async(async_func: Callable[[], Awaitable[T]]) -> T:
+    """Run an async function in a separate thread to avoid event loop conflicts.
+
+    This utility handles the common pattern of running async code from sync contexts
+    by using ThreadPoolExecutor to isolate the async execution.
+
+    Args:
+        async_func: A callable that returns an awaitable
+
+    Returns:
+        The result of the async function
+    """
+
+    async def execute_async() -> T:
+        return await async_func()
+
+    def execute() -> T:
+        return asyncio.run(execute_async())
+
+    with ThreadPoolExecutor() as executor:
+        future = executor.submit(execute)
+        return future.result()

src/strands/_exception_notes.py

@@ -0,0 +1,21 @@
+"""Exception note utilities for Python 3.10+ compatibility."""
+
+# add_note was added in 3.11 - we hoist to a constant to facilitate testing
+supports_add_note = hasattr(Exception, "add_note")
+
+
+def add_exception_note(exception: Exception, note: str) -> None:
+    """Add a note to an exception, compatible with Python 3.10+.
+
+    Uses add_note() if it's available (Python 3.11+) or modifies the exception message if it is not.
+    """
+    if supports_add_note:
+        # we ignore the mypy error because the version-check for add_note is extracted into a constant up above and
+        # mypy doesn't detect that
+        exception.add_note(note)  # type: ignore
+    else:
+        # For Python 3.10, append note to the exception message
+        if hasattr(exception, "args") and exception.args:
+            exception.args = (f"{exception.args[0]}\n{note}",) + exception.args[1:]
+        else:
+            exception.args = (note,)