agent-lab/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This repository is a Python Agent Lab for debugging chat and event agents. The source package lives under src/agent_lab/:

• domain/: message and event models shared across the app.
• application/: runtime orchestration, request/response contracts, and EventAgent tool handling.
• infrastructure/: OpenAI Chat Completions compatible streaming client and parser integration.
• presentation/: FastAPI routes, WebSocket endpoint, and static debug UI under presentation/static/.
• settings.py: pydantic-settings configuration.

Tests live in tests/, planning docs in docs/plans/, and the manual WebSocket smoke helper in scripts/ws_smoke.py.

Build, Test, and Development Commands

• uv sync: install runtime and dev dependencies from pyproject.toml and uv.lock.
• uv run pytest: run the full test suite.
• uv run uvicorn agent_lab.main:app --reload: start the FastAPI debug console locally.
• uv run python scripts/ws_smoke.py --help: inspect the WebSocket smoke-test CLI.
• uv run python -c "from agent_lab.main import app; print(app.title)": verify app import wiring.

Coding Style & Naming Conventions

Use Python 3.11+ with type hints on public boundaries. Keep DDD layers separate: domain types should not depend on FastAPI or HTTP clients, application code should coordinate use cases, and infrastructure should own provider-specific I/O. Prefer small dataclasses or Pydantic models for exchanged data. Use snake_case for modules, functions, fields, and environment variables.

Testing Guidelines

Use pytest and pytest-asyncio. Add focused tests beside the behavior being changed, using names like test_openai_stream_parser.py or test_websocket_api.py. Runtime and WebSocket tests should use mocked clients unless a task explicitly requires a live LLM smoke.

Configuration & Runtime Conventions

Configuration comes from Settings in src/agent_lab/settings.py with the AGENT_LAB_ prefix and optional local .env. Do not commit secrets. The app exposes GET /health, GET /, and WebSocket /ws/debug; keep WebSocket payloads aligned with application/contracts.py.

Commit & Pull Request Guidelines

Keep commits scoped to one todo or behavior change. PRs should summarize user-visible behavior, list verification commands, mention config changes, and include screenshots only when UI layout changes.