Filament Deepseek Chat Laravel Package

Getting Started

This is an early-stage (v0.1.x) Filament plugin for adding a DeepSeek-backed chat interface to a panel. The v0.1.0 → v0.1.2 diff ships no human-readable release notes, only a compare link, so treat the changelog as the only source of truth and read the README and composer.json constraints first.

Minimum path to a working chat:

1. composer require filaforge/filament-deepseek-chat (pin the exact version while it is pre-1.0).
2. Publish config and migrations if the package exposes them: php artisan vendor:publish --tag="filament-deepseek-chat-config" and any -migrations tag.
3. Add DEEPSEEK_API_KEY (and base URL / model overrides if configurable) to .env; never hardcode the key.
4. Register the plugin on your panel provider (->plugin(FilamentDeepSeekChatPlugin::make())) and, if it ships a page, a nav item or a Chat page route.
5. First use case: a single-panel internal assistant for support/ops staff — mount the chat page, confirm streaming tokens arrive, then confirm a conversation row is persisted and reloads.

Where to look first: the plugin class (panel registration and navigation), the config file (model, temperature, system prompt, history limits), and the Livewire component if one exists (that is where streaming and state live). Check for a Chat Filament page — that is the natural integration point.

Implementation Patterns

• Panel-scoped plugin registration. Keep the chat confined to an admin or internal panel rather than the default panel. Register per-panel so production-facing panels do not expose a chat surface accidentally.
• Config-driven model/persona. Drive system prompts, model name, and token limits from config/filament-deepseek-chat.php and env, not from code, so staging can point at a cheaper model.
• Livewire page + Blade view. If the package ships a Filament page, extend or wrap it rather than forking. Override the view via ->view() or publish views only for cosmetic changes, so upstream fixes still land.
• Conversation persistence. If messages are stored, wrap creation in a transaction and scope by panel/tenant. If it is stateless, keep the chat read-only and do not present it as a record system.
• Streaming responses. Confirm whether the transport is SSE/streamed or blocking. For streamed replies, ensure the Livewire component uses polling or a stream-capable response; a blocking call on a large prompt will hit PHP max_execution_time.
• Rate limiting and quotas. Put the DeepSeek call behind a queue or a rate limiter per user; chat UIs invite rapid repeat sends. A simple RateLimiter::for('deepseek-chat') middleware on the send action is the cheapest safeguard.
• Prompt hygiene. Treat any user content injected into the system prompt as untrusted; if you feed retrieved documents, delimit them and cap length.
• Testing. Mock the DeepSeek HTTP client (Laravel Http::fake()) in feature tests so the chat page renders and the send path is exercised without burning API credits.

Gotchas and Tips

• Sparse release notes. v0.1.2 only links to a GitHub compare. Pin "filaforge/filament-deepseek-chat": "0.1.2" in composer.json and diff v0.1.0...v0.1.2 yourself before deploying; pre-1.0 minor bumps can rename config keys or classes without notice.
• Config key churn. With two releases inside 0.1.x, assume config keys may move. Re-publish the config after upgrading and diff it against yours rather than assuming defaults.
• API key exposure. Filament assets and Livewire payloads are client-visible; make sure the DeepSeek key stays server-side in .env and is only read in PHP. Do not pass it to the view.
• Streaming vs. timeouts. DeepSeek responses can exceed default PHP/web-server timeouts. If streaming is not implemented, raise max_execution_time or move the call to a queued job with a broadcast/Livewire listener.
• Migration/tag names. Verify the exact publish tags from the README; vendor publish tags are easy to typo and fail silently.
• Filament version alignment. Check the package's composer.json for the supported Filament major (2 vs 3). A mismatch shows up as a missing plugin class or a broken page registration, not a clear error.
• Extension point. The plugin class is the place to add navigation groups, ->navigationLabel(), and conditional visibility; avoid editing package source so future v0.1.x bumps apply cleanly.
• No changelog, no guarantee of BC. Until v0.1.0 notes become descriptive, budget a quick diff review per upgrade and keep a smoke test that opens the chat page and sends one message.