name: python-skills
description: Shared Python best practices for LlamaFarm. Covers patterns, async, typing, testing, error handling, and security.
allowed-tools: Read, Grep, Glob
user-invocable: false

Python Skills for LlamaFarm

Shared Python best practices and code review checklists for all Python components in the LlamaFarm monorepo.

Applicable Components

Quick Reference

Code Style

LlamaFarm uses ruff with shared configuration in ruff.toml:

line-length = 88
target-version = "py311"
select = ["E", "F", "I", "B", "UP", "SIM"]

Key rules:
- E, F: Core pyflakes and pycodestyle
- I: Import sorting (isort)
- B: Bugbear (common pitfalls)
- UP: Upgrade syntax to modern Python
- SIM: Simplify code patterns

Architecture Patterns

Settings with pydantic-settings

from pydantic_settings import BaseSettings

class Settings(BaseSettings, env_file=".env"):
    LOG_LEVEL: str = "INFO"
    HOST: str = "0.0.0.0"
    PORT: int = 8000

settings = Settings()  # Singleton at module level

Structured Logging with structlog

from core.logging import FastAPIStructLogger  # Server
from core.logging import RAGStructLogger      # RAG
from core.logging import UniversalRuntimeLogger  # Runtime

logger = FastAPIStructLogger(__name__)
logger.info("Operation completed", extra={"count": 10, "duration_ms": 150})

Abstract Base Classes for Extensibility

from abc import ABC, abstractmethod

class Component(ABC):
    def __init__(self, name: str, config: dict[str, Any] | None = None):
        self.name = name or self.__class__.__name__
        self.config = config or {}

    @abstractmethod
    def process(self, documents: list[Document]) -> ProcessingResult:
        pass

Dataclasses for Internal Data

from dataclasses import dataclass, field

@dataclass
class Document:
    content: str
    metadata: dict[str, Any] = field(default_factory=dict)
    id: str = field(default_factory=lambda: str(uuid.uuid4()))

Pydantic Models for API Boundaries

from pydantic import BaseModel, Field, ConfigDict

class EmbeddingRequest(BaseModel):
    model: str
    input: str | list[str]
    encoding_format: Literal["float", "base64"] | None = "float"

    model_config = ConfigDict(str_strip_whitespace=True)

Directory Structure

Each Python component follows this structure:

component/
├── pyproject.toml     # UV-managed dependencies
├── core/              # Core functionality
│   ├── __init__.py
│   ├── settings.py    # Pydantic Settings
│   └── logging.py     # structlog setup
├── services/          # Business logic (server)
├── models/            # ML models (runtime)
├── tasks/             # Celery tasks (rag)
├── utils/             # Utility functions
└── tests/
    ├── conftest.py    # Shared fixtures
    └── test_*.py

Review Checklist Summary

When reviewing Python code in LlamaFarm:

1. Patterns (Medium priority)
2. Modern Python syntax (3.10+ type hints)
3. Dataclass vs Pydantic used appropriately

4. No mutable default arguments

5. Async (High priority)

6. No blocking calls in async functions
7. Proper asyncio.Lock usage

8. Cancellation handled correctly

9. Typing (Medium priority)

10. Complete return type hints
11. Generic types parameterized

12. Pydantic v2 patterns

13. Testing (Medium priority)

14. Fixtures properly scoped
15. Async tests use pytest-asyncio

16. Mocks cleaned up

17. Errors (High priority)

18. Custom exceptions with context
19. Structured logging with extra dict

20. Proper exception chaining

21. Security (Critical priority)

22. Path traversal prevention
23. Input sanitization
24. Safe deserialization

See individual topic files for detailed checklists with grep patterns.