Name: Botovis
Author: Botovis

After publishing the config file with php artisan vendor:publish --tag=botovis-config, you'll find all settings in config/botovis.php. This page covers every option in detail.

Mode

Botovis supports two operating modes:

'mode' => env('BOTOVIS_MODE', 'agent'),

Mode	Description
`agent`	Default. Uses the ReAct agent loop with tool calling. The AI reasons step-by-step, calls tools, observes results, and iterates until it has a complete answer. Supports multi-step queries.
`simple`	Uses intent classification to map queries directly to predefined actions. Faster but less flexible — suitable for simple CRUD operations only.

Locale

'locale' => env('BOTOVIS_LOCALE', 'en'),

Sets the language for system prompts and the widget UI. Supported values: en (English), tr (Turkish).

The agent uses a "generate stopping" mechanism to ensure it always produces an answer. At ≤3 steps remaining, a warning is injected. At the last step, tools are removed entirely, forcing a text response.

Model Whitelist

The models array maps Eloquent model classes to their allowed CRUD actions:

'models' => [
    \App\Models\User::class    => ['read'],
    \App\Models\Product::class => ['create', 'read', 'update', 'delete'],
    \App\Models\Order::class   => ['create', 'read', 'update'],
],

This is the most important security setting. Only models listed here are visible to the AI, and each model is restricted to the specified actions.

Models not in the list are completely invisible
Relationships to unlisted models are excluded
The botovis:discover command shows what the AI can see
Use botovis:models to interactively select models and generate this config

Per-Model Permissions

The actions array controls what the AI can do with each model. For example, ['read'] means the AI can only query this table — it cannot create, update, or delete records.

LLM Configuration

Botovis supports three LLM drivers out of the box:

'llm' => [
    'driver' => env('BOTOVIS_LLM_DRIVER', 'openai'),

    'openai' => [
        'api_key'  => env('BOTOVIS_OPENAI_API_KEY'),
        'model'    => env('BOTOVIS_OPENAI_MODEL', 'gpt-4o'),
        'base_url' => env('BOTOVIS_OPENAI_BASE_URL', 'https://api.openai.com/v1'),
    ],

    'anthropic' => [
        'api_key' => env('BOTOVIS_ANTHROPIC_API_KEY'),
        'model'   => env('BOTOVIS_ANTHROPIC_MODEL', 'claude-sonnet-4-20250514'),
    ],

    'ollama' => [
        'model'    => env('BOTOVIS_OLLAMA_MODEL', 'llama3'),
        'base_url' => env('BOTOVIS_OLLAMA_BASE_URL', 'http://localhost:11434'),
    ],
],

Driver Comparison

Feature	OpenAI	Anthropic	Ollama
Native tool calling	✅	✅	✅
Streaming	✅	✅	✅
Parallel tool calls	✅	✅	⚠️ Model-dependent
Custom endpoint URL	✅	❌	✅
Local / Self-hosted	❌	❌	✅

OpenAI-compatible APIs

The OpenAI driver supports any API that follows the OpenAI format. Set BOTOVIS_OPENAI_BASE_URL to use providers like Azure OpenAI, Together AI, Groq, or any OpenAI-compatible endpoint.

Recommended Models

For best results with database queries and tool calling:

OpenAI: gpt-4o, gpt-4o-mini
Anthropic: claude-sonnet-4-20250514, claude-3-5-haiku-20241022
Ollama: llama3, qwen2.5 (models with tool calling support)

Security Configuration

'security' => [
    'guard'                => 'web',
    'require_auth'         => true,
    'require_confirmation' => ['create', 'update', 'delete'],
    'use_gates'            => false,
    'roles' => [
        '*' => [
            '*' => ['create', 'read', 'update', 'delete'],
        ],
    ],
    'role_resolver'  => 'attribute',
    'role_attribute' => 'role',
    'role_method'    => 'getRole',
],

Option	Default	Description
`guard`	`'web'`	The Laravel authentication guard to use.
`require_auth`	`true`	Whether authentication is required. When `false`, unauthenticated users can access the API.
`require_confirmation`	`['create', 'update', 'delete']`	Which action types require user confirmation before execution.
`use_gates`	`false`	When `true`, uses Laravel Gates for table/action authorization (e.g., `botovis.orders.read`).
`role_resolver`	`'attribute'`	How to determine the user's role: `attribute`, `method`, `spatie`, or `callback`.
`role_attribute`	`'role'`	When `role_resolver` is `attribute`, reads this field from the user model (`$user->role`).
`role_method`	`'getRole'`	When `role_resolver` is `method`, calls this method on the user model (`$user->getRole()`).

See the Security page for detailed documentation on role resolvers, permission configuration, and advanced authorization.

Route Configuration

'route' => [
    'prefix'     => 'botovis',
    'middleware'  => ['web'],
],

Option	Default	Description
`prefix`	`botovis`	URL prefix for all Botovis API endpoints. All routes will be under `/{prefix}/`.
`middleware`	`['web']`	Middleware applied to all Botovis routes. The `web` middleware provides session/CSRF support. Add `'auth'` if you want to enforce authentication at the middleware level.

Authentication

The config default is ['web'] only. Botovis handles authentication internally via the require_auth security setting. If you prefer middleware-level auth, add 'auth' to the array: ['web', 'auth'].

The registered routes are:

Method	Path	Description
POST	`/{prefix}/chat`	Send a message (non-streaming)
POST	`/{prefix}/stream`	Send a message (SSE streaming)
POST	`/{prefix}/confirm`	Confirm a write operation
POST	`/{prefix}/stream-confirm`	Confirm with streaming
POST	`/{prefix}/reject`	Reject a write operation
POST	`/{prefix}/reset`	Reset conversation state
GET	`/{prefix}/schema`	Get visible database schema
GET	`/{prefix}/status`	Health check
GET	`/{prefix}/conversations`	List saved conversations
POST	`/{prefix}/conversations`	Save current conversation
GET	`/{prefix}/conversations/{id}`	Load a conversation
DELETE	`/{prefix}/conversations/{id}`	Delete a conversation
PATCH	`/{prefix}/conversations/{id}/title`	Update conversation title

Conversation Configuration

'conversations' => [
    'enabled'          => true,
    'driver'           => env('BOTOVIS_CONVERSATION_DRIVER', 'database'),
    'auto_title'       => true,
    'context_messages' => 10,
    'max_per_user'     => 0,
],

Option	Default	Description
`enabled`	`true`	Enable the conversation history feature. When disabled, each page load starts fresh.
`driver`	`database`	Storage backend: `database` (persistent, uses Eloquent) or `session` (temporary, per-session).
`auto_title`	`true`	Automatically generate conversation titles from the first message.
`context_messages`	`10`	Number of recent messages to include as context when sending a new message to the LLM.
`max_per_user`	`0`	Maximum number of saved conversations per user. `0` means unlimited.

Full Environment Variable Reference

Here's every environment variable Botovis reads:

# Core
BOTOVIS_MODE=agent
BOTOVIS_LOCALE=en

# Agent
BOTOVIS_AGENT_MAX_STEPS=10
BOTOVIS_AGENT_SHOW_STEPS=false
BOTOVIS_AGENT_STREAMING=true

# OpenAI Driver
BOTOVIS_LLM_DRIVER=openai
BOTOVIS_OPENAI_API_KEY=
BOTOVIS_OPENAI_MODEL=gpt-4o
BOTOVIS_OPENAI_BASE_URL=https://api.openai.com/v1

# Anthropic Driver
BOTOVIS_ANTHROPIC_API_KEY=
BOTOVIS_ANTHROPIC_MODEL=claude-sonnet-4-20250514

# Ollama Driver
BOTOVIS_OLLAMA_MODEL=llama3
BOTOVIS_OLLAMA_BASE_URL=http://localhost:11434

# Conversations
BOTOVIS_CONVERSATION_DRIVER=database

Configuration