53129
Pa
PAT / files
PAT / README.md
5.6 KB
1# Personal Assistant Thing 2 3A web-based personal assistant that connects to local Ollama models for chat conversations. Built with Next.js, TypeScript, and TailwindCSS. 4 5## Features 6 7- 💬 **Chat Interface**: Thread-based conversations with message history 8- 🤖 **Ollama Integration**: Connect to local LLM models via Ollama 9- 🧠 **Thinking Mode**: View model reasoning process with thinking output 10- 🛠️ **Tool Calling**: Built-in tools for web search (SearXNG) and page fetching 11- 🎨 **Modern UI**: Clean, responsive interface with dark/light theme support 12- 💾 **Persistent Storage**: PostgreSQL database for threads and messages 13- ⚡ **Caching**: Valkey (Redis-compatible) caching for improved performance 14- 📝 **Markdown Support**: Rich markdown rendering with syntax highlighting 15 16## Prerequisites 17 18- Node.js >= 25.0.0 19- Docker (for running PostgreSQL, Valkey, and SearXNG) 20- Ollama installed and running locally 21 22## Getting Started 23 24### 1. Clone the Repository 25 26```bash 27git clone <repository-url> 28cd personal-assistant-thing 29``` 30 31### 2. Install Dependencies 32 33```bash 34npm install 35``` 36 37### 3. Set Up Environment Variables 38 39Create a `.env` file in the root directory: 40 41```env 42# Database 43DATABASE_URL=postgresql://postgres:your_password@localhost:5432/personal_assistant 44 45# Valkey (Redis-compatible cache) 46VALKEY_URL=valkey://:your_valkey_password@localhost:6379 47 48# Docker setup (for start-docker.sh script) 49VALKEY_PASSWORD=your_valkey_password 50POSTGRES_PASSWORD=your_postgres_password 51POSTGRES_USER=postgres 52POSTGRES_DB=personal_assistant 53POSTGRES_PORT=5432 54 55# Optional: SearXNG URL (for web search tool, defaults to http://localhost:8888) 56SEARXNG_URL=http://localhost:8888 57``` 58 59### 4. Start Docker Services 60 61The project includes scripts to start PostgreSQL, Valkey, and SearXNG containers: 62 63```bash 64npm run start:docker 65``` 66 67This will start: 68 69- PostgreSQL database on port 5432 70- Valkey (Redis-compatible) cache on port 6379 71- SearXNG search engine on port 8888 72 73To stop the containers: 74 75```bash 76npm run stop:docker 77``` 78 79### 5. Run Database Migrations 80 81```bash 82npm run db:migrate 83``` 84 85### 6. Start the Development Server 86 87```bash 88npm run dev 89``` 90 91Open [http://localhost:3000](http://localhost:3000) in your browser. 92 93## Available Scripts 94 95- `npm run dev` - Start development server 96- `npm run build` - Build for production 97- `npm run start` - Start production server 98- `npm run lint` - Run ESLint 99- `npm run lint:fix` - Fix ESLint errors 100- `npm run typecheck` - Run TypeScript type checking 101- `npm run format` - Format code with Prettier 102- `npm run format:check` - Check code formatting 103- `npm run test` - Run tests with Vitest 104- `npm run test:ui` - Run tests with UI 105- `npm run test:run` - Run tests once 106- `npm run db:generate` - Generate database migrations 107- `npm run db:migrate` - Run database migrations 108- `npm run db:studio` - Open Drizzle Studio 109- `npm run db:wipe-dev` - Wipe development database 110- `npm run start:docker` - Start Docker containers 111- `npm run stop:docker` - Stop Docker containers 112 113## Project Structure 114 115``` 116personal-assistant-thing/ 117├── app/ # Next.js app directory 118│ ├── api/ # API routes 119│ │ ├── models/ # Model management endpoints 120│ │ └── threads/ # Thread and message endpoints 121│ ├── layout.tsx # Root layout 122│ └── page.tsx # Home page 123├── src/ 124│ ├── components/ # React components 125│ │ ├── App.tsx # Main app component 126│ │ ├── MessageList.tsx 127│ │ ├── MessageEditor.tsx 128│ │ ├── Sidebar.tsx 129│ │ └── ... 130│ ├── hooks/ # React hooks 131│ │ ├── api/ # API hooks 132│ │ └── ... 133│ └── lib/ # Library code 134│ ├── chat.ts # Chat generation logic 135│ ├── db/ # Database schema and connection 136│ ├── tools/ # Tool implementations 137│ ├── cache/ # Caching utilities 138│ └── ... 139├── drizzle/ # Database migrations 140├── scripts/ # Utility scripts 141└── searxng/ # SearXNG configuration 142``` 143 144## Tools 145 146The assistant supports the following tools: 147 148- **Web Search**: Search the web using SearXNG (privacy-focused metasearch engine) 149- **Fetch Page**: Fetch and extract content from web pages, including title, content, and links 150 151Both tools use caching to improve performance and reduce API calls. 152 153## Database Schema 154 155The application uses PostgreSQL with the following main tables: 156 157- **threads**: Conversation threads with model and configuration 158- **messages**: Messages within threads (user, assistant, tool) 159 160See `src/lib/db/schema.ts` for the complete schema. 161 162## Development 163 164### Code Style 165 166- Use TypeScript for all code 167- Follow ESLint and Prettier configurations 168- Use absolute imports with `@/` alias 169- Write modular, testable code 170 171### Testing 172 173Run tests with: 174 175```bash 176npm run test 177``` 178 179### Database Management 180 181Generate migrations after schema changes: 182 183```bash 184npm run db:generate 185``` 186 187Apply migrations: 188 189```bash 190npm run db:migrate 191``` 192 193View database in Drizzle Studio: 194 195```bash 196npm run db:studio 197``` 198 199## License 200 201This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. 202 203This license allows free use, modification, and distribution, but requires that: 204 205- All derivative works must also be licensed under AGPL-3.0 206- Source code must be made available to anyone who uses the software (including over a network) 207- The code cannot be sold as proprietary software 208 209See the [LICENSE](LICENSE) file for the full license text.