majiayu000 Python Skills for LlamaFarm
Shared Python best practices and code review checklists for all Python components in the LlamaFarm monorepo.
Applicable Components
| Component | Path | Python | Key Dependencies |
|---|---|---|---|
| Server | server/ |
3.12+ | FastAPI, Celery, Pydantic, structlog |
| RAG | rag/ |
3.11+ | LlamaIndex, ChromaDB, Celery |
| Universal Runtime | runtimes/universal/ |
3.11+ | PyTorch, transformers, FastAPI |
| Config | config/ |
3.11+ | Pydantic, JSONSchema |
| Common | common/ |
3.10+ | HuggingFace Hub |
Quick Reference
| Topic | File | Key Points |
|---|---|---|
| Patterns | patterns.md | Dataclasses, Pydantic, comprehensions, imports |
| Async | async.md | async/await, asyncio, concurrent execution |
| Typing | typing.md | Type hints, generics, protocols, Pydantic |
| Testing | testing.md | Pytest fixtures, mocking, async tests |
| Errors | error-handling.md | Custom exceptions, logging, context managers |
| Security | security.md | Path traversal, injection, secrets, deserialization |
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:
Patterns (Medium priority)
- Modern Python syntax (3.10+ type hints)
- Dataclass vs Pydantic used appropriately
- No mutable default arguments
Async (High priority)
- No blocking calls in async functions
- Proper asyncio.Lock usage
- Cancellation handled correctly
Typing (Medium priority)
- Complete return type hints
- Generic types parameterized
- Pydantic v2 patterns
Testing (Medium priority)
- Fixtures properly scoped
- Async tests use pytest-asyncio
- Mocks cleaned up
Errors (High priority)
- Custom exceptions with context
- Structured logging with extra dict
- Proper exception chaining
Security (Critical priority)
- Path traversal prevention
- Input sanitization
- Safe deserialization
See individual topic files for detailed checklists with grep patterns.