Add AGENTS.md with optimized guidance for AI agents

AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Project Overview
+
+Symfony AI monorepo with independent packages for AI integration in PHP applications. Each component in `src/` has its own composer.json, tests, and dependencies.
+
+## Architecture
+
+### Core Components
+- **Platform** (`src/platform/`): Unified AI platform interface (OpenAI, Anthropic, Azure, Gemini, VertexAI)
+- **Agent** (`src/agent/`): AI agent framework for user interaction and task execution
+- **Store** (`src/store/`): Data storage abstraction with vector database support
+- **MCP SDK** (`src/mcp-sdk/`): Model Context Protocol SDK for agent-tool communication
+
+### Integration Bundles
+- **AI Bundle** (`src/ai-bundle/`): Symfony integration for Platform, Store, and Agent
+- **MCP Bundle** (`src/mcp-bundle/`): Symfony integration for MCP SDK
+
+### Supporting Directories
+- **Examples** (`examples/`): Standalone usage examples
+- **Demo** (`demo/`): Full Symfony web application demo
+- **Fixtures** (`fixtures/`): Shared multi-modal test fixtures
+
+## Essential Commands
+
+### Testing
+```bash
+# Component-specific testing
+cd src/platform && vendor/bin/phpunit
+cd src/agent && vendor/bin/phpunit
+cd src/ai-bundle && vendor/bin/phpunit
+cd demo && vendor/bin/phpunit
+```
+
+### Code Quality
+```bash
+# Fix code style (always run after changes)
+vendor/bin/php-cs-fixer fix
+
+# Static analysis (component-specific)
+cd src/platform && vendor/bin/phpstan analyse
+```
+
+### Development Tools
+```bash
+# Link components for development
+./link /path/to/project
+
+# Run examples
+cd examples && php anthropic/chat.php
+
+# Demo application
+cd demo && symfony server:start
+```
+
+## Code Standards
+
+### PHP Conventions
+- Follow Symfony coding standards with `@Symfony` PHP CS Fixer rules
+- Use project-specific exceptions instead of global ones (`\RuntimeException`, `\InvalidArgumentException`)
+- Define array shapes for parameters and return types
+- Add `@author` tags to new classes
+- Always add newlines at end of files
+
+### Testing Guidelines
+- Use **PHPUnit 11+** with component-specific configurations
+- Prefer `MockHttpClient` over response mocking
+- Use `self::assert*` or `$this->assert*` in tests
+- No void return types for test methods
+- Leverage shared fixtures in `/fixtures` for multi-modal content
+- Always fix risky tests
+
+### Git & Commits
+- Never mention AI assistance in commits or PR descriptions
+- Sign commits with GPG
+- Use conventional commit messages
+
+### Variable Naming
+- Name MessageBus variables as `$bus` (not `$messageBus`)
+
+## Component Dependencies
+
+- Agent → Platform (AI communication)
+- AI Bundle → Platform + Agent + Store (integration)
+- MCP Bundle → MCP SDK (integration)
+- Store: standalone (often used with Agent for RAG)
+
+## Development Workflow
+
+1. Each `src/` component is independently versioned
+2. Use `@dev` versions for internal dependencies during development
+3. Run PHP-CS-Fixer after code changes
+4. Test component-specific changes in isolation
+5. Use monorepo structure for shared development workflow

demo/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md
+
+AI agent guidance for the Symfony AI demo application.
+
+## Project Overview
+
+Symfony 7.3 demo showcasing AI integration with RAG, streaming chat, multimodal interactions, and MCP server functionality.
+
+## Architecture
+
+### Core Features
+- **Chat Systems**: Blog, YouTube, Wikipedia, Audio, Stream implementations
+- **Twig LiveComponents**: Real-time chat interfaces with Symfony UX
+- **AI Agents**: Multiple configured agents with different models and tools
+- **Vector Store**: ChromaDB integration for similarity search
+- **MCP Tools**: Model Context Protocol for extending agent capabilities
+
+### Technologies
+- Symfony 7.3 + UX (LiveComponent, Turbo, Typed)
+- OpenAI GPT-4o-mini + embeddings
+- ChromaDB vector database
+- FrankenPHP runtime
+
+## Essential Commands
+
+### Setup
+```bash
+# Start services
+docker compose up -d
+composer install
+echo "OPENAI_API_KEY='sk-...'" > .env.local
+
+# Initialize vector store
+symfony console app:blog:embed -vv
+symfony console app:blog:query
+
+# Start server
+symfony serve -d
+```
+
+### Testing
+```bash
+vendor/bin/phpunit
+vendor/bin/phpunit tests/SmokeTest.php
+```
+
+### Code Quality
+```bash
+vendor/bin/php-cs-fixer fix
+vendor/bin/phpstan analyse
+```
+
+### MCP Server
+```bash
+symfony console mcp:server
+# Test: {"method":"tools/list","jsonrpc":"2.0","id":1}
+```
+
+## Configuration
+
+### AI Setup (`config/packages/ai.yaml`)
+- **Agents**: blog, stream, youtube, wikipedia, audio
+- **Platform**: OpenAI integration
+- **Store**: ChromaDB vector store
+- **Indexer**: Text embedding model
+
+### Chat Pattern
+- `Chat` class: Message flow and session management
+- `TwigComponent` class: LiveComponent UI
+- Agent configuration in `ai.yaml`
+- Session storage with component keys
+
+## Development Notes
+
+- PHP 8.4+ with strict typing
+- OpenAI GPT-4o-mini default model
+- ChromaDB on port 8080
+- LiveComponents for real-time UI
+- Symfony DI and best practices

examples/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+AI agent guidance for Symfony AI examples directory.
+
+## Project Overview
+
+Standalone examples demonstrating Symfony AI component usage across different platforms. Serves as reference implementations and integration tests.
+
+## Essential Commands
+
+### Setup
+```bash
+composer install
+../link  # Link local AI components
+docker compose up -d  # For store examples
+```
+
+### Running Examples
+```bash
+# Single example
+php openai/chat.php
+php openai/toolcall-stream.php -vvv
+
+# Batch execution
+./runner  # All examples
+./runner openai mistral  # Specific platforms
+./runner --filter=toolcall  # Pattern filter
+```
+
+### Environment
+Configure API keys in `.env.local` (copy from `.env` template).
+
+## Architecture
+
+### Directory Structure
+- Platform directories: `openai/`, `anthropic/`, `gemini/`, etc.
+- `misc/`: Cross-platform examples
+- `rag/`: Retrieval Augmented Generation examples
+- `toolbox/`: Utility tools and integrations
+- `bootstrap.php`: Common setup for all examples
+
+### Patterns
+- Shared `bootstrap.php` setup
+- Consistent structure across platforms
+- Verbose output flags (`-vv`, `-vvv`)
+- Synchronous and streaming demos
+
+### Dependencies
+Uses `@dev` versions:
+- `symfony/ai-platform`
+- `symfony/ai-agent`
+- `symfony/ai-store`
+
+## Development Notes
+
+- Examples serve as integration tests
+- Runner executes in parallel for platform verification
+- Demonstrates both sync and async patterns
+- Platform-specific client configurations

src/agent/AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md
+
+AI agent guidance for the Agent component.
+
+## Component Overview
+
+Framework for building AI agents with user interaction and task execution. Built on Platform component with optional Store integration for memory.
+
+## Architecture
+
+### Core Classes
+- **Agent** (`src/Agent.php`): Main orchestration class
+- **AgentInterface**: Contract for implementations
+- **Chat** (`src/Chat.php`): High-level conversation interface
+- **Input/Output** (`src/Input.php`, `src/Output.php`): Pipeline data containers
+
+### Processing Pipeline
+- **InputProcessorInterface**: Input transformation contract
+- **OutputProcessorInterface**: Output transformation contract
+- Middleware-like processing chain
+
+### Key Features
+- **Memory** (`src/Memory/`): Conversation memory with embeddings
+- **Toolbox** (`src/Toolbox/`): Function calling capabilities
+- **Structured Output**: Typed response support
+- **Message Stores** (`src/Chat/MessageStore/`): Chat persistence
+
+## Essential Commands
+
+### Testing
+```bash
+vendor/bin/phpunit
+vendor/bin/phpunit tests/AgentTest.php
+vendor/bin/phpunit --coverage-html coverage/
+```
+
+### Code Quality
+```bash
+vendor/bin/phpstan analyse
+cd ../../.. && vendor/bin/php-cs-fixer fix src/agent/
+```
+
+## Processing Architecture
+
+### Pipeline Flow
+1. Input processors modify requests
+2. Platform processes request
+3. Output processors modify responses
+
+### Built-in Processors
+- **SystemPromptInputProcessor**: Adds system prompts
+- **ModelOverrideInputProcessor**: Runtime model switching
+- **MemoryInputProcessor**: Conversation context from memory
+
+### Memory Providers
+- **StaticMemoryProvider**: In-memory storage
+- **EmbeddingProvider**: Vector-based semantic memory (requires Store)
+
+### Tool Integration
+- Auto-discovery via attributes
+- Fault-tolerant execution
+- Event system for lifecycle management
+
+## Dependencies
+
+- **Platform component**: Required for AI communication
+- **Store component**: Optional for embedding memory
+- **Symfony**: HttpClient, Serializer, PropertyAccess, Clock
+
+## Testing Patterns
+
+- Use `MockHttpClient` over response mocking
+- Test processors independently
+- Use `/fixtures` for multimodal content
+- Prefer `self::assert*` in tests
+
+## Development Notes
+
+- Component is experimental (BC breaks possible)
+- Add `@author` tags to new classes
+- Use component-specific exceptions from `src/Exception/`
+- Follow `@Symfony` PHP CS Fixer rules