Skip to content

AGENTS.md

Latest commit

 

History

History
40 lines (34 loc) · 2.2 KB

AGENTS.md

File metadata and controls

40 lines (34 loc) · 2.2 KB

Repository Guidelines

Project Structure & Module Organization

  • Source: cobalt_forward/
    • application/ (startup, DI container)
    • core/ (domain models, events, services, interfaces)
    • infrastructure/ (config, clients, logging, SSH, upload)
    • presentation/api/ (FastAPI app, routers, middleware)
    • plugins/ (plugin base + manager)
  • Tests: tests/test_*.py
  • Config: config.yaml (default), config.json, .env.example
  • Entrypoints: cobalt_forward/main.py (CLI), run.py, start.sh

Build, Test, and Development Commands

  • Install (uv): uv sync • Run: uv run cobalt-forward start -c config.yaml
  • Dev server: uv run cobalt-forward dev --reload -p 8000
  • Tests: uv run pytest -q (coverage enabled via --cov=cobalt_forward)
  • Lint/format: uv run ruff check . • uv run black . • uv run isort . • uv run mypy cobalt_forward
  • Without uv: python -m cobalt_forward.main start -c config.yaml and pytest -q

Coding Style & Naming Conventions

  • Python 3.10+. Format with Black (88 cols); imports via isort (black profile).
  • Static typing required; project runs mypy in strict mode.
  • Naming: modules/functions snake_case, classes PascalCase, constants UPPER_SNAKE_CASE.
  • Keep modules focused; prefer composition over inheritance. Avoid global state.

Testing Guidelines

  • Frameworks: pytest, pytest-asyncio. Place tests under tests/ named test_*.py.
  • Add unit tests for new logic and integration tests for routers/services when applicable.
  • Ensure coverage does not regress; keep --cov=cobalt_forward passing locally.

Commit & Pull Request Guidelines

  • Use Conventional Commits: feat:, fix:, refactor:, test:, docs:, chore:; include scope when helpful, e.g., feat(core): add event bus.
  • Write imperative, concise subjects; body explains motivation and behavior.
  • PRs include: clear description, linked issues, test evidence (output or coverage), and notes on config changes.

Security & Configuration Tips

  • Do not commit secrets. Use .env and reference via config loaders.
  • Prefer config.yaml; validate via uv run cobalt-forward validate_config config.yaml.
  • Logs write to logs/. Review levels in infrastructure/logging/setup.py.