xonecas.io
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.