Metadata-Version: 2.1
Name: nami-ai
Version: 1.0.0
Summary: nami — AI coding agent
Author-email: nami <admin@nami.dev>
License: MIT
Keywords: ai,agent,coding,cli,assistant
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests >=2.31.0
Requires-Dist: rich >=13.7.0
Requires-Dist: textual >=0.80.0
Requires-Dist: python-dotenv >=1.0.0
Requires-Dist: PyMuPDF >=1.23.0
Requires-Dist: openpyxl >=3.1.0
Requires-Dist: python-docx >=1.1.0
Requires-Dist: Pillow >=10.0.0
Requires-Dist: charset-normalizer >=3.0.0
Provides-Extra: mcp
Requires-Dist: mcp >=1.0.0 ; extra == 'mcp'

# ═══════════════════════════════════════════════════════════════════════════════
#  PRODUCTION-GRADE PYTHON APPLICATION
# ═══════════════════════════════════════════════════════════════════════════════

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

---

## 📋 Table of Contents

- [Features](#-features)
- [Quick Start](#-quick-start)
- [Project Structure](#-project-structure)
- [Development](#-development)
- [Testing](#-testing)
- [Deployment](#-deployment)
- [Security](#-security)
- [Monitoring](#-monitoring)
- [Contributing](#-contributing)
- [License](#-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**
   ```bash
   git clone <repository-url>
   cd nami
   ```

2. **Set up virtual environment**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

4. **Install pre-commit hooks**
   ```bash
   pre-commit install
   ```

5. **Configure environment**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

6. **Run the application**
   ```bash
   # 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**
   ```bash
   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

```bash
# 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
```bash
pytest tests/ -v --cov=src --cov-report=html
```

### Run Specific Test Categories
```bash
pytest tests/unit/          # Unit tests
pytest tests/integration/  # Integration tests
```

### Run with Coverage
```bash
pytest tests/ --cov=src --cov-report=xml --cov-fail-under=80
```

### Performance Benchmarking
```bash
pytest tests/ --benchmark-only
```

### Generate Coverage Report
```bash
make test-coverage
# Open htmlcov/index.html in browser
```

---

## 🐳 Deployment

### Docker

Build and run:
```bash
docker build -t myapp:latest .
docker run -p 8000:8000 --env-file .env myapp:latest
```

Using Docker Compose:
```bash
docker-compose up -d
```

### Kubernetes

```bash
# 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: security@example.com

---

## 📊 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](docs/) or open an issue.
