moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-python/SKILL.md

@@ -1,431 +1,481 @@
 ---
-
 name: moai-lang-python
-version: 2.0.0
-created: 2025-10-22
-updated: 2025-10-22
+description: Python 3.13+ development specialist covering FastAPI, Django, async patterns, data science, testing with pytest, and modern Python features. Use when developing Python APIs, web applications, data pipelines, or writing tests.
+version: 1.0.0
+updated: 2025-12-07
 status: active
-description: Python 3.13+ best practices with pytest 8.4.2, mypy 1.8.0, ruff 0.13.1, and uv 0.9.3. Use when writing or reviewing Python code in project workflows.
-keywords: [python, testing, pytest, mypy, ruff, uv, async, fastapi, pydantic]
-allowed-tools:
-  - Read
-  - Bash
+allowed-tools: Read, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
 ---
 
-# Python 3.13 Expert Skill
-
-## Skill Metadata
+## Quick Reference (30 seconds)
 
-| Field | Value |
-| ----- | ----- |
-| **Skill Name** | moai-lang-python |
-| **Version** | 2.0.0 (2025-10-22) |
-| **Python Support** | 3.13.1 (latest), 3.12.7 (LTS), 3.11.10 (maintenance) |
-| **Allowed tools** | Read (read_file), Bash (terminal) |
-| **Auto-load** | On demand when language keywords detected |
-| **Trigger cues** | `.py` files, Python frameworks, TDD discussions, async patterns |
-| **Tier** | Language / 23 (comprehensive coverage) |
+Python 3.13+ Development Specialist - FastAPI, Django, async patterns, pytest, and modern Python features.
 
----
+Auto-Triggers: `.py` files, `pyproject.toml`, `requirements.txt`, `pytest.ini`, FastAPI/Django discussions
 
-## What It Does
+Core Capabilities:
+- Python 3.13 Features: JIT compiler (PEP 744), GIL-free mode (PEP 703), pattern matching
+- Web Frameworks: FastAPI 0.115+, Django 5.2 LTS
+- Data Validation: Pydantic v2.9 with model_validate patterns
+- ORM: SQLAlchemy 2.0 async patterns
+- Testing: pytest with fixtures, async testing, parametrize
+- Package Management: poetry, uv, pip with pyproject.toml
+- Type Hints: Protocol, TypeVar, ParamSpec, modern typing patterns
+- Async: asyncio, async generators, task groups
+- Data Science: numpy, pandas, polars basics
 
-Provides **Python 3.13+ expertise** for modern TDD development, including:
+### Quick Patterns
 
-- ✅ **Testing Framework**: pytest 8.4.2 (fixtures, asyncio, parametrization)
-- ✅ **Code Quality**: ruff 0.13.1 (unified linter + formatter, replaces black/pylint)
-- ✅ **Type Safety**: mypy 1.8.0 + Pydantic 2.7.0 (static + runtime validation)
-- ✅ **Package Management**: uv 0.9.3 (10x faster than pip)
-- ✅ **Python 3.13 Features**: PEP 695 (type params), PEP 701 (f-strings), PEP 698 (@override)
-- ✅ **Async/Await**: asyncio.TaskGroup, context variables, concurrent patterns
-- ✅ **Security**: Secrets module, secure hashing, SQLAlchemy 2.0.28
+FastAPI Endpoint:
+```python
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
 
----
+app = FastAPI()
 
-## When to Use
+class UserCreate(BaseModel):
+    name: str
+    email: str
 
-**Automatic triggers**:
-- Python code discussions, `.py` files, framework guidance
-- "Writing Python tests", "How to use pytest", "Python type hints"
-- Python SPEC implementation (`/alfred:2-run`)
-- Async pattern requests
+@app.post("/users/")
+async def create_user(user: UserCreate) -> User:
+    return await UserService.create(user)
+```
 
-**Manual invocation**:
-- Review Python code for TRUST 5 compliance
-- Design Python microservices (FastAPI 0.115.0 recommended)
-- Upgrade from Python 3.12 to 3.13
-- Refactor async code to use TaskGroup
+Pydantic v2.9 Validation:
+```python
+from pydantic import BaseModel, ConfigDict
 
----
+class User(BaseModel):
+    model_config = ConfigDict(from_attributes=True, str_strip_whitespace=True)
 
-## How It Works (Best Practices)
+    id: int
+    name: str
+    email: str
 
-### 1. TDD Framework (pytest 8.4.2)
+user = User.model_validate(orm_obj)  # from ORM object
+user = User.model_validate_json(json_data)  # from JSON
+```
 
+pytest Async Test:
 ```python
-# Test discovery & fixtures
 import pytest
-from src.calculator import add
-
-def test_add_positive_numbers():
-    """Verify addition of positive integers."""
-    assert add(2, 3) == 5
 
 @pytest.mark.asyncio
-async def test_async_operation():
-    """Test async functions with pytest-asyncio."""
-    result = await async_fetch_data()
-    assert result is not None
+async def test_create_user(async_client):
+    response = await async_client.post("/users/", json={"name": "Test"})
+    assert response.status_code == 201
 ```
 
-**Key Points**:
-- ✅ Use pytest 8.4.2+ (not unittest)
-- ✅ One assertion per test (clarity)
-- ✅ Fixtures for setup/teardown
-- ✅ `pytest.mark.asyncio` for async tests
-- ✅ `pytest-mock` for mocking (not mock.patch)
-- ✅ Coverage ≥85% enforced by quality gate
+---
 
-**CLI Commands**:
-```bash
-pytest                              # Run all tests
-pytest -v                           # Verbose output
-pytest --cov=src --cov-report=term # Coverage report (≥85% required)
-pytest -k "pattern"                 # Run matching tests
-pytest -m asyncio                   # Run async tests only
-```
+## Implementation Guide (5 minutes)
 
-### 2. Code Quality (ruff 0.13.1 — NEW STANDARD)
+### Python 3.13 New Features
 
-**⚠️ BREAKING CHANGE**: Ruff 0.13.1 replaces black + pylint + isort. Update workflows:
+JIT Compiler (PEP 744):
+- Experimental feature, disabled by default
+- Enable: `PYTHON_JIT=1` environment variable
+- Build option: `--enable-experimental-jit`
+- Provides performance improvements for CPU-bound code
+- Copy-and-patch JIT that translates specialized bytecode to machine code
 
-```yaml
-# OLD (deprecated)
-- black .                           # Format
-- pylint src/                       # Lint
-- isort .                           # Import sort
+GIL-Free Mode (PEP 703):
+- Experimental free-threaded build (python3.13t)
+- Allows true parallel thread execution
+- Available in official Windows/macOS installers
+- Best for: CPU-intensive multi-threaded applications
+- Not recommended for production yet
 
-# NEW (ruff 0.13.1)
-- ruff check . --fix                # Lint + fix
-- ruff format .                     # Format (replaces black)
+Pattern Matching (match/case):
+```python
+def process_response(response: dict) -> str:
+    match response:
+        case {"status": "ok", "data": data}:
+            return f"Success: {data}"
+        case {"status": "error", "message": msg}:
+            return f"Error: {msg}"
+        case {"status": status} if status in ("pending", "processing"):
+            return "In progress..."
+        case _:
+            return "Unknown response"
 ```
 
-**Configuration** (`pyproject.toml`):
-```toml
-[tool.ruff]
-line-length = 100
-target-version = "py313"
+### FastAPI 0.115+ Patterns
 
-[tool.ruff.lint]
-select = ["E", "F", "W"]  # Errors, formatting, warnings
-extend-select = ["I"]     # Import sorting (replaces isort)
+Async Dependency Injection:
+```python
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await init_db()
+    yield
+    # Shutdown
+    await cleanup()
+
+app = FastAPI(lifespan=lifespan)
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        yield session
+
+@app.get("/users/{user_id}")
+async def get_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db)
+) -> UserResponse:
+    user = await get_user_by_id(db, user_id)
+    return UserResponse.model_validate(user)
 ```
 
-**CLI Commands**:
-```bash
-ruff check .                        # Lint all files
-ruff format .                       # Format with auto-fix
-ruff check --show-fixes .           # Show what would be fixed
-ruff check --select E501 .          # Check specific rule (line length)
-```
+Class-Based Dependencies:
+```python
+from fastapi import Depends
+
+class Paginator:
+    def __init__(self, page: int = 1, size: int = 20):
+        self.page = max(1, page)
+        self.size = min(100, max(1, size))
+        self.offset = (self.page - 1) * self.size
 
-### 3. Type Safety (mypy 1.8.0 + Pydantic 2.7.0)
+@app.get("/items/")
+async def list_items(pagination: Paginator = Depends()) -> list[Item]:
+    return await Item.get_page(pagination.offset, pagination.size)
+```
 
-**Static Type Checking** (mypy):
+### Django 5.2 LTS Features
 
+Composite Primary Keys:
 ```python
-from typing import override
+from django.db import models
 
-class Parent:
-    def method(self, x: int) -> str: ...
+class OrderItem(models.Model):
+    order = models.ForeignKey(Order, on_delete=models.CASCADE)
+    product = models.ForeignKey(Product, on_delete=models.CASCADE)
+    quantity = models.IntegerField()
 
-class Child(Parent):
-    @override  # NEW in Python 3.13 — mypy validates this
-    def method(self, x: int) -> str:
-        return str(x)
+    class Meta:
+        pk = models.CompositePrimaryKey("order", "product")
 ```
 
-**Runtime Validation** (Pydantic 2.7.0):
-
+URL Reverse with Query Parameters:
 ```python
-from pydantic import BaseModel, Field
+from django.urls import reverse
 
-class User(BaseModel):
-    id: int = Field(gt=0)           # Must be > 0
-    name: str = Field(min_length=1)
-    email: str                      # Auto-validated as email
+url = reverse("search", query={"q": "django", "page": 1}, fragment="results")
+# /search/?q=django&page=1#results
 ```
 
-**CLI Commands**:
+Automatic Model Imports in Shell:
 ```bash
-mypy .                              # Run type checker
-mypy --strict .                     # Strict mode (recommended)
-mypy --show-column-numbers .        # Precise error locations
+python manage.py shell
+# Models from all installed apps are automatically imported
 ```
 
-### 4. Package Management (uv 0.9.3)
+### Pydantic v2.9 Deep Patterns
 
-**Why uv?**: 10x faster than pip, integrated with ruff + pytest
+Reusable Validators with Annotated:
+```python
+from typing import Annotated
+from pydantic import AfterValidator, BaseModel
 
-```bash
-# Create virtual environment
-uv venv                             # Create .venv/
-source .venv/bin/activate           # Activate
+def validate_positive(v: int) -> int:
+    if v <= 0:
+        raise ValueError("Must be positive")
+    return v
 
-# Install dependencies
-uv add pytest ruff mypy             # Add to pyproject.toml
-uv add --dev pytest-asyncio         # Add as dev dependency
-uv sync                             # Install all (from lock file)
+PositiveInt = Annotated[int, AfterValidator(validate_positive)]
 
-# Publish
-uv publish                          # Push to PyPI
+class Product(BaseModel):
+    price: PositiveInt
+    quantity: PositiveInt
 ```
 
-**pyproject.toml** (uv config):
-```toml
-[project]
-name = "my-project"
-version = "2.0.0"
-requires-python = ">=3.13"
-
-[project.optional-dependencies]
-dev = ["pytest>=8.4.2", "ruff>=0.13.1", "mypy>=1.8.0"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+Model Validator for Cross-Field Validation:
+```python
+from pydantic import BaseModel, model_validator
+from typing import Self
+
+class DateRange(BaseModel):
+    start_date: date
+    end_date: date
+
+    @model_validator(mode="after")
+    def validate_dates(self) -> Self:
+        if self.end_date < self.start_date:
+            raise ValueError("end_date must be after start_date")
+        return self
 ```
 
-### 5. Async Patterns (Python 3.13)
-
-**TaskGroup** (cleaner than `asyncio.gather`):
-
+ConfigDict Best Practices:
 ```python
-import asyncio
-
-async def main():
-    async with asyncio.TaskGroup() as tg:
-        task1 = tg.create_task(fetch_user(1))
-        task2 = tg.create_task(fetch_posts(1))
-        # Tasks run concurrently
-        # Exceptions propagate automatically (no need for gather)
-
-asyncio.run(main())
+from pydantic import BaseModel, ConfigDict
+
+class BaseSchema(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,      # ORM object support
+        populate_by_name=True,     # Allow aliases
+        extra="forbid",            # Fail on unknown fields
+        str_strip_whitespace=True, # Clean strings
+    )
 ```
 
-**Context Variables** (thread-safe in async):
+### SQLAlchemy 2.0 Async Patterns
 
+Engine and Session Setup:
 ```python
-from contextvars import ContextVar
-
-request_id = ContextVar('request_id', default=None)
-
-async def handle_request(req_id):
-    token = request_id.set(req_id)
-    # All spawned tasks inherit this context var
-    await process_async()
+from sqlalchemy.ext.asyncio import (
+    create_async_engine,
+    async_sessionmaker,
+    AsyncSession,
+)
+
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@localhost/db",
+    pool_pre_ping=True,
+    echo=True,
+)
+
+async_session = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,  # Prevent detached instance errors
+)
 ```
 
-### 6. Security Best Practices
-
-**Secrets Module** (token generation):
+Repository Pattern:
 ```python
-import secrets
-
-api_key = secrets.token_urlsafe(32)  # Safe random tokens
-nonce = secrets.token_bytes(16)       # Cryptographic nonce
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+class UserRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def get_by_id(self, user_id: int) -> User | None:
+        result = await self.session.execute(
+            select(User).where(User.id == user_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def create(self, user: UserCreate) -> User:
+        db_user = User(**user.model_dump())
+        self.session.add(db_user)
+        await self.session.commit()
+        await self.session.refresh(db_user)
+        return db_user
 ```
 
-**Secure Hashing** (sha256, not md5):
+Streaming Large Results:
 ```python
-import hashlib
-
-# ✅ SECURE
-hash_obj = hashlib.sha256(b"password")
-
-# ❌ INSECURE (removed in Python 3.13)
-hash_obj = hashlib.md5(b"password")   # ValueError!
+async def stream_users(db: AsyncSession):
+    result = await db.stream(select(User))
+    async for user in result.scalars():
+        yield user
 ```
 
----
-
-## Python 3.13 New Features
-
-### PEP 695 — Type Parameter Syntax
+### pytest Advanced Patterns
 
+Async Fixtures with pytest-asyncio:
 ```python
-# OLD (3.12)
-from typing import TypeVar, Generic
-T = TypeVar('T')
-class Stack(Generic[T]):
-    def push(self, item: T) -> None: ...
-
-# NEW (3.13)
-class Stack[T]:
-    def push(self, item: T) -> None: ...
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient
+
+@pytest_asyncio.fixture
+async def async_client(app) -> AsyncGenerator[AsyncClient, None]:
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+@pytest_asyncio.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session() as session:
+        async with session.begin():
+            yield session
+            await session.rollback()
 ```
 
-### PEP 701 — Improved F-Strings
-
+Parametrized Tests:
 ```python
-# NEW: Nested f-strings, arbitrary expressions
-user = {"name": "Alice", "age": 30}
-print(f"User: {user['name']}, Age: {user['age']}")  # Works!
-
-# Nested f-strings
-x = 10
-print(f"Result: {f'{x:>10}'}")  # Works in 3.13!
+@pytest.mark.parametrize(
+    "input_data,expected_status",
+    [
+        ({"name": "Valid"}, 201),
+        ({"name": ""}, 422),
+        ({}, 422),
+    ],
+    ids=["valid", "empty_name", "missing_name"],
+)
+async def test_create_user(async_client, input_data, expected_status):
+    response = await async_client.post("/users/", json=input_data)
+    assert response.status_code == expected_status
 ```
 
-### PEP 698 — Override Decorator
-
+Fixture Factories:
 ```python
-from typing import override
-
-class Parent:
-    def method(self) -> None: ...
-
-class Child(Parent):
-    @override  # mypy checks this is actually overriding
-    def method(self) -> None: ...
+@pytest.fixture
+def user_factory():
+    async def _create_user(db: AsyncSession, **kwargs) -> User:
+        defaults = {"name": "Test User", "email": "test@example.com"}
+        user = User(**(defaults | kwargs))
+        db.add(user)
+        await db.commit()
+        return user
+    return _create_user
 ```
 
----
-
-## Example Workflow
+### Type Hints Modern Patterns
 
-**Setup** (uv + Python 3.13):
-```bash
-uv venv --python 3.13               # Create venv with Python 3.13
-source .venv/bin/activate
-uv add pytest ruff mypy fastapi pydantic
-```
+Protocol for Structural Typing:
+```python
+from typing import Protocol, runtime_checkable
 
-**TDD Loop** (pytest):
-```bash
-pytest                              # RED: Watch tests fail
-# [implement code]
-pytest                              # GREEN: Watch tests pass
-ruff check --fix .                  # REFACTOR: Fix code quality
+@runtime_checkable
+class Repository(Protocol[T]):
+    async def get(self, id: int) -> T | None: ...
+    async def create(self, data: dict) -> T: ...
+    async def delete(self, id: int) -> bool: ...
 ```
 
-**Quality Gate** (before commit):
-```bash
-pytest --cov=src --cov-report=term # Coverage ≥85%?
-ruff check .                        # Lint pass?
-mypy --strict .                     # Type check pass?
+ParamSpec for Decorators:
+```python
+from typing import ParamSpec, TypeVar, Callable
+from functools import wraps
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(times: int = 3) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(times):
+                try:
+                    return await func(*args, **kwargs)
+                except Exception:
+                    if attempt == times - 1:
+                        raise
+        return wrapper
+    return decorator
 ```
 
----
+### Package Management
 
-## Tool Version Matrix (2025-10-22)
+pyproject.toml (Poetry):
+```toml
+[tool.poetry]
+name = "my-project"
+version = "1.0.0"
+python = "^3.13"
 
-| Tool | Version | Purpose | Status |
-|------|---------|---------|--------|
-| **Python** | 3.13.1 | Runtime | ✅ Latest |
-| **pytest** | 8.4.2 | Testing | ✅ Current |
-| **ruff** | 0.13.1 | Lint/Format | ✅ New standard |
-| **mypy** | 1.8.0 | Type checking | ✅ Current |
-| **uv** | 0.9.3 | Package manager | ✅ Recommended |
-| **FastAPI** | 0.115.0 | Web framework | ✅ Latest |
-| **Pydantic** | 2.7.0 | Validation | ✅ Latest |
-| **SQLAlchemy** | 2.0.28 | ORM | ✅ Latest |
+[tool.poetry.dependencies]
+fastapi = "^0.115.0"
+pydantic = "^2.9.0"
+sqlalchemy = {extras = ["asyncio"], version = "^2.0.0"}
 
----
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.24"
+ruff = "^0.8"
 
-## Inputs
+[tool.ruff]
+line-length = 100
+target-version = "py313"
 
-- Python source directories (e.g., `src/`, `app/`)
-- Configuration files (`pyproject.toml`, `pytest.ini`)
-- Test suites and sample data
-- Existing CI/CD workflows
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
 
-## Outputs
+uv (Fast Package Manager):
+```bash
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-- Test/lint execution plan for Python 3.13
-- Code review checklist (TRUST 5 principles)
-- Migration guide (3.12 → 3.13)
-- Performance optimization recommendations
+# Create virtual environment
+uv venv
 
-## Failure Modes
+# Install dependencies
+uv pip install -r requirements.txt
 
-- ❌ Python 3.13 not installed → Recommend `uv venv --python 3.13`
-- ❌ Dependencies missing → Run `uv sync`
-- ❌ Tests fail → Use `debug-helper` agent for triage
+# Add dependency
+uv add fastapi
+```
 
 ---
 
-## Inputs
-
-- Language-specific source directories (e.g. `src/`, `app/`).
-- Language-specific build/test configuration files (e.g. `pyproject.toml`).
-- Relevant test suites and sample data.
-
-## Outputs
+## Advanced Implementation (10+ minutes)
 
-- Test/lint execution plan tailored to Python 3.13+.
-- TRUST 5 review checkpoints (coverage, linting, types, security, tags).
-- Migration path from older Python versions.
+For comprehensive coverage including:
+- Production deployment patterns (Docker, Kubernetes)
+- Advanced async patterns (task groups, semaphores)
+- Data science integration (numpy, pandas, polars)
+- Performance optimization techniques
+- Security best practices (OWASP patterns)
+- CI/CD integration patterns
 
-## Failure Modes
+See:
+- [reference.md](reference.md) - Complete reference documentation
+- [examples.md](examples.md) - Production-ready code examples
 
-- When Python 3.13 runtime is not installed.
-- When project dependencies are not in pyproject.toml.
-- When test coverage falls below 85%.
+---
 
-## Dependencies
+## Context7 Library Mappings
 
-- Access to the project file is required using the Read/Bash tools.
-- Integration with `moai-foundation-langs` for language detection.
-- Integration with `moai-foundation-trust` for quality gate enforcement.
+```
+/tiangolo/fastapi - FastAPI async web framework
+/django/django - Django web framework
+/pydantic/pydantic - Data validation with type annotations
+/sqlalchemy/sqlalchemy - SQL toolkit and ORM
+/pytest-dev/pytest - Testing framework
+/numpy/numpy - Numerical computing
+/pandas-dev/pandas - Data analysis library
+/pola-rs/polars - Fast DataFrame library
+```
 
 ---
 
-## References (Latest Documentation)
+## Works Well With
 
-- **Python 3.13**: https://docs.python.org/3.13/ (accessed 2025-10-22)
-- **pytest 8.4.2**: https://docs.pytest.org/en/stable/ (accessed 2025-10-22)
-- **ruff 0.13.1**: https://docs.astral.sh/ruff/ (accessed 2025-10-22)
-- **mypy 1.8.0**: https://mypy.readthedocs.io/ (accessed 2025-10-22)
-- **uv 0.9.3**: https://docs.astral.sh/uv/ (accessed 2025-10-22)
-- **FastAPI 0.115.0**: https://fastapi.tiangolo.com/ (accessed 2025-10-22)
-- **Pydantic 2.7.0**: https://docs.pydantic.dev/ (accessed 2025-10-22)
+- `moai-domain-backend` - REST API and microservices architecture
+- `moai-domain-database` - SQL patterns and ORM optimization
+- `moai-quality-testing` - TDD and testing strategies
+- `moai-essentials-debug` - AI-powered debugging
+- `moai-foundation-trust` - TRUST 5 quality principles
 
 ---
 
-## Changelog
+## Troubleshooting
 
-- **v2.0.0** (2025-10-22): Major update with Python 3.13 support, ruff 0.13.1 standard, uv 0.9.3 package manager, async/await TaskGroup patterns, security best practices, PEP 695/701/698 features
-- **v1.0.0** (2025-03-29): Initial Skill with pytest, mypy, ruff, black, uv coverage
+Common Issues:
 
----
+Python Version Check:
+```bash
+python --version  # Should be 3.13+
+python -c "import sys; print(sys.version_info)"
+```
 
-## Works Well With
+Async Session Detached Error:
+- Solution: Set `expire_on_commit=False` in session config
+- Or: Use `await session.refresh(obj)` after commit
+
+pytest asyncio Mode Warning:
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+```
 
-- `moai-foundation-trust` (coverage verification, quality gates)
-- `moai-alfred-code-reviewer` (Python-specific code review)
-- `moai-alfred-debugger-pro` (Python debugging with pdb, pudb)
-- `moai-lang-sql` (SQLAlchemy integration)
-- `moai-domain-backend` (FastAPI microservices)
+Pydantic v2 Migration:
+- `parse_obj()` is now `model_validate()`
+- `parse_raw()` is now `model_validate_json()`
+- `from_orm()` requires `from_attributes=True` in ConfigDict
 
 ---
 
-## Best Practices
-
-✅ **DO**:
-- Use ruff 0.13.1 as linter + formatter (not black + pylint)
-- Specify exact Python version: `requires-python = "^3.13"`
-- Use pytest 8.4.2 for all tests
-- Enable type checking: mypy --strict
-- Run quality gate before each commit
-- Use uv for package management (10x faster)
-- Add docstrings to public APIs
-- Use f-strings (PEP 701 supports nested expressions)
-
-❌ **DON'T**:
-- Use black + pylint (deprecated, use ruff instead)
-- Use md5 hashing (removed in Python 3.13)
-- Mix pytest with unittest
-- Ignore coverage requirements (<85% fails)
-- Use old type hint syntax (use PEP 695 `class Foo[T]:`)
-- Use `asyncio.gather` without error handling (use TaskGroup instead)
+Last Updated: 2025-12-07
+Status: Active (v1.0.0)