stirgpea
777d4b20f3
Fixes capitalization to pievr and replaces README with a full, comprehensive documentation of project architecture, concepts, and roadmap. Co-authored-by: StirGpea <stir@openclaw.local> Reviewed-on: #3 Co-authored-by: stirgpea <stjrgpea@wivziv.com> Co-committed-by: stirgpea <stjrgpea@wivziv.com>
44 lines
2.7 KiB
Markdown
44 lines
2.7 KiB
Markdown
# pievr
|
|
|
|
Telegram bot for technical interview preparation using flashcards and smart prioritized spaced repetition.
|
|
|
|
## Overview
|
|
|
|
**pievr** is a personal Telegram bot designed to streamline technical interview preparation. Instead of standard rigid calendar intervals (like traditional spaced repetition apps), it uses a dynamic priority queue system based on recent performance and time elapsed.
|
|
|
|
## Core Concepts & Architecture
|
|
|
|
### 1. Dynamic Priority System
|
|
- **No Calendar Dates:** Spaced repetition doesn't rely on strict dates.
|
|
- **Priority Calculation:** Priorities are calculated dynamically in Go code based on:
|
|
- Time elapsed since the question was last asked (older unseen/unasked questions rise in priority).
|
|
- Success streak (`streak`): successful answers decrease priority, while mistakes increase it sharply.
|
|
- **New Questions Mix:** Unseen questions (`times_asked = 0`) have no priority and are smoothly mixed into study sessions in a configurable proportion alongside prioritized review questions.
|
|
|
|
### 2. Flexible Tagging
|
|
- Questions support multiple tags (many-to-many relationship) to allow granular topic filtering and cross-cutting selections (e.g., combining `go` and `concurrency`).
|
|
|
|
### 3. LLM Integration (Gemini API)
|
|
- **Configurable BaseURL:** Configurable via environment or config file to support proxies or custom endpoints.
|
|
- **Background Generation:** Background workers passively generate questions in bulk (e.g., in JSON batches) to maintain a target buffer of questions.
|
|
- **Self-Validation:** When questions are generated, the LLM validates them by answering its own questions before they enter the active pool.
|
|
- **Bot Interaction:** The bot can operate as an AI assistant with tool-use capabilities to query the database, manage tags, and fetch questions.
|
|
|
|
### 4. Database Schema (SQLite)
|
|
Stored locally in `storage/` (excluded via `.gitignore`):
|
|
- **`questions`**: Stores core content (`type`, `question_text`, `payload` as JSON, `active`, `last_asked_at`, `streak`, `times_asked`, `times_correct`, `created_at`).
|
|
- **`tags`**: Tag definitions (`name`).
|
|
- **`question_tags`**: Many-to-many mapping between questions and tags.
|
|
|
|
## Project Structure
|
|
- `cmd/` — Application entrypoints
|
|
- `internal/` — Private application code (domain, services, storage, bot handlers)
|
|
- `prompts/` — Prompt templates embedded via `go:embed`
|
|
- `storage/` — SQLite database files and schemas
|
|
- `docs/` — Documentation and architectural notes
|
|
|
|
## Development Workflow
|
|
1. Sync with `master` before starting any new feature branch.
|
|
2. Implement features or fixes in dedicated feature branches (`feature/...` or `fix/...`).
|
|
3. Rebase against `master` before pushing.
|
|
4. Open a Pull Request for review and merge.
|