Skip to main content

Quick Start: Python

Open Repo Download ZIP

git clone https://github.com/AEEF-AI/aeef-quickstart.git my-project

This guide walks through setting up the AEEF Quick Start tier for a Python project. By the end, you will have a running FastAPI application with AI tool configuration, linting, testing, security scanning, and CI -- all enforcing AEEF standards.

Prerequisites​

  • Python 3.12+ -- Required for modern type hint syntax and performance improvements
  • uv 0.4+ -- Fast Python package manager and project tool
  • Git 2.30+ -- For branch protection and conventional commits
  • An AI coding tool configured for your IDE

Verify your environment:

python --version   # 3.12.x
uv --version       # 0.4.x
git --version      # 2.30+

Step-by-Step Setup​

1. Create the Project​

git clone https://github.com/AEEF-AI/aeef-quickstart.git my-py-project
cd my-py-project

# Run the Python setup
./scripts/setup.sh --lang python

2. Install Dependencies​

uv sync

This creates a virtual environment and installs the application and dev dependencies: FastAPI, pytest, Ruff, Semgrep, and their supporting packages.

3. Verify the Configuration​

uv run check

This executes: ruff check, ruff format --check, mypy, pytest --cov, and semgrep.

File-by-File Walkthrough​

pyproject.toml -- Project Configuration​

The pyproject.toml centralizes all tool configuration in a single file, following Python packaging best practices:

[project]
name = "aeef-quickstart"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn>=0.32.0",
    "pydantic>=2.10.0",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=80"

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "PT", "RUF"]

ruff.toml -- Linter and Formatter​

Ruff replaces both flake8 and black, providing linting and formatting in a single tool. The configuration enforces complexity limits aligned with PRD-STD-006:

[lint]
select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "PT", "RUF"]

[lint.mccabe]
max-complexity = 10

[lint.per-file-ignores]
"tests/**/*.py" = ["S101"]  # Allow assert in tests

pytest.ini / pyproject.toml [tool.pytest] -- Test Configuration​

Pytest is configured with an 80% coverage threshold, enforcing PRD-STD-003:

[pytest]
testpaths = tests
addopts = --cov=src --cov-report=term-missing --cov-fail-under=80

.cursorrules -- Cursor IDE Configuration​

Instructs Cursor to follow AEEF patterns for Python code generation:

You are assisting on a Python project governed by AEEF Standards.
All AI-generated code MUST:
- Use type hints on all function signatures
- Include docstrings following Google style
- Include pytest tests for any new functions
- Use Pydantic models for data validation
- Never introduce dependencies without explicit approval

.github/workflows/ci.yml -- CI Pipeline​

name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
      - run: uv sync
      - run: uv run ruff check src/ tests/
      - run: uv run ruff format --check src/ tests/
      - run: uv run mypy src/
      - run: uv run pytest --cov --cov-fail-under=80
      - run: uv run semgrep --config .semgrep/ src/
      - run: uv run pip-audit

.semgrep/ -- Security Rules​

Custom Semgrep rules for Python:

  • ai-code-patterns.yml -- Detects patterns commonly introduced by AI tools (hardcoded credentials, debug mode in production, unvalidated input)
  • python-security.yml -- Python-specific rules (SQL injection via f-strings, pickle deserialization, subprocess shell injection)

Running the Example Application​

# Development server with auto-reload
uv run uvicorn src.main:app --reload --port 8000

# Run with production settings
uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4

The example application is a minimal FastAPI service with health check, user CRUD, and input validation endpoints demonstrating AEEF-compliant patterns.

Making Your First AI-Assisted PR​

  1. Create a feature branch:

    git checkout -b feat/add-input-validation

  2. Use your AI tool to generate a new endpoint or utility.

  3. Verify test coverage:

    uv run pytest --cov --cov-report=html

  4. Run the full suite:

    uv run check

  5. Commit and push:

    git add .
    git commit -m "feat: add pydantic schema for user registration"
    git push -u origin feat/add-input-validation

  6. Open a PR and complete the AI-disclosure checklist in the PR template.

Running Security Scans Locally​

# Semgrep SAST scan
uv run semgrep --config .semgrep/ src/

# Dependency vulnerability audit
uv run pip-audit

# Check for known CVEs in lockfile
uv run safety check

Next Steps​

Last updated on by BalrogEg