diff --git a/src/dashboard/models/calm.py b/src/dashboard/models/calm.py index 403235cd..28fbf09e 100644 --- a/src/dashboard/models/calm.py +++ b/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) diff --git a/src/dashboard/routes/discord.py b/src/dashboard/routes/discord.py index 3f9bd515..d34165c0 100644 --- a/src/dashboard/routes/discord.py +++ b/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 diff --git a/src/dashboard/routes/telegram.py b/src/dashboard/routes/telegram.py index 303d5cf0..9cd186c2 100644 --- a/src/dashboard/routes/telegram.py +++ b/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 diff --git a/src/dashboard/routes/work_orders.py b/src/dashboard/routes/work_orders.py index 5d489f43..479e33a7 100644 --- a/src/dashboard/routes/work_orders.py +++ b/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 diff --git a/src/dashboard/services/scorecard_service.py b/src/dashboard/services/scorecard_service.py index 60a9da27..323daa6b 100644 --- a/src/dashboard/services/scorecard_service.py +++ b/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" diff --git a/src/infrastructure/chat_store.py b/src/infrastructure/chat_store.py index 72037e5f..80c38cbe 100644 --- a/src/infrastructure/chat_store.py +++ b/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 diff --git a/src/infrastructure/notifications/push.py b/src/infrastructure/notifications/push.py index 0aa038f6..925c74ae 100644 --- a/src/infrastructure/notifications/push.py +++ b/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 diff --git a/src/integrations/voice/nlu.py b/src/integrations/voice/nlu.py index 5bf55cc0..493577d6 100644 --- a/src/integrations/voice/nlu.py +++ b/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 diff --git a/src/lightning/ledger.py b/src/lightning/ledger.py index c43c7961..bcfd5788 100644 --- a/src/lightning/ledger.py +++ b/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" diff --git a/src/timmy/approvals.py b/src/timmy/approvals.py index 8cca50ff..5a30c132 100644 --- a/src/timmy/approvals.py +++ b/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 diff --git a/src/timmy/briefing.py b/src/timmy/briefing.py index 9c49295f..1f284429 100644 --- a/src/timmy/briefing.py +++ b/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) diff --git a/src/timmy/research_tools.py b/src/timmy/research_tools.py index 7818d27f..70a237cb 100644 --- a/src/timmy/research_tools.py +++ b/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 diff --git a/src/timmy_serve/app.py b/src/timmy_serve/app.py index 8b0013af..f4824cc7 100644 --- a/src/timmy_serve/app.py +++ b/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