AGENTS.md

Codex Guidance

Conventions

• Keep existing FastAPI endpoints and React flows stable; add new functionality behind flags/config toggles.
• Prefer small, composable helpers in backend/app/services/ for pipeline changes.
• Do not commit secrets (.env), caches (knowledge_files/), build artifacts (frontend/dist/), or logs (metrics_logs/).

Metrics

• New chatbot metrics live in backend/app/services/scrape_pipeline.py.
• Add supporting helpers in backend/app/services/metrics_logger.py.
• Guard all metrics code with the ENABLE_METRICS_LOGGING environment variable (default false).
• Surface new metrics via API stats objects without breaking existing fields.

Commands to run after changes

• Backend: pip install -r requirements.txt (if deps change), then pytest.
• Frontend: cd frontend && npm install (if deps change), then npm run build.

Feature flags

• All new features/metrics must be optional and off by default:
  • ENABLE_METRICS_LOGGING controls metrics/telemetry.
  • Wrap new logic in if os.getenv("ENABLE_METRICS_LOGGING", "false").lower() == "true": ....

Testing expectations

• Add/maintain unit tests for new logic; prefer fast, isolated tests with mocks over network calls.
• If modifying the pipeline, ensure cache behavior and new stats remain backward compatible.