Skip to content

CLAUDE.md

Latest commit

 

History

History
155 lines (121 loc) · 5.76 KB

CLAUDE.md

File metadata and controls

155 lines (121 loc) · 5.76 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Symfony AI monorepo containing multiple components and bundles that integrate AI capabilities into PHP applications. The project is organized as a collection of independent packages under the src/ directory, each with their own composer.json, tests, and dependencies.

Architecture

Core Components

  • Platform (src/platform/): Unified interface to AI platforms (OpenAI, Anthropic, Azure, Gemini, VertexAI, etc.)
  • Agent (src/agent/): Framework for building AI agents that interact with users and perform tasks
  • Chat (src/chat/): Chat interface components for building conversational AI applications
  • Store (src/store/): Data storage abstraction with indexing and retrieval for vector databases
  • Mate (src/mate/): AI-powered coding assistant for PHP development

Bridges

Each core component has bridges in src/<component>/src/Bridge/ that provide integrations with specific third-party services. Bridges are dedicated Composer packages with their own dependencies and can be installed independently.

Integration Bundles

  • AI Bundle (src/ai-bundle/): Symfony integration for Platform, Store, and Agent components
  • MCP Bundle (src/mcp-bundle/): Symfony integration for official MCP SDK

Supporting Directories

  • Examples (examples/): Standalone examples demonstrating component usage across different AI platforms
  • Demo (demo/): Full Symfony web application showcasing components working together
  • Fixtures (fixtures/): Shared test fixtures for multi-modal testing (images, audio, PDFs)

Development Commands

Testing

Each component has its own test suite. Run tests for specific components:

# Platform component
cd src/platform && vendor/bin/phpunit

# Agent component
cd src/agent && vendor/bin/phpunit

# AI Bundle
cd src/ai-bundle && vendor/bin/phpunit

# Demo application
cd demo && vendor/bin/phpunit

Code Quality

The project uses PHP CS Fixer with Symfony coding standards. Always run from the repository root:

# Fix code style issues
vendor/bin/php-cs-fixer fix

# Fix specific directories
vendor/bin/php-cs-fixer fix src/platform/

Static analysis with PHPStan (component-specific):

cd src/platform && vendor/bin/phpstan analyse

Documentation Validation

After adding or changing any RST files in docs/, always run the doctor-rst validator from the repository root:

./doctor-rst

This uses Docker (oskarstark/doctor-rst) to validate RST documentation files and catch formatting issues.

Development Linking

Use the ./link script to symlink local development versions:

# Link components to external project
./link /path/to/project

# Copy instead of symlink
./link --copy /path/to/project

# Rollback changes
./link --rollback /path/to/project

Running Examples

Examples are self-contained and can be run individually:

cd examples
php anthropic/chat.php
php openai/function-calling.php

Many examples require environment variables (see .env files in example directories).

Demo Application

The demo is a full Symfony application:

cd demo
composer install
symfony server:start

Component Dependencies

Components are designed to work independently but have these relationships:

  • Agent depends on Platform for AI communication
  • AI Bundle integrates Platform, Agent, and Store
  • MCP Bundle provides official MCP SDK integration
  • Store is standalone but often used with Agent for RAG applications

Testing Architecture

Each component uses:

  • PHPUnit 11+ for testing framework
  • Component-specific phpunit.xml.dist configurations
  • Shared fixtures in /fixtures for multi-modal content
  • MockHttpClient pattern preferred over response mocking

Development Notes

  • Each component in src/ is a separate Composer package with its own dependencies
  • Components follow Symfony coding standards and use @Symfony PHP CS Fixer rules
  • The monorepo structure allows independent versioning while maintaining shared development workflow
  • Do not use void return type for testcase methods
  • Always run PHP-CS-Fixer to ensure proper code style
  • Always add a newline at the end of the file
  • Prefer $this->assert* over self::assert* in tests
  • Never add Claude as co-author in the commits
  • Add @author tags to newly introduced classes by the user
  • Prefer classic if statements over short-circuit evaluation when possible
  • Define array shapes for parameters and return types
  • Use project specific exceptions instead of global exception classes like \RuntimeException, \InvalidArgumentException etc.
  • NEVER mention Claude as co-author in commits
  • Avoid using the empty() function; prefer explicit checks like [] === $array, '' === $string, or null === $value

Version Documentation

UPGRADE.md

  • Document breaking changes in the root UPGRADE.md file
  • Format: Use version headers like UPGRADE FROM 0.X to 0.Y with sections per component
  • Include code examples showing before/after changes with diff syntax

CHANGELOG.md

  • Each component has its own CHANGELOG.md in its root directory
  • Add entries for new features, and deprecations under the appropriate version heading
  • Format entries as bullet points starting with "Add", "Fix", "Deprecate", etc.

Pull Requests

  • Always use the PR template from .github/PULL_REQUEST_TEMPLATE.md
  • Fill in the table at the top of the PR description with appropriate values:
    • Bug fix?: yes/no
    • New feature?: yes/no (update CHANGELOG.md files for new features)
    • Docs?: yes/no (required for new features)
    • Issues: Fix #... (prefix each issue number with "Fix #")
    • License: MIT
  • Provide a clear description of the changes below the table