feat: persist chats & stream everything

.blade.format.json

@@ -0,0 +1,7 @@
+{
+    "useLaravelPint": true,
+    "attributeJsOptions": {
+        "semi": true,
+        "printWidth": 120
+    }
+}

.github/workflows/tests.yml

@@ -51,4 +51,4 @@ jobs:
         run: npm run build
 
       - name: Run Tests
-        run: ./vendor/bin/pest
+        run: ./vendor/bin/pest

.prettierignore

@@ -0,0 +1,4 @@
+composer.lock
+tests/**/*.html
+storage/framework/**/*.blade.php
+resources/views/emails/**/*.blade.php

.prettierrc

@@ -0,0 +1,24 @@
+{
+    "printWidth": 120,
+    "semi": true,
+    "singleQuote": true,
+    "tabWidth": 4,
+    "trailingComma": "all",
+    "plugins": ["prettier-plugin-tailwindcss", "prettier-plugin-blade"],
+    "overrides": [
+        {
+            "files": ["*.yml", "*.yaml"],
+            "options": { "tabWidth": 2 }
+        },
+        {
+            "files": "*.md",
+            "options": { "tabWidth": 2 }
+        },
+        {
+            "files": ["*.blade.php"],
+            "options": {
+                "parser": "blade"
+            }
+        }
+    ]
+}

CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is **Livewire Chat Kit** - a Laravel Starter Kit for building LLM-powered chat interfaces. It combines Laravel 12, Livewire 3, FluxUI components, and Prism PHP for LLM integration to create chat applications with minimal JavaScript.
+
+## Development Commands
+
+```bash
+# Laravel Herd handles server/queue/logs automatically
+# Only run this if you need console output visibility
+composer dev
+
+# Run tests
+composer test
+
+# Format code (PHP + JS/CSS)
+composer format
+
+# Check formatting
+composer format:check
+
+# Build assets for development
+npm run dev
+
+# Build assets for production
+npm run build
+```
+
+## Architecture Overview
+
+### Core Chat System
+
+- **`app/Livewire/Chat.php`** - Main chat component handling LLM streaming and message management
+- **`app/Livewire/Chat/Sidebar.php`** - Chat navigation and history
+- **Message flow**: User input → `sendMessage()` → `runChatToolLoop()` → Prism LLM streaming → real-time UI updates via Livewire streams
+
+### Data Layer
+
+- **Models**: `User`, `Chat`, `Message` with proper relationships
+- **DTOs**: `UserMessage`, `AssistantMessage` for type-safe message handling
+- **Enums**: `OpenAiModel`, `Visibility` for consistent value objects
+- **Policies**: `ChatPolicy` for authorization
+
+### Frontend Architecture
+
+- **Livewire-first**: Dynamic UI with minimal JavaScript
+- **FluxUI components**: Professional UI component library (find available components by googling "site:fluxui.dev <component name>"). Only use free components.
+- **Streaming responses**: Real-time message updates using Livewire streams
+- **Markdown rendering**: Built-in markdown-it with syntax highlighting
+
+### LLM Integration (Prism)
+
+- **Default provider**: OpenAI GPT-4o-mini
+- **Multi-provider support**: Easy switching between OpenAI, Anthropic, etc.
+- **Streaming**: Real-time token streaming for smooth UX
+- **Configuration**: LLM provider/model configurable per chat
+
+## Key Technical Patterns
+
+### Message Streaming Flow
+
+1. User submits message via `x-chat.message-input`
+2. `sendMessage()` adds user message to array, clears input
+3. `$this->js('$wire.runChatToolLoop()')` triggers LLM call
+4. `runChatToolLoop()` streams tokens via `$this->stream()`
+5. Frontend `x-chat.assistant-message` updates in real-time
+6. Complete message added to permanent `$messages` array
+
+### Environment Configuration
+
+- **Required**: `OPENAI_API_KEY` (or provider-specific keys)
+- **Database**: SQLite by default, configurable
+- **Development**: Laravel Herd handles server/queue/logs automatically
+
+### File Structure Patterns
+
+- **`/app/Livewire`** - All Livewire components
+- **`/resources/views/livewire`** - Component Blade templates
+- **`/resources/js`** - Minimal JavaScript (streaming markdown component)
+- **`/tests`** - Pest tests with Livewire testing utilities
+
+## Development Notes
+
+### Code Style
+
+- **PHP**: Laravel Pint for formatting, Rector for refactoring
+- **JavaScript/CSS**: Prettier with Tailwind plugin
+- **Blade**: Prettier blade plugin for template formatting
+
+### Testing
+
+- **Framework**: Pest PHP with Livewire plugin
+- **Coverage**: Feature and Unit tests for core functionality
+
+### Provider Switching
+
+To switch LLM providers, modify the `runChatToolLoop()` method in `Chat.php`:
+
+```php
+$generator = Prism::text()
+    ->using(Provider::Anthropic, 'claude-3-sonnet-20240229')
+    // ->using(Provider::OpenAI, 'gpt-4o-mini') // Default
+```
+
+### Asset Pipeline
+
+- **Vite**: Modern build tool with hot reload
+- **TailwindCSS 4**: Utility-first CSS with typography plugin
+- **Laravel Herd**: Development environment handles all services automatically
+
+## Development Workflow Notes
+
+- You don't need to run npm run build, I have npm run dev running
+- Use `php artisan` to do laravel related things like creating Models/Components etc.
+- Stay CRUDDY
+- Available UI components are under vendor/livewire/flux/stubs/resources/views/flux
+- Find available component docs by googling "site:fluxui.dev <component name>"

README.md

@@ -11,12 +11,27 @@ This starter kit provides a clean, simple foundation for creating chat applicati
 
 ## Features
 
-*   **Livewire-Powered:** Build dynamic interfaces with PHP.
-*   **Streamed Responses:** Real-time message streaming from LLMs for a smooth UX.
-*   **FluxUI Components:** Beautiful, pre-built UI components for a polished look and feel.
-*   **Prism Integration:** The Laravel-way of speaking to LLMs. Easy to use, test, and switch between providers (e.g., OpenAI, Anthropic).
-*   **Minimal JavaScript:** Focus on your PHP backend.
-*   **TailwindCSS Styled:** Includes a TailwindCSS setup with a typography plugin for rendering markdown.
+### Chat System
+
+- **Multi-Chat Management:** Create, manage, and navigate between multiple chat conversations
+- **Chat Sidebar:** Quick access to recent chats with intelligent navigation
+- **Chat Sharing:** Share conversations publicly or keep them private with visibility controls
+- **Model Selection:** Choose from different LLM models (GPT-4o, GPT-4o-mini, etc.) per chat
+- **Persistent History:** All conversations are saved and accessible across sessions
+
+### LLM Integration
+
+- **Livewire-Powered:** Build dynamic interfaces with PHP.
+- **Streamed Responses:** Real-time message streaming from LLMs for a smooth UX.
+- **Prism Integration:** The Laravel-way of speaking to LLMs. Easy to use, test, and switch between providers (e.g., OpenAI, Anthropic).
+- **Tool Support:** Built-in LLM tool calling with visual feedback and result display
+
+### UI & Design
+
+- **FluxUI Components:** Beautiful, pre-built UI components for a polished look and feel.
+- **Minimal JavaScript:** Focus on your PHP backend.
+- **TailwindCSS Styled:** Includes a TailwindCSS setup with a typography plugin for rendering markdown.
+- **Real-time Updates:** Seamless UI updates using Livewire streams
 
 ## Installation
 
@@ -68,45 +83,75 @@ Remember to add the corresponding API key to your `.env` file (e.g., `ANTHROPIC_
 
 ### 2. Explore the Chat Interface
 
-Navigate to your application's `/dashboard` route (or wherever you've set up the chat component) to start interacting with the chat interface.
+Navigate to your application's `/dashboard` route to start interacting with the chat interface. You can:
+
+- Create new chats from the sidebar
+- Switch between existing conversations
+- Share chats publicly or keep them private
+- Change the LLM model for each chat
+- Use built-in tools (like the example sum calculator)
+
+## Architecture
 
-## Core Components
+### Core Components
 
-### `app/Livewire/Chat.php`
+- **`app/Livewire/Chats/Index.php`** - Paginate over all of your chats
+- **`app/Livewire/Chats/Show.php`** - Main chat component handling LLM streaming, tool calls, and message management
+- **`app/Livewire/ChatSidebar.php`** - Chat navigation, history, and new chat creation
+- **`app/Models/Chat.php`** - Chat model with user relationships and visibility controls
+- **`app/Models/Message.php`** - Message model with tool call/result support and Prism integration
 
-This is the heart of the chat functionality.
+### Business Logic Layer
 
-### `resources/views/livewire/chat.blade.php`
+- **`app/Actions/`** - Clean action classes for complex operations:
+  - `AddNewUserMessageToChat` - Handles user message persistence
+  - `UpdateStreamDataFromPrismChunk` - Processes streaming LLM responses
+  - `PersistStreamDataToMessages` - Saves complete responses to database
+- **`app/Dtos/StreamData.php`** - Type-safe data transfer object for streaming
+- **`app/Policies/ChatPolicy.php`** - Authorization rules for chat access and sharing
 
-This Blade view renders the chat interface.
+### UI Components
+
+- **Chat Interface:** Real-time streaming with markdown rendering
+- **Tool Results Display:** Visual feedback for LLM tool executions
+- **Model Selector:** Per-chat model configuration
+- **Sharing Controls:** Public/private visibility management
 
 ## How it Works
 
-1.  User types a message in `x-chat.message-input` and hits send.
-2.  `sendMessage()` in `Chat.php` is triggered.
-    *   The user's message is added to the `$messages` array.
-    *   The input field is cleared.
-    *   `$this->js('$wire.runChatToolLoop()')` is called, which immediately invokes the `runChatToolLoop()` method. This allows the UI to update with the user's message before the LLM call.
-3.  `runChatToolLoop()`:
-    *   Constructs a request to the LLM using Prism, including the system prompt and the current chat history.
-    *   The request is sent as a stream.
-    *   As tokens arrive from the LLM:
-        *   They are appended to a local `$message` variable.
-        *   The `stream()` method sends the accumulated `$message` (converted to markdown) to the frontend, updating the part of the view listening to `streamed-message`. This is typically handled by the `x-chat.assistant-message` component.
-4.  Once the LLM finishes generating its response:
-    *   The complete assistant message is added to the `$messages` array. The temporary streamed display is effectively replaced by the final message in the loop.
+### Message Flow
+
+1. **User Input:** Message typed in chat interface and submitted
+2. **Message Processing:** `AddNewUserMessageToChat` action persists user message
+3. **LLM Streaming:** `runChatToolLoop()` initiates real-time streaming with Prism
+4. **Stream Handling:** `UpdateStreamDataFromPrismChunk` processes each chunk (text, tool calls, results)
+5. **UI Updates:** Livewire streams update the interface in real-time
+6. **Persistence:** `PersistStreamDataToMessages` saves complete conversation
+
+### Tool Integration
+
+- **Tool Definitions:** Tools are defined in the `runChatToolLoop()` method
+- **Automatic Execution:** LLM can call tools during conversation flow
+- **Visual Feedback:** Tool calls and results are displayed with dedicated UI components
+
+### Technical Implementation
+
+- **UUID Models:** All models use UUIDs for security and scalability
+- **Policy Authorization:** Fine-grained access control with `ChatPolicy`
+- **Type Safety:** DTOs and strong typing throughout the application
+- **Testing:** Comprehensive Pest test suite with Livewire integration
+- **Code Quality:** Laravel Pint, Rector, and Prettier for consistent formatting
 
 ## Contributing
 
 Contributions are welcome! If you'd like to improve the Livewire Chat Kit, please feel free to:
 
-*   Report a bug.
-*   Suggest a new feature.
-*   Submit a pull request.
+- Report a bug.
+- Suggest a new feature.
+- Submit a pull request.
 
 Please visit the [GitHub repository](https://github.com/kauffinger/livewire-chat-kit) to contribute.
 
 ## License
 
 This project is open-sourced software licensed under the [MIT license](LICENSE.md).
-```

app/Actions/AddNewUserMessageToChat.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Actions;
+
+use App\Models\Chat;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class AddNewUserMessageToChat
+{
+    public function handle(Chat $chat, string $userMessage): void
+    {
+        DB::transaction(function () use ($chat, $userMessage): void {
+            $chat->messages()->create([
+                'role' => 'user',
+                'parts' => [
+                    'text' => $userMessage,
+                ],
+                'attachments' => '[]',
+            ]);
+
+            $this->updateChatTitleIfMessageIsFirstMessage($chat, $userMessage);
+        });
+    }
+
+    private function updateChatTitleIfMessageIsFirstMessage(Chat $chat, string $userMessage): void
+    {
+        if ($chat->messages()->count() === 1) {
+            $chat->update([
+                'title' => Str::limit($userMessage, 50),
+            ]);
+        }
+    }
+}

app/Actions/PersistStreamDataToMessages.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Actions;
+
+use App\Dtos\StreamData;
+use App\Models\Chat;
+use Illuminate\Support\Facades\DB;
+
+class PersistStreamDataToMessages
+{
+    public function handle(Chat $chat, StreamData $streamData): void
+    {
+        DB::transaction(function () use ($chat, $streamData): void {
+            if ($streamData->toolResults !== []) {
+                $chat->messages()->create([
+                    'role' => 'tool_result',
+                    'parts' => ['toolResults' => $streamData->toolResults],
+                    'attachments' => '[]',
+                ]);
+            }
+
+            $chat->messages()->create([
+                'role' => 'assistant',
+                'parts' => $streamData->toArray(),
+                'attachments' => '[]',
+            ]);
+
+            $chat->touch();
+        });
+    }
+}