Python Workflow Type Safety

Enforce strict type safety, Pydantic models, and layered architecture patterns in Python projects using uv for dependency management.

Instructions

Type Checking

Always run type checking after edits:

```bash

ty check --exclude resources

```

Ensure type checking passes before considering any edit complete.

Dependency Management

Use `uv` for ALL dependency operations. NEVER use `pip` or `python` directly:

```bash

uv run <script> # Run scripts

uv sync # Sync dependencies

uv add <package> # Add packages

```

Type Safety Rules

1. **Use strict type annotations** on all functions and class methods

2. **Avoid `Any` and `Dict`** - use specific types or Pydantic models instead

3. **NEVER use `hasattr` or `getattr`** - use explicit type checking

4. **Prefer Pydantic models** for data structures whenever possible

Code Patterns

#### Good Examples

```python

Good: Specific type with Pydantic

from pydantic import BaseModel

class NodeConfig(BaseModel):

node_id: str

node_type: str

title: str | None = None

def process_node(config: NodeConfig) -> bool:

return config.node_id.startswith("node_")

```

#### Bad Examples

```python

Bad: Using Any and getattr

from typing import Any

def process_node(config: Any) -> bool:

if hasattr(config, 'node_id'):

return getattr(config, 'node_id').startswith("node_")

return False

```

Layered Architecture Pattern

When working with multi-layer architectures:

1. **Layer 1: Data Models** - Pure Pydantic models, no business logic

2. **Layer 2: File Operations** - I/O operations, basic CRUD, validation

3. **Layer 3: Business Logic** - Core operations, AI integration, complex workflows

4. **Layer 4: Interface** - CLI, API, or UI layer

Each layer should:

Configuration Management

Use YAML configuration with local overrides:

```yaml

config.yml (versioned)

api:

key: ${ENV_VAR}

local.config.yml (gitignored)

api:

key: actual_secret_key

```

Validation Workflow

Before committing changes:

1. Run type checker: `ty check --exclude resources`

2. Run tests: `uv run pytest`

3. Verify no `Any`, `Dict`, `hasattr`, or `getattr` in new code

4. Ensure all functions have type annotations

Usage Examples

Running Scripts

```bash

Run with type checking first

ty check --exclude resources && uv run python script.py

Interactive mode

uv run python cli.py

With arguments

uv run python cli.py resources/workflow.yml

```

Adding Dependencies

```bash

Add typed library

uv add pydantic

Sync after changes

uv sync

```

Important Notes