- How do I install and set up knobik/sql-agent in a Laravel 11 project?
- Run `composer require knobik/sql-agent` and execute `php artisan sql-agent:install`. Configure your LLM provider (e.g., OpenAI, Ollama) in `.env` by setting `SQL_AGENT_LLM_PROVIDER` and `SQL_AGENT_LLM_MODEL`. The package includes a built-in chat UI for quick testing, accessible via Blade or Livewire.
- Which Laravel versions and PHP versions does this package support?
- The package is officially tested with Laravel 10 and 11. Check the `composer.json` for PHP version requirements (typically 8.1+). Always verify compatibility with your Laravel version before installation, as the package is still in beta.
- Can I use this agent with PostgreSQL-specific features like JSONB or window functions?
- Yes, the agent leverages Laravel’s Query Builder, which supports PostgreSQL features. However, complex PostgreSQL-specific queries may require manual tuning or additional context in the knowledge base to ensure accurate SQL generation.
- How does the self-learning feature work, and what happens if the agent makes a mistake?
- The agent logs corrections via a feedback loop—users flag incorrect queries through the UI or API, and these corrections are stored for future improvements. The system dynamically refines its responses, reducing errors over time. For critical applications, consider validating corrections manually before deployment.
- What LLM providers are supported, and how do I choose the best one for my use case?
- Supported providers include OpenAI, Anthropic, Ollama, Gemini, Mistral, and XAI. For cost-sensitive projects, Ollama (local) or cheaper models like GPT-3.5 may suffice. For accuracy, use GPT-4 or equivalent. Always monitor LLM costs and latency, especially in production.
- Is there a way to cache responses to reduce LLM API calls and costs?
- Yes, the package supports caching frequent queries. Implement Redis or another cache driver for Laravel to store responses. Configure TTL (time-to-live) based on data volatility. Async processing or local caching can further mitigate LLM latency.
- How do I handle rate limits or API outages from the LLM provider?
- Configure fallback mechanisms like exponential backoff or queue delayed jobs for retries. For critical systems, implement a local cache or use a secondary LLM provider. Monitor API status and set alerts for downtime using Laravel’s queue monitoring or external tools.
- Can I integrate this agent into an existing frontend (React/Vue) instead of using the built-in chat UI?
- Yes, expose the agent as an API endpoint (e.g., `/api/sql-agent`) by creating a custom route and controller. Return JSON responses with `answer`, `sql`, and `results` for frontend consumption. The agent’s core logic remains agnostic to the UI layer.
- What security measures are in place to prevent SQL injection or destructive queries?
- The agent includes configurable guardrails to block unsafe operations (e.g., `DROP TABLE`, `UPDATE` without conditions). Validate queries against your schema and business rules. For high-security environments, review the `knowledge/` directory for custom restrictions.
- How do I test the agent thoroughly before deploying to production?
- Start with non-critical queries in staging, then expand to complex use cases. Test edge cases like ambiguous queries, joins across tables, and edge-case data (NULLs, empty results). Use Laravel’s testing tools to mock LLM responses and validate SQL output against expected results.