# Notolog Editor - AI-Readable Documentation

> This file is optimized for Large Language Models and AI agents

## Product Overview

Notolog is an open-source, cross-platform Markdown editor with integrated AI assistant capabilities.

**Primary Use**: Text editing, documentation, note-taking with AI enhancement
**Target Users**: Developers, writers, researchers, content creators
**Unique Value**: On-device AI inference + cloud AI options + strong encryption

## Core Capabilities

### 1. Markdown Editing
- Syntax highlighting for Markdown
- Live preview rendering
- Multi-line block support
- File management with tree view
- Search within documents

### 2. AI Assistant Integration
Three backend options:
- **OpenAI API**: Cloud-based GPT models (GPT-4o, GPT-5.2)
- **ONNX Runtime**: Local inference with ONNX models (Phi-3, Llama)
- **llama.cpp**: Local inference with GGUF models (Llama, Mistral, Mixtral)

Additional AI Assistant features:
- Custom prompt templates
- Settings UI parameters (temperature, max tokens)
- Save conversation history as .md files
- Async requests for non-blocking UI

### 3. Security & Privacy
- AES-128 encryption for files (CBC mode via Fernet)
- PBKDF2 key derivation with SHA-256
- Fernet encryption format
- Password-protected documents
- No cloud storage requirement
- Local-only AI option

### 4. Cross-Platform Support
- Windows (7+)
- macOS (10.13+)
- Linux (Ubuntu, Debian, Fedora, Arch)
- Consistent UI across platforms (Qt/PySide6)

## Technical Architecture

### Technology Stack
```
Frontend: PySide6 (Qt for Python 6.x)
Language: Python 3.10+
AI: OpenAI API, ONNX Runtime GenAI, llama-cpp-python
Encryption: cryptography library (Fernet, AES-128 CBC, PBKDF2HMAC with SHA-256)
Markdown: Python-Markdown with extensions
Async: asyncio for non-blocking operations
```

### Key Dependencies
- PySide6 Essentials >= 6.11.2, < 6.12.0
- onnxruntime-genai >= 0.11.2, < 0.12.0 on Python 3.10
- onnxruntime-genai >= 0.15.2, < 1.0.0 on Python 3.11-3.14
- llama-cpp-python >= 0.3.35, < 0.4.0 (optional)
- cryptography >= 50.0.0, < 51.0.0

OpenAI-compatible API support is built in and does not require the OpenAI Python SDK.

### Module Architecture
```
notolog/
├── notolog_editor.py      # Main application
├── edit_widget.py         # Markdown editor
├── view_widget.py         # Preview renderer
├── modules/
│   ├── openai_api/       # OpenAI integration
│   ├── ondevice_llm/     # ONNX Runtime
│   └── llama_cpp/        # llama.cpp integration
├── encrypt/              # Encryption utilities
├── highlight/            # Syntax highlighting
└── ui/                   # User interface components
```

## Installation Methods

### PyPI (pip)
```bash
pip install notolog
notolog  # Launch
```

### Debian/Ubuntu
```bash
# Download .deb from GitHub releases
sudo dpkg -i notolog_*.deb
```

### Conda
```bash
conda install -c conda-forge notolog
```

### From Source
```bash
git clone https://github.com/notolog/notolog-editor.git
cd notolog-editor
pip install -e .
python -m notolog
```

## AI Model Setup

### OpenAI API
1. Get API key from platform.openai.com
2. Settings → AI Assistant → OpenAI API
3. Enter API key (stored encrypted)
4. Select model (gpt-4o, gpt-5.2, etc.)

### ONNX Models (Local)
1. Download ONNX model from Hugging Face
2. Models typically 1-10 GB
3. Settings → AI Assistant → On Device LLM
4. Point to model directory
5. Select execution provider (CPU, CUDA, DirectML)

### Module llama.cpp (Local)
1. Download GGUF model
2. Quantized models (Q4_K_M recommended)
3. Settings -> AI Assistant -> Module llama.cpp
4. Select .gguf file
5. Configure context size and GPU Layers
6. **macOS Apple Silicon (M1-M4)**: Metal GPU acceleration works automatically

## Quick Configs (Copy-Paste Ready)

### Install with llama.cpp support
```bash
pip install "notolog[llama]"
```

### GPU Setup (NVIDIA CUDA)
```bash
pip uninstall onnxruntime-genai -y
pip install onnxruntime-genai-cuda
```

### GPU Setup (Windows DirectML)
```bash
pip uninstall onnxruntime-genai -y
pip install onnxruntime-genai-directml
```

### Revert to CPU
```bash
pip uninstall onnxruntime-genai-cuda onnxruntime-genai-directml -y
pip install --force-reinstall onnxruntime-genai
```

### Recommended ONNX Model
```
Model: microsoft/Phi-3-mini-4k-instruct-onnx
Path: cpu_and_mobile/cpu-int4-rtn-block-32/
Requires: genai_config.json in model directory
```

### Recommended GGUF Model
```
Model: Qwen/Qwen2-7B-Instruct-GGUF
File: qwen2-7b-instruct-q5_k_m.gguf
Size: ~6GB RAM required
```

## Common Use Cases

### 1. Technical Documentation
- Write README files
- Create API documentation
- Maintain changelogs
- Generate user guides
- AI assistance for technical writing

### 2. Note-Taking
- Personal knowledge base
- Meeting notes
- Research notes
- Encrypted journals
- Quick thoughts

### 3. Content Creation
- Blog posts
- Articles
- Tutorials
- Social media content
- AI-powered drafting

### 4. Development
- Code documentation
- Project planning
- Architecture docs
- Issue descriptions
- Pull request descriptions

## Configuration Options

### Editor Settings
- Font family and size
- Line numbers toggle
- Theme selection (6 themes)
- Default notes directory
- Auto-save behavior

### AI Settings
- Model selection
- API endpoint (customizable)
- Temperature (0-100)
- Max response tokens
- System prompts
- Conversation history size

### Encryption Settings
- Default encryption status
- Password requirements
- Key derivation rounds

## Performance Characteristics

### Resource Usage
- RAM: 100-500 MB (without AI models)
- RAM with AI: 2-16 GB (depending on model size)
- CPU: Low (editing), High (local AI inference)
- GPU: Optional (CUDA/DirectML for ONNX)

### Model Performance
- OpenAI API: Fast (network dependent)
- ONNX CPU: Slow (1-10 tokens/sec)
- ONNX GPU: Fast (10-100 tokens/sec)
- llama.cpp: Medium (5-30 tokens/sec)

## Security Features

### Encryption Details
- Algorithm: AES-128 in CBC mode (via Fernet)
- Key Derivation: PBKDF2HMAC with SHA-256
- Salt: Random 16 bytes per file
- Iterations: 600,000+
- Format: Fernet (URL-safe base64)
- File Extension: .enc

### Privacy
- No telemetry or tracking
- Local-only option available
- Encrypted API key storage
- No cloud sync required
- Open source (auditable)

## Extensibility

### Adding AI Modules
- Base class: `BaseAiCore`
- Implement: `request()`, `get_prompt_manager()`
- Register in module loader
- Settings dialog integration

### Custom Themes
- JSON-based theme definitions
- Color scheme customization
- Light and dark variants

### Translations
- Lexeme-based system
- JSON translation files
- Currently: 19 languages
- Easy to add new languages

## Troubleshooting

### Common Issues
1. **Model Loading Fails**: Check ONNX Runtime version, model format
2. **Slow Inference**: Use GPU acceleration, smaller quantized models
3. **API Errors**: Verify API key, check rate limits, network connectivity
4. **Encryption Issues**: Password is case-sensitive, cannot recover lost passwords

### System Requirements
- Python 3.10 or higher
- 4 GB RAM minimum (8 GB recommended)
- 500 MB disk space (plus models)
- GPU optional but recommended for local AI

## Contributing Guidelines

### Welcome Contributions
- Bug fixes
- Feature implementations
- Documentation improvements
- Translation additions
- New AI module integrations

### Development Setup
```bash
git clone https://github.com/notolog/notolog-editor.git
cd notolog-editor
python3 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -e .[dev]
python -m pytest  # Run tests
```

### Code Style
- PEP 8 compliance
- Type hints encouraged
- Docstrings required
- Unit tests for new features

## Roadmap

### Planned Features
- Collaborative editing
- More AI model integrations
- Enhanced encryption options
- Mobile companion apps
- Cloud sync (optional)
- Version control integration

## License & Legal

- License: MIT License
- Copyright: 2024-2026 Vadim Bakhrenkov
- Open source, free to use
- Commercial use allowed
- Attribution required (MIT license terms)

## Resources

- Text-to-Speech setup, models, languages, and troubleshooting: https://notolog.app/text-to-speech/
- Documentation: https://notolog.app
- GitHub: https://github.com/notolog/notolog-editor
- PyPI: https://pypi.org/project/notolog/
- Website: https://notolog.app
- Issues: https://github.com/notolog/notolog-editor/issues
- Discussions: https://github.com/notolog/notolog-editor/discussions

## Keywords for Search

markdown, editor, python, qt, pyside6, ai, assistant, openai, onnx, llama,
llm, local, on-device, inference, encryption, secure, notes, cross-platform,
open-source, text-editor, writing, documentation, developer-tools, notepad,
privacy, markdown-editor, wysiwyg, syntax-highlighting, gpt, chatgpt,
ai-powered, machine-learning, natural-language-processing

---

*Document version: 1.2.2*
*Last updated: August 2026*
*Optimized for: AI agents, LLMs, search engines, documentation crawlers*