GEMINI.md

1# Gemini Code Assistant Guide for Hovimestari
2 
3This guide provides essential information for AI code assistants working on the Hovimestari project.
4 
5## Project Overview
6 
7Hovimestari is a personal AI butler assistant written in Go. It gathers information from various sources (calendars, weather APIs, manual input), stores them as "memories" in a SQLite database, and uses a Large Language Model (LLM) to generate a personalized daily brief.
8 
9- **Inspiration**: [Geoffrey Litt's AI assistant](https://www.geoffreylitt.com/2025/04/12/how-i-made-a-useful-ai-assistant-with-one-sqlite-table-and-a-handful-of-cron-jobs)
10- **Name**: "Hovimestari" is Finnish for "Butler".
11- **Primary Language**: Briefs are generated in Finnish by default, but the codebase, comments, and logs are in English.
12 
13## Core Architecture & Key Files
14 
15The project follows a modular structure, separating concerns into distinct packages within the `internal/` directory.
16 
17- **Entry Point**: `cmd/hovimestari/main.go` initializes the [Cobra](https://github.com/spf13/cobra) CLI.
18- **CLI Commands**: Each command is a separate file in `cmd/hovimestari/commands/`.
19- **Configuration**: `internal/config/viper.go` manages configuration using [Viper](https://github.com/spf13/viper), supporting file-based (`config.json`), environment variables, and XDG standard directories (`~/.config/hovimestari/`).
20- **Database**: `internal/store/store.go` handles all interactions with the SQLite database (`memories.db`). It uses `modernc.org/sqlite` for CGO-free compilation. All data is stored in a single `memories` table.
21- **Brief Generation**: `internal/brief/brief.go` orchestrates the collection of memories and context to generate the final brief via the LLM.
22- **LLM Interaction**: `internal/llm/gemini.go` contains the client for the Google Gemini API. Prompts are stored in `prompts.json`.
23- **Importers**: Data sources are implemented as importers in `internal/importer/`. For example, `internal/importer/calendar/calendar.go` handles iCalendar/WebCal imports.
24- **Output**: `internal/output/` contains a multi-destination system to send briefs to the CLI, Discord, and Telegram.
25 
26## Developer Workflow & Commands
27 
28This project uses [Task](https://taskfile.dev/) as a command runner instead of Make. All common development tasks are defined in `Taskfile.yml`.
29 
30- **Build the application**:
31 
32```bash
33  task build
34```
35 
36- **Run all tests**:
37 
38```bash
39  task test
40```
41 
42- **Run linter**:
43 
44```bash
45  task lint
46```
47 
48- **Tidy dependencies**:
49 
50```bash
51  task deps
52```
53 
54Application commands are executed via the compiled binary. For example:
55 
56```bash
57# Import calendar events
58./build/hovimestari import-calendar
59 
60# Generate the daily brief
61./build/hovimestari generate-brief
62```
63 
64## Project Conventions
65 
66- **Error Handling**: Use the `fmt.Errorf("...: %w", err)` pattern to wrap and add context to errors.
67- **Logging**: The project uses the standard `log/slog` library with a custom human-readable handler in `internal/logging/handler.go`. Use this for all logging.
68- **Dependencies**: Use the standard library where possible. For external dependencies, ensure they are added to `go.mod` and run `task deps`.
69- **Configuration**: When adding new configuration options, update the `Config` struct in `internal/config/viper.go` and the `config.example.json` file.
70- **Adding a Command**: To add a new CLI command, create a new file in `cmd/hovimestari/commands/` and add it to the root command in `cmd/hovimestari/main.go`. Follow the existing Cobra command structure.
71 
72## Testing
73 
74- Tests are located in `*_test.go` files alongside the code they test.
75- Tests should be deterministic and not rely on external services (network, LLM APIs, or the database). Mock these dependencies where necessary.
76- Run all tests using `task test`.
77