ai-agent-policy-api

This is work-in-progress. See To Do List

• ai-agent-policy-api
  • Requirements
    • Python
    • Linting and Formatting
    • Docker
  • Local development
    • Setup & Configuration
    • Development
    • Testing
    • Production Mode
  • API endpoints
  • Custom Cloudwatch Metrics
  • Pipelines
    • Dependabot
    • SonarCloud
  • Licence
    • About the licence

Requirements

Python

Please install python >= 3.12 and configure your python virtual environment:

# create the virtual environment
python -m venv .venv

# activate the the virtual environment in the command line
source .venv/bin/activate

# update pip
python -m pip install --upgrade pip

# install the dependencies
pip install -r requirements-dev.txt

# install the pre-commit hooks
pre-commit install

This opinionated template uses the Fast API Python API framework.

This and all other runtime python libraries must reside in requirements.txt

Other non-runtime dependencies used for dev & test must reside in requirements-dev.txt

Linting and Formatting

This project uses Ruff for linting and formatting Python code.

Running Ruff

To run Ruff from the command line:

# Run linting with auto-fix
ruff check . --fix

# Run formatting
ruff format .

Pre-commit Hooks

This project uses pre-commit to run linting and formatting checks automatically before each commit.

The pre-commit configuration is defined in .pre-commit-config.yaml

To set up pre-commit hooks:

# Set up the git hooks
pre-commit install

To run the hooks manually on all files:

pre-commit run --all-files

VS Code Configuration

For the best development experience, configure VS Code to use Ruff:

1. Install the Ruff extension for VS Code
2. Configure your VS Code settings (.vscode/settings.json):

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": "explicit",
        "source.organizeImports.ruff": "explicit"
    },
    "ruff.lint.run": "onSave",
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    }
}

This configuration will:

• Format your code with Ruff when you save a file
• Fix linting issues automatically when possible
• Organize imports according to isort rules

Ruff Configuration

Ruff is configured in the .ruff.toml file

Docker

This repository uses Docker throughput its lifecycle i.e. both for local development and the environments. A benefit of this is that environment variables & secrets are managed consistently throughout the lifecycle

See the Dockerfile and compose.yml for details

Local development

Setup & Configuration

Follow the convention below for local environment variables and secrets in local development. Note that it does not use .env or python-dotenv as this is not the convention in the CDP environment.

Environment variables: compose/aws.env.

Secrets: compose/secrets.env. You need to create this, as it's excluded from version control.

Libraries: Ensure the python virtual environment is configured and libraries are installed using requirements-dev.txt, as above

Pre-Commit Hooks: Ensure you install the pre-commit hooks, as above

Development

The app can be run locally using Docker compose. This template contains a local environment with:

• Localstack
• MongoDB
• This service

To run the application in development mode:

docker compose watch

The service will then run on http://localhost:8085

Testing

Ensure the python virtual environment is configured and libraries are installed using requirements-dev.txt, as above

Testing follows the FastApi documented approach; using pytest & starlette.

To test the application run:

pytest

Production Mode

To mimic the application running in `production mode locally run:

docker compose up --build -d

The service will then run on http://localhost:8085

Stop the application with

docker compose down

API endpoints

Endpoint	Description
GET: /docs	Automatic API Swagger docs
GET: /example	Simple example

Custom Cloudwatch Metrics

Uses the aws embedded metrics library. An example can be found in metrics.py

In order to make this library work in the environments, the environment variable AWS_EMF_ENVIRONMENT=local is set in the app config. This tells the library to use the local cloudwatch agent that has been configured in CDP, and uses the environment variables set up in CDP AWS_EMF_AGENT_ENDPOINT, AWS_EMF_LOG_GROUP_NAME, AWS_EMF_LOG_STREAM_NAME, AWS_EMF_NAMESPACE, AWS_EMF_SERVICE_NAME

Pipelines

Dependabot

We have added an example dependabot configuration file to the repository. You can enable it by renaming the .github/example.dependabot.yml to .github/dependabot.yml

SonarCloud

Instructions for setting up SonarCloud can be found in sonar-project.properties

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.