Skip to content

Latest commit

 

History

History
77 lines (56 loc) · 4.84 KB

AGENTS.md

File metadata and controls

77 lines (56 loc) · 4.84 KB

WordPress AI Client - Coding Agent Guide

Project Overview

An AI client and API for WordPress to communicate with any generative AI models of various capabilities using a uniform API. Built on top of the PHP AI Client, it provides a WordPress-native Prompt Builder, an Admin Settings Screen for credentials, automatic credential wiring, a PSR-compliant HTTP client, and a client-side JavaScript API.

Commands & Scripts

  • composer lint: Lints the PHP code (PHPCodeSniffer and PHPStan).
  • composer phpcs: Runs PHPCodeSniffer on the PHP code.
  • composer phpstan: Runs PHPStan on the PHP code.
  • npm run build: Builds the JavaScript assets.
  • npm run format-js: Formats the JavaScript code using Prettier.
  • npm run lint-js: Lints the JavaScript code.
  • npm run lint-php: Lints the PHP code using Composer inside the wp-env environment.
  • npm run test-php: Runs PHPUnit tests with single site config inside the wp-env environment.
  • npm run test-php-multisite: Runs PHPUnit tests with Multisite config inside the wp-env environment.

Note: In order to follow the WordPress code style in JavaScript, the project uses a WordPress-specific fork of Prettier (wp-prettier) under the hood.

Coding Standards & Compatibility Constraints

This project adheres to the WordPress Coding Standards with specific exceptions for PSR-4 autoloading (file names match class names). More details about coding and documentation standards are outlined in the CONTRIBUTING.md file. Any agent working on this project MUST read and follow the guidelines in that file before starting any work.

  • PHP Version: Code must be compatible with PHP 7.4.
  • Code Style: All code (PHP and JavaScript) must be compliant with the WordPress Coding Standards.
  • Type Hints: Use explicit type hints for parameters, return values, and properties where supported by PHP 7.4.

Core Principles

  • Uniform API: Provide a consistent interface for interacting with various AI providers.
  • WordPress Native: Integrate deeply with WordPress APIs (Abilities API, HTTP API, Settings API).
  • Security: Restrict access to powerful features (like arbitrary prompt generation via REST API) using capabilities (prompt_ai).
  • Standards Compliance: Adhere to PSR standards where applicable (e.g., HTTP Client) while maintaining WordPress compatibility.

Project Architecture Overview

The project consists of three main layers:

  1. PHP SDK (includes/): The core logic, built on wordpress/php-ai-client. It handles prompt building, request execution, and response parsing. It also manages API credentials and integrates with WordPress core.
  2. REST API (includes/REST_API/): Exposes the AI capabilities to the client-side. It handles authentication and validation.
  3. JavaScript SDK (src/): A client-side library that mirrors the PHP Prompt Builder interface, communicating with the backend via the REST API.

Directory Structure

  • build/: Compiled JavaScript and CSS assets.
  • includes/: Main PHP source files (PSR-4 autoloaded).
    • API_Credentials/: Manages API keys and settings.
    • Builders/: Prompt builder implementations.
    • Capabilities/: Capability management.
    • HTTP/: HTTP client integrations.
    • REST_API/: REST API controllers.
  • src/: Source TypeScript/JavaScript files.
  • tests/: PHPUnit tests.
    • phpunit/: Test suite configuration and test files.
  • vendor/: Composer dependencies.

Git Repo

The main branch for this project is called "trunk".

Agent Guidelines

  • DO: Read CONTRIBUTING.md before writing any code.
  • DO: Ensure all PHP code is compatible with PHP 7.4.
  • DO: Use wp_enqueue_script( 'wp-ai-client' ) to load the JS SDK.
  • DO: Add unit tests for new PHP functionality in tests/phpunit/tests/.
  • DO: Run npm run lint-php and npm run test-php before submitting changes.
  • DON'T: Use PHP 8.0+ features (e.g., constructor property promotion, union types, match expressions, enums).
  • DON'T: Create new top-level directories without a strong reason.
  • DON'T: Hardcode API credentials.

Common Pitfalls

  • Ignoring the Fluent API: While the traditional API is available, the fluent API is the preferred way for implementers to use the client. Avoid writing complex, nested method calls when the fluent API provides a cleaner alternative.
  • Duplicating Interface Documentation: Manually writing PHPDoc descriptions for methods that implement an interface is a common pitfall. The {@inheritDoc} tag should be used instead to inherit the documentation from the interface.
  • Missing Capability Checks in REST: Exposing AI generation endpoints without proper capability checks. Always ensure prompt_ai capability is checked for privileged operations.