Enhance documentation for Spice.ai use cases (#1408)

Author: lukekim

website/docs/use-cases/ai/agentic-apps/index.md

@@ -9,6 +9,13 @@ pagination_next: null
 
 Spice.ai builds intelligent, autonomous agents for SaaS applications, enabling context-aware automation and decision-making to improve user experiences and operational efficiency.
 
+```mermaid
+graph LR
+    Sources[Data Sources] --> Spice[Spice]
+    Spice -->|Data + Search + AI| Agent[AI Agent]
+    Agent -->|Autonomous Actions| App[Application]
+```
+
 Unlike generic AI agent frameworks (e.g., AutoGen, CrewAI) that often lack direct integration with enterprise data or real-time capabilities, Spice.ai combines federated data access, hybrid search, and AI inference to deliver autonomous agents that operate with enterprise-grade governance and low-latency performance. This makes it ideal for SaaS platforms requiring dynamic, context-driven automation in customer-facing workflows.
 
 ## Why Spice.ai?

website/docs/use-cases/ai/edge-ai/index.md

@@ -9,6 +9,14 @@ pagination_next: null
 
 Spice.ai deploys AI applications and agents across cloud and edge for low-latency decisions in security IoT use cases, ensuring rapid threat detection and response in distributed environments.
 
+```mermaid
+graph LR
+    Cloud[Cloud Data] --> Spice[Spice - Edge]
+    Sensors[Edge Sensors] --> Spice
+    Spice --> Model[Local AI Model]
+    Model --> Decision[Decision]
+```
+
 Unlike cloud-centric AI platforms (e.g., AWS SageMaker, Google Vertex AI) that rely on constant connectivity and introduce latency, Spice.ai’s edge data materialization and local model inference enable real-time, resilient AI operations. This is critical for security applications requiring immediate action and functionality in low-connectivity scenarios, outperforming cloud-dependent solutions in speed and reliability.
 
 ## Why Spice.ai?

website/docs/use-cases/ai/federated-mcp-server/index.md

@@ -9,6 +9,15 @@ pagination_next: null
 
 Spice.ai federates external Model Context Protocol (MCP) servers over Server-Sent Events (SSE) for scalable, tool-driven AI applications in security, improving threat analysis with distributed tool ecosystems.
 
+```mermaid
+graph LR
+    MCP1[MCP Server A] --> Spice[Spice]
+    MCP2[MCP Server B] --> Spice
+    MCP3[MCP Server C] --> Spice
+    Spice -->|Unified Tools + Data| LLM[LLM]
+    LLM --> Response[Response]
+```
+
 Unlike centralized AI orchestration platforms (e.g., Apache Airflow for AI workflows) that introduce complexity and latency, Spice.ai's federated MCP client approach supports modular, scalable tool integration with integrated data and AI capabilities. This makes it ideal for security applications requiring distributed, real-time threat intelligence, outperforming platforms with rigid, centralized architectures.
 
 ## Why Spice.ai?

website/docs/use-cases/ai/index.md

@@ -1,7 +1,7 @@
 ---
 title: 'AI Applications and Agents'
 sidebar_label: 'AI Apps & Agents'
-sidebar_position: 4
+sidebar_position: 5
 description: 'AI Applications and Agents'
 pagination_prev: null
 pagination_next: null

website/docs/use-cases/ai/multi-tenant-agents/index.md

@@ -0,0 +1,175 @@
+---
+title: 'Multi-Tenant AI Agents'
+sidebar_label: 'Multi-Tenant AI Agents'
+sidebar_position: 16
+description: 'Deploy AI agents across many SaaS tenants with strict isolation and no per-tenant ETL pipelines.'
+pagination_prev: null
+pagination_next: null
+---
+
+Spice serves as the data substrate for multi-tenant AI agents, giving each tenant real-time access to its own data sources with configurable isolation and no per-tenant ETL pipelines. A lightweight Rust runtime can be deployed once for all tenants, once per tenant, or in a hybrid topology, and every deployment exposes the same SQL, search, and AI inference APIs over HTTP, Arrow Flight, FlightSQL, ODBC, JDBC, and ADBC.
+
+```mermaid
+graph LR
+    Agent[AI Agent or App] --> Router[Tenant Router]
+    Router --> Dedicated1[Spice: Enterprise A]
+    Router --> Dedicated2[Spice: Enterprise B]
+    Router --> Shared[Spice: Shared Partitioned]
+    Dedicated1 --> SourcesA[(Tenant A Sources)]
+    Dedicated2 --> SourcesB[(Tenant B Sources)]
+    Shared --> SourcesLT[(Long-Tail Tenant Sources)]
+```
+
+Pipeline-per-integration architectures collapse at scale: every tenant brings its own schema, refresh cadence, and ownership, and ETL orchestration becomes the bottleneck. Spice federates queries across 30+ data sources and accelerates them locally, so adding a tenant is a Spicepod configuration change rather than a new pipeline.
+
+## Why Spice.ai?
+
+- **Zero-ETL federation**: Query PostgreSQL, Snowflake, Databricks, S3, Kafka, and 25+ other sources through a single SQL interface. Onboarding a tenant is a dataset declaration, not a pipeline build.
+- **Configurable isolation**: Choose logical, config-level, or runtime-level tenant boundaries. Isolation becomes a deployment property rather than something enforced in application code.
+- **Sandboxed runtimes**: The Spice runtime is lightweight enough to deploy one instance per tenant or per agent, giving each agent its own sources, acceleration layers, and secrets.
+- **Local acceleration with CDC**: Materialize tenant working sets into Arrow, DuckDB, SQLite, or PostgreSQL accelerators and keep them current with change data capture.
+- **Declarative configuration**: The [`spicepod.yaml`](../../../reference/spicepod) manifest defines datasets, models, secrets, and acceleration behavior, so tenant topology is version-controlled and auditable.
+
+## Deployment Patterns
+
+Four patterns trade off operational simplicity against isolation strength. Most SaaS workloads converge on a hybrid configuration.
+
+### Pattern 1: Query-Time Tenant Isolation
+
+One runtime serves many tenants. Datasets reference tenant-partitioned tables, and the application includes a tenant filter in every query.
+
+```yaml
+version: v1
+kind: Spicepod
+name: saas-shared
+
+datasets:
+  - from: postgres:public.events
+    name: events
+    params:
+      pg_host: db.shared.internal
+      pg_port: '5432'
+      pg_db: app
+      pg_user: ${secrets:PG_USER}
+      pg_pass: ${secrets:PG_PASS}
+    acceleration:
+      enabled: true
+      engine: arrow
+      refresh_check_interval: 1s
+```
+
+This is the simplest and cheapest pattern to operate, but isolation is logical: correctness depends on every query path applying the tenant filter.
+
+**View-based variant**: Move tenant filtering into the Spicepod using [views](../../../reference/spicepod/views), so agents query a tenant-specific view rather than constructing the filter at runtime.
+
+```yaml
+datasets:
+  - name: events
+    from: postgres:public.events
+
+views:
+  - name: view_tenant_abc
+    sql: "select * from events where tenant='tenant_abc'"
+  - name: view_tenant_xyz
+    sql: "select * from events where tenant='tenant_xyz'"
+```
+
+### Pattern 2: Config-Level Tenant Isolation
+
+One runtime, but each tenant gets its own dataset entry. The manifest is typically generated from tenant-onboarding metadata.
+
+```yaml
+version: v1
+kind: Spicepod
+name: saas-many-datasets
+
+datasets:
+  - from: postgres:tenant_abc.events
+    name: tenant_abc_events
+    params:
+      pg_host: db.pool.internal
+      pg_db: app
+      pg_user: ${secrets:PG_USER}
+      pg_pass: ${secrets:PG_PASS}
+
+  - from: postgres:tenant_xyz.events
+    name: tenant_xyz_events
+    params:
+      pg_host: db.pool.internal
+      pg_db: app
+      pg_user: ${secrets:PG_USER}
+      pg_pass: ${secrets:PG_PASS}
+```
+
+Tenant boundaries are explicit in configuration and easier to audit, but the manifest grows with tenant count and reload time and memory planning become operational concerns at large scale.
+
+### Pattern 3: Runtime-Level Tenant Isolation
+
+Run a dedicated Spicepod per tenant and route requests using tenant context from auth or session claims. Each runtime has an independent manifest, compute envelope, and cache.
+
+```yaml
+version: v1
+kind: Spicepod
+name: tenant-abc
+
+datasets:
+  - from: postgres:public.events
+    name: events
+    params:
+      pg_host: tenant-abc-db.internal
+      pg_db: app
+      pg_user: ${secrets:PG_USER}
+      pg_pass: ${secrets:PG_PASS}
+    acceleration:
+      enabled: true
+      engine: duckdb
+      mode: file
+      refresh_check_interval: 1s
+      params:
+        duckdb_file: /var/lib/spice/tenant-abc.db
+```
+
+This gives the clearest isolation model and per-tenant operational control, at the cost of higher operational overhead as tenant count grows. It fits regulated workloads that require strict data boundaries.
+
+### Pattern 4: Hybrid Isolation
+
+Large tenants run on dedicated Spicepods while the long tail shares a partitioned deployment. A tenant-aware router decides placement and clients query a single logical interface.
+
+```yaml
+# router config (conceptual)
+tenants:
+  - id: enterprise-abc
+    spicepod: spicepod-tenant-abc
+  - id: enterprise-xyz
+    spicepod: spicepod-tenant-xyz
+
+default:
+  spicepod: spicepod-shared
+```
+
+Hybrid isolation keeps the query interface stable while allowing tenant placement by policy, isolating high-load or regulated tenants on dedicated runtimes and using shared capacity for the long tail. It is the recommended starting point for variable SaaS workloads.
+
+## Choosing a Pattern
+
+The right shape depends on isolation requirements, tenant count, and query volume per tenant.
+
+| Requirement | Recommended Pattern |
+| --- | --- |
+| Small tenant count, uniform workload | Pattern 1 or 1-view |
+| Explicit config-level boundaries, auditable manifest | Pattern 2 |
+| Regulated tenants, strict per-tenant SLOs | Pattern 3 |
+| Power-law tenant distribution | Pattern 4 (hybrid) |
+
+## Benefits
+
+- **Zero-ETL onboarding**: Add a tenant by declaring a dataset, not by building a pipeline.
+- **Deployment-level isolation**: Match isolation strength to business and compliance requirements without changing application code.
+- **Consistent interface**: Agents query SQL, search, and inference APIs the same way regardless of how tenants are partitioned underneath.
+
+## Learn More
+
+- [Multi-Tenancy for AI Agents without the Pipelines](https://spice.ai/blog/multi-tenancy-for-ai-agents-without-pipelines) — the engineering deep dive behind these patterns.
+- [Spicepod reference](../../../reference/spicepod) and [datasets reference](../../../reference/spicepod/datasets).
+- [Views](../../../reference/spicepod/views) for declarative tenant filtering.
+- [Data Acceleration](../../../features/data-acceleration) and [Change Data Capture](../../../features/data-acceleration/data-refresh).
+- [Federated SQL Query recipe](https://github.com/spiceai/cookbook/blob/trunk/federation/README.md).

website/docs/use-cases/ai/object-store-ai-engine/index.md

@@ -9,6 +9,15 @@ pagination_next: null
 
 Spice.ai enables SQL queries, hybrid search, and large language model (LLM) inference on object-store data for security applications, delivering real-time insights from distributed data sources with minimal infrastructure overhead.
 
+```mermaid
+graph LR
+    S3[S3 / Object Store] --> Spice[Spice]
+    Query[Query] --> Spice
+    Spice -->|SQL + Search| Results[Results]
+    Results --> LLM[LLM]
+    LLM --> Insights[Insights]
+```
+
 Unlike traditional data platforms (e.g., Snowflake, BigQuery) or separate search and AI frameworks (e.g., Elasticsearch, LangChain) that require complex data pipelines and centralized storage, Spice.ai integrates SQL querying, vector/keyword search, and LLM inference directly on object stores (e.g., S3, Azure Blob). This unified approach reduces latency, simplifies architecture, and ensures compliance for security applications, outperforming fragmented solutions that demand extensive data movement and integration.
 
 ## Why Spice.ai?

website/docs/use-cases/ai/real-time-decision-making/index.md

@@ -9,6 +9,13 @@ pagination_next: null
 
 Spice.ai powers instant, context-aware decisions for applications like security recommendations by grounding AI in federated, low-latency datasets.
 
+```mermaid
+graph LR
+    Sources[Multiple Data Sources] --> Spice[Spice]
+    Spice -->|Accelerated Data| AI[AI Gateway]
+    AI --> Decision[Real-Time Decision]
+```
+
 Unlike batch-processing analytics platforms (e.g., traditional data warehouses), Spice.ai delivers real-time decisions by unifying disparate data sources and accelerating access, outpacing siloed pipelines that introduce delays and complexity.
 
 ## Why Spice.ai?

website/docs/use-cases/ai/tool-calling-ai/index.md

@@ -9,6 +9,14 @@ pagination_next: null
 
 Spice.ai extends AI with custom tools via Model Context Protocol (MCP) server in financial services (finserv), integrating domain-specific APIs for enhanced functionality and precise decision-making in high-stakes financial applications.
 
+```mermaid
+graph LR
+    Client[AI Client] -->|Request| Spice[Spice MCP Server]
+    Spice -->|Tool Call| Tools[Custom Tools]
+    Spice -->|Query| Data[Federated Data]
+    Spice -->|Response| Client
+```
+
 Unlike generic tool-calling frameworks (e.g., OpenAI Functions) that rely on external APIs and lack deep data integration, Spice.ai's stdio-based MCP servers provide low-latency, secure tool interactions with federated data access. This makes it ideal for finserv applications requiring compliance, real-time performance, and tailored AI capabilities, outperforming platforms with limited domain-specific tool integration.
 
 ## Why Spice.ai?