senior-python-engineering

Skill: Senior Python Engineering

Purpose

Set the standard for writing Python in this repository: small, typed, explicit, testable modules with side effects pushed to the edges — code that future agents can safely modify without fear.

When to Use This Skill

• Implementing any Python code in src/agentplatform/ (tasks 0001+).
• Designing a new module, model, or adapter.
• Deciding between dataclass vs. Pydantic, sync vs. async, or where to put a dependency.

Files to Read First

• AGENTS.md (architecture rules and planned package layout).
• docs/ARCHITECTURE.md (layer responsibilities).
• .ai/skills/architecture-review.md (invariants you must not break).
• pyproject.toml (configured tools: ruff, mypy, pytest).

Core Principles

• Small modules, single responsibility. One layer concern per module; no giant files.
• Explicit typed models. Type everything; mypy runs strict.
  • Use Pydantic for data crossing a boundary that needs validation/parsing (YAML spec models, plugin/API payloads).
  • Use dataclasses (often frozen) for internal domain models that don't need runtime validation (e.g. compiled graph nodes). Choose intentionally, not at random.
• Separate domain models from transport/API models. Don't reuse a FastAPI request model as your internal domain object.
• Keep side effects at boundaries. I/O, network, time, and randomness live in adapters at the edges; core logic stays pure and testable.
• Dependency injection over hidden globals. Pass collaborators in; no module-level mutable singletons, and never mutable global request state.
• Adapters via explicit interfaces. External integrations (LLM, MCP, DB, plugins) sit behind ABCs so implementations are navigable and can be faked in tests. Reach for typing.Protocol where the typing is structural rather than nominal: runtime_checkable Protocols for optional capabilities detected with isinstance (see agent_engine/engine/), plain Protocols for the minimal shape a function needs of its argument.
• Clear async boundaries. Don't mix blocking I/O into async paths; keep async at the edges and be consistent within a module.
• Typed, actionable errors. Define specific exception types; messages name the offending thing (key, id, variable). Avoid bare except.
• Small, intent-named functions. A function name should describe what it does; if you need "and" in the name, split it.
• Avoid clever code and premature abstraction. Write the simple version; abstract only when a second real case appears.