Derive equipped item mana state and time-remaining data in inventory-service, then render a Mana panel inside the inventory window with live icon, state, mana, and countdown display.
154 lines
6.5 KiB
Markdown
154 lines
6.5 KiB
Markdown
# 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`
|
|
- History endpoint: `GET /history`
|
|
- Plugin WS endpoint: `/ws/position` (authenticated)
|
|
- Browser WS endpoint: `/ws/live` (unauthenticated)
|
|
- 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.
|