Filament Chatgpt Bot Laravel Package

Getting Started

Since there's no prior assessment on file, treat v1.3.1 as the baseline for this package.

1. Install and publish config

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

   The published config file is the first place to look — v1.3.1 puts the default model there rather than hardcoding it in the client.

2. Set the model explicitly in .env

   <PACKAGE>_API_KEY=sk-...
   <PACKAGE>_MODEL=gpt-5.6-sol
   

   v1.3.1 changes the shipped default to gpt-5.6-sol and makes the model configurable. Pinning it in .env means future default changes in the package won't silently alter your app's behaviour.

3. First use case: a single call that resolves the default model from config — e.g. a summarisation or classification action invoked from a controller or job. Confirm the resolved model name in a log line before you build anything on top of it.

4. Verify the override surface. "Make model changeable" is typically exposed two ways — a config key and a per-call setter. Check the changelog/source for the exact method (->withModel(), ->using(), setModel(), etc.) before wiring it into your code; the release note doesn't specify the API shape.

Implementation Patterns

Config default + per-call override. Keep one default in config and override only where the task justifies it:

// config/<package>.php
'model' => env('<PACKAGE>_MODEL', 'gpt-5.6-sol'),

// per call
$response = <Facade>::withModel('gpt-5.6-sol')  // verify method name
    ->prompt($prompt);

Named presets instead of raw model strings. Put model names in config under semantic keys and reference them by intent, so a model swap is a one-line config change and never a find-and-replace across the codebase:

'models' => [
    'fast' => env('<PACKAGE>_MODEL_FAST', 'gpt-5.6-sol'),
    'deep' => env('<PACKAGE>_MODEL_DEEP', 'gpt-5.6-sol'),
],

Environment-scoped models. Use the cheapest viable model in local and testing, the strong default in production. Drive this from the config file's environment branches rather than from if (app()->isProduction()) scattered through your services.

Wrap calls in an action/service class. Controllers and jobs should call SummariseDocument::run($doc), not the package facade directly. That gives you one place to inject the model, add retries, and swap the package later.

Queue anything non-trivial. Long completions inside a request will hit PHP/nginx timeouts. Dispatch a job with an explicit $timeout and $tries, and implement failed() so a model error doesn't strand the record in a half-processed state.

Testing. Fake the underlying HTTP client (or the package's fake, if provided) and assert on the model name in the outgoing payload — that's how you catch an accidental default-model regression after a package upgrade.

Observability. Log model name, prompt tokens, completion tokens, and latency per call. Once the model is configurable, "which model produced this output" becomes a question you'll actually need to answer during incident review.

Gotchas and Tips

• The default change is a silent behaviour change. Anyone relying on the previously shipped default now gets gpt-5.6-sol on upgrade with no deprecation warning. Pin <PACKAGE>_MODEL in .env and in phpunit.xml before upgrading, and diff outputs on a representative sample.
• Config caching hides changes. After editing .env or the config file, run php artisan config:clear (or config:cache in deploy). A stale cached config is the most common reason "the model won't change."
• Restart queue workers. Long-lived queue:work processes hold config in memory; model changes won't apply until php artisan queue:restart.
• Model names fail at call time, not boot time. A typo in a model string surfaces as a runtime API error deep inside a job. Add a smoke test or a small artisan command that issues a one-token request so config errors fail fast.
• Cost and latency are not uniform across models. Don't let the strong default bleed into high-volume classification or extraction paths; use the per-call override (or a fast preset) for those.
• Validate overrides, don't trust them. If model names come from user input or a database column, whitelist against your config's preset keys — an arbitrary string reaching the API is both a cost and a support risk.
• Extension points to look for: a bindable client interface (swap in a stub for tests), macros on the facade/builder, and any resolver or factory used to construct the model config. Bind these in a service provider rather than editing the published config, so package upgrades stay clean.
• Read the v1.3.0 → v1.3.1 diff. This is a patch release, so backwards compatibility is expected, but the default value changed — confirm whether the config key was renamed or merely re-defaulted, since a rename would silently orphan an existing published config file.