From 42162c87bd9380c16542749f21bb5e5f93bbeff2 Mon Sep 17 00:00:00 2001
From: Oskar Stark <oskarstark@googlemail.com>
Date: Mon, 8 Sep 2025 23:41:33 +0200
Subject: [PATCH]  Add `AGENTS.md` with optimized guidance for AI agents

---
 AGENTS.md               | 96 +++++++++++++++++++++++++++++++++++++++++
 demo/AGENTS.md          | 79 +++++++++++++++++++++++++++++++++
 examples/AGENTS.md      | 59 +++++++++++++++++++++++++
 src/agent/AGENTS.md     | 82 +++++++++++++++++++++++++++++++++++
 src/ai-bundle/AGENTS.md | 94 ++++++++++++++++++++++++++++++++++++++++
 src/platform/AGENTS.md  | 64 +++++++++++++++++++++++++++
 src/store/AGENTS.md     | 62 ++++++++++++++++++++++++++
 7 files changed, 536 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 demo/AGENTS.md
 create mode 100644 examples/AGENTS.md
 create mode 100644 src/agent/AGENTS.md
 create mode 100644 src/ai-bundle/AGENTS.md
 create mode 100644 src/platform/AGENTS.md
 create mode 100644 src/store/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..50c8c7400
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/demo/AGENTS.md b/demo/AGENTS.md
new file mode 100644
index 000000000..2da757cc0
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/examples/AGENTS.md b/examples/AGENTS.md
new file mode 100644
index 000000000..92f69f80a
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/src/agent/AGENTS.md b/src/agent/AGENTS.md
new file mode 100644
index 000000000..8b8130c7d
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/src/ai-bundle/AGENTS.md b/src/ai-bundle/AGENTS.md
new file mode 100644
index 000000000..0647ee13f
--- /dev/null
+++ b/src/ai-bundle/AGENTS.md
@@ -0,0 +1,94 @@
+# AGENTS.md
+
+AI agent guidance for the Symfony AI Bundle.
+
+## Component Overview
+
+Symfony integration bundle providing DI configuration for AI components (Platform, Agent, Store). Enables declarative YAML configuration and PHP attributes.
+
+## Architecture
+
+### Core Integration
+- **Platform Integration**: AI platforms as Symfony services
+- **Agent Configuration**: Declarative agent setup with tools/processors
+- **Store Configuration**: Vector stores for document retrieval
+- **Security Integration**: `#[IsGrantedTool]` attribute for authorization
+- **Profiler Integration**: Debug toolbar for AI interactions
+
+### Key Components
+- `AiBundle.php`: Main bundle with service configuration
+- `ProcessorCompilerPass.php`: Processor registration
+- Security system with `IsGrantedToolAttributeListener`
+- Profiler data collector and traceable decorators
+
+## Essential Commands
+
+### Testing
+```bash
+vendor/bin/phpunit
+vendor/bin/phpunit tests/DependencyInjection/AiBundleTest.php
+vendor/bin/phpunit --coverage-html coverage/
+```
+
+### Code Quality
+```bash
+vendor/bin/phpstan analyse
+# Code style fixes from monorepo root
+```
+
+## Configuration Architecture
+
+### Platform Configuration
+- Multiple AI providers via factory classes
+- Anthropic, OpenAI, Azure OpenAI, Gemini, VertexAI
+- HTTP client integration
+- Automatic service aliasing
+
+### Agent Configuration
+- Model configuration (class, name, options)
+- Tool integration via `#[AsTool]` or explicit references
+- Input/Output processor chains
+- System prompt with optional tool inclusion
+- Token usage tracking
+
+### Store Configuration
+- Local stores: memory, cache
+- Cloud stores: Azure Search, Pinecone, Qdrant
+- Database stores: MongoDB, ClickHouse, Neo4j
+
+### Security Integration
+- `#[IsGrantedTool]` method-level authorization
+- Symfony Security component integration
+- Runtime permission checking
+
+## Service Registration
+
+### Attribute-Based
+- `#[AsTool]`: Tool registration with name/description
+- `#[AsInputProcessor]`: Agent-specific input processing
+- `#[AsOutputProcessor]`: Agent-specific output processing
+
+### Interface-Based Autoconfiguration
+- `InputProcessorInterface` → `ai.agent.input_processor`
+- `OutputProcessorInterface` → `ai.agent.output_processor`
+- `ModelClientInterface` → `ai.platform.model_client`
+
+## Debug Features
+
+### Profiler Integration
+- Traceable decorators for platforms/toolboxes
+- Symfony Profiler data collector
+- AI interaction and token usage monitoring
+
+### Error Handling
+- Fault-tolerant toolbox wrapper
+- Bundle-specific exception hierarchy
+- Clear missing dependency error messages
+
+## Testing Patterns
+
+- Bundle configuration testing
+- Compiler pass testing
+- Security integration with mock checker
+- Profiler data collection testing
+- PHPUnit 11 with strict configuration
\ No newline at end of file
diff --git a/src/platform/AGENTS.md b/src/platform/AGENTS.md
new file mode 100644
index 000000000..72a057a75
--- /dev/null
+++ b/src/platform/AGENTS.md
@@ -0,0 +1,64 @@
+# AGENTS.md
+
+AI agent guidance for the Platform component.
+
+## Component Overview
+
+Unified abstraction for AI platforms (OpenAI, Anthropic, Azure, Gemini, VertexAI, Ollama, etc.). Provides consistent interfaces regardless of provider.
+
+## Architecture
+
+### Core Classes
+- **Platform**: Main entry point implementing `PlatformInterface`
+- **Model**: AI models with provider-specific configurations
+- **Contract**: Abstract contracts for AI capabilities (chat, embedding, speech)
+- **Message**: Message system for AI interactions
+- **Tool**: Function calling capabilities
+- **Bridge**: Provider-specific implementations
+
+### Key Directories
+- `src/Bridge/`: Provider implementations
+- `src/Contract/`: Abstract contracts and interfaces
+- `src/Message/`: Message handling system
+- `src/Tool/`: Function calling and tool definitions
+- `src/Result/`: Result types and converters
+- `src/Exception/`: Platform-specific exceptions
+
+### Provider Support
+Bridge implementations for:
+- OpenAI (GPT, DALL-E, Whisper)
+- Anthropic (Claude models)
+- Azure OpenAI
+- Google Gemini, VertexAI
+- AWS Bedrock, Ollama
+- Many others (see composer.json)
+
+## Essential Commands
+
+### Testing
+```bash
+vendor/bin/phpunit
+vendor/bin/phpunit tests/ModelTest.php
+vendor/bin/phpunit --coverage-html coverage
+```
+
+### Code Quality
+```bash
+vendor/bin/phpstan analyse
+cd ../../.. && vendor/bin/php-cs-fixer fix src/platform/
+```
+
+### Dependencies
+```bash
+composer install
+composer update
+```
+
+## Development Notes
+
+- PHPUnit 11+ with strict configuration
+- Test fixtures in `../../fixtures` for multimodal content
+- MockHttpClient pattern preferred
+- Follows Symfony coding standards
+- Bridge pattern for provider implementations
+- Consistent contract interfaces across providers
\ No newline at end of file
diff --git a/src/store/AGENTS.md b/src/store/AGENTS.md
new file mode 100644
index 000000000..c793fceaf
--- /dev/null
+++ b/src/store/AGENTS.md
@@ -0,0 +1,62 @@
+# AGENTS.md
+
+AI agent guidance for the Store component.
+
+## Component Overview
+
+Low-level abstraction for vector stores enabling RAG applications. Unified interfaces for various vector database implementations.
+
+## Architecture
+
+### Core Interfaces
+- **StoreInterface**: Main interface with `add()` and `query()` methods
+- **ManagedStoreInterface**: Extends with `setup()` and `drop()` lifecycle methods
+- **Indexer**: High-level service converting TextDocuments to VectorDocuments
+
+### Bridge Pattern
+Multiple vector store implementations:
+
+**Database**: Postgres, MariaDB, ClickHouse, MongoDB, Neo4j, SurrealDB
+**Cloud**: Azure AI Search, Pinecone
+**Search**: Meilisearch, Typesense, Weaviate, Qdrant, Milvus
+**Local**: InMemoryStore, CacheStore (PSR-6)
+**External**: ChromaDb (requires codewithkyrian/chromadb-php)
+
+### Document System
+- **TextDocument**: Input documents with text and metadata
+- **VectorDocument**: Documents with embedded vectors for storage
+- **Vectorizer**: Converts TextDocuments using AI Platform
+- **Transformers**: ChainTransformer, TextSplitTransformer, ChunkDelayTransformer
+
+## Essential Commands
+
+### Testing
+```bash
+vendor/bin/phpunit
+vendor/bin/phpunit tests/Bridge/Local/InMemoryStoreTest.php
+vendor/bin/phpunit --filter testMethodName
+```
+
+### Code Quality
+```bash
+vendor/bin/phpstan analyse
+```
+
+### Dependencies
+```bash
+composer install
+```
+
+## Key Dependencies
+
+- **symfony/ai-platform**: AI model integration and vectorization
+- **psr/log**: Logging throughout indexing process
+- **symfony/http-client**: HTTP-based vector store communication
+
+## Development Notes
+
+- Bridge pattern architecture with corresponding test structure
+- PHPUnit 11+ with strict configuration
+- Document preprocessing with transformers
+- Batch indexing for performance
+- Unified interface across all vector store types
\ No newline at end of file