chore: prepare directory layout for monorepo convergence (#2317)

Co-authored-by: Mackenzie Zastrow <zastrowm@users.noreply.github.com>

.github/dependabot.yml

@@ -1,12 +1,12 @@
 version: 2
 updates:
   - package-ecosystem: "pip"
-    directory: "/"
+    directory: "/strands-py"
     schedule:
       interval: "daily"
     open-pull-requests-limit: 100
     commit-message:
-      prefix: ci
+      prefix: "ci(python)"
     groups:
       dev-dependencies:
         patterns:

.github/workflows/python-check-markdown-links.yml

@@ -1,4 +1,4 @@
-name: Check Markdown Links
+name: "Python: Check Markdown Links"
 
 on:
   schedule:
@@ -16,7 +16,8 @@ jobs:
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'yes'
-          config-file: '.markdown-link-check.json'
+          config-file: 'strands-py/.markdown-link-check.json'
+          folder-path: 'strands-py'
         continue-on-error: true
 
       - name: Create issue if links are broken

.github/workflows/python-integration-test.yml

@@ -1,9 +1,12 @@
-name: Secure Integration test
+name: "Python: Integration Test"
 
 on:
   pull_request_target:
     branches: [main]
-  merge_group: # Run tests in merge queue
+    paths:
+      - 'strands-py/**'
+      - '.github/workflows/python-*'
+  merge_group:
     types: [checks_requested]
 
 jobs:
@@ -21,7 +24,7 @@ jobs:
           skip-check: ${{ github.event_name == 'merge_group' }}
           username: ${{ github.event.pull_request.user.login || 'invalid' }}
           allowed-roles: 'maintain,triage,write,admin'
-  
+
   check-access-and-checkout:
     runs-on: ubuntu-latest
     needs: authorization-check
@@ -30,6 +33,9 @@ jobs:
       id-token: write
       pull-requests: read
       contents: read
+    defaults:
+      run:
+        working-directory: strands-py
     steps:
       - name: Configure Credentials
         uses: aws-actions/configure-aws-credentials@v6
@@ -41,21 +47,19 @@ jobs:
       - name: Checkout head commit
         uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.pull_request.head.sha }} # Pull the commit from the forked repo
-          persist-credentials: false  # Don't persist credentials for subsequent actions
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: '3.10'
       - name: Install dependencies
-        # Pin virtualenv until hatch is fixed.
-        # See https://github.com/pypa/hatch/issues/2193
         run: |
           pip install --no-cache-dir hatch 'virtualenv<21'
       - name: Run integration tests
         env:
           AWS_REGION: us-east-1
-          AWS_REGION_NAME: us-east-1 # Needed for LiteLLM
+          AWS_REGION_NAME: us-east-1
           STRANDS_TEST_API_KEYS_SECRET_NAME: ${{ secrets.STRANDS_TEST_API_KEYS_SECRET_NAME }}
         id: tests
         run: |
@@ -66,7 +70,7 @@ jobs:
         uses: actions/upload-artifact@v7
         with:
           name: test-results
-          path: ./build/test-results.xml
+          path: strands-py/build/test-results.xml
 
   upload-metrics:
     runs-on: ubuntu-latest

.github/workflows/python-pr-and-push.yml

@@ -1,22 +1,29 @@
-name: Pull Request and Push Action
+name: "Python: Pull Request and Push"
 
 on:
-  pull_request:  # Safer than pull_request_target for untrusted code
+  pull_request:
     branches: [ main ]
     types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'strands-py/**'
+      - '.github/workflows/python-*'
   push:
-    branches: [ main ]  # Also run on direct pushes to main
+    branches: [ main ]
+    paths:
+      - 'strands-py/**'
+      - '.github/workflows/python-*'
+  workflow_dispatch:
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
   call-test-lint:
-    uses: ./.github/workflows/test-lint.yml
+    uses: ./.github/workflows/python-test-lint.yml
     permissions:
       contents: read
     with:
-      ref: ${{ github.event.pull_request.head.sha }}
+      ref: ${{ github.event.pull_request.head.sha || github.sha }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
@@ -28,13 +35,12 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v6
       with:
-        fetch-depth: 0  # We the need the full Git history.
+        fetch-depth: 0
     - name: Setup uv
       uses: astral-sh/setup-uv@v7
     - name: Check API breaking changes
       run: |
-        if ! uvx griffe check --search src --format github strands --against "main"; then
+        if ! uvx griffe check --search strands-py/src --format github strands --against "main"; then
           echo "Potential API changes detected (review if actually breaking)"
           exit 1
         fi
-

.github/workflows/python-publish-lambda-layer.yml

@@ -1,4 +1,4 @@
-name: Publish PyPI Package to Lambda Layer
+name: "Python: Publish Lambda Layer"
 
 on:
   workflow_dispatch:

.github/workflows/python-pypi-publish-on-release.yml

@@ -1,4 +1,4 @@
-name: Publish Python Package
+name: "Python: Publish Package"
 
 on:
   release:
@@ -7,7 +7,8 @@ on:
 
 jobs:
   call-test-lint:
-    uses: ./.github/workflows/test-lint.yml
+    if: startsWith(github.event.release.tag_name, 'python/v')
+    uses: ./.github/workflows/python-test-lint.yml
     permissions:
       contents: read
     with:
@@ -16,17 +17,22 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   build:
-    name: Build distribution 📦
+    name: Build distribution
+    if: startsWith(github.event.release.tag_name, 'python/v')
     permissions:
       contents: read
     needs:
       - call-test-lint
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: strands-py
 
     steps:
     - uses: actions/checkout@v6
       with:
         persist-credentials: false
+        fetch-depth: 0
 
     - name: Set up Python
       uses: actions/setup-python@v6
@@ -34,8 +40,6 @@ jobs:
         python-version: '3.10'
 
     - name: Install dependencies
-      # Pin virtualenv until hatch is fixed.
-      # See https://github.com/pypa/hatch/issues/2193
       run: |
         python -m pip install --upgrade pip
         pip install hatch twine 'virtualenv<21'
@@ -59,7 +63,7 @@ jobs:
       uses: actions/upload-artifact@v7
       with:
         name: python-package-distributions
-        path: dist/
+        path: strands-py/dist/
 
   deploy:
     name: Upload release to PyPI
@@ -67,20 +71,17 @@ jobs:
     - build
     runs-on: ubuntu-latest
 
-    # environment is used by PyPI Trusted Publisher and is strongly encouraged
-    # https://docs.pypi.org/trusted-publishers/adding-a-publisher/
     environment:
       name: pypi
       url: https://pypi.org/p/strands-agents
     permissions:
-      # IMPORTANT: this permission is mandatory for Trusted Publishing
       id-token: write
-    
+
     steps:
     - name: Download all the dists
       uses: actions/download-artifact@v8
       with:
         name: python-package-distributions
         path: dist/
-    - name: Publish distribution 📦 to PyPI
+    - name: Publish distribution to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/python-test-lint.yml

@@ -1,4 +1,4 @@
-name: Test and Lint
+name: "Python: Test and Lint"
 
 on:
   workflow_call:
@@ -58,33 +58,37 @@ jobs:
     runs-on: ${{ matrix.os }}
     env:
       LOG_LEVEL: DEBUG
+    defaults:
+      run:
+        working-directory: strands-py
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
         with:
-          ref: ${{ inputs.ref }}  # Explicitly define which commit to check out
-          persist-credentials: false  # Don't persist credentials for subsequent actions
+          ref: ${{ inputs.ref }}
+          persist-credentials: false
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install system audio dependencies (Linux)
         if: matrix.os-name == 'linux'
+        working-directory: .
         run: |
           sudo apt-get update
           sudo apt-get install -y portaudio19-dev libasound2-dev
       - name: Install system audio dependencies (macOS)
         if: matrix.os-name == 'macOS'
+        working-directory: .
         run: |
           brew install portaudio
       - name: Install system audio dependencies (Windows)
         if: matrix.os-name == 'windows'
+        working-directory: .
         run: |
           # Windows typically has audio libraries available by default
           echo "Windows audio dependencies handled by PyAudio wheels"
       - name: Install dependencies
-        # Pin virtualenv until hatch is fixed.
-        # See https://github.com/pypa/hatch/issues/2193
         run: |
           pip install --no-cache-dir hatch 'virtualenv<21'
       - name: Run Unit tests
@@ -101,6 +105,9 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    defaults:
+      run:
+        working-directory: strands-py
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -115,13 +122,12 @@ jobs:
           cache: 'pip'
 
       - name: Install system audio dependencies (Linux)
+        working-directory: .
         run: |
           sudo apt-get update
           sudo apt-get install -y portaudio19-dev libasound2-dev
 
       - name: Install dependencies
-        # Pin virtualenv until hatch is fixed.
-        # See https://github.com/pypa/hatch/issues/2193
         run: |
           pip install --no-cache-dir hatch 'virtualenv<21'
 
@@ -129,4 +135,3 @@ jobs:
         id: lint
         run: hatch fmt --linter --check
         continue-on-error: false
-

.gitignore

@@ -1,17 +1,9 @@
 .DS_Store
-build
 __pycache__*
-.coverage*
 .env
 .venv
-.mypy_cache
-.pytest_cache
-.ruff_cache
 *.bak
 .vscode
-dist
-repl_state
 .kiro
-uv.lock
-.audio_cache
 CLAUDE.md
+.claude/settings.local.json

CONTRIBUTING.md

@@ -52,6 +52,12 @@ When proposing solutions or reviewing code, we reference these principles to gui
 
 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.
 
+All `hatch` commands should be run from the `strands-py/` subdirectory (where `pyproject.toml` lives):
+
+```bash
+cd strands-py
+```
+
 ### Setting Up Your Development Environment
 
 1. Entering virtual environment using `hatch` (recommended), then launch your IDE in the new shell.
@@ -112,7 +118,7 @@ We use the following tools to ensure code quality:
 1. **ruff** - For formatting and linting
 2. **mypy** - For static type checking
 
-These tools are configured in the [pyproject.toml](./pyproject.toml) file. Please ensure your code passes all linting and type checks before submitting a pull request:
+These tools are configured in the [pyproject.toml](./strands-py/pyproject.toml) file. Please ensure your code passes all linting and type checks before submitting a pull request:
 
 ```bash
 # Run all checks
@@ -122,7 +128,7 @@ hatch fmt --linter
 
 If you're using an IDE like VS Code or PyCharm, consider configuring it to use these tools automatically.
 
-For additional details on styling, please see our dedicated [Style Guide](./docs/STYLE_GUIDE.md).
+For additional details on styling, please see our dedicated [Style Guide](./strands-py/docs/STYLE_GUIDE.md).
 
 
 ## Contributing via Pull Requests
@@ -132,7 +138,7 @@ Contributions via pull requests are much appreciated. Before sending us a pull r
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
 
-For guidance on writing effective PR descriptions, see our [PR Description Guidelines](./docs/PR.md).
+For guidance on writing effective PR descriptions, see our [PR Description Guidelines](./strands-py/docs/PR.md).
 
 To send us a pull request, please:
 

README.md

@@ -308,6 +308,19 @@ For detailed guidance & examples, explore our documentation:
 - [API Reference](https://strandsagents.com/docs/api/python/strands.agent.agent/)
 - [Production & Deployment Guide](https://strandsagents.com/docs/user-guide/deploy/operating-agents-in-production/)
 
+## Development
+
+Source code lives in the `strands-py/` subdirectory. To develop locally:
+
+```bash
+cd strands-py
+pip install hatch
+hatch test        # run unit tests
+hatch fmt         # format & lint
+```
+
+Git operations (commits, branches, PRs) are still done from the repo root as normal.
+
 ## Contributing ❤️
 
 We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:

strands-py/.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+build
+__pycache__*
+.coverage*
+.env
+.venv
+.mypy_cache
+.pytest_cache
+.ruff_cache
+*.bak
+.vscode
+dist
+repl_state
+.kiro
+uv.lock
+.audio_cache
+CLAUDE.md

strands-py/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This document provides context, patterns, and guidelines for AI coding assistants working in this repository. For human contributors, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+This document provides context, patterns, and guidelines for AI coding assistants working in this repository. For human contributors, see [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 ## Product Overview
 
@@ -562,7 +562,7 @@ hatch build                    # Build package
 ## Additional Resources
 
 - [Strands Agents Documentation](https://strandsagents.com/)
-- [CONTRIBUTING.md](./CONTRIBUTING.md) - Human contributor guidelines
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Human contributor guidelines
 - [docs/](./docs/) - Developer documentation
   - [STYLE_GUIDE.md](./docs/STYLE_GUIDE.md) - Code style conventions
   - [HOOKS.md](./docs/HOOKS.md) - Hooks system guide

strands-py/docs/README.md

@@ -12,5 +12,5 @@ This folder contains documentation for contributors and developers working on th
 ## Related Documentation
 
 - [AGENTS.md](../AGENTS.md) - Guidance for AI agents and LLMs working with this codebase
-- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines for human contributors
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution guidelines for human contributors
 - [strandsagents.com](https://strandsagents.com/) - User-facing documentation

strands-py/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 name = "strands-agents"
 dynamic = ["version"]  # Version determined by git tags
 description = "A model-driven approach to building AI agents in just a few lines of code"
-readme = "README.md"
+readme = "../README.md"
 requires-python = ">=3.10"
 license = {text = "Apache-2.0"}
 authors = [
@@ -112,7 +112,10 @@ packages = ["src/strands"]
 
 
 [tool.hatch.version]
-source = "vcs"  # Use git tags for versioning
+source = "vcs"
+raw-options.root = ".."
+raw-options.tag_regex = "^python/v(?P<version>.+)$"
+raw-options.git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "python/v*"]
 
 
 [tool.hatch.envs.hatch-static-analysis]