Add comprehensive documentation for AI agents, file storage, background jobs, and localization

docs/site/.vitepress/config.ts

@@ -55,6 +55,15 @@ export default defineConfig({
             { text: 'Inertia.js Integration', link: '/guide/inertia' },
           ],
         },
+        {
+          text: 'Infrastructure',
+          items: [
+            { text: 'Background Jobs', link: '/guide/background-jobs' },
+            { text: 'File Storage', link: '/guide/file-storage' },
+            { text: 'Localization', link: '/guide/localization' },
+            { text: 'AI Agents & RAG', link: '/guide/ai-agents' },
+          ],
+        },
       ],
 
       '/frontend/': [

docs/site/getting-started/introduction.md

@@ -100,6 +100,32 @@ sm new feature Products/Browse  # add a feature to an existing module
 sm doctor --fix              # validate project structure, auto-fix issues
 ```
 
+### AI Agents & RAG
+
+Build AI-powered features with built-in support for multiple LLM providers, tool calling, and retrieval-augmented generation:
+
+- **Multi-provider AI** -- Anthropic (Claude), OpenAI, Azure OpenAI, and Ollama behind a unified `IChatClient` interface
+- **Agent runtime** -- define agents with custom instructions, tools, and guardrails. Supports streaming (SSE) responses
+- **Tool discovery** -- mark methods with `[AgentTool]` for automatic tool registration
+- **RAG pipeline** -- index documents into a vector store and inject relevant context into agent conversations
+- **Built-in safety** -- rate limiting, token tracking, PII redaction, and prompt injection detection
+
+### File Storage
+
+A pluggable file storage abstraction with providers for local filesystem, AWS S3, and Azure Blob Storage. The FileStorage module adds HTTP upload/download endpoints, folder browsing, and a database-backed file registry.
+
+### Background Jobs
+
+Schedule and monitor long-running tasks with the BackgroundJobs module:
+
+- Immediate, delayed, and CRON-based recurring job scheduling
+- Real-time progress reporting and structured logging
+- Admin dashboard with job monitoring, retry, and cancellation
+
+### Localization
+
+Built-in multi-language support with embedded JSON locale files, automatic locale resolution (user settings, Accept-Language header), and a React `useTranslation()` hook for frontend integration.
+
 ### Multi-Provider Database
 
 SimpleModule supports multiple database providers with automatic schema isolation:
@@ -169,8 +195,12 @@ You don't write registration code, startup configuration, or reflection-based di
 | Build tooling | Vite, Tailwind CSS 4 |
 | Source generation | Roslyn incremental generators |
 | Component library | Radix UI |
-| Testing | xUnit.v3, FluentAssertions, Bogus |
+| AI | Anthropic, OpenAI, Azure OpenAI, Ollama via Microsoft.Extensions.AI |
+| RAG | Vector search with PostgreSQL or in-memory stores |
+| Testing | xUnit.v3, FluentAssertions, Bogus, Playwright, BenchmarkDotNet, NBomber |
 | Database | SQLite, PostgreSQL, SQL Server via EF Core |
+| File storage | Local, AWS S3, Azure Blob Storage |
+| Job scheduling | TickerQ with CRON support |
 | CLI | System.CommandLine |
 
 ## Next Steps

docs/site/getting-started/project-structure.md

@@ -10,32 +10,60 @@ A SimpleModule solution follows a consistent directory layout that separates the
 
 ```
 MyApp/
-├── framework/               # Core framework packages
+├── framework/                    # Core framework packages
 │   ├── SimpleModule.Core/
 │   ├── SimpleModule.Generator/
 │   ├── SimpleModule.Database/
 │   ├── SimpleModule.Blazor/
 │   ├── SimpleModule.Hosting/
-│   └── SimpleModule.DevTools/
-├── modules/                 # Your feature modules
-│   ├── Products/
+│   ├── SimpleModule.DevTools/
+│   ├── SimpleModule.Agents/       # AI agent runtime and registry
+│   ├── SimpleModule.AI.Anthropic/ # Claude API provider
+│   ├── SimpleModule.AI.OpenAI/    # OpenAI API provider
+│   ├── SimpleModule.AI.AzureOpenAI/ # Azure OpenAI provider
+│   ├── SimpleModule.AI.Ollama/    # Ollama local model provider
+│   ├── SimpleModule.Rag/          # RAG pipeline and knowledge store
+│   ├── SimpleModule.Rag.StructuredRag/      # Structured RAG pipeline
+│   ├── SimpleModule.Rag.VectorStore.InMemory/ # In-memory vector store (dev)
+│   ├── SimpleModule.Rag.VectorStore.Postgres/ # PostgreSQL vector store
+│   ├── SimpleModule.Storage/      # Storage provider abstraction
+│   ├── SimpleModule.Storage.Local/ # Local filesystem storage
+│   ├── SimpleModule.Storage.S3/    # AWS S3 storage
+│   └── SimpleModule.Storage.Azure/ # Azure Blob storage
+├── modules/                      # Your feature modules
+│   ├── Admin/
+│   ├── Agents/
+│   ├── AuditLogs/
+│   ├── BackgroundJobs/
+│   ├── Dashboard/
+│   ├── FeatureFlags/
+│   ├── FileStorage/
+│   ├── Localization/
+│   ├── Marketplace/
+│   ├── OpenIddict/
 │   ├── Orders/
-│   └── Settings/
-├── packages/                # Frontend npm packages
+│   ├── PageBuilder/
+│   ├── Permissions/
+│   ├── Products/
+│   ├── Rag/
+│   ├── Settings/
+│   ├── Tenants/
+│   └── Users/
+├── packages/                     # Frontend npm packages
 │   ├── SimpleModule.Client/
 │   ├── SimpleModule.UI/
 │   └── SimpleModule.Theme.Default/
 ├── template/
-│   └── SimpleModule.Host/   # The host application
+│   └── SimpleModule.Host/        # The host application
 │       ├── ClientApp/
 │       ├── Program.cs
 │       └── wwwroot/
 ├── cli/
-│   └── SimpleModule.Cli/    # The sm CLI tool
-├── tests/                   # Framework-level test projects
-├── SimpleModule.slnx        # Solution file
-├── package.json             # Root npm workspace config
-└── Directory.Build.props    # Shared MSBuild properties
+│   └── SimpleModule.Cli/         # The sm CLI tool
+├── tests/                        # Framework-level test projects
+├── SimpleModule.slnx             # Solution file
+├── package.json                  # Root npm workspace config
+└── Directory.Build.props         # Shared MSBuild properties
 ```
 
 ## Framework Projects
@@ -98,6 +126,35 @@ Module registration infrastructure. Provides the runtime plumbing that the gener
 
 Development utilities including hot reload support, diagnostic middleware, and developer experience tooling that is excluded from production builds.
 
+### SimpleModule.Agents
+
+AI agent runtime and orchestration. Provides `IAgentRegistry` for agent discovery, `AgentChatService` for chat (streaming and non-streaming), `IAgentToolProvider` with `[AgentTool]` attribute for tool discovery, and middleware for rate limiting, token tracking, and guardrails (PII redaction, prompt injection detection).
+
+### SimpleModule.AI.*
+
+AI provider integrations implementing `IChatClient` from Microsoft.Extensions.AI:
+
+- **SimpleModule.AI.Anthropic** -- Claude API via the Anthropic SDK
+- **SimpleModule.AI.OpenAI** -- OpenAI API
+- **SimpleModule.AI.AzureOpenAI** -- Azure OpenAI Service
+- **SimpleModule.AI.Ollama** -- Ollama for local model inference
+
+### SimpleModule.Rag
+
+Retrieval-augmented generation pipeline. Defines `IRagPipeline` for querying a knowledge base and `IKnowledgeStore` for indexing documents. Includes `KnowledgeIndexingHostedService` for background indexing with deduplication.
+
+- **SimpleModule.Rag.StructuredRag** -- Structured RAG implementation (table, graph, algorithm, catalogue, chunk formats)
+- **SimpleModule.Rag.VectorStore.InMemory** -- In-memory vector store for development and testing
+- **SimpleModule.Rag.VectorStore.Postgres** -- PostgreSQL-backed vector store for production
+
+### SimpleModule.Storage
+
+File storage abstraction with `IStorageProvider` interface (save, get, delete, exists, list). Three provider implementations:
+
+- **SimpleModule.Storage.Local** -- local filesystem storage
+- **SimpleModule.Storage.S3** -- AWS S3 and S3-compatible services
+- **SimpleModule.Storage.Azure** -- Azure Blob Storage
+
 ## Module Structure
 
 Every module follows a **three-project pattern**: implementation, contracts, and tests.

docs/site/guide/ai-agents.md

@@ -0,0 +1,224 @@
+---
+outline: deep
+---
+
+# AI Agents
+
+SimpleModule includes a framework for building AI-powered agents with tool calling, RAG (retrieval-augmented generation), and streaming responses. The agent system supports multiple AI providers and is configured through the standard settings system.
+
+## Architecture
+
+The agent stack has three layers:
+
+1. **AI Providers** (`SimpleModule.AI.*`) -- `IChatClient` implementations for different LLM providers
+2. **Agent Runtime** (`SimpleModule.Agents`) -- orchestration, tool discovery, session management, and middleware
+3. **RAG Pipeline** (`SimpleModule.Rag`) -- knowledge indexing and retrieval for context injection
+
+## Setting Up an AI Provider
+
+Register one AI provider in your host application. Each provider reads from a dedicated configuration section.
+
+### Anthropic (Claude)
+
+```csharp
+builder.Services.AddAnthropicAI(builder.Configuration);
+```
+
+```json
+{
+  "AI": {
+    "Anthropic": {
+      "ApiKey": "sk-ant-...",
+      "Model": "claude-sonnet-4-20250514"
+    }
+  }
+}
+```
+
+### OpenAI
+
+```csharp
+builder.Services.AddOpenAI(builder.Configuration);
+```
+
+```json
+{
+  "AI": {
+    "OpenAI": {
+      "ApiKey": "sk-...",
+      "Model": "gpt-4o"
+    }
+  }
+}
+```
+
+### Azure OpenAI
+
+```csharp
+builder.Services.AddAzureOpenAI(builder.Configuration);
+```
+
+```json
+{
+  "AI": {
+    "AzureOpenAI": {
+      "Endpoint": "https://your-resource.openai.azure.com",
+      "DeploymentName": "gpt-4o",
+      "ApiKey": "your-key"
+    }
+  }
+}
+```
+
+### Ollama (Local)
+
+```csharp
+builder.Services.AddOllamaAI(builder.Configuration);
+```
+
+```json
+{
+  "AI": {
+    "Ollama": {
+      "BaseUrl": "http://localhost:11434",
+      "Model": "llama3"
+    }
+  }
+}
+```
+
+## Registering the Agent Runtime
+
+```csharp
+builder.Services.AddSimpleModuleAgents(builder.Configuration);
+```
+
+This registers:
+- `AgentChatService` -- handles chat requests (streaming and non-streaming)
+- `IAgentRegistry` -- discovers and serves agent definitions
+- `IAgentSessionStore` -- persists conversation history
+- Middleware pipeline: logging, rate limiting, token tracking, retry
+- Guardrails: content length limits, PII redaction, prompt injection detection
+
+## Defining an Agent
+
+Implement `IAgentDefinition` in your module:
+
+```csharp
+public class ProductAssistant : IAgentDefinition
+{
+    public string Name => "product-assistant";
+    public string Description => "Helps users find and manage products";
+    public string Instructions => """
+        You are a product catalog assistant.
+        Help users search, compare, and manage products.
+        """;
+
+    // Optional overrides
+    public int? MaxTokens => 2048;
+    public double? Temperature => 0.5;
+    public bool? EnableRag => true;
+    public string? RagCollectionName => "products";
+}
+```
+
+## Creating Agent Tools
+
+Implement `IAgentToolProvider` and mark methods with `[AgentTool]`:
+
+```csharp
+public class ProductTools(IProductContracts products) : IAgentToolProvider
+{
+    [AgentTool(Name = "search_products", Description = "Search the product catalog")]
+    public async Task<List<ProductDto>> SearchAsync(string query, CancellationToken ct)
+    {
+        return await products.SearchAsync(query, ct);
+    }
+
+    [AgentTool(Name = "get_product", Description = "Get product details by ID")]
+    public async Task<ProductDto?> GetByIdAsync(int id, CancellationToken ct)
+    {
+        return await products.GetByIdAsync(id, ct);
+    }
+}
+```
+
+Tools are automatically discovered via DI and converted to AI function definitions that the LLM can call.
+
+## Chat API
+
+### Non-Streaming
+
+```csharp
+var response = await agentChatService.ChatAsync(
+    "product-assistant",
+    new AgentChatRequest { Message = "Find me all products under $50" },
+    cancellationToken);
+```
+
+### Streaming (SSE)
+
+```csharp
+await foreach (var chunk in agentChatService.ChatStreamAsync(
+    "product-assistant",
+    new AgentChatRequest { Message = "Compare these two products" },
+    cancellationToken))
+{
+    // Send chunk to client via SSE
+}
+```
+
+## RAG Integration
+
+When `EnableRag` is `true` on an agent definition, the runtime automatically:
+
+1. Queries the knowledge base via `IRagPipeline.QueryAsync()`
+2. Injects matching knowledge chunks into the system message
+3. Sends the enriched context to the LLM
+
+### Setting Up RAG
+
+```csharp
+builder.Services.AddSimpleModuleRag(builder.Configuration);
+```
+
+```json
+{
+  "Rag": {
+    "DefaultTopK": 5,
+    "MinScore": 0.7,
+    "EmbeddingDimension": 1536,
+    "IndexOnStartup": true
+  }
+}
+```
+
+Choose a vector store:
+
+```csharp
+// Development
+builder.Services.AddInMemoryVectorStore();
+
+// Production
+builder.Services.AddPostgresVectorStore(builder.Configuration);
+```
+
+## Agent Settings
+
+The module registers these settings (manageable via the admin UI):
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `Agents.Enabled` | `true` | Global kill switch |
+| `Agents.MaxTokens` | `4096` | Default max tokens per response |
+| `Agents.Temperature` | `0.7` | Default sampling temperature |
+| `Agents.EnableRag` | `true` | Enable RAG context injection |
+| `Agents.EnableStreaming` | `true` | Allow streaming responses |
+| `Agents.RateLimit.RequestsPerMinute` | `60` | Rate limit per user |
+| `Agents.RateLimit.TokensPerMinute` | `100000` | Token rate limit per user |
+
+## Next Steps
+
+- [File Storage](/guide/file-storage) -- storing files for RAG knowledge indexing
+- [Settings](/guide/settings) -- runtime configuration for agent behavior
+- [Modules](/guide/modules) -- structuring agent tools within modules