nami-ai 1.0.0

nami — AI coding agent

═══════════════════════════════════════════════════════════════════════════════

PRODUCTION-GRADE PYTHON APPLICATION

═══════════════════════════════════════════════════════════════════════════════

A comprehensive, production-ready Python application template with best practices, testing, security, and deployment configurations.

---

📋 Table of Contents

• Features
• Quick Start
• Project Structure
• Development
• Testing
• Deployment
• Security
• Monitoring
• Contributing
• License

---

✨ Features

Code Quality

• ✅ Black - Uncompromising code formatting
• ✅ isort - Import sorting
• ✅ Ruff - Fast Python linter
• ✅ mypy - Static type checking
• ✅ pre-commit - Git hooks for quality gates

Testing

• ✅ pytest - Testing framework
• ✅ pytest-cov - Coverage reporting
• ✅ pytest-xdist - Parallel test execution
• ✅ pytest-benchmark - Performance benchmarking
• ✅ Factory Boy - Test data generation
• ✅ Faker - Realistic fake data

Security

• ✅ Bandit - Security linting
• ✅ Safety - Dependency vulnerability scanning
• ✅ detect-secrets - Secret detection
• ✅ OWASP - Security best practices

Containerization

• ✅ Docker - Multi-stage builds
• ✅ docker-compose - Local development
• ✅ Health checks - Container health monitoring
• ✅ Non-root user - Security hardening

CI/CD

• ✅ GitHub Actions - Automated pipeline
• ✅ Multi-stage jobs - Lint, test, build, deploy
• ✅ Code coverage - Codecov integration
• ✅ Security scanning - Automated security checks

Monitoring & Observability

• ✅ Structured logging - JSON logging
• ✅ Metrics - Prometheus metrics
• ✅ Tracing - OpenTelemetry integration
• ✅ Health checks - Application health endpoints

Configuration

• ✅ Environment-based - 12-factor app
• ✅ Pydantic - Settings validation
• ✅ Multiple environments - dev, staging, prod

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker & Docker Compose
• Git

Local Development

1. Clone the repository

   git clone <repository-url>
   cd nami
   

2. Set up virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install --upgrade pip
   pip install -r requirements.txt
   

4. Install pre-commit hooks

   pre-commit install
   

5. Configure environment

   cp .env.example .env
   # Edit .env with your configuration
   

6. Run the application

   # Development server
   uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
   
   # Or using Docker Compose
   docker-compose up -d
   

7. Run tests

   pytest tests/ -v --cov=src --cov-report=html
   

---

📁 Project Structure

nami/
├── src/                          # Application source code
│   ├── api/                      # API routes
│   │   ├── v1/                   # API version 1
│   │   │   ├── endpoints/        # Route handlers
│   │   │   └── __init__.py
│   │   └── __init__.py
│   ├── core/                     # Core functionality
│   │   ├── config.py             # Configuration management
│   │   ├── logging.py            # Logging setup
│   │   ├── security.py           # Security utilities
│   │   └── __init__.py
│   ├── models/                   # Data models
│   │   ├── schemas.py            # Pydantic schemas
│   │   └── __init__.py
│   ├── services/                 # Business logic
│   │   ├── __init__.py
│   │   └── example_service.py
│   ├── utils/                    # Utilities
│   │   ├── __init__.py
│   │   └── helpers.py
│   ├── main.py                   # Application entry point
│   └── __init__.py
├── tests/                        # Test suite
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   ├── conftest.py               # pytest fixtures
│   └── test_production.py        # Production tests
├── scripts/                      # Helper scripts
│   ├── generate_secrets_baseline.sh
│   └── setup.sh
├── .github/                      # GitHub configuration
│   └── workflows/
│       └── ci.yml                # CI/CD pipeline
├── docker/                       # Docker configuration
│   ├── nginx/
│   │   └── nginx.conf
│   └── entrypoint.sh
├── .pre-commit-config.yaml       # Pre-commit hooks
├── .env.example                  # Environment template
├── .secrets.baseline             # Detect-secrets baseline
├── Makefile                      # Development commands
├── Dockerfile                    # Production Docker image
├── docker-compose.yml            # Local development
├── requirements.txt              # Python dependencies
├── pyproject.toml                # Project metadata
├── README.md                     # This file
└── LICENSE                       # License file

---

🛠️ Development

Available Make Commands

# Development
make install          # Install dependencies
make dev              # Start development server
make dev-docker       # Start with Docker Compose

# Code Quality
make lint             # Run all linters
make format           # Format code with Black & isort
make type-check       # Run mypy type checking
make security         # Run security scans

# Testing
make test             # Run tests with coverage
make test-unit        # Run unit tests only
make test-integration # Run integration tests only
make test-benchmark   # Run performance benchmarks
make test-coverage    # Generate coverage report

# Docker
make build            # Build Docker image
make push             # Push to registry
make docker-logs      # View container logs

# Utilities
make clean            # Clean build artifacts
make backup           # Create backup
make health-check     # Check application health

Environment Variables

See .env.example for all available configuration options.

Key variables:

• APP_ENV - Environment (development, staging, production)
• DATABASE_URL - Database connection string
• SECRET_KEY - Application secret key
• LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)

---

🧪 Testing

Run All Tests

pytest tests/ -v --cov=src --cov-report=html

Run Specific Test Categories

pytest tests/unit/          # Unit tests
pytest tests/integration/  # Integration tests

Run with Coverage

pytest tests/ --cov=src --cov-report=xml --cov-fail-under=80

Performance Benchmarking

pytest tests/ --benchmark-only

Generate Coverage Report

make test-coverage
# Open htmlcov/index.html in browser

---

🐳 Deployment

Docker

Build and run:

docker build -t myapp:latest .
docker run -p 8000:8000 --env-file .env myapp:latest

Using Docker Compose:

docker-compose up -d

Kubernetes

# Build and push
make build push

# Deploy
kubectl apply -f k8s/

Environment Configuration

1. Development - Local with hot reload
2. Staging - Pre-production testing
3. Production - Live environment

Each environment uses different configuration via environment variables.

---

🔒 Security

Best Practices Implemented

• ✅ Secrets detection (detect-secrets)
• ✅ Dependency vulnerability scanning (Safety)
• ✅ Security linting (Bandit)
• ✅ Non-root Docker user
• ✅ Input validation (Pydantic)
• ✅ Rate limiting
• ✅ CORS configuration
• ✅ Security headers

Reporting Vulnerabilities

Please report security issues to: [e-mail]

---

📊 Monitoring

Health Checks

• /health - Application health
• /metrics - Prometheus metrics
• /ready - Readiness probe
• /live - Liveness probe

Logging

Structured JSON logging with levels:

• DEBUG - Detailed debugging
• INFO - General information
• WARNING - Warnings
• ERROR - Errors
• CRITICAL - Critical failures

Metrics

• Request count
• Response time
• Error rate
• System resources

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Install pre-commit hooks: pre-commit install
4. Make changes and run tests
5. Submit a pull request

Code Standards

• Follow PEP 8
• Use type hints
• Write tests for new features
• Update documentation

---

📄 License

MIT License - see LICENSE file for details.

---

═══════════════════════════════════════════════════════════════════════════════

QUICK REFERENCE

═══════════════════════════════════════════════════════════════════════════════

Task	Command
Install dependencies	make install or pip install -r requirements.txt
Start development	make dev or uvicorn src.main:app --reload
Run tests	make test or pytest tests/
Format code	make format or black . && isort .
Lint code	make lint or ruff .
Type check	make type-check or mypy src/
Security scan	make security or bandit -r src/
Build Docker image	make build or docker build -t app .
Docker Compose up	make dev-docker or docker-compose up -d

---

Need help? Check the documentation or open an issue.