AGENTS.md

Purpose: operating guide for agentic coding assistants in this repository. Scope: setup, build/run/test commands, and code-style conventions.

Repository Snapshot

• Stack: Python 3.11, FastAPI, SQLAlchemy async, Celery, Redis, Postgres.
• API entrypoint: services/api_gateway/src/app/main.py.
• Shared modules: services/shared/.
• Worker app: services/orchestrator/src/app/.
• Local API runner: run_server.py (Windows asyncio fix included).
• Infra orchestration: docker-compose.yml.
• UI folder: webui/ (Playwright dependency present).

Instruction Overlays (Cursor/Copilot)

Checked:

• .cursorrules
• .cursor/rules/
• .github/copilot-instructions.md

Current status:

• No Cursor rules or Copilot instruction files found.
• If they appear later, treat them as high-priority repo instructions.
• Update this file when rule sources change.

Setup

Python Environment

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Notes:

• requirements.txt is UTF-16 encoded.
• Most tools handle it; convert to UTF-8 only if a tool fails.

Infrastructure Services

docker compose up --build
docker compose down

Equivalent Make targets:

make up
make down

Build and Run Commands

API Gateway

python run_server.py
uvicorn services.api_gateway.src.app.main:app --reload --host 0.0.0.0 --port 8000
make run-api

Celery Worker

celery -A services.orchestrator.src.app.celery_app.celery_app worker --loglevel=info
make run-celery

Lint, Format, and Type Checking

No committed root config for Ruff, Black, isort, Flake8, or mypy.

Agent expectations:

• Match existing style in touched files.
• Avoid broad reformat-only changes.
• Keep imports tidy and remove unused imports you introduce.
• Keep typing patterns consistent with nearby code.

Safe local sanity check:

python -m compileall services tests

Test Commands

Pytest (All / Single)

python -m pytest tests -q
python -m pytest tests/security/test_verification.py -q
python -m pytest tests/security/test_verification.py::test_generate_token -q

Script-Style Flows Used in This Repo

python tests/security/test_verification.py
python tests/security/integration_test.py
python tests/security/test_server.py
python tests/security/hosts_manager.py check

Notes:

• Some tests require API + DB + Redis running.
• Some flows depend on local hosts/domain setup.
• integration_test.py includes interactive/manual steps.

Playwright (WebUI)

Run from webui/:

npx playwright test
npx playwright test path/to/spec-file.spec.ts
npx playwright test -g "name fragment"

Code Style Guidelines

Imports

• Group imports: standard library, third-party, local modules.
• Separate groups with one blank line.
• Prefer explicit imports over wildcard imports.

Formatting

• Match existing formatting in each file.
• Keep functions focused and readable.
• Avoid non-functional whitespace churn.

Types and Schemas

• Add type hints for new/changed function signatures.
• Use str | None unions where consistent.
• Use Pydantic models for FastAPI request/response contracts.
• Use Field(...) validation for constrained inputs.

Naming Conventions

• snake_case: variables, functions, modules.
• PascalCase: classes, ORM models, Pydantic models.
• UPPER_SNAKE_CASE: constants.
• Prefer clear route handler names (create_project, list_tasks, start_scan).

Async and Database Usage

• Preserve async handlers for IO paths.
• Use get_db dependency with AsyncSession.
• Commit/refresh intentionally on write flows.
• Roll back session after integrity/database write errors.

Error Handling and Security

• Use HTTPException with explicit status codes.
• Return structured error payloads for client-facing failures.
• Do not swallow exceptions silently.
• Avoid leaking secrets/tokens in error text.
• Treat verification and scan authorization logic as security-critical.
• Preserve ownership/legal-agreement checks and blacklist logic.

Architecture and Boundaries

• API routes: services/api_gateway/src/app/routes/.
• Shared auth/config/db/models: services/shared/.
• Worker tasks: services/orchestrator/src/app/tasks.py.
• Compose services: Postgres, Redis, API, Celery worker, Flower.

Cross-service change expectations:

• Keep schema/model contracts synchronized.
• Keep diffs minimal and clearly scoped.
• Verify startup and health behavior after edits.

Agent Change Hygiene

• Do not revert unrelated local/user changes.
• Avoid renaming/moving files unless task requires it.
• Keep changes focused and atomic.
• Note assumptions when full integration testing is not possible.
• Update this file when commands/tooling conventions change.