src/dashboard/models/calm.py

@@ -8,6 +8,7 @@ from .database import Base  # Assuming a shared Base in models/database.py
 
 
 class TaskState(StrEnum):
+    """Enumeration of possible task lifecycle states."""
     LATER = "LATER"
     NEXT = "NEXT"
     NOW = "NOW"
@@ -16,12 +17,14 @@ class TaskState(StrEnum):
 
 
 class TaskCertainty(StrEnum):
+    """Enumeration of task time-certainty levels."""
     FUZZY = "FUZZY"  # An intention without a time
     SOFT = "SOFT"  # A flexible task with a time
     HARD = "HARD"  # A fixed meeting/appointment
 
 
 class Task(Base):
+    """SQLAlchemy model representing a CALM task."""
     __tablename__ = "tasks"
 
     id = Column(Integer, primary_key=True, index=True)
@@ -52,6 +55,7 @@ class Task(Base):
 
 
 class JournalEntry(Base):
+    """SQLAlchemy model for a daily journal entry with MITs and reflections."""
     __tablename__ = "journal_entries"
 
     id = Column(Integer, primary_key=True, index=True)

src/dashboard/routes/discord.py

@@ -14,6 +14,7 @@ router = APIRouter(prefix="/discord", tags=["discord"])
 
 
 class TokenPayload(BaseModel):
+    """Request payload containing a Discord bot token."""
     token: str
 
 

src/dashboard/routes/telegram.py

@@ -7,6 +7,7 @@ router = APIRouter(prefix="/telegram", tags=["telegram"])
 
 
 class TokenPayload(BaseModel):
+    """Request payload containing a Telegram bot token."""
     token: str
 
 

src/dashboard/routes/work_orders.py

@@ -51,6 +51,7 @@ def _get_db() -> Generator[sqlite3.Connection, None, None]:
 
 
 class _EnumLike:
+    """Lightweight enum-like wrapper for string values used in templates."""
     def __init__(self, v: str):
         self.value = v
 

src/dashboard/services/scorecard_service.py

@@ -23,6 +23,7 @@ TRACKED_AGENTS = frozenset({"hermes", "kimi", "manus", "claude", "gemini"})
 
 
 class PeriodType(StrEnum):
+    """Scorecard reporting period type."""
     daily = "daily"
     weekly = "weekly"
 

src/infrastructure/chat_store.py

@@ -24,6 +24,7 @@ MAX_MESSAGES: int = 500
 
 @dataclass
 class Message:
+    """A single chat message with role, content, timestamp, and source."""
     role: str  # "user" | "agent" | "error"
     content: str
     timestamp: str

src/infrastructure/notifications/push.py

@@ -21,6 +21,7 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class Notification:
+    """A push notification with title, message, category, and read status."""
     id: int
     title: str
     message: str

src/integrations/voice/nlu.py

@@ -24,6 +24,7 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class Intent:
+    """A classified user intent with confidence score and extracted entities."""
     name: str
     confidence: float  # 0.0 to 1.0
     entities: dict

src/lightning/ledger.py

@@ -17,11 +17,13 @@ logger = logging.getLogger(__name__)
 
 
 class TxType(StrEnum):
+    """Lightning transaction direction type."""
     incoming = "incoming"
     outgoing = "outgoing"
 
 
 class TxStatus(StrEnum):
+    """Lightning transaction settlement status."""
     pending = "pending"
     settled = "settled"
     failed = "failed"

src/timmy/approvals.py

@@ -36,6 +36,7 @@ _EXPIRY_DAYS = 7
 
 @dataclass
 class ApprovalItem:
+    """A proposed autonomous action requiring owner approval."""
     id: str
     title: str
     description: str

src/timmy/briefing.py

@@ -46,6 +46,7 @@ class ApprovalItem:
 
 @dataclass
 class Briefing:
+    """A generated morning briefing summarizing recent activity and pending approvals."""
     generated_at: datetime
     summary: str  # 150-300 words
     approval_items: list[ApprovalItem] = field(default_factory=list)

src/timmy/research_tools.py

@@ -32,8 +32,10 @@ def get_llm_client() -> Any:
     # a client for an LLM service like OpenAI, Anthropic, or a local
     # model.
     class MockLLMClient:
+        """Stub LLM client for testing without a real language model."""
         async def completion(self, prompt: str, max_tokens: int) -> Any:
             class MockCompletion:
+                """Stub completion response returned by MockLLMClient."""
                 def __init__(self, text: str) -> None:
                     self.text = text
 

src/timmy_serve/app.py

@@ -25,15 +25,18 @@ logger = logging.getLogger(__name__)
 
 
 class ChatRequest(BaseModel):
+    """Incoming chat request payload for the Timmy Serve API."""
     message: str
     stream: bool = False
 
 
 class ChatResponse(BaseModel):
+    """Chat response payload returned by the Timmy Serve API."""
     response: str
 
 
 class StatusResponse(BaseModel):
+    """Service status response with backend information."""
     status: str
     backend: str