Pygentic-AI/.specify/memory/constitution.md

Pygentic-AI Constitution

Core Principles

I. Test-Driven Development (NON-NEGOTIABLE)

Tests MUST be written before implementation. The TDD cycle is strictly enforced:

1. Write tests that define expected behavior
2. Verify tests fail (Red)
3. Implement minimal code to pass tests (Green)
4. Refactor while maintaining passing tests (Refactor)

Rationale: TDD ensures code correctness, maintainability, and prevents regressions. Pre-written tests serve as living documentation and enable confident refactoring.

II. API-First Design

All features MUST expose well-defined APIs with clear contracts. API specifications MUST be documented before implementation, including:

• Request/response schemas using Pydantic models
• Error handling and status codes
• Authentication/authorization requirements
• Rate limiting and performance characteristics

Rationale: API-first design enables parallel development of frontend/backend, facilitates integration testing, and ensures consistent interfaces across the system.

III. Asynchronous Architecture

The system MUST leverage asynchronous patterns for I/O-bound operations:

• FastAPI async endpoints for web APIs
• Celery for long-running background tasks
• Redis for caching and task queuing
• Async database operations with asyncpg/aiomysql

Rationale: AI model invocations and external API calls are I/O-bound. Async patterns maximize throughput, reduce latency, and improve resource utilization for concurrent requests.

IV. Observability and Monitoring

Every component MUST implement comprehensive observability:

• Structured logging with contextual information (logfire, loguru)
• OpenTelemetry instrumentation for distributed tracing
• Metrics collection for performance monitoring (Prometheus)
• Error tracking with detailed context

Rationale: AI systems are inherently complex and opaque. Observability is essential for debugging, performance optimization, and understanding system behavior in production.

V. Type Safety and Validation

Code MUST be type-annotated and validated at runtime:

• Pydantic models for all data structures
• Type hints for all function signatures
• Runtime validation at API boundaries
• Static type checking with mypy (when enabled)

Rationale: Type safety catches errors early, improves IDE support, serves as documentation, and prevents invalid data from propagating through the system.

VI. Security by Default

Security MUST be built into every layer:

• No credentials in code (use environment variables)
• Input validation and sanitization at all entry points
• Authentication and authorization for all protected endpoints
• SQL injection prevention through parameterized queries
• Regular security audits (Bandit for Python)

Rationale: AI services handle sensitive data and API keys. A single security vulnerability can compromise the entire system and user data.

Development Standards

Code Quality

• Formatting: Black (line length: 80), isort for imports
• Linting: Ruff with enabled rules (E, F, B), max complexity: 10
• Documentation: Docstrings for all public APIs, inline comments for complex logic
• Error Handling: Explicit exception handling with meaningful error messages
• Dependencies: Use uv for dependency management, pin versions in requirements

Testing Requirements

• Unit Tests: Test individual functions/methods in isolation
• Integration Tests: Test component interactions (API + database, service + external APIs)
• Contract Tests: Verify API contracts match specifications
• Coverage: Aim for >80% code coverage, 100% for critical paths
• Test Independence: Tests MUST be independent and runnable in any order

Architecture Patterns

• Service Layer: Business logic isolated from API/database layers
• Repository Pattern: Database access abstracted behind repositories (using FastCRUD)
• Dependency Injection: FastAPI's dependency injection for services and configurations
• Background Tasks: Long-running operations delegated to Celery workers
• Caching Strategy: Redis caching for expensive operations (AI model results, API responses)

Quality Assurance

Pre-Commit Requirements

All commits MUST pass:

1. Code formatting (Black, isort)
2. Linting (Ruff)
3. Type checking (if enabled)
4. Security scan (Bandit)
5. All tests passing

Use pre-commit hooks to enforce these checks automatically.

Code Review Standards

All changes MUST be reviewed before merge:

• Verify tests exist and pass
• Check for security vulnerabilities
• Validate error handling and edge cases
• Ensure observability (logging, metrics)
• Confirm documentation is updated
• Validate performance impact for critical paths

Deployment Gates

Production deployments MUST satisfy:

• All tests passing in CI/CD pipeline
• Security scan clean (no high/critical vulnerabilities)
• Performance benchmarks within acceptable thresholds
• Database migrations tested and reversible
• Rollback plan documented

Governance

Amendment Process

Constitution amendments require:

1. Proposal with clear rationale and impact assessment
2. Discussion period (minimum 3 days for minor, 7 days for major changes)
3. Team consensus or majority vote
4. Documentation of decision and migration plan
5. Version bump according to semantic versioning

Versioning Policy

• MAJOR: Backward-incompatible changes to core principles or mandatory requirements
• MINOR: New principles added or existing principles materially expanded
• PATCH: Clarifications, wording improvements, non-semantic refinements

Compliance

• All code reviews MUST verify compliance with this constitution
• Violations MUST be justified with documented rationale
• Technical debt MUST be tracked and addressed systematically
• Constitution supersedes all other development practices

Complexity Justification

Any deviation from YAGNI (You Aren't Gonna Need It) MUST be justified:

• Document the specific problem being solved
• Explain why simpler alternatives are insufficient
• Provide measurable success criteria
• Plan for future simplification if possible

Version: 1.0.0 | Ratified: 2025-01-16 | Last Amended: 2026-02-02