strands-agent-service

Python backend service for the strands-agent-service project.

Overview

This repository provides a minimal, reproducible template for data science projects that use a src layout, tooling and Python 3.13 or newer.

Included structure

• src/
  • Purpose: Contains the project Python package implemented using a src layout.
  • Contents: A project package directory named strands_agent_service, which provides the importable Python package for the strands-agent-service project, with an empty __init__.py file ready for your code.
• tests/
  • Purpose: Contains all automated tests associated with the project code.
  • Contents: An empty __init__.py file so that tests can be treated as a package when needed.
• pyproject.toml
  • Purpose: Defines the project metadata, Python requirement (>=3.13) and development tooling dependencies.
  • Highlights: Uses [dependency-groups] for development tools such as pytest, pytest-cov, ruff, pre-commit, nox, mypy, bandit, types-requests and typing-extensions. Configures pytest for the src layout and coverage to only measure the src directory.
• .pre-commit-config.yaml
  • Purpose: Defines a local pre-commit hook that enforces full test coverage on every commit.
  • Highlights: Runs uv run pytest --cov=src --cov-report=term-missing --cov-fail-under=100 with pass_filenames: false so that coverage must remain at one hundred percent.
• noxfile.py
  • Purpose: Provides Nox sessions to run ruff, mypy and bandit against the src and tests directories.
  • Highlights: Targets Python 3.13 only, uses a src layout, and centralises helper functions for installation and command execution so that session definitions stay concise and consistent.
• .github/workflows/main.yml
  • Purpose: Defines a GitHub Actions workflow that runs on pushes to main and pull requests.
  • Highlights: Uses uv for all Python related commands, runs pre-commit, executes Nox sessions and runs the test suite with coverage across Ubuntu, macOS and Windows. Targets Python 3.13 exclusively.
• .github/actions/setup-uv-env/
  • Purpose: Provides a small composite action that installs uv and the requested Python version for use in the workflow.
  • Highlights: Wraps astral-sh/setup-uv so the workflow can remain concise and can request a specific Python version using a single input.

Prerequisites

• Python: Version 3.13 or newer must be installed on your system.
• uv: The uv tool must be installed so that environments and dependencies can be managed consistently.
• Git: Recommended for using the pre-commit hooks and GitHub Actions workflow.

Initial setup

To start using this template locally, follow these steps.

• 1. Clone or copy the repository

  Clone the repository or copy its contents into a new directory, then update the project metadata as needed for your environment.

• 2. Create and use a uv environment

  Use uv to create and activate a virtual environment and install development dependencies.

  uv venv
  source .venv/bin/activate  # or the platform equivalent
  uv sync --group dev

• 3. Run the test suite

  Use uv to run the tests and confirm that the tooling is wired up correctly.

  uv run pytest

• 4. Run the linters and static analysis

  Use the Nox sessions to run linting, type checking and security scanning over the src and tests directories.

  uv run nox -s ruff
  uv run nox -s mypy
  uv run nox -s bandit

Pre-commit usage

Once development dependencies are installed you can enable pre-commit hooks so that tests with full coverage run before each commit.

uv run pre-commit install

After installation, any git commit will automatically run the configured hook and will fail if the tests do not pass or if coverage drops below one hundred percent. This keeps the template strictly tested as you add new code and tests.