diff --git a/documentation/README.md b/documentation/README.md
new file mode 100644
index 00000000..055c983a
--- /dev/null
+++ b/documentation/README.md
@@ -0,0 +1,43 @@
+# Mintlify Starter Kit
+
+Use the starter kit to get your docs deployed and ready to customize.
+
+Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+
+- Guide pages
+- Navigation
+- Customizations
+- API reference pages
+- Use of popular components
+
+**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+
+## Development
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+
+```
+npm i -g mint
+```
+
+Run the following command at the root of your documentation, where your `docs.json` is located:
+
+```
+mint dev
+```
+
+View your local preview at `http://localhost:3000`.
+
+## Publishing changes
+
+Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+
+## Need help?
+
+### Troubleshooting
+
+- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
+- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+
+### Resources
+- [Mintlify documentation](https://mintlify.com/docs)
diff --git a/documentation/ai-tools/claude-code.mdx b/documentation/ai-tools/claude-code.mdx
new file mode 100644
index 00000000..bdc4e04b
--- /dev/null
+++ b/documentation/ai-tools/claude-code.mdx
@@ -0,0 +1,76 @@
+---
+title: "Claude Code setup"
+description: "Configure Claude Code for your documentation workflow"
+icon: "asterisk"
+---
+
+Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation.
+
+## Prerequisites
+
+- Active Claude subscription (Pro, Max, or API access)
+
+## Setup
+
+1. Install Claude Code globally:
+
+ ```bash
+ npm install -g @anthropic-ai/claude-code
+```
+
+2. Navigate to your docs directory.
+3. (Optional) Add the `CLAUDE.md` file below to your project.
+4. Run `claude` to start.
+
+## Create `CLAUDE.md`
+
+Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards:
+
+````markdown
+# Mintlify documentation
+
+## Working relationship
+- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
+- ALWAYS ask for clarification rather than making assumptions
+- NEVER lie, guess, or make up information
+
+## Project context
+- Format: MDX files with YAML frontmatter
+- Config: docs.json for navigation, theme, settings
+- Components: Mintlify components
+
+## Content strategy
+- Document just enough for user success - not too much, not too little
+- Prioritize accuracy and usability of information
+- Make content evergreen when possible
+- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
+- Check existing patterns for consistency
+- Start by making the smallest reasonable changes
+
+## Frontmatter requirements for pages
+- title: Clear, descriptive page title
+- description: Concise summary for SEO/navigation
+
+## Writing standards
+- Second-person voice ("you")
+- Prerequisites at start of procedural content
+- Test all code examples before publishing
+- Match style and formatting of existing pages
+- Include both basic and advanced use cases
+- Language tags on all code blocks
+- Alt text on all images
+- Relative paths for internal links
+
+## Git workflow
+- NEVER use --no-verify when committing
+- Ask how to handle uncommitted changes before starting
+- Create a new branch when no clear branch exists for changes
+- Commit frequently throughout development
+- NEVER skip or disable pre-commit hooks
+
+## Do not
+- Skip frontmatter on any MDX file
+- Use absolute URLs for internal links
+- Include untested code examples
+- Make assumptions - always ask for clarification
+````
diff --git a/documentation/ai-tools/cursor.mdx b/documentation/ai-tools/cursor.mdx
new file mode 100644
index 00000000..fbb77616
--- /dev/null
+++ b/documentation/ai-tools/cursor.mdx
@@ -0,0 +1,420 @@
+---
+title: "Cursor setup"
+description: "Configure Cursor for your documentation workflow"
+icon: "arrow-pointer"
+---
+
+Use Cursor to help write and maintain your documentation. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components.
+
+## Prerequisites
+
+- Cursor editor installed
+- Access to your documentation repository
+
+## Project rules
+
+Create project rules that all team members can use. In your documentation repository root:
+
+```bash
+mkdir -p .cursor
+```
+
+Create `.cursor/rules.md`:
+
+````markdown
+# Mintlify technical writing rule
+
+You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
+
+## Core writing principles
+
+### Language and style requirements
+
+- Use clear, direct language appropriate for technical audiences
+- Write in second person ("you") for instructions and procedures
+- Use active voice over passive voice
+- Employ present tense for current states, future tense for outcomes
+- Avoid jargon unless necessary and define terms when first used
+- Maintain consistent terminology throughout all documentation
+- Keep sentences concise while providing necessary context
+- Use parallel structure in lists, headings, and procedures
+
+### Content organization standards
+
+- Lead with the most important information (inverted pyramid structure)
+- Use progressive disclosure: basic concepts before advanced ones
+- Break complex procedures into numbered steps
+- Include prerequisites and context before instructions
+- Provide expected outcomes for each major step
+- Use descriptive, keyword-rich headings for navigation and SEO
+- Group related information logically with clear section breaks
+
+### User-centered approach
+
+- Focus on user goals and outcomes rather than system features
+- Anticipate common questions and address them proactively
+- Include troubleshooting for likely failure points
+- Write for scannability with clear headings, lists, and white space
+- Include verification steps to confirm success
+
+## Mintlify component reference
+
+### Callout components
+
+#### Note - Additional helpful information
+
+
+Supplementary information that supports the main content without interrupting flow
+
+
+#### Tip - Best practices and pro tips
+
+
+Expert advice, shortcuts, or best practices that enhance user success
+
+
+#### Warning - Important cautions
+
+
+Critical information about potential issues, breaking changes, or destructive actions
+
+
+#### Info - Neutral contextual information
+
+
+Background information, context, or neutral announcements
+
+
+#### Check - Success confirmations
+
+
+Positive confirmations, successful completions, or achievement indicators
+
+
+### Code components
+
+#### Single code block
+
+Example of a single code block:
+
+```javascript config.js
+const apiConfig = {
+ baseURL: 'https://api.example.com',
+ timeout: 5000,
+ headers: {
+ 'Authorization': `Bearer ${process.env.API_TOKEN}`
+ }
+};
+```
+
+#### Code group with multiple languages
+
+Example of a code group:
+
+
+```javascript Node.js
+const response = await fetch('/api/endpoint', {
+ headers: { Authorization: `Bearer ${apiKey}` }
+});
+```
+
+```python Python
+import requests
+response = requests.get('/api/endpoint',
+ headers={'Authorization': f'Bearer {api_key}'})
+```
+
+```curl cURL
+curl -X GET '/api/endpoint' \
+ -H 'Authorization: Bearer YOUR_API_KEY'
+```
+
+
+#### Request/response examples
+
+Example of request/response documentation:
+
+
+```bash cURL
+curl -X POST 'https://api.example.com/users' \
+ -H 'Content-Type: application/json' \
+ -d '{"name": "John Doe", "email": "john@example.com"}'
+```
+
+
+
+```json Success
+{
+ "id": "user_123",
+ "name": "John Doe",
+ "email": "john@example.com",
+ "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+
+### Structural components
+
+#### Steps for procedures
+
+Example of step-by-step instructions:
+
+
+
+ Run `npm install` to install required packages.
+
+
+ Verify installation by running `npm list`.
+
+
+
+
+ Create a `.env` file with your API credentials.
+
+ ```bash
+ API_KEY=your_api_key_here
+ ```
+
+
+ Never commit API keys to version control.
+
+
+
+
+#### Tabs for alternative content
+
+Example of tabbed content:
+
+
+
+ ```bash
+ brew install node
+ npm install -g package-name
+ ```
+
+
+
+ ```powershell
+ choco install nodejs
+ npm install -g package-name
+ ```
+
+
+
+ ```bash
+ sudo apt install nodejs npm
+ npm install -g package-name
+ ```
+
+
+
+#### Accordions for collapsible content
+
+Example of accordion groups:
+
+
+
+ - **Firewall blocking**: Ensure ports 80 and 443 are open
+ - **Proxy configuration**: Set HTTP_PROXY environment variable
+ - **DNS resolution**: Try using 8.8.8.8 as DNS server
+
+
+
+ ```javascript
+ const config = {
+ performance: { cache: true, timeout: 30000 },
+ security: { encryption: 'AES-256' }
+ };
+ ```
+
+
+
+### Cards and columns for emphasizing information
+
+Example of cards and card groups:
+
+
+Complete walkthrough from installation to your first API call in under 10 minutes.
+
+
+
+
+ Learn how to authenticate requests using API keys or JWT tokens.
+
+
+
+ Understand rate limits and best practices for high-volume usage.
+
+
+
+### API documentation components
+
+#### Parameter fields
+
+Example of parameter documentation:
+
+
+Unique identifier for the user. Must be a valid UUID v4 format.
+
+
+
+User's email address. Must be valid and unique within the system.
+
+
+
+Maximum number of results to return. Range: 1-100.
+
+
+
+Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
+
+
+#### Response fields
+
+Example of response field documentation:
+
+
+Unique identifier assigned to the newly created user.
+
+
+
+ISO 8601 formatted timestamp of when the user was created.
+
+
+
+List of permission strings assigned to this user.
+
+
+#### Expandable nested fields
+
+Example of nested field documentation:
+
+
+Complete user object with all associated data.
+
+
+
+ User profile information including personal details.
+
+
+
+ User's first name as entered during registration.
+
+
+
+ URL to user's profile picture. Returns null if no avatar is set.
+
+
+
+
+
+
+### Media and advanced components
+
+#### Frames for images
+
+Wrap all images in frames:
+
+
+
+
+
+
+
+
+
+#### Videos
+
+Use the HTML video element for self-hosted video content:
+
+
+
+Embed YouTube videos using iframe elements:
+
+
+
+#### Tooltips
+
+Example of tooltip usage:
+
+
+API
+
+
+#### Updates
+
+Use updates for changelogs:
+
+
+## New features
+- Added bulk user import functionality
+- Improved error messages with actionable suggestions
+
+## Bug fixes
+- Fixed pagination issue with large datasets
+- Resolved authentication timeout problems
+
+
+## Required page structure
+
+Every documentation page must begin with YAML frontmatter:
+
+```yaml
+---
+title: "Clear, specific, keyword-rich title"
+description: "Concise description explaining page purpose and value"
+---
+```
+
+## Content quality standards
+
+### Code examples requirements
+
+- Always include complete, runnable examples that users can copy and execute
+- Show proper error handling and edge case management
+- Use realistic data instead of placeholder values
+- Include expected outputs and results for verification
+- Test all code examples thoroughly before publishing
+- Specify language and include filename when relevant
+- Add explanatory comments for complex logic
+- Never include real API keys or secrets in code examples
+
+### API documentation requirements
+
+- Document all parameters including optional ones with clear descriptions
+- Show both success and error response examples with realistic data
+- Include rate limiting information with specific limits
+- Provide authentication examples showing proper format
+- Explain all HTTP status codes and error handling
+- Cover complete request/response cycles
+
+### Accessibility requirements
+
+- Include descriptive alt text for all images and diagrams
+- Use specific, actionable link text instead of "click here"
+- Ensure proper heading hierarchy starting with H2
+- Provide keyboard navigation considerations
+- Use sufficient color contrast in examples and visuals
+- Structure content for easy scanning with headers and lists
+
+## Component selection logic
+
+- Use **Steps** for procedures and sequential instructions
+- Use **Tabs** for platform-specific content or alternative approaches
+- Use **CodeGroup** when showing the same concept in multiple programming languages
+- Use **Accordions** for progressive disclosure of information
+- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
+- Use **ParamField** for API parameters, **ResponseField** for API responses
+- Use **Expandable** for nested object properties or hierarchical information
+````
diff --git a/documentation/ai-tools/windsurf.mdx b/documentation/ai-tools/windsurf.mdx
new file mode 100644
index 00000000..fce12bfd
--- /dev/null
+++ b/documentation/ai-tools/windsurf.mdx
@@ -0,0 +1,96 @@
+---
+title: "Windsurf setup"
+description: "Configure Windsurf for your documentation workflow"
+icon: "water"
+---
+
+Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow.
+
+## Prerequisites
+
+- Windsurf editor installed
+- Access to your documentation repository
+
+## Workspace rules
+
+Create workspace rules that provide Windsurf with context about your documentation project and standards.
+
+Create `.windsurf/rules.md` in your project root:
+
+````markdown
+# Mintlify technical writing rule
+
+## Project context
+
+- This is a documentation project on the Mintlify platform
+- We use MDX files with YAML frontmatter
+- Navigation is configured in `docs.json`
+- We follow technical writing best practices
+
+## Writing standards
+
+- Use second person ("you") for instructions
+- Write in active voice and present tense
+- Start procedures with prerequisites
+- Include expected outcomes for major steps
+- Use descriptive, keyword-rich headings
+- Keep sentences concise but informative
+
+## Required page structure
+
+Every page must start with frontmatter:
+
+```yaml
+---
+title: "Clear, specific title"
+description: "Concise description for SEO and navigation"
+---
+```
+
+## Mintlify components
+
+### Callouts
+
+- `` for helpful supplementary information
+- `` for important cautions and breaking changes
+- `` for best practices and expert advice
+- `` for neutral contextual information
+- `` for success confirmations
+
+### Code examples
+
+- When appropriate, include complete, runnable examples
+- Use `` for multiple language examples
+- Specify language tags on all code blocks
+- Include realistic data, not placeholders
+- Use `` and `` for API docs
+
+### Procedures
+
+- Use `` component for sequential instructions
+- Include verification steps with `` components when relevant
+- Break complex procedures into smaller steps
+
+### Content organization
+
+- Use `` for platform-specific content
+- Use `` for progressive disclosure
+- Use `` and `` for highlighting content
+- Wrap images in `` components with descriptive alt text
+
+## API documentation requirements
+
+- Document all parameters with ``
+- Show response structure with ``
+- Include both success and error examples
+- Use `` for nested object properties
+- Always include authentication examples
+
+## Quality standards
+
+- Test all code examples before publishing
+- Use relative paths for internal links
+- Include alt text for all images
+- Ensure proper heading hierarchy (start with h2)
+- Check existing patterns for consistency
+````
diff --git a/documentation/development.mdx b/documentation/development.mdx
new file mode 100644
index 00000000..59218287
--- /dev/null
+++ b/documentation/development.mdx
@@ -0,0 +1,223 @@
+---
+title: 'Development'
+description: 'Set up your development environment for Flo AI'
+---
+
+
+ **Prerequisites**:
+ - Python 3.10 or higher
+ - pip or poetry package manager
+ - API keys for your chosen LLM providers
+
+
+Follow these steps to set up your development environment for Flo AI.
+
+
+
+
+Install Flo AI using pip or poetry:
+
+```bash
+# Using pip
+pip install flo-ai
+
+# Using poetry
+poetry add flo-ai
+```
+
+
+
+
+
+Configure your API keys for LLM providers:
+
+```bash
+# OpenAI
+export OPENAI_API_KEY="your-openai-key"
+
+# Anthropic
+export ANTHROPIC_API_KEY="your-anthropic-key"
+
+# Google Gemini
+export GOOGLE_API_KEY="your-google-key"
+
+# For Google Vertex AI
+export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+
+
+
+
+Test your installation with a simple agent:
+
+```python
+import asyncio
+from flo_ai.builder.agent_builder import AgentBuilder
+from flo_ai.llm import OpenAI
+
+async def test_installation():
+ agent = (
+ AgentBuilder()
+ .with_name('Test Agent')
+ .with_prompt('You are a helpful assistant.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .build()
+ )
+
+ response = await agent.run('Hello, world!')
+ print(f'Agent response: {response}')
+
+asyncio.run(test_installation())
+```
+
+
+
+
+## Development Tools
+
+### Flo AI Studio
+
+The Flo AI Studio is a visual workflow designer for creating AI agent workflows:
+
+
+
+
+```bash
+cd studio
+pnpm install
+```
+
+
+
+
+
+```bash
+pnpm dev
+```
+
+The studio will be available at `http://localhost:5173`.
+
+
+
+
+### Testing
+
+Run the test suite to ensure everything is working correctly:
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test files
+pytest tests/unit-tests/test_agent.py
+
+# Run with coverage
+pytest --cov=flo_ai
+```
+
+## Project Structure
+
+Understanding the Flo AI project structure:
+
+```
+flo_ai/
+├── flo_ai/ # Core package
+│ ├── builder/ # Agent builder components
+│ ├── llm/ # LLM provider integrations
+│ ├── tool/ # Tool framework
+│ ├── arium/ # Workflow orchestration
+│ ├── models/ # Data models
+│ └── telemetry/ # Observability
+├── examples/ # Example implementations
+├── tests/ # Test suite
+└── studio/ # Visual workflow designer
+```
+
+## Contributing
+
+
+
+
+ 1. Fork the repository
+ 2. Clone your fork: `git clone https://github.com/your-username/flo-ai.git`
+ 3. Install in development mode: `pip install -e .`
+ 4. Install development dependencies: `pip install -e ".[dev]"`
+ 5. Run tests: `pytest`
+
+
+
+
+
+ Flo AI uses pre-commit hooks for code formatting:
+
+ ```bash
+ # Install pre-commit
+ pip install pre-commit
+
+ # Install hooks
+ pre-commit install
+
+ # Run on all files
+ pre-commit run --all-files
+ ```
+
+
+
+
+
+ 1. Create a feature branch: `git checkout -b feature/your-feature`
+ 2. Make your changes and add tests
+ 3. Run tests: `pytest`
+ 4. Commit with conventional commits: `git commit -m "feat: add new feature"`
+ 5. Push and create a pull request
+
+
+
+
+## Troubleshooting
+
+
+
+
+ If you encounter import errors, ensure you're using Python 3.10+ and have installed all dependencies:
+
+ ```bash
+ pip install -r requirements.txt
+ # or
+ poetry install
+ ```
+
+
+
+
+
+ Verify your API keys are correctly set:
+
+ ```bash
+ echo $OPENAI_API_KEY
+ echo $ANTHROPIC_API_KEY
+ ```
+
+
+
+
+
+ If the studio doesn't load, try:
+
+ ```bash
+ cd studio
+ rm -rf node_modules
+ pnpm install
+ pnpm dev
+ ```
+
+
+
+
+## Need Help?
+
+- Check out our [examples](https://github.com/rootflo/flo-ai/tree/main/flo_ai/examples)
+- Join our [community discussions](https://github.com/rootflo/flo-ai/discussions)
+- Read the [contributing guide](https://github.com/rootflo/flo-ai/blob/main/CONTRIBUTING.md)
diff --git a/documentation/docs.json b/documentation/docs.json
new file mode 100644
index 00000000..a705f779
--- /dev/null
+++ b/documentation/docs.json
@@ -0,0 +1,98 @@
+{
+ "$schema": "https://mintlify.com/docs.json",
+ "theme": "mint",
+ "name": "Flo AI Documentation",
+ "colors": {
+ "primary": "#3B82F6",
+ "light": "#60A5FA",
+ "dark": "#1E40AF"
+ },
+ "favicon": "/favicon.png",
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "Guides",
+ "groups": [
+ {
+ "group": "Getting started",
+ "pages": [
+ "index",
+ "quickstart",
+ "development"
+ ]
+ },
+ {
+ "group": "Core Features",
+ "pages": [
+ "essentials/agents",
+ "essentials/arium",
+ "essentials/studio",
+ "essentials/yaml-agents",
+ "essentials/code"
+ ]
+ },
+ {
+ "group": "Advanced",
+ "pages": [
+ "essentials/llm-providers",
+ "essentials/tools",
+ "essentials/yaml-workflows",
+ "essentials/routing",
+ "essentials/telemetry"
+ ]
+ }
+ ]
+ }
+ ],
+ "global": {
+ "anchors": [
+ {
+ "anchor": "GitHub",
+ "href": "https://github.com/rootflo/flo-ai",
+ "icon": "github"
+ },
+ {
+ "anchor": "Community",
+ "href": "https://github.com/rootflo/flo-ai/discussions",
+ "icon": "comments"
+ }
+ ]
+ }
+ },
+ "logo": {
+ "light": "/logo/light.png",
+ "dark": "/logo/dark.png"
+ },
+ "navbar": {
+ "links": [
+ {
+ "label": "Examples",
+ "href": "https://github.com/rootflo/flo-ai/tree/main/flo_ai/examples"
+ }
+ ],
+ "primary": {
+ "type": "button",
+ "label": "Get Started",
+ "href": "https://github.com/rootflo/flo-ai"
+ }
+ },
+ "contextual": {
+ "options": [
+ "copy",
+ "view",
+ "chatgpt",
+ "claude",
+ "perplexity",
+ "mcp",
+ "cursor",
+ "vscode"
+ ]
+ },
+ "footer": {
+ "socials": {
+ "x": "https://x.com/rootflo",
+ "github": "https://github.com/rootflo/flo-ai",
+ "linkedin": "https://linkedin.com/company/rootflo"
+ }
+ }
+}
diff --git a/documentation/essentials/agents.mdx b/documentation/essentials/agents.mdx
new file mode 100644
index 00000000..1cdd79c7
--- /dev/null
+++ b/documentation/essentials/agents.mdx
@@ -0,0 +1,301 @@
+---
+title: 'Agents'
+description: 'Learn how to create and configure AI agents with Flo AI'
+icon: 'robot'
+---
+
+## Creating Agents
+
+Agents are the core building blocks of Flo AI. They represent AI-powered entities that can process inputs, use tools, and generate responses.
+
+### Basic Agent Creation
+
+Create a simple conversational agent:
+
+```python
+from flo_ai.builder.agent_builder import AgentBuilder
+from flo_ai.llm import OpenAI
+
+agent = (
+ AgentBuilder()
+ .with_name('Customer Support')
+ .with_prompt('You are a helpful customer support agent.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .build()
+)
+
+response = await agent.run('How can I reset my password?')
+```
+
+### Agent Configuration
+
+Configure agents with various options:
+
+```python
+agent = (
+ AgentBuilder()
+ .with_name('Data Analyst')
+ .with_prompt('You are an expert data analyst.')
+ .with_llm(OpenAI(model='gpt-4o', temperature=0.3))
+ .with_retries(3) # Retry on failure
+ .with_max_tokens(1000)
+ .build()
+)
+```
+
+## Agent Types
+
+### Conversational Agents
+
+Basic agents for chat and Q&A:
+
+```python
+conversational_agent = (
+ AgentBuilder()
+ .with_name('Chat Assistant')
+ .with_prompt('You are a friendly conversational assistant.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .build()
+)
+```
+
+### Tool-Using Agents
+
+Agents that can use external tools:
+
+```python
+from flo_ai.tool import flo_tool
+
+@flo_tool(description="Get weather information")
+async def get_weather(city: str) -> str:
+ return f"Weather in {city}: sunny, 25°C"
+
+tool_agent = (
+ AgentBuilder()
+ .with_name('Weather Assistant')
+ .with_prompt('You help users get weather information.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .with_tools([get_weather.tool])
+ .build()
+)
+```
+
+### Structured Output Agents
+
+Agents that return structured data:
+
+```python
+from pydantic import BaseModel, Field
+
+class AnalysisResult(BaseModel):
+ summary: str = Field(description="Executive summary")
+ key_findings: list = Field(description="List of key findings")
+ recommendations: list = Field(description="Actionable recommendations")
+
+structured_agent = (
+ AgentBuilder()
+ .with_name('Business Analyst')
+ .with_prompt('Analyze business data and provide insights.')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .with_output_schema(AnalysisResult)
+ .build()
+)
+```
+
+## Agent Capabilities
+
+### Variable Resolution
+
+Use dynamic variables in agent prompts:
+
+```python
+agent = (
+ AgentBuilder()
+ .with_name('Personalized Assistant')
+ .with_prompt('Hello ! You are at .')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .build()
+)
+
+# Use variables at runtime
+variables = {
+ 'user_name': 'John',
+ 'user_role': 'Data Scientist',
+ 'company': 'TechCorp'
+}
+
+response = await agent.run(
+ 'What should I focus on today?',
+ variables=variables
+)
+```
+
+### Document Processing
+
+Process PDF and text documents:
+
+```python
+from flo_ai.models.document import DocumentMessage, DocumentType
+
+# Create document message
+document = DocumentMessage(
+ document_type=DocumentType.PDF,
+ document_file_path='report.pdf'
+)
+
+# Process with agent
+response = await agent.run([document])
+```
+
+### Error Handling
+
+Built-in retry mechanisms and error recovery:
+
+```python
+robust_agent = (
+ AgentBuilder()
+ .with_name('Reliable Agent')
+ .with_prompt('You are a reliable assistant.')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .with_retries(3) # Retry up to 3 times
+ .with_timeout(30) # 30 second timeout
+ .build()
+)
+```
+
+## Best Practices
+
+### Prompt Engineering
+
+- **Be specific**: Clearly define the agent's role and capabilities
+- **Use examples**: Provide examples of expected inputs and outputs
+- **Set boundaries**: Define what the agent should and shouldn't do
+
+```python
+well_prompted_agent = (
+ AgentBuilder()
+ .with_name('Code Reviewer')
+ .with_prompt('''
+ You are an expert code reviewer. Your role is to:
+ 1. Review code for bugs, security issues, and best practices
+ 2. Suggest improvements and optimizations
+ 3. Provide constructive feedback
+
+ Always be specific about issues and provide actionable suggestions.
+ Focus on code quality, performance, and maintainability.
+ ''')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .build()
+)
+```
+
+### Model Selection
+
+Choose the right model for your use case:
+
+- **GPT-4o**: Best for complex reasoning and analysis
+- **GPT-4o-mini**: Good balance of performance and cost
+- **Claude-3.5-Sonnet**: Excellent for creative tasks
+- **Gemini**: Good for multilingual applications
+
+### Performance Optimization
+
+```python
+# Use streaming for long responses
+streaming_agent = (
+ AgentBuilder()
+ .with_name('Content Generator')
+ .with_prompt('Generate detailed content.')
+ .with_llm(OpenAI(model='gpt-4o', stream=True))
+ .build()
+)
+
+# Use caching for repeated queries
+cached_agent = (
+ AgentBuilder()
+ .with_name('Cached Agent')
+ .with_prompt('You provide consistent responses.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .with_cache(ttl=3600) # Cache for 1 hour
+ .build()
+)
+```
+
+## Agent Lifecycle
+
+### Initialization
+
+```python
+# Create agent
+agent = AgentBuilder().with_name('My Agent').build()
+
+# Initialize with configuration
+await agent.initialize()
+```
+
+### Execution
+
+```python
+# Simple execution
+response = await agent.run('Hello!')
+
+# With context
+response = await agent.run('Hello!', context={'user_id': '123'})
+
+# With variables
+response = await agent.run('Hello!', variables={'name': 'John'})
+```
+
+### Cleanup
+
+```python
+# Clean up resources
+await agent.cleanup()
+```
+
+## Advanced Features
+
+### Custom Memory
+
+```python
+from flo_ai.arium.memory import BaseMemory
+
+class CustomMemory(BaseMemory):
+ def __init__(self):
+ self.messages = []
+
+ def add(self, message):
+ self.messages.append(message)
+
+ def get(self):
+ return self.messages
+
+agent = (
+ AgentBuilder()
+ .with_name('Memory Agent')
+ .with_prompt('You remember previous conversations.')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .with_memory(CustomMemory())
+ .build()
+)
+```
+
+### Custom Event Handlers
+
+```python
+async def on_agent_start(agent, input_data):
+ print(f"Agent {agent.name} started processing")
+
+async def on_agent_complete(agent, result):
+ print(f"Agent {agent.name} completed with result: {result}")
+
+agent = (
+ AgentBuilder()
+ .with_name('Event Agent')
+ .with_prompt('You are an event-driven agent.')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .with_event_handler('start', on_agent_start)
+ .with_event_handler('complete', on_agent_complete)
+ .build()
+)
+```
diff --git a/documentation/essentials/arium.mdx b/documentation/essentials/arium.mdx
new file mode 100644
index 00000000..44388d06
--- /dev/null
+++ b/documentation/essentials/arium.mdx
@@ -0,0 +1,377 @@
+---
+title: 'Arium Workflows'
+description: 'Create complex multi-agent workflows with Arium orchestration'
+icon: 'sitemap'
+---
+
+## What is Arium?
+
+Arium is Flo AI's powerful workflow orchestration engine for creating complex multi-agent workflows. It allows you to chain agents together, implement conditional routing, and build sophisticated AI systems.
+
+## Basic Workflow Creation
+
+### Simple Agent Chain
+
+Create a linear workflow with multiple agents:
+
+```python
+from flo_ai.arium import AriumBuilder
+from flo_ai.models.agent import Agent
+from flo_ai.llm import OpenAI
+
+async def simple_chain():
+ llm = OpenAI(model='gpt-4o-mini')
+
+ # Create agents
+ analyst = Agent(
+ name='content_analyst',
+ system_prompt='Analyze the input and extract key insights.',
+ llm=llm
+ )
+
+ summarizer = Agent(
+ name='summarizer',
+ system_prompt='Create a concise summary based on the analysis.',
+ llm=llm
+ )
+
+ # Build and run workflow
+ result = await (
+ AriumBuilder()
+ .add_agents([analyst, summarizer])
+ .start_with(analyst)
+ .connect(analyst, summarizer)
+ .end_with(summarizer)
+ .build_and_run(["Analyze this complex business report..."])
+ )
+
+ return result
+```
+
+### Conditional Routing
+
+Route to different agents based on conditions:
+
+```python
+from flo_ai.arium.memory import BaseMemory
+
+def route_by_type(memory: BaseMemory) -> str:
+ """Route based on classification result"""
+ messages = memory.get()
+ last_message = str(messages[-1]) if messages else ""
+
+ if "technical" in last_message.lower():
+ return "tech_specialist"
+ else:
+ return "business_specialist"
+
+# Build workflow with conditional routing
+result = await (
+ AriumBuilder()
+ .add_agents([classifier, tech_specialist, business_specialist, final_agent])
+ .start_with(classifier)
+ .add_edge(classifier, [tech_specialist, business_specialist], route_by_type)
+ .connect(tech_specialist, final_agent)
+ .connect(business_specialist, final_agent)
+ .end_with(final_agent)
+ .build_and_run(["How can we optimize our database performance?"])
+)
+```
+
+## YAML-Based Workflows
+
+Define entire workflows in YAML for easy management:
+
+```yaml
+metadata:
+ name: "content-analysis-workflow"
+ version: "1.0.0"
+ description: "Multi-agent content analysis pipeline"
+
+arium:
+ agents:
+ - name: "analyzer"
+ role: "Content Analyst"
+ job: "Analyze the input content and extract key insights."
+ model:
+ provider: "openai"
+ name: "gpt-4o-mini"
+
+ - name: "summarizer"
+ role: "Content Summarizer"
+ job: "Create a concise summary based on the analysis."
+ model:
+ provider: "anthropic"
+ name: "claude-3-5-sonnet-20240620"
+
+ workflow:
+ start: "analyzer"
+ edges:
+ - from: "analyzer"
+ to: ["summarizer"]
+ end: ["summarizer"]
+```
+
+```python
+# Run YAML workflow
+result = await (
+ AriumBuilder()
+ .from_yaml(yaml_file='workflow.yaml')
+ .build_and_run(["Analyze this quarterly business report..."])
+)
+```
+
+## Advanced Routing
+
+### LLM-Powered Routers
+
+Use LLMs for intelligent routing decisions:
+
+```yaml
+routers:
+ - name: "content_type_router"
+ type: "smart" # Uses LLM for intelligent routing
+ routing_options:
+ technical_writer: "Technical content, documentation, tutorials"
+ creative_writer: "Creative writing, storytelling, fiction"
+ marketing_writer: "Marketing copy, sales content, campaigns"
+ model:
+ provider: "openai"
+ name: "gpt-4o-mini"
+```
+
+### ReflectionRouter
+
+For A→B→A→C feedback patterns:
+
+```yaml
+routers:
+ - name: "reflection_router"
+ type: "reflection"
+ flow_pattern: [writer, critic, writer] # A → B → A pattern
+ model:
+ provider: "openai"
+ name: "gpt-4o-mini"
+```
+
+### PlanExecuteRouter
+
+For Cursor-style plan-and-execute workflows:
+
+```yaml
+routers:
+ - name: "plan_router"
+ type: "plan_execute"
+ agents:
+ planner: "Creates detailed execution plans"
+ developer: "Implements features according to plan"
+ tester: "Tests implementations and validates functionality"
+ reviewer: "Reviews and approves completed work"
+ settings:
+ planner_agent: planner
+ executor_agent: developer
+ reviewer_agent: reviewer
+```
+
+## Workflow Patterns
+
+### Sequential Processing
+
+```python
+# A → B → C
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b, agent_c])
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .connect(agent_b, agent_c)
+ .end_with(agent_c)
+)
+```
+
+### Parallel Processing
+
+```python
+# A → [B, C] → D
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b, agent_c, agent_d])
+ .start_with(agent_a)
+ .connect(agent_a, [agent_b, agent_c])
+ .connect(agent_b, agent_d)
+ .connect(agent_c, agent_d)
+ .end_with(agent_d)
+)
+```
+
+### Fan-out/Fan-in
+
+```python
+# A → [B, C, D] → E
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b, agent_c, agent_d, agent_e])
+ .start_with(agent_a)
+ .connect(agent_a, [agent_b, agent_c, agent_d])
+ .connect(agent_b, agent_e)
+ .connect(agent_c, agent_e)
+ .connect(agent_d, agent_e)
+ .end_with(agent_e)
+)
+```
+
+## Memory Management
+
+### Shared Memory
+
+```python
+from flo_ai.arium.memory import MessageMemory
+
+# Create shared memory
+shared_memory = MessageMemory()
+
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_memory(shared_memory)
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
+
+### Custom Memory
+
+```python
+from flo_ai.arium.memory import BaseMemory
+
+class CustomMemory(BaseMemory):
+ def __init__(self):
+ self.data = {}
+
+ def add(self, key, value):
+ self.data[key] = value
+
+ def get(self, key):
+ return self.data.get(key)
+
+custom_memory = CustomMemory()
+```
+
+## Event Handling
+
+### Workflow Events
+
+```python
+async def on_workflow_start(workflow, input_data):
+ print(f"Workflow started with input: {input_data}")
+
+async def on_workflow_complete(workflow, result):
+ print(f"Workflow completed with result: {result}")
+
+async def on_agent_start(agent, input_data):
+ print(f"Agent {agent.name} started")
+
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_event_handler('workflow_start', on_workflow_start)
+ .with_event_handler('workflow_complete', on_workflow_complete)
+ .with_event_handler('agent_start', on_agent_start)
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
+
+## Error Handling
+
+### Retry Logic
+
+```python
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_retries(3) # Retry failed agents up to 3 times
+ .with_timeout(60) # 60 second timeout
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
+
+### Error Recovery
+
+```python
+async def error_handler(agent, error):
+ print(f"Agent {agent.name} failed: {error}")
+ # Implement custom error recovery logic
+ return "fallback_response"
+
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_error_handler(error_handler)
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
+
+## Performance Optimization
+
+### Parallel Execution
+
+```python
+# Execute multiple agents in parallel
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b, agent_c])
+ .start_with(agent_a)
+ .connect_parallel(agent_a, [agent_b, agent_c])
+ .end_with([agent_b, agent_c])
+)
+```
+
+### Caching
+
+```python
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_cache(ttl=3600) # Cache results for 1 hour
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
+
+## Best Practices
+
+### Workflow Design
+
+1. **Keep it simple**: Start with linear workflows before adding complexity
+2. **Use meaningful names**: Name agents and workflows descriptively
+3. **Handle errors**: Always implement error handling and recovery
+4. **Test thoroughly**: Test workflows with various inputs
+
+### Performance Tips
+
+1. **Use appropriate models**: Choose models based on task complexity
+2. **Implement caching**: Cache expensive operations
+3. **Optimize routing**: Use efficient routing logic
+4. **Monitor performance**: Use telemetry to track workflow performance
+
+### Debugging
+
+```python
+# Enable debug mode
+workflow = (
+ AriumBuilder()
+ .add_agents([agent_a, agent_b])
+ .with_debug(True) # Enable debug logging
+ .start_with(agent_a)
+ .connect(agent_a, agent_b)
+ .end_with(agent_b)
+)
+```
diff --git a/documentation/essentials/code.mdx b/documentation/essentials/code.mdx
new file mode 100644
index 00000000..503c253c
--- /dev/null
+++ b/documentation/essentials/code.mdx
@@ -0,0 +1,182 @@
+---
+title: 'Code Examples'
+description: 'Flo AI code examples and syntax highlighting'
+icon: 'code'
+---
+
+## Basic Agent Creation
+
+Here's how to create a simple conversational agent with Flo AI:
+
+```python Simple Agent
+import asyncio
+from flo_ai.builder.agent_builder import AgentBuilder
+from flo_ai.llm import OpenAI
+
+async def main():
+ agent = (
+ AgentBuilder()
+ .with_name('Math Tutor')
+ .with_prompt('You are a helpful math tutor.')
+ .with_llm(OpenAI(model='gpt-4o-mini'))
+ .build()
+ )
+
+ response = await agent.run('What is the formula for the area of a circle?')
+ print(f'Response: {response}')
+
+asyncio.run(main())
+```
+
+## Tool Integration
+
+Create agents that can use custom tools:
+
+```python Tool-Using Agent
+import asyncio
+from flo_ai.builder.agent_builder import AgentBuilder
+from flo_ai.tool import flo_tool
+from flo_ai.llm import Anthropic
+
+@flo_tool(description="Perform mathematical calculations")
+async def calculate(operation: str, x: float, y: float) -> float:
+ """Calculate mathematical operations between two numbers."""
+ operations = {
+ 'add': lambda: x + y,
+ 'subtract': lambda: x - y,
+ 'multiply': lambda: x * y,
+ 'divide': lambda: x / y if y != 0 else 0,
+ }
+ return operations.get(operation, lambda: 0)()
+
+async def main():
+ agent = (
+ AgentBuilder()
+ .with_name('Calculator Assistant')
+ .with_prompt('You are a math assistant that can perform calculations.')
+ .with_llm(Anthropic(model='claude-3-5-sonnet-20240620'))
+ .with_tools([calculate.tool])
+ .build()
+ )
+
+ response = await agent.run('Calculate 5 plus 3')
+ print(f'Response: {response}')
+
+asyncio.run(main())
+```
+
+## Structured Outputs
+
+Use Pydantic models for structured agent responses:
+
+```python Structured Output
+import asyncio
+from pydantic import BaseModel, Field
+from flo_ai.builder.agent_builder import AgentBuilder
+from flo_ai.llm import OpenAI
+
+class MathSolution(BaseModel):
+ solution: str = Field(description="Step-by-step solution")
+ answer: str = Field(description="Final answer")
+ confidence: float = Field(description="Confidence level (0-1)")
+
+async def main():
+ agent = (
+ AgentBuilder()
+ .with_name('Math Solver')
+ .with_llm(OpenAI(model='gpt-4o'))
+ .with_output_schema(MathSolution)
+ .build()
+ )
+
+ response = await agent.run('Solve: 2x + 5 = 15')
+ print(f'Structured Response: {response}')
+
+asyncio.run(main())
+```
+
+## Multi-Agent Workflows
+
+Create complex workflows with multiple agents:
+
+```python Multi-Agent Workflow
+import asyncio
+from flo_ai.arium import AriumBuilder
+from flo_ai.models.agent import Agent
+from flo_ai.llm import OpenAI
+
+async def content_analysis_workflow():
+ llm = OpenAI(model='gpt-4o-mini')
+
+ # Create specialized agents
+ analyst = Agent(
+ name='content_analyst',
+ system_prompt='Analyze the input and extract key insights.',
+ llm=llm
+ )
+
+ summarizer = Agent(
+ name='summarizer',
+ system_prompt='Create a concise summary based on the analysis.',
+ llm=llm
+ )
+
+ # Build and run workflow
+ result = await (
+ AriumBuilder()
+ .add_agents([analyst, summarizer])
+ .start_with(analyst)
+ .connect(analyst, summarizer)
+ .end_with(summarizer)
+ .build_and_run(["Analyze this complex business report..."])
+ )
+
+ return result
+
+asyncio.run(content_analysis_workflow())
+```
+
+## YAML Configuration
+
+Define entire workflows in YAML:
+
+```yaml workflow.yaml
+metadata:
+ name: "content-analysis-workflow"
+ version: "1.0.0"
+ description: "Multi-agent content analysis pipeline"
+
+arium:
+ agents:
+ - name: "analyzer"
+ role: "Content Analyst"
+ job: "Analyze the input content and extract key insights."
+ model:
+ provider: "openai"
+ name: "gpt-4o-mini"
+
+ - name: "summarizer"
+ role: "Content Summarizer"
+ job: "Create a concise summary based on the analysis."
+ model:
+ provider: "anthropic"
+ name: "claude-3-5-sonnet-20240620"
+
+ workflow:
+ start: "analyzer"
+ edges:
+ - from: "analyzer"
+ to: ["summarizer"]
+ end: ["summarizer"]
+```
+
+```python Run YAML Workflow
+from flo_ai.arium import AriumBuilder
+
+# Run YAML workflow
+result = await (
+ AriumBuilder()
+ .from_yaml(yaml_file='workflow.yaml')
+ .build_and_run(["Analyze this quarterly business report..."])
+)
+```
diff --git a/documentation/essentials/images.mdx b/documentation/essentials/images.mdx
new file mode 100644
index 00000000..1144eb2c
--- /dev/null
+++ b/documentation/essentials/images.mdx
@@ -0,0 +1,59 @@
+---
+title: 'Images and embeds'
+description: 'Add image, video, and other HTML elements'
+icon: 'image'
+---
+
+
+
+## Image
+
+### Using Markdown
+
+The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
+
+```md
+
+```
+
+Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
+
+### Using embeds
+
+To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
+
+```html
+
+```
+
+## Embeds and HTML elements
+
+
+
+
+
+
+
+Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
+
+
+
+### iFrames
+
+Loads another HTML page within the document. Most commonly used for embedding videos.
+
+```html
+
+```
diff --git a/documentation/essentials/llm-providers.mdx b/documentation/essentials/llm-providers.mdx
new file mode 100644
index 00000000..f29eac2b
--- /dev/null
+++ b/documentation/essentials/llm-providers.mdx
@@ -0,0 +1,439 @@
+---
+title: 'LLM Providers'
+description: 'Supported language model providers and configuration'
+icon: 'brain'
+---
+
+## Supported Providers
+
+Flo AI supports multiple LLM providers with consistent interfaces, allowing you to easily switch between different models and providers.
+
+## OpenAI
+
+### Basic Configuration
+
+```python
+from flo_ai.llm import OpenAI
+
+# Basic OpenAI configuration
+llm = OpenAI(
+ model='gpt-4o',
+ temperature=0.7,
+ max_tokens=1000
+)
+
+# With additional parameters
+llm = OpenAI(
+ model='gpt-4o-mini',
+ temperature=0.3,
+ max_tokens=500,
+ timeout=30,
+ api_key='your-api-key' # Optional, can use environment variable
+)
+```
+
+### Available Models
+
+```python
+# GPT-4 models
+gpt4 = OpenAI(model='gpt-4o')
+gpt4_mini = OpenAI(model='gpt-4o-mini')
+
+# GPT-3.5 models
+gpt35 = OpenAI(model='gpt-3.5-turbo')
+gpt35_16k = OpenAI(model='gpt-3.5-turbo-16k')
+```
+
+### Streaming Support
+
+```python
+# Enable streaming for real-time responses
+streaming_llm = OpenAI(
+ model='gpt-4o',
+ stream=True
+)
+
+# Use with agent
+agent = (
+ AgentBuilder()
+ .with_name('Streaming Agent')
+ .with_prompt('You are a helpful assistant.')
+ .with_llm(streaming_llm)
+ .build()
+)
+```
+
+## Anthropic Claude
+
+### Basic Configuration
+
+```python
+from flo_ai.llm import Anthropic
+
+# Basic Claude configuration
+claude = Anthropic(
+ model='claude-3-5-sonnet-20240620',
+ temperature=0.7,
+ max_tokens=1000
+)
+
+# With additional parameters
+claude = Anthropic(
+ model='claude-3-5-haiku-20241022',
+ temperature=0.3,
+ max_tokens=500,
+ timeout=30
+)
+```
+
+### Available Models
+
+```python
+# Claude 3.5 models
+claude_sonnet = Anthropic(model='claude-3-5-sonnet-20240620')
+claude_haiku = Anthropic(model='claude-3-5-haiku-20241022')
+
+# Claude 3 models
+claude_3_sonnet = Anthropic(model='claude-3-sonnet-20240229')
+claude_3_haiku = Anthropic(model='claude-3-haiku-20240307')
+```
+
+## Google Gemini
+
+### Basic Configuration
+
+```python
+from flo_ai.llm import Gemini
+
+# Basic Gemini configuration
+gemini = Gemini(
+ model='gemini-2.5-flash',
+ temperature=0.7,
+ max_tokens=1000
+)
+
+# With additional parameters
+gemini = Gemini(
+ model='gemini-2.5-pro',
+ temperature=0.3,
+ max_tokens=500,
+ timeout=30
+)
+```
+
+### Available Models
+
+```python
+# Gemini 2.5 models
+gemini_flash = Gemini(model='gemini-2.5-flash')
+gemini_pro = Gemini(model='gemini-2.5-pro')
+
+# Gemini 1.5 models
+gemini_15_flash = Gemini(model='gemini-1.5-flash')
+gemini_15_pro = Gemini(model='gemini-1.5-pro')
+```
+
+## Google Vertex AI
+
+### Configuration
+
+```python
+from flo_ai.llm import VertexAI
+
+# Vertex AI configuration
+vertex_llm = VertexAI(
+ model='gemini-2.5-flash',
+ project='your-project-id',
+ location='us-central1',
+ temperature=0.7
+)
+
+# With service account
+vertex_llm = VertexAI(
+ model='gemini-2.5-pro',
+ project='your-project-id',
+ credentials_path='path/to/service-account.json',
+ location='us-central1'
+)
+```
+
+## Ollama (Local)
+
+### Configuration
+
+```python
+from flo_ai.llm import OllamaLLM
+
+# Local Ollama configuration
+ollama = OllamaLLM(
+ model='llama2',
+ base_url='http://localhost:11434',
+ temperature=0.7
+)
+
+# With custom parameters
+ollama = OllamaLLM(
+ model='codellama',
+ base_url='http://localhost:11434',
+ temperature=0.3,
+ timeout=60
+)
+```
+
+### Popular Local Models
+
+```python
+# Code generation
+codellama = OllamaLLM(model='codellama')
+
+# General purpose
+llama2 = OllamaLLM(model='llama2')
+llama3 = OllamaLLM(model='llama3')
+
+# Specialized models
+mistral = OllamaLLM(model='mistral')
+phi = OllamaLLM(model='phi')
+```
+
+## Provider Comparison
+
+| Provider | Best For | Cost | Speed | Quality |
+|----------|----------|------|-------|---------|
+| GPT-4o | Complex reasoning | High | Medium | Excellent |
+| GPT-4o-mini | Balanced tasks | Medium | Fast | Good |
+| Claude-3.5-Sonnet | Creative writing | High | Medium | Excellent |
+| Claude-3.5-Haiku | Simple tasks | Low | Fast | Good |
+| Gemini-2.5-Pro | Multimodal tasks | Medium | Medium | Good |
+| Gemini-2.5-Flash | Fast responses | Low | Very Fast | Good |
+| Ollama | Privacy/Offline | Free | Variable | Variable |
+
+## Model Selection Guide
+
+### For Different Use Cases
+
+```python
+# Code generation and analysis
+code_llm = OpenAI(model='gpt-4o', temperature=0.1)
+
+# Creative writing
+creative_llm = Anthropic(model='claude-3-5-sonnet-20240620', temperature=0.8)
+
+# Data analysis
+analysis_llm = OpenAI(model='gpt-4o', temperature=0.2)
+
+# Customer support
+support_llm = OpenAI(model='gpt-4o-mini', temperature=0.3)
+
+# Fast responses
+fast_llm = Gemini(model='gemini-2.5-flash', temperature=0.3)
+```
+
+### Performance Optimization
+
+```python
+# For high-volume, simple tasks
+efficient_llm = OpenAI(
+ model='gpt-4o-mini',
+ temperature=0.1,
+ max_tokens=200
+)
+
+# For complex reasoning
+powerful_llm = OpenAI(
+ model='gpt-4o',
+ temperature=0.2,
+ max_tokens=2000
+)
+```
+
+## Environment Configuration
+
+### API Keys
+
+```bash
+# OpenAI
+export OPENAI_API_KEY="your-openai-key"
+
+# Anthropic
+export ANTHROPIC_API_KEY="your-anthropic-key"
+
+# Google
+export GOOGLE_API_KEY="your-google-key"
+
+# Vertex AI
+export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+### Python Configuration
+
+```python
+import os
+from flo_ai.llm import OpenAI
+
+# Configure with environment variables
+llm = OpenAI(
+ model='gpt-4o',
+ api_key=os.getenv('OPENAI_API_KEY')
+)
+
+# Or use default environment variable names
+llm = OpenAI(model='gpt-4o') # Automatically uses OPENAI_API_KEY
+```
+
+## Advanced Configuration
+
+### Custom Headers
+
+```python
+# Add custom headers for API requests
+llm = OpenAI(
+ model='gpt-4o',
+ headers={
+ 'X-Custom-Header': 'value',
+ 'User-Agent': 'MyApp/1.0'
+ }
+)
+```
+
+### Retry Configuration
+
+```python
+# Configure retry behavior
+llm = OpenAI(
+ model='gpt-4o',
+ max_retries=3,
+ retry_delay=1.0,
+ timeout=30
+)
+```
+
+### Rate Limiting
+
+```python
+# Configure rate limiting
+llm = OpenAI(
+ model='gpt-4o',
+ requests_per_minute=60,
+ tokens_per_minute=150000
+)
+```
+
+## Model Switching
+
+### Dynamic Model Selection
+
+```python
+def get_llm_for_task(task_type: str):
+ if task_type == 'creative':
+ return Anthropic(model='claude-3-5-sonnet-20240620')
+ elif task_type == 'analytical':
+ return OpenAI(model='gpt-4o')
+ elif task_type == 'fast':
+ return Gemini(model='gemini-2.5-flash')
+ else:
+ return OpenAI(model='gpt-4o-mini')
+
+# Use in agent
+task_type = 'creative'
+llm = get_llm_for_task(task_type)
+agent = AgentBuilder().with_llm(llm).build()
+```
+
+### A/B Testing
+
+```python
+# Test different models
+models = [
+ OpenAI(model='gpt-4o'),
+ Anthropic(model='claude-3-5-sonnet-20240620'),
+ Gemini(model='gemini-2.5-pro')
+]
+
+for i, llm in enumerate(models):
+ agent = AgentBuilder().with_llm(llm).build()
+ response = await agent.run('Test prompt')
+ print(f"Model {i+1}: {response}")
+```
+
+## Troubleshooting
+
+### Common Issues
+
+
+
+
+ Ensure your API keys are correctly set:
+
+ ```bash
+ echo $OPENAI_API_KEY
+ echo $ANTHROPIC_API_KEY
+ echo $GOOGLE_API_KEY
+ ```
+
+
+
+
+
+ If you hit rate limits, implement backoff:
+
+ ```python
+ import time
+ import random
+
+ async def with_backoff(func, max_retries=3):
+ for attempt in range(max_retries):
+ try:
+ return await func()
+ except RateLimitError:
+ wait_time = (2 ** attempt) + random.uniform(0, 1)
+ time.sleep(wait_time)
+ raise Exception("Max retries exceeded")
+ ```
+
+
+
+
+
+ Check that the model name is correct and available in your region:
+
+ ```python
+ # List available models
+ from flo_ai.llm import OpenAI
+
+ # This will raise an error if model is not available
+ try:
+ llm = OpenAI(model='gpt-4o')
+ print("Model is available")
+ except Exception as e:
+ print(f"Model error: {e}")
+ ```
+
+
+
+
+## Best Practices
+
+### Model Selection
+
+1. **Start with GPT-4o-mini** for most tasks
+2. **Use GPT-4o** for complex reasoning
+3. **Try Claude** for creative tasks
+4. **Use Gemini** for multimodal or fast responses
+5. **Use Ollama** for privacy-sensitive applications
+
+### Cost Optimization
+
+1. **Use appropriate models** for task complexity
+2. **Implement caching** for repeated queries
+3. **Set reasonable limits** on max_tokens
+4. **Monitor usage** and costs
+5. **Use streaming** for long responses
+
+### Performance Tips
+
+1. **Batch requests** when possible
+2. **Use connection pooling** for high-volume applications
+3. **Implement retry logic** with exponential backoff
+4. **Cache responses** for identical inputs
+5. **Monitor latency** and optimize accordingly
diff --git a/documentation/essentials/markdown.mdx b/documentation/essentials/markdown.mdx
new file mode 100644
index 00000000..a45c1d56
--- /dev/null
+++ b/documentation/essentials/markdown.mdx
@@ -0,0 +1,88 @@
+---
+title: 'Markdown syntax'
+description: 'Text, title, and styling in standard markdown'
+icon: 'text-size'
+---
+
+## Titles
+
+Best used for section headers.
+
+```md
+## Titles
+```
+
+### Subtitles
+
+Best used for subsection headers.
+
+```md
+### Subtitles
+```
+
+
+
+Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
+
+
+
+## Text formatting
+
+We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
+
+| Style | How to write it | Result |
+| ------------- | ----------------- | --------------- |
+| Bold | `**bold**` | **bold** |
+| Italic | `_italic_` | _italic_ |
+| Strikethrough | `~strikethrough~` | ~strikethrough~ |
+
+You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
+
+You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
+
+| Text Size | How to write it | Result |
+| ----------- | ------------------------ | ---------------------- |
+| Superscript | `superscript` | superscript |
+| Subscript | `subscript` | subscript |
+
+## Linking to pages
+
+You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
+
+Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
+
+Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
+
+## Blockquotes
+
+### Singleline
+
+To create a blockquote, add a `>` in front of a paragraph.
+
+> Dorothy followed her through many of the beautiful rooms in her castle.
+
+```md
+> Dorothy followed her through many of the beautiful rooms in her castle.
+```
+
+### Multiline
+
+> Dorothy followed her through many of the beautiful rooms in her castle.
+>
+> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+
+```md
+> Dorothy followed her through many of the beautiful rooms in her castle.
+>
+> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+```
+
+### LaTeX
+
+Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
+
+8 x (vk x H1 - H2) = (0,1)
+
+```md
+8 x (vk x H1 - H2) = (0,1)
+```
diff --git a/documentation/essentials/navigation.mdx b/documentation/essentials/navigation.mdx
new file mode 100644
index 00000000..60adeff2
--- /dev/null
+++ b/documentation/essentials/navigation.mdx
@@ -0,0 +1,87 @@
+---
+title: 'Navigation'
+description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
+icon: 'map'
+---
+
+The navigation menu is the list of links on every website.
+
+You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
+
+## Navigation syntax
+
+Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
+
+
+
+```json Regular Navigation
+"navigation": {
+ "tabs": [
+ {
+ "tab": "Docs",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": ["quickstart"]
+ }
+ ]
+ }
+ ]
+}
+```
+
+```json Nested Navigation
+"navigation": {
+ "tabs": [
+ {
+ "tab": "Docs",
+ "groups": [
+ {
+ "group": "Getting Started",
+ "pages": [
+ "quickstart",
+ {
+ "group": "Nested Reference Pages",
+ "pages": ["nested-reference-page"]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+
+
+## Folders
+
+Simply put your MDX files in folders and update the paths in `docs.json`.
+
+For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
+
+
+
+You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
+
+
+
+```json Navigation With Folder
+"navigation": {
+ "tabs": [
+ {
+ "tab": "Docs",
+ "groups": [
+ {
+ "group": "Group Name",
+ "pages": ["your-folder/your-page"]
+ }
+ ]
+ }
+ ]
+}
+```
+
+## Hidden pages
+
+MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
diff --git a/documentation/essentials/reusable-snippets.mdx b/documentation/essentials/reusable-snippets.mdx
new file mode 100644
index 00000000..376e27bd
--- /dev/null
+++ b/documentation/essentials/reusable-snippets.mdx
@@ -0,0 +1,110 @@
+---
+title: "Reusable snippets"
+description: "Reusable, custom snippets to keep content in sync"
+icon: "recycle"
+---
+
+import SnippetIntro from '/snippets/snippet-intro.mdx';
+
+
+
+## Creating a custom snippet
+
+**Pre-condition**: You must create your snippet file in the `snippets` directory.
+
+
+ Any page in the `snippets` directory will be treated as a snippet and will not
+ be rendered into a standalone page. If you want to create a standalone page
+ from the snippet, import the snippet into another file and call it as a
+ component.
+
+
+### Default export
+
+1. Add content to your snippet file that you want to re-use across multiple
+ locations. Optionally, you can add variables that can be filled in via props
+ when you import the snippet.
+
+```mdx snippets/my-snippet.mdx
+Hello world! This is my content I want to reuse across pages. My keyword of the
+day is {word}.
+```
+
+
+ The content that you want to reuse must be inside the `snippets` directory in
+ order for the import to work.
+
+
+2. Import the snippet into your destination file.
+
+```mdx destination-file.mdx
+---
+title: My title
+description: My Description
+---
+
+import MySnippet from '/snippets/path/to/my-snippet.mdx';
+
+## Header
+
+Lorem impsum dolor sit amet.
+
+
+```
+
+### Reusable variables
+
+1. Export a variable from your snippet file:
+
+```mdx snippets/path/to/custom-variables.mdx
+export const myName = 'my name';
+
+export const myObject = { fruit: 'strawberries' };
+```
+
+2. Import the snippet from your destination file and use the variable:
+
+```mdx destination-file.mdx
+---
+title: My title
+description: My Description
+---
+
+import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
+
+Hello, my name is {myName} and I like {myObject.fruit}.
+```
+
+### Reusable components
+
+1. Inside your snippet file, create a component that takes in props by exporting
+ your component in the form of an arrow function.
+
+```mdx snippets/custom-component.mdx
+export const MyComponent = ({ title }) => (
+
+
{title}
+
... snippet content ...
+