fan-manager AGENTS.md

AGENTS.md

Claude Code loads this file via CLAUDE.md (@AGENTS.md import) — the two stay in sync. Edit this file, not CLAUDE.md.

Tech Stack & Architecture

• Language/Version: Python 3.11+
• Core Libraries: agent-utilities, fastmcp (via agent-utilities[mcp]), pydantic-ai
• Domain: Dell PowerEdge / IPMI 2.0 control via ipmitool + lm-sensors. Thermal (fan/temperature) runs local with no creds; the IPMI/BMC wrapper (CONCEPT:FM-OS.governance.power-chassis..008: power, sensors, SEL, SoL, BMC LAN/user config, raw) runs in-band (local /dev/ipmi0) or out-of-band over LAN (-I lanplus -H -U -P, creds from OpenBao apps/idrac).
• Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution, action-routed MCP tools.

Architecture & Deliberate Simplicity

Fan Manager is a small local tool, so it deliberately avoids a full domain/adapter/port hexagonal split — that would be over-engineering for a two-concept package. The design makes exactly the highest-value seam instead:

• Adapter seam (DI): CommandRunner (a Protocol in fan_manager.fan_manager) abstracts the sensors/ipmitool shell-out; SubprocessCommandRunner is the production implementation. Tests inject a fake runner rather than monkeypatching subprocess globally.
• Service layer (DI): fan_manager/services/FanControlService composes the injected CommandRunner + runtime config and exposes the temperature (CONCEPT:FM-OS.governance.service-reads-temperature-through) and fan-control (CONCEPT:FM-OS.governance.service-writes-fan-level) operations. The Api facade composes this service.
• Model layer: fan_manager/models.py holds the Pydantic envelopes.

Anything beyond this (separate domain/, ports/, adapters/ packages) is intentionally not added — it would add indirection without value at this size.

Architecture Diagram

graph TD
    User([User/A2A]) --> Agent[Pydantic AI Agent]
    Agent --> MCP[MCP Server / FastMCP]
    MCP --> Temp[temperature tool — CONCEPT:FM-OS.governance.service-reads-temperature-through]
    MCP --> Fan[fan-control tool — CONCEPT:FM-OS.governance.service-writes-fan-level]
    MCP --> Ipmi[ipmi tools — CONCEPT:FM-OS.governance.power-chassis..008]
    Temp --> Service[FanControlService - DI]
    Fan --> Service
    Service --> Runner[CommandRunner adapter]
    Ipmi --> Runner
    Runner --> Sensors([lm-sensors])
    Runner --> IPMI([BMC via ipmitool: in-band /dev/ipmi0 or lanplus])