fetch_ml/AGENTS.md

AGENTS.md - Coding Agent Guidelines

This document provides essential information for agentic coding assistants working with the FetchML codebase.

Build Commands

Go Components

# Build all Go components
make build

# Build for development (faster compilation)
make dev

# Build for production (optimized)
make prod

# Cross-platform build for Linux/macOS/Windows
make cross-platform

Zig CLI

# Build CLI with release-small optimization
cd cli && make all

# Build for development
cd cli && make dev

# Build for production
cd cli && make prod

# Alternative using zig build system
cd cli && zig build

Test Commands

Running Tests

# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests only
make test-integration

# Run end-to-end tests only
make test-e2e

# Run with coverage report
make test-coverage

# Run a single test
go test -v ./path/to/package -run TestName

# Run tests with race detector
go test -race ./path/to/package/...

Performance Testing

# Run performance benchmarks
make benchmark

# Run load testing suite
make load-test

# Run chaos engineering tests
make chaos-test

# Run complete technical excellence suite
make tech-excellence

Lint Commands

# Run all linters and formatters
make lint

# Run Go linters
golangci-lint run

# Run Go formatters
gofmt -w ./cmd ./internal ./tests

# Run Go vet
go vet ./...

# Format Zig code
cd cli && zig fmt .

# Validate YAML configs against schema
make configlint
make worker-configlint

Code Style Guidelines

Go Code Style

1. Formatting:

   • Use gofmt for formatting
   • Line length: 100 characters (configured in .golangci.yml)
   • Use goimports for import organization

2. Naming Conventions:

   • Use camelCase for variables and functions
   • Use PascalCase for exported identifiers
   • Use clear, descriptive names
   • Acronyms should be all caps (e.g., HTTP, URL)

3. Imports:

   • Group imports in order: standard library, third-party, internal
   • Use meaningful import aliases when needed
   • Remove unused imports

4. Error Handling:

   • Always handle errors explicitly
   • Use errors.Is and errors.As for error checking
   • Wrap errors with context using fmt.Errorf("context: %w", err)

5. Documentation:

   • All exported functions, types, and variables must have doc comments
   • Comments should explain "why" not just "what"
   • Use godoc formatting conventions

Zig Code Style

1. Formatting:

   • Use built-in Zig formatter (zig fmt)
   • Consistent indentation with 4 spaces

2. Naming Conventions:

   • Use camelCase for variables and functions
   • Use PascalCase for types
   • Use snake_case for file names

3. Error Handling:

   • Use Zig's error union types (!T)
   • Handle errors with try, catch, or if expressions
   • Return errors early when appropriate

Python Code Style

1. Formatting:

   • Use Black formatter with 80 character line limit
   • Use isort for import organization (Google style)

2. Type Checking:

   • Use mypy with strict settings
   • All functions should have type annotations

3. Testing:

   • Use pytest framework
   • Follow naming conventions: test_* for functions, *_test.py for files

YAML/Configuration Style

1. Formatting:

   • Use yamllint for validation
   • Consistent indentation with 2 spaces
   • No trailing whitespace

2. Validation:

   • All configs must pass schema validation
   • Use make configlint and make worker-configlint

Development Guidelines

Testing Requirements (from .windsurf/rules/test-new-features.md)

• Every new feature MUST include corresponding tests
• Test coverage for new code should be >80%
• Include both unit tests and integration tests where applicable
• Test edge cases, error paths, and boundary conditions

Code Organization

• Clean up as you go - no orphaned files or dead code
• Remove commented-out code blocks
• Delete unused imports, functions, and variables immediately
• Consolidate duplicate code into reusable functions

Documentation Standards

• Update relevant documentation IN THE SAME COMMIT as code changes
• Documentation locations:
  • README.md: User-facing features, installation, quick start
  • CHANGELOG.md: All changes, following Keep a Changelog format
  • Code comments: Complex logic, non-obvious decisions, API contracts
  • Function/struct docs: Public APIs must have doc comments

Commit Message Convention

Use conventional commits:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• style: for formatting changes
• refactor: for code refactoring
• test: for adding/updating tests
• chore: for maintenance tasks

Project Structure

• cmd/ - Main applications
• internal/ - Internal packages
• cli/ - Zig command-line interface
• tests/ - Test files organized by type
• configs/ - Configuration files and schemas
• docs/ - Documentation
• scripts/ - Utility scripts

Dependencies

• Go 1.25+
• Zig 0.15+
• Python 3.11+ (for some tools)
• Redis (for integration tests)
• Docker/Podman (for container-based tests)

Useful Make Targets

# Development workflow
make dev-start     # Start development environment
make test          # Run all tests
make lint          # Run linters
make ci-local      # Run local CI dry-run

# Documentation
make docs          # Start documentation server
make docs-build    # Build static documentation

# Cleanup
make clean         # Remove build artifacts
make clean-docs    # Remove documentation artifacts