Repository Guidelines

Project Structure & Module Organization

FullMooncGPT hosts the orchestration code for conversational agents. Place runtime modules in src/fullmooncgpt/, grouped by feature folders such as agents/, pipelines/, and integrations/. Shared helpers belong in src/fullmooncgpt/common/ so they can be reused without circular dependencies. Prompt templates, YAML configs, and sample payloads live in assets/, with a short README.md per subsection describing expected inputs and outputs. Tests sit in tests/, mirroring the module layout, and notebooks or exploratory scripts go under research/ so they never ship with the package.

Build, Test, and Development Commands

python -m pip install -r requirements.txt installs the runtime stack; add dev-only tooling to requirements-dev.txt.
python -m pip install -e .[dev] enables editable development once pyproject.toml is in place.
python -m fullmooncgpt.cli --help exercises the primary entry point; add new subcommands under src/fullmooncgpt/cli/.
python -m pytest runs the entire suite; pass -k to focus on a subset during iteration.
ruff format && ruff check enforce formatting and linting; run before every commit to match CI.

Coding Style & Naming Conventions

Target Python 3.11+, annotate public functions, and rely on dataclasses or pydantic models for structured payloads. Follow snake_case for modules and functions, PascalCase for classes, and keep module names short but descriptive. Stick to 4-space indentation and keep functions focused on a single responsibility. Store configuration in .env files loaded through pydantic-settings rather than hard-coding credentials.

Testing Guidelines

Use pytest and hypothesis for property-based coverage. Name files test_<module>.py and isolate test data under tests/fixtures/. Aim for ≥85% statement coverage; capture notable gaps in the PR description. Mark slow or external-integration tests with @pytest.mark.slow so CI can opt in.

Commit & Pull Request Guidelines

Adopt Conventional Commits (for example, feat: planner adds multi-hop support) to keep changelog generation simple. Keep PRs scoped; include a checklist covering tests run, documentation updates, and backward compatibility notes. Link related issues with Closes #ID and attach logs or screenshots for UI-facing adjustments. Request at least one maintainer review and avoid force pushes after review without coordination.

2.4 KiB Raw Permalink Blame History