MosswartOverlord/AGENTS.md

AGENTS.md

Guidance for coding agents working in MosswartOverlord (Dereth Tracker).

Read shared integration rules first: ../AGENTS.md.

Scope and priorities

• This repo is a Python/FastAPI multi-service project with Docker-first workflows.
• Primary services: main.py (telemetry API + WS + static frontend), inventory-service/main.py (inventory + suitbuilder), discord-rare-monitor/discord_rare_monitor.py (Discord bot).
• Favor minimal, targeted changes over broad refactors.

Local rule sources

• Additional project guidance exists in CLAUDE.md; follow it when relevant.
• Cursor/Copilot rule discovery is documented centrally in ../AGENTS.md.

Environment and dependencies

• Python versions in Dockerfiles: 3.12 (main + bot), 3.11 (inventory-service).
• Databases: PostgreSQL/TimescaleDB for telemetry; PostgreSQL for inventory.
• Core Python deps: FastAPI, Uvicorn, SQLAlchemy, databases, asyncpg, httpx.
• Bot deps: discord.py, websockets.

Build and run commands

Docker (recommended)

• Start all services: docker compose up -d
• Rebuild app service after source changes (no cache): docker compose build --no-cache dereth-tracker
• Redeploy app service: docker compose up -d dereth-tracker
• Rebuild inventory service: docker compose build --no-cache inventory-service
• Rebuild Discord bot: docker compose build --no-cache discord-rare-monitor
• Follow logs (app): docker logs mosswartoverlord-dereth-tracker-1
• Follow logs (telemetry DB): docker logs dereth-db

Local (without Docker)

• Main API dev run: uvicorn main:app --reload --host 0.0.0.0 --port 8765
• Inventory service dev run: uvicorn main:app --reload --host 0.0.0.0 --port 8000 (from inventory-service/)
• Data generator: python generate_data.py
• Discord bot run: python discord-rare-monitor/discord_rare_monitor.py

Lint/format commands

• Repo formatter target: make reformat
• What it does: runs black *.py in repo root.
• Prefer formatting changed files before finalizing edits.
• No repo-level Ruff/Flake8/isort/mypy config files were found.

Test commands

• There is no conventional tests/ suite configured in this repo.
• Existing executable test script: python discord-rare-monitor/test_websocket.py
• This script validates rare classification and WebSocket handling.
• It expects a reachable server at ws://localhost:8765/ws/position for connection checks.

Single-test guidance (important)

• For the current codebase, a single targeted test means running the script above.
• Practical single-test command:
• python discord-rare-monitor/test_websocket.py
• The script is not pytest-based; use stdout/log output for pass/fail interpretation.
• If pytest is introduced later, preferred pattern is:
• python -m pytest path/to/test_file.py::test_name -q

Service-specific quick checks

• Main health endpoint: GET /debug
• Live data endpoint: GET /live
• Trails endpoint: GET /trails
• Plugin WS endpoint: /ws/position (authenticated via X-Plugin-Secret)
• Browser WS endpoint: /ws/live (session-cookie authenticated; internal Docker-network clients trusted by IP)
• Inventory service endpoint family: /search/*, /inventory/*, /suitbuilder/*

Repo-specific architecture notes

• Telemetry DB schema is in db_async.py (SQLAlchemy Core tables).
• Inventory DB schema is in inventory-service/database.py (SQLAlchemy ORM models).
• Static frontend is served from static/ by FastAPI.
• Keep inventory-service enum loading paths intact (comprehensive_enum_database_v2.json, fallback JSON).

Code style conventions observed

Imports and module structure

• Use standard-library imports first, then third-party, then local imports.
• Keep import groups separated by one blank line.
• Prefer explicit imports over wildcard imports.
• In existing files, typing imports are common (Dict, List, Optional, Any).
• Avoid introducing circular imports; shared helpers belong in dedicated modules.

Formatting and layout

• Follow Black-compatible formatting (88-char style assumptions are acceptable).
• Use 4 spaces, no tabs.
• Keep functions focused; extract helpers for repeated logic.
• Maintain existing docstring style (triple double quotes for module/function docs).
• Preserve readable logging statements with context-rich messages.

Types and data models

• Add type hints for new functions and non-trivial variables.
• Use Pydantic models for request/response payload validation in FastAPI layers.
• Keep DB schema changes explicit in SQLAlchemy model/table definitions.
• Prefer precise types over Any when practical.
• For optional values, use Optional[T] or T | None consistently within a file.

Naming conventions

• Functions/variables: snake_case.
• Classes: PascalCase.
• Constants/env names: UPPER_SNAKE_CASE.
• Endpoint handlers should be action-oriented and descriptive.
• Database table/column names should remain stable unless migration is planned.

Error handling and resilience

• Prefer explicit try/except around external I/O boundaries:
• DB calls, WebSocket send/recv, HTTP calls, file I/O, JSON parsing.
• Log actionable errors with enough context to debug production issues.
• Fail gracefully for transient network/database errors (retry where already patterned).
• Do not swallow exceptions silently; at minimum log at warning or error.
• Keep user-facing APIs predictable (consistent JSON error responses).

Logging conventions

• Use module-level logger: logger = logging.getLogger(__name__).
• Respect LOG_LEVEL environment variable patterns already present.
• Prefer structured, concise messages; avoid noisy logs in hot loops.
• Keep emoji-heavy logging style only where already established in file context.

Database and migrations guidance

• Be careful with uniqueness/index assumptions (especially portal coordinate rounding logic).
• Validate any schema-affecting changes against Dockerized Postgres services.

Frontend/static guidance

• Preserve existing API base path assumptions used by frontend scripts.
• Reverse-proxy prefix behavior (/api) is documented in ../AGENTS.md; keep frontend/backend paths aligned.

Secrets and configuration

• Never hardcode secrets/tokens in commits.
• Use env vars (SHARED_SECRET, POSTGRES_PASSWORD, bot token variables).
• Keep defaults safe for local dev, not production credentials.

Change management for agents

• Keep patches small and scoped to the requested task.
• Update docs when behavior, endpoints, or run commands change.
• If adding new tooling (pytest/ruff/mypy), include config and command docs in this file.
• For cross-repo payload changes, follow ../AGENTS.md checklist and update both sides.