https://github.com/iamgerwin/nova-ai-context-aware-input
AI-assisted Nova field that seamlessly improves text with context
https://github.com/iamgerwin/nova-ai-context-aware-input
Last synced: 3 months ago
JSON representation
AI-assisted Nova field that seamlessly improves text with context
- Host: GitHub
- URL: https://github.com/iamgerwin/nova-ai-context-aware-input
- Owner: iamgerwin
- License: mit
- Created: 2025-11-03T18:21:25.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-11-03T19:22:29.000Z (5 months ago)
- Last Synced: 2026-01-11T15:19:03.120Z (3 months ago)
- Language: PHP
- Size: 567 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# Nova AI Context-Aware Input
[](https://packagist.org/packages/iamgerwin/nova-ai-context-aware-input)
[](https://packagist.org/packages/iamgerwin/nova-ai-context-aware-input)
[](https://packagist.org/packages/iamgerwin/nova-ai-context-aware-input)
A Laravel Nova field that brings the power of AI to your admin panel, enhancing text input with intelligent, context-aware suggestions. Seamlessly integrates with Nova's workflow while providing real-time text improvements powered by leading AI providers.
Think of it as having a professional editor looking over your shoulder, understanding the context of your entire form, and offering thoughtful improvements—without disrupting your natural writing flow.
## Features
### Core Capabilities
- **Multiple AI Providers**: OpenAI, Anthropic Claude, DeepSeek, and Azure OpenAI support
- **Context-Aware Intelligence**: Leverages form data, user information, and resource context for relevant suggestions
- **Real-Time Suggestions**: Choose from blur, idle, or manual trigger modes
- **Visual Diff Mode**: See exactly what changed with highlighted additions and deletions
- **Suggestion History**: Navigate through previous AI suggestions with undo/redo support
- **Flexible Styling**: Six built-in writing styles (professional, formal, friendly, succinct, marketing, technical)
### Performance & Security
- **Intelligent Caching**: Reduces API costs by caching similar improvements
- **Rate Limiting**: Configurable per-user or global rate limits
- **PII Detection**: Built-in detection to prevent sensitive data from being sent to AI providers
- **Input Validation**: Maximum length enforcement and content filtering
- **Fallback Support**: Automatic failover to backup providers
### Developer Experience
- **Zero Configuration**: Works out of the box with sensible defaults
- **Highly Customizable**: Fine-tune every aspect through configuration or field methods
- **Event System**: Hook into `TextImproved` and `SuggestionDiscarded` events
- **Comprehensive Logging**: Track usage, errors, and performance metrics
- **Type-Safe**: Full PHP 8.2+ type declarations
## Requirements
- PHP 8.2+ or 8.3+
- Laravel 10.x, 11.x, or 12.x
- Laravel Nova 4.x or 5.x
- At least one AI provider API key (OpenAI, Anthropic, DeepSeek, or Azure OpenAI)
## Installation
Install the package via Composer:
```bash
composer require iamgerwin/nova-ai-context-aware-input
```
Publish the configuration file:
```bash
php artisan vendor:publish --tag="nova-ai-context-aware-input-config"
```
Build the Nova assets:
```bash
cd vendor/iamgerwin/nova-ai-context-aware-input
npm install && npm run build
```
Or if you prefer using the root directory:
```bash
php artisan nova:publish
```
## Quick Start
### 1. Configure Your AI Provider
Add your API key to your `.env` file:
```env
# Choose your preferred provider
TEXT_IMPROVE_PROVIDER=openai:gpt-4o-mini
OPENAI_API_KEY=sk-...
# Or use Anthropic
TEXT_IMPROVE_PROVIDER=anthropic:claude-3-5-sonnet-20241022
ANTHROPIC_API_KEY=sk-ant-...
# Or DeepSeek
TEXT_IMPROVE_PROVIDER=deepseek:deepseek-chat
DEEPSEEK_API_KEY=sk-...
# Or Azure OpenAI
TEXT_IMPROVE_PROVIDER=azure_openai:gpt-4
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
```
### 2. Use the Field in Your Nova Resource
Replace the standard `Textarea` field with `TextImprove`:
```php
use Iamgerwin\NovaAiContextAwareInput\Fields\TextImprove;
public function fields(Request $request)
{
return [
TextImprove::make('Description')
->style('professional')
->trigger('blur'),
];
}
```
That's it! Your field now has AI-powered text improvement capabilities.
## Configuration
The package comes with extensive configuration options. Here are the key settings:
### Default Provider
```php
// config/nova-ai-context-aware-input.php
'provider' => env('TEXT_IMPROVE_PROVIDER', 'openai:gpt-4o-mini'),
```
### Field Defaults
```php
'min_length' => 12, // Minimum characters before AI triggers
'history_size' => 3, // Number of suggestions to keep
'trigger' => 'blur', // blur|idle|manual
'style' => 'professional', // Default writing style
'debounce_ms' => 600, // Milliseconds to wait before processing
```
### Rate Limiting
```php
'rate_limit' => env('TEXT_IMPROVE_RATE_LIMIT', 'user:10,1'),
```
Format: `scope:max_attempts,decay_minutes`
- `user:10,1` - 10 attempts per user per minute
- `global:100,60` - 100 attempts globally per hour
### Caching
```php
'cache' => [
'enabled' => true,
'ttl' => 3600, // Cache for 1 hour
'driver' => env('CACHE_DRIVER', 'file'),
],
```
### Security
```php
'security' => [
'max_input_length' => 5000,
'enable_pii_detection' => true,
'pii_patterns' => [
// Email detection
'/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/',
// Phone numbers
'/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/',
// Credit card numbers
'/\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/',
],
],
```
## Usage Examples
### Basic Usage
```php
use Iamgerwin\NovaAiContextAwareInput\Fields\TextImprove;
TextImprove::make('Content')
->style('professional')
->trigger('blur')
->minLength(20);
```
### Advanced Configuration
```php
TextImprove::make('Product Description')
->provider('anthropic:claude-3-5-sonnet-20241022')
->fallback('openai:gpt-4o-mini')
->style('marketing')
->trigger('idle')
->context(['title', 'category', 'price'])
->minLength(30)
->maxTokens(500)
->history(5)
->rateLimit('user:20,1')
->diff(true);
```
### Custom Styling
```php
TextImprove::make('Blog Post')
->style('technical') // Built-in styles
->trigger('manual'); // Only improve when user clicks button
```
Available styles:
- `professional` - Professional and clear business writing
- `formal` - Formal and academic tone
- `friendly` - Warm and approachable tone
- `succinct` - Brief and to the point
- `marketing` - Persuasive marketing copy
- `technical` - Technical and precise language
### Context-Aware Improvements
Leverage contextual information for smarter suggestions:
```php
TextImprove::make('Email Body')
->context(['subject', 'recipient_name', 'sender_role'])
->style('professional');
```
## Available Providers
### OpenAI
```php
'provider' => 'openai:gpt-4o-mini',
// or
'provider' => 'openai:gpt-4',
'provider' => 'openai:gpt-4-turbo',
```
Environment variables:
```env
OPENAI_API_KEY=sk-...
```
### Anthropic Claude
```php
'provider' => 'anthropic:claude-3-5-sonnet-20241022',
// or
'provider' => 'anthropic:claude-3-opus-20240229',
'provider' => 'anthropic:claude-3-haiku-20240307',
```
Environment variables:
```env
ANTHROPIC_API_KEY=sk-ant-...
```
### DeepSeek
```php
'provider' => 'deepseek:deepseek-chat',
```
Environment variables:
```env
DEEPSEEK_API_KEY=sk-...
```
### Azure OpenAI
```php
'provider' => 'azure_openai:gpt-4',
```
Environment variables:
```env
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
```
## Context Providers
Context providers enrich AI suggestions by providing relevant information about the form, user, and resource being edited.
### Sibling Fields Provider
Includes data from other fields in the form:
```php
TextImprove::make('Description')
->context(['title', 'category', 'tags']);
```
This helps the AI understand the broader context. For example, when improving a product description, it knows the product's title and category.
### User Persona Provider
Includes information about the authenticated user:
```php
// Automatically includes:
// - User role
// - Locale/language preference
// - Timezone
```
Helps tailor suggestions to the user's context and language.
### Resource Snapshot Provider
Provides context about the resource being edited:
```php
// Automatically includes:
// - Resource type (e.g., "Article", "Product")
// - Resource ID
// - Common fields (title, name, description, category, type, status)
```
### Policy Hints Provider
Enforces content policies and guidelines:
```php
// config/nova-ai-context-aware-input.php
'policy_hints' => [
'Avoid using profanity or offensive language.',
'Maintain professional tone and clarity.',
'Preserve factual accuracy of the original text.',
],
```
You can also add custom hints per field:
```php
use Iamgerwin\NovaAiContextAwareInput\Context\PolicyHintsProvider;
TextImprove::make('Comment')
->context([
(new PolicyHintsProvider())->addHints([
'Be respectful and constructive.',
'Avoid personal attacks.',
])
]);
```
### Disabling Context Providers
```php
// config/nova-ai-context-aware-input.php
'context_providers' => [
'sibling_fields' => true,
'user_persona' => false, // Disable user context
'resource_snapshot' => true,
'policy_hints' => true,
],
```
## Security Features
### PII Detection
The package automatically detects and warns about potential PII (Personally Identifiable Information) before sending data to AI providers:
- Email addresses
- Phone numbers
- Credit card numbers
- Custom patterns (configurable)
When PII is detected, the request is blocked and an error is returned.
### Input Validation
- Maximum input length enforcement (default: 5000 characters)
- Content sanitization
- API key validation
### Rate Limiting
Prevent abuse with configurable rate limits:
```php
TextImprove::make('Content')
->rateLimit('user:10,1'); // 10 requests per user per minute
```
### Caching
Reduce costs and improve performance by caching improvements:
```php
// Cache key is based on: hash(input + context + style)
// Same input with same context = cache hit
```
## Events
The package dispatches events you can listen to:
### TextImproved Event
Fired when text is successfully improved:
```php
use Iamgerwin\NovaAiContextAwareInput\Events\TextImproved;
class LogTextImprovement
{
public function handle(TextImproved $event): void
{
// $event->originalText
// $event->improvedText
// $event->provider
// $event->style
// $event->user
}
}
```
### SuggestionDiscarded Event
Fired when a user discards an AI suggestion:
```php
use Iamgerwin\NovaAiContextAwareInput\Events\SuggestionDiscarded;
class LogDiscardedSuggestion
{
public function handle(SuggestionDiscarded $event): void
{
// $event->originalText
// $event->suggestedText
// $event->user
}
}
```
## Customizing Prompts
You can customize the system and user prompts sent to AI providers:
```php
// config/nova-ai-context-aware-input.php
'templates' => [
'system' => <<<'TXT'
You are an expert editor improving business text for clarity and professionalism.
Your task is to enhance the given text while:
- Preserving all factual information
- Respecting domain-specific terminology
- Maintaining the original intent and meaning
- Following the specified style guidelines
Return ONLY the improved text without explanations, quotes, or additional commentary.
TXT,
'user' => <<<'TXT'
Please improve the following text:
{{ user_input }}
Context: {{ context }}
Desired Style: {{ style }}
Language: {{ language }}
TXT,
],
```
Available placeholders:
- `{{ user_input }}` - The text to improve
- `{{ context }}` - Contextual information from providers
- `{{ style }}` - The selected writing style
- `{{ language }}` - User's language/locale
## Testing
Run the test suite:
```bash
composer test
```
Run tests with coverage:
```bash
composer test-coverage
```
Run static analysis:
```bash
composer analyse
```
Format code (PSR-12):
```bash
composer format
```
## Performance Tips
1. **Enable caching** to reduce API calls for similar content
2. **Use rate limiting** to control costs
3. **Choose appropriate models**: Smaller models (gpt-4o-mini, claude-3-haiku) for simple improvements, larger models for complex content
4. **Set reasonable `minLength`** to avoid processing very short inputs
5. **Use `trigger='manual'`** for fields where AI assistance is optional
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
### Development Setup
1. Clone the repository
2. Install dependencies: `composer install && npm install`
3. Copy `.env.example` to `.env` and add your API keys
4. Run tests: `composer test`
## Changelog
Please see [CHANGELOG.md](CHANGELOG.md) for recent changes.
## Security
If you discover any security-related issues, please email iamgerwin@live.com instead of using the issue tracker.
## License
The MIT License (MIT). Please see [LICENSE.md](LICENSE.md) for more information.
## Credits
- [Gerwin](https://github.com/iamgerwin) - Creator and maintainer
- Built with [Laravel Nova](https://nova.laravel.com)
- Powered by leading AI providers: [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [DeepSeek](https://deepseek.com)
## Acknowledgments
Special thanks to the Laravel and Nova communities for their excellent frameworks and tools that made this package possible.
---
**Made with care for the Laravel community.**